Claude Mem 深度调研：为 AI 编程助手装上持久化记忆
简介
Claude Code 默认是无状态的——每次新会话都从零开始，你需要重新解释项目结构、代码规范和历史决策。这就像每次上班都要重新入职一样低效。
claude-mem 由 Alex Newman（@thedotmack）于 2025 年 8 月创建，是一个为 Claude Code 等 AI 编程助手提供跨会话持久化记忆的开源系统。GitHub 斩获 74000+ Star，目前最新版本 v13.3.0（2026 年 5 月）。
它解决的核心问题是：让 AI 记住每一次编码会话的关键决策、Bug 修复和技术发现，并在未来的会话中自动注入相关上下文。
核心架构
claude-mem 由四大核心组件构成：
[会话行为流] → [记忆引擎] → [压缩存储] → [上下文注入]1. Worker 服务（Bun HTTP Server）
基于 Bun 运行时的高性能 HTTP 服务，默认监听 127.0.0.1:37777，负责：
- 接收来自 Hook 脚本的事件数据
- 管理 SQLite 数据库读写
- 调用 AI 模型进行观察压缩和摘要生成
- 提供 Web UI 实时查看记忆流
- 提供 REST API 供外部查询
2. 数据库层（SQLite + Chroma）
采用混合存储策略：
- SQLite（WAL 模式）：存储会话、观察记录、摘要的结构化数据，启用 FTS5 全文搜索
- Chroma 向量数据库：存储语义向量，支持相似度搜索
- 所有数据存储在
~/.claude-mem/目录下，不离开本机
核心数据表：
| 表名 | 用途 |
|---|---|
sdk_sessions |
会话记录，含项目名、平台来源、状态 |
observations |
每次工具调用的观察记录 |
session_summaries |
会话结束后的 AI 生成摘要 |
3. MCP Server
一个轻量级包装层（mcp-server.cjs），将 MCP 协议翻译为 Worker 的 HTTP API 调用，向 Claude Code 暴露搜索、时间线、详情获取等工具。
4. Hook 脚本系统
通过 Claude Code 的 Hook 机制注册到五个生命周期节点。
五大生命周期 Hook
claude-mem 在 Claude Code 的每个关键节点注入逻辑，形成完整的「感知-记录-总结-注入」闭环：
Setup Hook
在 Claude Code 启动时触发，执行版本检查和插件自检，确保组件就绪。
SessionStart Hook
匹配事件：startup、clear、compact
执行两个关键任务：
- 启动 Worker 服务：通过
bun-runner.js拉起 Worker 进程 - 注入历史上下文：调用
context-generator.cjs，从数据库中检索当前项目的相关历史观察，注入到当前会话的 prompt 中
UserPromptSubmit Hook
用户每次提交 prompt 时触发，执行会话初始化，确保当前会话在数据库中被正确追踪。
PostToolUse Hook
最核心的 Hook，匹配所有工具调用（*）。每次 Claude 执行 Read、Edit、Bash、Grep 等工具后：
- 捕获工具名称、参数和结果
- 格式化为结构化观察记录
- 发送到 Worker 服务进行存储
- 触发 AI 压缩（去噪、提取关键信息）
Stop Hook
会话结束时触发，调用 Worker 的 summarize 接口，由 AI 模型生成结构化摘要，包含：
request：用户的请求investigated：调研的内容learned：学到的知识completed：完成的工作next_steps：下一步计划files_read/files_edited：涉及的文件
PreToolUse Hook（Read 专用）
在 Claude 读取文件之前触发，将文件上下文信息发送给 Worker，用于丰富记忆的关联性。
观察（Observation）生成管线
claude-mem v13.1.0 引入了 server-beta 事件管线，将观察生成升级为完整的生产级管道：
Agent Event → Outbox → BullMQ Worker → Observation Row关键特性：
- 幂等入队：request-id 端到端传播，保证不重复
- 三 AI 提供商支持：Anthropic、OpenAI、Google，可按团队/项目配置
- 生成任务重试/取消：支持失败重试和手动取消
- 结构化审计日志：完整的操作追踪
MCP 搜索工具：3 层递进式检索
claude-mem 的 MCP 搜索设计是其标志性特性，通过递进式信息披露节省约 10 倍 Token：
| 层级 | 工具 | 返回内容 | Token 成本 |
|---|---|---|---|
| 第一层 | search |
索引摘要（ID、时间戳、类型、标题） | ~50-100/条 |
| 第二层 | timeline |
围绕指定观察的时间线上下文 | 可变 |
| 第三层 | get_observations |
完整观察详情 | ~500-1000/条 |
核心原则：永远不要在筛选之前获取完整详情。
MCP 工具清单
基础搜索工具（4 个）
| 工具 | 功能 |
|---|---|
search |
全文搜索 + 语义搜索，支持按项目、类型、日期过滤 |
timeline |
获取指定观察的前后时序上下文 |
get_observations |
批量获取观察完整详情 |
observation_search |
基于 GIN 倒排索引的 PostgreSQL 全文搜索（server-beta） |
知识代理工具（6 个，v12.1.0+）
| 工具 | 功能 |
|---|---|
build_corpus |
从观察历史编译过滤后的语料库 |
list_corpora |
列出所有已构建的语料库 |
prime_corpus |
将语料库加载到 AI 会话中 |
query_corpus |
对已加载的语料库进行对话式查询 |
rebuild_corpus |
用新数据重建语料库 |
reprime_corpus |
刷新过期的语料库会话 |
观察管理工具（3 个）
| 工具 | 功能 |
|---|---|
observation_add |
手动插入观察记录 |
observation_context |
获取与查询相关的前 N 条观察的上下文注入文本 |
observation_record_event |
记录 Agent 事件，触发生成任务 |
Tree-Sitter AST 工具（3 个）
| 工具 | 功能 |
|---|---|
smart_search |
基于 AST 解析的结构化代码搜索，替代 Grep/Glob/Read 发现循环 |
smart_outline |
获取文件的结构骨架（所有符号及其签名） |
smart_unfold |
展开特定符号（函数、类、方法）的完整源码 |
支持 20+ 语言（Python、JavaScript、TypeScript、Go、Rust、C/C++、Java、Ruby、Swift、Kotlin、PHP、Scala、Bash、Haskell、Zig、CSS/SCSS、TOML、YAML、SQL、Markdown、Lua、Elixir）。
SKILL 体系
claude-mem 内置了 15 个 SKILL（可调用的子代理），覆盖开发全流程：
| SKILL | 用途 |
|---|---|
do |
编排子代理执行分阶段实施计划 |
make-plan |
创建 LLM 友好的分阶段实施计划 |
mem-search |
跨会话搜索历史工作记录 |
smart-explore |
使用 AST 解析进行低 Token 代码探索 |
learn-codebase |
系统性地通读整个代码库 |
knowledge-agent |
构建和查询基于记忆的 AI 知识库 |
design-is |
基于 Dieter Rams 十大设计原则审核设计 |
timeline-report |
生成项目完整开发历史的叙事报告 |
weekly-digests |
生成按周划分的串行叙事摘要 |
oh-my-issues |
将 Issue 堆积分类为根因集群 |
babysit |
监控 PR 评审循环直到可合并 |
pathfinder |
将代码库映射为功能分组的流程图 |
version-bump |
语义化版本发布工作流 |
wowerpoint |
将文档转化为分享式幻灯片 PDF |
how-it-works |
解释 claude-mem 的工作原理 |
安装与配置
一行命令安装
npx claude-mem install或在 Claude Code 内部安装：
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem关键配置项
配置文件位于 ~/.claude-mem/settings.json：
| 配置项 | 默认值 | 说明 |
|---|---|---|
CLAUDE_MEM_MODEL |
claude-sonnet-4-5 |
用于观察压缩的模型 |
CLAUDE_MEM_WORKER_PORT |
37777 |
Worker HTTP 服务端口 |
CLAUDE_MEM_WORKER_HOST |
127.0.0.1 |
Worker 绑定地址 |
CLAUDE_MEM_PROVIDER |
claude |
AI 提供商（claude/openrouter/gemini） |
CLAUDE_MEM_CONTEXT_OBSERVATIONS |
50 |
上下文注入的最大观察数 |
CLAUDE_MEM_LOG_LEVEL |
INFO |
日志级别 |
CLAUDE_MEM_MODE |
code |
语言模式（code/code–zh/code–ja） |
CLAUDE_MEM_DATA_DIR |
~/.claude-mem |
数据存储目录 |
支持 13 种 IDE
Claude Code、Gemini CLI、OpenCode、Windsurf、OpenClaw、Codex CLI、Copilot CLI、Antigravity、Goose、Crush、Roo Code、Warp、Cursor。
隐私与多语言
隐私保护
- 所有数据存储在本地
~/.claude-mem/，不离开本机 - 仅 AI 压缩调用会发送数据到配置的 AI 提供商
- 用
<private>...</private>标签包裹敏感内容，系统会自动排除 npx claude-mem uninstall彻底清除所有数据
多语言模式
内置三种语言模式：
| 模式 | 语言 |
|---|---|
code |
英文 |
code--zh |
中文 |
code--ja |
日文 |
通过 CLAUDE_MEM_MODE 配置项切换。
上下文注入机制
注入时机
记忆注入从第二个会话开始生效。第一个会话在项目中播种记忆，后续会话自动注入过去相关工作的上下文。
注入内容
每次 SessionStart 时，context-generator 从数据库检索：
- 最近会话摘要（最近 N 个会话的完成内容）
- 相关历史观察（基于项目名和语义相似度）
- Token 节省统计（展示记忆系统的压缩效率）
注入到 CLAUDE.md 和 stdout，Claude 无需调用任何工具即可获得历史上下文。
快速入门
运行 /learn-codebase 可在单次遍历中（约 5 分钟）将整个代码库前端加载到记忆中。
Claude Code 内置记忆系统
Claude Code v2.1.x 起内置了一套未公开的自动记忆系统，与 claude-mem 并存：
工作原理
- 存储格式：纯 Markdown 文件，位于
~/.claude/projects/<项目编码>/memory/ - 索引文件：
MEMORY.md，每个会话自动加载到系统提示词中 - 四种记忆类型：User（用户偏好）、Feedback（反馈指导）、Project（项目上下文）、Reference（外部资源指针）
- 后台提取：一个
extract-memories子代理在会话结束后自动运行，提取关键洞察
关键限制
- 200 行硬上限：
MEMORY.md超过 200 行后，旧条目静默截断 - 25KB 字节上限：作为次要限制
- 每回合最多 5 个记忆文件
- 无向量搜索：通过独立的 Claude Sonnet 侧调用来扫描文件名/描述以选取相关文件
- 陈旧度警告：超过 1 天的记忆会被注入陈旧度警告
静默遗忘是最危险的——Claude 无法知道记忆被截断，可能导致重复犯错、与之前的架构决策矛盾、反复询问偏好。
与同类方案对比
claude-mem vs claude-mem-lite
claude-mem-lite（@sdsrss / @mingfeiqiao）是对原始 claude-mem 的轻量级重设计：
| 维度 | claude-mem（原版） | claude-mem-lite |
|---|---|---|
| LLM 调用方式 | 每次工具调用触发 Sonnet | 仅在批量刷新时调用（5-10 条一批） |
| 每会话 Token 消耗 | ~100K-250K | ~1K-4K |
| 成本 | 基准 | 低 50-100 倍，便宜 600 倍+ |
| 运行时 | 长驻 Worker（1.8MB） | 按需启动，立即退出 |
| 依赖 | Bun + Python/uv + Chroma | 仅 Node.js（3 个 npm 包） |
| 向量搜索 | ChromaDB（Python/MCP） | SQLite FTS5 + TF-IDF 余弦相似度 |
| 噪音过滤 | LLM 判断 | 确定性代码级过滤 |
claude-mem-lite 的设计哲学：先用代码过滤，只把重要内容发送给轻量模型。
claude-mem vs memsearch（Zilliz/Milvus）
| 维度 | memsearch | claude-mem |
|---|---|---|
| 架构 | 4 个 Shell Hook + 后台监听进程 | Node.js Worker + Express + React |
| 存储 | 纯 Markdown（每天一个文件） | SQLite + Chroma |
| 召回方式 | 自动注入（Hook 触发语义搜索） | Agent 驱动（手动调用工具） |
| 上下文开销 | 零（无 MCP 工具定义） | MCP 工具定义常驻 |
| 向量索引 | Milvus（可从 Markdown 重建） | Chroma |
memsearch 的亮点在于零 Token 上下文开销——每次 UserPromptSubmit Hook 自动执行语义搜索并将 Top-3 结果注入 prompt，Claude 无需决定是否搜索，它直接获得上下文。
claude-mem vs mem0
mem0（mem0ai/mem0）是面向生产环境的向量记忆层：
- 完全基于嵌入向量的语义检索（无 200 行限制）
- 无静默截断
- 跨会话召回无需显式工具调用
- 支持 Claude Code 和 Cowork 双平台
技术栈总览
| 组件 | 技术选型 |
|---|---|
| 运行时 | Bun（Worker 服务） |
| Web 框架 | Express |
| 数据库 | SQLite（WAL 模式 + FTS5） |
| 向量存储 | ChromaDB（Python/uv 依赖） |
| 进程管理 | 自研 PM2 风格管理器 |
| AI 压缩 | Anthropic Claude / OpenAI / Google Gemini |
| 前端 UI | React（localhost:37777） |
| 代码分析 | Tree-sitter（20+ 语言支持） |
| MCP 协议 | 自研轻量包装层 |
| 任务队列 | BullMQ（server-beta） |
总结
claude-mem 通过 Hook 驱动的生命周期感知 + AI 压缩 + 混合向量检索，构建了一套完整的 AI 记忆系统。其核心价值在于：
- 上下文连续性：跨会话记住关键技术决策和 Bug 修复方案，避免重复踩坑
- Token 经济性：3 层递进式检索在提供丰富上下文的同时将 Token 消耗控制到最低
- 开发生命周期全覆盖：从代码探索（smart-explore）→ 计划制定（make-plan）→ 执行实施（do）→ PR 审核（babysit）→ Issue 归并（oh-my-issues）→ 版本发布（version-bump），15 个 SKILL 构成完整的 AI 辅助开发工作流
- 隐私可控：数据本地化、敏感内容过滤、一键卸载
局限也不容忽视——对 Chroma 的 Python 依赖增加了安装复杂度，每次工具调用的 LLM 压缩会导致较高的 API 成本，而 Claude Code 内置记忆系统的 200 行静默截断在项目规模增大时会成为瓶颈。
选择合适的方案取决于具体需求：
- 需要丰富功能和 UI → claude-mem 原版
- 追求低开销和简单 → claude-mem-lite
- 看重透明性和纯 Markdown → memsearch
- 生产级向量记忆 → mem0
- 零配置开箱即用 → Claude Code 内置记忆（注意 200 行限制）