session-recall

Local, agentic semantic recall over your Claude Code and Codex session history. Both hosts feed one index, so either agent can recover context created by the other. It gives the agent 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 all indexed transcripts, including under-the-hood turns (tool output, thinking) that never became search chunks.
• 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 your current working directory to scope results to the current repo (worktrees collapse to the repo root); omit it for cross-project recall. Ranked hits carry a human-readable when_human timestamp alongside the raw epoch. Every MCP tool accepts an optional source (claude or codex); omit it to use the unified history. Results include provenance as source=claude or source=codex. The three discovery tools also accept on_date for one day or inclusive start_date / end_date (YYYY-MM-DD) plus an optional IANA timezone, so an agent can constrain retrieval to an actual local calendar day instead of hoping a date written into the semantic query affects ranking. If timezone is omitted, Session Recall uses the timezone of the computer running the MCP server.

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

How it works

Claude Code transcripts and Codex sessions from ~/.codex/sessions plus ~/.codex/archived_sessions share the same index. Only the conversation "surface" is embedded — user prompts and assistant text replies. Tool calls, results, reasoning, and other trace data are not embedded but stay reachable on demand via expand_around (and step) or grep. Raw Codex transcript files remain local; only the extracted conversation surface is sent to the configured embedding provider.

Embeddings: Voyage voyage-4-large (dim 1024) → SQLite (sqlite-vec KNN + FTS5, bm25-ranked) → Voyage rerank-2.5 → top-k. Indexing is incremental (by file metadata, including Codex inode+size) and cheap on live transcripts: they are append-only, so unchanged chunks are matched by content hash and their vectors reused — only new turns hit the embedding API. Moving a Codex rollout into the archive also reuses its existing vectors. Each file indexes in its own transaction; a failing file is logged and retried on the next run, never aborting the rest. Claude sidechains (<session>/subagents/) and Codex spawned-subagent sessions are intentionally skipped — they are under-the-hood tooling, not the primary user/agent conversation.

Embeddings are pluggable (Voyage is the default); the reranker is optional, and the system degrades gracefully to KNN + FTS without one. Switching the embedding provider/model is detected (an embed fingerprint is part of each file's index signature) and triggers a clean re-embed instead of silently mixing vector spaces.

Install / run

For normal use with the bundled Claude Code/Codex plugins, install the two CLI entrypoints on your user PATH (the manifests also check ~/.local/bin):

pipx install --editable .
export VOYAGE_API_KEY=...                        # your Voyage key

session-recall index                             # both sources (same as --source all)
session-recall index --source claude             # only ~/.claude/projects
session-recall index --source codex              # active + archived Codex sessions
session-recall search "query"                    # unified semantic search
session-recall search "query" --source codex
session-recall recent --source claude            # freshest Claude sessions
session-recall recent --date 2026-07-14           # uses this computer's timezone
session-recall search "deployment work" --start-date 2026-07-14 \
  --end-date 2026-07-14 --timezone Asia/Yekaterinburg
session-recall grep "exact" --source codex --limit 100  # raw scan, no API needed
session-recall prune                             # drop rows for deleted transcripts

For repository development or manual MCP registration, an in-tree virtualenv works too:

python -m venv .venv && .venv/bin/pip install -e .
.venv/bin/session-recall index

index --source accepts all, claude, or codex and defaults to all. search, recent, grep, and prune accept optional --source claude|codex; omit it for both. search, recent, and grep accept --date for one day or --start-date, --end-date, and --timezone for a range; range dates are inclusive and either boundary may be omitted. The timezone defaults to the computer's local zone and can be overridden with an IANA name. Raw grep returns at most 100 matches by default; use --limit to adjust the cap.

Connect to Claude Code or Codex (MCP)

The repo includes both Claude Code and Codex plugin manifests around the same MCP server and recall skill. To register the server manually in Claude Code:

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. For Codex, the .codex-plugin/plugin.json manifest is ready to place in a local repo or personal marketplace; follow the local plugin installation guide. In Claude Code, verify with claude mcp list → ✔ Connected. Start a new session/task after enabling the plugin so the MCP tools and skill are loaded.

Keeping the index fresh

Indexing is incremental (it skips already-indexed files by signature), so staying fresh is cheap. The plugin's bundled SessionStart hook is compatible with both hosts and runs session-recall index in the background; the default --source all refreshes both histories. Codex requires a one-time review/trust of newly installed or changed hooks through /hooks. For a manual Claude Code hook in ~/.claude/settings.json:

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

The pgrep guard prevents overlapping runs; ( … & ) detaches so session start doesn't wait. Keep the host-level hook synchronous: the shell already backgrounds the indexer, and Codex ignores Claude's async extension. A launchd/cron timer is another option. (Local on one machine is enough; a server-side index 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.
• Claude Code transcripts plus active and archived Codex transcripts are read locally. Only user/assistant surface text is embedded; tool/reasoning trace data stays out of embeddings and is exposed only by explicit raw expansion or grep.
• Chunk texts ARE sent to your configured embedding/rerank provider (Voyage by default) — pick a provider you trust with your transcripts, or point the OpenAI-compatible provider at a local endpoint.