{"id":46231910,"url":"https://github.com/sakebomb/mcp-recall","last_synced_at":"2026-04-08T23:02:02.849Z","repository":{"id":341315487,"uuid":"1169679033","full_name":"sakebomb/mcp-recall","owner":"sakebomb","description":"mcp-recall compresses MCP tool outputs (94 KB → 3.5 KB · 96%) and stores full results in SQLite for retrieval — up to 30x more tool calls per session for heavy MCP workloads.","archived":false,"fork":false,"pushed_at":"2026-04-08T02:36:26.000Z","size":2945,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T04:23:43.230Z","etag":null,"topics":["bun","claude","claude-code","claude-code-plugin","context-window","mcp","sqlite","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sakebomb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T03:21:14.000Z","updated_at":"2026-04-08T02:36:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sakebomb/mcp-recall","commit_stats":null,"previous_names":["sakebomb/mcp-recall"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/sakebomb/mcp-recall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakebomb%2Fmcp-recall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakebomb%2Fmcp-recall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakebomb%2Fmcp-recall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakebomb%2Fmcp-recall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sakebomb","download_url":"https://codeload.github.com/sakebomb/mcp-recall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakebomb%2Fmcp-recall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31577448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","claude","claude-code","claude-code-plugin","context-window","mcp","sqlite","typescript"],"created_at":"2026-03-03T18:06:26.085Z","updated_at":"2026-04-08T23:02:02.842Z","avatar_url":"https://github.com/sakebomb.png","language":"TypeScript","readme":"# mcp-recall\n\n[![CI](https://github.com/sakebomb/mcp-recall/actions/workflows/ci.yml/badge.svg)](https://github.com/sakebomb/mcp-recall/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/mcp-recall.svg)](https://www.npmjs.com/package/mcp-recall)\n[![npm downloads](https://img.shields.io/npm/dw/mcp-recall.svg)](https://www.npmjs.com/package/mcp-recall)\n![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)\n![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-f472b6.svg)\n![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)\n![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin-orange.svg)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n**Your context window is finite. MCP tool outputs aren't. mcp-recall bridges the gap.**\n\nMCP tool outputs — Playwright snapshots, GitHub issues, file reads — 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.\n\nSessions that used to hit context limits in 30 minutes routinely run for 3+ hours.\n\n![mcp-recall demo](demo/demo.gif)\n\n---\n\n## The full context stack\n\nContext pressure builds at four distinct layers. mcp-recall targets the two that nothing else handles.\n\n```mermaid\nflowchart TD\n    A([\"Claude session begins\"]) --\u003e B\n\n    B[\"① Tool definitions loaded into context\\n~500 tokens × every connected tool\"]\n    B --\u003e|\"Claude Code Tool Search · Switchboard\\ndefer unused schemas\"| C\n\n    C[\"② Claude calls tools in sequence\"]\n    C --\u003e|\"Code Mode · FastMCP 3.1\\nrun script in sandbox, no intermediate results\"| D\n\n    D[\"③ Tool returns large output\\n50–85 KB per call\"]\n    D --\u003e|\"mcp-recall\\ncompresses to ~300 B, stores in SQLite\"| E\n\n    E[\"④ Session ends\"]\n    E --\u003e|\"mcp-recall\\npersists across sessions via FTS index\"| F([\"Next session: clean context\"])\n```\n\n| Layer | Problem | Solution |\n|---|---|---|\n| **① Tool definitions** | Every connected MCP loads its full schema upfront (~500 tokens/tool) | [Claude Code Tool Search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) (built-in) · Switchboard |\n| **② Intermediate results** | Multi-step workflows pass each result back through context | [Code Mode](https://blog.cloudflare.com/code-mode/) · [FastMCP 3.1](https://www.jlowin.dev/blog/fastmcp-3-1-code-mode) |\n| **③ Single-tool outputs** | One snapshot or API response dumps 50–85 KB | **mcp-recall** |\n| **④ Cross-session memory** | Useful context disappears when the session ends | **mcp-recall** |\n\nLayers ① and ② have solid first-party and community solutions. mcp-recall focuses on ③ and ④ — the outputs that do land in context, and the knowledge that shouldn't vanish when the session ends. All four layers stack: run them together for maximum efficiency.\n\n---\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[\"MCP tool output\\n(e.g. 56 KB snapshot)\"] --\u003e|\"PostToolUse hook\"| B([\"mcp-recall\"])\n    B --\u003e|\"~300 B summary\"| C[\"Claude's context\"]\n    B --\u003e|\"full content + FTS index\"| D[(\"SQLite\")]\n    D \u003c--\u003e|\"recall__retrieve · recall__search\"| C\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eDetailed pipeline\u003c/summary\u003e\n\n```mermaid\nflowchart TD\n    A[\"MCP tool response\u003cbr/\u003e(e.g. 56 KB snapshot)\"] --\u003e B[PostToolUse hook]\n\n    subgraph SEC[\"Security checks\"]\n        DENY[denylist match?]\n        SCRT[secret detected?]\n    end\n\n    B --\u003e DENY\n    DENY -- yes --\u003e P1([skip: passes through unchanged])\n    DENY -- no --\u003e SCRT\n    SCRT -- yes --\u003e P2([skip + warn: passes through unchanged])\n    SCRT -- no --\u003e DEDUP_N\n\n    subgraph DEDUP[\"Dedup check\"]\n        DEDUP_N[\"sha256(name+input)\"]\n    end\n\n    DEDUP_N -- \"cache hit\" --\u003e CACHED([\"[cached] header\"])\n    DEDUP_N -- miss --\u003e HAND_N\n\n    subgraph HANDLER[\"Compression handler (TOML profile first)\"]\n        HAND_N[\"Playwright · GitHub · GitLab · Shell\u003cbr/\u003eLinear · Slack · Tavily · Database\u003cbr/\u003eSentry · Filesystem · CSV · JSON · Text\"]\n    end\n\n    HAND_N --\u003e CTX[\"Context\u003cbr/\u003e299 B summary + recall header\"]\n    HAND_N --\u003e DB_N\n\n    subgraph DB[\"SQLite store\"]\n        DB_N[\"full content (56 KB) · summary (299 B)\u003cbr/\u003eFTS index · access tracking · session days\"]\n    end\n\n    DB_N --\u003e TOOLS[\"recall__* tools\u003cbr/\u003eretrieve · search · pin · note\u003cbr/\u003estats · session_summary · list · forget · export · context\"]\n```\n\n\u003c/details\u003e\n\n**Two hooks, one MCP server.**\n\n- `SessionStart` hook — records each active day, prunes expired items, and injects a compact context snapshot before the first message\n- `PostToolUse` hook — intercepts MCP tool outputs and native Bash commands; deduplicates identical calls; compresses, stores, and returns summary\n- `recall` MCP server — exposes ten tools for retrieval, search, memory, and management\n\n\u003e **Scope**: Compression applies to MCP tools and the native `Bash` built-in. The remaining built-ins (Read, Grep, Glob) pass through unchanged. See [Scope](#scope) for details.\n\n---\n\n## Results\n\nReal numbers from actual tool calls:\n\n| Tool | Original | Delivered | Reduction |\n|---|---|---|---|\n| `mcp__playwright__snapshot` | 56.2 KB | 299 B | 99.5% |\n| `mcp__github__list_issues` (20 items) | 59.1 KB | 1.1 KB | 98.1% |\n| `mcp__filesystem__read_file` (large file) | 85.0 KB | 2.2 KB | 97.4% |\n| Analytics CSV (500 rows) | 85.0 KB | 222 B | 99.7% |\n| Tavily web extracts (12 calls, one session) | 170.3 KB | 2.0 KB | 99% |\n\nAcross a full session: 315 KB of tool output → 5.4 KB delivered to context.\n\nUsed daily in development of this project for over 40 days across 9 releases. No broken sessions, no data loss.\n\n---\n\n## Install\n\n→ **[Quickstart guide](docs/quickstart.md)** — get up and running in 2 minutes.\n\n### Prerequisites\n\n- [Claude Code](https://claude.ai/claude-code) installed\n- [Bun](https://bun.sh) installed — `curl -fsSL https://bun.sh/install | bash`\n\n### Option A — npm (recommended)\n\nNo global install required — run directly with npx or bunx:\n\n```bash\nnpx mcp-recall install   # or: bunx mcp-recall install\n```\n\nOr install globally for faster subsequent runs:\n\n```bash\nbun add -g mcp-recall    # or: npm i -g mcp-recall\nmcp-recall install       # register hooks + MCP server in Claude Code\nmcp-recall status        # verify\n```\n\n`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.\n\nUpdate: `bun update -g mcp-recall \u0026\u0026 mcp-recall install`\n\nUninstall: `mcp-recall uninstall \u0026\u0026 bun remove -g mcp-recall`\n\n### Option B — Claude Code plugin marketplace\n\n```bash\nclaude plugin marketplace add mcp-recall https://github.com/sakebomb/mcp-recall\nclaude plugin install mcp-recall@mcp-recall\n```\n\nBoth hooks and the MCP server register automatically. Verify with `claude --debug`.\n\n### Option C — from source\n\n```bash\ngit clone https://github.com/sakebomb/mcp-recall\ncd mcp-recall\nbun install\nbun run build\n./bin/recall install\n```\n\nThe `mcp-recall` binary is not on PATH for source installs. Add an alias so the CLI works everywhere:\n\n```bash\necho 'alias mcp-recall=\"bun /path/to/mcp-recall/plugins/mcp-recall/dist/cli.js\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\nOr symlink it:\n\n```bash\nln -sf /path/to/mcp-recall/plugins/mcp-recall/dist/cli.js ~/.local/bin/mcp-recall\n```\n\n---\n\n## Updating\n\n### Option A — npm / bun global install\n\n```bash\nbun update -g mcp-recall \u0026\u0026 mcp-recall install\n```\n\n`mcp-recall install` is idempotent — it updates hook paths and the MCP server entry in place without touching your stored data or config.\n\n### Option B — Claude Code plugin marketplace\n\n```bash\nclaude plugin update mcp-recall@mcp-recall\n```\n\n### Option C — from source\n\n```bash\ngit pull\nbun install\nbun run build\nmcp-recall install   # re-registers hooks with the new binary path\n```\n\n### After updating\n\nRun `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:\n\n```bash\nmcp-recall profiles update\n```\n\n---\n\n## Profiles\n\nProfiles teach mcp-recall how to compress output from specific MCPs. Four profiles ship built in (Jira, Gmail, Context7, Docker). **[18 community profiles](https://github.com/sakebomb/mcp-recall-profiles)** cover Grafana, Shopify, Notion, and more.\n\n```bash\n# Install profiles for all your connected MCPs\nmcp-recall profiles seed\n\n# Or install the full community catalog at once\nmcp-recall profiles seed --all\n\n# See what's available in the community catalog (add --verbose for MCP URLs)\nmcp-recall profiles available\n\n# See what's installed (accepts short names: \"grafana\" not \"mcp__grafana\")\nmcp-recall profiles list\n\n# Get full metadata for a profile (manifest-first, falls back to local data offline)\nmcp-recall profiles info grafana\n\n# Keep profiles up to date\nmcp-recall profiles update\n```\n\n→ [Profiles quickstart](docs/profiles-quickstart.md) · [Profile schema](docs/profile-schema.md) · [Community catalog](https://github.com/sakebomb/mcp-recall-profiles)\n\n---\n\n## Configuration\n\nmcp-recall works out of the box. To customize, create `~/.config/mcp-recall/config.toml`:\n\n```toml\n[store]\n# Days of actual Claude Code use before stored items expire.\n# Vacations and context switches to other projects don't count —\n# only days you actively used Claude Code on this project.\n# See \"Session days\" below.\nexpire_after_session_days = 30\n\n# How to identify a project.\n# \"git_root\" is recommended — stable regardless of launch directory.\n# Falls back to \"cwd\" if not inside a git repo.\nkey = \"git_root\"\n\n# Hard cap on store size in megabytes. Least-frequently-accessed\n# non-pinned items are evicted when this limit is exceeded.\nmax_size_mb = 500\n\n# Access count threshold for pin suggestions in recall__stats.\n# Items accessed at least this many times will appear as pin candidates.\npin_recommendation_threshold = 5\n\n# Days since creation before a never-accessed item appears as a stale candidate\n# in recall__stats. Helps identify stored output that was never retrieved.\nstale_item_days = 3\n\n[retrieve]\n# Max bytes returned by recall__retrieve() when no query is provided.\n# Claude can override this per-call via the max_bytes parameter.\ndefault_max_bytes = 8192\n\n[denylist]\n# Additional tool name glob patterns to never store.\n# These extend the built-in defaults — they don't replace them.\nadditional = [\n  # \"*myserver*secret*\",\n]\n\n# Allowlist — tools matching these patterns are always stored,\n# even if they match a deny pattern. Use when a legitimate tool\n# is blocked by a keyword pattern (e.g. *token* blocking your\n# analytics tool).\nallowlist = [\n  # \"mcp__myservice__list_authors\",\n]\n\n# Replace built-in defaults entirely (use sparingly).\n# Must re-specify any defaults you still want.\noverride_defaults = [\n  # \"mcp__recall__*\",\n  # \"mcp__1password__*\",\n]\n\n[profiles]\n# Manifest signature verification mode when installing/updating community profiles.\n# Requires the gh CLI. Options: \"warn\" (default), \"error\", \"skip\".\nverify_signature = \"warn\"\n```\n\n### Session days\n\nThe `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.\n\nThis means a 7-day setting gives you 7 working sessions of stored context, regardless of how much calendar time passes between them.\n\n---\n\n## Tools\n\nTen `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.\n\n| Tool | Use when |\n|---|---|\n| `recall__context` | Start of session — get pinned items, notes, and recent activity |\n| `recall__retrieve(id, query?)` | Need detail from a prior tool call |\n| `recall__search(query, tool?)` | Find stored output by content, no ID needed |\n| `recall__pin(id)` | Protect an item from expiry and eviction |\n| `recall__note(text, title?)` | Store a conclusion or decision as project memory |\n| `recall__stats()` | Session efficiency report with savings and suggestions |\n| `recall__session_summary(date?)` | Digest of a specific session's activity |\n| `recall__list_stored(sort?, tool?)` | Browse stored items |\n| `recall__forget(...)` | Delete by id, tool, session, age, or all |\n| `recall__export()` | JSON dump of all stored items |\n\n→ [Full tool reference](docs/tools.md)\n\n---\n\n## Compression handlers\n\nHandlers are selected by tool name, with content-based fallback. Every compressed result includes a header line:\n\n```\n[recall:recall_abc12345 · 56.2KB→299B (99% reduction)]\n```\n\nRepeated identical tool calls return a cached header instead of re-compressing:\n\n```\n[recall:recall_abc12345 · cached · 2026-03-01]\n```\n\n| Handler | Matches | Strategy |\n|---|---|---|\n| Bash | native `Bash` tool | CLI-aware routing on `tool_input.command`: `git diff`/`git show` → changed-files summary with per-file +/- stats; `git log` → 20-commit cap; `terraform plan` → resource action symbols + Plan: summary; `git status` → staged/unstaged counts + branch info; `npm`/`bun`/`yarn`/`pip install` → success or error summary (pnpm → shell compression); `pytest`/`jest`/`bun test`/`vitest`/`go test` → pass/fail counts + failure names; `docker ps` → container name/image/status/ports; `make`/`just` → target + outcome; `gh` → list output compressed to count + first 10 rows, check output to pass/fail summary, view output to key-value metadata; JSON stdout (any command) → JSON handler; everything else → shell handler. |\n| Playwright | tool name contains `playwright` and `snapshot` | Interactive elements (buttons, inputs, links), visible text, headings. Drops aria noise. |\n| GitHub | `mcp__github__*` | Number, title, state, body (200 chars), labels, URL. Lists: first 10 + overflow count. |\n| GitLab | `mcp__gitlab__*` | IID, title, state, description excerpt (200 chars), labels, web URL. Lists: first 10 + overflow count. |\n| Stripe | `mcp__stripe__*` | Amount formatting (smallest currency unit, zero-decimal currencies like JPY/KRW handled separately), per-tool routing: customers, invoices, payment intents, subscriptions, products, prices, disputes, payment links, balance, account. |\n| Shell | tool name contains `bash`, `shell`, `terminal`, `run_command`, `ssh_exec`, `exec_command`, `remote_exec`, or `container_exec` | Strips ANSI escape codes and SSH post-quantum advisory noise. Parses structured `{stdout, stderr, returncode}` JSON; falls back to plain text. JSON stdout is routed through the JSON handler. Stdout: first 25 lines + overflow count. Stderr: first 20 lines, shown in a separate section. Exit code in header. |\n| Linear | tool name contains `linear` | Identifier, title, state, priority (numeric → label), description excerpt (200 chars), URL. Handles single, array, GraphQL, and Relay shapes. |\n| Slack | tool name contains `slack` | Channel, formatted timestamp, user/display name, message text (200 chars). Handles `{ok, messages}` wrappers and bare arrays. Lists: first 10 + overflow count. |\n| Tavily | tool name contains `tavily` | Query header, synthesized answer in full, per-result title + URL + 150-char content snippet. Drops `raw_content`, `score`, `response_time`. Lists: first 10 + overflow count. |\n| Database | tool name contains `postgres`, `mysql`, `sqlite`, or `database` | Row/column count header, column names, first 10 rows as col=value pairs. Handles node-postgres `{rows, fields}`, bare array, and `{results}` wrapper shapes. |\n| Sentry | tool name contains `sentry` | Exception type + message, level, environment, release, event ID. Last 8 stack frames (innermost/most relevant). Drops breadcrumbs, SDK info, request headers. |\n| Filesystem | `mcp__filesystem__*` or tool name contains `read_file` / `get_file` | Line count header + first 50 lines + truncation notice. |\n| CSV | tool name contains `csv`, or content-based detection | Column headers + first 5 data rows as key=value pairs + row/col count. Handles quoted fields. |\n| Generic JSON | Any unmatched tool with JSON output | 3-level depth limit, arrays capped at 3 items with overflow count. |\n| Generic text | Everything else | First 500 chars + ellipsis. |\n\nThe generic JSON handler is intentionally conservative — it keeps structure and marks what was dropped. Correctness matters more than compression ratio.\n\nCredential 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](SECURITY.md) for details.\n\n---\n\n## Scope\n\n**Compression applies to MCP tools and the native Bash built-in.**\n\nClaude Code's `PostToolUse` hook supports output replacement for MCP tools and the `Bash` tool. mcp-recall intercepts both:\n\n- **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)\n- **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\n\nThe 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](https://github.com/modelcontextprotocol/servers) instead of the built-in Read tool.\n\n---\n\n## Privacy\n\nAll 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.\n\nTo wipe all stored data for the current project:\n\n```\nrecall__forget(all: true, confirmed: true)\n```\n\nOr delete the directory directly:\n\n```bash\nrm -rf ~/.local/share/mcp-recall/\n```\n\n---\n\n## Error contract\n\nmcp-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.\n\n---\n\n## Troubleshooting\n\n→ [Troubleshooting guide](docs/troubleshooting.md)\n\n---\n\n## Profile system\n\nDeclarative TOML profiles extend compression to any MCP — no TypeScript required. Four profiles ship built in (Jira, Gmail, Context7, Docker), and **[18 community profiles](https://github.com/sakebomb/mcp-recall-profiles)** cover Stripe, Grafana, Shopify, Datadog, Notion, Teams, and more.\n\n```bash\nmcp-recall learn                         # auto-generate profiles from your installed MCPs\nmcp-recall profiles seed                 # install community profiles for detected MCPs\nmcp-recall profiles available            # browse the community catalog with install status\nmcp-recall profiles info \u003cname\u003e          # full metadata for any profile (works offline)\nmcp-recall profiles install \u003cname\u003e       # install by short name, e.g. \"grafana\"\nmcp-recall profiles retrain              # suggest field additions using your stored data\nmcp-recall profiles test \u003ctool\u003e          # apply a profile and show compression result\nmcp-recall profiles list                 # show all installed profiles\n```\n\n→ [Profiles quickstart](docs/profiles-quickstart.md) · [Profile schema](docs/profile-schema.md) · [retrain guide](docs/retrain.md) · [AI profile guide](docs/ai-profile-guide.md) · [Contributing a profile](CONTRIBUTING.md#contributing-a-profile)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/sakebomb/mcp-recall\ncd mcp-recall\nbun install\nbun test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for project structure, workflow, and how to add a new compression handler.\n\n---\n\n## What's next\n\nThe 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](https://github.com/sakebomb/mcp-recall-profiles) or open a [profile request](https://github.com/sakebomb/mcp-recall/issues/new?template=profile-request.md).\n\nTypeScript handlers are welcome for tools with complex, non-JSON output (HTML, DOM trees, binary formats) — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full release history.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsakebomb%2Fmcp-recall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsakebomb%2Fmcp-recall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsakebomb%2Fmcp-recall/lists"}