ClaudeMemory

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

What It Does

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.

Quick Start

1. Install the Gem

gem install claude_memory

2. Install the Plugin

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

3. Initialize 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

4. Analyze Your Project (Optional)

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.

5. Verify Setup

claude-memory doctor

Use with Claude Code

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 →

How It Works

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 →

Key Features

• 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

Privacy Control

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>

Upgrading

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.

Troubleshooting

Check Setup Status

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

Installation Help

Need help getting started? Run:

/setup-memory

This skill provides:

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

Health Check

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)

Uninstalling

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.

Documentation

• 📖 Getting Started - Step-by-step onboarding
• 💡 Examples - Use cases and workflows
• 🔧 Plugin Setup - Claude Code integration
• 🏗️ Architecture - Technical deep dive
• 📝 Changelog - Release notes

For Developers

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

Support

• 🐛 Report a bug
• 💬 Discussions

License

MIT - see LICENSE.txt

---

Made with ❤️ by Valentino Stoll