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 →

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
• 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

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
• Hooks configuration
• Snapshot status
• Stuck operations
• Orphaned hooks (hooks without MCP configuration)

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
• 🔧 Plugin Setup - Claude Code integration
• 🏗️ Architecture - Technical deep dive
• 📝 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: 985 examples, 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