ClaudeMemory

Long-term memory for Claude Code - automatic, intelligent, zero-configuration

ClaudeMemory gives Claude Code a persistent memory across all your conversations. It automatically:

• ✅ Extracts durable facts from conversations (tech stack, preferences, decisions)
• ✅ Remembers project-specific and global knowledge
• ✅ Provides instant recall without manual prompting
• ✅ Maintains truth (handles conflicts, supersession)

No API keys. No configuration. Just works.

gem install claude_memory

From within Claude Code, add the marketplace and install the plugin:

# Add the marketplace (one-time setup)
/plugin marketplace add codenamev/claude_memory

# Install the plugin
/plugin install claude-memory

Initialize both global and project-specific memory:

claude-memory init

This creates:

• Global database (~/.claude/memory.sqlite3) - User-wide preferences
• Project database (.claude/memory.sqlite3) - Project-specific knowledge

Bootstrap memory with your project's tech stack:

/claude-memory:analyze

This reads your project files (Gemfile, package.json, etc.) and stores facts about languages, frameworks, tools, and conventions.

claude-memory doctor

Just talk naturally! Memory happens automatically.

You: "I'm building a Rails app with PostgreSQL, deploying to Heroku"
Claude: [helps with setup]

# Behind the scenes:
# - Session transcript ingested
# - Facts extracted automatically
# - No user action needed

Later:

You: "Help me add a background job"
Claude: "Based on my memory, you're using Rails with PostgreSQL..."

👉 See Getting Started Guide → 👉 View Example Conversations →

We tested identical prompts with and without ClaudeMemory to measure the actual impact. Here's what we found:

Prompt: "Explain the conflict detection and resolution system. Answer from knowledge only — do not read any files."

Prompt: "I want to add a new predicate. Walk me through every file I need to update."

Prompt: "What are my standard development environment preferences across all my projects?"

File-searchable questions ("what version is this?") and one-shot code generation without explicit recall don't benefit — grep is equally effective. Memory shines when the answer isn't in any single file: architecture spanning dozens of classes, conventions from past sessions, decisions with rationale, and user preferences.

1. You chat with Claude - Tell it about your project
2. Facts are extracted - Claude identifies durable knowledge
3. Memory persists - Stored locally in SQLite
4. Automatic recall - Claude remembers in future conversations

👉 Architecture Deep Dive →

• Dual Scope: Project-specific + global user preferences
• Hybrid Search: FTS5 full-text + semantic vector search with Reciprocal Rank Fusion
• Native Vector Storage: sqlite-vec for fast KNN search with local embeddings (fastembed-rb, no API key)
• Session Context: Automatic context injection at session start with recent facts
• Privacy First: <private> tags exclude sensitive data
• Progressive Disclosure: Lightweight queries before full details
• Semantic Shortcuts: Quick access to decisions, conventions, architecture
• Truth Maintenance: Automatic conflict resolution
• Claude-Powered: Uses Claude's intelligence to extract facts (no API key needed)
• Token Efficient: 10x reduction in memory queries with progressive disclosure
• Database Maintenance: Compact, export, and backup commands
• Built-in Observability (0.10.0+): claude-memory dashboard opens a local web UI with a moments feed, trust panel (token budget, quality score, utilization, feedback), conflicts dedup, knowledge index, and 👍/👎 feedback. See Dashboard guide →. claude-memory digest writes a weekly markdown report (Activity, Context cost, Quality, New knowledge, Utilization, Conflicts, Feedback); claude-memory show prints what would be injected next SessionStart; claude-memory census audits the predicate vocabulary across projects.

Five user-visible signals so you can answer "is memory still worth it?" with numbers, not vibes:

• Token budget telemetry — every SessionStart context injection now records its estimated context_tokens. claude-memory stats --tokens [--since DAYS] reports p50/p95/avg/min/max plus a histogram across <500 / 500-1k / 1-2k / 2-5k / 5k+ buckets so you can see the per-session cost at a glance. The dashboard's Trust panel and claude-memory digest surface the same numbers.
• Hallucination-rate metric — the dashboard now scores how clean the fact base is, not just how full it is. Distill::BareConclusionDetector flags decision / convention facts that skipped the reason-clause requirement. Trust panel shows quality_score (live 30-day window with historical baseline beneath). claude-memory digest adds a Quality section with rejection rate.
• claude-memory show — new command prints what memory would inject at the next SessionStart in plain Markdown. Footer reports fact count, ~token estimate, and char count so you see the cost at a glance. Default hides the raw-transcript "Pending Knowledge" dump for readability; --pending opts in. --source startup|resume|clear simulates each fresh-session entrypoint.
• First-week ROI nudge — at SessionEnd, memory now prints memory contributed N facts this session, %used = X for the first 10 sessions, then quiets. Cold-start trust signal — you don't have to know about the dashboard. Opt out with CLAUDE_MEMORY_NO_NUDGE=1.
• Harm benchmark prototype — first ClaudeMemory benchmark that measures whether memory can make Claude wrong. Three hand-written cases (stale-tech, mismatched-scope, superseded-but-undetected) under spec/benchmarks/e2e/harm_bench_spec.rb. Real-mode run on the 0.11 release reported 0/3 harm; the full 10-15-case corpus + release gate lands in 0.12.

Three behavior changes worth knowing about — they affect what you'll see in extracted facts and SessionStart context, even if you don't change anything:

• Auto-memory mirror — On fresh sessions, the SessionStart context hook scans ~/.claude/projects/<slug>/memory/*.md and surfaces new or changed entries as candidates for extraction into ClaudeMemory. You'll see a "Pending Knowledge Extraction" section in Claude's startup context citing files from your auto-memory directory. Claude reviews these and calls memory.store_extraction for the high-signal ones; you don't need to copy-paste manually anymore.
• Why-clause enforcement — When Claude distills decision and convention facts, it's now required to embed a reason ("…because…", "…so that…", "…to avoid…"). A bare conclusion is dead weight; a fact with a reason stays useful when the situation changes. You'll see this reflected in fact text being longer and more justified.
• Reference predicate — Active facts that look like reference material (LOC counts, "X is a plugin/library/tool" templates, "by Firstname Lastname" attributions) are auto-tagged predicate=reference instead of convention. Keeps the conventions list signal-rich. Browse them in the dashboard's Knowledge → References section, or run claude-memory reclassify-references --dry-run to see candidates.

Plus: staleness detection (claude-memory stats --stale) lists active facts that haven't been recalled in N days, so you can prune dead weight explicitly. The dashboard's Trust → Needs review panel surfaces the count.

Exclude sensitive data from memory using privacy tags:

You: "My API key is <private>sk-abc123</private>"
Claude: [uses it during session]

# Stored: "API endpoint configured with key"
# NOT stored: "sk-abc123"

Supported tags: <private>, <no-memory>, <secret>

Existing users can upgrade seamlessly:

gem update claude_memory

All database migrations happen automatically. Run claude-memory doctor to verify.

See CHANGELOG.md for detailed release notes.

If memory tools aren't working, check initialization status:

memory.check_setup

This returns:

• Initialization status (healthy, needs_upgrade, not_initialized)
• Version information
• Missing components
• Actionable recommendations

Need help getting started? Run:

/setup-memory

This skill provides:

• Step-by-step installation instructions
• Common error solutions
• Post-installation verification
• Upgrade guidance

Verify your ClaudeMemory installation:

claude-memory doctor

This checks:

• Database existence and integrity
• Schema version compatibility
• sqlite-vec availability and index coverage
• Hooks configuration
• Snapshot status
• Stuck operations

To remove ClaudeMemory configuration:

# Remove hooks and MCP configuration (keeps databases)
claude-memory uninstall

# Remove everything including databases
claude-memory uninstall --full

# For global uninstall
claude-memory uninstall --global
claude-memory uninstall --global --full

The uninstall command removes:

• Hooks from .claude/settings.json
• MCP server from .claude.json
• ClaudeMemory section from CLAUDE.md
• Databases and generated files (with --full)

Note: The doctor command will warn you if orphaned hooks are detected (hooks configured but MCP plugin removed). Run claude-memory uninstall to clean them up.

• 📖 Getting Started - Step-by-step onboarding
• 💡 Examples - Use cases and workflows
• 📊 Dashboard - Local web UI for inspection and trust signals (0.10.0+)
• 🔧 Plugin Setup - Claude Code integration
• 🏗️ Architecture - Technical deep dive
• 🔒 API Stability - What's stable / experimental / internal across releases (0.12.0+)
• 📝 Changelog - Release notes

ClaudeMemory includes DevMemBench, a developer-domain benchmark suite that measures retrieval quality and truth maintenance accuracy. All offline benchmarks run locally at zero cost.

Semantic and hybrid retrieval use fastembed-rb with the BAAI/bge-small-en-v1.5 model (384-dim, runs locally, no API key needed).

Retrieval accuracy -- Given a database of ~105 developer-domain facts across 5 simulated projects, how well does search find the right facts? Measured with standard IR metrics (Recall@k, MRR, nDCG@10) across 155 queries at varying difficulty levels (exact keyword match, semantic paraphrase, cross-category synthesis, abstention, temporal).

Truth maintenance -- Given pairs of existing and incoming facts, does the resolver correctly determine the outcome? 100 FEVER-inspired cases test four outcomes: supersession (new stated fact replaces old), conflict (inferred fact contradicts stated), accumulation (multi-value predicates coexist), and corroboration (same fact adds provenance).

End-to-end with Claude -- 31 scenarios across 5 LongMemEval ability categories (information extraction, multi-session reasoning, temporal reasoning, knowledge updates, abstention). Requires EVAL_MODE=real and costs ~$2-8 per run.

# Offline benchmarks ($0, ~8 seconds)
bundle exec rspec spec/benchmarks/ --tag benchmark --format documentation

# Full evals + benchmarks
./bin/run-evals --all

# End-to-end with real Claude (~$2-8)
EVAL_MODE=real bundle exec rspec spec/benchmarks/e2e/ --tag eval_real

The benchmark dataset draws from real CLAUDE.md patterns and is designed specifically for ClaudeMemory's 6 predicates and 8 entity types. Open IR datasets (BEIR, FEVER, LongMemEval) informed the methodology but don't cover developer-domain knowledge.

👉 Benchmark Details →

• Language: Ruby 3.2+
• Storage: SQLite3 (no external services)
• Testing: 1964 examples (~1700 unit/integration + ~250 benchmarks/evals), 100% core coverage
• Code Style: Standard Ruby

git clone https://github.com/codenamev/claude_memory
cd claude_memory
bin/setup
bundle exec rspec

👉 Development Guide →

• 🐛 Report a bug
• 💬 Discussions

MIT - see LICENSE.txt

Made with ❤️ by Valentino Stoll