claude-mem

---

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: memory that runs off-plan, free for your first 30 days, 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

Or install for Antigravity CLI (setup guide):

npx claude-mem install --ide antigravity

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:

1. 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook)
3. Worker Service - Local HTTP API with web viewer UI and search endpoints, managed by Bun
4. SQLite Database - Stores sessions, observations, summaries
5. mem-search Skill - Natural language queries with progressive disclosure
6. Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval

See Architecture Overview for details.

---

MCP Search Tools