Claude Memory System (claude-mem)

Truth + Context = Clarity

A revolutionary memory system that transforms your Claude Code conversations into a persistent, intelligent knowledge base. Never lose valuable insights, code patterns, or debugging solutions again. Your AI assistant finally has a memory that spans across all your projects and sessions.

🚀 Why Claude-Mem?

The Problem We Solve

• Lost Context: Starting every Claude Code session from scratch
• Repeated Explanations: Re-describing your codebase and architecture repeatedly
• Fragmented Knowledge: Valuable insights scattered across hundreds of conversations
• Context Switching: Losing progress when switching between projects or devices
• Knowledge Decay: Brilliant solutions forgotten and re-discovered multiple times

The Claude-Mem Solution

Transform your Claude Code experience from forgetful to persistent, from isolated sessions to connected knowledge, from starting over to building upon previous insights.

✨ Key Features

🧠 Intelligent Memory Compression

• Automatically extracts key learnings from your Claude Code conversations
• Identifies patterns, architectural decisions, and breakthrough moments
• Compresses hours of conversation into searchable, actionable knowledge
• Uses advanced AI analysis to understand context and significance

🔄 Seamless Integration

• One-command setup: claude-mem install and you're ready
• Zero friction: Works invisibly in the background
• Automatic triggers: Memory compression on /compact and /clear
• Instant context loading: New sessions start with relevant memories

🎯 Smart Context Loading

• Loads relevant memories when starting new sessions
• Project-aware context selection
• Semantic search finds related knowledge across all sessions
• Prevents re-explaining the same concepts repeatedly

📚 Comprehensive Knowledge Base

• Stores technical implementations, bug fixes, and solutions
• Captures design patterns and architectural decisions
• Remembers tool configurations and setup procedures
• Archives complete conversation transcripts for detailed reference

🔍 Powerful Search & Retrieval

• Vector-based semantic search finds related concepts
• Keyword search for specific terms and technologies
• Project filtering to focus on relevant memories
• Time-based filtering to find recent insights

🛠 Installation & Setup

Prerequisites

• Node.js 18+
• Claude Code CLI installed
• uv (Python package manager) - automatically installed if missing

Quick Install

# Install globally
npm install -g claude-mem

# Set up Claude Code integration (installs uv if needed)
claude-mem install

# Restart Claude Code to activate

Alternative Installation

# Use without installing globally
npx claude-mem install

The claude-mem install command will automatically install uv if it's not already present on your system. uv is required for the Chroma MCP server that powers the memory system.

Verification

# Check installation status
claude-mem status

💻 How It Works

The Memory Lifecycle

1. 🎬 Session Start: Claude-mem loads relevant context from your knowledge base
2. 💬 Active Session: You work normally in Claude Code - no changes needed
3. 🗜️ Memory Compression: Use /compact or /clear to trigger intelligent compression
4. 🧠 Knowledge Extraction: AI analysis extracts key learnings and patterns
5. 💾 Persistent Storage: Memories stored in searchable vector database
6. 🔄 Context Ready: Next session starts with relevant memories loaded

Technical Architecture

• Vector Database: ChromaDB for semantic search and storage
• MCP Integration: Model Context Protocol for Claude Code communication
• AI Analysis: Advanced prompt engineering for knowledge extraction
• Local Storage: All data stored locally in ~/.claude-mem/

📋 Commands Reference

Core Commands

claude-mem install          # Set up Claude Code integration
claude-mem status           # Check system status and configuration
claude-mem load-context     # View and search stored memories
claude-mem logs             # View system logs and debug information
claude-mem uninstall       # Remove Claude Code hooks

Advanced Usage

claude-mem compress <file>  # Manually compress a transcript file
claude-mem restore          # Restore from backups
claude-mem trash-view       # View deleted files (Smart Trash feature)

📁 Storage Structure

Your claude-mem data is organized in ~/.claude-mem/:

~/.claude-mem/
├── index/           # ChromaDB vector database
├── archives/        # Original conversation transcripts  
├── hooks/           # Claude Code integration scripts
├── trash/           # Smart Trash (deleted files)
└── logs/            # System logs and debug information

🌟 Real-World Benefits

For Individual Developers

• Faster Problem Solving: Find solutions you've used before instantly
• Knowledge Accumulation: Build expertise that persists across projects
• Context Continuity: Pick up where you left off, even weeks later
• Pattern Recognition: See how you've solved similar problems before

For Teams (Coming Soon)

• Shared Knowledge: Team-wide memory accessible to all members
• Onboarding Acceleration: New team members access collective knowledge
• Best Practices: Capture and share proven solutions
• Institutional Memory: Prevent knowledge loss when team members leave

🚀 Coming Soon: Cloud Sync

Individual Plan ($9.95/month)

• Multi-device sync: Access your memories on any device
• Cloud backup: Never lose your knowledge base
• Enhanced search: Advanced filtering and semantic search
• API access: Integrate with your own tools and workflows

Team Plan ($29.95/month, 3+ seats)

• Shared memories: Team-wide knowledge base
• Role-based access: Control what memories are shared
• Admin dashboard: Manage team members and usage
• Priority support: Direct access to our engineering team

Join the waitlist for early access to cloud features.

🛡️ Privacy & Security

• Local-first: All data stored locally by default
• No tracking: We don't collect or transmit your conversations
• Your data: You own and control your knowledge base
• Open architecture: ChromaDB and MCP are open standards

🆘 Troubleshooting

Common Issues

Hook not triggering?

claude-mem status    # Check installation
claude-mem install --force   # Reinstall hooks

Context not loading?

claude-mem load-context   # Verify memories exist
claude-mem logs           # Check for errors

Performance issues?

# ChromaDB maintenance (if needed)
claude-mem status    # Check memory usage

🔧 Requirements

• Node.js: 18.0 or higher
• Claude Code: Latest version recommended
• Storage: ~100MB for typical usage
• Memory: 2GB RAM minimum for large knowledge bases

📞 Support & Community

• Documentation: Complete guides at claude-mem.ai/docs
• Issues: Report bugs at GitHub Issues
• Feature Requests: GitHub Discussions
• Community: Join our Discord for tips and discussions

📄 License

This software is free to use but is NOT open source. See LICENSE file for complete terms.

---

🎯 Ready to Transform Your Claude Code Experience?

npm install -g claude-mem
claude-mem install

Your AI assistant is about to get a lot smarter. 🧠✨

---

Built with ❤️ for developers who believe AI assistants should remember and learn from every conversation.