synapse-mcp
A local-first MCP memory server that gives AI assistants persistent, hybrid cognitive memory across sessions.
synapse_recall— Retrieve memories, SOPs, and architectural decisions via hybrid semantic vector + BM25 search, with a configurable token budget (default 300).synapse_retain— Store atomic facts, rules, decisions, or SOPs, tagged by category (preference,decision,architecture,incident,sop) and weighted by salience (0.0–1.0).synapse_record_episode— Capture structured episodic learnings (Situation → Action → Outcome → Lesson) so agents avoid repeating past mistakes.synapse_get_stats— Inspect real-time cortex statistics (active nodes, edges, vectors, superseded counts).Shared persistent brain — Backed by SQLite and shared across Claude Desktop, Cursor, Windsurf, and other MCP clients; isolate per project via
SYNAPSE_DB_PATH.Offline-capable — Zero-dependency fallback vectorizer and deterministic heuristics; optionally upgrade with
sentence-transformersand any OpenAI-compatible LLM for belief revision.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@synapse-mcp recall what we decided about the auth token expiry"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Synapse Cortex (synapse-cortex)
Biomimetic Cognitive Graph Memory, Spreading Activation, and Progressive Context Packing for Autonomous AI Agents.
Why Synapse?
AI agents without memory forget everything between sessions. However, naive vector databases (flat RAG) introduce critical cognitive flaws:
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.
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.
Context Window Bleed: Dumping raw conversation transcripts into system prompts consumes thousands of tokens and triggers attention dilution.
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 │
└─────────────────┘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.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).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-cortexPyPI 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-mcpresolves its database in this order:SYNAPSE_DB_PATHwhen set; otherwise an existing./data/synapse.dbin 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_PATHexplicitly:{ "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-mcpAvailable MCP Tools
Tool | Description |
| Hybrid semantic vector + BM25 search across all past memories, SOPs, and architectural decisions. |
| Store an atomic rule, decision, or SOP with salience weighting. |
| Record a structured episodic experience (Situation → Action → Outcome → Lesson). |
| 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) │
└──────────────────────────────────┴─────────────────────────────────────┘1. The Embedding Engine (Vector Search)
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 usingall-MiniLM-L6-v2(or your configuredSYNAPSE_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 .envThe 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=./vaultNote for Local Runners (Ollama, vLLM): If you are running locally with Ollama or vLLM, set
OPENAI_BASE_URL=http://localhost:11434/v1and leaveOPENAI_API_KEYandOPENAI_MODELblank 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.pyCounterfactual Guardrails:
test_counterfactual_guardrail.pySpreading Activation & Retainment:
test_synapse_retriever.py,test_synapse_storage.pyHebbian Reinforcement & Abstract Rollups:
test_hebbian_and_rollup.py,test_hebbian_outcome_feedback.pyMetacognitive Calibration:
test_metacognitive_scorer.py
Technical Design & Honest Trade-Offs
To maintain transparency and help developers choose the right tool for their architecture:
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_MODELvia Ollama or OpenAI) or installsentence-transformers.
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.
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).
Multi-Project Isolation:
synapse-mcpusesSYNAPSE_DB_PATHwhen 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 toolssynapse_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory for AI agents, for code, research and everyday life. Stale facts retire.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityDmaintenanceEnables 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.7MIT
- AlicenseNot gradedqualityCmaintenanceProvides 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
- AlicenseAqualityBmaintenanceEnables 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.6MIT