Claude-Mem: Persistent Memory System for AI Coding Assistants

Introduction

Every AI coding session starts fresh — your assistant has no memory of previous conversations, decisions made yesterday, or lessons learned from past projects. You end up repeating the same context, explaining the same codebase structure, and losing valuable insights buried in conversation history.

Claude-mem solves this problem by creating a persistent memory system for Claude Code. It automatically captures tool usage observations, compresses them using AI, and stores them in a hybrid SQLite + Chroma vector database. When you start a new session, relevant context is intelligently injected based on semantic similarity and keyword matching.

With 29,663 GitHub stars and active community adoption, claude-mem has become the go-to solution for developers who want their AI coding assistant to remember and learn from past interactions.

What is Claude-Mem?

Claude-mem is an open-source Claude Code plugin that adds persistent memory to your AI coding assistant. Unlike Claude's basic built-in memory (which only stores simple facts), claude-mem captures and compresses the full context of your tool usage, decisions, and development patterns.

How It Works

1. Capture: 5 lifecycle hooks monitor every tool usage (file operations, searches, commands)
2. Compress: Claude Agent SDK processes observations and extracts key insights
3. Store: SQLite database + Chroma vector embeddings for hybrid search
4. Inject: MCP tools provide relevant context in new sessions via progressive disclosure

The system achieves ~10x token savings by filtering observations before retrieval — you get relevant context without overwhelming the AI with unnecessary details.

Key Features

5 Lifecycle Hooks

Claude-mem hooks into every aspect of your coding session:

• SessionStart: Initialize memory context for the session
• UserPromptSubmit: Capture user intent and context
• PostToolUse: Log tool results, decisions, and patterns
• Stop: Process and compress observations when stopping
• SessionEnd: Final compression and storage

Worker Service & Web UI

A background worker service runs on port 37777 with a web viewer interface. You can browse your memory database, search observations, and see how context is being compressed and retrieved.

Hybrid Search System

Claude-mem uses both semantic similarity (via Chroma vector embeddings) and keyword matching (SQLite full-text search) to find relevant context. This hybrid approach ensures you get both conceptually related and specifically relevant observations.

MCP Integration with Progressive Disclosure

Three MCP tools provide intelligent memory access:

• search: Find relevant observations (returns summaries)
• timeline: Show chronological context for specific topics
• get_observations: Fetch full details for specific observations

This 3-layer system prevents context overload while ensuring relevant details are accessible when needed.

Privacy Controls

Wrap sensitive information in <private> tags to exclude it from memory storage:

<private>
API_KEY=sk-1234567890abcdef
DATABASE_URL=postgres://user:pass@localhost/db
</private>

The system automatically filters out private content during observation processing.

Endless Mode (Beta)

For extended coding sessions, Endless Mode prevents memory fragmentation by maintaining continuous context compression across multiple session boundaries.

Architecture & Technology

Technology Stack

Data Flow

# Memory Creation Flow
User Action → Tool Usage → PostToolUse Hook → 
Raw Observation → Claude Agent SDK → 
Compressed Summary → SQLite + Chroma → Stored Memory

# Memory Retrieval Flow  
New Session → User Query → MCP Search Tools →
Hybrid Search (Semantic + Keyword) → 
Progressive Disclosure → Injected Context

Installation Guide

Prerequisites

• Node.js 18+ (for the plugin and worker service)
• Claude Code with OpenClaw Gateway integration
• SQLite3 (automatically installed)

The system automatically installs Bun and uv (Python package manager) as needed.

Installation Steps

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Configuration

Create a claude-mem.config.js file to customize behavior:

module.exports = {
  // Database location
  dbPath: './claude-mem.db',
  
  // Worker service port
  workerPort: 37777,
  
  // Compression settings
  compression: {
    enabled: true,
    batchSize: 10,
    maxObservations: 1000
  },
  
  // Privacy settings
  privacy: {
    enablePrivateTags: true,
    excludePatterns: ['password', 'token', 'secret']
  },
  
  // MCP tools configuration
  mcp: {
    searchLimit: 20,
    progressiveDisclosure: true
  }
};

Use Cases

Long-term Project Development

Working on a complex codebase over weeks or months? Claude-mem remembers:

• Architecture decisions and reasoning
• File structure and component relationships
• Bug fixes and their solutions
• Performance optimizations tried
• Code review feedback incorporated

Team Knowledge Sharing

Multiple developers can benefit from shared memory contexts:

• Onboarding new team members with project context
• Preserving architectural knowledge
• Sharing debugging techniques and solutions
• Maintaining consistent coding patterns

Learning & Skill Development

Claude-mem accelerates learning by remembering:

• New frameworks and their patterns
• Debugging strategies that worked
• Common mistakes and their fixes
• Best practices discovered through experience

Research & Experimentation

Perfect for research projects where context accumulates over time:

• Experiment results and insights
• Literature review findings
• Model performance comparisons
• Research methodology decisions

Community Feedback

What Developers Are Saying

"This is exactly what I needed. No more explaining the same codebase structure every session. Claude-mem makes my AI assistant actually feel like a team member who remembers our conversations."

"The progressive disclosure system is brilliant. I get relevant context without token bloat. The 3-layer MCP integration (search → timeline → get_observations) prevents information overload."

"Started using this for a 6-month React Native project. The memory compression is incredible — it captures the essence of decisions without storing every single detail. Game changer for long-term development."

Community Resources

• Discord Server: Active community for support and feature requests
• GitHub Discussions: Technical discussions and architecture feedback
• Blog Coverage: Multiple technical blogs have covered setup and use cases
• Reddit Thread: Popular discussion with 500+ upvotes and real-world experiences

Competitors

Pros & Cons

Pricing

Cost Breakdown

The main cost is Claude API usage for observation compression:

• Light Usage (10 sessions/week): ~$1-2/month
• Heavy Usage (daily coding): ~$5-10/month
• Team Usage (shared memory): ~$20-50/month

Compare this to the time saved from not having to re-explain context — claude-mem typically pays for itself in saved developer hours within days.

Getting Started

Quick Start Guide

1. Install via OpenClaw Gateway:

   /plugin marketplace add thedotmack/claude-mem
   /plugin install claude-mem

2. Start coding normally — claude-mem begins capturing observations automatically
3. Check the web UI at http://localhost:37777 to see memory building
4. Use MCP search tools to retrieve context:
   • search "React components" — find related observations
   • timeline "debugging session" — see chronological context
   • get_observations [123, 456] — fetch specific details
5. Add privacy tags for sensitive content:

   <private>API_KEY=your-secret-key</private>

Best Practices

• Let it build: Use claude-mem for 2-3 sessions before expecting significant context
• Use descriptive names: Good file names and clear prompts improve memory quality
• Review periodically: Check the web UI to understand what's being captured
• Tag sensitive data: Always wrap secrets in <private> tags
• Monitor storage: Database can grow large with extensive usage

Troubleshooting

For additional support, join the GitHub Discussions or the community Discord server.