Claude Mem

Quick Start

Install with a single command:

npx claude-mem install

Or install for Gemini CLI (auto-detects ~/.gemini):

npx claude-mem install --ide gemini-cli

Or install for OpenCode:

npx claude-mem install --ide opencode

Or install from the plugin marketplace inside Claude Code:

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

Restart Claude Code or Gemini CLI. 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 http://localhost:37777
• 💻 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 (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)
• 🧪 Beta Channel - Try experimental features like Endless Mode via version switching

Documentation

📚 View Full Documentation - Browse on official website

Getting Started

• Installation Guide - Quick start & advanced installation
• Gemini CLI Setup - Dedicated guide for Google's Gemini CLI integration
• Usage Guide - How Claude-Mem works automatically
• Search Tools - Query your project history with natural language
• Beta Features - Try experimental features like Endless Mode

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
• 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 - HTTP API on port 37777 with web viewer UI and 10 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

Claude-Mem provides intelligent memory search through 4 MCP tools following a token-efficient 3-layer workflow pattern:

The 3-Layer Workflow:

1. search - Get compact index with IDs (~50-100 tokens/result)
2. timeline - Get chronological context around interesting results
3. 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:

1. search - Search memory index with full-text queries, filters by type/date/project
2. timeline - Get chronological context around a specific observation or query
3. 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.

Beta Features

Claude-Mem offers a beta channel with experimental features like Endless Mode (biomimetic memory architecture for extended sessions). Switch between stable and beta versi

…