Claude-Mem：让AI编程助手拥有跨会话记忆的插件

痛点/场景引入

你有没有过这样的经历？昨晚用Claude Code（Anthropic推出的AI编程工具）写了一晚上代码，让它改了十几个Bug，调整了数据库架构，还设计了一套新接口。结果今天早上打开新会话，Claude完全不记得昨天做了什么——你只能从头再讲一遍项目背景，重新解释一遍为什么要这样设计，再手把手告诉它上次踩过哪些坑。每次会话都像失忆后的重新相识，这种"金鱼记忆"让人抓狂。更惨的是多人协作场景：同事昨天的调试结论你今天完全不知道，只能重复相同的错误排查路径。AI编程助手再强，没有记忆也只是一次性工具。

项目是什么

Claude-Mem是一个专为Claude Code打造的持久化记忆压缩插件——它自动捕获你每次编程会话中Claude的所有操作，用AI压缩成语义摘要，并在你下次打开新会话时把相关上下文自动注入回来，让Claude真正拥有"跨会话记忆"。

核心功能

• 🧠 持久化记忆：上下文跨会话保留，关掉终端再打开，Claude还记得上次做了什么
• 📊 渐进式披露（Progressive Disclosure）：三层分层检索机制，先给你看精简索引（约50-100 token/条），你需要时再展开完整细节，节省约10倍token开销
• 🔍 智能搜索：支持用自然语言查询历史记录，比如"我们上次修复了什么Bug？"——Claude会自动调用MCP搜索工具（search、timeline、get_observations三层工作流）找到答案
• 🖥️ Web可视化界面：浏览器打开 http://localhost:37777，实时查看记忆流、搜索历史、调整配置
• 💻 Claude Desktop搜索：不只是Claude Code，从Claude Desktop对话中也能搜索记忆
• 🔒 隐私控制：用 <private> 标签包裹敏感内容，自动排除存储，防止密码、密钥等泄漏
• ⚙️ 精细上下文配置：可控制注入哪些类型的观察（Bug修复/功能/重构/发现/决策/变更），哪些概念标签（工作原理/设计理由/变更摘要/问题与方案/坑点/模式/权衡）
• 🤖 全自动运行：安装后零手动干预，5个生命周期钩子（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd）全程自动运转
• 🔗 观察引用：每条观察都有唯一ID，可通过Web界面或API直接引用查看
• 🧪 Beta频道：支持尝鲜实验性功能，如"无尽模式（Endless Mode）"——仿生记忆架构，适用于超长会话
• 🌐 多AI提供商：默认用Claude处理观察，也可切换为OpenRouter（支持100+模型，含免费模型）或Gemini（有免费额度）
• 📝 多IDE支持：不仅支持Claude Code，还支持Gemini CLI、Cursor、Windsurf等

安装步骤

前提条件

在安装Claude-Mem之前，你需要先确保以下环境就绪：

方法一：npx 一键安装（推荐）

这是最简单的方式，一条命令搞定一切：

Mac / Linux：

npx claude-mem install

Windows（PowerShell）：

npx claude-mem install

Windows注意事项： 如果你看到 npm : The term 'npm' is not recognized 的错误，说明Node.js没加到PATH环境变量。去 https://nodejs.org 下载最新版安装包，安装后重启终端就行。

交互式安装器会自动完成以下工作：

1. 检测你电脑上安装的IDE（Claude Code、Cursor、Gemini CLI、Windsurf等）
2. 把插件文件复制到正确位置
3. 向Claude Code注册插件
4. 安装所有依赖（包括Bun和uv）
5. 自动启动Worker后台服务

安装完成后重启Claude Code，你会在新会话中看到来自之前会话的上下文自动出现。

方法二：Claude Code插件市场安装

如果你已经在Claude Code会话中，可以直接用插件命令安装：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

然后重启Claude Code即可。

⚠️ 重要提醒： npm install -g claude-mem 只安装SDK/库，不会注册插件钩子也不会启动Worker服务。务必用上面两种方式之一安装。

方法三：安装到Gemini CLI

如果你用的是Google的Gemini CLI而不是Claude Code：

npx claude-mem install --ide gemini-cli

安装器会自动检测 ~/.gemini 目录并配置相应文件。

方法四：从源码构建（开发者进阶）

想参与开发或需要最新未发布功能：

# 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# 安装依赖
npm install

# 构建钩子和Worker服务
npm run build

# Worker服务会在首次Claude Code会话时自动启动
# 或者手动启动：
npm run worker:start

# 验证Worker是否运行
npm run worker:status

安装后验证

安装完成后，按以下步骤确认一切正常：

1. 确认插件钩子已配置：

cat plugin/hooks/hooks.json

你应该能看到SessionStart、UserPromptSubmit、PostToolUse、Stop等钩子配置。

2. 查看数据目录：

ls ~/.claude-mem/

应该包含：

• claude-mem.db — SQLite数据库，存所有会话记忆
• .install-version — 缓存版本号，供智能安装器使用
• worker.port — Worker服务的当前端口号
• logs/ — 日志目录

3. 检查Worker日志：

npm run worker:logs

没有报错就说明运行正常。

4. 测试上下文检索：

npm run test:context

看到输出说明记忆注入功能正常工作。

5. 打开Web可视化界面：

浏览器访问 http://localhost:37777，应该能看到Claude-Mem的管理界面。

使用方法

基础用法：装好就忘——全自动运行

Claude-Mem的设计理念就是"装完不管"。安装后的完整工作循环如下：

1. 你启动Claude Code → SessionStart钩子自动运行，查询数据库，把最近10个会话的上下文注入到Claude的初始上下文中
2. 你正常工作 → 每次Claude使用工具（读文件、写文件、执行命令等），PostToolUse钩子自动捕获这个操作
3. Claude回复结束 → Stop钩子自动生成会话摘要（包含：你请求了什么、探索了什么、学到了什么、完成了什么、下一步该做什么）
4. 你下次打开会话 → 之前的工作上下文自动出现在新会话中

你什么都不用做，记忆就在后台自动积累和生效。

捕获的信息类型包括：Claude读的文件内容、新建的文件、修改的代码、执行的命令、文件搜索结果、内容搜索结果，以及所有其他Claude Code工具操作。

每条观察会被Worker服务处理后提取出：

• 标题 — 简要描述发生了什么
• 副标题 — 补充上下文
• 叙述 — 详细解释
• 要点 — 关键成果的要点列表
• 概念标签 — 相关分类标签（如how-it-works、gotcha、problem-solution等）
• 类型 — 分类标记（决策、Bug修复、功能、重构、发现、变更等）
• 关联文件 — 涉及了哪些文件

进阶用法一：用自然语言搜索历史记录

Claude-Mem提供了智能MCP搜索工具，你不需要记命令——直接用自然语言问Claude就行：

"我们上次会话修复了哪些Bug？"
"我们是怎么实现认证功能的？"
"worker-service.ts做过什么修改？"
"给我看下这个项目最近的工作"
"添加Web界面的时候发生了什么？"

Claude会自动识别你的意图并调用MCP搜索工具。搜索是三层渐进式工作流：

1. search — 获取精简索引（每条约50-100 token），返回ID列表
2. timeline — 获取特定时间点的上下文，看看前后还发生了什么
3. get_observations — 只对你筛选出的ID获取完整细节（每条约500-1000 token）

这种"先看目录再翻内容"的设计，相比一次性加载所有细节，大约节省10倍token开销。

进阶用法二：切换AI提供商降低成本

Claude-Mem默认用Claude（Agent SDK）来处理和压缩观察数据。但如果你在中国，Claude API的访问可能不太方便，或者你想降低成本，可以切换为其他提供商：

切换为OpenRouter（支持免费模型）：

1. 去 https://openrouter.ai 注册账号，创建API Key（不需要信用卡）
2. 编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-你的key",
  "CLAUDE_MEM_OPENROUTER_MODEL": "xiaomi/mimo-v2-flash:free"
}

默认的 xiaomi/mimo-v2-flash:free 是小米的MiMo-V2-Flash模型（309B参数MoE架构），完全免费，在SWE-bench Verified排名第一，编码和推理能力都很强。

其他免费模型选择：

• google/gemini-2.0-flash-exp:free — Google旗舰，1M上下文窗口
• deepseek/deepseek-r1:free — DeepSeek推理模型，671B参数
• meta-llama/llama-3.1-70b-instruct:free — Meta的70B通用模型

切换为Gemini：

{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "你的Gemini API Key",
  "CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash-lite"
}

Gemini有免费额度，适合预算有限的用户。

切换无需重启：在Web界面 http://localhost:37777 的设置里切换提供商，下一条观察就会用新提供商处理，不需要重启Worker服务。如果新提供商出错，会自动回退到Claude SDK处理，保证不中断。

实际场景举例

跟同类对比

目前市面上也有其他尝试给AI编程助手添加记忆能力的项目，下面是Claude-Mem与典型同类的对比：

为什么选Claude-Mem？ 核心原因是"全自动+智能压缩+高效检索"三位一体。你不需要手动维护任何记忆文件，不需要每次会话去翻阅日志，Claude-Mem像是一个默默工作的秘书——你写代码时它在一旁记录，你下次来时它把精华摊开在你面前。再加上渐进式披露设计和向量搜索，让token开销极低，这在Claude API按token计费的语境下非常实在。

配置进阶

上下文注入精细控制

打开 http://localhost:37777 的Web界面，点击右上角齿轮图标，可以精确控制什么内容被注入到新会话中：

加载设置：

• Observations（观察数量）：默认50，范围1-200。数值越高上下文越丰富但启动越慢
• Sessions（会话数量）：默认10，范围1-50

过滤设置——按类型：

• bugfix（Bug修复）、feature（新功能）、refactor（重构）、discovery（发现）、decision（决策）、change（变更）

过滤设置——按概念：

• how-it-works（工作原理）、why-it-exists（设计理由）、what-changed（变更摘要）、problem-solution（问题与方案）、gotcha（坑点）、pattern（模式）、trade-off（权衡）

显示设置：

• Full Observations Count：展开详细信息的最近N条观察，默认5，范围0-20
• Full Observations Field：展开时显示narrative（叙述）还是facts（要点）
• Token Economics：是否显示读取成本、工作投入、节省金额等token经济指标

如果不想用Web界面，也可以直接编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
  "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
  "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
  "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative"
}

手动Worker管理

虽然Worker会自动启动，但你也可以手动管理：

# 启动Worker服务（通常不需要，自动启动）
npm run worker:start

# 停止Worker服务
npm run worker:stop

# 重启Worker服务
npm run worker:restart

# 查看Worker日志
npm run worker:logs

# 检查Worker状态
npm run worker:status

自定义数据目录

如果你的磁盘空间紧张，可以把数据存在其他位置：

{
  "CLAUDE_MEM_DATA_DIR": "/data/claude-mem"
}

或者通过环境变量：

export CLAUDE_MEM_DATA_DIR=/data/claude-mem

自定义Worker端口

如果37777端口被占用了：

{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}

改完后重启Worker：npm run worker:restart

直接查询数据库

如果你想直接看原始数据，可以用SQLite命令行：

# 打开数据库
sqlite3 ~/.claude-mem/claude-mem.db

# 查看最近的会话
SELECT session_id, project, created_at, status FROM sdk_sessions ORDER BY created_at DESC LIMIT 10;

# 查看会话摘要
SELECT session_id, request, completed, learned FROM session_summaries ORDER BY created_at DESC LIMIT 5;

# 查看某个会话的所有观察
SELECT tool_name, created_at FROM observations WHERE session_id = 'YOUR_SESSION_ID';

调试与日志

遇到问题时，可以开启调试日志：

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

或者直接向Claude描述问题——Claude-Mem内置了troubleshoot技能，会自动诊断并提供修复方案。

生成Bug报告：

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

Beta频道切换

想体验实验性功能（如Endless Mode），打开 http://localhost:37777 → Settings → Version Channel → 点击"Try Beta (Endless Mode)"。切换回稳定版同样点"Switch to Stable"。记忆数据在切换时不会丢失，只更换插件代码。

导出导入记忆

Claude-Mem支持记忆的导出和导入，方便备份或迁移到其他机器。详见官方文档的 Memory Export/Import 页面。

小结

Claude-Mem是目前最成熟的Claude Code记忆插件（GitHub 55,800+ Stars），通过5个生命周期钩子全自动工作，AI语义压缩确保记忆高质量且token高效，三层渐进式披露+Chroma向量搜索让历史触手可及。对中国用户尤其友好的是，它支持OpenRouter免费模型（如小米MiMo-V2-Flash）和Gemini免费额度，可以实现零成本运行。

项目地址： https://github.com/thedotmack/claude-mem 官方文档： https://docs.claude-mem.ai/ Discord社区： https://discord.com/invite/J4wttp9vDu