thedotmack/claude-mem

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk Persistent memory compression system built for Claude Code . Quick Start • How It Works • Search Tools • Documentation • Configuration • Troubleshooting • License Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect. Quick Start Install claude-mem for Grok Bot: npx claude-mem install --ide grok-bot Grok Bot has no host hooks, so we watch the chat log files. Default is CMEM Pro, the hosted memory. Local observer is opt-in: --provider host . Installing this plugin does not install Cursor. Awareness push pilot (LFG + Orifice): needle observations ( decision , bugfix , security_alert , sensitive ) are appended as dated - YYYY-MM-DD [awareness] … lines into that bot's memory/log/YYYY-MM.md . Grok Bot already re-reads the log from disk. This does not write profile.md , user-memory, or project memory. Disable with CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false . Install with a single command: npx claude-mem install The installer sets everything up first, then asks you to sign in to claude-mem in your browser (email magic link — no card required). Signing in provisions a memory key for your account and unlocks the claude-mem observer with a 30 Day Free Trial : memory runs off-plan, so you get up to 100% more usage from your plan. When the free trial ends, memory automatically falls back to your Anthropic plan unless you subscribe. After sign-in you pick your memory provider — the claude-mem observer, your own OpenRouter or Gemini key, or your Anthropic plan. Prefer to skip the sign-in? Pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false , or run in CI/non-interactive shells — the installer completes without any account interaction. Or install for OpenCode: npx claude-mem install --ide opencode This works with OpenCode 1.3.4 or later, including OpenCode 2. Restart OpenCode after installing. Or install for T3 Code (Codex and Claude Code providers): npx claude-mem install --ide t3code The installer discovers T3 Code's enabled providers, registers native Claude-Mem plugins in their configured homes, and supports T3-managed Codex. Restart T3 Code, trust the provider's hooks when prompted, and start a new thread. See the T3 Code integration guide for custom server settings, status, and removal. Or install for Antigravity CLI ( setup guide ): npx claude-mem install --ide antigravity Or install for OMP (Oh My Pi): npx claude-mem install --ide omp Or install the native Pi extension or DeepSeek Harness plugin: npx claude-mem install --ide pi npx claude-mem install --ide dsh --dsh-profile tui Pi and DeepSeek Harness use the worker runtime. See native harness setup for capture, recall, and troubleshooting. Or install from the plugin marketplace inside Claude Code: /plugin marketplace add thedotmack/claude-mem /plugin install claude-mem Restart Claude Code. Context from previous sessions will automatically appear in new sessions. Note: Claude-Mem is also published on npm, but npm install -g claude-mem installs the SDK/library only — it does not register the plugin hooks or set up the worker service. Always install via npx claude-mem install or the /plugin commands above. 🦞 OpenClaw Gateway Install claude-mem as a persistent memory plugin on OpenClaw gateways with a single command: curl -fsSL https://install.cmem.ai/openclaw.sh | bash The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the OpenClaw Integration Guide for details. Key Features: 🧠 Persistent Memory - Context survives across sessions 📊 Progressive Disclosure - Layered memory retrieval with token cost visibility 🔍 Skill-Based Search - Query your project history with mem-search skill 🖥️ Web Viewer UI - Real-time memory stream at the worker URL printed on startup 💻 Claude Desktop Skill - Search memory from Claude Desktop conversations 🔒 Privacy Control - Use <private> tags to exclude sensitive content from storage ⚙️ Context Configuration - Fine-grained control over what context gets injected 🤖 Automatic Operation - No manual intervention required 🔗 Citations - Reference past observations with IDs through the worker API or view all in the web viewer Documentation 📚 View Full Documentation - Browse on official website Getting Started Installation Guide - Quick start & advanced installation Usage Guide - How Claude-Mem works automatically Search Tools - Query your project history with natural language Cloud Sync - Back up your memories to cmem.ai — no daemon, the worker syncs on write Best Practices Context Engineering - AI agent context optimization principles Progressive Disclosure - Philosophy behind Claude-Mem's context priming strategy Architecture Overview - System components & data flow Architecture Evolution - The journey from v3 to v5 Hooks Architecture - How Claude-Mem uses lifecycle hooks Hooks Reference - 7 hook scripts explained Worker Service - HTTP API & Bun management Database - SQLite schema & FTS5 search Search Architecture - Hybrid search with Chroma vector database Configuration & Development Configuration - Environment variables & settings Development - Building, testing, contributing Release Branches - Stable, core-dev, and community-edge branch flow Troubleshooting - Common issues & solutions How It Works Core Components: 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts) Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook) Worker Service - Local HTTP API with web viewer UI and search endpoints, managed by Bun SQLite Database - Stores sessions, observations, summaries mem-search Skill - Natural language queries with progressive disclosure Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval See Architecture Overview for details. MCP Search Tools Claude-Mem provides intelligent memory search through 4 MCP tools following a token-efficient 3-layer workflow pattern : The 3-Layer Workflow: search - Get compact index with IDs (~50-100 tokens/result) timeline - Get chronological context around interesting results get_observations - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result) How It Works: Claude uses MCP tools to search your memory Start with search to get an index of results Use timeline to see what was happening around specific observations Use get_observations to fetch full details for relevant IDs ~10x token savings by filtering before fetching details Available MCP Tools: search - Search memory index with full-text queries, filters by type/date/project timeline - Get chronological context around a specific observation or query get_observations - Fetch full observation details by IDs (always batch multiple IDs) Example Usage: // Step 1: Search for index search ( query = "authentication bug" , type = "bugfix" , limit = 10 ) // Step 2: Review index, identify relevant IDs (e.g., #123, #456) // Step 3: Fetch full details get_observations ( ids = [ 123 , 456 ] ) See Search Tools Guide for detailed examples. Release Branches Stable releases ship from main and are published to npm. core-dev and community-edge are source-run branches for early reliability fixes and community integrations. See Release Branches for the branch flow and non-stable run instructions. System Requirements Node.js : 20.0.