synaptic-core 0.1.1

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]"

Axis-core plugin usage:

python -m pip install synaptic-core

synaptic-core now publishes an axis.memory entry point named synaptic that resolves to synaptic_core.axis:SynapticAxisMemory.

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

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.
• Axis-compatible provider method shapes are covered by integration tests (store, retrieve, feedback).
• Axis-compatible key-value/session adapter is available as SynapticAxisMemory.