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).

Related MCP server: Memex

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 marketplace add verve-sh/claude-plugins
claude plugin install session-recall@verve-sh

From source

Claude Code does not auto-discover plugin directories, so register the clone as a local marketplace rather than copying it into .claude/plugins/:

git clone https://github.com/verve-sh/session-recall.git ~/src/session-recall
mkdir -p ~/src/.claude-plugin
cat > ~/src/.claude-plugin/marketplace.json <<'EOF'
{
  "name": "my-local-plugins",
  "owner": { "name": "me" },
  "plugins": [{ "name": "session-recall", "source": "./session-recall" }]
}
EOF
claude plugin marketplace add ~/src
claude plugin install session-recall@my-local-plugins

First run

No manual build. The MCP server launches through scripts/start-mcp.sh, which builds on first start and execs the server directly thereafter — so the first session takes about a minute longer while the native SQLite bindings compile. This repeats once after each plugin update.

A prebuilt dist/ cannot be shipped here: better-sqlite3 and sqlite-vec both produce platform-specific native artifacts. Requires npm on PATH. See INSTALL.md for details.

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

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