session-recall

Session transcripts hold the detail that memory files and commit messages don't — error traces, abandoned approaches, debugging steps, exact tool output. This plugin makes that history searchable.

session-recall indexes completed Claude Code sessions into a local SQLite database and exposes them via an MCP server. Search is hybrid — FTS5 trigram matching for exact text (error messages, file names, CLI output) and optional vector embeddings for semantic similarity — so both precise and fuzzy queries work.

MCP tools

• session_search — Search across all indexed sessions. Returns ranked snippets with session ID, timestamp, and match context.
• session_drill — Expand context around a search hit. Pass a session ID and chunk ordinal to see surrounding conversation turns.
• session_coverage — Batch coverage report: for each term, count how many chunks mention it and when it was last seen. Use for dead-code/dead-skill detection.
• session_health — Index health report (counts, staleness, DB size).

How it works

1. A SessionEnd hook writes a pending-session marker when a session completes
2. The MCP server runs a background backfill loop that discovers and indexes .jsonl session files
3. Sessions are parsed, chunked, redacted (secrets stripped), and stored in a SQLite FTS5 index
4. When VOYAGE_API_KEY is set, chunks are also embedded via Voyage AI and stored in a sqlite-vec virtual table for vector search
5. Search queries run against both indexes; results are fused via RRF with configurable recency boost

Install

From marketplace

claude plugin install session-recall@verve-sh/session-recall

From source

git clone https://github.com/verve-sh/session-recall.git
cp -r session-recall/ <your-project>/.claude/plugins/session-recall/
cd <your-project>/.claude/plugins/session-recall/
npm install --legacy-peer-deps
npm run build

Vector search (optional)

Set VOYAGE_API_KEY in your environment to enable vector cosine search alongside FTS5. Without it, search falls back to FTS5-only (still effective for exact text matching).

Configuration

Variable	Description
VOYAGE_API_KEY	Voyage AI API key for vector embeddings. Without it, search falls back to FTS5-only.
SESSION_RECALL_DB	Override path to the sessions SQLite database. Default: ~/.claude/sessions-index.db.
SESSION_RECALL_DIR	Override path to the session .jsonl directory. Default: derived from CLAUDE_PROJECT_DIR.

Usage

When to use

• User asks about prior decisions, past work, or "have we done X before"
• Investigating recurring friction — errors, failed approaches, workaround patterns
• Checking whether an issue was previously encountered or a solution tried
• Building evidence for process improvements (hooks, rules, gotchas)

Query strategy

• Use concrete text from actual sessions: error messages, file names, script names, CLI output
• Single focused queries, not compound keyword lists — "ECONNREFUSED 127.0.0.1:5432" finds results; "database connection failed" does not
• Run 3-4 targeted queries in parallel to triangulate a topic
• Use explain: true to diagnose weak results

Workflow

session_search → read snippets → session_drill(session_id, chunk_ord) on best hit for full context

CLI

node dist/cli.js --health                    # Index health report
node dist/cli.js --backfill                  # Index new/changed sessions
node dist/cli.js --backfill-last             # Write pending marker (fast)
node dist/cli.js --rebuild                   # Rebuild entire index
node dist/cli.js --hydrate-vectors           # Fill missing vector embeddings
node dist/cli.js --reindex <session-id>      # Reindex a specific session
node dist/cli.js <query> [--limit N] [--explain]  # Search sessions

Requirements

• Node.js 20.19+ / 22.13+ / 24+
• Python is NOT required

License

Apache-2.0