synaptic-core 0.3.0

Synaptic Core foundation and persistence layer for graph-backed memory.

synaptic-core

synaptic-core v0.3 ships a clean canonical API for graph memory:

• Clients: AsyncSynaptic and Synaptic
• Core methods: remember, recall, set, get, find, connect, related
• Session-first helpers: client.session("...")
• Structured errors: SynapticError { code, message, hint }

Install

pip install synaptic-core

Happy Path (Async, Session-First)

import asyncio

from synaptic_core import AsyncSynaptic, SynapticError
from synaptic_core.types import OutcomeSignalType


def embed(text: str) -> list[float]:
    normalized = text.lower().strip()
    return [
        float(len(normalized.split())),
        float(len(normalized)) / 100.0,
        float(sum(ord(ch) for ch in normalized) % 257) / 257.0,
    ]


async def main() -> None:
    client = AsyncSynaptic(db_path="synaptic.db", embedding_fn=embed)
    session = client.session("chat-42")

    await session.remember("Customer asked for monthly usage CSV export")
    recall = await session.recall("How do I export monthly usage as CSV?", top_k=5)

    if recall.nodes:
        await session.feedback(
            recall.query_id,
            outcome=OutcomeSignalType.EXPLICIT_POSITIVE,
            provider="app",
        )

    print("nodes", [str(node.id) for node in recall.nodes])
    print("stats", await client.stats())


try:
    asyncio.run(main())
except SynapticError as exc:
    print(exc.as_dict())

Canonical API

• remember(content, *, session_id="default", memory_type=None, external_id=None, source_type=None, metadata=None) -> Node
• recall(query, *, session_id="default", top_k=None) -> RetrievalResult
• feedback(query_id, outcome, *, session_id=None, agent_response=None, user_next_message=None, dwell_time_ms=None, active_nodes=None, corrected_nodes=None, provider="unknown") -> CompositeOutcome
• set(key, value, *, namespace=None, metadata=None, ttl=None) -> None
• get(key, *, namespace=None) -> Any | None
• find(query, *, namespace=None, limit=10, filters=None) -> list[dict]
• connect(node_a_id, node_b_id, *, weight=0.3, connection_type="excitatory", formation_trigger="explicit", is_cross_tier=None) -> dict
• related(node_id, *, limit=None) -> list[dict]
• stats() -> dict
• graph_status() -> dict
• sessions_recent(limit=20) -> list[dict]
• queries_recent(session_id=None, limit=20) -> list[dict]
• outcomes_recent(session_id=None, limit=20) -> list[dict]

Session-First Helpers

• client.session(session_id).remember(...)
• client.session(session_id).recall(...)
• client.session(session_id).feedback(...)
• client.session(session_id).summary()
• client.session(session_id).queries_recent(limit=20)
• client.session(session_id).outcomes_recent(limit=20)

CLI

synaptic doctor --db-path synaptic.db
synaptic stats --db-path synaptic.db --json
synaptic graph status --db-path synaptic.db --json
synaptic sessions recent --db-path synaptic.db --limit 20 --json
synaptic queries recent --db-path synaptic.db --session-id chat-42 --limit 20 --json
synaptic migrate-api /path/to/codebase --write

Migration

Strict migration steps and breaking changes are documented in:

• docs/migration-v0.2-to-v0.3.md