mcp-recall: Instructions file for Claude Code

CLAUDE.md – mcp-recall

Project-level conventions. Global ~/.claude/CLAUDE.md guardrails always take precedence on conflicts.

Project Overview

mcp-recall is a Claude Code plugin that intercepts large MCP tool outputs (Playwright snapshots, GitHub API responses, large file reads), compresses them, stores full versions in SQLite with FTS, and delivers brief summaries to Claude. When Claude needs detail, it retrieves via recall__* tools. Goal: enable 3+ hour sessions by preventing context window exhaustion.

Tech Stack

• Runtime: Bun (package manager + test runner — use bun not npm)
• Language: TypeScript strict mode, ESNext target
• Database: SQLite with FTS5 (built into Bun via bun:sqlite)
• Schema validation: Zod
• Config format: TOML (smol-toml)

Commands

bun test              # run all tests
bun test --watch      # watch mode
bun run typecheck     # tsc --noEmit
bun run build         # bundle src/ → plugins/mcp-recall/dist/
bun run start         # MCP server
bun run dev           # MCP server in watch mode
bun run sandbox:binary  # standalone-binary checks in a throwaway, offline Docker container
bun run quality       # public quality benchmark over benchmark/corpus/ (--write regenerates results.md, --check verifies)

No just / make in this project. Use bun test directly (not just test).

Releases follow the weekly train in CONTRIBUTING.md (Releases): merge any day, release Wednesday morning ET on the maintainer's go, hotfix only for security or a broken install/hook. Do not propose publishing outside it.

Architecture

bin/recall              Entrypoint used by hooks/hooks.json (session-start, post-tool-use)
                        and as the npm `bin`. Resolves symlinks before locating src/.
src/
  server.ts             MCP server — exposes the recall__* tools listed below
  cli.ts                Hook CLI dispatcher (mcp-recall install / learn / profiles / serve / …)
  binary.ts             Standalone-binary startup (#361): extracts embedded profiles, then cli main.
                        Built by scripts/build-binary.ts (`bun run build:binary`) into dist/bin/.
                        install/ detects the binary (detectLaunch) and registers it as hooks + server
  config.ts             TOML config loader (Zod-validated, cached)
  config-schema.ts      The Zod config schema, required only once a config file is read (#416)
  project-key.ts        Git root detection + SHA256 path hash
  log.ts                Unified stderr logging — info/warn/error/debug, gated on RECALL_DEBUG=1
  format.ts             Shared byte-size and relative-time formatting utilities
  hints.ts              Extracts salient search terms for the summary header (deterministic)
  tools.ts              Tool handler logic for all recall__* tools (pure functions; server.ts wires to MCP SDK)
  denylist.ts           Built-in + configurable denylist
  secrets.ts            Secret pattern detection before any write
  db/
    types.ts            All TypeScript interfaces for the DB layer
    schema.ts           DDL, migrations, getDb / closeDb / initSchema / defaultDbPath
    chunking.ts         CHUNK_SIZE, chunkText(), sanitizeFtsQuery()
    queries.ts          Core CRUD — storeOutput, retrieveOutput, evictIfNeeded, forgetOutputs, …
    analytics.ts        Aggregation queries — getStats, getContext, getSessionSummary, getSuggestions, …
    index.ts            Re-export barrel (all db/* in one import surface)
  handlers/             Compression handlers. The dispatch order is documented
                        canonically above getHandler() in index.ts — read it there rather
                        than trusting a paraphrase. The consequential part: user and
                        community profiles BEAT the TypeScript registry, bundled profiles
                        LOSE to it, and native Bash is routed first, before any of them.
                        Counting handlers is ambiguous (registry entries vs files vs
                        fallbacks), so HANDLER_REGISTRY is the source of truth.
  hooks/                Hook implementations (SessionStart, PostToolUse)
  gc/                   mcp-recall gc — classifies every project DB and reclaims disk.
                        Deletion policy lives in STATUS_POLICY; see the safety note below.
  discover/             mcp-recall discover — ranks fallback-routed output by bytes, with
                        reduction and retrieval rate (#341). Read-only over every store.
                        A NULL `handler` means "stored before #341", never a fallback.
  import/               mcp-recall import — restores a recall__export dump into a store
  install/              mcp-recall install / uninstall / status — writes to ~/.claude.json, settings.json, CLAUDE.md
  learn/                mcp-recall learn — reads ~/.claude.json, spawns MCP servers via stdio, generates TOML profiles
  profiles/             mcp-recall profiles subcommands (list, install, update, remove, seed, feed, check, test, info, available, retrain)
tests/                  Bun tests, co-located by module name
.claude-plugin/         Root plugin manifest (local dev / manual install)
hooks/hooks.json        Hook definitions — canonical source, copied to plugins/ on build
plugins/mcp-recall/     Marketplace-installable plugin bundle
  dist/                 Bundled server.js + cli.js (bun build --target bun)