Claude-Mem: When AI Agents Can Remember Everything You've Done

Claude-Mem: When AI Agents Can Remember Everything You’ve Done

Last week, I opened Claude Code to continue the feature I was working on - and realized I had to explain the entire project context from scratch.

Why did I choose this pattern last time? Which file did I modify? What bug did I fix? Everything disappeared with the old session. Claude Code is a blank slate with each new session. So frustrating.

If you’ve ever experienced this feeling, Claude-Mem is exactly what you need.

What Is It?

Claude-Mem (GitHub: thedotmack/claude-mem) is an open-source plugin - now with over 46,000 stars on GitHub. A crazy number for a plugin. The simple reason: it solves the biggest pain when working with AI agents.

The way it works is also surprisingly simple:

1. Observe every tool call in the session (Read, Write, Edit, Bash…)
2. Compress information using AI into structured observations
3. Store in SQLite + vector database
4. Inject relevant context into the next session

One AI helping another take notes. Elegant.

And importantly - it’s not just for Claude Code. Claude-Mem supports Claude Code, OpenClaw, Codex, Gemini CLI, Copilot, OpenCode, Hermes, and many more.

Setup: 2 Lines, Done

If you use Claude Code:

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

Restart Claude Code. Context from the previous session will automatically appear in the new session. No additional configuration is needed.

For other agents:

# Gemini CLI
npx claude-mem install --ide gemini-cli

# OpenCode
npx claude-mem install --ide opencode

# OpenClaw (what I use)
curl -fsSL https://install.cmem.ai/openclaw.sh | bash

⚠️ A small trap: npm install -g claude-mem only installs the SDK/library, DOES NOT register hooks or start the worker. You must use npx claude-mem install or /plugin install to get it running. I spent 15 minutes debugging this, hope you don’t fall into the same trap 💀

Architecture Deep Dive

This is the part I enjoy the most - dissecting how Claude-Mem is designed.

Overview

Claude-Mem consists of 5 main components:

┌─────────────────────────────────────────────────────────────────┐
│                    CLAUDE CODE SESSION                           │
│                                                                  │
│  Setup → SessionStart → PromptSubmit → ToolUse → Stop → End    │
│    ↓          ↓              ↓           ↓        ↓       ↓     │
│  [check  [2 hooks]      [hook]      [hook]    [hook]  [hook]  │
└─────────────────────────────────────────────────────────────────┘
      ↓          ↓              ↓           ↓        ↓       ↓
┌─────────────────────────────────────────────────────────────────┐
│                    CLAUDE-MEM SYSTEM                             │
│                                                                  │
│  Worker Service (Express HTTP API, port 37777)                  │
│  SQLite Database (observations, sessions, FTS5 search)          │
│  Chroma Vector DB (semantic search, optional)                   │
│  React Viewer UI (real-time memory stream)                      │
└─────────────────────────────────────────────────────────────────┘

Tech stack:

• TypeScript (ES2022) + Node.js 20+ / Bun
• SQLite 3 with FTS5 full-text search
• Chroma (optional) for semantic search
• Express.js 5 for HTTP API
• React + TypeScript for Viewer UI
• Claude Agent SDK (or Gemini / OpenRouter) for AI compression

Hook System: The Heart of Everything

This is the most intelligent part of Claude-Mem. It does not modify Claude Code (which is a closed-source binary), but observes from the outside through lifecycle hooks.

The plugin registers 7 hook scripts for the entire lifecycle of a Claude Code session:

┌──────────────────┬──────────────────────────────────────────────┐
│ HOOK             │ NHIỆM VỤ                                     │
├──────────────────┼──────────────────────────────────────────────┤
│ Setup            │ Check version marker (<100ms, always exit 0) │
│ SessionStart #1  │ Start Bun worker if not running           │
│ SessionStart #2  │ Inject context from previous session into prompt    │
│ UserPromptSubmit │ Create session record + save raw prompt for FTS5 │
│ PostToolUse (*)  │ Capture observation from every tool call         │
│ Stop             │ Call Claude Agent SDK to create session summary     │
│ SessionEnd       │ Graceful cleanup, does not DELETE sessions      │
└──────────────────┴──────────────────────────────────────────────┘

Key insight: Each hook must run under 1 second. AI compression (which takes 5-30 seconds) is pushed to a background worker. Hooks only do one thing: receive data → push into queue → return immediately.

This is the part I respect the most. This design is similar to the message queue pattern in distributed systems - decoupling ingestion with processing. Hooks are producers, and workers are consumers.

Hook (fast, ~20ms)
  │
  ├─ Read stdin (<1ms)
  ├─ INSERT INTO observation_queue (<10ms)
  └─ Return success (<20ms total)
         │
         ▼ (queue)
Worker (slow, 5-30s)
  ├─ Poll observation_queue
  ├─ Claude Agent SDK compress observation
  └─ Save to observations table

Context Injection: Progressive Disclosure

The context injection part is also noteworthy. Instead of stuffing the entire history into the prompt (which costs a lot of tokens), the SessionStart hook only injects a lightweight index:

# [claude-mem recent context

**Legend:** 🎯 session-request | 🔴 gotcha | 🟡 problem-solution

### Oct 26, 2025

**General**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file empty | ~51 |
| #2590 | 01:15 AM | 🔴 | SQLite FTS5 query syntax | ~120 |

*Use MCP search tools to access full details*

Claude can use this index to decide whether to fetch full details or not. This mechanism is similar to L1/L2/L3 cache - fetching deeper costs more tokens, but only fetches when necessary.

Search Pipeline: 3-Layer Progressive Disclosure

This is the part that made me go “wow” when reading the source. Search in Claude-Mem is not just calling an API and dumping all the results. It’s like progressive disclosure - disclosing one layer at a time:

Layer 1: search() → Lightweight index (~50-100 tokens/result)
   ↓ Choose IDs of interest
Layer 2: timeline() → Context surrounding (~100-200 tokens/obs)
   ↓ Confirm IDs to read
Layer 3: get_observations() → Full details (~500-1000 tokens/obs)

Comparison of actual tokens:

Saves ~10x. With Claude’s API pricing, this is no joke.

Actual usage:

// Step 1: Search
search(query="authentication bug", type="bugfix", limit=10)

// Step 2: Review index, identify relevant IDs (e.g., #123, #456)

// Step 3: Fetch only what you need
get_observations(ids=[123, 456)

MCP tools are available: search, timeline, get_observations. Supports full FTS5 query syntax (AND, OR, NOT, phrase search, column-specific search).

Bonus: From v5.4.0+, there’s an additional mem-search skill - loads faster than MCP tools, saves an extra ~2,250 tokens per session.

Worker Service: The Background Brain

The worker is an Express.js HTTP server running on port 37700 + (uid % 100) (default 37777). Its main tasks:

• Search API: 10 endpoints for full-text search, timeline, observations
• Viewer UI: React app real-time memory stream via SSE (Server-Sent Events)
• Async Processing: Poll observation queue, use Claude Agent SDK to compress observations into structured learnings
• Multi-provider: Supports Claude Agent SDK, Gemini, or OpenRouter

The worker is managed by Bun - auto-start, auto-restart if it crashes. Also clean.

OpenClaw Integration

The part I’m most interested in because I use OpenClaw. OpenClaw’s embedded runner calls the Anthropic API directly - doesn’t spawn a claude process - so Claude Code hooks don’t fire. The Claude-Mem plugin for OpenClaw solves this problem by hooking into OpenClaw’s event system:

OpenClaw Gateway
  │
  ├── before_agent_start ───→ Init session
  ├── before_prompt_build ──→ Inject context into system prompt
  ├── tool_result_persist ──→ Record observation (fire-and-forget)
  ├── agent_end ────────────→ Summarize + Complete session
  └── gateway_start ────────→ Reset session tracking
                    │
                    ▼
         Claude-Mem Worker (localhost:37777)

Context is injected into the system prompt via appendSystemContext, without touching MEMORY.md. Caches for 60 seconds to avoid re-fetching every LLM turn.

Bonus: Observation feed - streams real-time observations to Telegram, Discord, Slack, Signal, WhatsApp, LINE. Each observation creates a message like:

🧠 Claude-Mem Observation
**Implemented retry logic for API client**
Added exponential backoff with configurable max retries

Feels like having an AI colleague sending Slack updates about what your agent is doing. Both useful and slightly creepy 😂

Advantages

✅ Multi-platform: Claude Code, OpenClaw, Codex, Gemini, Copilot, OpenCode, Hermes - a plugin for all

✅ Non-invasive: Does not modify agent behavior, only observes through hooks. If the plugin crashes, the agent still runs normally.

✅ Token-efficient: Progressive disclosure saves ~10x tokens compared to traditional RAG. With the current API price, this translates directly to money.

✅ Graceful cleanup: v4.1.0+ does not DELETE sessions, workers finish processing and exit on their own. Avoids race conditions and lost pending observations.

✅ Real-time viewer: Web UI at localhost:37777, view live memory stream. Features infinite scroll, project filtering, and GPU-accelerated animations.

✅ Multi-language: Supports 28+ languages - from Vietnamese, Chinese, Japanese, Korean to Hebrew, Arabic, Urdu, Bengali.

✅ OpenClaw native: Dedicated plugin, deeply integrated with the event system and multi-channel observation feed.

✅ Apache 2.0: Open-source, can be embedded into other tools. The reason for choosing this license is stated by the author: “durable agentic memory should be easy to embed in developer tools, local agents, MCP servers, enterprise systems, robotics stacks, and production agent harnesses.”

✅ Beta channel: Features Endless Mode - biomimetic memory architecture for extended sessions. For those who want to try the bleeding edge.

Weak Points

This is the most important part. I don’t want to write a PR article - so I’ll directly state what’s not okay.

1. SPOF: Worker Single Point of Failure

Worker is a single process. If it crashes, observations get stuck in the queue. There’s a recovery command (npm run queue:recover) but you have to actively check. No automatic health check, no alert. In production, this is not okay.

2. SQLite Not Suitable for Multi-User

Database is a local file ~/.claude-mem/claude-mem.db. Can’t be shared between multiple machines, no replication. Okay for personal development, not okay for teams. If you’re thinking of setting up Claude-Mem for a team of 5 people working on 1 project - forget it.

3. Chroma Optional, But Setup Not Simple

Semantic search needs a separate Chroma vector DB. By default, only FTS5 full-text search is available - i.e., keyword-based. If you want to search like “find bugs related to connection pooling” but the observation doesn’t have the words “connection pooling”, FTS5 will miss. Need Chroma for embedding-based search, but setting up Chroma adds complexity. Not the kind of “run and done”.

4. Token Cost for AI Compression

Each observation is compressed using Claude Agent SDK (or Gemini/OpenRouter). Many tool calls = many API calls = cost money. A 2-hour working session with Claude Code can generate 50-100 observations. Each compression costs ~500-1000 tokens. Calculated, it can cost a few USD per month just for “remembering”.

Docs don’t have a clear cost estimate. I have to measure it myself.

5. No Retention Policy

Observations accumulate without limit. No auto-cleanup, TTL, or archive policy. Database will grow over time. Using it for 6 months → several tens of MB. Using it for 2 years → can be several GB. No tool to prune old data.

6. Privacy: Local Storage, But Need to be Cautious

All observations are stored locally in SQLite. Okay for personal development. But if working with sensitive codebases (fintech, healthcare, internal company tools) - you need to know that all tool input/output is captured. There’s a tag exclusion (<private>) but it needs to be configured manually, no auto-detection.

7. Dependent on Claude Code Hook API

If Claude Code changes the hook API, the plugin must update. History has shown breaking changes from Claude Code v2.1.0 (ultrathink update) - SessionStart hooks no longer display user-visible messages. Not a fault of Claude-Mem, but a risk if you depend on it for your daily workflow.

Comparison With Alternatives

Bottom line: Claude-Mem excels in token efficiency and multi-agent support. Mem0/Zep excel in multi-user support. LangMem excels in simplicity. The choice depends on whether you use it alone or in a team, and whether you use Claude Code or LangChain.

Personally: if you use Claude Code or OpenClaw alone, Claude-Mem is the best on-premise choice currently. No need to think.

Verdict

Who should use:

• Devs working long-term on the same project with Claude Code/OpenClaw
• Want the agent to “remember” decisions, bug fixes, architecture choices between sessions
• Prioritize privacy (local storage), don’t want to send data to the cloud
• Want something that runs right after 2 lines of command, no need to read lengthy docs

When not to use:

• Short-term projects, one-off scripts - setup not worth the effort
• Teams need to share memory between multiple people - need cloud solutions like Mem0/Zep
• Limited budget for API calls - AI compression has hidden costs
• Working with extremely sensitive codebases - need to carefully audit what’s being captured

Rating: ⭐⭐⭐⭐ (4/5)

Deducted 1 star due to the lack of retention policy, worker SPOF, and unclear cost estimate. These are things a 46K-star plugin should have.

Overall, Claude-Mem is a must-have plugin for anyone who regularly uses Claude Code or OpenClaw. I’ve had it installed on OpenClaw for 2 weeks, and the most noticeable difference is: the agent no longer asks me questions I’ve already answered last week. It “knows” what I’ve done, what I’ve decided. It feels like having a new colleague - someone who’s read the team’s documentation before joining.

The feeling of opening Claude Code, seeing the context line, and thinking “ah yes, I was working on this last time” - it’s satisfying 😊.

Links:

• GitHub: https://github.com/thedotmack/claude-mem
• Docs: https://docs.claude-mem.ai
• OpenClaw Integration: https://docs.claude-mem.ai/openclaw-integration
• Discord: https://discord.com/invite/J4wttp9vDu

Have you tried Claude-Mem? Using any other solution for agent memory? Leave a comment, I want to hear 🦞