Claude-Mem

Claude-Mem: Persistent Memory for Claude Code

Claude-Mem is an innovative plugin designed specifically for Claude Code, Anthropic's AI-powered coding assistant. It addresses a key limitation in AI-assisted development: the loss of context across sessions. By implementing a sophisticated memory compression system, Claude-Mem ensures that Claude retains knowledge from previous interactions, enabling more efficient and coherent coding workflows.

Core Functionality

At its heart, Claude-Mem operates through a series of automated processes triggered by lifecycle hooks in Claude Code sessions. When a session begins, it injects recent observations as context, providing Claude with an immediate recap of past work. As the user interacts—submitting prompts or executing tools (like reading or writing files)—Claude-Mem captures these actions in real-time. Observations are then processed by a worker service that uses Claude's agent-sdk to extract key learnings, compressing them into concise, semantic summaries stored in a SQLite database with full-text search capabilities.

This system supports multi-prompt sessions, preserving context even across /clear commands, and works seamlessly in the background without requiring manual intervention. Upon session end, a final summary is generated, ready for the next interaction. The result is a biomimetic memory architecture that mimics human recall, allowing for progressive disclosure: users (or Claude) can access layered information—from high-level indexes to detailed narratives and full transcripts—while monitoring token costs to optimize efficiency.

Key Features

• Persistent Memory: Context survives session restarts or terminations, ensuring continuity for long-term projects.
• Progressive Disclosure: Memory is retrieved in layers. Layer 1 offers an index of observations with token estimates; Layer 2 provides on-demand details via search; Layer 3 enables perfect recall of original content. This approach saves significant tokens (e.g., ~2,250 per session start via skill-based search) and aids decision-making with visual indicators for observation types (e.g., 🔴 for critical issues).
• Intelligent Search Tools: The mem-search skill allows natural language queries like "What bugs did we fix last session?" or "How did we implement authentication?" It supports operations such as searching by concept, file, type (decision, bugfix, etc.), timeline, or recent context, leveraging a hybrid semantic + keyword search powered by Chroma vector database and FTS5.
• Web Viewer UI: A real-time dashboard at http://localhost:37777 displays memory streams, search results, and configuration options, including version switching for beta features.
• Privacy and Configuration Controls: Use <private> tags to exclude sensitive content from storage. Fine-grained settings (11 new in v6.4.9) control context injection, filtering by type/concept, and token economics display. Environment variables allow model selection (default: claude-haiku-4-5) and port customization.
• Beta Features like Endless Mode: An experimental mode that compresses tool outputs into ~500-token observations, reducing context window usage by ~95% and enabling ~20x more tool uses before limits. It transforms transcripts in real-time for linear scaling, though it adds latency (60-90s per tool).
• Structured Observations: AI-extracted learnings categorized by type, tagged with concepts and files, complete with citations via claude-mem:// URIs for referencing past decisions.

Architecture Overview

Claude-Mem's architecture is modular and robust:

1. Lifecycle Hooks: Five core hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) plus a pre-hook for smart installation.
2. Worker Service: Managed by PM2, exposes an HTTP API with 10 search endpoints and a web UI on port 37777.
3. Database: SQLite for sessions, observations, and summaries, enhanced with FTS5 for search and Chroma for vectors.
4. Automatic Processing: No global dependencies beyond Node.js >=18; bundles PM2 and SQLite.

This setup ensures privacy (edge processing for private tags) and scalability, with full transcripts archived for recall.

Usage and Benefits

Installation is straightforward: Add the plugin via Claude Code's marketplace and restart. Once active, it runs transparently, injecting context at startup and capturing data during use. Developers benefit from reduced repetition, faster onboarding to projects, and smarter AI assistance—Claude can now 'remember' implementations, fixes, and decisions without re-explaining.

In practice, it shines in iterative development: Search for patterns like "recent changes to worker-service.ts" or timelines around specific events. For teams, the privacy features and citations foster collaborative continuity.

Development and Evolution

Built with TypeScript and powered by Claude Code, Claude-Mem has evolved rapidly—from v3's basic hooks to v6's advanced search and beta modes. Recent updates include dual-tag privacy (v6.4.0), version channels (v6.3.0), and context configuration (v6.4.9). It's open-source under AGPL-3.0, encouraging contributions via forking, testing, and PRs.

System requirements are minimal: Node.js 18+, latest Claude Code. Troubleshooting is aided by a dedicated skill and logs.

Overall, Claude-Mem transforms Claude Code from a session-bound tool into a persistent coding companion, boosting productivity in AI-assisted development by bridging the gap between ephemeral chats and enduring knowledge.