Claude-Mem

What is Claude-Mem?

Claude-Mem is a Claude Code Smart Memory plugin created by Alex Newman. It automatically captures tool calls, code decisions, and debugging processes during a session through five lifecycle hooks, including SessionStart and PostToolUse. Using the Claude Agent SDK, it compresses the raw output into structured observation logs (approximately 500 tokens) and stores them in a local SQLite + Chroma vector database. When a user starts a new session, the plugin automatically injects the relevant historical context, allowing Claude to “remember” previous project background, architectural decisions, and bug fixing processes, eliminating the need for repeated explanations from the user. The plugin supports a web-based visual interface, privacy tags, and multi-language modes, and is compatible with Gemini CLI and OpenClaw gateway.

Claude-Mem’s main functions

• Automatic context capture : Automatically records the entire session through 5 lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) without manual intervention.
• AI-powered intelligent compression : Compresses tool output into structured observation records (including fields such as type, title, facts, narrative, and concepts), with each record containing approximately 500 tokens, saving context space.
• Hybrid search capabilities : Integrates SQLite FTS5 full-text search + Chroma vector database semantic search, supporting 10 search endpoints (full text, concept tags, document references, type filtering, etc.).
• Three-layer progressive retrieval : Layer 1 search returns an index of 50-100 tokens; Layer 2 timeline provides context for 100-200 tokens; Layer 3 retrieves the complete record (500-1000 tokens) on demand, increasing the signal rate from 6% to over 80%.
• Web visualization interface : Built-in HTTP API service (default port 37777), providing a browser-based interface for viewing and managing real-time memory streams.
• Endless Mode (Experimental) : Breaks the limitation of Claude Code’s context exceeding the limit after about 50 tool calls, and achieves theoretically unlimited sessions through real-time transcription and conversion. In actual testing, it completed the complete reconstruction of 600+ files.
• Automatic CLAUDE.md generation : Automatically generates and updates a file containing the activity timeline in the project folder CLAUDE.md, while retaining manually written content.
• Privacy controls : Use <private>the `<sup>` tag to exclude sensitive content from storage; all data is saved locally by default.
• Multilingual and mode system : Supports 28 languages ​​and provides workflow mode switching such as Code, Email Investigation, and Chill.

How to use Claude-Mem

• Execute in Claude Code :

• Restart Claude Code : Enable lifecycle hooks.
• Verify installation (choose one of three):
  • When the terminal is running curl http://localhost:37777/api/health, it should return.{"status":"ok"}
  • Check ~/.claude/hooks.jsonthe PostToolUse and SessionStart entries containing claude-mem.
  • Open in your browser http://localhost:37777and view the web viewer
• Getting Started : The first session begins accumulating observation records, and the second session onwards automatically injects relevant context.

Key information and usage requirements for Claude-Mem

• Product Positioning : An open-source intelligent memory plugin designed specifically for Claude Code. It automatically captures and persists the coding session context through lifecycle hooks, solving the problem of AI assistants “forgetting” across sessions.
• Core architecture : Fully automatic recording is achieved based on 5 lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd), eliminating the need for manual triggering of saving.
• Intelligent compression mechanism : Utilizing the Claude Agent SDK, the original tool output is compressed into structured observation records (including fields for type, title, facts, narrative, and concepts), with each record containing approximately 500 tokens, significantly saving context space.
• Three-layer progressive retrieval : Layer 1 searchreturns an index of 50-100 tokens → Layer 2 timelineprovides the timeline context of 100-200 tokens → Layer 3 get_observationsretrieves the complete 500-1000 token records on demand, increasing the saliency from 6% to over 80%.
• Hybrid storage solution : Local SQLite database (FTS5 full-text search) + Chroma vector database (semantic search), default storage path is~/.claude-mem/claude-mem.db
• Local Embedding Model : Runs using all-MiniLM-L6-v2 via ONNX, with all vector computations performed locally, eliminating the need to call external Embedding APIs.
• Web-based visual interface : Built-in HTTP service (default port 37777), open in a browser http://localhost:37777to view the real-time memory stream and management interface.
• Installation method : It must be installed through the plugin marketplace within Claude Code. /plugin marketplace add thedotmack/claude-memAfter execution /plugin install claude-mem, it is strictly forbidden to use it npm install -g claude-mem(this command only installs the SDK library and does not register lifecycle hooks, causing the functionality to be completely disabled).
• System prerequisites : Node.js version 18+ is a strict requirement; dependencies such as Bun, UV, and SQLite will be automatically detected and installed on the first run.
• Restart for the changes to take effect : Claude Code must be restarted after installation for the hooks configuration to be written ~/.claude/hooks.jsonand take effect.

Claude-Mem’s core advantages

• True cross-session continuity : Solving the problem of Claude Code “starting from scratch” with each new session, allowing yesterday’s debugging logs and last week’s architectural decisions to be directly referenced.
• Extremely low token cost : It can save about 2,250 tokens compared to the traditional MCP method, and the three-layer retrieval architecture avoids the inefficient practice of loading 35,000 tokens at once.
• Zero-configuration automation : It runs fully automatically after installation, without the need for manual logging or triggering of saving. The background worker completes non-blocking compression in an average of 8ms.
• Local priority, privacy and security : Data is stored by default ~/.claude-mem/claude-mem.db, no additional API key is required, and sensitive content can be excluded by tags.
• Cross-ecosystem compatibility : It not only supports Claude Code, but also Gemini CLI, Cursor, Windsurf, and OpenClaw gateway, and is compatible with Linux/macOS/Windows platforms.
• Multi-machine synchronization : claude-mem-syncEnables developers to synchronize observation logs and session summaries across multiple machines via SSH.