Skip to main content
Glama

Synapse Cortex (synapse-cortex)

Biomimetic Cognitive Graph Memory, Spreading Activation, and Progressive Context Packing for Autonomous AI Agents.

PyPI: synapse-cortex License: MIT Python: 3.9+ Tests: 406 Passed Architecture: Local--First


Why Synapse?

AI agents without memory forget everything between sessions. However, naive vector databases (flat RAG) introduce critical cognitive flaws:

  1. Belief Drift & Hallucination: Flat vector search blindly retrieves outdated memories alongside new ones. If a task status changes from In Progress to Completed, traditional RAG frequently returns both, causing the model to hallucinate progress.

  2. Disconnected Knowledge: Real-world knowledge forms an associative graph. If an agent knows "Module X manages authentication" and "Module X experienced an outage under load Y", it must associate these facts when debugging auth bottlenecks without explicit keywords.

  3. Context Window Bleed: Dumping raw conversation transcripts into system prompts consumes thousands of tokens and triggers attention dilution.

  4. Episodic Amnesia: Agents repeatedly attempt failed operations because they lack structured counterfactual guardrails (Situation → Action → Outcome → Lesson).

Synapse solves this with a biomimetic cognitive memory architecture designed specifically for long-running autonomous agents.


Related MCP server: agent-logbook

Core Tripartite Architecture

                  ┌────────────────────────────────────────┐
                  │       Autonomous Agent Runtime         │
                  └───────┬────────────────────────▲───────┘
                          │ retain()               │ recall()
                          ▼                        │
       ┌───────────────────────────────────────────────────────────┐
       │                 SYNAPSE COGNITIVE CORTEX                  │
       │                                                           │
       │  [Tier 1: Mental Models]     [Tier 2: Observations]       │
       │  Dynamic AST Markdown        Deduplicated Pattern Clusters│
       │                                                           │
       │  [Tier 3: Graph Storage]     [Tier 4: Research Vault]     │
       │  FTS5 (BM25) + Dense Vector  Quarantined Harvested Docs   │
       └───────────────────────────▲───────────────────────────────┘
                                   │ reflect()
                          ┌────────┴────────┐
                          │ Background Loop │
                          │ Belief Revision │
                          │ Hebbian Decay   │
                          └─────────────────┘
  1. retain() - Micro-Episodic Storage: Extracts atomic facts, categorizes knowledge (architecture, sop, decision, preference, incident), generates dense vectors (384-dimensional by default), and establishes synaptic associative graph edges.

  2. recall() — Hybrid Spreading Activation: Combines SQLite FTS5 (BM25 lexical search), dense vector cosine similarity, and multi-hop graph spreading activation. Context is packed progressively using multi-tiered token budgeting (L0 Abstract < 40 tokens, L1 Overview < 300 tokens).

  3. reflect() — Cascading Belief Revision: Resolves factual contradictions, supersedes stale beliefs, applies Hebbian reinforcement based on retrieval co-activation, and rolls up obsolete nodes into compact abstract summaries.


Quickstart

Installation

The quickest way to install Synapse Cortex and the synapse-mcp server binary:

pip install synapse-cortex

PyPI may lag the repository. The latest published release can be older than the source version in pyproject.toml. For the current source features, use the source install below.

(Or for optional development and testing tools: pip install "synapse-cortex[dev]").


Installing from Source (Developers)

Linux & macOS

git clone https://github.com/nafispradipta/synapse-agent.git
cd synapse-agent

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install package in editable mode
pip install -e ".[dev]"

Windows (PowerShell)

git clone https://github.com/nafispradipta/synapse-agent.git
cd synapse-agent

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1

# Install package in editable mode
pip install -e .

# (Optional) Install development and testing dependencies
pip install -e ".[dev]"

Windows (Command Prompt - cmd.exe)

git clone https://github.com/nafispradipta/synapse-agent.git
cd synapse-agent

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate.bat

# Install package in editable mode
pip install -e .

Basic Usage

from synapse.adapter import SynapseAdapter

# Initialize in-memory or persistent SQLite storage
adapter = SynapseAdapter({"db_path": "./data/synapse.db", "token_budget": 250})

# 1. Retain an architectural rule or invariant
adapter.retain(
    content="Always enable WAL mode and set busy_timeout >= 5000ms for concurrent SQLite operations.",
    category="architecture",
    salience=0.95,
    title="SQLite Concurrency Rule"
)

# 2. Record an episodic learning experience
adapter.record_episode(
    title="Database Lock Incident Under High Load",
    situation="Agent workers experienced database lock contention during concurrent batch writes.",
    action_taken="Switched journal mode to WAL and increased busy timeout to 5000ms.",
    outcome="Lock contention eliminated completely across all concurrent workers.",
    lessons_learned="Always enable WAL mode and configure busy_timeout >= 5000ms.",
    salience=0.95
)

# 3. Recall packed context for your agent prompt
recalled_context = adapter.recall("How to handle SQLite database locks under high load?")

for block in recalled_context:
    print(block)

Model Context Protocol (MCP) Server

Synapse includes a built-in JSON-RPC 2.0 MCP server, enabling AI coding assistants (Claude Desktop, Cursor, Windsurf, OpenCode, Codex, Pi CLI, Hermes, Zed, etc.) to tap directly into the shared cognitive memory cortex.

MCP Configuration

Add the synapse entry to your assistant's MCP configuration (mcpServers block):

{
  "mcpServers": {
    "synapse": {
      "command": "synapse-mcp"
    }
  }
}

Shared Memory Pool: synapse-mcp resolves its database in this order: SYNAPSE_DB_PATH when set; otherwise an existing ./data/synapse.db in the server's working directory; otherwise ~/.synapse/synapse.db. In the common case all your AI assistants (Claude, Cursor, terminal agents) share one persistent brain on the machine.

If you prefer an isolated database for a specific project, always set SYNAPSE_DB_PATH explicitly:

{
  "mcpServers": {
    "synapse": {
      "command": "synapse-mcp",
      "env": {
        "SYNAPSE_DB_PATH": "/path/to/project/data/synapse.db"
      }
    }
  }
}

Direct CLI Execution

For terminal-based coding agents or stdio inspection:

synapse-mcp

Available MCP Tools

Tool

Description

synapse_recall

Hybrid semantic vector + BM25 search across all past memories, SOPs, and architectural decisions.

synapse_retain

Store an atomic rule, decision, or SOP with salience weighting.

synapse_record_episode

Record a structured episodic experience (Situation → Action → Outcome → Lesson).

synapse_get_stats

Retrieve real-time cortex statistics (active nodes, edges, vectors, superseded counts).


Configuration & Dual-Engine Architecture

Synapse operates using two complementary cognitive engines: The Embedding Engine (for dense associative vector search) and The LLM Engine (for subconscious reflection and mental model synthesis).

┌────────────────────────────────────────────────────────────────────────┐
│                        SYNAPSE COGNITIVE ENGINES                       │
├──────────────────────────────────┬─────────────────────────────────────┤
│      1. Dense Embedding Engine   │          2. LLM Engine              │
│  (Vector Search & Association)   │ (Belief Revision & Reflection)      │
├──────────────────────────────────┼─────────────────────────────────────┤
│ Primary: sentence-transformers   │ Any OpenAI-Compatible Provider:     │
│ (all-MiniLM-L6-v2, 384-dim)      │ OpenAI, Ollama, vLLM, Groq, etc.    │
│                                  │                                     │
│ Fallback: Built-in pure-Python   │ Fallback: Built-in rule-based       │
│ CRC32 n-gram vectorizer          │ deterministic heuristics            │
│ (Zero dependencies, 0 token cost)│ (Operates offline without API keys) │
└──────────────────────────────────┴─────────────────────────────────────┘

Synapse generates dense vectors (384-dimensional by default) to power hybrid retrieval (BM25 lexical + vector cosine similarity):

  • Zero-Dependency Built-In Fallback: If no external libraries are installed, Synapse automatically uses a built-in deterministic subword n-gram vectorizer. It requires zero external packages, zero model downloads, and zero API costs.

  • Neural Embeddings (Optional): If you install sentence-transformers, Synapse seamlessly upgrades to neural embeddings using all-MiniLM-L6-v2 (or your configured SYNAPSE_EMBEDDING_MODEL):

    pip install sentence-transformers

2. The LLM Engine (Cognitive Synthesis)

The LLM is invoked during background consolidation to synthesize high-level Mental Models, extract abstract takeaways from episodic experiences, and resolve complex factual contradictions:

  • Provider-Agnostic: Any standard OpenAI-compatible API is supported (local runners like Ollama, vLLM, LM Studio, or hosted endpoints like OpenAI, Groq, DeepSeek).

  • Graceful Fallback: If no LLM endpoint or API key is provided, Synapse automatically uses deterministic rule-based heuristics. Core memory operations (retain(), recall(), record_episode()) never crash or block.

Environment Configuration

Copy the environment template:

cp .env.example .env

The library reads process environment variables directly and does not load .env by itself. Export the file in your shell before running a command, or set the variables in your MCP client's env block.

# POSIX
set -a; source .env; set +a
# PowerShell: set individual variables
$env:SYNAPSE_DB_PATH = "./data/synapse.db"

Edit .env according to your requirements:

# SQLite Database location (default: ~/.synapse/synapse.db)
SYNAPSE_DB_PATH=./data/synapse.db

# Standard OpenAI-Compatible LLM Settings
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4o-mini

# (Optional) Dedicated Synapse Endpoint Override
# SYNAPSE_BASE_URL=http://localhost:11434/v1
# SYNAPSE_API_KEY=
# SYNAPSE_MODEL=

# (Optional) Embedding Model Override (defaults to all-MiniLM-L6-v2)
# SYNAPSE_EMBEDDING_MODEL=all-MiniLM-L6-v2

# (Optional) Markdown Knowledge Base / Vault Path
# SYNAPSE_VAULT_PATH=./vault

Note for Local Runners (Ollama, vLLM): If you are running locally with Ollama or vLLM, set OPENAI_BASE_URL=http://localhost:11434/v1 and leave OPENAI_API_KEY and OPENAI_MODEL blank to use your active model.


Testing

Synapse comes with an exhaustive test suite covering all cognitive subsystems:

python -m pytest
================================ 399 passed in 31.38s =============================
  • Belief Revision & Contradiction Resolution: test_contradiction_resolver.py

  • Counterfactual Guardrails: test_counterfactual_guardrail.py

  • Spreading Activation & Retainment: test_synapse_retriever.py, test_synapse_storage.py

  • Hebbian Reinforcement & Abstract Rollups: test_hebbian_and_rollup.py, test_hebbian_outcome_feedback.py

  • Metacognitive Calibration: test_metacognitive_scorer.py


Technical Design & Honest Trade-Offs

To maintain transparency and help developers choose the right tool for their architecture:

  1. Semantic Search vs. Subword Fallback:

    • The default zero-dependency vectorizer uses subword CRC32 n-gram hashing. It excels at fast keyword matching, spelling variations, and offline local operations without downloading heavy packages.

    • For true conceptual paraphrasing and cross-lingual understanding (e.g. "How is login token handled?" matching "Autentikasi API memakai JWT"), configure an OpenAI-compatible embedding endpoint (OPENAI_EMBEDDING_MODEL via Ollama or OpenAI) or install sentence-transformers.

  2. Automated Belief Revision Scope:

    • Real-time arbitration resolves numeric attributes (ports, memory, limits), technology version updates (e.g. PostgreSQL 14 → 16), and task lifecycle states (In Progress → Completed).

    • Broad semantic belief revisions that require reasoning over prose are synthesized during background consolidation cycles with LLM assistance.

  3. Performance & Target Scale:

    • Vector cosine similarity is computed in-memory across candidate graph nodes in Python.

    • This design is lightweight and optimal for personal and team agent memory graphs (<10,000 active nodes). It is not designed to replace high-scale multi-million vector databases (Milvus, Pinecone).

  4. Multi-Project Isolation:

    • synapse-mcp uses SYNAPSE_DB_PATH when set, then an existing ./data/synapse.db, then ~/.synapse/synapse.db. Without an explicit variable, assistants can share context across repositories.

    • For strictly isolated project environments, always set SYNAPSE_DB_PATH=./data/synapse.db.


License

MIT License. See LICENSE for details.

Available Tools

4 tools
synapse_get_statsA

Get real-time statistics and node counts of the Synapse memory cortex.

Inputs: no named parameters.

synapse_recallA

Recall memories, SOPs, and past architectural decisions from Synapse Memory Engine using hybrid semantic vector and BM25 search.

Inputs: query (required), budget.

synapse_record_episodeC

Record an episodic learning memory (Situation -> Action -> Outcome -> Lesson) so agents never repeat past mistakes.

Inputs: title (required), outcome (required), situation (required), action_taken (required), +2 more.

synapse_retainB

Save an atomic fact, architectural decision, permanent directive, or SOP into Synapse Memory.

Inputs: content (required), category, salience.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    The read/write split is clear: synapse_recall and synapse_get_stats are retrieval, while synapse_retain and synapse_record_episode are storage. synapse_retain and synapse_record_episode both write memories, which could be confused, but the descriptions distinguish atomic facts/SOPs from structured Situation-Action-Outcome-Lesson episodes.

    Naming Consistency4/5

    All tools share the synapse_ namespace prefix and use verb-based names, giving a predictable pattern. Minor deviation: recall and retain are bare verbs while record_episode and get_stats use verb_noun form, but the set still reads consistently.

    Tool Count4/5

    Four tools is a tight, focused surface for a memory engine, and each one has a distinct role (store fact, store episode, recall, stats). It sits at the low end of the comfortable range, with room for lifecycle operations without feeling padded.

    Completeness3/5

    Core workflows (store and retrieve memories, check stats) are covered, but the lifecycle is incomplete: there is no update/edit, delete/forget, or list/enumerate operation. For a persistent memory system, the inability to correct or remove outdated facts or SOPs is a notable gap.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables persistent, graph-based memory for AI agents, allowing them to store, traverse, and recall relationships between facts, decisions, and context across sessions for efficient reasoning and reduced token usage.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to maintain long-term memory by logging and retrieving facts and decisions in a SQLite database, with relevance ranking and full history tracking.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI assistants with persistent long-term memory by organizing experiences into documents, memory atoms, and a knowledge graph, and enabling hybrid BM25/vector/graph retrieval with decay, reinforcement, and automatic recall.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to persist facts with tags, sources, and importance in a local SQLite database, retrieve them through hybrid BM25 plus embedding search weighted by retention decay, link or supersede related entries, and review everything in a read-only visual dashboard showing the memory graph and timeline.
      6
      MIT