## Introduction claude-mem is a persistent memory compression system for AI coding agents that solves the fundamental "amnesia problem" -- the loss of project context between coding sessions. With over 37,000 GitHub stars and rapid community adoption, claude-mem has become the leading solution for enabling AI coding assistants to remember what they've learned about your codebase across sessions. The system automatically captures tool usage during sessions, generates semantic summaries, and injects relevant context into future sessions, creating a continuous knowledge loop. The project addresses a critical pain point that every developer using AI coding agents has encountered: starting each session from scratch, re-explaining project architecture, conventions, and recent decisions. claude-mem turns ephemeral agent interactions into a durable knowledge base that grows smarter with each session. ## Architecture and Design claude-mem uses a three-layer architecture that balances memory depth with retrieval speed: | Layer | Purpose | Storage | |-------|---------|--------| | Observation Capture | Records tool calls, file reads, edits, and terminal output during sessions | SQLite | | Semantic Compression | Distills raw observations into structured summaries with entity extraction | SQLite + Chroma | | Context Injection | Retrieves and ranks relevant memories for the current task | Vector search | The observation capture layer runs transparently during coding sessions, recording which files the agent reads, what changes it makes, what tests pass or fail, and what decisions are discussed. The semantic compression engine periodically processes raw observations into structured memory entries that include entities (files, functions, concepts), relationships, and confidence scores. The retrieval workflow uses a progressive disclosure pattern: it starts with a lightweight summary of the project state, then dynamically pulls in detailed memories based on the current task's semantic similarity to stored entries. This prevents context window bloat while ensuring relevant knowledge is available. ## Key Capabilities **Automatic Observation Capture**: claude-mem transparently monitors agent tool usage during sessions -- file reads, edits, terminal commands, search queries, and conversation turns. No manual annotation or tagging required. The system learns from what you do, not what you tell it. **Semantic Compression**: Raw session data is compressed into structured memory entries using LLM-powered summarization. A 2-hour coding session with hundreds of tool calls might compress into 5-10 high-quality memory entries that capture the essential decisions, patterns, and outcomes. **3-Layer Retrieval Workflow**: Memory retrieval combines recency-weighted search, semantic similarity (via Chroma vector store), and entity-based lookup. The system prioritizes recent, relevant, and high-confidence memories, with configurable weights for each dimension. **Web Viewer UI**: A built-in web interface lets developers browse, search, and manage their agent's memory store. You can inspect what the agent remembers, delete incorrect entries, pin important memories, and visualize knowledge graphs of entity relationships. **MCP Search Tools**: claude-mem exposes its memory store through the Model Context Protocol, allowing any MCP-compatible agent to query project history. This enables multi-agent workflows where different agents share accumulated knowledge. **Privacy Controls**: Fine-grained controls let developers exclude specific files, directories, or patterns from observation capture. Sensitive data like credentials, API keys, and personal information can be filtered at the capture layer before entering the memory store. **Claude Desktop and Claude Code Integration**: First-class support for both Claude Desktop (via MCP) and Claude Code (via skill integration) provides seamless setup for Anthropic's ecosystem. Configuration is a single command. ## Developer Integration Setup is minimal: ```bash npm install -g claude-mem claude-mem init ``` This creates a `.claude-mem` directory in your project with a SQLite database and Chroma vector store. The Claude Code skill is automatically registered if Claude Code is detected. Memory queries can be performed programmatically: ```typescript import { MemoryStore } from 'claude-mem'; const store = new MemoryStore('./project'); const memories = await store.search('authentication flow', { limit: 5 }); ``` The web viewer launches with: ```bash claude-mem viewer --port 3333 ``` ## Limitations The SQLite + Chroma storage model works well for individual projects but may struggle with very large monorepos containing thousands of files. Semantic compression quality depends on the LLM used for summarization, and cheaper models may produce less accurate memory entries. The system currently lacks multi-user support, so team-shared memories require manual export/import. Vector search accuracy degrades over very long time periods as the memory store grows, requiring periodic compaction. The TypeScript-only implementation limits use in non-Node.js environments. ## Who Should Use This claude-mem is ideal for developers who use AI coding agents daily and find themselves repeatedly re-explaining project context at the start of each session. Teams working on complex, long-running projects where accumulated knowledge matters most will see the greatest benefit. Developers who frequently switch between multiple projects and need each agent session to quickly "remember" project-specific conventions and architecture will appreciate the automatic context injection. The MCP integration makes it particularly valuable for users building multi-agent development workflows.