# 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

```bash
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/`:

```bash
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](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

| 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

```bash
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