claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

90,564 stars JavaScript Markdown Skills API Spec #ai#ai-agents#ai-memory#anthropic
AI Prompts & Specs

Repository: thedotmack/claude-mem


Stars: 61056

CLAUDE.md

Claude-Mem: AI Development Instructions

Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.

Architecture

5 Lifecycle Hooks: SessionStart → UserPromptSubmit → PostToolUse → Summary → SessionEnd

Hooks (src/hooks/.ts) - TypeScript → ESM, built to plugin/scripts/-hook.js

Worker Service (src/services/worker-service.ts) - Express API on port 37777, Bun-managed, handles AI processing asynchronously

Database (src/services/sqlite/) - SQLite3 at ~/.claude-mem/claude-mem.db

Search Skill (plugin/skills/mem-search/SKILL.md) - HTTP API for searching past work, auto-invoked when users ask about history

Planning Skill (plugin/skills/make-plan/SKILL.md) - Orchestrator instructions for creating phased implementation plans with documentation discovery

Execution Skill (plugin/skills/do/SKILL.md) - Orchestrator instructions for executing phased plans using subagents

Chroma (src/services/sync/ChromaSync.ts) - Vector embeddings for semantic search

Viewer UI (src/ui/viewer/) - React interface at http://localhost:37777, built to plugin/ui/viewer.html

Privacy Tags


- <private>content</private> - User-level privacy control (manual, prevents storage)

Implementation: Tag stripping happens at hook layer (edge processing) before data reaches worker/database. See src/utils/tag-stripping.ts for shared utilities.

Build Commands

bash
npm run build-and-sync        # Build, sync to marketplace, restart worker

Configuration

Settings are managed in ~/.claude-mem/settings.json. The file is auto-created with defaults on first run.

File Locations

- Source: <project-root>/src/
- Built Plugin: <project-root>/plugin/
- Installed Plugin: ~/.claude/plugins/marketplaces/thedotmack/
- Database: ~/.claude-mem/claude-mem.db
- Chroma: ~/.claude-mem/chroma/

Exit Code Strategy

Claude-mem hooks use specific exit codes per Claude Code's hook contract:

- Exit 0: Success or graceful shutdown (Windows Terminal closes tabs)
- Exit 1: Non-blocking error (stderr shown to user, continues)
- Exit 2: Blocking error (stderr fed to Claude for processing)

Philosophy: Worker/hook errors exit with code 0 to prevent Windows Terminal tab accumulation. The wrapper/plugin layer handles restart logic. ERROR-level logging is maintained for diagnostics.

See private/context/claude-code/exit-codes.md for full hook behavior matrix.

Requirements

- Bun (all platforms - auto-installed if missing)
- uv (all platforms - auto-installed if missing, provides Python for Chroma)
- Node.js

Documentation

Public Docs: https://docs.claude-mem.ai (Mintlify)
Source: docs/public/ - MDX files, edit docs.json for navigation
Deploy: Auto-deploys from GitHub on push to main

Pro Features Architecture

Claude-mem is designed with a clean separation between open-source core functionality and optional Pro features.

Open-Source Core (this repository):

- All worker API endpoints on localhost:37777 remain fully open and accessible
- Pro features are headless - no proprietary UI elements in this codebase
- Pro integration points are minimal: settings for license keys, tunnel provisioning logic
- The architecture ensures Pro features extend rather than replace core functionality

Pro Features (coming soon, external):

- Enhanced UI (Memory Stream) connects to the same localhost:37777 endpoints as the open viewer
- Additional features like advanced filtering, timeline scrubbing, and search tools
- Access gated by license validation, not by modifying core endpoints
- Users without Pro licenses continue using the full open-source viewer UI without limitation

This architecture preserves the open-source nature of the project while enabling sustainable development through optional paid features.

Important

No need to edit the changelog ever, it's generated automatically.


README.md

<h1 align="center">
<br>
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
</picture>
</a>
<br>
</h1>

<p align="center">
<a href="docs/i18n/README.zh.md">🇨🇳 中文</a> •
<a href="docs/i18n/README.zh-tw.md">🇹🇼 繁體中文</a> •
<a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •
<a href="docs/i18n/README.pt.md">🇵🇹 Português</a> •
<a href="docs/i18n/README.pt-br.md">🇧🇷 Português</a> •
<a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
<a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
<a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
<a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •
<a href="docs/i18n/README.he.md">🇮🇱 עברית</a> •
<a href="docs/i18n/README.ar.md">🇸🇦 العربية</a> •
<a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •
<a href="docs/i18n/README.pl.md">🇵🇱 Polski</a> •
<a href="docs/i18n/README.cs.md">🇨🇿 Čeština</a> •
<a href="docs/i18n/README.nl.md">🇳🇱 Nederlands</a> •
<a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a> •
<a href="docs/i18n/README.uk.md">🇺🇦 Українська</a> •
<a href="docs/i18n/README.vi.md">🇻🇳 Tiếng Việt</a> •
<a href="docs/i18n/README.tl.md">🇵🇭 Tagalog</a> •
<a href="docs/i18n/README.id.md">🇮🇩 Indonesia</a> •
<a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •
<a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
<a href="docs/i18n/README.bn.md">🇧🇩 বাংলা</a> •
<a href="docs/i18n/README.ur.md">🇵🇰 اردو</a> •
<a href="docs/i18n/README.ro.md">🇷🇴 Română</a> •
<a href="docs/i18n/README.sv.md">🇸🇪 Svenska</a> •
<a href="docs/i18n/README.it.md">🇮🇹 Italiano</a> •
<a href="docs/i18n/README.el.md">🇬🇷 Ελληνικά</a> •
<a href="docs/i18n/README.hu.md">🇭🇺 Magyar</a> •
<a href="docs/i18n/README.fi.md">🇫🇮 Suomi</a> •
<a href="docs/i18n/README.da.md">🇩🇰 Dansk</a> •
<a href="docs/i18n/README.no.md">🇳🇴 Norsk</a>
</p>

<h4 align="center">Persistent memory compression system built for <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>

<p align="center">
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
</a>
<a href="package.json">
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
</a>
<a href="https://github.com/thedotmack/awesome-claude-code">
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
</a>
</p>

<p align="center">
<a href="https://trendshift.io/repositories/15496" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
</picture>
</a>
</p>

<br>

<table align="center">
<tr>
<td align="center">
<a href="https://github.com/thedotmack/claude-mem">
<picture>
<img
src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif"
alt="Claude-Mem Preview"
width="500"
>
</picture>
</a>
</td>
<td align="center">
<a href="https://www.star-history.com/#thedotmack/claude-mem&Date">
<picture>
<source
media="(prefers-color-scheme: dark)"
srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&theme=dark&legend=top-left"
/>
<source
media="(prefers-color-scheme: light)"
srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
/>
<img
alt="Star History Chart"
src="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
width="500"
/>
</picture>
</a>
</td>
</tr>
</table>

<p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#how-it-works">How It Works</a> •
<a href="#mcp-search-tools">Search Tools</a> •
<a href="#documentation">Documentation</a> •
<a href="#configuration">Configuration</a> •
<a href="#troubleshooting">Troubleshooting</a> •
<a href="#license">License</a>
</p>

<p align="center">
Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.
</p>

---

Quick Start

Install with a single command:

bash
npx claude-mem install

Or install for Gemini CLI (auto-detects ~/.gemini):

bash
npx claude-mem install --ide gemini-cli

Or install for OpenCode:

bash
npx claude-mem install --ide opencode

Or install from the plugin marketplace inside Claude Code:

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

Restart Claude Code or Gemini CLI. Context from previous sessions will automatically appear in new sessions.

Note: Claude-Mem is also published on npm, but npm install -g claude-mem installs the SDK/library only — it does not register the plugin hooks or set up the worker service. Always install via npx claude-mem install or the /plugin commands above.

🦞 OpenClaw Gateway

Install claude-mem as a persistent memory plugin on OpenClaw gateways with a single command:

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

The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the OpenClaw Integration Guide for details.

Key Features:

- 🧠 Persistent Memory - Context survives across sessions
- 📊 Progressive Disclosure - Layered memory retrieval with token cost visibility
- 🔍 Skill-Based Search - Query your project history with mem-search skill
- 🖥️ Web Viewer UI - Real-time memory stream at http://localhost:37777
- 💻 Claude Desktop Skill - Search memory from Claude Desktop conversations
- 🔒 Privacy Control - Use <private> tags to exclude sensitive content from storage
- ⚙️ Context Configuration - Fine-grained control over what context gets injected
- 🤖 Automatic Operation - No manual intervention required
- 🔗 Citations - Reference past observations with IDs (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)
- 🧪 Beta Channel - Try experimental features like Endless Mode via version switching

---

Documentation

📚 View Full Documentation - Browse on official website

Getting Started

- Installation Guide - Quick start & advanced installation
- Gemini CLI Setup - Dedicated guide for Google's Gemini CLI integration
- Usage Guide - How Claude-Mem works automatically
- Search Tools - Query your project history with natural language
- Beta Features - Try experimental features like Endless Mode

Best Practices

- Context Engineering - AI agent context optimization principles
- Progressive Disclosure - Philosophy behind Claude-Mem's context priming strategy

Architecture

- Overview - System components & data flow
- Architecture Evolution - The journey from v3 to v5
- Hooks Architecture - How Claude-Mem uses lifecycle hooks
- Hooks Reference - 7 hook scripts explained
- Worker Service - HTTP API & Bun management
- Database - SQLite schema & FTS5 search
- Search Architecture - Hybrid search with Chroma vector database

Configuration & Development

- Configuration - Environment variables & settings
- Development - Building, testing, contributing
- Troubleshooting - Common issues & solutions

---

How It Works

Core Components:

1. 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
2. Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook)
3. Worker Service - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
4. SQLite Database - Stores sessions, observations, summaries
5. mem-search Skill - Natural language queries with progressive disclosure
6. Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval

See Architecture Overview for details.

---

MCP Search Tools

Claude-Mem provides intelligent memory search through 4 MCP tools following a token-efficient 3-layer workflow pattern:

The 3-Layer Workflow:

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

How It Works:
- Claude uses MCP tools to search your memory
- Start with search to get an index of results
- Use timeline to see what was happening around specific observations
- Use get_observations to fetch full details for relevant IDs
- ~10x token savings by filtering before fetching details

Available MCP Tools:

1. search - Search memory index with full-text queries, filters by type/date/project
2. timeline - Get chronological context around a specific observation or query
3. get_observations - Fetch full observation details by IDs (always batch multiple IDs)

Example Usage:

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

See Search Tools Guide for detailed examples.

---

Beta Features

Claude-Mem offers a beta channel with experimental features like Endless Mode (biomimetic memory architecture for extended sessions). Switch between stable and beta versions from the web viewer UI at http://localhost:37777 → Settings.

See Beta Features Documentation for details on Endless Mode and how to try it.

---

System Requirements

- Node.js: 18.0.0 or higher
- Claude Code: Latest version with plugin support
- Bun: JavaScript runtime and process manager (auto-installed if missing)
- uv: Python package manager for vector search (auto-installed if missing)
- SQLite 3: For persistent storage (bundled)

---

Windows Setup Notes

If you see an error like:

powershell
npm : The term 'npm' is not recognized as the name of a cmdlet

Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation.

---

Configuration

Settings are managed in ~/.claude-mem/settings.json (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings.

See the Configuration Guide for all available settings and examples.

Mode & Language Configuration

Claude-Mem supports multiple workflow modes and languages via the CLAUDE_MEM_MODE setting.

This option controls both:
- The workflow behavior (e.g. code, chill, investigation)
- The language used in generated observations

#### How to Configure

Edit your settings file at ~/.claude-mem/settings.json:

json
{
  "CLAUDE_MEM_MODE": "code--zh"
}

Modes are defined in plugin/modes/. To see all available modes locally:

bash
ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

#### Available Modes

| Mode | Description |
|------------|-------------------------|
| code | Default English mode |
| code--zh | Simplified Chinese mode |
| code--ja | Japanese mode |

Language-specific modes follow the pattern code--[lang] where [lang] is the ISO 639-1 language code (e.g., zh for Chinese, ja for Japanese, es for Spanish).

Note: code--zh (Simplified Chinese) is already built-in — no additional installation or plugin update is required.

#### After Changing Mode

Restart Claude Code to apply the new mode configuration.
---

Development

See the Development Guide for build instructions, testing, and contribution workflow.

---

Troubleshooting

If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.

See the Troubleshooting Guide for common issues and solutions.

---

Bug Reports

Create comprehensive bug reports with the automated generator:

bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Update documentation
5. Submit a Pull Request

See Development Guide for contribution workflow.

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.

See the LICENSE file for full details.

What This Means:

- You can use, modify, and distribute this software freely
- If you modify and deploy on a network server, you must make your source code available
- Derivative works must also be licensed under AGPL-3.0
- There is NO WARRANTY for this software

Note on Ragtime: The ragtime/ directory is licensed separately under the PolyForm Noncommercial License 1.0.0. See ragtime/LICENSE for details.

---

Support

- Documentation: docs/
- Issues: GitHub Issues
- Repository: github.com/thedotmack/claude-mem
- Official X Account: @Claude_Memory
- Official Discord: Join Discord
- Author: Alex Newman (@thedotmack)

---

Built with Claude Agent SDK | Powered by Claude Code | Made with TypeScript

---

What About $CMEM?

$CMEM is a solana token created by a 3rd party without Claude-Mem's prior consent, but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing real-time agent data to the developers and knowledge workers that need it most. $CMEM: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS