synaptic-core 0.2.0

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

synaptic-core

Graph-backed memory runtime for production AI applications.

synaptic-core provides an async memory engine with hybrid retrieval, associative activation, feedback-driven learning, and durable observability.

Why synaptic-core

• Hybrid retrieval: combines keyword, semantic, and graph activation signals.
• Tiered memory: supports short-term and long-term memory with automatic graduation.
• Feedback learning: updates graph associations based on user/agent outcomes.
• Operational visibility: includes graph health, per-session summaries, and weekly digest reporting.
• Local-first default: ships with a SQLite backend and stable persistence semantics.

Installation

Requirements:

• Python 3.10+

Install from source:

python -m pip install .

Optional extras:

python -m pip install ".[real_embedding]"

Quick Start

import asyncio

from synaptic_core import SynapticMemory
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) % 97) / 100.0,
    ]


async def main() -> None:
    memory = SynapticMemory(
        db_path="synaptic.db",
        embedding_fn=embed,
        deployment_id="prod-us-east-1",
    )

    await memory.store(
        "Customer requested monthly usage report with CSV export.",
        metadata={"tenant": "acme", "channel": "support"},
    )

    retrieval = await memory.retrieve(
        "How does Acme get their monthly usage report?",
        session_id="chat-42",
        top_k=5,
    )

    outcome = await memory.feedback(
        retrieval.query_id,
        outcome=OutcomeSignalType.EXPLICIT_POSITIVE,
        active_nodes=[node.id for node in retrieval.nodes],
        provider="assistant-api",
    )

    status = await memory.graph_status()
    session = await memory.session_summary("chat-42")
    digest = await memory.weekly_digest()

    print(retrieval.nodes[0].content if retrieval.nodes else "no matches")
    print(outcome.composite_score, status["graph_confidence"], session["query_count"], digest["summary"])


asyncio.run(main())

Core API

• store(content, ...) -> Node
• retrieve(query, ...) -> RetrievalResult
• activate(node_ids, initial_energy=1.0, ...) -> RetrievalResult
• feedback(query_id, outcome, ...) -> CompositeOutcome
• graph_status() -> dict
• session_summary(session_id) -> dict
• weekly_digest(...) -> dict
• stats() -> dict
• delete(node_id) -> None
• link(node_a_id, node_b_id, ...) -> dict
• neighbors(node_id, limit=None) -> list[dict]
• recent_queries(session_id=None, limit=20) -> list[dict]
• recent_sessions(limit=20) -> list[dict]
• recent_outcomes(session_id=None, limit=20) -> list[dict]
• kv_set(key, value, metadata=None, ttl=None, namespace=None) -> None
• kv_get(key, namespace=None) -> Any | None
• kv_search(query, limit=10, namespace=None, filters=None) -> list[KeyValueItem]
• kv_delete(key, namespace=None) -> bool
• kv_clear(namespace=None) -> int (supports namespace "*" for global clear)
• store_session(session) -> session (optimistic version checks)
• retrieve_session(session_id) -> session | dict | None
• update_session(session) -> session

Production Notes

• embedding_fn is required for store and retrieve; it may be sync or async.
• Use stable session_id values to get accurate session analytics.
• Use stable deployment_id values to keep telemetry attribution consistent.
• Telemetry and background hardening paths are designed to be failure-isolated from hot request paths.
• The default SQLite backend is appropriate for single-node/local deployments.

Extensibility

• Backend abstraction is defined by MemoryBackend in src/synaptic_core/backends/base.py.
• You can supply a custom backend by passing backend=... to SynapticMemory.
• Framework adapters are intentionally external to this package.
• Axis interoperability is supported through the external AXIS-MEMORY-PROVIDER-V1 contract implemented by Axis-owned adapter code.