Claude Code Memory Plugin Cuts Token Usage 10x, Works Across 18+ AI Coding Tools

Problem: Claude Code Forgets Context Between Sessions

Developers using Claude Code frequently encounter a frustrating limitation: each new session starts with a blank slate. As the author illustrates, after fixing a login bug on Monday — reading src/auth.ts, editing the token expiry logic, and adding regression tests — a fresh Tuesday session forces the user to re-explain the entire project because Claude has no memory of prior work.

Solution: claude-mem Architecture

The claude-mem plugin solves this by automatically recording session activity, compressing it into structured summaries, and injecting relevant context at the start of new sessions — all without manual intervention.

Core Mechanism: 5 Hooks + 1 Background Worker

Claude Code emits signals at key moments; claude-mem intercepts five of them:

SessionStart : Starts the worker and injects the recent observation index (default 50 entries) plus the last session summary.

UserPromptSubmit : Registers the current session and stores the user's prompt.

PostToolUse : After every tool call (Read, Edit, Bash, etc.), sends the tool name, input, and output to the worker for compression into an "observation" containing type, title, key facts, narrative context, and involved files.

Stop : When Claude finishes a response, generates a session summary covering what was asked, what was explored, what was learned, what was completed, and next steps.

SessionEnd : Notifies the worker to finalize the session.

The actual compression and storage happen in a local Worker background service that runs on the developer's machine. It queues records, calls an AI model (default: Claude Haiku 4.5 via the user's own Anthropic subscription) to compress raw tool logs into concise observations, and provides a web viewer for real-time inspection.

Dual Storage: SQLite + Chroma

SQLite (with FTS5 full-text search): stores sessions, prompts, observations, and summaries in a single local database file under ~/.claude-mem.

Chroma (vector database): enables semantic "search by meaning" combined with keyword search for higher recall. Enabled by default; can be disabled to use SQLite only.

From Tool Call to Observation: A Concrete Example

When the user runs npm test via the Bash tool, the raw output may be a full screen of logs. The worker feeds this to the compression model (default Haiku 4.5) which produces a structured observation:

Type: e.g., test Title: e.g., "Add login regression tests"

Key facts: test count, pass/fail status

Narrative: why the test was added, what it covers

Files:

src/auth.test.ts

Three-Layer Retrieval: Progressive Disclosure Saves ~10x Tokens

Dumping all accumulated memory into the context window would be prohibitively expensive. claude-mem implements a three-step retrieval process that Claude invokes automatically:

search — Returns a numbered, compact index (~50–100 tokens per entry). Example query: query="authentication bug", type="bugfix" yields a list like #123 Login kick-out fix, #456 Third-party callback 404.

timeline — Given an anchor ID (e.g., anchor=123), returns surrounding entries (default ±3) to show what happened before and after.

get_observations — Fetches the full observation records for only the selected IDs (~500–1000 tokens each).

Because the index entry is roughly 1/10 the size of a full observation, and only a few full records are ever retrieved, the official estimate is ~10x token savings. The author calls this "progressive disclosure" — "use only what you need" — and notes the design resembles the Skills pattern.

Installation & Common Pitfalls

Correct Install Command

npx claude-mem install

Requires Node.js 20+; Bun and uv are auto-installed if missing. Alternatively, install via Claude Code's plugin marketplace:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

After installation, restart Claude Code; prior session memories appear automatically in new sessions.

Pitfall 1: Don't Use Global npm Install

npm install -g claude-mem

only installs the library — hooks are not registered and the worker does not start. The npx command runs the installer that sets up hooks and launches the worker.

Pitfall 2: Browser Login Prompt for Hosted Service

The installer opens a browser to sign into claude-mem observer , a hosted service offering 30 days free (memory writes don't count against your Claude quota). After trial, it falls back to your own Anthropic plan. To skip registration entirely, use: npx claude-mem install --provider claude Or set the environment variable CLAUDE_MEM_ONLINE_OPTIN=false before installing (useful for CI/non-interactive environments).

Beyond Claude Code: 18+ Supported Tools

Despite the name, claude-mem supports a wide range of AI coding assistants via the --ide flag. The installer source reveals 18 targets grouped by integration depth:

Deep hook/plugin integration (auto-recording) : Claude Code, Codex CLI, Cursor, OpenCode, Kimi Code, Antigravity, T3 Code, OMP, Windsurf, DeepSeek Harness ( dsh), OpenClaw, Hermes Agent.

Chat-log integration : Grok Bot.

MCP search only : Copilot CLI, Goose, Roo Code, Warp.

Manual memory fetch : Pi (auto-recording depends on compatibility).

Examples:

npx claude-mem install --ide opencode
npx claude-mem install --ide t3code
npx claude-mem install --ide dsh --dsh-profile tui

OpenCode requires v1.3.4+; T3 Code installs for both Codex and Claude Code; dsh is DeepSeek Harness.

Cross-Tool Memory Sharing

When using Claude Code and Codex together, enable:

"CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true"

New sessions then include memories from all tools (default is off, isolating per-tool memory).

Three Recommended Post-Install Settings

1. Write Memories in Chinese

Edit ~/.claude-mem/settings.json:

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

Simplified Chinese mode is built-in; restart Claude Code to apply.

2. Switch the Compression Model to Save Quota

Every observation and summary invokes an AI model. Default is Claude Haiku 4.5 (consumes your Claude quota). The CLAUDE_MEM_PROVIDER setting supports five providers: claude (default)

codex

gemini

openrouter

openai-compatible

— works with any /chat/completions -compatible endpoint (DeepSeek, NVIDIA NIM, Ollama, LM Studio).

DeepSeek example:

{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "deepseek",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "your-deepseek-key"
}

Default model is deepseek-chat; override with CLAUDE_MEM_OPENAI_COMPAT_MODEL.

Local Ollama (no API key, fully on-device):

{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "ollama",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "your-ollama-model-name"
}

Model name comes from ollama list. Memories never leave the machine.

3. Exclude Sensitive Content with <private> Tags

Wrap secrets, customer data, or keys in <private>...</private> — the plugin will not store tagged content.

Quick-Start Checklist

Run npx claude-mem install (add --provider claude to skip login), then restart.

Do not use npm install -g claude-mem.

For non-Claude Code tools, add --ide <name> (e.g., --ide opencode).

Set "CLAUDE_MEM_MODE": "code--zh" for Chinese memories.

To reduce quota usage, switch compression model to DeepSeek or local Ollama.

Wrap sensitive data in <private> tags.

The author plans to run claude-mem on a personal writing project and report back on long-term effectiveness.