Synapse — Personal AI Memory OS

Chat history is a log. Synapse is a brain.

Synapse is a local-first personal memory operating system that gives AI agents durable, typed long-term memory. It extracts semantic facts from episodic conversations, anchors single-current-value facts to entity keys so new values supersede old ones, detects and resolves conflicts, decays stale information, and retrieves with a hybrid scoring pipeline that attaches trust qualifiers and learns from agent feedback — all on local SQLite with full user control over export and purge. It refuses to store credentials, and an always-on digest covers what retrieval can't: the facts an agent should just know at session start.

Architecture

flowchart TB
    subgraph Agents["Agents & Surfaces"]
        MCP["MCP clients<br/>Claude Code · Claude Desktop · Cursor · OpenCode"]
        SDK["SDK adapters<br/>Anthropic · OpenAI-compatible routers"]
        CLI["CLI<br/>synapse remember / query / export"]
        UI["Inspector UI"]
    end

    subgraph Tools["Memory tools (Zod-validated, importance-capped)"]
        W["memory_write<br/>+ entityKey supersession"]
        R["memory_retrieve<br/>+ trust qualifiers"]
        D["memory_digest<br/>always-on core memory"]
        F["memory_feedback<br/>helpful / stale / wrong"]
    end

    API["HTTP API (Hono)<br/>/v1/memories · /v1/jobs · /v1/conflicts · /v1/export · /v1/purge"]

    subgraph Store["Store (better-sqlite3 · WAL)"]
        REPO["MemoryRepository<br/>CRUD · links · quarantine · audit · jobs"]
        RET["RetrievalService<br/>vector + BM25 keyword + importance + recency − decay − conflict"]
        JOBS["Jobs<br/>consolidate · conflict · decay · purge"]
    end

    subgraph Providers["Providers (env-configured factories)"]
        EMB["Embeddings<br/>hash (offline) · OpenAI-compatible"]
        LLM["LLM<br/>OpenAI-compatible · FakeLlm for tests"]
    end

    MCP --> W & R & D & F
    SDK --> W & R
    W & R --> API
    CLI --> Store
    UI --> API
    API --> Store
    RET --> EMB
    JOBS --> LLM
    JOBS --> EMB

The MCP server talks to the store directly (like the CLI); the SDK adapters route through the HTTP API. All write paths share the same guards.

Monorepo layout

apps/
  api/             HTTP API (Hono) + inspector page
  demo-agent/      tool-calling demo agent
  mcp-server/      stdio MCP server (Claude Code/Desktop/Cursor)
packages/
  core/            Zod schemas, scoring helpers, ID generation
  store/           SQLite repository, retrieval, jobs
  embeddings/      provider interface + hash/OpenAI embeddings
  sdk/             SynapseClient + tool definitions + provider adapters
  evals/           32 golden cases + lifecycle test
  cli/             synapse CLI
scripts/
  demo.sh          north-star demo script

Retrieval scoring

Hybrid score per candidate memory:

\begin{aligned}
\text{score} ={} & 0.40 \cdot \text{vector} + 0.20 \cdot \text{keyword} + 0.15 \cdot \text{importance} + 0.10 \cdot \text{confidence} \\
& + 0.10 \cdot \text{recency} - 0.10 \cdot \text{decay} - 0.05 \cdot \text{conflict}
\end{aligned}

Weights defined in DEFAULT_RANK_WEIGHTS (packages/core/src/scoring.ts). Retrieval is 100% non-LLM by default; the LLM is used only in consolidation and conflict detection. An opt-in rerank: true flag lets an LLM reorder the final hit list (for benchmark headroom) — any parse failure or LLM error falls back silently to hybrid order, and the MCP path never uses it.

The keyword component is real full-text search, not substring matching: an SQLite FTS5 index (porter unicode61 tokenizer — English stemming, other scripts match exactly) scores hits with BM25, and every query token prefix-matches ("roas" finds "roast"). Candidacy is the union of FTS keyword hits and the vector top-K — memories matching neither signal are noise for that query and are never scored (always-know facts are the digest's job, below). If the FTS index is ever broken, retrieval degrades to legacy substring scoring instead of failing, and audits the fallback.

Retrieval also closes the loop instead of being a one-way pipe:

• Trust qualifiers — each result may carry a qualifier string ("stored 8 months ago — may be outdated; disputed by a conflicting memory; low confidence") so the consuming LLM can hedge instead of confidently asserting stale facts.
• Touch-on-retrieve — returned memories get their lastAccessedAt bumped, so memories that keep proving relevant rank higher over time via the recency term.
• Abstention — pass minScore and Synapse returns nothing rather than weakly-related noise; an empty result is a signal, not a failure.
• Rank-based group boost — the tag group whose best member scored highest gets a small additive boost for all its members (ordinal, not distance-based), so weak siblings of a strong hit outrank unrelated stragglers.
• 1-hop link expansion — a hit on a memory pulls in its part_of / related_to neighbors at half score when there's room, so a hit on a chapter brings its book along.
• Semantic dedup at write time — a new memory near-identical to an existing one is absorbed instead of stored twice, keeping retrieval results from filling with duplicates.

Memory tools (MCP)

Entity anchoring fixes the classic staleness bug ("I work at Acme Corp" retrieved three months after you switched jobs): facts with an entityKey behave like a current-value slot, not an append-only log. The consolidation job emits entity keys too, so facts extracted from conversation get the same treatment. Superseded values stay in history (status: superseded, linked via supersedes) — nothing is silently lost.

Quick start

pnpm install
pnpm test                              # all tests
pnpm eval                              # eval harness (32 cases)
pnpm dev:api                           # http://localhost:8787

# CLI
pnpm --filter @synapse/cli start remember semantic "User prefers TypeScript"
pnpm --filter @synapse/cli start query "TypeScript preference"
pnpm --filter @synapse/cli start export

# Inspector — browse/edit memories, link graph, analytics charts, audit trail (light/dark)
open http://localhost:8787/inspector

# North-star demo (requires API running)
./scripts/demo.sh

Use from any AI agent

Synapse exposes memory_write, memory_retrieve, memory_digest, and memory_feedback over MCP. Any MCP-capable agent can use it — verified live with Claude Code (write in one session, recall in a fresh one).

Claude Code:

claude mcp add --scope user synapse -- npx -y synapse-os

# or from a source checkout:
claude mcp add --scope user synapse -- pnpm --dir /path/to/synapse mcp

Then verify inside a new session with /mcp — synapse must show as connected. Tool calls appear as permission prompts named synapse - memory_write / synapse - memory_retrieve.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart the app:

{
  "mcpServers": {
    "synapse": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/memory-os", "mcp"]
    }
  }
}

Cursor — Settings → MCP → Add server, or add the same mcpServers block to ~/.cursor/mcp.json.

OpenCode:

opencode mcp add synapse -- pnpm --dir /path/to/memory-os mcp

Forced recall (optional): MCP tool calls are ultimately the model's choice. For deterministic recall, copy integrations/opencode/synapse-recall.ts to ~/.config/opencode/plugin/ and set SYNAPSE_REPO to your checkout (or edit the REPO constant). It hooks chat.message: when a prompt contains a trigger phrase ("use synapse", "deep memory", "recall", "what do you know about …"), it queries the DB directly and injects the results into the prompt before the model runs — no reliance on the model calling the tool.

Any other MCP client — it's a standard stdio server: command pnpm, args ["--dir", "/path/to/memory-os", "mcp"].

The server stores to ~/.synapse/synapse.db by default; set SYNAPSE_DB in the server's env to share one database with the API/CLI/Inspector.

Testing tips (learned the hard way):

• Confirm the tool is actually connected in the session before judging results (/mcp in Claude Code, opencode mcp list).
• Hosts with their own memory feature (Claude Code) may prefer it for passive "remember X" phrasing — name the tool ("use the synapse memory_write tool") or add Use the synapse MCP tools for storing and recalling user memories. to