每个使用 AI 编程智能体的开发者都经历过：你花了一个小时向 Claude Code 解释你的项目架构、偏好和规范。会话结束了。你开始了一个新的会话。结果又是 白纸一张。 Claude-Mem 是解决这个问题的开源插件 — 并且它已成为 AI 编程生态中最受欢迎的工具之一。我们调研了 GitHub、Reddit、Twitter/X 以及源代码本身 — 以下是权威指南。
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
1. 为什么它很重要
Claude-Mem 是 获得 Star 最多的插件之一 在 Claude Code 生态系统中，拥有数万个 GitHub star、数百个版本发布和数千次 fork。对于一个本质上是为 AI 编程智能体增加记忆功能的插件来说，这种采用率是惊人的。它既不是框架也不是库 — 它是一种 行为增强 针对 Claude Code。
为什么这很重要
AI 智能体在设计上是无状态的 — 每个会话都是从零开始。但实际的开发项目往往跨越 数周甚至数月。每一次重复解释都会消耗 token、时间，并带来智能体误解你已经澄清过的内容的风险。Claude-Mem 自动弥补了这一差距。
该项目主要使用 TypeScript构建，并结合了 JavaScript、 Shell 脚本以及 HTML 用于其 Web 查看器。它采用 AGPL-3.0协议授权，这意味着你可以自由使用和修改它，但在网络上部署的衍生作品也必须开源。
2. 起源故事
Claude-Mem 由 Alex Newman 创建，在网上的 ID 为 @thedotmack。Newman 的背景涵盖了 AI 产品管理、解决方案架构以及前向部署工程 — 这种背景组合解释了为什么 claude-mem 感觉不像是一个业余项目，而更像是一个生产级的基础设施。
该项目源于一个简单的观察：Claude Code 非常强大，但它对待每一次会话都像是第一次见到你。Newman 构建 claude-mem 是为了解决他自己的痛点 — 而开发者社区对此给予了巨大的认可。
核心洞察
Newman 意识到问题不在于 存储 记忆 — 而是在于 如何高效地压缩和检索 它们。原始对话日志过于庞大且缺乏重点。Claude-Mem 利用 AI 自身来生成每次会话内容的语义摘要，然后仅为下一次会话检索相关的上下文。
该项目拥有官方 X/Twitter 账号 (@Claude_Memory)、一个 Discord 社区，甚至还有一个官方网站： claude-mem.ai ，并配有详尽的文档。
3. 它解决的问题
如果你使用 Claude Code、Cursor 或任何 AI 编程代理超过一天，你就会明白这种痛苦：
问题 1：上下文失忆症
你解释了项目架构、数据库模式和编码规范。会话结束。下个会话：“这是个什么项目？”每一次，都是如此。
问题 2：重复决策
你决定使用特定的模式（例如，“始终使用 server actions，绝不使用 API routes”）。下个会话，Agent 生成了 API routes，因为它不记得你的偏好。
问题 3：丢失 Bug 上下文
你花了 30 分钟调试一个棘手的竞态条件。修复方案需要理解三个相互关联的服务。下个会话，Agent 建议的正是你已经尝试并拒绝过的方案。
问题 4：Token 浪费
每次重新解释都会消耗 Token。如果你使用的是按量计费方案，每天几十次会话中重建上下文的成本会迅速累积。
Claude-Mem 解决了这四个问题。它在后台静默运行，捕捉 Claude 的 行为 （而不仅仅是你的 言语），将这些观察结果压缩成语义摘要，并在每个新会话开始时注入相关的摘要。
4. 工作原理
Claude-Mem 通过 6 个核心组件协同工作，构建出一个无缝的记忆层：
| 组件 | 功能描述 |
|---|---|
| 5 个生命周期钩子 | SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd — 捕捉每个阶段的事件 |
| 智能安装 | 在 hook 运行前执行的缓存依赖检查器（确保 Bun、uv 及相关依赖已就绪） |
| Worker 服务 | 运行在 37777 端口的 HTTP API，包含 Web 查看器 UI 和 10 个搜索端点，由 Bun 管理 |
| SQLite 数据库 | 在本地存储会话、观察结果和摘要，并支持 FTS5 全文搜索 |
| mem-search 技能 | 支持自然语言查询，并通过渐进式披露检索项目历史 |
| Chroma 向量数据库 | 混合语义 + 关键词搜索，实现智能上下文检索 |
生命周期流程
以下是典型会话期间发生的过程：
1. SessionStart Hook
→ Worker 服务启动（如果尚未运行）
→ 检索相关的历史观察结果
→ 将压缩后的上下文注入会话
2. UserPromptSubmit Hook
→ 记录用户的提问内容
3. PostToolUse Hook（在每次工具调用后运行）
→ 捕获工具名称 + 输入 + 输出
→ 使用 AI 压缩观测结果
→ 存储在 SQLite + 向量数据库中
4. Stop Hook
→ 捕获会话暂停事件
5. SessionEnd Hook
→ 生成会话摘要
→ 存储最终上下文快照
这里的核心洞察是 PostToolUse。Claude-Mem 不仅仅记录你的消息 — 它还记录了智能体 所做的操作：读取的文件、编写的代码、运行的测试、遇到的错误。这使得它对项目状态的理解比单纯的对话日志要深刻得多。
5. 渐进式披露
这是 claude-mem 最具创新性的设计模式。它没有将所有记忆全部倾倒进上下文窗口（这会导致 Token 成本飙升），而是使用了一个 三层检索系统：
第一层：会话引导 (<500 tokens)
→ 轻量级项目摘要
→ 最近会话的关键决策
→ 在 SessionStart 时自动注入
第 2 层：搜索索引 (~50-100 tokens/结果)
→ 紧凑的观察 ID + 标题
→ Agent 在需要更多上下文时进行搜索
→ 足以判断 “这是否相关？”
第 3 层：详细内容 (~500-1000 tokens/结果)
→ 完整的观察内容
→ 仅针对相关的 ID 进行获取
→ Agent 显式请求其所需内容
结果：相比“全量堆凑”的方法，节省了约 10 倍的 token
正是这种架构让 claude-mem 在大规模应用中具有实用性。如果没有渐进式披露，记忆系统要么消耗过多的 token（昂贵且分散注意力），要么检索内容太少（遗漏关键上下文）。Claude-mem's 的三层系统让 Agent 能够自行判断相关性。
6. MCP 搜索工具
Claude-Mem 提供了 4 个 MCP 工具 供 Claude 用于查询其自身记忆：
| 工具 | 用途 | Token 消耗 |
|---|---|---|
搜索 | 带过滤条件的全文搜索（类型、日期、项目） | 约 50-100/结果 |
时间线 | 特定观测结果前后的时间线上下文 | 约 100-200/结果 |
get_observations | 通过观测 ID 批量获取完整详情 | 约 500-1000/结果 |
示例：搜索您的记忆
search(query="身份验证 bug",
type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs
// e.g., observations #123, #456 look relevant
// Step 3: Fetch full details ONLY for those
get_observations(ids=[123, 456])
这种工作流意味着 Claude 只需为其实际需要的 observations 支付 token 成本，而不是数据库中的所有内容。搜索层充当 过滤器，而检索层提供 深度。
7. 如何安装
Claude-Mem 提供三种安装方式：
选项 A：npx（推荐）
最快的方式 — 仅需一条命令：
npx claude-mem install
# 为 Gemini CLI 安装
npx claude-mem install --ide gemini-cli
选项 B：插件市场（Claude Code 内置）
/plugin marketplace add thedotmack/claude-mem
# 安装插件
/plugin install claude-mem
选项 C：OpenClaw Gateway
⚠️ 重要提示
npm install -g claude-mem 仅安装 SDK/库 — 它并 不会 注册插件钩子或设置 worker 服务。请务必使用 npx claude-mem install 或 /plugin 命令。
系统要求
| 要求 | 详情 |
|---|---|
| Node.js | 18.0.0 或更高版本 |
| Claude Code | 支持插件的最新版本 |
| Bun | JavaScript 运行时（如果缺失将自动安装） |
| uv | 用于向量搜索的 Python 包管理器（自动安装） |
| SQLite 3 | 用于持久化存储（已捆绑） |
安装完成后，重启 Claude Code 或 Gemini CLI。之前会话的上下文将自动出现在新会话中 — 无需手动干预。
8. 核心功能深度解析
🧠 持久化记忆
核心功能：上下文跨会话持久存在。当你开始新会话时，Claude 已经了解你处理过哪些文件、修复过哪些 bug、做过哪些架构决策以及你偏好的模式。
🖥️ Web 查看器 UI
在浏览器中访问 http://localhost:37777 即可查看实时记忆流。你可以浏览观察结果、搜索历史记录，并监控 claude-mem 正在捕获的内容。查看器还提供对 Beta 功能和版本切换的访问。
🔒 隐私控制
将任何内容包裹在 <private> 标签中即可将其排除在存储之外。API 密钥、凭据、个人信息 — 这些标签内的任何内容都不会被持久化。数据完全保留在你本地机器的 SQLite 中。
🔗 引用
每个观察结果都有一个唯一的 ID。你可以通过 ID 引用过去的观察结果，并通过 http://localhost:37777/api/observation/{id}进行访问。这使得我们可以追溯 准确的 Claude 做出特定决策的原因。
🧪 Beta 频道：无尽模式 (Endless Mode)
实验性的 “无尽模式” 实现了一种 仿生记忆架构 专为持续数小时的长会话设计。它采用了一种不同的压缩策略，可防止在马拉松式的编程会话中出现上下文窗口饱和。您可以通过 Web 查看器 UI 在稳定版和 Beta 版之间进行切换。
⚙️ 上下文配置
设置管理于 ~/.claude-mem/settings.json。您可以配置用于压缩的 AI 模型、Worker 端口、数据目录、日志级别，并对注入上下文的内容和时机进行细粒度控制。
9. 架构概览
Claude-Mem 的架构在多个大版本中经历了显著演进。以下是各组件的协作方式：
┌─────────────────────────────────────┐
│ Claude Code 会话 │
│ │
│ SessionStart → PostToolUse → End │
└────────────────┬────────────────────┘
│ Hooks
▼
┌─────────────────────────────────────┐
│ Worker 服务 (Bun, 端口 37777) │
│ │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ Web UI │ │ 10 个 API 端点 │ │
│ └──────────┘ └──────────────────┘ │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 存储层 │
│ │
│ ┌──────────────┐ ┌──────────────┐│
│ │ SQLite + FTS5 │ │ Chroma VecDB ││
│ │ (结构化) │ │ (语义化) ││
│ └──────────────┘ └──────────────┘│
└─────────────────────────────────────┘
双数据库策略
Claude-Mem 同时使用两个数据库：
- SQLite (配合 FTS5) — 用于结构化查询、精确匹配搜索和基于时间的过滤。快速、本地化、零配置。
- Chroma 向量数据库 — 用于语义相似度搜索。当 Claude 询问 “我们对身份验证系统做了什么？” 时，即使关键词不完全匹配，Chroma 也能找到概念相关的观察结果。
它们共同提供了 混合搜索：来自 SQLite 的精确匹配以及来自 Chroma 的模糊/语义匹配。这与生产级 RAG 系统所使用的搜索架构模式相同，只是针对本地使用进行了小型化。
10. 社区反响
我们调研了以下平台的讨论： Reddit (r/ClaudeAI, r/ClaudeCode)、Twitter/X 以及技术文章。以下是社区共识：
“空白状态” 杀手
Reddit 上的压倒性观点是：claude-mem 是解决 “空白状态” 问题的最佳方案。用户反馈它 显著减少了 重新解释项目架构的阻力，节省了时间、Token 并减少了挫败感。r/ClaudeCode 上的多个帖子将其描述为 “必备” 插件。
Token 经济辩论
一些用户最初担心 Token 成本 — 一个通过 AI 调用来压缩观察结果的活跃记忆系统本身可能会消耗 Token。社区共识是： 渐进式披露架构 使其收益为正。因无需重新解释上下文而节省的 Token 远超用于记忆压缩所消耗的 Token。
“重型 vs 轻量” 之争
由于 claude-mem 是一个全功能系统（需要 Bun、用于向量搜索的 Python 以及后台工作服务），一些开发者创建了更轻量级的替代方案，例如 claude-mem-lite 以及 memsearch这些工具使用更简单的基于文本的存储，并最大限度地减少了 LLM 调用。社区认为它们是互补的：claude-mem 适用于严肃的、跨越数周的项目，而轻量级工具则适用于快速实验。
工作流集成层
Reddit 上的高级用户将 claude-mem 描述为 基础层 用于自定义工作流。他们在之上构建专门的 “技能” — 将持久化记忆与自定义规则和特定领域知识相结合，从而创建能够深入理解其特定项目的 AI Agent。
社区评价
Claude-Mem 被广泛认为是 AI Agent 持久化记忆的最佳解决方案。主要的批评在于它太 “重” — 一个具有多个依赖项的复杂系统。而反驳的观点是： 记忆是一个难题，而简单的解决方案只能产生简单的结果。
11. 结论：Claude-Mem 值得使用吗？
我们的看法
是的，如果你在多会话项目中使用 Claude Code。 Claude-Mem 是 AI 编程 Agent 的最佳持久化记忆解决方案。渐进式披露架构使其具有极高的 Token 效率，SQLite + Chroma 双重搜索为你提供精确检索和语义检索，而全自动运行则意味着零手动开销。
适用场景：
- 你的项目跨越多个会话（数天、数周、数月）
- 你厌倦了在每次会话中重新解释项目架构
- 你希望 Claude 记住过去的决策、Bug 修复和被否决的方案
- 你可以接受其依赖占用（Node.js、Bun、用于向量搜索的 Python）
不适用场景：
- 你只在处理快速、一次性的任务时使用 Claude Code
- 你更倾向于极简工具，且不希望有任何后台服务
- 你使用 Cursor 或 Windsurf（claude-mem 仅适用于 Claude Code、Gemini CLI 和 OpenClaw）
- 一个维护良好的
CLAUDE.md文件已足以满足你的工作流
12. 替代方案 & 对比
与其他为 AI Agent 提供记忆的方法相比，claude-mem 表现如何？
| 方案 | 优点 | 缺点 |
|---|---|---|
| CLAUDE.md (手动) | 简单、无依赖、完全可控 | 手动维护、无自动捕获、静态 |
| Claude-Mem | 自动化、语义搜索、渐进式披露、内容丰富 | 配置复杂、需要 Bun + Python、后台服务 |
| claude-mem-lite | 轻量级、基于文本、依赖更少 | 无语义搜索、压缩方式更简单 |
| 自定义脚本 | 完全可定制，无外部依赖 | 万物皆可 DIY，无生态系统支持 |
| 内置 Claude Memory | 零配置，原生集成 | 范围有限，缺乏针对特定项目的持久化 |
对于大多数从事严肃的多会话项目的开发者来说， claude-mem 提供了最丰富的功能集。对于快速实验或偏好极简工具的开发者， 一个维护良好的 CLAUDE.md 文件 结合一个 skills 文件（例如 Karpathy's skills）可能就足够了。
13. 宏观视角
从无状态到有状态的 Agent
Claude-Mem 代表了我们对 AI 编程 Agent 思考方式的转变。第一代 AI 助手是 无状态的 — 每次交互都是从零开始。而当前这一代，凭借 claude-mem 等工具，正在变得 有状态的 — 能够随着时间的推移不断积累项目知识的 Agent。
这具有深远的影响。一个有状态的智能体不仅仅是编写代码 — 它 理解你的代码库。它知道哪些模式有效，哪些被拒绝了，以及原因。它记得认证系统使用特定的令牌格式是因为过去的迁移限制。它回想起数据库查询需要特定的索引，因为你两周前调试过一个性能问题。
上下文工程生态系统
Claude-Mem 是更广泛的 “上下文工程” 生态系统的一部分，该生态正在迅速成熟：
- CLAUDE.md / 规则文件 — 静态上下文（项目规范、编码标准）
- 技能/插件 — 行为准则（比如 Karpathy's 技能文件）
- 记忆插件 — 动态上下文（claude-mem、会话历史）
- MCP 服务器 — 外部知识（数据库、API、文档）
这些层级结合在一起，创建了 深度定制化 且针对特定项目和开发者的智能体。松散、无结构的 AI 交互的 “氛围编程” 时代正在演变为 “智能体工程” — 一种严谨的实践，其中上下文管理与提示词本身同样重要。
未来展望
在 v12 版本中，claude-mem 已经支持 Claude Code、Gemini CLI 和 OpenClaw 网关。其发展轨迹正指向 通用智能体记忆 — 一个可跨越任何 AI 编程工具、编辑器或平台工作的持久化知识层。$CMEM 代币（一种由社区驱动、并已获得创作者正式接纳的 Solana 代币）预示着在实时智能体数据共享和开发者协作方面更宏大的计划。
14. 常见问题解答
Q: claude-mem 是否支持 Gemini CLI，还是仅支持 Claude Code？
Claude-Mem 同时支持 Claude Code 和 Gemini CLI。使用 'npx claude-mem install --ide gemini-cli' 即可为 Gemini CLI 安装。它还兼容 OpenClaw 网关。
Q: claude-mem 会将我的代码或数据发送到云端吗？
不会。所有数据都存储在本地的 SQLite 数据库中，路径为 ~/.claude-mem/claude-mem.db。任何数据都不会离开您的机器。运行在 37777 端口的 HTTP API 也在本地运行，无需身份验证。
Q: claude-mem 会消耗额外的 token 吗？
它在压缩 observations 时会消耗 token，但其渐进式披露架构意味着净节省。由于无需在不同会话间重复解释上下文，节省的 token 远超压缩成本。
Q: 为什么 worker 无法启动，或者 37777 端口被占用？
使用 'lsof -i :37777' 检查端口占用情况，并使用 'kill -9 $(lsof -t -i:37777)' 终止进程。您也可以在 ~/.claude-mem/settings.json 中修改端口。
Q: claude-mem 和 CLAUDE.md 有什么区别？
CLAUDE.md 是一个由您手动维护、包含项目规范的静态文件。Claude-Mem 则是自动化的——它能动态捕获、压缩并检索上下文。两者互为补充：CLAUDE.md 用于定义规则，claude-mem 用于管理记忆。
Q: 我可以在 Cursor 或 Windsurf 中使用 claude-mem 吗？
不可以。Claude-Mem 是专为 Claude Code 的插件/hooks 系统构建的。它还支持 Gemini CLI 和 OpenClaw 网关，但不支持 Cursor、Windsurf 或其他 IDE。
Q: claude-mem 中的 Endless Mode 是什么？
Endless Mode 是一个 Beta 功能，它为长达数小时的马拉松式编程会话实现了仿生记忆架构。它采用不同的压缩策略来防止上下文窗口饱和。你可以通过 Web Viewer UI 切换到该模式。
15. 所有来源与链接
本文的研究基于 多源研究 涵盖了 GitHub、Reddit、Twitter/X、网络文章以及源代码本身。以下是所有主要来源：
主要来源
- GitHub: thedotmack/claude-mem — 项目仓库
- claude-mem.ai — 官方网站与文档
- 架构概览 — 系统组件与数据流
- 渐进式披露文档 — 上下文引导哲学
- 上下文工程指南 — AI 智能体优化原则
社区与社交
- @Claude_Memory — 官方 X/Twitter 账号
- Discord 社区 — 官方 Discord 服务器
- Reddit r/ClaudeAI — 关于 AI 记忆解决方案的社区讨论
- Reddit r/ClaudeCode — 关于插件架构、Token 管理的技术讨论帖
技术参考
- 架构演进 — 从 v3 到 v5+ 的演进历程
- Hooks 架构 — claude-mem 如何使用生命周期 Hooks
- 搜索架构 — 基于 Chroma 的混合搜索
- 搜索工具指南 — MCP 工具使用示例
作者
- Alex Newman (@thedotmack) — claude-mem 的作者
本站相关文章
- Karpathy's CLAUDE.md 技能文件：完整指南
- Karpathy's LLM Wiki：其想法文件的完整指南
- 如何在你的 AI IDE 中设置技能
- AI Agent 系统提示词完整指南
- 精通 Agent 技能
Get the Ultimate Antigravity Cheat Sheet
Join 5,000+ developers and get our exclusive PDF guide to mastering Gemini 3 shortcuts and agent workflows.