synapse-memory
Advanced tools
MCP server for Claude Code session intelligence — persistent memory across coding sessions
Persistent session memory for Claude Code
An MCP server that gives Claude Code a memory that lasts.
Every session — files touched, decisions made, patterns discovered — recorded locally in SQLite.
Queryable across sessions. Zero infrastructure. Clear upgrade path to Synapse.
Claude Code starts every session with amnesia. It doesn't know what you decided yesterday, which files you refactored last week, or what patterns your codebase follows. You re-explain context. It re-discovers patterns. You both waste time.
synapse-memory records what happens in each coding session and makes it available at the start of the next one. Decisions persist. Patterns are remembered. Errors that were resolved stay resolved.
All data persists in a local SQLite file across sessions, across restarts, forever. No cloud. No accounts. No infrastructure.
Here's what actually happens when synapse-memory is connected:
┌─────────────────────── SESSION 1 ───────────────────────┐
│ │
│ > session_start({projectPath: "/myapp"}) │
│ Session started: a1b2c3d4 │
│ │
│ > record_event({ │
│ detail: { type: "decision", │
│ title: "Use repository pattern", │
│ rationale: "Clean data access separation" } │
│ }) │
│ Event recorded: decision │
│ │
│ > promote_knowledge({ │
│ title: "Use repository pattern", │
│ content: "All data access through repository │
│ functions. Never access db directly.", │
│ knowledgeType: "decision" │
│ }) │
│ Knowledge promoted. │
│ │
│ > session_end({ │
│ summary: "Built storage layer with repo pattern" │
│ }) │
│ Session completed. Duration: 45 min. Events: 12. │
│ │
└─────────────────────────────────────────────────────────┘
════════════════ Time passes. New day. ════════════════
┌─────────────────────── SESSION 2 ───────────────────────┐
│ │
│ > session_start({projectPath: "/myapp"}) │
│ │
│ Session started: e5f6g7h8 │
│ Project: /myapp │
│ Branch: main │
│ │
│ --- Recent Sessions --- │
│ [2026-02-16] Built storage layer with repo pattern │
│ Decision: Use repository pattern │
│ Pattern: Immutable return types with readonly │
│ │
│ --- Project Knowledge --- │
│ [decision] Use repository pattern: All data access │
│ through repository functions. Never access db │
│ directly. │
│ │
│ Claude now knows what happened yesterday. │
│ │
└─────────────────────────────────────────────────────────┘
This is real output. Session 2 automatically surfaces decisions, patterns, and promoted knowledge from Session 1 — with no manual context passing.
claude mcp add synapse-memory -- npx -y synapse-memory
.mcp.json{
"mcpServers": {
"synapse-memory": {
"command": "npx",
"args": ["-y", "synapse-memory"]
}
}
}
That's it. No database to run. No API keys. No configuration. Data lives in ~/.synapse-memory/memory.db.
synapse-memory provides 7 MCP tools organized around a session lifecycle:
session_start ──> record_event (repeat) ──> session_end
│ │
│ Returns context from past sessions │ Computes metrics, stores summary
│ + promoted knowledge │
▼ ▼
┌─────────────────────────────────────────────────────┐
│ SQLite (persisted) │
│ ~/.synapse-memory/memory.db │
│ │
│ sessions ─── session_events ─── promoted_knowledge │
└─────────────────────────────────────────────────────┘
▲ ▲
│ │
recall / stats promote_knowledge
get_knowledge (elevate to permanent)
Key insight: session_start reads from the database. session_end writes to it. The SQLite file bridges the gap between sessions — that's the entire trick. No external service needed.
| Tool | Purpose |
|---|---|
session_start | Begin a session. Auto-detects git branch/commit. Returns context from recent sessions and promoted knowledge. |
session_end | End a session. Computes metrics (duration, files touched, decisions recorded) and stores a summary. |
| Tool | Purpose |
|---|---|
record_event | Record significant events during a session: file operations, tool calls, architectural decisions, patterns, error resolutions, milestones. |
| Tool | Purpose |
|---|---|
recall | Full-text search across past sessions. Find decisions, patterns, and error resolutions from your project history. |
stats | Session analytics: total sessions, time spent, most-touched files, event breakdowns by period. |
| Tool | Purpose |
|---|---|
promote_knowledge | Elevate a session finding to project-level knowledge. Promoted knowledge persists permanently and is surfaced at the start of every new session. |
get_knowledge | Retrieve promoted knowledge, optionally filtered by type (decision, pattern, error_resolved, milestone). |
session_startStart a new coding session. Abandons any stale active sessions for the same project.
Input:
projectPath string (required) Working directory / project root
branch string (optional) Git branch — auto-detected if omitted
gitCommit string (optional) Current HEAD SHA — auto-detected if omitted
Output:
Session ID, project context from recent sessions, promoted knowledge
session_endEnd the current session with computed metrics.
Input:
sessionId string (required) Session ID from session_start
summary string (optional) What was accomplished
gitCommit string (optional) HEAD SHA at session end
Output:
Session metrics (duration, events by category, files read/modified,
decisions recorded, patterns discovered, errors resolved)
record_eventRecord a significant event. The eventType is derived from the detail object for consistency.
Input:
sessionId string (required) Active session ID
eventType string (required) file_read | file_write | file_edit | tool_call |
decision | pattern | error_resolved | milestone
detail object (required) Event-specific detail (see below)
Detail shapes:
| Type | Shape |
|---|---|
| File operation | { type: "file_op", path: "/src/index.ts", operation: "read" | "write" | "edit" } |
| Tool call | { type: "tool_call", toolName: "Bash", params?: "npm test" } |
| Decision | { type: "decision", title: "Use SQLite", rationale: "Zero infrastructure" } |
| Pattern | { type: "pattern", description: "Repository pattern", files: ["/src/storage/"] } |
| Error resolved | { type: "error_resolved", error: "TypeError: ...", resolution: "Added null check", files: ["/src/utils.ts"] } |
| Milestone | { type: "milestone", summary: "Storage layer complete" } |
recallQuery past sessions for relevant knowledge.
Input:
projectPath string (required) Project root path
query string (optional) Full-text search term
branch string (optional) Filter by git branch
eventType string (optional) Filter by event type
limit number (optional) Max results (default 10, max 50)
Output:
Matching sessions with summaries, decisions, patterns, and error resolutions
statsSession analytics for a project.
Input:
projectPath string (required) Project root path
period string (optional) day | week | month | all (default: week)
Output:
Total sessions, total time, most-touched files, patterns discovered
promote_knowledgeElevate a session finding to project-level knowledge.
Input:
projectPath string (required) Project root path
title string (required) Short title
content string (required) Detailed content
knowledgeType string (required) decision | pattern | error_resolved | milestone
tags string[] (optional) Tags for categorization
sessionId string (optional) Source session ID
sourceEventId string (optional) Source event ID
Output:
Confirmation with knowledge ID and total count
get_knowledgeRetrieve promoted project-level knowledge.
Input:
projectPath string (required) Project root path
knowledgeType string (optional) Filter by type
limit number (optional) Max results (default 20, max 100)
Output:
Knowledge items with type, title, content, and tags
All data stays on your machine. Nothing is sent anywhere.
~/.synapse-memory/
memory.db # SQLite database (WAL mode, persists across sessions)
Override the location:
SYNAPSE_MEMORY_DIR=/custom/path synapse-memory
The database uses versioned migrations (currently v2):
| Table | Purpose |
|---|---|
sessions | Session lifecycle (start, end, status, summary, git refs) |
session_events | Events recorded during sessions (file ops, decisions, patterns, ...) |
promoted_knowledge | Project-level knowledge promoted from sessions |
synapse_sync_config | Connection config for optional Synapse sync (future) |
schema_version | Migration tracking |
synapse-memory is the local-first entry point to Synapse, a semantic caching layer for LLM applications. The types and schema are designed for a smooth upgrade path:
| synapse-memory | Synapse (Rust) | Alignment |
|---|---|---|
PromotedKnowledge | synapse-types::PromotedKnowledge | Field-level mapping |
SessionMetrics | synapse-types::SessionMetrics | eventsTotal -> tool_calls_total |
SynapseSessionExport | Full session export format | Ready for sync API |
synapse_sync_config | Tenant/project model | Stores connection details |
session_start, session_end)session_start (recent sessions + decisions + patterns)recall)stats)git clone https://github.com/WorldFlowAI/synapse-memory
cd synapse-memory
npm install
npm test # 71 tests, 88%+ coverage
npm run build # Compile to dist/
src/
index.ts # Entry point (stdio transport)
server.ts # MCP server setup + tool registration
types.ts # Core types (aligned with Synapse)
utils.ts # Git helpers, event categorization
storage/
database.ts # SQLite setup + versioned migrations
sessions.ts # Session CRUD + metrics
events.ts # Event CRUD
knowledge.ts # Promoted knowledge CRUD
tools/
session-start.ts # session_start tool
session-end.ts # session_end tool
record-event.ts # record_event tool
recall.ts # recall tool
stats.ts # stats tool
knowledge.ts # promote_knowledge + get_knowledge tools
tests/
storage/ # Storage layer tests
tools/ # Tool handler tests
npm run build
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
SYNAPSE_MEMORY_DIR=/tmp/test node dist/index.js
FAQs
MCP server for Claude Code session intelligence — persistent memory across coding sessions
The npm package synapse-memory receives a total of 1 weekly downloads. As such, synapse-memory popularity was classified as not popular.
We found that synapse-memory demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.