Persistent memory for Claude Code with native Skills integration, automatic capture, failure learning, and project scoping via MCP server
npm install claude-recallClaude Recall is a local memory engine + MCP server that gives Claude Code something it's missing by default:
the ability to learn from you over time.
Your preferences, project structure, workflows, corrections, and coding style are captured automatically and applied in future sessions — securely stored on your machine.
> TL;DR
> Claude Recall stores and searches your past preferences and project knowledge.
> Install it → restart Claude Code → Claude knows when to search memory via native Skills integration.
---
- Continuous Learning — captures coding patterns, tool preferences, corrections, architectural decisions, and workflow habits in local SQLite
- Native Claude Skills — no hooks required; Claude decides when to search/store based on built-in skill guidance
- User-Confirmed Storage — Claude asks for your permission before storing any memory
- Project-Scoped Knowledge — each project gets its own memory namespace; switch projects and Claude switches memory
- Failure Learning — captures failures with counterfactual reasoning (what failed, why, what to do instead)
- Memory Evolution — tracks agent progression over time across sophistication levels (L1–L4)
- Zero Cloud Storage — all memory stored locally, no telemetry, works fully offline
- Process Management — automatic server lifecycle management with stale process cleanup
---
| Component | Version | Notes |
| --------- | ----------------------- | --------------------------- |
| Node.js | 20+ | required for better-sqlite3 |
| OS | macOS / Linux / Windows | WSL supported |
``bash
cd your-project
npm install claude-recall
$3
Register MCP server with Claude Code:
bash
claude mcp add claude-recall -- npx -y claude-recall@latest mcp start
`Then restart your terminal or Claude Code session.
Already registered? Remove first:
bash
claude mcp remove claude-recall
`$3
In Claude Code, ask: "Load my rules"
Claude should call
. If it works, you're ready.$3
`bash
npm uninstall claude-recall && npm install claude-recall
`---
How It Works
Claude Recall has three layers:
$3
Stores and evolves preferences, patterns, decisions, corrections, and failure learnings. Uses WAL mode for concurrency, content-hash deduplication, and automatic compaction.
$3
Exposes two tools to Claude Code:
| Tool | Purpose |
| ---- | ------- |
|
| Load all active rules (preferences, corrections, failures, devops) at the start of a task |
| store_memory | Save new knowledge — preferences, corrections, devops rules, failures |$3
Installed automatically to
.claude/skills/memory-management/SKILL.md. Teaches Claude:
- Load rules before writing/editing code
- Apply learned conventions and avoid past mistakes
- Ask the user for confirmation before storing any memory
- Capture corrections when users fix mistakes
- Store learning cycles (fail → fix → success)---
CLI Reference
$3
`bash
npx claude-recall stats # Memory statistics
npx claude-recall search "query" # Search memories
npx claude-recall store "content" # Store memory directly
npx claude-recall export backup.json # Export memories to JSON
npx claude-recall import backup.json # Import memories from JSON
npx claude-recall clear --force # Clear all memories
`$3
bash
npx claude-recall evolution # Memory evolution metrics (L1-L4)
npx claude-recall evolution --days 60 # Custom time window
npx claude-recall failures # View failure memories
npx claude-recall failures --limit 20 # Limit results
npx claude-recall monitor # Memory search monitoring stats
`$3
bash
npx claude-recall mcp status # Current project's server status
npx claude-recall mcp ps # List all running servers
npx claude-recall mcp stop # Stop server
npx claude-recall mcp stop --force # Force stop
npx claude-recall mcp restart # Restart server
npx claude-recall mcp cleanup # Remove stale PID files
npx claude-recall mcp cleanup --all # Stop all servers
`$3
bash
npx claude-recall project show # Current project info
npx claude-recall project list # All registered projects
npx claude-recall project register # Register current project
npx claude-recall project clean # Remove stale registry entries
`$3
bash
npx claude-recall setup # Show activation instructions
npx claude-recall status # Installation and system status
npx claude-recall repair # Clean up old hooks, install skills
`---
How Project Scoping Works
Each project gets isolated memory based on its working directory:
- Project ID is derived from the
that Claude Code passes to the MCP server
- Universal memories (no project scope) are available everywhere
- Project memories are only returned when working in that project
- Switching projects switches memory automatically — no configuration neededDatabase location:
~/.claude-recall/claude-recall.db (shared file, scoped by project_id column).---
WSL Users
If you hit "invalid ELF header" errors from mixed Windows/WSL
node_modules, use a global install:`bash
From WSL:
npm install -g claude-recallUpdate ~/.claude.json to use the global binary:
{
"claude-recall": {
"type": "stdio",
"command": "claude-recall",
"args": ["mcp", "start"],
"env": {}
}
}
`Global installation does not affect project scoping — project ID is still detected from Claude Code's working directory.
---
Security & Privacy
- SQLite memory never leaves your machine
- No external services required
- No prompts, code, or memory content is transmitted
- Full transparency via CLI (
, search, export)
- Never stores secrets (API keys, passwords, tokens)Details in docs/security.md.
---
Documentation
/docs:- Installation
- Quickstart
- CLI Reference
- Memory Types
- Learning Loop
- Project Scoping
- Content Hashing
- Troubleshooting
- Security
- FAQ
---
Development & Contributions
PRs welcome — Claude Recall is open to contributors.
`bash
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.