recall-kit

Persistent memory and project continuity for AI agents, shared across Claude Code, Claude Desktop, Codex and any MCP client, with a test suite that proves it works across fresh sessions.

The problem

People who work with several AI tools hit the same wall. ChatGPT remembers one thing, Claude another, Codex nothing. Project status lives in a Notion page that no agent reads. When a fact changes, the old version keeps coming back. When you ask an assistant to "forget that", you can't verify it did. And nobody can say where a remembered "fact" came from.

recall-kit is a small, self-hostable memory layer that fixes this with boring, inspectable parts:

• Markdown files are the source of truth: one file per memory, with YAML frontmatter (type, source, created/updated, confidence, supersedes, tags).

• git versions every change, so history, diffs and restore come free.

• SQLite FTS5 + vectors give hybrid (BM25 + embedding) retrieval. The index is derived data and can be rebuilt.

• MCP (stdio and Streamable HTTP) lets every client share the same memory and project state.

• A continuity test suite runs each "session" as a brand-new process and checks recall, correction, deletion, citation and project resume, plus the ways agent memory typically fails.

All names, clients and data in this repo are fictional.

Related MCP server: MCP Shared Memory Hub

Demo (real terminal output)

Each rk line below is a separate process, so a fresh session every time. The only thing they share is the store on disk.

Architecture

flowchart LR
    subgraph Clients
        CC[Claude Code]
        CD[Claude Desktop]
        CX[Codex]
        VA[VPS agent / any MCP client]
    end
    CC & CD & CX -- stdio --> S1[rk serve]
    VA -- "HTTPS + Bearer token (scoped)" --> CA[Caddy TLS] --> S2[rk serve --http]
    S1 & S2 --> API[MemoryStore + ProjectBoard]
    API -->|write| MD[(memories/*.md\nprojects/*.md)]
    API -->|commit| GIT[(.git history)]
    API -->|index| IDX[(index.sqlite\nFTS5 + vectors + conflicts)]
    API -->|append| AUD[(audit.jsonl\nids only)]
    IDX -. rank .-> API
    MD -. "serve + verify each hit" .-> API
    BK[rk backup] -->|AES-256-GCM| OFF[(encrypted .rkb\noff-site)]
    MD & GIT --> BK

Three rules hold everything together:

1. Files are the truth, the index only ranks. Recall re-reads every hit from its markdown file, so a stale, rolled-back or tampered index cannot serve deleted, superseded or altered text. It heals itself instead.

2. Nothing is overwritten. correct creates a new version that supersedes the old one. The old version stays in history but is never returned as current.

3. Deletion is physical. forget removes the file, rewrites git history, deletes the FTS rows and vectors, then runs FTS optimize + VACUUM with secure_delete. The audit log records that something was deleted, never what.

How memory flows between sessions

sequenceDiagram
    participant S1 as Session 1 (Claude Code)
    participant St as Store (files + git + index)
    participant S2 as Session 2 (Codex, days later)
    S1->>St: memory_remember("Harbor Lane pays net-30", source="user, call 11-03", key=client.harbor-lane.terms)
    St-->>S1: created mem_a1 (file + commit + index)
    Note over S1: session ends, process exits
    S2->>St: memory_recall("Harbor Lane payment terms")
    St-->>S2: mem_a1 + source {origin, file, commit}
    S2->>St: memory_correct(mem_a1, "net-45 from December", source="email 11-09")
    St-->>S2: mem_b2 supersedes mem_a1
    S2->>St: project_resume("harbor-portal")
    St-->>S2: status, blockers, next steps, follow-ups, decisions (cited)

Test matrix (real results)

Run on macOS arm64 / Python 3.12, uv run pytest, 2026-11-10: 42 passed, 1 skipped (the LLM eval, because no API key is set). CI runs the same suite on Ubuntu for every push.

Full per-test list: CI writes it to the job summary (scripts/test_matrix.py).

What was verified outside the test suite

• Docker: image built; container run read-only; /healthz OK; POST /mcp without a token → 401; memory_remember + memory_recall over Streamable HTTP with a scoped token → stored at /data/store.

• Compose: docker compose config validates. Caddy/TLS needs a real domain, so it was not run here.

• Real agent client: see docs/verification/ for the status of the Claude Code session check.

Quick start

git clone https://github.com/sibrahimpa1/recall-kit && cd recall-kit
uv sync
uv run rk demo                       # fictional sample data in ~/.recall-kit
uv run rk recall "Tallow & Tide invoice terms"
uv run rk resume northwind-relaunch
uv run rk brief
uv run pytest                        # ~1 minute; the continuity suite is `-m continuity`

Core CLI:

rk remember TEXT --source S [--type fact|preference|decision|project] [--key K] [--project P] [--tag T]
rk recall QUERY [-k 5] [--type] [--project] [--all-versions] [--json]
rk correct ID TEXT --source S [--reason R]        rk forget ID --yes        rk history ID
rk conflicts | approve ID | list | doctor | reindex | stats
rk project update|add|close|decide|list ...       rk resume SLUG             rk brief
rk ics --out followups.ics                        rk backup create|verify|restore|prune
rk token new --name N --scopes read,write         rk serve [--http --port 8765]

MCP tools

Connect your clients

Ready-to-paste configs are in clients/: Claude Code (claude mcp add … or .mcp.json), Claude Desktop (claude_desktop_config.json), Codex (~/.codex/config.toml), and the remote HTTPS variant with a bearer token. integrations/claude-code/ adds a memory-protocol skill (when to recall, remember, correct, forget) and a permissions file that auto-allows reads but asks before correct and forget. integrations/AGENTS.md is the same protocol for Codex and other agents.

Security and operations

• Tokens: per-client, scoped (read, write, forget, admin), stored on the server only as SHA-256 hashes in RECALL_TOKENS. Revoke = delete the line + restart. HTTP mode won't start without tokens. Host-header allow-list against DNS rebinding.

• Secrets only in env: .env (git-ignored), see .env.example.

• Backups: rk backup create = tar of files + full git history, scrypt-derived key, AES-256-GCM, hash manifest checked on restore. rk backup verify proves a backup restores. Cron example in deploy/crontab.example.

• Deploy: deploy/docker-compose.yml: read-only container, non-root, no published port, Caddy in front with automatic TLS.

• Runbooks: docs/handover.md covers operate, troubleshoot, back up/restore, rotate credentials, revoke access, and extend.

• When is this worth it vs. built-in memory? See docs/tool-comparison.md, including rough costs and an honest list of limits.

LLM-in-the-loop eval (optional)

export ANTHROPIC_API_KEY=...        # your own key; never committed
uv run --extra eval python evals/llm_eval.py

Five scenarios (recall, correction, deletion, resume, injected content). Each session is a new MCP server process and a new conversation with no history. Model: claude-opus-5-5 (adaptive thinking, effort: medium, server-side refusal fallback). A deterministic grader checks the final answer and the store on disk. For example, after "update the sync to Thursday" there must be exactly one current sync memory and one superseded one. Results go to evals/results/. Without a key it prints SKIPPED and exits 0. In CI it runs only if the repo has an ANTHROPIC_API_KEY secret.

Project layout

src/recall_kit/   store.py (lifecycle + recall) · index.py (FTS5/vectors) · gitrepo.py · projects.py
                  admin.py (brief, ICS) · backup.py · auth.py · safety.py · embed.py · server.py (MCP) · cli.py
tests/            continuity, failure modes, HTTP auth, ops (fresh process per session)
evals/            LLM-in-the-loop eval
clients/          Claude Code / Desktop / Codex configs        integrations/   skill, permissions, AGENTS.md
deploy/           Docker Compose + Caddy + cron                docs/           handover, tool comparison, verification

Author

Senka Ibrahimpašić GitHub @sibrahimpa1

Licensed under the MIT License.