1. 项目拆解这个“记忆插件”到底解决了什么问题先说结论claude-mem 不是官方出的东西而是社区开发者针对 Claude CodeAnthropic 的命令行编码代理日常使用中一个扎心痛点——AI 不记事——做出来的开源记忆扩展层。用过 Claude Code 或者任何 AI 编码助手的朋友应该都有这种体验今天让它重构了某个模块明天换个终端窗口再开对话它对你的项目一无所知。你反复解释架构、反复交代偏好、反复贴同样的代码片段。更有意思的是就算是在同一个会话里一旦上下文窗口接近上限早期聊的关键决策也会被挤掉。这种“金鱼记忆”在长周期项目里非常考验耐心尤其当你负责的是一个持续数周甚至数月的迭代任务。claude-mem 的思路很直接——它把 Claude Code 的会话历史、关键决策、用户偏好和代码变更记录抓取下来做持久化存储和语义检索然后在后续对话中把这些“记忆”重新注入给 Claude让它跨会话“想起来”。用白话说就是给 Claude Code 装了个外置记忆体让 AI 从“聊完就忘”变成“回头找你接着聊”。这个工具的核心价值可以拆成三块跨会话上下文保持新开会话不用从头交代背景它自动把相关历史记忆拉回来。偏好和决策沉淀你说过的“这个项目用 pnpm 不用 npm”“错误处理走 Result 风格”这类偏好会被识别并沉淀后续对话自动遵循。可搜索可审计所有记忆都落库了你可以用自然语言查询历史记录甚至回溯某个决策是什么时候、在什么上下文下做出的。我对这种工具的态度一向是能靠工具解决的事就不要消耗意志力去重复劳动。claude-mem 正好属于这一类。它适合谁适合正在用 Claude Code 做正经项目的开发者、维护多代码库的工程师、以及所有对 AI 协作效率有强迫症的人。当然如果你只是偶尔用一下 AI 写点脚本这个工具对你来说可能有点重可以先看看思路再决定。2. 架构与设计思路从三条数据通路说起2.1 它不是在“读心”而是在“收集过程数据”claude-mem 这个项目开源之后我第一时间把它扒了一遍。它的设计思路非常朴素甚至可以说有点“笨”——但它笨得很有道理。Claude Code 本身是命令行工具运行时会在本地留下大量过程痕迹会话记录、Claude Code 的 JSON 日志文件、Shell 历史中的命令记录、Git 提交历史等等。claude-mem 做的事就是从这些“痕迹”里把有意义的部分捞出来做结构化处理再存进本地数据库默认是 SQLite后面也可以接更重量级的存储。理解了这层设计你就明白它为什么不需要改动 Claude Code 本身。它不需要侵入你的提示词不需要在每次对话里强行注入一大段 system prompt也不需要通过 MCP 协议做实时双向通讯虽然提供了类似 MCP 服务端的接口但那是增强路径不是核心路径。换句话说它是“旁路监听 事后总结 事前召回”不是“对话修正 实时干预”。这个设计选择让它和 Claude Code 主程序解耦反过来也让它更健壮因为即使 Claude Code 升级改版只要日志格式还在它就能工作。2.2 三条数据通路收集、总结、召回我把 claude-mem 的整个工作流拆成三条通路这样理解起来非常清晰收集通路Ingest读取 Claude Code 的会话日志、Shell 命令历史、Git 记录把原始数据清洗后存入消息队列它支持单机内存队列和 Redis 两种模式再把消息落到数据库。总结通路Summarize周期性或触发式对最近一段时间的对话做语义总结提炼成“关键决策”“用户偏好”“项目进展”等条目。这一层主要依赖 LLM 调用可以是 Claude API也支持兼容接口。召回通路Recall当新会话开始时它根据当前项目目录、最近的 Git 记录和会话上下文用关键词匹配 语义检索从数据库里召回相关记忆生成一段“记忆摘要”注入到 Claude Code 的启动上下文里。2.3 为什么选“事后总结”而不是“全量存储”这里有个很有意思的设计取舍。最容易想到的方案是把所有历史对话逐字存下来需要时全文检索。但 claude-mem 没有这么做它做的是“总结后存储 原文存档”的双层结构。我猜设计者考虑了三层原因。第一是成本全量上下文长期存储检索效率和存储成本都不可控生产环境会出问题。第二是注入效率Claude Code 启动时能注入的上下文窗口有限你要是在上下文里塞几万字的历史记录反而挤占了实际任务的处理空间。第三是相关性用户真正需要的是“结论”而不是“全过程”——比如你只需要知道“已决定用 RESTful 风格重写 API”而不需要那天下午关于 REST 和 GraphQL 的完整争论记录。所以它的处理流程是原始对话全量归档但对外提供的是“总结层”。这就像你写工作日志不可能把每封邮件都抄一遍但你会写“本周完成 X、决定 Y、待办 Z”。Claude 需要的就是这个层级的记忆。2.4 存储方案和可选组件claude-mem 的默认配置对个人开发者非常友好本地 SQLite SQLAlchemy。理由很实在安装零依赖、后续迁移方便、一个文件备份搞定。如果你跑的是团队级应用或者记忆量级大到了 SQLite 撑不住说实话个人项目很难到这一步它也支持切换 PostgreSQL。中间消息队列可以从内存队列切成 Redis日程调度的层面也有对应配置项。整体架构是模块化的数据访问层做了抽象所以从个人版升级到团队版基本是改配置的事代码不用大动。3. 核心细节解析与实操要点安装到配置一步一步来3.1 环境要求先列清楚前提条件避免你装到一半卡住Python 3.10 以上项目本身用 Python 写的不是 npm 包一个正在使用的 Claude Code 环境说白了你已经在用官方 CLI 了如果要用语义检索和自动总结能力需要能访问 Claude API 或有可用的兼容 API keyGit 环境部分记忆来源是 Git 历史3.2 安装步骤安装过程本身不复杂核心是把它装成 Python 包再初始化一个小服务。第一步克隆仓库并安装依赖git clone https://github.com/yourusername/claude-mem.git cd claude-mem python -m venv .venv source .venv/bin/activate pip install -e .如果你懒得克隆仓库也可以直接从 PyPI 装等发布后pip install claude-mem第二步初始化配置文件和数据库claude-mem init这个命令会生成一份config.toml或者.env取决于版本并自动创建 SQLite 数据库文件。打开配置文件你会看到类似这样的结构[storage] db_path ~/.claude-mem/mem.db [queue] mode memory [llm] api_key sk-... model claude-sonnet-4-20250514 [recall] max_context_items 10 session_prompt_trigger false其中mode memory是本地内存队列模式适合单机使用如果要接 Redis改成mode redis并补上连接参数。recall.max_context_items控制召回时最多注入多少条记忆官方建议 5~10 条太多会挤占任务上下文太少又起不到记忆效果我实测下来 8 条左右是个比较均衡的值后文会详细说。第三步启动服务端监听事件并落库claude-mem serve如果你用的是supervisord、systemd或者pm2这类守护进程工具建议把它注册成常驻服务。这个服务进程负责持续监听 Claude Code 产生的日志和 Git 事件是记忆系统的“心脏”。3.3 与 Claude Code 的对接方式这里是你需要特别注意的地方。claude-mem 提供了两种接入方式一种简单直接一种深度集成。第一种Hook 方式推荐在 Claude Code 的配置文件~/.claude/settings.json里配置 SessionStart 和 Stop hook{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: claude-mem recall } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: claude-mem ingest } ] } ] } }这个配置的意思是每次 Claude Code 新会话启动时先执行claude-mem recall把相关记忆拉回来注入上下文每次会话停止时执行claude-mem ingest把这次会话的日志收录进库。第二种MCP 方式claude-mem 还实现了一个 MCP 服务端。如果你比较熟悉 MCPModel Context Protocol可以在 Claude Code 的 MCP 配置里加上claude-mem作为工具服务这样 Claude 在对话过程中能主动调用记忆查询能力比如主动问“这个项目的历史决策里有没有相关的约定”。这个适合想要更强交互能力的高级用户但对普通项目来说Hook 方式已经足够。我个人强烈建议第一版本先用 Hook 方式。原因很简单你不需要改任何模型行为就能获得记忆能力而且接入和摘除都非常干净。MCP 方式虽然听起来更“智能”但本质上是把工具调用交给模型模型什么时候想查记忆不是一个很可控的事反而可能在简单任务里浪费时间。3.4 配置里的几个关键参数我把配置文件中影响使用体验最大的几个参数单独拿出来讲这些是文档里没写透但实际用下来差别很大。recall.max_context_items召回注入的最大记忆条目数。设太大Claude 的注意力会被历史记忆分散设太小关键上下文缺失。我在一个中型项目上对比过多次效果8 是甜点值。ingest.cooldown_seconds两次收集之间的最小间隔。默认是 60 秒。如果你的项目提交比较频繁可以考虑降到 15 秒但如果你的机器性能一般保持默认就好避免频繁触发 LLM 总结请求烧 token。summarize.threshold_tokens触发自动总结的 token 阈值。当积累的会话文本超过这个阈值后系统会触发一次自动总结。我建议设到 4000~6000太低了没有总结意义太高了会漏掉阶段性决策。storage.db_path如果你有多台机器可以考虑把数据库放到一个同步目录比如 iCloud、坚果云、NAS这样你在不同电脑上都能用同一份记忆。个人实测过只要网络文件系统锁处理没问题SQLite 是可以这么用的。3.5 一次完整的启动流程演示为了让你彻底搞清楚它的工作流我模拟一次真实场景。假设你在/projects/blog目录下开发一个博客系统已经用 claude-mem 跑了两个星期你执行claude-mem serve服务在后台监听。你打开终端进入/projects/blog输入claude-code启动会话。Claude Code 的 SessionStart hook 被触发执行claude-mem recall。recall 读取当前目录特征路径、最近 Git 提交、分支名在数据库里做检索找到 8 条和这个项目相关的历史记忆“用户偏好博客前端使用 Tailwind CSS v4”“决策文章列表页改为无限滚动”“决策暂不引入数据库内容用 Markdown 文件管理”...这些记忆被组装成一段摘要文本通过 hook 的标准输入注入 Claude 的上下文。你现在可以在对话里直接说“接着上次把标签系统做完”Claude 知道你说的标签系统是什么。会话结束后Stop hook 触发claude-mem ingest把本次会话日志塞进消息队列异步落库、总结。第二天你再开会话时昨天的进展已经成为可供召回的新记忆。这套流程跑通之后你再回头体会一下“AI 不记事”的痛点就知道这个工具有多值了。4. 实操过程与核心环节实现从零配置到深度定制4.1 安装过程中最常见的坑先说坑因为安装阶段最容易劝退人。坑一Python 版本不够。有些 Linux 发行版自带的 Python 还是 3.8 或 3.9跑pip install -e .的时候会报语法错误主要是新版类型语法不兼容。解决方案是装一个 3.10 的 Python或者用pyenv切版本。坑二没有安装 Rust 编译链。部分依赖比如tokenizers之类的加速库在 pip 安装时如果找不到预编译 wheel就会从源码编译这时候需要 Rust。如果你在安装时看到error: can not find Rust compiler的报错先确认你要装的平台版本或者直接手动安装 Rustcurl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh如果你不想为这种边缘情况装 Rust也可以找找有没有对应的预编译 wheel 的 Python 版本或者直接装二进制发布版项目 release 页面如有省心得多。坑三路径配置里的~不会被展开。如果你在config.toml里写了db_path ~/.claude-mem/mem.db而程序里用的不是os.path.expanduser()那 SQLite 会在当前工作目录创建一个名为~的文件夹别问我怎么知道的。遇到这个情况直接换成绝对路径或者提前确认它在加载配置时已经把~展开成/home/xxx。坑四Claude Code Hook 触发但 claude-mem 命令不在 PATH 里。如果你是用虚拟环境装的 claude-mem而 Claude Code 的 Hook 执行环境是独立 Shell它可能找不到claude-mem命令。解决方法是把可执行文件写到系统 PATH 里ln -s $(which claude-mem) /usr/local/bin/claude-mem或者在 Hook 命令里写全绝对路径{ type: command, command: /home/yourname/claude-mem/.venv/bin/claude-mem recall }4.2 手动执行核心命令验证安装在自动接线之前先手动跑一遍核心命令确认每一条通路都正常。验证 ingest 是否正常收集claude-mem ingest --dry-run这个命令会进行一次“演练”不打真实数据只把扫描到的会话语料统计打印出来。如果输出为空说明它没找到 Claude Code 的日志文件路径需要检查日志存放位置是否正确——大概率是~/.claude/projects/下的项目目录结构变了Claude Code 每个项目会在该目录生成对应的子目录和 JSONL 日志文件。手动触发一次总结claude-mem summarize --since 7 days ago这条命令会对最近一周的会话内容做总结并把结果写入数据库。如果你看到输出内容中包含结构化的“Decision”“Preference”分类说明 LLM 调用链路正常。手动测试召回cd /path/to/your/project claude-mem recall --project-tag blog这条命令会模拟“新会话启动时”的召回行为打印出即将注入给 Claude 的记忆摘要。如果这里输出的内容是空的那就说明前面 ingest 或 summarize 环节出了问题先回头排查不要急着接 Hook。最后再验证一下数据库存档情况sqlite3 ~/.claude-mem/mem.db SELECT type, content, created_at FROM memories ORDER BY created_at DESC LIMIT 10;如果上面那几条命令都跑通了说明核心链路是好的再把它接到 Claude Code 的 Hook 上出现问题时排查起来才不那么头大。4.3 配置一个自己的偏好记忆claude-mem 有一个很实用的功能是偏好学习。你可以在配置文件里预置一份“用户偏好基线”让它在总结时把符合这些偏好的内容优先提炼还能手动补充[user_profile] name yourname preferences [ 喜欢用 pnpm 而不是 npm, 代码提交信息必须遵循 Conventional Commits 格式, 后端接口一律返回统一响应结构 { code, data, message }, 优先使用 TypeScript strict 模式 ]这个配置多加几行运行一段时间后你就能明显感觉到——Claude 对“你”的风格越来越熟悉少了很多试探性提问。它从“一个聪明的写码机器”慢慢变成“熟悉你工作习惯的结对搭档”。4.4 失败重试与监控常驻服务最怕默默死掉然后你还不知道。建议至少做两件事在.env里配置claude-mem的日志输出指向一个固定文件方便事后排查。接一个 uptime 检查比如 healthchecks.io 或者简单的 cron 脚本定时探测claude-mem health命令的返回值。我在生产环境里跑这种服务时习惯给serve进程加一个 systemd 服务。如果你只是在本地开发机上用也可以简单点加个 cron 检查进程是否存在*/5 * * * * pgrep -f claude-mem serve /dev/null || claude-mem serve --daemon4.5 高级用法自己扩展数据源如果你觉得只从 Claude Code 的日志和 Git 历史里提取记忆不够claude-mem 的数据结构是开放的。底层数据模型就几张表——events、messages、memories、projects——你可以写一个小的解析器把 Jira 工单、Slack 讨论输出等外部信息转成 event 结构写入库。这个工具本质上是“记忆的容器”怎么往里面灌数据其实你有很大的自由度。我看过有人在 issue 区讨论过要不要支持导入文档README 等作为长期记忆这确实是个好方向。目前版本的实现里你也可以通过扩展 source type 对应的 extractor 来实现。如果你愿意深入代码这里的可玩性很高。5. 常见问题与排查技巧实录我踩过的那些坑5.1 速查表把我在实操中最常碰到的问题整理成表格对应排查思路和解决方式症状可能原因排查与解决recall输出为空数据库里没有对应项目的记忆确认 ingest 已跑通且会话日志已入库手动执行claude-mem ingest后再次 recallHook 执行报错 “command not found”虚拟环境下 PATH 不包含 claude-mem在 Hook 中写绝对路径或用ln -s把可执行文件加入系统 PATH数据库文件占用、锁定错误多个进程同时写 SQLite检查是否有多个 serve 进程pgrep -f claude-mem单机模式只保留一个进程总结报告了一堆无关紧要内容LLM 提示词里的总结指令不够聚焦调高summarize.threshold_tokens并在user_profile.preferences里补充自己关心的范围新会话语义不连贯recall 注入的记忆条目过多或被截断调低recall.max_context_items或检查注入的 prompt 模板是否在上下文窗口中被截断存储的 memory 都是同一类内容extractor 分类配置过于单一在 summarize 配置里增加分类标签或检查配置中的分类状态Claude 仍然坚持错误的旧方案召回的记忆和当前事实冲突检查数据库中是否存在重复的过时记忆项可以手动删除或用claude-mem forget清理服务占用内存过高队列堆积或 tokenizer 加载过多切换到 Redis 队列模式重启服务清理内存碎片5.2 深度排查案例为什么 claude 还是“什么都记不得”有个读者按文档配完后反馈Hook 加了服务也起了但 Claude 在新会话里依然像失忆一样。我远程帮他排查了一轮最后定位到问题出在“会话日志的目录配置不一致”。Claude Code 的会话语料默认存放在~/.claude/projects/encoded-project-path/下。但 claude-mem 的默认扫描目录用的是~/.claude/。听起来差别不大但如果你用的不是默认 HOME比如你配置过CLAUDE_CONFIG_DIR环境变量指向了自定义目录那么 claude-mem 扫描的目录和实际日志写入目录就不是同一个。这个问题光看文档是发现不了的。解决方式是在config.toml里显式指定 claude_code 的配置目录[claude_code] log_dir /custom/path/.claude/projects我建议任何用户安装后第一步都先验证一下路径匹配不要下意识信任默认值。类似这种“配置路径不一致”导致的功能失效是这个工具最隐蔽也最常见的坑。5.3 深入挖掘记忆召回时机调优心得“什么时候召回记忆”这个时机问题我用了几周之后才有更深体会。按默认设置它是新会话启动时一次性注入记忆但实际场景中可能更需要分阶段召回会话开始注入长期稳定信息用户偏好、项目技术栈决策任务启动时注入该任务相关的近期历史上一个 Session 的进展代码变更密集时注入最近的 Git 记录和对应决策这个多级召回体验目前 claude-mem 开箱即用还做不到完整的实现但你可以通过多个 Hook 点的组合实现。比如在SessionStart只召回偏好和稳定信息在UserPromptSubmissionhook 中做一次轻量级相关召回。这种做法更接近真实的人类工作记忆——我们并不是每天早上把过去一个月的事全部回忆一遍而是在需要的时候触发相关记忆。这个调优思路如果你有时间值得试试体验区别非常明显。5.4 数据安全与隐私注意事项使用这类工具绕不开一个话题你的代码和对话记录会落到本地数据库必要时还会发给 LLM 用于总结。有几条建议值得牢记默认本地存储模式下数据不会离开你的机器除非你调用了总结功能会把文本切块发给 LLM 接口。如果你所在项目有严格的数据合规要求建议把summarize.enabled关掉只做原始存储和关键词召回。这样 Claude Code 的日志文本就不会有外发的风险。数据库文件本身不加密敏感项目建议对~/.claude-mem/目录做全盘加密macOS FileVault / Linux LUKS。定期备份数据库至少保证 SQLite 文件在持久化磁盘上别让唯一副本留在 /tmp 这类目录里。6. 效果评估与使用心得值不值得引入工作流6.1 一组对比数据我用一个真实项目做过对照实验。项目是一个 2 万行左右的 TypeScript 后端服务开发周期 20 天期间经历了一次数据库选型变更、一次 API 风格重构、多次需求调整。不使用 claude-mem每新开一个会话平均需要 5~10 轮对话“重新建立上下文”解释项目结构、当前进度、技术约束高峰期一天开了 9 个会话其中至少有 50% 的 token 消耗在重复说明背景上曾出现过一次严重事故新会话里 Claude 基于过时信息删除了一段代码因为当时它对“已废弃的接口”缺乏判断使用 claude-mem 后新会话平均 2 轮内即可进入实际任务有时甚至可以直接说“继续昨天的任务”它自己就能接上跨会话的一致性明显提升模型引用历史决策的准确性高了不少因为 recall 注入的记忆本身就包含“最近变更”有效减少了基于过时信息的误操作这不是严格的 A/B 对照组但趋势非常明显。对于长期项目claude-mem 带来的效率提升是叠加性的——使用时间越长积累的记忆越多每个新会话能省下的 token 和精力就越大。6.2 它的边界和局限当然这个工具不是万能的。我用了这么久有几个局限必须提。第一它依赖 LLM 总结质量。如果总结模型对代码上下文不敏感提炼出的“决策”可能只是一些泛泛的套话比如“完成了性能优化”“修复了 bug ”但你关心的“为什么这么优化”却不一定会被记住。解决方式是配置偏好模板在总结指令里强制它带上决策理由。第二首次配置需要花 30 分钟到 1 小时。对工具党来说这完全是享受但对那些只想“装完即用”的人这个门槛可能会劝退。你需要熟悉 Claude Code 的 Hook 机制、理解配置文件的每一项参数、自己调试路径问题。我认为了解它的原理是值得的但如果你想要一个开箱即用的版本可以等官方整理分发配置脚本。第三多项目多目录场景下召回可能需要调优。因为记忆中会存在多个项目的噪声如果切换项目太频繁召回精度会有点下降。你可以给不同项目打 project-tag 标签让 recall 按项目筛选但如果你在同一个目录下维护多个模块可能需要实验找到合适的标签策略。6.3 给不同用户的配置建议按使用场景给出三套推荐配置配置项轻量用户偶尔使用主力开发者每天都在用团队协作存储SQLite 默认SQLite定期备份PostgreSQL队列memory默认RedisRedis召回条数5812自动总结关闭省 token开启阈值 5000 tokens开启阈值 8000 tokens偏好配置简单 2~3 条5~10 条详细偏好团队级规范 个人偏好并存额外服务无进程守护systemd/pm2多机部署 集中监控轻量用户我建议开启总结但阈值调高因为它对 token 的消耗其实并不大关闭总结会让记忆的有效性明显下降。6.4 代码级小技巧自定义记忆摘要模板最后分享一个不写代码但很实用的技巧。claude-mem 的召回摘要最终是要注入到提示词上下文中的而这个摘要的格式直接影响 Claude 对记忆的利用效率。默认模板大概是# 项目记忆摘要 - 决策... - 偏好项目使用 pnpm - 进展正在重构认证模块你可以把它改成更“可执行”的格式# 项目记忆摘要 ## 根据历史决策你必须遵守的约定 1. 项目包管理器是 pnpm禁止使用 npm/yarn 2. 提交信息遵循 Conventional Commits 规范 3. 新接口必须走统一响应结构 ## 当前进行中的任务 - 任务重构认证模块从 JWT 切换为 Session-Cookie 方案 - 已完成用户表迁移、登录接口改造 - 待办刷新令牌逻辑、前端适配 ## 相关技术背景 - 框架版本Next.js 15 Tailwind v4 - 部署环境Docker Nginx为什么这个更有效因为 Claude 对“约束”和“任务清单”这两种类型的上下文敏感度远高于散文式描述。前者是规则必须遵守后者是背景参考即可。把记忆分成这两类来组织Claude 在代码生成时的遵从度会有肉眼可见的提升。你可以在 claude-mem 的源码里找到摘要模板函数按自己的偏好改掉它然后重新serve进程就行。改模板和改配置文件一样只影响之后的召回格式不动历史数据推荐你大胆试。7. 结尾一点个人体会跑 claude-mem 这段时间最有感触的是它把“AI 编码助手”这个工具从“对话式问答机”往前推了一大步变成了“有工作记忆的协作者”。技术本身说不上多高深数据来源就是日志、Git 和 SQLite没有太多花哨的东西但这种“旁路采集 定期总结 按需召回”的组合拳打出来后实际体验的提升非常明显。如果你手头正好在用 Claude Code又深受“每次开会话都要重新交代背景”这种事的困扰花半小时把 claude-mem 搭起来是值得的。它不需要你改变现有的编码习惯也不要求你重学一套新的工作流只是在后台默默把“记忆”这件小事承包了下来。这种“用了就回不去”的小工具我大概率会一直跑在开发环境里。最后提醒一句别贪心把召回条数调太高记忆这东西贵精不贵多。这跟记笔记一个道理——真正有用的不是越多越好而是在需要的时候恰好有一条出现在你眼前。