claude-mem: Persistent Context Across Sessions for AI Agents

Introduction

claude-mem is a powerful open-source repository by thedotmack that provides persistent context across sessions for various AI agents. It addresses a critical challenge in AI development: enabling agents to retain and leverage knowledge from past interactions. By automatically capturing agent activities, compressing them with AI, and injecting relevant context into future sessions, claude-mem ensures a continuous and intelligent workflow. This system is designed to work seamlessly with a wide array of AI platforms, including Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, and OpenCode, making it an invaluable tool for developers building sophisticated AI applications.

Installation

Getting started with claude-mem is straightforward. The primary installation method is via npx:

npx claude-mem install

For specific IDEs, you can use the --ide flag:

# For Gemini CLI (auto-detects ~/.gemini)
npx claude-mem install --ide gemini-cli

# For OpenCode
npx claude-mem install --ide opencode

If you are using Claude Code, you can install it directly from the plugin marketplace:

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

After installation, restart your AI environment (e.g., Claude Code or Gemini CLI) for the changes to take effect. Context from previous sessions will then automatically appear in new sessions.

Note: While claude-mem is also on npm, npm install -g claude-mem only installs the SDK/library and does not set up the necessary plugin hooks or worker service. Always use npx claude-mem install or the /plugin commands for full functionality.

For OpenClaw Gateway integration, use the dedicated installer:

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

Examples

claude-mem enhances AI agent capabilities with intelligent memory search through a token-efficient, 3-layer workflow pattern. This approach optimizes context retrieval, saving tokens and improving performance.

The 3-Layer Workflow:

search: Get a compact index with IDs (e.g., ~50-100 tokens per result).
timeline: Get chronological context around interesting results.
get_observations: Fetch full details ONLY for filtered IDs (e.g., ~500-1,000 tokens per result).

Here's an example of how to use these tools:

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

This method allows AI agents to efficiently query their memory, focusing on relevant information and significantly reducing token usage compared to fetching full details upfront.

Why Use It

claude-mem offers a suite of features designed to elevate the performance and intelligence of your AI agents:

Persistent Memory: Ensures context survives across sessions, allowing agents to build on past knowledge.
Progressive Disclosure: Provides layered memory retrieval with clear token cost visibility, optimizing resource usage.
Skill-Based Search: Query your project history using natural language with the mem-search skill.
Web Viewer UI: A real-time memory stream available at http://localhost:37777 for easy monitoring and debugging.
Privacy Control: Use <private> tags to exclude sensitive content from storage, maintaining data confidentiality.
Automatic Operation: Requires no manual intervention, seamlessly integrating into your agent's workflow.
Token Savings: The 3-layer search workflow provides approximately 10x token savings by filtering before fetching full details.

By integrating claude-mem, developers can empower their AI agents with robust, long-term memory capabilities, leading to more coherent, efficient, and intelligent interactions.