📦 thedotmack/claude-mem – 为每个 Agent 提供跨会话持久化记忆
英文标题：📦 thedotmack/claude-mem
Claude-Mem 是一个持久化记忆压缩系统，专为 Claude Code 构建，可自动捕获会话中 Agent 的工具使用行为并生成语义摘要，将相关上下文注入未来会话。它实现了跨会话的上下文连续性，支持 Claude Code、OpenClaw、Gemini、Copilot 等工具，并通过三层渐进披露搜索工作流节省约 10 倍 token 成本。该项目内置 Web 查看器、隐私控制及 Chroma 向量数据库，为开发者提供了低干预、可控的 Agent 长期记忆基础设施。
77.9 KB
77.7 KB
1.3 KB
1.3 KB
1.3 KB
8.0 KB
5.1 KB
5.1 KB
2.1 MB
31.2 KB
28.0 KB
247.1 KB
中文
🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk
专为 Claude Code 构建的持久化记忆压缩系统。
快速入门 • 工作原理 • 搜索工具 • 文档 • 配置 • 故障排除 • 许可证
Claude-Mem 通过自动捕获工具使用观察数据、生成语义摘要并将其提供给未来的会话，无缝地跨会话保留上下文。这使得 Claude 即使在会话结束或重新连接后，也能保持对项目知识的连续性。
只需一条命令安装：
或者为 OpenCode 安装：
npx claude-mem install --ide opencode
或者为 Antigravity CLI 安装（安装指南）：
npx claude-mem install --ide antigravity
或者从 Claude Code 的插件市场安装：
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
重启 Claude Code。之前会话的上下文将自动出现在新会话中。
注意： Claude-Mem 也发布在 npm 上，但
npm install -g claude-mem只会安装 SDK/库——它不会注册插件钩子或设置 worker 服务。请始终通过npx claude-mem install或上述/plugin命令进行安装。
通过一条命令将 claude-mem 作为持久化记忆插件安装在 OpenClaw 网关上：
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
安装程序会处理依赖项、插件设置、AI 提供商配置、worker 启动，以及可选的实时观察数据推送到 Telegram、Discord、Slack 等。详情请参阅 OpenClaw 集成指南。
核心功能：
- 🧠 持久化记忆 —— 上下文跨会话保留
- 📊 渐进披露 —— 分层记忆检索，token 成本可见
- 🔍 基于技能的搜索 —— 使用 mem-search 技能查询项目历史
- 🖥️ Web 查看器 UI —— 在 http://localhost:37777 实时查看记忆流
- 💻 Claude 桌面技能 —— 从 Claude 桌面对话中搜索记忆
- 🔒 隐私控制 —— 使用
<private>标记将敏感内容排除在存储之外 - ⚙️ 上下文配置 —— 细粒度控制注入哪些上下文
- 🤖 自动运行 —— 无需手动干预
- 🔗 引用 —— 通过 ID 引用过去的观察数据（通过 http://localhost:37777/api/observation/{id} 访问，或在 Web 查看器 http://localhost:37777 中查看全部）
- 🧪 Beta 频道 —— 通过版本切换体验无限模式等实验性功能
📚 查看完整文档 —— 在官方网站上浏览
配置与开发
核心组件：
- 5 个生命周期钩子 —— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 个钩子脚本）
- 智能安装 —— 缓存依赖检查器（预钩子脚本，非生命周期钩子）
- Worker 服务 —— 端口 37777 上的 HTTP API，具有 Web 查看器 UI 和 10 个搜索端点，由 Bun 管理
- SQLite 数据库 —— 存储会话、观察数据、摘要
- mem-search 技能 —— 自然语言查询，渐进披露
- Chroma 向量数据库 —— 混合语义 + 关键词搜索，实现智能上下文检索
详情请参阅 架构概述。
Claude-Mem 通过 4 个 MCP 工具 提供智能记忆搜索，遵循 token 高效的 3 层工作流模式：
3 层工作流：
search—— 获取带有 ID 的紧凑索引（每个结果约 50-100 token）timeline—— 获取与相关结果关联的时间线上下文get_observations—— 仅针对筛选后的 ID 获取完整详情（每个结果约 500-1,000 token）
工作原理：
- Claude 使用 MCP 工具搜索你的记忆
- 从
search开始获取结果索引 - 使用
timeline查看特定观察数据周围发生的情况 - 使用
get_observations获取相关 ID 的完整详情 - 在获取详情前筛选，节省约 10 倍 token
可用的 MCP 工具：
search—— 使用全文查询搜索记忆索引，按类型/日期/项目筛选timeline—— 获取特定观察数据或查询的时间线上下文get_observations—— 通过 ID 获取完整观察数据详情（始终批量处理多个 ID）
使用示例：
// Step 1: 搜索索引
search(query="authentication bug", type="bugfix", limit=10)
// Step 2: 审查索引，识别相关 ID（例如 #123、#456）
// Step 3: 获取完整详情
get_observations(ids=[123, 456])
详见 搜索工具指南。
Claude-Mem 提供一个 beta 频道，包含 无限模式（针对扩展会话的仿生记忆架构）等实验性功能。在 http://localhost:37777 → Settings 的 Web 查看器 UI 中切换稳定版和 beta 版。
详见 Beta 功能文档 了解无限模式及其试用方式。
- Node.js ：20.0.0 或更高版本
- Claude Code ：最新版本，支持插件
- Bun ：JavaScript 运行时和进程管理器（缺失时自动安装）
- uv ：Python 包管理器，用于向量搜索（缺失时自动安装）
- SQLite 3 ：用于持久化存储（已打包）
如果你看到类似以下错误：
npm : The term 'npm' is not recognized as the name of a cmdlet
请确保已安装 Node.js 和 npm 并添加到 PATH 中。从 https://nodejs.org 下载最新的 Node.js 安装程序，安装后重启终端。
设置在 ~/.claude-mem/settings.json 中进行管理（首次运行时自动创建，包含默认值）。配置 AI 模型、worker 端口、数据目录、日志级别和上下文注入设置。
详见 配置指南 查看所有可用设置和示例。
模式与语言配置
Claude-Mem 通过 CLAUDE_MEM_MODE 设置支持多种工作流模式和语言。
此选项同时控制：
- 工作流行为（例如 code、chill、investigation）
- 生成的观察数据所使用的语言
编辑位于 ~/.claude-mem/settings.json 的设置文件：
{
"CLAUDE_MEM_MODE": "code--zh"
}
模式定义在 plugin/modes/ 中。要在本地查看所有可用模式：
ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/
| 模式 | 描述 |
|---|---|
code |
默认英文模式 |
code--zh |
简体中文模式 |
code--ja |
日语模式 |
语言特定模式遵循 code--[lang] 格式，其中 [lang] 是 ISO 639-1 语言代码（例如 zh 代表中文，ja 代表日语，es 代表西班牙语）。
注意：
code--zh（简体中文）已内置——无需额外安装或更新插件。
重启 Claude Code 以应用新的模式配置。
详见 开发指南 了解构建说明、测试和贡献流程。
如果遇到问题，请向 Claude 描述问题，故障排除技能将自动诊断并提供修复。
详见 故障排除指南 了解常见问题和解决方案。
使用自动化生成器创建全面的 bug 报告：
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
欢迎贡献！请：
- Fork 仓库
- 创建特性分支
- 进行修改并测试
- 更新文档
- 提交 Pull Request
Claude-Mem 从三个分支发布：main（稳定版）、core-dev 和 community-edge。仅 main 分支发布到 npm；其他分支从源码运行。详见 发布分支 了解策略以及如何在本地运行非稳定版本。
详见 开发指南 了解贡献流程。
Claude-Mem 根据 Apache License 2.0 许可。
我们选择 Apache-2.0，是因为持久的 Agent 记忆应当易于嵌入开发者工具、本地 Agent、MCP 服务器、企业系统、机器人技术栈和生产级 Agent 框架中。
详见 LICENSE 文件获取完整细节。查看 docs/license.md 和 docs/ip-boundary.md 了解许可范围及开源/商业边界。
关于 Ragtime 的说明 ：ragtime/ 目录基于 Apache License 2.0 许可。详见 ragtime/LICENSE。
使用 Claude Agent SDK 构建 | 与 Claude Code 配合使用 | 使用 TypeScript 制作
CMEM 是由第三方创建的代币，但得到了 Claude-Mem 创建者（Alex Newman，@thedotmack）的正式认可。该代币充当社区增长的催化剂，也是将 CMEM 带给最需要它的开发者和知识工作者的载体。
官方 BASE CA：0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3
English / 原文
🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk
Persistent memory compression system built for Claude Code.
Quick Start • How It Works • Search Tools • Documentation • Configuration • Troubleshooting • License
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.
Install with a single command:
Or install for OpenCode:
npx claude-mem install --ide opencode
Or install for Antigravity CLI (setup guide):
npx claude-mem install --ide antigravity
Or install from the plugin marketplace inside Claude Code:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
Note: Claude-Mem is also published on npm, but
npm install -g claude-meminstalls the SDK/library only — it does not register the plugin hooks or set up the worker service. Always install vianpx claude-mem installor the/plugincommands above.
Install claude-mem as a persistent memory plugin on OpenClaw gateways with a single command:
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
📚 View Full Documentation - Browse on official website
Configuration & Development
Core Components:
- 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
- Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook)
- Worker Service - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
- SQLite Database - Stores sessions, observations, summaries
- mem-search Skill - Natural language queries with progressive disclosure
- Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval
See Architecture Overview for details.
Claude-Mem provides intelligent memory search through 4 MCP tools following a token-efficient 3-layer workflow pattern :
The 3-Layer Workflow:
search- Get compact index with IDs (~50-100 tokens/result)timeline- Get chronological context around interesting resultsget_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
searchto get an index of results - Use
timelineto see what was happening around specific observations - Use
get_observationsto fetch full details for relevant IDs - ~10x token savings by filtering before fetching details
Available MCP Tools:
search- Search memory index with full-text queries, filters by type/date/projecttimeline- Get chronological context around a specific observation or queryget_observations- Fetch full observation details by IDs (always batch multiple IDs)
Example Usage:
// 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.
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.
- Node.js : 20.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)
If you see an error like:
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.
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
Edit your settings file at ~/.claude-mem/settings.json:
{
"CLAUDE_MEM_MODE": "code--zh"
}
Modes are defined in plugin/modes/. To see all available modes locally:
ls ~/.claude/plugins/marketplaces/thedotmack/plugin/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.
Restart Claude Code to apply the new mode configuration.
See the Development Guide for build instructions, testing, and contribution workflow.
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.
Create comprehensive bug reports with the automated generator:
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Update documentation
- Submit a Pull Request
Claude-Mem ships from three branches: main (stable), core-dev, and community-edge. Only main is published to npm; the others are run from source. See Release Branches for the strategy and how to run the non-stable lines locally.
See Development Guide for contribution workflow.
Claude-Mem is licensed under the Apache License 2.0.
We chose Apache-2.0 because durable agentic memory should be easy to embed in developer tools, local agents, MCP servers, enterprise systems, robotics stacks, and production agent harnesses.
See the LICENSE file for full details. See docs/license.md and docs/ip-boundary.md for licensing scope and the open/commercial boundary.
Note on Ragtime : The ragtime/ directory is licensed under the Apache License 2.0. See ragtime/LICENSE for details.
Built with Claude Agent SDK | Works with Claude Code | Made with TypeScript
CMEM is a token created by a 3rd party 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 CMEM to the developers and knowledge workers that need it most.
Official BASE CA: 0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3