Memory compression and persistence system for Claude Code conversations

Documentation · Report Bug · Request Feature

• About the Project
  • Tech Stack
  • Features
• Getting Started
  • Prerequisites
  • Installation
  • Running Tests
• Usage
  • Basic Commands
  • Hook System
  • Memory Operations
  • ChromaDB MCP Tools
  • Advanced Usage
• Architecture
• Configuration
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

claude-mem automatically captures, compresses, and retrieves context across Claude Code sessions, enabling true long-term memory through semantic search and intelligent compression.

Perfect for developers who want their AI assistant to remember project context, past decisions, and conversation history across sessions without manual context management.

• 🧠 Automatic Memory Compression - Real-time conversation capture and intelligent summarization
• 🔍 Semantic Search - ChromaDB-powered vector search for intelligent context retrieval
• 📦 Project Isolation - Memories segregated by project with multi-project support
• 🔄 Session Persistence - Context loads automatically at session start and /clear command
• 🎯 MCP Integration - 15+ ChromaDB tools via Model Context Protocol
• 💾 SQLite Storage - Fast metadata and session tracking with embedded database
• 🗑️ Smart Trash - Safe file deletion with recovery capabilities
• ⚡ Streaming Hooks - Sub-50ms overhead for real-time event capture
• 🤖 Agent SDK Compression - Async transcript processing without blocking conversations
• 📊 Session Overviews - Automatic session summaries with temporal context

This project requires Node.js and works best with Claude Code

• Node.js >= 18.0.0
• Claude Code with MCP support
• macOS/Linux (POSIX-compliant system)
• Bun >= 1.0.0 (optional, for development)

Install claude-mem globally via npm

npm install -g claude-mem
claude-mem install

The interactive installer will guide you through three installation scopes:

• User - Install for current user (default, recommended)
• Project - Install for current project only
• Local - Install to custom directory

To run tests, use the following commands

# Run all tests
bun test

# Run integration tests
npm run test:integration

# Run with coverage
npm run test:coverage

# Check installation status
claude-mem status

# View operation logs
claude-mem logs

# Load context for current project
claude-mem load-context --project my-project

# View compressed memories (interactive)
claude-mem restore

# Manage trash bin
claude-mem trash view
claude-mem restore
claude-mem trash empty

claude-mem integrates with Claude Code via streaming hooks that capture conversation events:

• user-prompt-submit - Captures user prompts in real-time
• post-tool-use - Spawns Agent SDK for async compression
• stop-streaming - Generates session overview and cleanup
• session-start - Loads relevant context automatically

Hooks are configured during installation with a 180-second timeout and run transparently in the background.

claude-mem compress

Compress Claude Code transcripts into searchable memories with semantic embeddings.

# Load last 10 memories for current project
claude-mem load-context

# Load specific number of memories
claude-mem load-context --count 20

# Filter by project
claude-mem load-context --project my-app

# Output raw JSON
claude-mem load-context --raw

claude-mem includes Smart Trash for safe file operations:

# Move files to trash
claude-mem trash file.txt
claude-mem trash -r directory/

# View trash contents
claude-mem trash view

# Restore files interactively
claude-mem restore

# Empty trash permanently
claude-mem trash empty

claude-mem exposes 15+ ChromaDB operations via MCP:

# List collections
claude-mem chroma-list-collections

# Create collection
claude-mem chroma-create-collection --collection-name memories

# Query documents semantically
claude-mem chroma-query-documents \
  --collection-name memories \
  --query-texts '["authentication implementation"]' \
  --n-results 5

# Add documents
claude-mem chroma-add-documents \
  --collection-name memories \
  --documents '["content here"]' \
  --ids '["mem-001"]'

# Get documents by ID
claude-mem chroma-get-documents \
  --collection-name memories \
  --ids '["mem-001"]'

# Update documents
claude-mem chroma-update-documents \
  --collection-name memories \
  --ids '["mem-001"]' \
  --documents '["updated content"]'

# Delete documents
claude-mem chroma-delete-documents \
  --collection-name memories \
  --ids '["mem-001"]'

See all available Chroma MCP commands with claude-mem --help.

# Generate title and subtitle from prompt
claude-mem generate-title "implemented authentication with OAuth"

# Output as JSON
claude-mem generate-title "fixed bug in checkout" --json

# Save to database
claude-mem generate-title "added feature" --session-id abc123 --save

# Run environment diagnostics
claude-mem doctor

# Output as JSON
claude-mem doctor --json

# Generate changelog from memories
claude-mem changelog

# Preview without saving
claude-mem changelog --preview

# Generate for specific version
claude-mem changelog --generate 3.9.0

# Search historical versions
claude-mem changelog --historical 5

~/.claude-mem/
├── archives/           # Compressed transcript backups
├── chroma/            # ChromaDB vector database
├── trash/             # Smart Trash with recovery
├── hooks/             # Hook configurations
├── logs/              # Operation logs
└── claude-mem.db      # SQLite metadata database

Rolling Memory - Real-time conversation turn capture via hooks with immediate ChromaDB storage

TranscriptCompressor - Intelligent chunking and compression of large conversations

MCP Server - 15+ ChromaDB tools for memory operations and semantic search

SQLite Backend - Session tracking, metadata management, and diagnostics storage

Hooks communicate via JSON stdin/stdout and run with minimal overhead:

1. user-prompt-submit - Stores user prompt immediately in ChromaDB
2. post-tool-use - Spawns Agent SDK subprocess for async compression
3. stop-streaming - Generates session overview, deletes SDK transcript
4. session-start - Loads project-specific context invisibly

src/
├── bin/           # CLI entry point
├── commands/      # Command implementations
├── core/          # Core compression logic
├── services/      # SQLite, ChromaDB, path discovery
├── shared/        # Configuration and utilities
└── mcp-server.ts  # MCP server implementation

hook-templates/    # Hook source files
dist/              # Minified production bundle
test/              # Unit and integration tests

Default hook timeout is 180 seconds. Configure during installation:

claude-mem install --timeout 300000  # 5 minutes

Skip MCP server installation if needed:

claude-mem install --skip-mcp

claude-mem install --force

• Real-time conversation capture with streaming hooks
• ChromaDB vector storage for semantic search
• SQLite metadata and session tracking
• MCP server with 15+ ChromaDB tools
• Smart Trash for safe file deletion
• Automatic session overviews
• Web UI for memory visualization
• Cross-platform Windows support
• Memory analytics and insights

Contributions are always welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Distributed under the AGPL-3.0 License. See LICENSE for more information.

Alex Newman - @thedotmack

Project Link: https://github.com/thedotmack/claude-mem

NPM Package: https://www.npmjs.com/package/claude-mem

• ChromaDB - Vector database for AI applications
• Anthropic - Claude AI and Agent SDK
• Model Context Protocol - Standardized AI tool integration
• better-sqlite3 - Fast SQLite bindings
• Shields.io - Beautiful README badges
• Awesome README Template - Template inspiration

Philosophy: claude-mem follows the Make It Work First approach - direct execution over defensive validation, natural failures instead of artificial guards, and memory as a living, evolving system. Context improves with use through semantic search, project isolation, and temporal relevance.

Built with TypeScript, ChromaDB, SQLite, and the Anthropic Agent SDK