context-keeper

context-keeper

Cross-session memory for Claude Code — local-first, with a searchable browser and map of everything you've ever worked on.

By Selran — written and maintained by Padmalochan Singh ([email protected]), with Aidin Eslampour ([email protected]). MIT licensed.

Claude Code forgets everything between sessions. context-keeper walks every transcript on disk, builds a semantic chunk index plus a topic graph, and exposes a recall(query) MCP tool so future sessions pull exactly the past context they need — ranked, diversity-re-ranked, token-budgeted. The agent can also remember durable facts (and update or forget them) — as relevance-recalled notes, always-on rules, or file-glob-scoped tips that only surface when you touch a matching path; recall returns the right ones alongside the matching past transcript. An optional hook injects relevant memory into every prompt automatically, and a small web UI renders your projects, topics, and sessions as an interactive map.

Local-first: your transcripts are indexed on your machine by a local embedding model; the daemon binds 127.0.0.1 only; no telemetry. Secrets (API keys, tokens, private keys) are redacted from every chunk at ingest, before anything is embedded or stored. The only opt-in exception is LLM topic-naming/summaries — see PRIVACY.md.

What it looks like

The primary view is a fast, searchable browser of every session, grouped by project — filter by title instantly, or hit Search content (⌘K) to run the same semantic recall Claude uses. A force-directed graph is the optional secondary view. Dark, light, and system themes throughout.

Browser — your sessions (dark)	Browser (light)

The secondary graph view:

(Screenshots use a small demo workspace, not real data.)

Use it from Claude Code (plugin)

# 1. The daemon (one-time; Rust toolchain required)
cargo install --git https://github.com/apourmd941/context-keeper ck
ck daemon &        # or: ./start.sh from a clone; or: ck autostart install

# 2. The plugin (ships the MCP wiring)
/plugin install context-keeper

Then ask Claude things like "recall what we decided about the auth refactor" — or enable the auto-recall hook (§ Quickstart, step 8) and relevant past context arrives with every prompt, no tool call needed.

Summaries and topic names — no API key. Because Claude itself is connected through the plugin, it can do the LLM work in conversation: ask "summarize my recent sessions" and Claude walks list_unsummarized_sessions → get_session_transcript → save_session_summary, and names topic clusters via name_topic. The results persist to the same caches the optional API path uses and appear in the UI immediately. ANTHROPIC_API_KEY (or an optional local model gateway) remains relevant only for unattended batch summarization (ck summarize).

No database to install. context-keeper stores everything in an embedded SQLite file and a flat-file vector index under ~/.context-keeper/ — there is no Postgres, no server, and no external service to set up. The first run downloads a small local embedding model (~130 MB); after that it works fully offline.

What it does

~/.claude/projects/*.jsonl                   # source of truth (Claude Code's transcripts)
        │
        ▼
  [parse + chunk]   defensive JSONL → typed records → token-budgeted chunks
        │
        ▼
  [embed]           bge-small-en-v1.5 via fastembed (local ONNX, 384-d)
        │           ╲
        ▼            ▶ flat-file vector index (~/.context-keeper/index/vectors.bin)
  [cluster]         hand-rolled DBSCAN over chunk embeddings, per project
        │
        ▼
  [name + edge]     LLM topic names (optional)
        │           topic-similarity, shared-file edges
        ▼
  [serve]           axum HTTP/WS (loopback) + the web UI
        │           MCP stdio shim (recall, summarize, name topics, …)
        ▼
  Claude Code session calls `recall("…")` and gets ranked, MMR-diversified,
  token-budgeted chunks back.

Quickstart (macOS)

# One-time toolchain
brew install just pnpm rustup protobuf
rustup default stable

# Homebrew installs rustup keg-only — `cargo` won't be on your PATH yet.
# Add it (one of these, depending on your shell):
echo 'export PATH="/opt/homebrew/opt/rustup/bin:$PATH"' >> ~/.zshrc       # zsh (default)
echo 'export PATH="/opt/homebrew/opt/rustup/bin:$PATH"' >> ~/.bash_profile # bash
# Then open a new terminal, or `source` the file.

pnpm install

# Build
cargo build --release --bin ck

# 1. Walk transcripts (fast — metadata only)
./target/release/ck doctor