claude-mem
[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”它值不值得用、怎么用、什么时候不用”。 底层概念链接到
related_concepts；真实项目落地链接到used_in_projects。
AI Agent 持久记忆系统——自动捕获会话中的工具使用观察，生成语义摘要，跨会话注入相关上下文，实现知识连续性。
为什么需要它
AI 编码助手的致命痛点：每次新会话都从零开始。你花了 30 分钟让 Agent 理解项目架构，下次打开又得重新解释。claude-mem 通过生命周期 hooks 自动捕获会话中的关键观察（工具调用、决策、错误），用 AI 生成语义摘要存入数据库，下次会话开始时自动注入相关历史记忆。Agent 不再”失忆”。
核心优势
- 自动记忆捕获：5 个生命周期 hooks（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd）自动工作，无需手动记录
- 语义搜索检索：Chroma 向量数据库支持关键词 + 语义混合搜索，精准召回相关记忆
- 渐进式披露（3 层 MCP）：
search（紧凑索引，~50-100 tokens/条）→timeline（时间线上下文）→get_observations（完整详情，~500-1000 tokens/条），按需加载避免浪费 - Web 可视化：
http://localhost:37777实时记忆流，可观测记忆的捕获和检索过程 - 隐私控制：
<private>标签排除敏感内容不被记录 - 多语言支持：英语、中文、日语等
性能表现
| 指标 | 数据 | 备注 |
|---|---|---|
| 搜索效率 | 3 层渐进式，~10x token 节省 | 对比直接返回全部记忆 |
| 存储 | SQLite + Chroma | 本地存储，无云依赖 |
| 记忆注入开销 | 取决于注入条数 | 可配置限制 |
快速上手
安装
# 一键安装
npx claude-mem install
# 或通过 Claude Code 插件市场安装系统要求
- Node.js ≥ 18.0.0
- Bun（自动安装）
- uv（Python 包管理器，向量搜索用，自动安装）
- SQLite 3（内置）
最小示例
# 安装后正常使用 Claude Code，记忆自动工作
# 手动搜索记忆
# 通过 MCP 工具：search → timeline → get_observations
# 查看记忆流
# 浏览器打开 http://localhost:37777配置要点
~/.claude-mem/settings.json：主配置文件- AI 模型选择（用于生成摘要）
- Worker 端口（默认 37777）
- 数据目录
- 上下文注入设置（控制注入条数和 token 预算）
适用场景
适合：
- 长期项目开发——Agent 需要记住项目架构、历史决策、常见问题
- 多会话工作流——今天讨论的方案，明天继续时 Agent 还记得
- 知识密集型任务——调试过程、排查路径需要跨会话保留
- 团队协作——共享记忆库让不同会话的 Agent 共享知识
不适合：
- 一次性短任务——记忆捕获和总结有开销，短会话收益不大
- 隐私敏感场景——虽然有
<private>标签，但需要仔细配置 - 对延迟极度敏感——记忆注入增加会话启动时间
已知坑 & 注意事项
[!warning] 记忆注入可能膨胀上下文 如果不限制注入条数，claude-mem 可能注入大量历史记忆，反而增加 token 消耗。建议在配置中限制每次注入的记忆条数。
- 依赖较重：需要 Node.js、Bun、uv、SQLite，比纯 CLI 工具复杂
- AI 总结质量：记忆摘要是 AI 生成的，质量取决于所选模型
- 存储增长：长期使用后 SQLite 和 Chroma 数据库可能变大，需定期清理
- Hook 顺序：与其他工具（如 Headroom）同时使用时，需注意 hook 执行顺序
竞品对比
| 维度 | claude-mem | Headroom | mem0 | supermemory |
|---|---|---|---|---|
| 核心功能 | 跨会话持久记忆 | 实时上下文压缩 | 通用记忆层 | 通用记忆层 |
| 作用时机 | 会话结束 → 下次会话开始 | 每次消息发送前 | API 调用时 | API 调用时 |
| 存储方式 | SQLite + Chroma 向量库 | 本地文件（CCR） | 向量数据库 | 向量数据库 |
| 语义搜索 | ✅ 混合搜索 | ❌ | ✅ | ✅ |
| Web UI | ✅ | ❌ | ❌ | ❌ |
| 压缩功能 | ❌（只总结，不压缩） | ✅ 60-95% 压缩 | ❌ | ❌ |
| 目标 Agent | Claude Code 为主 | 通用（10+ 框架） | 通用 | 通用 |
选择建议：
- 需要跨会话记忆 → claude-mem（最成熟的 Agent 持久记忆方案）
- 需要实时压缩当前上下文 → Headroom
- 需要通用记忆 API → mem0 或 supermemory
- claude-mem + Headroom 组合 → 记忆管理 + 上下文压缩，功能互补但需调优
生态 & 社区
- 维护状态：活跃。1,934 commits，持续迭代
- 文档质量：好。README 详尽，30+ 语言翻译
- 社区活跃度：80.5k stars，Discord 社区、GitHub Discussions
- License：Apache 2.0
引入评估
| 维度 | 评分（/5） | 备注 |
|---|---|---|
| 上手难度 | ⭐⭐⭐⭐ | npx claude-mem install 一键安装 |
| 文档完善度 | ⭐⭐⭐⭐ | README 详尽，多语言支持 |
| 社区活跃 | ⭐⭐⭐⭐⭐ | 80.5k stars，非常活跃 |
| 性能 | ⭐⭐⭐ | 记忆捕获和注入有开销，需配置优化 |
| 稳定性 | ⭐⭐⭐ | 依赖较重（Node/Bun/uv/SQLite），偶有兼容性问题 |
| 综合 | ⭐⭐⭐⭐ | 最成熟的 Agent 持久记忆方案，适合长期项目 |
结论：推荐 — 如果你在长期项目中使用 AI 编码助手，claude-mem 的跨会话记忆能力是杀手级功能。渐进式披露和语义搜索设计优秀，能有效控制记忆检索的 token 开销。注意配置好注入限制，避免记忆膨胀。建议与 Headroom 搭配时先小规模验证 hook 兼容性。
推荐引入版本：使用最新稳定版（npx claude-mem install 自动获取）
相关链接
前置知识：Agent 记忆系统 · 向量数据库 · RAG 竞品/互补：Headroom · mem0 · supermemory 使用场景：AI 编码助手 · Agent 系统 · Token 优化
个人备注
{留白，供后续补充实际使用心得}