claude-mem: Persistent Memory Across Sessions for AI Coding Agents

The Problem: AI Agents Forget Everything Between Sessions

An AI coding agent like Claude Code starts each session with only the context it can read from the project's files and any CLAUDE.md memory files that are already in place. When a session ends, every decision the agent made, every bug it debugged, and every architectural choice it worked through is gone from its context unless someone manually documented it. The next session starts blind.

The README describes claude-mem as a persistent context system that captures everything an agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. The package description states it works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode, and others.

This is distinct from a project's CLAUDE.md file. A CLAUDE.md file captures what a developer manually chooses to document. claude-mem captures what the agent actually does, including tool calls, decisions, bug fixes, and security observations, and uses a separate AI pass to compress that activity into summaries small enough to inject as context.

How claude-mem Captures and Compresses Context

The README describes three steps: capture, compress, and inject. During a session, the plugin observes tool usage by the agent. This observation is handled differently per host. For hosts with hook support, claude-mem registers hooks in the agent's configuration. For hosts without hooks (like Grok Bot), it watches the chat log files directly.

The package.json records dependencies including knowledge-graph and transcript in its keywords, and the docker-compose.yml describes a production stack with a claude-mem-server (HTTP, no generation) and a claude-mem-worker (BullMQ generation consumer backed by Postgres and Valkey). The worker handles the AI compression step: it reads the session transcript and generates semantic summaries.

The README describes a subset of observations as high-priority: decision, bugfix, security_alert, and sensitive. For the Grok Bot integration, these are appended as dated awareness lines into a monthly Markdown log file. The awareness feature can be disabled with CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false.

For Claude Code specifically, the README says to restart Claude Code after installation, after which context from previous sessions automatically appears in new sessions.

Installing claude-mem

The standard installation for Claude Code is:

npx claude-mem install

The installer sets everything up and then asks the user to sign in to claude-mem using an email magic link, with no payment card required. Signing in provisions a memory key and unlocks the claude-mem observer: a hosted memory service described in the README as free for up to 14 days, after which memory falls back to the user's Anthropic plan unless they subscribe.

To skip the sign-in entirely, pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or run in a CI or non-interactive shell.

For OpenCode:

npx claude-mem install --ide opencode

For the Claude Code plugin marketplace:

/plugin marketplace add thedotmack/claude-mem

For OpenClaw gateways:

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

The README includes a note that npm install -g claude-mem installs the SDK/library only and does not register plugin hooks or set up the worker service. The npx claude-mem install path is required for the full installation.

Memory Providers and Self-Hosting

After installation, the user picks a memory provider. The README lists three options: the claude-mem observer (the hosted service), an OpenRouter or Gemini API key, or the user's own Anthropic plan. The provider choice determines where the AI compression work runs and where the compressed summaries are stored.

For teams that need to keep session data off third-party servers, self-hosting is possible. The docker-compose.yml in the repository describes the required stack: a Postgres instance for canonical storage, a Valkey instance for BullMQ queues, a claude-mem-server container, and one or more claude-mem-worker containers. The worker count is scalable with docker compose up -d --scale claude-mem-worker=N.

The docker-compose.yml requires several environment variables at startup: CLAUDE_MEM_RUNTIME=server-beta, CLAUDE_MEM_QUEUE_ENGINE=bullmq, CLAUDE_MEM_SERVER_DATABASE_URL, CLAUDE_MEM_REDIS_URL, and CLAUDE_MEM_AUTH_MODE=api-key. The file explicitly states it must not be deployed unmodified to any environment reachable from the public internet, and that the Postgres credentials are required environment variables with no defaults.

The package.json records engine requirements for contributors: Node.js 20.12.0 or later and Bun 1.1.31 or later.

Limitations and Risks

The default installation routes session data through the claude-mem hosted service for compression. Developers working on codebases with confidential business logic, proprietary algorithms, or regulated data should evaluate whether sending session transcripts to a third-party server is acceptable before using the hosted provider.

The plugin is at version 13.28.0 with frequent minor releases, indicating rapid development. The README describes an OpenClaw gateway integration, an Antigravity CLI integration, a Grok Bot integration, and a Cursor integration, among others. A project maintaining integration points across this many hosts will face compatibility work each time a host changes its plugin API. Users should check the changelog before each update.

The awareness feature logs sensitive, security_alert, bugfix, and decision observations as dated lines in a monthly Markdown file. The README notes that for Grok Bot this writes to memory/log/YYYY-MM.md. This is useful for audit trails but also means security-sensitive observations are persisted as plaintext files on disk wherever that log directory is stored.

The npm install -g path installing only the SDK is a notable footgun. Developers who install via npm global and then find the plugin not working will need to re-run npx claude-mem install to get the hooks and worker service registered properly.

Versus Manually Maintained CLAUDE.md Files

The traditional approach to preserving context across Claude Code sessions is a CLAUDE.md file: a Markdown document in the project root that the developer maintains by hand, documenting architecture decisions, coding conventions, and project-specific facts. Claude Code reads this file at the start of each session.

Manually maintained CLAUDE.md files are explicit: the developer decides exactly what context to preserve and how to phrase it. Nothing is captured automatically, and nothing is sent to an external service. The trade-off is that it only captures what the developer chooses to write down. A session where the agent debugs a subtle race condition leaves no trace unless the developer updates the file afterward.

claude-mem captures automatically, which means it also captures everything: routine commands, exploratory tool calls, and dead ends alongside meaningful decisions. The compression step is meant to reduce this to what is relevant, but the quality of that compression depends on the AI provider and the prompt logic in the worker. A manual CLAUDE.md file has no such dependency.

Maintenance and License

The last push to the repository was on 2026-09-26. Version 13.28.0 was released that day, with 13.27.1 and 13.27.0 also released the same day. This is a very active release cadence: multiple releases per day are common in the changelog. The repository is not archived.

The project is licensed under Apache-2.0. The package.json also includes a NOTICE file in the repository, which is a common practice for Apache-2.0 licensed projects that incorporate other works. Apache-2.0 permits commercial use, modification, and redistribution, and requires preservation of the NOTICE file and attribution when distributing modified versions.

The repository includes a RECEIPT-JOIN.md file and several AI-oriented configuration directories (.agents/, .claude/, .codex/, .cursor/, .windsurf/), reflecting its focus on AI agent environments.

Editorial conclusion

Developers using Claude Code, OpenCode, or similar AI coding agents who find that relevant project context is lost between sessions are the primary audience for claude-mem. The tool installs with a single npx command and signs users into the hosted memory service by default. Teams that need to avoid sending session data to a third party should use the --provider flag to route compression through their own OpenRouter, Gemini, or Anthropic API key, or self-host using the Docker Compose stack in the repository. The last push was on 2026-09-26 and the project is under active development at version 13.28.0.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes