SophiaGraph

Durable memory, provenance, and knowledge-workspace primitives for local AI systems.

GitHub · PyPI · Website · Docs · X

SophiaGraph v0.0.5 is a standalone alpha package for durable, typed memory. It stores memory records, relations, provenance, lifecycle state, and portable workspace data without importing the OpenMinion runtime.

Read This First

1. Read At a Glance to confirm the package boundary.
2. Follow Install and Quick Start for a durable SQLite-backed memory round trip.
3. Read How It Fits before combining SophiaGraph with OpenMinion, PragmaGraph, or GraphFakos.
4. Use the package docs for workspace, storage, service, retrieval, and production-oriented guidance.
5. Read Development before changing the package.

Trust and Brand Safety

• Official GitHub: https://github.com/openminion/sophiagraph
• Official website: https://www.openminion.com
• Official X account: https://x.com/OpenMinion

SophiaGraph has no official token, coin, NFT, airdrop, staking program, treasury product, or investment offering. Any claim otherwise is unauthorized and should be treated as a scam.

At a Glance

Common Commands

python3.11 -m pip install sophiagraph
sophiagraph-smoke
sophiagraph-ui --screen explore --serve --open

Create and inspect a persistent workspace:

python3.11 -m sophiagraph workspace-init .sophia-workspace \
  --scope agent:local --agent-id local --graph-id main --json
python3.11 -m sophiagraph workspace-status .sophia-workspace --json

Install

Install the base package:

python3.11 -m pip install sophiagraph

Install an optional backend only when you need it:

python3.11 -m pip install "sophiagraph[kuzu]"
python3.11 -m pip install "sophiagraph[neo4j]"

For a source checkout:

python3.11 -m pip install -e ".[dev]"

Quick Start

External Consumer Quickstart

Store and retrieve one typed memory record:

from pathlib import Path
from uuid import uuid4

from sophiagraph.models import MemoryNamespace, MemoryRecord
from sophiagraph.query import SearchQueryOptions
from sophiagraph.storage import create_sqlite_store

store = create_sqlite_store(Path(".sophiagraph"))
namespace = MemoryNamespace(agent_id="demo", graph_id="main")
record = MemoryRecord(
    id=str(uuid4()),
    scope="agent:demo",
    type="fact",
    key="project:apollo",
    title="Apollo launch window",
    content={"text": "Apollo launches in Q2."},
    created_at="2026-01-01T00:00:00+00:00",
    updated_at="2026-01-01T00:00:00+00:00",
    source="validated",
    confidence=0.95,
    namespace=namespace,
)

store.put_record(record)
matches = store.search_records(
    SearchQueryOptions(
        query="Apollo",
        scopes=["agent:demo"],
        namespaces=[namespace],
    )
)
print(matches)

Run the complete example:

python3.11 examples/basic_usage.py

Use create_memory_store() instead when a test or short-lived consumer needs an ephemeral in-memory store rather than a durable SQLite path.

What SophiaGraph Provides

• typed memory records, namespaces, relations, provenance, and citations
• SQLite and in-memory stores with explicit capability reporting
• portable snapshots and import/export contracts
• lifecycle, trust, governance, deletion, audit, and freshness helpers
• structural queries, graph paths, connected components, and knowledge views
• workspace initialization, sync planning, history, templates, and publishing
• optional graph and vector backend adapters
• bounded local UI and server surfaces for package-owned workflows

What SophiaGraph Does Not Provide

• application or agent orchestration
• model-provider selection or routing
• session and turn execution
• automatic fact, relation, tag, or summary inference from prose
• automatic embedding-provider calls or model selection
• hosted collaboration, hosted administration, or managed sync
• ownership of a host application’s authorization or policy decisions

The core package operates on explicit typed inputs. Hosts remain responsible for LLM calls, semantic interpretation, scheduling, credentials, and user-facing policy.

How It Fits

SophiaGraph can run by itself. OpenMinion may use it as a memory backend, and GraphFakos may visualize a provider projection, but neither integration changes who owns memory truth.

Storage and Workspace Paths

Use the in-memory store for tests and ephemeral consumers. Use SQLite for the default durable local path. Optional Kuzu, Neo4j, and Qdrant adapters expose capability-specific behavior and should be selected explicitly.

The workspace surface adds persistent scope, namespace, import, sync, review, and publishing workflows on top of those package contracts:

python3.11 -m sophiagraph workspace-import-plan \
  .sophia-workspace ./notes --json
python3.11 -m sophiagraph workspace-sync-apply \
  .sophia-workspace ./notes --json

Read docs/workspace-mode.md, docs/storage-retrieval-backends.md, and docs/retrieval-boundary.md before building a larger integration.

Development

make dev-install
make hooks-install
make check

Use make release-check before publishing or changing the documented public surface.

Docs and Release

• docs/README.md: package documentation map
• docs/getting-started.md: contributor bootstrap
• docs/api-stability.md: public stability guidance
• docs/production-foundations.md: production-oriented package boundaries
• docs/backend-compatibility-matrix.md: backend support and proof
• docs/source-tree-owner-map.md: code owners and package layout
• docs/standalone-claim-alignment.md: public claims mapped to shipped package surfaces and proof
• API_COMPATIBILITY.md: supported import roots
• RELEASING.md: release and publish flow

License and Brand-use Boundary

• Source code license: Apache-2.0
• Brand/trademark grant: none

The license grants rights to use, modify, and redistribute the code. It does not grant rights to present a fork, clone, token, website, or social account as the official SophiaGraph or OpenMinion project or imply affiliation or endorsement.