Power your agent
The publisher's own command. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code has no install link for a local command. Copy the command below and run it in a terminal.
claude mcp add claude-recall -- npx -y claude-recall@0.47.0Run in a terminal.
{ "mcpServers": { "claude-recall": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
Coding agents forget everything between sessions. Claude Recall fixes that: it captures your preferences, corrections, project facts, and failures automatically as you work, stores them in a local SQLite database, and injects them back into the agent's context in every future session.
Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping
It works with Claude Code, Pi, and Kiro CLI — all three share the same database, so a rule learned in one agent is applied in the others. Everything stays on your machine: no cloud, no telemetry, works offline.
Jump to: Quick Start · In practice · vs. CLAUDE.md · What runs automatically · Commands · How it works · Upgrading · Configuration · Security
Tuesday — you correct the agent once, in plain language:
You: use pnpm here, not npm
Seconds later, silently in the background (~/.claude-recall/hook-logs/cc-classifier.log):
classified via claude -p (model=haiku, Claude subscription, no API key): correction — Use pnpm, not npm
That's the whole workflow. A background hook classified your prompt with an LLM — the agent's own LLM (your Claude subscription under Claude Code, Kiro's credits under Kiro; no API key involved) — decided it was a durable rule and stored it locally. No "remember this" incantation, no tool call, no config file to edit.
Friday — brand-new session, no shared history:
You: set up a test runner for this project
Agent: Installing vitest with pnpm (applied from memory: "Use pnpm, not npm") …
Your rules are injected at session start and kept alive mid-session — just-in-time before each relevant tool call (Claude Code, Pi), or as a periodic refresh (Kiro) — at the moment of decision, not 50,000 tokens upstream. This works across agents too: correct Claude Code on Tuesday, and Kiro applies it on Friday.
And you can audit what it knows at any time:
$ claude-recall search "pnpm"
🔍 Found 1 memories (showing top 1):
1. [correction] Score: 7.9
Content: {"content":"Use pnpm, not npm","confidence":0.95,"source":"hook-auto-capture",...}
Requirements: Node.js 20.19+, macOS / Linux / Windows (WSL supported).
Install the global binary once:
npm install -g claude-recall
Do NOT add claude-recall as a project dependency (
npm install claude-recallinside a project). All projects share one database, and a stale project-local copy silently shadows your global one. One global binary; per-project activation only. HitEACCES: permission denied? See Upgrade & install troubleshooting below.
Using nvm? A global install lives under the active Node version, so switching Node versions hides it (
claude-recall: command not found, and hooks stop firing). Make it stick across versions once:echo 'claude-recall' >> ~/.nvm/default-packages # every future `nvm install` includes it
claude-recall doctorflags a version-orphaned install and how to fix it. Works in your terminal but not in the Claude desktop app or an IDE? See nvm: "Executable not found" in Install & upgrade troubleshooting below.
Install once — active in every project (recommended):
claude-recall setup --install --global # hooks → ~/.claude (every project)
claude mcp add --scope user claude-recall -- claude-recall mcp start
Restart Claude Code and you're done — every project, current and future, has memory with nothing more to run. Memories still scope per project automatically (isolation comes from the working directory, not the install). Ask "Load my rules" to verify — Claude should call load_rules.
Or activate a single project only (hooks + MCP scoped to this directory):
claude-recall setup --install # hooks → ./.claude
claude mcp add claude-recall -- claude-recall mcp start
Already set up per-project and tired of repeating it? Run the global pair above once, then
claude-recall doctor --fix— it repairs any stale config and removes the now-redundant per-project hooks for you (preserving your own hooks). One command cleans up a messy machine.
Capture runs on your Claude subscription — no API key. The capture hook classifies each prompt via a headless claude -p call on the same login that powers your session, in a detached background worker (your turn is never blocked; capture is silent and lands a few seconds later). If you happen to have ANTHROPIC_API_KEY exported for other tools, it is deliberately not used unless you set CLAUDE_RECALL_PREFER_API_KEY=1 — a stray key shouldn't quietly spend your Anthropic API credits. Verify captures any time:
tail -5 ~/.claude-recall/hook-logs/cc-classifier.log # which model ran, what was stored
claude-recall search "something you said"
Design details (the claude -p key-precedence gotcha, recursion guards, which features run on the subscription): docs/cc-llm-capture.md.
pi install npm:claude-recall
That's it. Ask Pi to "Load my rules" to verify.
Requires claude-recall ≥ 0.28.0. In the project directory, before starting Kiro:
claude-recall kiro setup # writes a custom agent at .kiro/agents/recall.json
kiro # then inside the chat: /agent swap recall
Already living in a custom agent of your own? Merge Claude Recall into it instead of swapping (backup written, idempotent, your config preserved):
claude-recall kiro setup --merge-into <agent-name>
⚠️ You must start ONE fresh conversation after setup — this is the most common reason "it does nothing."
After
kiro setupor--merge-into, start one new conversation without--resume:kiro-cli chat --agent recall # or: --agent <your-agent> if you mergedKiro snapshots the agent config at the moment a conversation is created. Any conversation that already existed — including one you reach with
--resumeor after restarting Kiro — was snapshotted before claude-recall was wired in, so it will never run the hooks and capture will silently do nothing. Once you've started that one fresh conversation, every conversation from then on carries the hooks and--resumeworks normally. This is a one-time rollover, once per project.Confirm the wiring is live before you rely on it:
claude-recall kiro doctor # green checks = hooks are active for this project
Capture runs on Kiro's own LLM — no API key, no personal subscription. It classifies each prompt with a dedicated fixed model (default claude-haiku-4.5, independent of your chat model) and costs ~0.06 Kiro credits per prompt — cheap, but note it's every prompt, so budget accordingly across a team.
What to expect from capture — read this so it doesn't feel broken:
Word your rules precisely — under Kiro this matters more. Claude Code and Pi re-surface relevant rules right beside each tool call; Kiro has no channel for that, so rules act from a distance (session start + a refresh every 15 prompts). A vague rule tends to get overlooked mid-task; one that names the trigger and the concrete pattern gets applied. Real example, same session:
dummy_email.txt anywayemail_*.txt" → agent named it correctly and cited the rule while doing itTo verify capture actually worked — from a second terminal (Kiro's chat can't shell out):
claude-recall search "pnpm" # did the rule land?
tail -5 ~/.claude-recall/hook-logs/kiro-classifier.log # what the classifier decided, and which model ran
Or, from inside the Kiro session, just ask the agent to recall it ("what do you remember about my package manager?") — it reads the same DB and will surface the stored rule if capture succeeded.
Everything else Kiro — MCP-only mode, project scoping and --resume, the classifier internals, enterprise-governance notes, troubleshooting: docs/kiro.md.
Use them! They're the right tool for team standards you already know — written by hand, reviewed in PRs, shipped with the repo. Claude Recall covers what they structurally can't:
In short: steering files are documentation — what your team decided. Claude Recall is memory — what your sessions taught.
Once installed, Claude Recall works in the background (CC = Claude Code):
Classification runs on each runtime's own LLM — Claude Code via headless claude -p on your subscription; Kiro via kiro-cli chat --no-interactive on Kiro credits — with regex as the fallback. An exported ANTHROPIC_API_KEY is never touched unless you explicitly opt in with CLAUDE_RECALL_PREFER_API_KEY=1. No API key is ever required; no configuration needed.
Captured rules are kept precise and current: the classifier phrases each rule as trigger + concrete pattern where your message allows ("email files must start with email" → "When creating an email text file, name it email_*.txt"); a rule too vague to act on is stored but flagged, and the agent is nudged at injection time to ask you for a precise restatement. When you restate an existing rule in new words, the new phrasing supersedes the old row (counters carry over) instead of creating a duplicate or being swallowed by the old wording.
You'll see it's on. The work happens in background hooks, so Claude Recall surfaces a persistent visible signal: a statusLine indicator — 🧠 Recall · N rules · <project> — pinned at the bottom of the Claude Code terminal for the whole session. setup --install adds it automatically (and never clobbers an existing statusLine — if you have one, add claude-recall statusline to it). After a compaction you'll also see a 🔄 Recall: N rules re-loaded line. For anything deeper, claude-recall doctor gives a full health verdict.
# Verify it's working
claude-recall doctor # full health check (install, config, hooks, server, DB)
claude-recall stats
claude-recall search "preference"
claude-recall status # Installation health: hooks, MCP, DB path, project ID
claude-recall stats # What's in the DB for this project (--global for all)
claude-recall list # List all memories, newest first (-t <type>, --all, --json, --global)
claude-recall search "query" # Search this project's memories (--global, --json, --project <id>)
claude-recall failures # What broke and what fixed it
claude-recall outcomes # Outcome-aware learning status
claude-recall store "content" # Store a memory by hand (-t correction|devops|...)
claude-recall delete <key> # Delete one memory (keys shown by search)
claude-recall export backup.json # Export to JSON (import to restore)
claude-recall clear --force # Wipe this project's memories (auto-backup first)
claude-recall upgrade # Update the global binary for all runtimes
Persistent "where I left off" snapshots — one per project, replaced on each save:
claude-recall checkpoint save --completed "API layer" --remaining "wire the UI" --blockers "none"
claude-recall checkpoint load
Auto-checkpoints are also saved on session exit in Claude Code and Pi (Pi has no --resume, so this is its main recovery path). Extraction runs on your Claude subscription (headless claude -p) — like capture, no API key needed and no key touched. The same applies to the other background LLM features (failure hindsight hints, end-of-session lesson extraction). Pi-only machines without the claude binary can opt in to an ANTHROPIC_API_KEY with CLAUDE_RECALL_PREFER_API_KEY=1. A quality gate refuses to overwrite a manual checkpoint with a fabricated one when the task was already complete.
claude-recall doctor # One-shot health check: install, MCP config, hooks, live server, DB
claude-recall doctor --fix # Repair MCP-config drift + rewrite orphaned/broken hook paths (backups first)
claude-recall status # Are hooks + MCP registered? Which project is this?
claude-recall hooks check # Do the hook files exist and validate?
claude-recall mcp status # Is the MCP server running? (mcp ps lists all)
claude-recall project show # Which project ID does this directory map to?
claude-recall repair # Fix broken hook paths (--dry-run to preview)
claude-recall mcp cleanup --all # Stop stale MCP servers
# What did the hooks actually do?
tail -20 ~/.claude-recall/hook-logs/hook-dispatcher.log
# "error: unknown command '<x>'" → your binary predates the feature:
claude-recall upgrade
# ── Setup & Diagnostics ─────────────────────────────────────────────
claude-recall setup # Show activation instructions
claude-recall setup --install # Install skills + hooks (Claude Code, current project)
claude-recall kiro setup # Write Kiro custom agent (--global for all projects)
claude-recall kiro setup --merge-into <agent> # Merge into an existing Kiro agent
claude-recall kiro doctor # Kiro integration health report
claude-recall doctor # Health check: install, MCP config, hooks, live server, DB (--fix repairs config + hooks)
claude-recall statusline # One-line memory indicator for Claude Code's settings.json "statusLine" (added by setup)
claude-recall upgrade # One-shot upgrade: global binary + clear stale MCP servers
claude-recall status # Installation and system status
claude-recall repair # Fix broken claude-recall hook paths (preserves your customizations)
claude-recall repair --auto # Non-interactive; apply safe fixes without prompting
claude-recall repair --dry-run # Report what would change without writing
claude-recall repair --scope user|project|all # Scope the scan (default: all)
claude-recall repair --reinstall-hooks # Opinionated: rewrite entire hook block from current template
claude-recall hooks check # Verify hook files exist and are valid
claude-recall hooks test-enforcement # Test if search enforcer hook works
# ── Memory ───────────────────────────────────────────────────────────
claude-recall stats # Memory statistics (--global for all projects)
claude-recall list # List memories, newest first (-t <type>, --all, --json, --global)
claude-recall search "query" # Search memories (--global, --json, --project <id>)
claude-recall store "content" # Store memory directly
claude-recall store "content" -t <type> # Type: preference, correction, failure, devops, project-knowledge, solution
claude-recall export backup.json # Export current project (--global for all)
claude-recall import backup.json # Import memories from JSON
claude-recall delete <key> # Delete one memory by key (get keys from `search`)
claude-recall clear --force # Clear current project (--global for all; auto-backup written first)
claude-recall failures # View failure memories (--limit N)
claude-recall outcomes # Outcome-aware learning status (--section lessons|stats, --limit N)
claude-recall monitor # Memory search monitoring stats
# ── Rule Hygiene ─────────────────────────────────────────────────────
claude-recall rules demote [--dry-run] # Demote rules loaded >=N times but never cited
claude-recall rules demote --min-loads 20 --min-age-days 7 # Tune thresholds
claude-recall rules promote <id> # Restore an auto-demoted or auto-deduped rule
claude-recall rules dedup [--dry-run] # Collapse near-duplicate rules (--threshold 0.8 for stricter)
# ── Task Checkpoints ────────────────────────────────────────────────
claude-recall checkpoint save --completed <text> --remaining <text> [--blockers <text>] [--notes <text>]
claude-recall checkpoint load [--json]
claude-recall checkpoint clear
# ── Skills ───────────────────────────────────────────────────────────
claude-recall skills generate # Generate skills from memories (--dry-run, --force)
claude-recall skills list # List generated skills
claude-recall skills clean --force # Remove all auto-generated skills
# ── MCP Server ───────────────────────────────────────────────────────
claude-recall mcp status # Current project's server status
claude-recall mcp ps # List all running servers
claude-recall mcp stop [--force] # Stop server
claude-recall mcp restart # Stop server (Claude Code respawns it next session)
claude-recall mcp cleanup [--all] # Remove stale PID files / stop all servers
# ── Project ──────────────────────────────────────────────────────────
claude-recall project show # Current project info
claude-recall project list # All registered projects
claude-recall project register # Register current project
claude-recall project unregister [id] # Unregister a project
claude-recall project clean # Remove stale registry entries
# ── Database Maintenance ─────────────────────────────────────────────
claude-recall compact # Dedup + prune + VACUUM (--dry-run to preview; also runs on MCP boot)
claude-recall cleanup test-pollution [--dry-run] # Delete legacy test-fixture rows
# ── Auto-Capture Hooks (run automatically, registered via setup --install) ──
claude-recall hook run correction-detector # UserPromptSubmit hook
claude-recall hook run memory-stop # Stop hook
claude-recall hook run precompact-preserve # PreCompact hook
claude-recall hook run memory-sync # Stop + PreCompact hook (syncs rules to auto-memory)
Six memory tools (load_rules, store_memory, search_memory, delete_memory, save_checkpoint, load_checkpoint) backed by one local SQLite database (~/.claude-recall/claude-recall.db, WAL mode, content-hash dedup, auto-compaction). Exposure per agent:
mcp__claude-recall__* tools) + file-system hooks for automatic capturerecall_* tools) + event handlersSource links. A memory captured by a Claude Code hook records the session, transcript file and transcript entry it came from. It also keeps a copy of the user's text, up to 2,000 chars. search_memory prints the source under the memory, so the agent can read the user's exact words when the one-line extract isn't enough. Claude Code deletes old transcripts (cleanupPeriodDays, 30 days by default); once a transcript is gone, search_memory quotes the saved text instead of the dead path. Memories stored through store_memory, the CLI, Pi or Kiro, and memories captured before 0.46.0, have no source.
Skills. Claude Recall teaches agents when to use memory via skill files — Anthropic's Agent Skills standard for Claude Code (.claude/skills/memory-management/, plus auto-generated .claude/skills/auto-*/ crystallized from accumulated memories), and a bundled skill file for Pi.
Outcome-aware learning. Claude Recall tracks what happens after the agent acts:
action → outcome event → episode → candidate lesson → promotion → active rule
↓
JIT-injected before the next action
↓
outcome resolved per injected rule
Failures become candidate lessons (deduplicated by similarity); lessons seen 2+ times (or once, if severe) are promoted to active rules; every just-in-time injection (Claude Code, Pi) is recorded and resolved against the tool's outcome, building per-rule effectiveness data over time.
Auto-capture is failure-biased by design — it learns from what breaks. But a hard-won success is just as reusable: the command, flag, or sequence you finally landed after several dead ends. Claude Recall captures those as a first-class solution memory, two ways:
store_memory with type: "solution" — the intended home for "I cracked this, don't make me re-derive it."A solution is active immediately (no wait for a second occurrence — you rarely crack the same hard thing twice), injected at every surface alongside your other rules, and ranked just below explicit corrections. List them with claude-recall list --type solution. Unlike other rules, solutions are exempt from the never-cited auto-demote sweep, so a rarely-needed-but-valuable win isn't retired.
Automatic capture inevitably stores some noise — a conversational fragment misfiled as a preference, the same lesson in five wordings, a rule too vague to act on. Counters can flag unused rules (CLAUDE_RECALL_AUTO_DEMOTE), but they can't tell a rarely-cited gem from junk. Once a day, the memory janitor has the runtime's own LLM (same backend policy as capture — your Claude subscription or Kiro credits, never an API key unless you opted in) review the stored rules and:
Guardrails: nothing is ever deleted (demotions are reversible via rules promote <id>, and re-teaching a demoted rule revives it); memories younger than 24h are never reviewed; at most 10 actions per run; malformed LLM output does nothing.
claude-recall janitor --dry-run # preview what it would do
claude-recall janitor # run it now
claude-recall janitor --status # see the last automatic run
Disable with CLAUDE_RECALL_JANITOR=off.
One command upgrades the shared binary for all runtimes:
claude-recall upgrade
It checks the registry, refreshes the global binary, and clears any running MCP servers — they respawn on the next tool call with the new version.
Per-runtime notes:
claude-recall setup --install in each active project (safe any time; a no-op when current).pi update npm:claude-recall and restart Pi.kiro setup once and start one fresh conversation — see docs/kiro.md.EACCES: permission denied — your global npm prefix is root-owned (common when node came from apt). Quick fix: sudo npm install -g claude-recall@latest. Permanent fix — move the prefix to a user-owned directory so global installs never need sudo again:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g claude-recall@latest
claude-recall --version
error: unknown command '<anything>' — your installed binary is older than the docs you're reading (kiro needs ≥ 0.28.0, compact ≥ 0.26.0, upgrade ≥ 0.23.2). Run claude-recall upgrade; if upgrade itself is unknown, bootstrap with npm install -g claude-recall@latest.
Claude Code registered before v0.27.x? Older versions auto-registered the MCP server with an npx-based command, which can be shadowed by stale project-local installs. Switch to the direct binary form (run in each affected project):
claude mcp remove claude-recall
claude mcp add claude-recall -- claude-recall mcp start
WSL: "invalid ELF header" — mixed Windows/WSL node_modules. Use the global install (the default) and verify the binary resolves to a Linux path: which claude-recall should show /home/<user>/..., not a Windows path. Global installation does not affect project scoping.
nvm: "Executable not found" in the Claude desktop app / an IDE, but fine in a terminal — nvm adds Node to PATH only in interactive shells (~/.bashrc). Apps that start Claude Code without one (the Claude desktop app, some IDEs) then can't find claude-recall or node: the MCP server fails with ENOENT: Executable not found in $PATH: "claude-recall" and every hook fails with claude-recall: not found. claude-recall doctor reports this under Launch outside a terminal. Fix: register claude-recall by absolute path through a small wrapper that puts nvm's Node on PATH:
mkdir -p ~/.local/bin
cat > ~/.local/bin/claude-recall-wrap <<'EOF'
#!/bin/sh
# newest nvm Node that has claude-recall; no nvm.sh, so hooks stay fast
for d in $(ls -d "$HOME"/.nvm/versions/node/*/bin 2>/dev/null | sort -V -r); do
if [ -x "$d/claude-recall" ]; then PATH="$d:$PATH"; export PATH; exec "$d/claude-recall" "$@"; fi
done
echo "claude-recall-wrap: claude-recall not found under ~/.nvm" >&2; exit 127
EOF
chmod +x ~/.local/bin/claude-recall-wrap
# check it works without your shell's PATH (as the desktop app sees it)
env -i HOME=$HOME PATH=/usr/bin:/bin ~/.local/bin/claude-recall-wrap --version
Then use the absolute wrapper path (/home/<user>/.local/bin/claude-recall-wrap) instead of claude-recall in the MCP server command (claude mcp remove claude-recall, then claude mcp add --scope user claude-recall -- /home/<user>/.local/bin/claude-recall-wrap mcp start), every hook command in ~/.claude/settings.json (… hook run …), and the statusLine command. Restart Claude Code and re-run claude-recall doctor. From 0.45.0, setup --install and doctor --fix keep the wrapper instead of rewriting it back to claude-recall. The wrapper picks the newest nvm Node that has claude-recall installed, so it keeps working after nvm install as long as claude-recall comes along (see ~/.nvm/default-packages above).
Each project gets isolated memory. The project ID is derived from the working directory the agent reports; universal memories (no project scope) are available everywhere. Switching projects switches memory automatically — no configuration.
To pin one logical project across several directories (worktrees, subrepos), set CLAUDE_RECALL_PROJECT_ID. Details: docs/project-scoping.md.
Defaults work out of the box; tune via environment variables as needed.
~/.claude-recall is private to your user account (0700)claude -p on your Claude login under Claude Code, Kiro's LLM under Kiro, or the Anthropic API only if you opt in with CLAUDE_RECALL_PREFER_API_KEY=1. That's the same provider your session already talks to, but avoid pasting secrets into promptsstats, search, export)Details in docs/security.md.
PRs welcome.
npm run build # Compile TypeScript
npm test # Run all tests
npm run test:watch # Watch mode
npm run mcp:dev # Start MCP server in dev mode
MIT · SPDX MIT · Copyright © 2025-2026 Raoul Biagioni
Free to use, modify and distribute — including commercially and in closed-source work — provided the copyright notice and permission notice are retained. The software is provided "as is", without warranty of any kind. Full text: LICENSE.
Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping
{ "mcpServers": { "claude-recall": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Claude Recall runs locally over stdio.
Last checked 2026-11-14. Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping