sophiagraph 0.0.1

Standalone wisdom graph substrate for durable agent memory

sophiagraph

Status: publish-ready alpha Shape: standalone Python package License: Apache-2.0

sophiagraph is a standalone wisdom graph substrate for durable agent memory. The name comes from Greek Sophia (Σοφία), meaning wisdom; in this package it frames durable knowledge as a graph of records, relations, provenance, trust, and portable snapshots.

What the package provides

sophiagraph currently provides:

• canonical durable-memory models
• contract and provenance helpers
• query DTOs
• portability bundle models and codec helpers
• audit-event schemas
• trust and temporal primitives
• typed namespace DTOs for explicit tenant/user/agent/session isolation
• directed relation APIs with explicit incoming/outgoing/bidirectional lookup
• Obsidian-style structural document/link DTOs, Markdown/frontmatter adapter, backlinks, outgoing links, local graph traversal, graph snapshots, structural search DTOs, saved view DTOs, JSON Canvas DTOs, and extension hooks
• a package-local SQLite durable engine
• a package-local in-memory backend for tests and ephemeral consumers
• a standalone smoke entrypoint for publish/install validation

What the package does not provide

This package does not provide:

• application orchestration or gateway policy
• a full Obsidian clone, editor, sync service, or visual renderer
• provider/model routing
• session orchestration
• automatic link, tag, relation, entity, or summary inference from prose
• implicit imports back into any host framework

Host frameworks remain the orchestrators. sophiagraph owns reusable durable wisdom graph primitives and the standalone durable engine.

Install

Editable install during local development:

python3.11 -m pip install -e .

Wheel build:

python3.11 -m build

Fresh-wheel smoke:

TMP_VENV="$(mktemp -d)/sophiagraph-venv"
python3.11 -m venv "$TMP_VENV"
"$TMP_VENV/bin/pip" install dist/sophiagraph-*.whl
"$TMP_VENV/bin/sophiagraph-smoke" --root /tmp/sophiagraph-release-smoke --seed --json

Standalone Smoke

Source-root smoke:

PYTHONPATH=src python3.11 -m sophiagraph --root /tmp/sophiagraph-smoke --seed --json

Installed-console-script smoke:

sophiagraph-smoke --root /tmp/sophiagraph-smoke --seed --json

External Consumer Quickstart

Minimal standalone flow for another framework or service:

from sophiagraph.models import MemoryNamespace, MemoryRecord
from sophiagraph.portability.models import MemoryBundleExportOptions, MemoryBundleImportOptions
from sophiagraph.query import ListQueryOptions, SearchQueryOptions
from sophiagraph.storage import create_memory_store, create_sqlite_store

store = create_sqlite_store("/tmp/sophiagraph-demo")
namespace = MemoryNamespace(
    tenant_id="tenant-demo",
    user_id="user-demo",
    agent_id="demo",
    graph_id="main",
)
store.put_record(
    MemoryRecord(
        id="rec-1",
        scope="agent:demo",
        type="fact",
        key="project:apollo",
        title="Apollo launch date",
        content={"text": "Apollo launched in Q2"},
        created_at="2026-05-22T00:00:00+00:00",
        updated_at="2026-05-22T00:00:00+00:00",
        source="validated",
        confidence=0.95,
        event_time="2026-05-22T00:00:00+00:00",
        namespace=namespace,
    )
)

namespace_filter = MemoryNamespace(agent_id="demo")
records = store.list_records(
    ListQueryOptions(scopes=["agent:demo"], namespaces=[namespace_filter])
)
search_hits = store.search_records(
    SearchQueryOptions(query="Apollo", scopes=["agent:demo"], namespaces=[namespace_filter])
)
snapshot = store.export_snapshot(
    MemoryBundleExportOptions(scopes=["agent:demo"], namespaces=[namespace_filter])
)
import_store = create_memory_store()
import_store.import_snapshot(snapshot, MemoryBundleImportOptions())

Runnable example:

PYTHONPATH=src python3.11 examples/basic_usage.py
PYTHONPATH=src python3.11 examples/obsidian_substrate.py

Typed Namespaces

Records still accept the legacy scope string for compatibility. New integrations can also attach typed namespace DTOs to records and use the same typed dimensions for query/export/import boundaries:

from sophiagraph.models import MemoryNamespace

namespace = MemoryNamespace(
    tenant_id="tenant-acme",
    user_id="user-j",
    agent_id="agent-codex",
    session_id="session-123",
    graph_id="main",
)

legacy_scope = namespace.to_scope("agent")

record = MemoryRecord(
    id="rec-namespace",
    scope=legacy_scope,
    type="fact",
    content={"text": "Namespace-safe records keep tenant and agent separate."},
    created_at="2026-05-23T00:00:00+00:00",
    updated_at="2026-05-23T00:00:00+00:00",
    namespace=namespace,
)

records = store.list_records(
    ListQueryOptions(scopes=[legacy_scope], namespaces=[MemoryNamespace(agent_id="agent-codex")])
)

Namespace values must be explicit caller-provided identifiers. sophiagraph does not infer tenant, user, project, or agent identity from prose. Existing SQLite rows without namespace columns are migrated from their explicit legacy scope value only; no content or title text is inspected.

Graph Relations

Relations are explicit, typed, directed edges between records. Consumers can list outgoing, incoming, or bidirectional edges through the direction option:

outgoing = store.list_relations("rec-1")
incoming = store.list_relations("rec-1", direction="in")
neighborhood = store.get_related_records(
    "rec-1",
    ["agent:demo"],
    direction="both",
)

The package does not infer relation types from prose. Callers must submit relation records directly.

Obsidian-Style Knowledge Graph Substrate

sophiagraph now has package-core surfaces for Obsidian-comparable structural workflows:

• KnowledgeDocument wraps document-profile MemoryRecord nodes with path, title, aliases, content hash, namespace, timestamps, and provenance.
• StructuralLink represents explicit wikilinks, Markdown links, embeds, property links, external URLs, unresolved targets, headings, and block refs.
• extract_markdown(...) parses frontmatter, aliases, tags, and explicit link syntax without modifying note prose.
• Store backends expose put_link(...), list_links(...), get_backlinks(...), get_outgoing_links(...), get_local_graph(...), and get_graph_snapshot(...).
• Structural search, saved views, JSON Canvas, and extension hooks are durable DTO/helper surfaces. They do not require a UI renderer or OpenMinion import.

Example:

from sophiagraph.adapters.markdown import extract_markdown
from sophiagraph.models import LinkResolutionCandidate, MemoryNamespace
from sophiagraph.query import LinkQueryOptions, LocalGraphOptions

namespace = MemoryNamespace(agent_id="demo", graph_id="main")
imported = extract_markdown(
    "See [[Roadmap]].",
    path="Index.md",
    record_id="rec-index",
    namespace=namespace,
    resolver_candidates=[
        LinkResolutionCandidate(
            record_id="rec-roadmap",
            path="Roadmap.md",
            title="Roadmap",
            namespace=namespace,
        )
    ],
)
for link in imported.links:
    store.put_link(link)

backlinks = store.list_links(LinkQueryOptions(record_id="rec-roadmap", direction="in"))
local_graph = store.get_local_graph(LocalGraphOptions(record_id="rec-index", depth=1))

The resolver contract is deliberately structural: explicit path first, then case-insensitive title/alias matching inside the namespace. Unresolved and ambiguous targets are preserved as first-class outcomes. Unlinked mentions are not persisted as graph edges.

Alpha-Scale Search and SQLite Connections

Current search is deterministic substring search over hydrated record payloads. It is suitable for alpha-scale package use and tests, but it is not yet an FTS5-backed or vector-backed retrieval engine. The hybrid retrieval roadmap owns the future FTS/vector/rerank design.

SophiaGraphSqliteStore opens a short-lived SQLite connection per method call. That keeps alpha behavior simple and avoids hidden shared connection state. A pooled or long-lived connection strategy should be introduced only with a separate lifecycle/concurrency contract.

Cross-Package Compatibility DTOs

Some contract DTOs, including runtime snapshot/capsule/query shapes and MemoryPatchResult, are retained for host-runtime adapters such as OpenMinion and future service surfaces. They are compatibility contracts; package-local stores are not required to instantiate every DTO.

Import Boundary Rule

sophiagraph must never import from host frameworks such as OpenMinion.

Dependency direction is one-way:

• allowed: host framework -> sophiagraph
• forbidden: sophiagraph -> host framework

Public API

Stable top-level exports for external consumers:

• sophiagraph.SophiaGraphSqliteStore
• sophiagraph.SophiaGraphMemoryStore
• sophiagraph.create_sqlite_store(...)
• sophiagraph.create_memory_store()
• sophiagraph.default_db_path(...)
• sophiagraph.audit
• sophiagraph.contracts
• sophiagraph.portability
• sophiagraph.trust
• sophiagraph.coerce_temporal_dt

Supported import roots:

• sophiagraph
• sophiagraph.models
• sophiagraph.query
• sophiagraph.storage
• sophiagraph.portability
• sophiagraph.adapters
• sophiagraph.canvas
• sophiagraph.extensions
• sophiagraph.views
• sophiagraph.audit
• sophiagraph.trust
• sophiagraph.temporal
• sophiagraph.contracts

API Compatibility

Compatibility and deprecation policy:

• API_COMPATIBILITY.md

Release Docs

Package-local release runbook:

• RELEASING.md
• scripts/release_check.py