mcp-recall

Your context window is finite. MCP tool outputs aren't. mcp-recall bridges the gap.

MCP tool outputs — Playwright snapshots, GitHub API responses, Linear queries — can consume tens of kilobytes of context per call. A 200K token context window fills up in ~30 minutes of active MCP use. mcp-recall intercepts those outputs, stores them in full locally, and delivers compressed summaries to Claude instead. When Claude needs more detail, it retrieves exactly what it needs via FTS search — without re-running the tool.

Sessions that used to hit context limits in 30 minutes routinely run for 3+ hours.

The full context stack

Context pressure builds at four distinct layers. Native Claude tooling now covers most of them for built-in tools — but leaves MCP tool output largely unhandled. That's the gap mcp-recall fills.

flowchart TD
    A(["Claude session begins"]) --> B

    B["① Tool definitions loaded into context\n~500 tokens × every connected tool"]
    B -->|"Claude Code Tool Search · Switchboard\ndefer unused schemas"| C

    C["② Claude calls tools in sequence"]
    C -->|"Code Mode · FastMCP 3.1\nrun script in sandbox, no intermediate results"| D

    D["③ MCP tool returns large output\n50–85 KB per call"]
    D -->|"mcp-recall\nintercepts pre-context · ~300 B summary · full copy in SQLite"| E

    E["④ Session ends"]
    E -->|"mcp-recall\npersists across sessions via FTS index"| F(["Next session: clean context"])

Layers ① and ② have solid first-party and community solutions. For layer ③, Claude Code's microcompaction already offloads built-in tool output to disk — but MCP tool output is instead truncated at a 25k-token ceiling and discarded. mcp-recall fills exactly that gap: it intercepts MCP output before it reaches the window, stores the full payload locally, and keeps it retrievable.

How this compares to Claude's native context tools: API-level context editing (beta), compaction (beta), and the memory tool all reduce context — but through lossy eviction or model-authored summaries, with no verbatim retrieval or full-text search of the original tool output. mcp-recall is complementary, not competing: it captures MCP output automatically (skipping denylisted tools and secrets), stores it verbatim with an FTS index, and sits ahead of native compaction in the pipeline as the MCP-output layer. All layers stack — run them together for maximum efficiency.

How it works

flowchart LR
    A["MCP tool output\n(e.g. 56 KB snapshot)"] -->|"PostToolUse hook"| B(["mcp-recall"])
    B -->|"~300 B summary"| C["Claude's context"]
    B -->|"full content + FTS index"| D[("SQLite")]
    D <-->|"recall__retrieve · recall__search"| C

flowchart TD
    A["MCP tool response<br/>(e.g. 56 KB snapshot)"] --> B[PostToolUse hook]

    subgraph SEC["Security checks"]
        DENY[denylist match?]
        SCRT[secret detected?]
    end

    B --> DENY
    DENY -- yes --> P1([skip: passes through unchanged])
    DENY -- no --> SCRT
    SCRT -- yes --> P2([skip + warn: passes through unchanged])
    SCRT -- no --> DEDUP_N

    subgraph DEDUP["Dedup check"]
        DEDUP_N["sha256(name+input)<br/>or sha256(content)"]
    end

    DEDUP_N -- "cache hit" --> CACHED(["[cached] header"])
    DEDUP_N -- miss --> HAND_N

    subgraph HANDLER["Compression handler (TOML profile first)"]
        HAND_N["Playwright · GitHub · GitLab · Shell<br/>Linear · Slack · Tavily · Database<br/>Sentry · Filesystem · CSV · JSON · Text"]
    end

    HAND_N --> CTX["Context<br/>299 B summary + recall header"]
    HAND_N --> DB_N

    subgraph DB["SQLite store"]
        DB_N["full content (56 KB) · summary (299 B)<br/>FTS index · access tracking · session days"]
    end

    DB_N --> TOOLS["recall__* tools<br/>retrieve · search · pin · note<br/>stats · session_summary · list · forget · export · context"]

Two hooks, one MCP server.

• SessionStart hook — records each active day, prunes expired items, and injects a compact context snapshot before the first message
• PostToolUse hook — intercepts MCP tool outputs and native Bash commands; deduplicates identical calls (by input) and identical output (by content hash); compresses, stores, and returns summary
• recall MCP server — exposes ten tools for retrieval, search, memory, and management

Scope: Compression applies to MCP tools and the native Bash built-in. The remaining built-ins (Read, Grep, Glob) pass through unchanged. See Scope for details.

Results

Real numbers from actual tool calls:

Across a full session: 315 KB of tool output → 5.4 KB delivered to context.

Used daily in development of this project for over 40 days across 9 releases. No broken sessions, no data loss.

Install

→ Quickstart guide — get up and running in 2 minutes.

Prerequisites

• Claude Code installed
• Bun installed — curl -fsSL https://bun.sh/install | bash

Option A — npm (recommended)

No global install required — run directly with npx or bunx:

npx mcp-recall install   # or: bunx mcp-recall install

Or install globally for faster subsequent runs:

bun add -g mcp-recall    # or: npm i -g mcp-recall
mcp-recall install       # register hooks + MCP server in Claude Code
mcp-recall status        # verify

mcp-recall install writes the MCP server entry and hooks to ~/.claude.json and ~/.claude/settings.json, and adds a short instruction block to ~/.claude/CLAUDE.md so Claude knows how to use the recall tools. It's idempotent — safe to re-run after updates.

Update: bun update -g mcp-recall && mcp-recall install

Uninstall: mcp-recall uninstall && bun remove -g mcp-recall

Option B — Claude Code plugin marketplace

claude plugin marketplace add mcp-recall https://github.com/sakebomb/mcp-recall
claude plugin install mcp-recall@mcp-recall

Both hooks and the MCP server register automatically. Verify with claude --debug.

Option C — from source

git clone https://github.com/sakebomb/mcp-recall
cd mcp-recall
bun install
bun run build
./bin/recall install

The mcp-recall binary is not on PATH for source installs. Add an alias so the CLI works everywhere:

echo 'alias mcp-recall="bun /path/to/mcp-recall/plugins/mcp-recall/dist/cli.js"' >> ~/.zshrc
source ~/.zshrc

Or symlink it:

ln -sf /path/to/mcp-recall/plugins/mcp-recall/dist/cli.js ~/.local/bin/mcp-recall

Updating

Option A — npm / bun global install

bun update -g mcp-recall && mcp-recall install

mcp-recall install is idempotent — it updates hook paths and the MCP server entry in place without touching your stored data or config.

Option B — Claude Code plugin marketplace

claude plugin update mcp-recall@mcp-recall

Option C — from source

git pull
bun install
bun run build
mcp-recall install   # re-registers hooks with the new binary path

After updating

Run mcp-recall status to confirm the new version is active and hooks are registered correctly. Then update community profiles to pick up any new or revised ones:

mcp-recall profiles update

Maintenance

mcp-recall keeps a separate SQLite database per project under ~/.local/share/mcp-recall/. Over time, projects you delete leave their databases behind, and databases accumulate free pages. mcp-recall gc reclaims both:

# Review what would be reclaimed — dry run, deletes nothing
mcp-recall gc

# Actually delete orphaned + stale databases
mcp-recall gc --force

# Also compact the databases you keep (reclaims free pages;
# rewrites each file, so it can take a moment on a large store)
mcp-recall gc --force --vacuum

Each database is classified by whether its recorded project path still exists on disk:

• orphaned — the project directory is gone; safe to delete.
• legacy — created before path tracking; only a deletion candidate once untouched longer than --stale-days N (default 90).
• active / current — kept; the current project's database is never deleted.

The active project's database is always protected. When the store grows past store.gc_reminder_mb (default 2 GB), session start injects a one-line reminder to run gc, and mcp-recall status shows the store's size. There's no automatic deletion — reclaiming is always an explicit command.

Profiles

Profiles teach mcp-recall how to compress output from specific MCPs. Four profiles ship built in (Jira, Gmail, Context7, Docker). 18 community profiles cover Grafana, Shopify, Notion, and more.

# Install profiles for all your connected MCPs
mcp-recall profiles seed

# Or install the full community catalog at once
mcp-recall profiles seed --all

# See what's available in the community catalog (add --verbose for MCP URLs)
mcp-recall profiles available

# See what's installed (accepts short names: "grafana" not "mcp__grafana")
mcp-recall profiles list

# Get full metadata for a profile (manifest-first, falls back to local data offline)
mcp-recall profiles info grafana

# Keep profiles up to date
mcp-recall profiles update

→ Profiles quickstart · Profile schema · Community catalog

Configuration

mcp-recall works out of the box. To customize, create ~/.config/mcp-recall/config.toml:

[store]
# Days of actual Claude Code use before stored items expire.
# Vacations and context switches to other projects don't count —
# only days you actively used Claude Code on this project.
# See "Session days" below.
expire_after_session_days = 30

# How to identify a project.
# "git_root" is recommended — stable regardless of launch directory.
# Falls back to "cwd" if not inside a git repo.
key = "git_root"

# Hard cap on store size in megabytes. Least-frequently-accessed
# non-pinned items are evicted when this limit is exceeded.
max_size_mb = 500

# Access count threshold for pin suggestions in recall__stats.
# Items accessed at least this many times will appear as pin candidates.
pin_recommendation_threshold = 5

# Days since creation before a never-accessed item appears as a stale candidate
# in recall__stats. Helps identify stored output that was never retrieved.
stale_item_days = 3

# Half-life (in days) for eviction scoring when the store exceeds max_size_mb.
# Eviction ranks items by a recency-weighted access frequency, so a steadily
# used recent item outranks one accessed many times but long ago. Lower =
# recency matters more; higher = frequency dominates. Pinned items are exempt.
eviction_half_life_days = 7

# When the on-disk store (all project databases combined) grows past this many
# megabytes, session start injects a one-line reminder to run `mcp-recall gc`.
# Set to 0 to disable the reminder. Detection is cheap (no databases are opened).
gc_reminder_mb = 2048

[retrieve]
# Max bytes returned by recall__retrieve(mode: "full").
# Claude can override this per-call via the max_bytes parameter.
default_max_bytes = 8192

[denylist]
# Additional tool name glob patterns to never store.
# These extend the built-in defaults — they don't replace them.
additional = [
  # "*myserver*secret*",
]

# Allowlist — tools matching these patterns are always stored,
# even if they match a deny pattern. Use when a legitimate tool
# is blocked by a keyword pattern (e.g. *token* blocking your
# analytics tool).
allowlist = [
  # "mcp__myservice__list_authors",
]

# Replace built-in defaults entirely (use sparingly).
# Must re-specify any defaults you still want.
override_defaults = [
  # "mcp__recall__*",
  # "mcp__1password__*",
]

[profiles]
# Manifest signature verification mode when installing/updating community profiles.
# Requires the gh CLI. Options: "warn" (default), "error", "skip".
verify_signature = "warn"

Session days

The expire_after_session_days setting counts days you actively use Claude Code on this project — not calendar days. If you work on a task on Monday, leave for a week, and come back the following Tuesday, your stored context is still exactly as you left it. The counter only advances when you open a session.

This means a 7-day setting gives you 7 working sessions of stored context, regardless of how much calendar time passes between them.

Tools

Ten recall__* tools are available to Claude in every session. The recall__ prefix is the MCP naming convention — it namespaces the tools so Claude knows which plugin owns them. You don't call these yourself; Claude uses them automatically.

→ Full tool reference

Compression handlers

Handlers are selected by tool name, with content-based fallback. Every compressed result includes a header line, ending with a few search: hints — salient terms pulled from the stored content so Claude's first recall__search lands without guessing keywords:

[recall:recall_abc12345 · 56.2KB→299B (99% reduction) · search: "checkout", "sessionToken", "orderId"]

Repeated identical tool calls return a cached header instead of re-compressing:

[recall:recall_abc12345 · cached · 2026-03-01]

The generic JSON handler is intentionally conservative — it keeps structure and marks what was dropped. Correctness matters more than compression ratio.

Credential tools are never stored. Password managers are blocked by explicit name (mcp__1password__*, mcp__bitwarden__*, mcp__lastpass__*, mcp__dashlane__*, mcp__keeper__*, mcp__hashicorp_vault__*, mcp__vault__*, mcp__doppler__*, mcp__infisical__*) because their tool names — get_item, list_logins, vault read — don't contain obvious credential keywords. Keyword patterns catch remaining credential-adjacent names: *secret*, *token*, *password*, *credential*, *api_key*, *access_key*, *private_key*, *signing_key*, *oauth*, *auth_token*, *authenticate*, *env_var*, *dotenv*. Output is also scanned for secret patterns (PEM headers, GitHub PATs, AWS keys, etc.) before any write. If a legitimate tool is blocked by a keyword pattern, add it to denylist.allowlist in your config. See SECURITY.md for details.

Scope

Compression applies to MCP tools and the native Bash built-in.

Claude Code's PostToolUse hook supports output replacement for MCP tools and the Bash tool. mcp-recall intercepts both:

• MCP tools (mcp__*) — all compression handlers apply (Playwright, GitHub, GitLab, filesystem, shell/remote-exec, Linear, Slack, Tavily, database query results, Sentry events, CSV, JSON, generic text)
• Bash — CLI-aware handlers: git diff/git show → file-level summary; git log → 20-commit cap; terraform plan → resource action summary; git status → staged/unstaged counts; package install (npm/bun/yarn/pip) → success/error summary; test runners (pytest/jest/bun test/vitest/go test) → pass/fail counts; docker ps → container list; make/just → target + outcome; everything else → 50-line shell cap with ANSI stripping

The remaining built-in tools — Read, Grep, Glob — do not support output replacement. Their full output enters context directly. If large file reads are your biggest context consumer, consider the filesystem MCP server instead of the built-in Read tool.

Privacy

All stored data lives locally on your machine at ~/.local/share/mcp-recall/. Nothing is sent to any external service. The SQLite database contains full tool outputs — treat it accordingly.

To wipe all stored data for the current project:

recall__forget(all: true, confirmed: true)

Or delete the directory directly:

rm -rf ~/.local/share/mcp-recall/

Error contract

mcp-recall never breaks a tool call. Every failure mode — hook crash, SQLite error, handler exception, timeout, secret detected — degrades gracefully to the original uncompressed output passing through unchanged. The session gets slightly worse context efficiency. It never gets broken.

Troubleshooting

→ Troubleshooting guide

Profile system

Declarative TOML profiles extend compression to any MCP — no TypeScript required. Four profiles ship built in (Jira, Gmail, Context7, Docker), and 18 community profiles cover Stripe, Grafana, Shopify, Datadog, Notion, Teams, and more.

mcp-recall learn                         # auto-generate profiles from your installed MCPs
mcp-recall profiles seed                 # install community profiles for detected MCPs
mcp-recall profiles available            # browse the community catalog with install status
mcp-recall profiles info <name>          # full metadata for any profile (works offline)
mcp-recall profiles install <name>       # install by short name, e.g. "grafana"
mcp-recall profiles retrain              # suggest field additions using your stored data
mcp-recall profiles test <tool>          # apply a profile and show compression result
mcp-recall profiles list                 # show all installed profiles

→ Profiles quickstart · Profile schema · retrain guide · AI profile guide · Contributing a profile

Development

git clone https://github.com/sakebomb/mcp-recall
cd mcp-recall
bun install
bun test

See CONTRIBUTING.md for project structure, workflow, and how to add a new compression handler.

What's next

The easiest way to contribute is a TOML profile — no TypeScript, no clone of this repo needed. If you use an MCP that isn't covered, check the community profiles repo or open a profile request.

TypeScript handlers are welcome for tools with complex, non-JSON output (HTML, DOM trees, binary formats) — see CONTRIBUTING.md.

Changelog

See CHANGELOG.md for the full release history.

License

MIT — see LICENSE