session-recall: Instructions file for Claude Code

Session Recall Plugin

Standalone Claude Code plugin: hybrid FTS5 trigram + vector cosine search over past sessions, fused via RRF with recency boost.

Commands

cd plugins/session-recall && npm install --legacy-peer-deps
cd plugins/session-recall && npm run build
cd plugins/session-recall && npm run test

Architecture

src/
  index.ts    # MCP server setup, tool registration, stdio transport
  tools.ts    # Zod schemas + handlers for session_search, session_drill, session_health
  lib.ts      # Core: indexSession, search (hybrid FTS5 + vec0 cosine, RRF fusion), drill, health
  db.ts       # SQLite singleton: better-sqlite3 + sqlite-vec, sessions DB at ~/.claude/sessions-index.db
  marker.ts   # SessionEnd hook: zero native deps, marks session transcript for async indexing
  cli.ts      # CLI entry: session-recall index|search|drill|health
hooks/
  hooks.json       # SessionEnd hook definition
  session-end-hook.sh  # Hook script — invokes CLI to index completed session
scripts/
  start-mcp.sh     # MCP launcher — builds on first run, then execs the server

Build model

plugin.json launches scripts/start-mcp.sh, not node dist/index.js. The launcher execs the server straight through when dist/index.js exists, and otherwise runs npm install --legacy-peer-deps && npm run build first.

dist/ stays gitignored and cannot be committed. better-sqlite3 loads a platform-specific better_sqlite3.node and sqlite-vec ships a per-platform vec0 extension, so build output is only valid on the machine that produced it — a prebuilt artifact would break every install on a different OS or arch. (dispatch-lens has no native deps, so it commits a bundle instead.)

Three invariants when touching the launcher:

• Nothing may write to stdout. stdout is the JSON-RPC transport; npm writes progress there by default, which is why every build command is redirected >&2.
• Concurrent starts are serialised through an atomic mkdir "$ROOT/.build.lock". Several Claude Code sessions can launch the server at once, and two npm install runs in one directory corrupt node_modules. Release the lock before exec — exec replaces the process, so the EXIT trap never fires.
• Readiness means "a database opens", not "dist/index.js exists". Claude Code runs its own npm install at install time with install scripts disabled, so node_modules/better-sqlite3 arrives with no build/ and better_sqlite3.node is never compiled. A later npm install does nothing about it — the tree already satisfies the lockfile — so the launcher must npm rebuild better-sqlite3 explicitly. Left unbuilt, the server completes the MCP handshake and lists its tools, then fails every call with "Internal error".