Synaptic Memory

Brain-inspired knowledge graph for LLM agents and multi-agent systems.

Agents automatically structure their operational data — tool calls, decisions, outcomes, lessons — into an auto-constructed ontology, enabling self-retrieval and reasoning over past experiences. Library + MCP server.

Why

LLM agents don't remember. They repeat the same mistakes, fail to leverage past successes, and can't access accumulated team knowledge.

Traditional RAG stops at "chunk documents and search by vector." But agents need more than document retrieval — they need structured experience:

• "What decision did I make last time in this situation, and what was the outcome?"
• "Has this pattern failed before? Why?"
• "What rules should I follow when using this tool?"

Synaptic Memory borrows the answer from how the brain works.

Differentiators

Benchmarks (FTS only, no embedding)

Design Philosophy — Four Principles from the Brain

1. Spreading Activation — Associative Search

When the brain hears "deploy," it co-activates CI/CD, rollback, incidents, and monitoring.

Search: "deployment"
  → FTS match: [CI/CD pipeline, deployment automation]
  → Neighbor activation: [rollback strategy, canary deployment, incident response rules]
  → Resonance ranking: relevance × importance × recency × vitality × context

2. Hebbian Learning — "What fires together, wires together"

Agent uses [PostgreSQL selection] + [vector search implementation] together → success
  → edge weight += 0.1 → co-activated in future searches

Agent uses [skip tests] + [production deploy] together → failure
  → edge weight -= 0.15 → failure experience surfaces first

3. Memory Consolidation — Keep only what matters

L0 (Raw, 72h)      ← All records. Deleted after 72h if not accessed.
L1 (Sprint, 90d)   ← 3+ accesses. Retained for 90 days.
L2 (Monthly, 365d) ← 10+ accesses. Retained for 1 year.
L3 (Permanent)     ← 80%+ success rate. Permanently preserved. (Demoted below 60%)

4. Auto-Ontology — Structure knowledge for future retrieval

"When will an agent search for this knowledge?" — metadata is auto-generated based on predicted future queries:

await graph.add("Payment Outage Postmortem", "PG API timeout caused...")

# LLM auto-generates:
# kind: LESSON
# tags: ["payment", "PG", "timeout", "circuit-breaker"]
# search_keywords: ["payment failure cause", "PG outage response", "API timeout fix"]
# search_scenarios: ["searching past cases when payment system fails"]
# relations to existing nodes: --[LEARNED_FROM]--> "deployment decision"

Three-tier auto-construction:

Install

pip install synaptic-memory                      # Core (zero deps)
pip install synaptic-memory[embedding]           # + auto-embedding (Ollama/vLLM)
pip install synaptic-memory[sqlite]              # + SQLite FTS5
pip install synaptic-memory[scale]               # Neo4j + Qdrant + MinIO + embedding
pip install synaptic-memory[mcp]                 # + MCP server
pip install synaptic-memory[all]                 # Everything

Quick Start

1. In-memory — zero-dep, instant start

from synaptic import SynapticGraph, ActivityTracker

async def main():
    graph = SynapticGraph.memory()
    tracker = ActivityTracker(graph)

    # Search past experiences (intent auto-inferred)
    result = await graph.agent_search("DB migration failure")

    # Record a decision
    session = await tracker.start_session(agent_id="my-agent")
    decision = await tracker.record_decision(
        session.id,
        title="Choose PostgreSQL",
        rationale="Need vector search + ACID",
        alternatives=["MongoDB", "SQLite"],
    )

    # Record outcome → auto Hebbian learning
    await tracker.record_outcome(
        decision.id,
        title="Migration succeeded",
        content="Achieved zero downtime",
        success=True,
    )

2. SQLite — lightweight production

from synaptic import SynapticGraph

graph = SynapticGraph.sqlite("knowledge.db")
await graph.backend.connect()

# RuleBasedClassifier + RelationDetector + Ontology included automatically.
# Just add content — kind and relations are auto-classified.
await graph.add("Refund Policy", "Refunds available within 7 days...")  # → kind=RULE (auto)

3. Full — LLM classification + embedding + relation detection

from synaptic import SynapticGraph
from synaptic.backends.sqlite import SQLiteBackend
from synaptic.extensions.llm_provider import OllamaLLMProvider

graph = SynapticGraph.full(
    SQLiteBackend("knowledge.db"),
    llm=OllamaLLMProvider(model="qwen3:0.6b"),
    embed_api_base="http://localhost:8080/v1",
    embed_model="BAAI/bge-m3",
)
await graph.backend.connect()

# LLM auto-generates: kind classification + tags + search keywords + search scenarios
# Embeddings include search_keywords → improved vector search accuracy
# Semantic relations auto-detected against existing nodes (DEPENDS_ON, LEARNED_FROM, etc.)
node = await graph.add("Payment Outage Postmortem", "PG API timeout caused...")

4. Custom — manual composition

Instead of factory methods, compose each component directly:

from synaptic import SynapticGraph, OpenAIEmbeddingProvider
from synaptic.backends.sqlite import SQLiteBackend

graph = SynapticGraph(
    SQLiteBackend("knowledge.db"),
    embedder=OpenAIEmbeddingProvider("http://gpu-server:8080/v1", model="BAAI/bge-m3"),
)
await graph.backend.connect()

# Auto: title + content → vector generation → stored
await graph.add("Deployment Strategy", "Blue-green deployment for zero downtime")
# Auto: query → vector generation → FTS + vector hybrid search
result = await graph.search("deployment approach")

5. Scale — CompositeBackend

from synaptic import SynapticGraph
from synaptic.backends.composite import CompositeBackend
from synaptic.backends.neo4j import Neo4jBackend
from synaptic.backends.qdrant import QdrantBackend
from synaptic.backends.minio_store import MinIOBackend

composite = CompositeBackend(
    graph=Neo4jBackend("bolt://localhost:7687"),
    vector=QdrantBackend("http://localhost:6333"),
    blob=MinIOBackend("localhost:9000", access_key="minio", secret_key="secret"),
)
await composite.connect()

graph = SynapticGraph.full(composite, embed_api_base="http://gpu-server:8080/v1")

# Internal routing:
# - embedding → Qdrant, content > 100KB → MinIO, everything else → Neo4j

Architecture

SynapticGraph (Facade)
  │
  ├── Auto-Ontology ───── RuleBasedClassifier / LLMClassifier
  │                       RuleBasedRelationDetector / LLMRelationDetector
  ├── OntologyRegistry ── Type hierarchy + property inheritance + constraint validation
  ├── ActivityTracker ─── Session / tool call / decision / outcome capture
  ├── AgentSearch ──────── 6 intent-based search strategies
  ├── HybridSearch ─────── FTS + vector → synonym → LLM rewrite
  ├── ResonanceScorer ──── 5-axis resonance (relevance × importance × recency × vitality × context)
  ├── HebbianEngine ────── Co-activation reinforcement / weakening
  ├── ConsolidationCascade  L0→L3 lifecycle
  ├── EmbeddingProvider ── Auto vector generation (Ollama/vLLM/OpenAI)
  ├── LLMProvider ──────── LLM for ontology construction (Ollama/OpenAI)
  └── Exporters ─────────── Markdown, JSON
       │
  StorageBackend (Protocol)
       │
  ┌────┼──────────┬───────────────┬──────────────┐
  │    │          │               │              │
Memory SQLite  PostgreSQL     Neo4j       CompositeBackend
(dev)  (FTS5)  (pgvector)   (Cypher)    (Neo4j+Qdrant+MinIO)

5-axis Resonance Scoring

Score = 0.55 × relevance     Search match score [0,1]
      + 0.15 × importance    (success - failure) / access_count [0,1]
      + 0.20 × recency       exp(-0.05 × days_since_update) [0,1]
      + 0.10 × vitality      Periodic decay ×0.95 [0,1]
      + (context weight) × context  Session tag Jaccard similarity [0,1]

Weights vary by intent. past_failures emphasizes importance; context_explore emphasizes context. Same query, different intent, different results.

Ontology

from synaptic import OntologyRegistry, TypeDef, PropertyDef, build_agent_ontology

ontology = build_agent_ontology()

# Add custom type
ontology.register_type(TypeDef(
    name="incident",
    parent="agent_activity",
    description="Production incident",
    properties=[
        PropertyDef(name="severity", value_type="str", required=True),
    ],
))

graph = SynapticGraph(backend, ontology=ontology)
# → Auto-validated on graph.add() and graph.link()

Default Ontology

knowledge                          agent_activity
  ├── concept                        ├── session
  ├── entity                         ├── tool_call
  ├── lesson                         ├── observation
  ├── decision                       ├── reasoning
  ├── rule                           └── outcome
  └── artifact

Backends

MCP Server — 16 Tools

synaptic-mcp                                              # stdio (Claude Code)
synaptic-mcp --db ./knowledge.db                         # SQLite
synaptic-mcp --embed-url http://localhost:8080/v1        # + auto-embedding

Knowledge (7) — knowledge_search, knowledge_add, knowledge_link, knowledge_reinforce, knowledge_stats, knowledge_export, knowledge_consolidate

Agent Workflow (4) — agent_start_session, agent_log_action, agent_record_decision, agent_record_outcome

Semantic Search (3) — agent_find_similar, agent_get_reasoning_chain, agent_explore_context

Ontology (2) — ontology_define_type, ontology_query_schema

Dev

uv sync --extra dev --extra sqlite --extra neo4j --extra qdrant --extra minio
uv run pytest -v                              # 266+ tests
uv run pytest tests/benchmark/ -v -s          # Benchmarks (8 datasets + ablation)
uv run ruff check --fix && uv run ruff format

License

MIT