Released on October 30, 2026, claude-mem is an open-source long-term memory plugin built for coding agents, created by developer Alex Newman, whose GitHub handle is thedotmack. First published in August 2025 under the Apache-2.0 license, the repository had accumulated roughly 105,000 GitHub stars as of October 30, 2026. The latest stable release is v15.6.0.
The core design of claude-mem centers on event hooking, lightweight observation compression, and indexed on-demand retrieval. Instead of injecting the full conversation history into every new prompt, the system stores compressed observation records inside a local SQLite database. When a fresh session starts, only lightweight index summaries are loaded. Full context is fetched by ID only when the agent explicitly requires it. Official documentation cites a representative comparison: feeding the complete historical context directly to the model consumes approximately 35,000 tokens, while indexed lookup of the same information only requires around 920 tokens.
A critical caveat is often overlooked: claude-mem itself generates token overhead through its background "observer" model, which handles compression tasks. By default, this observer draws capacity from an Anthropic subscription plan. Users can reconfigure the observer endpoint to point to any OpenAI-compatible API and run compression workloads on cheaper small models, which is the primary adjustment that determines whether the plugin delivers net cost savings.
Core Workflow: Capture, Compress, Retrieve On Demand
The entire pipeline of claude-mem can be separated into three sequential stages: hook-based recording, observer compression, and tiered retrieval injection.
- Hook Recording: The plugin attaches listeners to six agent lifecycle events:
SessionStart,UserPromptSubmit,PreToolUse,PostToolUse,Stop, andSessionEnd. Every tool call operation, including file reading, editing, bash execution and grep searches, is captured and timestamped. - Observer Compression: A secondary background model converts raw tool event logs into structured observation records. Each record contains a title, factual takeaways, classification tags such as decision notes, bug fixes or feature implementations, and references to related source files. These compressed records are saved to local SQLite storage, with optional vector indexing via Chroma for hybrid search. At the end of a working session, the observer also generates a final summary that documents completed actions, learned constraints and planned next steps.
- Context Injection: At the launch of a new session, the agent loads index entries for the most recent 50 observation records by default. The tiered MCP retrieval toolkit enables progressive disclosure, so the agent only pulls detailed full records when search results indicate they are relevant.
The three retrieval tools carry predictable token footprints:
| Tool | Approximate Token Cost | Function |
| ---- | ---- | ---- |
| search | 50–100 tokens | Scan indexed metadata for relevant records |
| timeline | Variable | Reconstruct the chronological sequence of prior work |
| get_observations | 500–1000 tokens | Fetch complete raw observation records |
The official documentation describes this progressive lookup pattern as a roughly 10x reduction in token usage for context loading. Independent benchmark data comes from its Smart Explore test suite. Across a repository containing 194 TypeScript files, context-aware search powered by Smart Explore consumed around 14,000 tokens. By contrast, traditional exploration workflows built on Glob, Grep and Read operations required approximately 250,000 tokens, marking a 17.8x difference in token consumption. It is important to note this benchmark runs on the project’s own codebase. Actual token savings will vary significantly based on repository structure and task patterns for individual teams.
Why claude-mem Gained 100,000 Stars
Native coding agents suffer from a fundamental limitation: every brand-new session begins with no persistent memory. When developers resume work the next day, the agent must re-read source files, re-understand the directory layout and re-discover previously resolved bugs. This repeated re-interpretation dominates token spending for long-running agent workflows. claude-mem directly targets this pain point by helping agents retain knowledge accumulated across disconnected sessions.
Its compatibility extends well beyond Claude Code. Supported agent clients include:
- Claude Code (installed via the plugin marketplace)
- OpenCode 1.3.4 and newer releases, including OpenCode 2
- T3 Code, with support for both Codex and Claude Code providers
- Antigravity CLI, Pi, DeepSeek Harness, OpenClaw gateway and other agent runtimes
The project also maintains an aggressive release cadence. Between October 28 and October 29, three sequential versions v15.4.0, v15.5.0 and v15.6.0 shipped in quick succession. The v15.5.0 update introduced batch processing support for observation records through any OpenAI-compatible endpoint, expanding flexibility for users running third-party observer models.
The Hidden Cost: Memory Compression Also Consumes Tokens
While claude-mem cuts the token load for the primary agent conversation, every captured tool call triggers a request to the observer model. Official documentation includes an explicit warning about scaling risk. Complex multi-agent workflows can spawn dozens to hundreds of child agents. Each tool call from every child agent generates a new observation entry. Under heavy load, a single run can produce hundreds of records, which can rapidly exhaust the quota of the selected model.
The default observer is Claude Haiku, which shares quota allocation with the primary Claude session within the same Anthropic billing plan. Users who register for claude-mem’s managed observer service receive a 30-day free trial. Once the trial expires, the plugin automatically falls back to the user’s Anthropic plan unless an alternate endpoint is configured.
The official guidance for cost optimization is straightforward: observation records follow a fixed, structured format and do not require frontier reasoning capability. Users can route compression jobs to smaller, low-cost models instead. claude-mem exposes the CLADE_MEM_PROVIDER environment variable to switch the backend to openai-compatible. Predefined configurations are built in for DeepSeek, MiniMax, Spark, Ollama and vLLM, and users can define fully custom base URLs. Teams managing multiple model endpoints often rely on unified routing to isolate low-priority compression workloads from high-stakes coding inference. 4sapi, an API gateway, can consolidate these provider endpoints, centralize usage logging and enforce rate limits for observer traffic.
Step-by-Step Setup: Install claude-mem and Swap the Observer Model
The following walkthrough targets Claude Code, and the full setup generally takes roughly 10 minutes.
Step 1: Installation
The official package installation command only deploys the SDK and will not automatically register plugin hooks. Users need to execute the dedicated install command below:
For installation inside Claude Code’s native plugin marketplace, run the marketplace add command first:
For OpenCode users, substitute the IDE flag:
Step 2: Configure the OpenAI-Compatible Observer
Edit the configuration file located at ~/.claude-mem/settings.json. For teams subscribed to the 4sapi token plan, the OpenAI-compatible endpoint exposes lightweight models such as DeepSeek V4.1 Flash and GLM-5.3 Flash, which fit compression workloads well.
Security best practices advise against placing API keys directly inside settings.json. Store credentials separately within ~/.claude-mem/.env:
Selected configuration parameters control runtime behavior:
OBSERVATION_BATCH_SIZE: Merges sequential observation entries into one API request. Valid values range from 1 to 32, with a default value of 1. Increasing this value reduces total request count.SKIP_AGENT_TYPES: Suppresses logging for specified agent categories, preventing uncontrolled record explosion in multi-agent pipelines.code-zh: Built-in mode that generates observation summaries in simplified Chinese, requiring no extra third-party translation service.
Step 3: Restart and Validate
Reopen Claude Code. Index summaries from prior sessions will appear automatically at the start of new conversations. Users can visit the worker address printed on startup to access the /viewer dashboard, which displays all stored memories, session history and observation metadata.
Step 4: Audit Observer Token Consumption
After running the plugin for several working days, review token consumption statistics on your gateway platform to quantify the overhead from compression tasks. Many lightweight plans include off-peak discount tiers; running observer jobs during discounted time windows can further reduce operational expenditure.
Deployment Decision Guide: When claude-mem Delivers Net Value
The plugin delivers positive ROI under these scenarios:
- Developers work continuously within the same code repository for days or weeks and repeatedly explain prior work state to the agent.
- Teams need shared historical context. The built-in TeamBrain feature allows users to selectively share observation records with collaborators.
It is less suitable for:
- One-off short scripts or ad-hoc question sessions, where the cost of observer compression outweighs token savings from context injection.
- Uncontrolled parallel multi-agent pipelines without careful tuning of
SKIP_AGENT_TYPES. Record volume can grow far beyond expectations and erase all cost benefits.
For privacy, all memory records persist locally under the ~/.claude-mem/ directory. Content wrapped with <private> tags is excluded from storage. The v15.5.0 release added automatic redaction for tokens, secrets and API keys within observation records. Cloud synchronization is disabled by default and must be manually activated by users.
Frequently Asked Questions
Q: How is claude-mem different from the native CLAUDE.md file supported by Claude Code?
A: CLAUDE.md stores static rules, project conventions and handwritten documentation. These contents remain fixed unless manually edited. claude-mem captures dynamic runtime memory generated during agent execution. The two tools work well together: static standards live inside CLAUDE.md, while evolving session history is managed by claude-mem.
Q: Can the observer run entirely on local models without Anthropic quota?
A: Yes. The observer backend supports Ollama, LM Studio and vLLM. Simply populate the OpenAI-compatible base URL and local model ID, and no cloud API key is required. If the target model ID cannot be resolved, the plugin falls back to the default Anthropic provider.
Q: What happens once the observer quota is exhausted?
A: Behavior is governed by CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER. It can be configured to revert to an Anthropic subscription, switch to a secondary OpenAI-compatible endpoint, or stop compression work entirely with the off setting.
Conclusion
claude-mem addresses a long-standing pain point for coding agents: amnesia across separate chat sessions. Its hook + lightweight observer compression + indexed retrieval architecture trades a small amount of background token overhead for massive cuts to the context window size loaded into each new agent turn. Official tests demonstrate up to 17.8x token reduction for repository exploration workflows, though this ratio is heavily workload-dependent.
The most impactful optimization is decoupling the compression observer from expensive frontier models. Routing observation tasks to cheaper lightweight endpoints is the key to achieving net token savings. Users must also apply guardrails for multi-agent workloads to avoid uncontrolled record generation and secret leakage. The project continues rapid iteration, and configuration settings should be cross-referenced against the official documentation at docs.claude-mem.ai for the latest v15.6.0 specification.
