Mar 27, 2026

技术热点落地：Claude-Mem — 为 Claude Code 打造跨会话持久记忆系统（2026-03-27）

适用场景与目标

Claude Code 是 2026 年最流行的 AI 编程助手之一，但它每次新会话都从零开始——不知道你上次解决了什么 bug、不记得项目的架构决策、不记得哪些模块已重构过。这在大型项目和长期迭代中是一个显著的效率瓶颈。

Claude-Mem（thedotmack/claude-mem，9.4K+ GitHub Stars）正是为解决这一痛点而生：自动捕获 Claude Code 会话中的所有操作轨迹，经 AI 压缩后注入未来会话，实现真正的跨会话上下文连续性。

核心价值

减少重复劳动：不再重复解释项目背景、已知的坑、既有的技术选型
节省 Token 消耗：记忆压缩比手动总结更高，且只注入相关上下文
提升大型项目开发连续性：跨越数周的项目迭代也能保持连贯理解
多项目全局记忆：跨项目知识复用（如”这个 ORM 遇到过什么问题”）

适用人群：重度使用 Claude Code 开发中大型项目的工程师；monorepo 或多人协作项目中需要 AI 理解项目规范的团队。

最小可行方案（MVP）步骤

第一步：确认环境依赖

Claude-Mem 需要：

Node.js 18+（含 npm）和 Bun（Worker 服务运行时）
Claude Code 已安装并配置好 (npx @anthropic/claude-code)
Claude API Key 环境变量已设置 (ANTHROPIC_API_KEY)

# 检查 Node 版本
node --version  # 需要 v18+

# 检查 Bun（若未安装）
curl -fsSL https://bun.sh/install | bash

# 验证 Claude Code 可用
claude --version

第二步：安装 Claude-Mem 插件

⚠️ 常见误区：不要用 npm install -g claude-mem，那只会安装 SDK，不注册插件钩子！

正确做法是通过 Claude-Mem 提供的 /plugin 命令安装：

# 在 Claude Code 中或终端里运行
claude /plugin install claude-mem

这会自动：

安装 claude-mem npm 包
注册 5 个生命周期钩子（Hook Scripts）
启动 Bun Worker Service（后台守护进程）
初始化 SQLite 数据库和 Chroma 向量数据库

安装完成后，Worker Service 运行在 **http://localhost:37777**，有 Web UI 可查看记忆。

第三步：验证安装

# 检查 Worker Service 是否运行
curl http://localhost:37777/health

# 在 Claude Code 中查看可用命令
claude --help | grep mem

确认看到 mem-search 等 MCP 工具被加载后，即可开始使用。

第四步：基础使用——让 AI 自动管理记忆

安装后，Claude-Mem 以被动捕获为主：你正常做开发，插件在后台自动记录。

触发记忆注入：在新会话中，直接用自然语言查询记忆：

claude > "我们上次在支付模块遇到的超时问题是怎么解决的？"

Claude 会通过 MCP 工具自动搜索记忆库，先获取索引，再按需获取完整细节。

主动写入记忆（可选）：

claude > /mem-summarize "本次会话关键决策：选用 Prisma ORM，原因是 xxx；已知问题：用户头像上传在 iOS Safari 有兼容性问题"

关键实现细节

架构概览

┌─────────────────────────────────────────────────┐
│            Claude Code Session                  │
│  5 Lifecycle Hooks:                              │
│  SessionStart → UserPromptSubmit → PostToolUse  │
│  → Stop → SessionEnd                            │
└────────────────┬────────────────────────────────┘
                 │ hook 触发
                 ▼
┌─────────────────────────────────────────────────┐
│         Bun Worker Service (:37777)              │
│  - HTTP API Server                              │
│  - AI Observation Compressor (agent-sdk)        │
│  - Chroma Vector DB (语义搜索)                   │
│  - SQLite (结构化存储)                           │
└─────────────────────────────────────────────────┘

5 个生命周期钩子详解

钩子	触发时机	作用
`SessionStart`	会话开始	注入相关历史记忆上下文
`UserPromptSubmit`	用户提交 Prompt 前	预处理 Prompt，注入相关记忆
`PostToolUse`	每次工具调用后	记录关键操作轨迹
`Stop`	用户主动中断	触发阶段性总结压缩
`SessionEnd`	会话正常结束	全量压缩 observation → summary

3 层 Token 高效搜索协议

这是 Claude-Mem 最重要的设计细节，直接解决 AI 记忆系统的 token 成本问题：

第 1 层 — search：轻量索引查询

返回 compact ID 列表，约 50-100 tokens/结果
支持全文检索 + 类型/日期/项目过滤
Claude 先用这个缩小范围

第 2 层 — timeline：时间线上下文

获取相关 observation 周围的时序上下文
理解”在这个 bug 修复之前发生了什么”

第 3 层 — get_observations：按需获取完整细节

只对过滤后的 ID 批量获取完整内容
约 500-10,000 tokens/结果
必须批量传多个 ID，避免逐条调用

// 典型搜索流程伪代码
const index = await search({ query: "auth bug", limit: 5 })
const ids = index.map(r => r.id)
const timeline = await timeline({ query: "auth bug" })
const observations = await get_observations({ ids: ids.slice(0, 2) })

Chroma 向量数据库的角色

Chroma 提供语义搜索能力，使得”上次处理的那个性能问题”这种模糊查询也能命中正确结果，而不仅依赖关键词匹配。默认配置下，Chroma 在本地运行，数据存储在 ~/.claude-mem/chroma/。

常见坑与规避清单

坑 1：全局安装 SDK 而非插件安装

表现：/plugin 命令找不到，或 Hook 不触发。原因：npm install -g claude-mem 只装了库，没注册生命周期钩子。规避：始终使用 claude /plugin install claude-mem。

坑 2：Worker Service 端口被占用

表现：安装后记忆不生效，curl localhost:37777 连接失败。原因：37777 端口已被其他进程占用。解决：

# 查找占用端口的进程
lsof -i :37777

# 或启动时指定其他端口
claude-mem --port 37778

坑 3：首次冷启动 Chroma 建库极慢

表现：第一次安装后，新会话记忆注入奇慢甚至超时。原因：Chroma 在首次启动时扫描并向量化历史 observation。规避：在空闲时提前运行初始化：claude-mem backfill。

坑 4：Token 预算被记忆数据撑爆

表现：Claude 回复变慢，或收到”context overflow”错误。原因：记忆搜索返回过多 observation，注入的上下文超限。规避：

在 ~/.claude-mem/config.json 设置 max_context_tokens: 4096
养成习惯：先 search，再选最相关的 1-2 条用 get_observations 获取

坑 5：多项目记忆混淆

表现：A 项目的记忆出现在了 B 项目中。原因：默认全局记忆池，没有项目隔离。规避：在 ~/.claude-mem/config.json 配置 project_filter: true，或使用标签机制：

# 主动标记项目
claude > /mem-tag "project:payment-gateway"

坑 6：Hook 脚本与 Claude Code 版本不兼容

表现：Hook 报错或根本不触发，Claude Code 升级后尤为常见。原因：Claude Code 内部 API 变化导致钩子协议失效。规避：关注 GitHub Issues，每次 Claude Code 大版本升级后运行：

claude /plugin update claude-mem

成本/性能/维护权衡

成本维度

维度	说明
Token 成本	记忆压缩使用 Claude API（通常用 Sonnet 级模型），每次压缩消耗 token，但远低于重复对话成本
存储成本	SQLite + Chroma 本地运行，磁盘占用随项目增长（通常 < 500MB/项目）
运行成本	Bun Worker Service 常驻内存 ~100MB，无外部云依赖

性能维度

记忆注入延迟：热启动（缓存命中）< 500ms；冷启动（Chroma 查询新词）约 2-5 秒
搜索延迟：向量搜索 < 100ms（本地），语义+关键词混合搜索 < 500ms
Hook 触发开销：几乎无感知（异步写入，不阻塞主会话）

维护维度

数据备份：SQLite 文件在 ~/.claude-mem/，可定期打包备份
版本迁移：插件升级时注意运行 claude-mem migrate
清理策略：建议每月运行一次 claude-mem prune --older-than 90d，删除 90 天以上 observation

一周内可执行行动清单

Day 1（30 分钟）：尝鲜体验

在个人项目中运行 claude /plugin install claude-mem
完成一次完整开发会话，观察记忆是否被自动记录
新会话中查询刚做的操作，验证注入生效

Day 2-3（1 小时）：深度配置

阅读 ~/.claude-mem/config.json 了解可配置项
配置 max_context_tokens 和 project_filter（如有需要）
安装 Chrome 扩展或打开 Web UI（http://localhost:37777）查看记忆可视化

Day 4-5（1.5 小时）：生产环境验证

在真实项目（非 toy project）中启用
测试”跨 2-3 天”的记忆连续性
评估 token 消耗是否符合预期

Day 6-7（1 小时）：避坑与收尾

复盘是否遇到”坑与规避清单”中的问题
配置定时清理任务（cron 或 npm script）
备份一次 SQLite 数据库到云存储
将使用体验和问题记录到团队知识库

附：快速命令速查

# 安装插件
claude /plugin install claude-mem

# 检查状态
curl http://localhost:37777/health

# 手动触发压缩
claude > /mem-summarize "SESSION_SUMMARY"

# 查看 Web UI
open http://localhost:37777

# 清理旧记忆
claude-mem prune --older-than 90d

# 更新插件
claude /plugin update claude-mem

Claude-Mem 解决的是 AI 编程助手最根本的体验断点——记忆缺失。一个月用下来，你会明显感受到：处理”两周前那个模块的遗留 bug”时，不再需要从头解释上下文，AI 直接带着记忆上岗。这才是 AI 编程助手真正走向”靠谱同事”的关键一步。