SophiaGraph

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

GitHub · PyPI · Website · Docs · X

The current SophiaGraph source is the v0.0.10 alpha release line 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 Kuzu and Neo4j graph adapters support the same typed structural pattern payloads as the in-memory conformance backend; they never accept natural-language or generated query text.

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.

Delegated Agent Access

Remote agents and untrusted adapters should use AuthorizedSophiaGraphGateway, not a raw store. The gateway intersects a trusted principal context with a host-resolved DelegationMemoryGrant on every operation, bounds results and context, and returns the same absent envelope for missing and unauthorized direct IDs.

Sophiagraph does not persist grants. OpenMinion or another host remains the grant issuer and revocation authority through the package-neutral DelegationMemoryGrantResolver protocol. Child-authored durable knowledge is submitted by the parent as a candidate and follows the existing review and promotion flow.

See docs/delegated-memory-access.md for the trust boundary, migration steps, and rollback posture.

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.