Repo Dev Tools

thedotmack/claude-mem

Persistent memory plugin that captures agent tool usage, summarizes it, and injects relevant context into future sessions for Claude Code, OpenCode, OpenClaw and more.

  • 99k GitHub stars
  • TypeScript
  • ⚖️ Apache-2.0
  • 🎯 Intermediate
View on GitHub (opens in a new tab) Setup guide
npx claude-mem install
thedotmack/claude-mem preview image

What it is

Claude-Mem preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. It uses lifecycle hooks, a local Bun-managed worker service with a web viewer, a SQLite database, and a Chroma vector database for hybrid semantic and keyword search. Memory can be queried through MCP search tools and a mem-search skill.

Who it's for

  • Claude Code users who want project knowledge to persist after sessions end or reconnect
  • Users of other supported harnesses named in the README (OpenCode, OpenClaw, T3 Code, Antigravity CLI, OMP, Pi, DeepSeek Harness, Grok Bot)
  • Developers who want token-efficient, searchable history of past agent work

Requirements

Requirements

  • Node.js 20.0.0 or higher
  • Claude Code: latest version with plugin support
  • Bun (auto-installed if missing)
  • uv, Python package manager for vector search (auto-installed if missing)
  • SQLite 3 (bundled)
  • OpenCode 1.3.4 or later (for the OpenCode integration)

Setup

  1. Install with the installer

    Run the single-command installer. It sets everything up, then offers a browser sign-in for the claude-mem observer (30 Day Free Trial). You can skip sign-in with an explicit --provider flag, CLAUDE_MEM_ONLINE_OPTIN=false, or in CI/non-interactive shells. Do not use npm install -g claude-mem, which installs only the SDK/library.

    bash
    npx claude-mem install

  2. Or install from the Claude Code plugin marketplace

    Run these inside Claude Code, then restart Claude Code. Context from previous sessions will automatically appear in new sessions.

    bash
    /plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

  3. Install for OpenCode

    Works with OpenCode 1.3.4 or later, including OpenCode 2. Restart OpenCode after installing.

    bash
    npx claude-mem install --ide opencode

  4. Install on an OpenClaw gateway

    The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more.

    bash
    curl -fsSL https://install.cmem.ai/openclaw.sh | bash

Examples

Search memory with the 3-layer workflow

typescript
typescript
// 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])

What it does: Get a compact index first, then fetch full details only for relevant IDs to save tokens (~10x per the README).

Switch mode/language

json
json
{
  "CLAUDE_MEM_MODE": "code--zh"
}

What it does: Set in ~/.claude-mem/settings.json to change workflow mode and observation language (here Simplified Chinese). Restart Claude Code to apply.

Include observations from all harnesses at session start

json
json
"CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true"

What it does: Set in ~/.claude-mem/settings.json so Claude Code and Codex SessionStart context includes observations from every harness; default is "false".

Install for Pi and DeepSeek Harness

bash
bash
npx claude-mem install --ide pi
npx claude-mem install --ide dsh --dsh-profile tui

What it does: Installs the native Pi extension or the DeepSeek Harness plugin; both use the worker runtime.

Pros & cons

Pros

  • Pro:Automatic operation: captures observations and injects context without manual intervention
  • Pro:Token-efficient 3-layer search (search, timeline, get_observations) with progressive disclosure
  • Pro:Privacy control via <private> tags to exclude sensitive content from storage
  • Pro:Supports many harnesses via a single installer with --ide options, plus a web viewer UI

Cons

  • Con:Installing via npm install -g claude-mem gives only the SDK/library, not the plugin hooks or worker, which can confuse setup
  • Con:Depends on a worker service, Bun, uv and a Chroma vector database, adding runtime components
  • Con:Default installer flow prompts browser sign-in for the hosted observer, with a 30-day free trial after which memory falls back to the Anthropic plan unless subscribed

Images

thedotmack/claude-mem preview image
thedotmack/claude-mem preview image · thedotmack/claude-mem on GitHub · Apache-2.0
thedotmack/claude-mem preview image