claude-mem

Claude-mem is an open-source persistent memory engine built specifically for AI coding agents like Claude Code, Codex, Gemini CLI, and OpenCode. It solves one of the most frustrating limitations of session-based AI assistants: the fact that every new session starts cold, with no knowledge of what was done before. Claude-mem intercepts the agent lifecycle through hooks, records every tool call and observation, then uses a background AI worker to compress that raw activity into structured, searchable memory.

The system is built around a five-hook lifecycle — SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd — that work invisibly alongside your existing workflow. A background Bun worker service handles compression, storage in SQLite, and optional semantic indexing via ChromaDB. At the start of each new session, the most relevant past observations are retrieved using hybrid full-text and vector search, then injected into the agent’s context window via progressive disclosure to keep token costs under control.

Beyond passive memory, claude-mem ships with a full MCP server exposing search tools directly to the agent, a real-time web viewer UI at localhost:37777, and a growing library of skills for the Claude Code plugin marketplace. The installation is a single npx command, and the plugin is also available through the Claude Code marketplace. Support spans multiple AI runtimes, with adapters for Cursor, Gemini CLI, OpenCode, and OpenClaw gateway deployments.

With over 83,000 stars and roughly 175 commits per month, claude-mem has emerged as the de facto memory layer for AI-assisted development workflows. It is released under the Apache 2.0 license, with the open-source core covering the memory engine, server, SDK, MCP tools, and all adapters.

What You Get

• Five lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) that capture everything the agent does without interrupting the workflow
• A background Bun worker service running an HTTP API on port 37777 that handles AI compression, SQLite storage, and optional ChromaDB vector indexing
• Progressive disclosure context injection that surfaces layered memory at session start while displaying token cost so you stay in control of context window usage
• An MCP server with three search tools (search, timeline, get_observations) enabling the agent to query its own memory using natural language with a ~10x token efficiency pattern
• A real-time web viewer UI at http://localhost:37777 for browsing observation streams, session timelines, and raw memories with full citation support
• Privacy controls via <private> tags to exclude sensitive content from being stored, plus fine-grained settings in ~/.claude-mem/settings.json
• Multi-runtime adapter support for Claude Code, Gemini CLI, Cursor, OpenCode, Codex, and OpenClaw gateways with a single install command per target

Common Use Cases

• Long-running refactors where the agent needs to remember which files were changed and why across multiple sessions spanning days or weeks
• Debugging investigations where past observations about error patterns, tried fixes, and environment quirks should inform the next debugging session
• Learning a new codebase incrementally, so each session builds on what the agent previously explored rather than re-reading the same files
• Team handoff workflows on OpenClaw gateways where multiple agents or team members share a common memory pool about a project
• Auditing AI-assisted development by reviewing the observation stream in the web viewer to understand exactly what the agent did and decided
• Building memory-aware agent pipelines where the MCP search tools let downstream agents query past work before beginning new tasks

Under The Hood

Architecture Claude-mem is structured as a layered event-driven system with a clear separation between the hook execution plane, the worker service plane, and the storage plane. Lifecycle hooks (thin scripts that call out to the worker HTTP API) are completely decoupled from the compression and retrieval logic, which lives in the background Bun worker. That worker itself is organized into discrete services — SessionManager, DatabaseManager, ClaudeProvider, SearchManager, SSEBroadcaster — each with a single responsibility and no cross-cutting dependencies. Context injection is handled through a ContextBuilder pipeline with pluggable renderers (header, timeline, summary, footer sections) and a TokenCalculator that enforces budget limits. The sync layer managing ChromaDB is similarly isolated behind ChromaSync and ChromaMcpManager abstractions. The result is a system where each layer can fail or be replaced independently, and the plugin degrades gracefully when optional components like ChromaDB are absent.

Tech Stack The entire system is TypeScript compiled to ESM, targeting Node.js 20+ and Bun 1.0+. The worker service runs under Bun for its native SQLite bindings and fast startup, while the npm CLI and install scripts run under Node.js for maximum compatibility. Storage is split between SQLite (via Bun’s built-in bindings and the bun:sqlite module) for structured session data, observations, and FTS5 full-text search, and ChromaDB (managed via uv/Python and connected through the MCP protocol) for optional vector embeddings. The web viewer UI is React 19 built with esbuild and served from the worker’s Express 5 HTTP server. The AI compression agent uses the @anthropic-ai/claude-agent-sdk, and MCP connectivity uses the @modelcontextprotocol/sdk. BullMQ with ioredis backs the optional async job queue, and Better Auth provides API key management for the server endpoint.

Code Quality The codebase shows extensive investment in correctness — 198 test files covering hook lifecycle, SQLite schema migrations, context injection, MCP integrations, install error matrices, and worker spawning edge cases. Tests run under Bun’s native test runner. TypeScript strict mode is enabled throughout, and the code uses typed schemas with Zod for runtime validation. Error handling is largely explicit: the parser returns a discriminated union (ParseResult), the worker handles native module rebuild failures gracefully, and a dedicated FallbackErrorHandler manages Claude API error classification. CI runs on both Linux and Windows with dedicated workflows. Custom lint scripts check hook I/O discipline and spawn environment hygiene — domain-specific rules that standard linters would miss. The main area of complexity is the worker service entry point, which accumulates substantial setup logic, but the rest of the modules maintain good altitude and single responsibility.

What Makes It Unique Claude-mem’s core innovation is treating AI compression as a first-class pipeline stage rather than a post-processing afterthought. Instead of dumping raw transcript text into a vector store, the system uses the Claude Agent SDK to extract structured semantic summaries — typed observations with facts, narrative, concepts, and file lists — before storage. This structured intermediate representation enables the three-layer MCP search workflow (search index → timeline context → full observation fetch) that achieves dramatic token efficiency without sacrificing recall. The progressive disclosure injection strategy — surfacing layered memory with visible token cost at session start — is a thoughtful solution to the context window budget problem that most memory systems ignore. The worktree adoption feature, which automatically merges memory from merged git branches, is a developer-workflow-specific innovation with no known analog in general-purpose memory libraries.

Self-Hosting

Claude-mem is released under the Apache License 2.0, which grants broad rights to use, modify, distribute, and commercially deploy the software without restriction. The license includes an explicit patent grant — meaningful for a memory engine that may be embedded in proprietary agent systems — and only requires attribution and preservation of the license notice. There are no copyleft obligations, so you can integrate the library or fork the server into closed-source products without opening your own code.

Running claude-mem yourself is straightforward for a single developer but carries real operational weight at scale. The system depends on Bun (auto-installed) and uv/Python (auto-installed for Chroma), and the worker process must stay alive as a background daemon for memory compression to happen. SQLite handles persistence locally; ChromaDB is optional but required for semantic vector search. For team deployments on OpenClaw gateways, the installer handles more of the configuration, but you remain responsible for keeping the worker running, managing the data directory at ~/.claude-mem/, rotating logs, and handling upgrades — which ship as frequent npm releases (the repo averages 175 commits per month).

There is no official hosted cloud or managed tier. The license docs explicitly note that enterprise features, team sync, hosted cloud, and premium knowledge agents are reserved outside the Apache-2.0 public implementation. What this means in practice: you get no SLA, no managed backups, no high-availability setup, and no vendor support contract. The community is active (GitHub Discussions and Discord), documentation is thorough at docs.claude-mem.ai, and the codebase evolves rapidly — but upgrades are self-managed, and any production deployment is your responsibility.