session-recall

session-recall

Local, agentic semantic recall over your Claude Code session history. It gives theagent five tools (via MCP) so it can resume past work instead of making you re-explain it:

• recall_search(query) — find a past discussion by meaning (not substring).
• expand_around(session_id, uuid) — a cursor into the raw turn (tool calls, outputs, thinking).
• step(session_id, uuid, direction) — move to an adjacent turn (cheap cursor step).
• grep(pattern) — on-demand substring scan over the raw transcripts.
• recent_sessions() — the freshest past sessions first (what's current, how fresh the index is).

On-demand (no proactive auto-injection in v1). Local, open source.

recall_search, grep and recent_sessions also take an optional scope_cwd — pass yourcurrent working directory to scope results to the current repo (worktrees collapse to the reporoot); omit it for cross-project recall. Ranked hits carry a human-readable when_humantimestamp alongside the raw epoch.

Status: v1, built and validated on real history. Key design rationale lives indocs/decisions/.

How it works

Only the conversation "surface" is indexed — user prompts and assistant text replies.tool_result / thinking / harness noise are not embedded but stay reachable viaexpand_around / grep. Embeddings: Voyage voyage-4-large (dim 1024) → SQLite(sqlite-vec KNN + FTS5) → Voyage rerank-2.5 → top-k. Indexing is incremental(by mtime+size). Subagent sidechains (<session>/subagents/) are intentionally skipped —that's under-the-hood tooling, not conversation.

Embeddings are pluggable (Voyage is the default); the reranker is optional, and thesystem degrades gracefully to KNN + FTS without one.

Install / run

python -m venv .venv && .venv/bin/pip install -e .
export VOYAGE_API_KEY=...                        # your Voyage key

.venv/bin/session-recall index                   # index ~/.claude/projects
.venv/bin/session-recall search "query"          # semantic search from the CLI

Connect to Claude Code (MCP)

claude mcp add session-recall --scope user -- \
  /absolute/path/.venv/bin/python -m session_recall.server

The server reads VOYAGE_API_KEY from the environment; the tools (recall_search andfriends) become available to the agent in new sessions. Verify withclaude mcp list → ✔ Connected.

Keeping the index fresh

Indexing is incremental (it skips already-indexed files by signature), so staying fresh ischeap. The most direct way is a Claude Code SessionStart hook that runssession-recall index in the background at the start of each session. In~/.claude/settings.json:

"hooks": {
  "SessionStart": [
    { "hooks": [ {
      "type": "command",
      "async": true,
      "command": "pgrep -f 'session-recall index' >/dev/null 2>&1 || (VOYAGE_API_KEY=... /abs/path/.venv/bin/session-recall index >/tmp/sr-index.log 2>&1 &)"
    } ] }
  ]
}

The pgrep guard prevents overlapping runs; ( … & ) detaches so session start doesn'twait. A launchd/cron timer works too. (Local on one machine is enough; a server-sideindex only makes sense across several machines — at the cost of privacy and network.)

Privacy — hard invariant

This is a public repository. Only code goes in it.

• Data, indexes, raw transcripts, embeddings → ~/.local/share/session-recall/,outside the repo tree. They physically cannot be committed.
• API keys → environment only (VOYAGE_API_KEY); .gitignore blocks .env.
• Tests → synthetic fixtures only, never a real slice of a session.