最近一直在折腾本地开发环境里的 AI 辅助编程流程有个绕不开的痛点当前主流的对话式编程工具默认都是无状态的。你跟它聊了一个小时好不容易把项目背景、代码规范、命名习惯都交代清楚关掉终端再开一个新会话它完全不记得你昨天说过什么。我已经不止一次在同一个项目里反复向它解释“这个服务用 Python 3.12命名空间必须保持分层、数据库表名一律蛇形”每次都像是第一次见面。claude-mem 这个工具就是冲这个痛点来的它给对话工具补上了一块“长期记忆”让每个新会话都能自动带上之前积累的项目偏好、技术约束和历史决策。这篇文章聊聊我实际使用 claude-mem 的理解、配置过程和踩过的坑。它不是官方功能而是一种“记忆层”方案跑在 Claude 周边负责把对话里值得记住的东西抽出来、存起来、在合适的时机再塞回给模型。适合正在用 Claude 做日常开发、又不想每次重复喂上下文的开发者参考也适合那些想给团队 AI 工作流加一层“项目记忆”的人。1. 为什么需要给 Claude 补上记忆1.1 无状态对话才是常态不少人对大模型的印象是“什么都知道”但落到对话场景里模型其实像个鱼只有七秒记忆的选手。每一次新会话的起跑线都差不多只有系统提示词、你的第一句话以及上下文窗口里能装下的内容。窗口再长也是有限的项目聊得越久前面的约定就越容易滑出窗口。我最早是用“每次对话开头粘贴一段项目说明”来对抗这个问题。写了个模板文件里面放技术栈、目录结构、命名约定、已完成事项每次开会话先丢给它。刚开始挺好用但模板文件本身需要维护而且每次粘贴都要消耗不少 token。更重要的是模板里全是“一次性事实”项目演进以后旧信息没人清理经常出现模板里说用旧框架、代码里早换成新框架的尴尬局面。1.2 手工维护上下文为什么不可持续后来试过几个变体把项目说明写进 README、用系统提示词固定加载某个文档、在对话里要求模型“总结一下今天的内容并输出到文件”。这些方案都有一个共同问题它们依赖人的纪律性。你忙起来会忘记更新你的同事不会按你的格式写时间一长这些“辅助记忆”本身就变成了需要维护的负债。对话摘要还有一个隐藏缺陷摘要是一次性快照丢了上一轮摘要后面的“原文”新摘要很容易丢失细节。比如模型把“用户要求使用 PostgreSQL理由是团队熟、运维省心”压成“使用 PostgreSQL”两周后你再看到这条记忆时已经想不起当初背后的决策原因了。记忆不是单纯的关键词缓存它需要保留上下文、来源和信任等级这正是手工方案做不好的地方。1.3 claude-mem 解决的是哪一层问题claude-mem 的定位不是在对话里“加一句话”而是给模型外挂一个长期存储对话结束以后它把这次会话产生的、值得长期保留的信息抓取出来结构化存进本地数据库下一次新会话开始时它从数据库里按相关性捞出一批记忆注入到系统提示或对话开头让模型一上来就带着“上一次的记忆”。这个思路听起来简单真正要紧的设计在于三个环节抓什么、怎么存、怎么取。抓得太多会污染上下文抓得太少会漏关键约束存得杂乱会检索不到检索到不相关的记忆又等于白注入。claude-mem 的价值就在于把这三个环节做成了一套可配置的流水线不是把全部历史倒给模型而是像人一样“想起来什么就说什么”。2. 整体设计思路拆解记忆是怎么存下来并派上用场的2.1 存储底座选型SQLite 为什么比 JSON 靠谱第一版做记忆功能的时候很多人会本能地想到“写个 JSON 文件不就行了”。确实最早期原型可以直接把记忆数组追加到文件里读取也简单。但记忆一旦上规模JSON 的维护成本立刻上来了并发写入要自己加锁检索一条记忆要遍历整个数组字段要升级时还得写迁移脚本。SQLite 的优势恰好对上了这个场景。它是单文件数据库一个 memory.db 文件就能装下全部记忆备份、迁移、换机器都只需要拷贝一个文件不需要单独跑数据库服务。它支持事务写入过程中断电不会留下半截记录自带 FTS5 全文检索查关键词不用自己写索引还能方便地加新字段比如后面要存 embedding 向量、存来源会话 ID只要加列就行。2.2 记忆条目的字段设计一条记忆要存多少信息才够用我拆解下来至少需要这几类内容本身、归属信息、状态信息、来源信息。归属信息包括它是哪个项目、哪个会话、哪个用户产生的这决定了记忆会不会串味状态信息包括创建时间、最近访问时间、访问次数、是否被固定这决定了记忆的“权重”怎么算来源信息则记录它是从哪段对话提炼出来的方便回溯。id : 唯一标识UUID scope : 记忆所属范围如 project / user / global project_id : 项目标识用于多项目隔离 session_id : 来源会话标识便于回溯上下文 content : 记忆正文通常是一段结构化描述 memory_type : 记忆类型如偏好、决策、事实、约定、环境配置 importance : 重要性评分取值范围 0 到 1 pinned : 是否固定固定后不会被自动遗忘 created_at : 创建时间 last_access_at : 最近被注入到对话的时间 access_count : 累计被注入次数用于计算热度和权重 source : 来源信息比如会话标题、消息摘要这些字段看起来琐碎但它们决定了后续所有算法能不能跑起来。没有 importance 和 access_count你就只能对所有记忆一视同仁注入时必然会出现“旧的不重要的压过了新的重要信息”的情况。没有 project_id多个项目共用一个记忆库尽量别碰这个场景后面我会专门说。2.3 记忆生命周期的三个阶段一条记忆从产生到被使用要经过抓取、沉淀、注入三个阶段。抓取阶段发生在对话进行中或结束后claude-mem 分析对话内容把“用户偏好”“技术决策”“问题解决方案”这类信息提炼出来。它不是把对话原文存进去而是生成一句概括性的话比如原文是“这个项目不要用 pip 装包我们统一走 uv”存下来的记忆可能就是“项目依赖管理统一使用 uv禁止直接用 pip install”。沉淀阶段做的事情是去重、合并、评分。如果新记忆跟旧记忆说的是同一件事可以选择丢弃新内容也可以更新旧内容的最后访问时间如果发现旧记忆已经过时比如技术栈换了旧的那条应该降权或删除。这个过程需要判断规则做得太激进会误删做得太保守又会让记忆库膨胀。注入阶段是关键新会话开始前claude-mem 根据当前项目和历史交互情况筛选出一批相关度最高的记忆拼接成一段“记忆上下文”注入到模型的对话开头。这里不能全量注入否则几百条记忆塞进去模型根本分不清重点还白白占掉大量 token。2.4 与 Claude 的集成方式这个工具不修改模型本身而是在外层做包装。如果你用的是 Claude Code 这种终端编程工具它提供了 hook 机制允许在用户输入前、工具调用后等时机执行外部脚本。claude-mem 就靠这些 hook 挂进去用户每次提问前先查记忆、注入记忆工具返回后再抽取新的可记住内容写入数据库。如果不用 Claude Code而是直接用 API也可以把它当成一个中间层请求发出前调用 claude-mem 的查询命令把返回结果拼进 system prompt再把请求发给模型。这样设计的好处是解耦记忆逻辑坏了不影响模型本身模型版本升级也不需要跟着改。3. 安装与五分钟快速上手3.1 环境准备与安装命令我实际的环境是 macOS Node.js 18项目本身是 Python 后端。claude-mem 是基于 Node.js 的工具安装前请确认机器上有 Node 18 或更高版本安装命令很简单全局装一次后面所有项目都能用。具体包名和发布渠道以你拿到的版本说明为准我这里给的是通用的安装思路。# 检查 Node 版本 node -v # 全局安装 npm install -g claude-mem # 验证安装 claude-mem --version # 初始化默认配置和数据目录 claude-mem initinit 命令会在你的用户目录下生成一个配置文件夹里面包含空数据库文件 config.json 和 memory.db。到这里工具本身已经能跑了但还没接上 Claude所以它还不知道该什么时候去“想”记忆。3.2 初始化与项目隔离接入前建议先给项目设一个标识这是很多人会跳过的一步。如果只有一个全局记忆库所有项目的记忆混在一起A 项目的技术决策很可能被注入到 B 项目的会话里那体验会非常灾难。建议的用法是每个项目一个逻辑空间在项目根目录执行一条链接命令让 claude-mem 记住“当前目录对应哪个项目”。# 在项目根目录执行建立项目关联 claude-mem link --project web-backend执行之后后续从这个目录发起的会话都会被标记上 web-backend 这个 project_id。后面哪怕是同一台机器上的多个项目记忆在数据库里也是按 project_id 隔离的注入时只捞当前项目的记忆。3.3 配置 Hook 让记忆自动流转Claude Code 的配置文件通常位于用户目录或项目目录下的 .claude/settings.json。在里面声明 hooks让 Claude 在特定事件触发时调用 claude-mem。我采用的配置思路是在用户输入提交前读取记忆、在每次工具调用后异步抓取新记忆。大致结构如下具体事件名和参数格式以你使用的版本为准。{ hooks: { UserPromptSubmit: [ { matcher: *, command: claude-mem inject } ], PostToolUse: [ { matcher: *, command: claude-mem capture --async } ] } }UserPromptSubmit 里的 inject 会在每次提问前运行把当前项目的高权重记忆注入进上下文。PostToolUse 里的 capture 则是在模型调用完工具后把刚刚的交互内容交给记忆抓取器分析。用 --async 是为了不让它阻塞对话流程记忆抽取在后台排队执行你感知不到它的存在。3.4 第一次实测从“失忆”到“记得”配好后我做了一个最简单的验证实验。第一个会话里告诉 Claude“这个项目的数据库表名全部用蛇形命名不要用驼峰历史原因是我们团队所有 SQL 规范都基于蛇形。”然后正常聊点代码结束会话等几秒让后台把这段对话抓完。关掉终端重新开一个会话我没有手动粘贴任何项目说明直接问它“我们这个项目的数据库命名规范是什么”它回答里直接出现了“表名采用 snake_case”这个结论还附带了一句“这是之前对话中确定的约定”。那一刻我终于感觉到它不是每隔七秒就失忆的鱼了。4. 核心机制与关键参数详解4.1 记忆抽取策略很多人会误以为记忆是把整段对话存进数据库其实不是。抽取的目的不是备份聊天记录而是提炼“以后还能用”的事实。实际抽取时claude-mem 一般会关注这么几类信息用户的显式偏好“我喜欢用 X”、项目级决策“我们决定用 Y 替换 Z”、问题解决方案“这个报错是因为缺少环境变量解决办法是……”、团队约定“代码评审要求……”。抽取可以设计成规则式也可以设计成让模型参与提炼。用规则式的话主要靠关键词和消息模板匹配快但漏得多用模型参与的话会先让当前对话的模型自己总结一段“本次对话产生了哪些长期记忆”再经过清洗写入。后者效果更好但会额外消耗一次模型调用具体取舍要看你对成本和质量的平衡。4.2 记忆注入的排序与限流记忆注入不是“随机挑几条”而是按权重排序。设计权重时我会重点考虑三个维度相关度、时间衰减和访问热度。相关度解决“这条记忆跟当前问的问题沾不沾边”时间衰减解决“三个月前的决策是否还有参考价值”访问热度解决“哪些记忆被频繁使用可能是核心约束”。可以简化地用这样一个加权思路当然实际实现会有更复杂的算法score 0.4 * 相关度 0.3 * 时间衰减分 0.2 * 访问热度 0.1 * 是否固定其中“是否固定”就是 pinned 字段它是一票否决性质的加分项用于那些绝对不能被遗忘的核心项。注入时还需要设置一个 token 上限比如 max_inject_tokens 默认控制在 2000 到 4000 之间。超过上限就只取排序靠前的记忆宁可少注入也不要一次性塞几十条让模型抓不住重点。4.3 自然语言查询与记忆维护除了自动注入还需要一个手动查询通道方便你自己确认“它到底记住了什么”。claude-mem 的命令行里我常用这几个子命令命令作用典型场景list列出当前项目全部记忆检查记忆库是否膨胀search按关键词或语义搜索记忆确认某条约定是否被记住pin固定某条记忆加了高权重不让核心偏好被遗忘机制清掉unpin取消固定一条约定不再适用时forget删除指定记忆旧技术决策作废时手动清理dump导出全部记忆为可读文本备份、迁移、团队同步restore从备份恢复记忆库换机器后找回历史search 这里有个值得说的点如果启用了语义检索它会先对查询词做向量化再和记忆条目算相似度能解决“关键词没对上但意思一样”的问题。代价是要额外配置向量计算的接口。如果没启用就退回 SQLite 的全文检索够用了偶尔会漏。4.4 遗忘机制的重要性记忆系统最容易被忽略的是“遗忘”。如果什么都存永远不清理过不了多久记忆库就会变成垃圾场过时技术栈的旧决策、已经改掉的命名规范、临时踩坑时的权宜解决方案全都堆在一起。自动注入时它们还会抢权重干扰后来的正确决策。遗忘有两层设计一层是软遗忘旧记忆不删除只是权重越来越低几乎不会被注入另一层是硬淘汰当记忆条数超过容量上限时自动清理掉那些低频、低重要度、未固定的记忆。硬淘汰容易被骂误删所以通常只作用于“从来没被访问过、又不重要”的条目。设计原则是遗忘也要有理由不能随机删。我的习惯是定期跑一遍 list看到明显过时的条目直接 forget而不是完全依赖自动清理。5. 常见问题与排查技巧实录5.1 配置了 Hook 但记忆完全不生效这个问题的典型现象是对话聊了半天claude-mem list 里一条记忆都没有或者 list 有记忆但新会话注入没有任何效果。我遇到过的原因有三个。第一个是 hooks 根本没触发。排查方法是先在终端手动执行一遍 claude-mem inject 和 claude-mem capture看命令本身能不能跑通如果报错就说明路径或参数有问题大概率是全局安装的 node 模块没有出现在 Claude Code 子进程的 PATH 里用绝对路径去调用可以绕过。第二个是 hook 事件名跟版本对不上。工具更新后事件名可能改变如果配置是照着旧文档抄的静默失败非常正常。第三个是记忆抽取出来但注入内容被系统提示截断了。需要看调试日志确认注入内容是否真的进入了发送给模型的上下文。5.2 记忆重复、过时与冲突跑了一阵子之后发现记忆库里有四五条都在说“数据库表名用蛇形命名”措辞不同意思一样。这通常是因为每次对话产生相似表达时去重逻辑没能识别出来。解决方法是开启更严格的内容归一化或者提高去重阈值让“看起来差不多”的条目自动合并。更复杂的情况是旧记忆和新记忆冲突比如周一约定“接口返回字段用驼峰”周三改成“统一用蛇形”两条同时留在库里。模型注入时可能先看到旧记忆做出错误判断。我的处理经验是重要约定发生变化时主动手动 forget 掉旧的那条再让新的留下来。别指望工具能完全读懂你的心思。5.3 会话开头越来越“啰嗦”注入内容被模型输出的第一个回答里直接引用但描述了一大堆通用原则反而把真正跟当前任务相关的记忆淹没了。这个现象说明权重排序出了问题或者注入上限设得太高。我看到的情况是max_inject_tokens 默认给的比较大里面混入了一批低相关度的记忆模型在长上下文里抓不住重点。把注入上限从 4000 压到 2000再把相关度权重拉高效果会明显改善。另一个习惯是遇到具体重要问题直接用 search 查询而不是依赖自动注入手动注入的结果往往更准。5.4 多项目串味与敏感信息泄露在一台机器上同时维护两三个项目时最容易出现“A 项目的约定出现在 B 项目的回答里”。项目隔离配置不严格就可能这样。检查点有三个是否每个项目都执行了 link数据库里的 project_id 是否各不相同搜索时有没有带项目过滤条件。关于敏感信息如果记忆库里混入了密钥、token、账号等这是很危险的。最好在配置里加 ignore_patterns对匹配到密码、AK/SK 的消息直接跳过提取。另外记忆库默认存在本地如果是团队共享明文存储要考虑加密方案。以下是我整理的一份快速排查参考。现象可能原因检查项记忆完全没有注入Hook 未触发 / PATH 异常手动执行 claude-mem inject记忆抓取不到新内容capture 没跑 / 抽取策略太严查看 debug 日志、检查会话长度注入内容太多上限过高 / 相关度权重低调低 max_inject_tokens项目记忆串味未做项目隔离检查 project_id 配置敏感信息被抓进去未配置忽略规则配置 ignore_patterns5.5 切换机器与备份恢复记忆库是单文件迁移成本低但也容易丢。换机器最稳妥的做法是定期执行 claude-mem dump把记忆导出成文本文件存到自己的备份渠道里。到了新机器先做 init再把备份文件 restore 进去最后重新 link 项目。不要试图直接拷贝 memory.db 到正在运行的进程上可能出现锁冲突。6. 进阶玩法与扩展思路6.1 用 pin 固化核心偏好跑了一段时间之后记忆库里最重要的几条基本固定下来了。比如“对外接口统一使用 OpenAPI 3.1 规范”“数据库迁移必须走迁移脚本不允许手动改表结构”这类条目我全部 pin 掉。固定之后它们总会出现在注入列表中不参与低权重淘汰也不受时间衰减影响。使用 pin 不要太随意我见过有人把一二十条都 pin 住结果每次注入全是固定内容新的重要信息反而挤不进来。我的建议是核心偏好控制在五条以内让固定项起到锚点作用就好。6.2 团队共享记忆库如果项目是团队协作可以让成员共享同一份记忆库文件比如放在一个共享盘或者同步目录里。这样一个人跟 Claude 确定的代码规范其他人打开新会话时也能继承到。注意并发访问同一个 SQLite 文件有锁问题最适合的模式是“单写多读”由一个人或一个定时任务统一写入其余人只读。另外一个折中方案是把记忆导出成文本放进项目仓库的 docs 目录让 Claude 在需要时自动读取。虽然失去了一些自动化但胜在透明Git 记录能清楚看到每条记忆的变更历史。6.3 跟任务管理、定时任务结合我额外做了一个定时任务每天凌晨跑一次 claude-mem capture把当天所有会话的剩余记忆一次性抓到库里。原理是把最近 24 小时的会话记录喂给抽取器让它可以跨多个会话总结出一个“今日决策汇总”。这样即使某些中间会话没有触发 capture后续也能补上。还可以把 claude-mem 和项目里的 Git 提交消息打通。每次提交代码前把当前提交的内容用模型总结成一句话追加到记忆里形成“哪天、因为什么、改了什么”的项目时间线。后续再开会话问“上次那个限流方案为什么改”模型能直接从记忆里找到答案比翻 Git log 快得多。6.4 把 claude-mem 当“第二大脑”的边界用它一段时间后我开始意识到记忆工具的最大价值不是“省 token”而是让对话真正有积累。人跟 AI 协作的过程中最有价值的部分不是某一次代码生成而是你在讨论中逐渐形成的决策链。这条链以前只存在于某个人的脑子和聊天记录里现在可以被持久化、被查询、被传播。但它也有边界它存储的是你已经说出来的内容不是你还没想清楚的东西它擅长记录事实和约定不擅长帮你做深度推理。别指望一个记忆库能把一个项目的完整背景全装下记忆库的意义是让你和模型每次都站在更新的起点上而不是替代你思考。我现在的习惯是每周花五分钟翻一下记忆库该合并的合并、该删的删把遗忘权重新掌握在自己手里。最后分享一个小技巧我平时会在重要项目里专门开一条 session命名为“项目决策日志”隔几天就跟 Claude 聊几句近期遇到的问题、做了什么决定。会话结束后让 claude-mem 把这段内容抓进记忆库相当于给整个项目不定期打“记忆快照”。这个习惯不花多少时间但长期积累下来模型对你的项目了解程度会越来越接近一个跟队多年的老成员。 
长河君 · 2026/10/10 4:26:38 · 阅读 1.2k Claude-mem 实战：给 AI 编程助手补上长期记忆
最近一直在折腾本地开发环境里的 AI 辅助编程流程有个绕不开的痛点当前主流的对话式编程工具默认都是无状态的。你跟它聊了一个小时好不容易把项目背景、代码规范、命名习惯都交代清楚关掉终端再开一个新会话它完全不记得你昨天说过什么。我已经不止一次在同一个项目里反复向它解释“这个服务用 Python 3.12命名空间必须保持分层、数据库表名一律蛇形”每次都像是第一次见面。claude-mem 这个工具就是冲这个痛点来的它给对话工具补上了一块“长期记忆”让每个新会话都能自动带上之前积累的项目偏好、技术约束和历史决策。这篇文章聊聊我实际使用 claude-mem 的理解、配置过程和踩过的坑。它不是官方功能而是一种“记忆层”方案跑在 Claude 周边负责把对话里值得记住的东西抽出来、存起来、在合适的时机再塞回给模型。适合正在用 Claude 做日常开发、又不想每次重复喂上下文的开发者参考也适合那些想给团队 AI 工作流加一层“项目记忆”的人。1. 为什么需要给 Claude 补上记忆1.1 无状态对话才是常态不少人对大模型的印象是“什么都知道”但落到对话场景里模型其实像个鱼只有七秒记忆的选手。每一次新会话的起跑线都差不多只有系统提示词、你的第一句话以及上下文窗口里能装下的内容。窗口再长也是有限的项目聊得越久前面的约定就越容易滑出窗口。我最早是用“每次对话开头粘贴一段项目说明”来对抗这个问题。写了个模板文件里面放技术栈、目录结构、命名约定、已完成事项每次开会话先丢给它。刚开始挺好用但模板文件本身需要维护而且每次粘贴都要消耗不少 token。更重要的是模板里全是“一次性事实”项目演进以后旧信息没人清理经常出现模板里说用旧框架、代码里早换成新框架的尴尬局面。1.2 手工维护上下文为什么不可持续后来试过几个变体把项目说明写进 README、用系统提示词固定加载某个文档、在对话里要求模型“总结一下今天的内容并输出到文件”。这些方案都有一个共同问题它们依赖人的纪律性。你忙起来会忘记更新你的同事不会按你的格式写时间一长这些“辅助记忆”本身就变成了需要维护的负债。对话摘要还有一个隐藏缺陷摘要是一次性快照丢了上一轮摘要后面的“原文”新摘要很容易丢失细节。比如模型把“用户要求使用 PostgreSQL理由是团队熟、运维省心”压成“使用 PostgreSQL”两周后你再看到这条记忆时已经想不起当初背后的决策原因了。记忆不是单纯的关键词缓存它需要保留上下文、来源和信任等级这正是手工方案做不好的地方。1.3 claude-mem 解决的是哪一层问题claude-mem 的定位不是在对话里“加一句话”而是给模型外挂一个长期存储对话结束以后它把这次会话产生的、值得长期保留的信息抓取出来结构化存进本地数据库下一次新会话开始时它从数据库里按相关性捞出一批记忆注入到系统提示或对话开头让模型一上来就带着“上一次的记忆”。这个思路听起来简单真正要紧的设计在于三个环节抓什么、怎么存、怎么取。抓得太多会污染上下文抓得太少会漏关键约束存得杂乱会检索不到检索到不相关的记忆又等于白注入。claude-mem 的价值就在于把这三个环节做成了一套可配置的流水线不是把全部历史倒给模型而是像人一样“想起来什么就说什么”。2. 整体设计思路拆解记忆是怎么存下来并派上用场的2.1 存储底座选型SQLite 为什么比 JSON 靠谱第一版做记忆功能的时候很多人会本能地想到“写个 JSON 文件不就行了”。确实最早期原型可以直接把记忆数组追加到文件里读取也简单。但记忆一旦上规模JSON 的维护成本立刻上来了并发写入要自己加锁检索一条记忆要遍历整个数组字段要升级时还得写迁移脚本。SQLite 的优势恰好对上了这个场景。它是单文件数据库一个 memory.db 文件就能装下全部记忆备份、迁移、换机器都只需要拷贝一个文件不需要单独跑数据库服务。它支持事务写入过程中断电不会留下半截记录自带 FTS5 全文检索查关键词不用自己写索引还能方便地加新字段比如后面要存 embedding 向量、存来源会话 ID只要加列就行。2.2 记忆条目的字段设计一条记忆要存多少信息才够用我拆解下来至少需要这几类内容本身、归属信息、状态信息、来源信息。归属信息包括它是哪个项目、哪个会话、哪个用户产生的这决定了记忆会不会串味状态信息包括创建时间、最近访问时间、访问次数、是否被固定这决定了记忆的“权重”怎么算来源信息则记录它是从哪段对话提炼出来的方便回溯。id : 唯一标识UUID scope : 记忆所属范围如 project / user / global project_id : 项目标识用于多项目隔离 session_id : 来源会话标识便于回溯上下文 content : 记忆正文通常是一段结构化描述 memory_type : 记忆类型如偏好、决策、事实、约定、环境配置 importance : 重要性评分取值范围 0 到 1 pinned : 是否固定固定后不会被自动遗忘 created_at : 创建时间 last_access_at : 最近被注入到对话的时间 access_count : 累计被注入次数用于计算热度和权重 source : 来源信息比如会话标题、消息摘要这些字段看起来琐碎但它们决定了后续所有算法能不能跑起来。没有 importance 和 access_count你就只能对所有记忆一视同仁注入时必然会出现“旧的不重要的压过了新的重要信息”的情况。没有 project_id多个项目共用一个记忆库尽量别碰这个场景后面我会专门说。2.3 记忆生命周期的三个阶段一条记忆从产生到被使用要经过抓取、沉淀、注入三个阶段。抓取阶段发生在对话进行中或结束后claude-mem 分析对话内容把“用户偏好”“技术决策”“问题解决方案”这类信息提炼出来。它不是把对话原文存进去而是生成一句概括性的话比如原文是“这个项目不要用 pip 装包我们统一走 uv”存下来的记忆可能就是“项目依赖管理统一使用 uv禁止直接用 pip install”。沉淀阶段做的事情是去重、合并、评分。如果新记忆跟旧记忆说的是同一件事可以选择丢弃新内容也可以更新旧内容的最后访问时间如果发现旧记忆已经过时比如技术栈换了旧的那条应该降权或删除。这个过程需要判断规则做得太激进会误删做得太保守又会让记忆库膨胀。注入阶段是关键新会话开始前claude-mem 根据当前项目和历史交互情况筛选出一批相关度最高的记忆拼接成一段“记忆上下文”注入到模型的对话开头。这里不能全量注入否则几百条记忆塞进去模型根本分不清重点还白白占掉大量 token。2.4 与 Claude 的集成方式这个工具不修改模型本身而是在外层做包装。如果你用的是 Claude Code 这种终端编程工具它提供了 hook 机制允许在用户输入前、工具调用后等时机执行外部脚本。claude-mem 就靠这些 hook 挂进去用户每次提问前先查记忆、注入记忆工具返回后再抽取新的可记住内容写入数据库。如果不用 Claude Code而是直接用 API也可以把它当成一个中间层请求发出前调用 claude-mem 的查询命令把返回结果拼进 system prompt再把请求发给模型。这样设计的好处是解耦记忆逻辑坏了不影响模型本身模型版本升级也不需要跟着改。3. 安装与五分钟快速上手3.1 环境准备与安装命令我实际的环境是 macOS Node.js 18项目本身是 Python 后端。claude-mem 是基于 Node.js 的工具安装前请确认机器上有 Node 18 或更高版本安装命令很简单全局装一次后面所有项目都能用。具体包名和发布渠道以你拿到的版本说明为准我这里给的是通用的安装思路。# 检查 Node 版本 node -v # 全局安装 npm install -g claude-mem # 验证安装 claude-mem --version # 初始化默认配置和数据目录 claude-mem initinit 命令会在你的用户目录下生成一个配置文件夹里面包含空数据库文件 config.json 和 memory.db。到这里工具本身已经能跑了但还没接上 Claude所以它还不知道该什么时候去“想”记忆。3.2 初始化与项目隔离接入前建议先给项目设一个标识这是很多人会跳过的一步。如果只有一个全局记忆库所有项目的记忆混在一起A 项目的技术决策很可能被注入到 B 项目的会话里那体验会非常灾难。建议的用法是每个项目一个逻辑空间在项目根目录执行一条链接命令让 claude-mem 记住“当前目录对应哪个项目”。# 在项目根目录执行建立项目关联 claude-mem link --project web-backend执行之后后续从这个目录发起的会话都会被标记上 web-backend 这个 project_id。后面哪怕是同一台机器上的多个项目记忆在数据库里也是按 project_id 隔离的注入时只捞当前项目的记忆。3.3 配置 Hook 让记忆自动流转Claude Code 的配置文件通常位于用户目录或项目目录下的 .claude/settings.json。在里面声明 hooks让 Claude 在特定事件触发时调用 claude-mem。我采用的配置思路是在用户输入提交前读取记忆、在每次工具调用后异步抓取新记忆。大致结构如下具体事件名和参数格式以你使用的版本为准。{ hooks: { UserPromptSubmit: [ { matcher: *, command: claude-mem inject } ], PostToolUse: [ { matcher: *, command: claude-mem capture --async } ] } }UserPromptSubmit 里的 inject 会在每次提问前运行把当前项目的高权重记忆注入进上下文。PostToolUse 里的 capture 则是在模型调用完工具后把刚刚的交互内容交给记忆抓取器分析。用 --async 是为了不让它阻塞对话流程记忆抽取在后台排队执行你感知不到它的存在。3.4 第一次实测从“失忆”到“记得”配好后我做了一个最简单的验证实验。第一个会话里告诉 Claude“这个项目的数据库表名全部用蛇形命名不要用驼峰历史原因是我们团队所有 SQL 规范都基于蛇形。”然后正常聊点代码结束会话等几秒让后台把这段对话抓完。关掉终端重新开一个会话我没有手动粘贴任何项目说明直接问它“我们这个项目的数据库命名规范是什么”它回答里直接出现了“表名采用 snake_case”这个结论还附带了一句“这是之前对话中确定的约定”。那一刻我终于感觉到它不是每隔七秒就失忆的鱼了。4. 核心机制与关键参数详解4.1 记忆抽取策略很多人会误以为记忆是把整段对话存进数据库其实不是。抽取的目的不是备份聊天记录而是提炼“以后还能用”的事实。实际抽取时claude-mem 一般会关注这么几类信息用户的显式偏好“我喜欢用 X”、项目级决策“我们决定用 Y 替换 Z”、问题解决方案“这个报错是因为缺少环境变量解决办法是……”、团队约定“代码评审要求……”。抽取可以设计成规则式也可以设计成让模型参与提炼。用规则式的话主要靠关键词和消息模板匹配快但漏得多用模型参与的话会先让当前对话的模型自己总结一段“本次对话产生了哪些长期记忆”再经过清洗写入。后者效果更好但会额外消耗一次模型调用具体取舍要看你对成本和质量的平衡。4.2 记忆注入的排序与限流记忆注入不是“随机挑几条”而是按权重排序。设计权重时我会重点考虑三个维度相关度、时间衰减和访问热度。相关度解决“这条记忆跟当前问的问题沾不沾边”时间衰减解决“三个月前的决策是否还有参考价值”访问热度解决“哪些记忆被频繁使用可能是核心约束”。可以简化地用这样一个加权思路当然实际实现会有更复杂的算法score 0.4 * 相关度 0.3 * 时间衰减分 0.2 * 访问热度 0.1 * 是否固定其中“是否固定”就是 pinned 字段它是一票否决性质的加分项用于那些绝对不能被遗忘的核心项。注入时还需要设置一个 token 上限比如 max_inject_tokens 默认控制在 2000 到 4000 之间。超过上限就只取排序靠前的记忆宁可少注入也不要一次性塞几十条让模型抓不住重点。4.3 自然语言查询与记忆维护除了自动注入还需要一个手动查询通道方便你自己确认“它到底记住了什么”。claude-mem 的命令行里我常用这几个子命令命令作用典型场景list列出当前项目全部记忆检查记忆库是否膨胀search按关键词或语义搜索记忆确认某条约定是否被记住pin固定某条记忆加了高权重不让核心偏好被遗忘机制清掉unpin取消固定一条约定不再适用时forget删除指定记忆旧技术决策作废时手动清理dump导出全部记忆为可读文本备份、迁移、团队同步restore从备份恢复记忆库换机器后找回历史search 这里有个值得说的点如果启用了语义检索它会先对查询词做向量化再和记忆条目算相似度能解决“关键词没对上但意思一样”的问题。代价是要额外配置向量计算的接口。如果没启用就退回 SQLite 的全文检索够用了偶尔会漏。4.4 遗忘机制的重要性记忆系统最容易被忽略的是“遗忘”。如果什么都存永远不清理过不了多久记忆库就会变成垃圾场过时技术栈的旧决策、已经改掉的命名规范、临时踩坑时的权宜解决方案全都堆在一起。自动注入时它们还会抢权重干扰后来的正确决策。遗忘有两层设计一层是软遗忘旧记忆不删除只是权重越来越低几乎不会被注入另一层是硬淘汰当记忆条数超过容量上限时自动清理掉那些低频、低重要度、未固定的记忆。硬淘汰容易被骂误删所以通常只作用于“从来没被访问过、又不重要”的条目。设计原则是遗忘也要有理由不能随机删。我的习惯是定期跑一遍 list看到明显过时的条目直接 forget而不是完全依赖自动清理。5. 常见问题与排查技巧实录5.1 配置了 Hook 但记忆完全不生效这个问题的典型现象是对话聊了半天claude-mem list 里一条记忆都没有或者 list 有记忆但新会话注入没有任何效果。我遇到过的原因有三个。第一个是 hooks 根本没触发。排查方法是先在终端手动执行一遍 claude-mem inject 和 claude-mem capture看命令本身能不能跑通如果报错就说明路径或参数有问题大概率是全局安装的 node 模块没有出现在 Claude Code 子进程的 PATH 里用绝对路径去调用可以绕过。第二个是 hook 事件名跟版本对不上。工具更新后事件名可能改变如果配置是照着旧文档抄的静默失败非常正常。第三个是记忆抽取出来但注入内容被系统提示截断了。需要看调试日志确认注入内容是否真的进入了发送给模型的上下文。5.2 记忆重复、过时与冲突跑了一阵子之后发现记忆库里有四五条都在说“数据库表名用蛇形命名”措辞不同意思一样。这通常是因为每次对话产生相似表达时去重逻辑没能识别出来。解决方法是开启更严格的内容归一化或者提高去重阈值让“看起来差不多”的条目自动合并。更复杂的情况是旧记忆和新记忆冲突比如周一约定“接口返回字段用驼峰”周三改成“统一用蛇形”两条同时留在库里。模型注入时可能先看到旧记忆做出错误判断。我的处理经验是重要约定发生变化时主动手动 forget 掉旧的那条再让新的留下来。别指望工具能完全读懂你的心思。5.3 会话开头越来越“啰嗦”注入内容被模型输出的第一个回答里直接引用但描述了一大堆通用原则反而把真正跟当前任务相关的记忆淹没了。这个现象说明权重排序出了问题或者注入上限设得太高。我看到的情况是max_inject_tokens 默认给的比较大里面混入了一批低相关度的记忆模型在长上下文里抓不住重点。把注入上限从 4000 压到 2000再把相关度权重拉高效果会明显改善。另一个习惯是遇到具体重要问题直接用 search 查询而不是依赖自动注入手动注入的结果往往更准。5.4 多项目串味与敏感信息泄露在一台机器上同时维护两三个项目时最容易出现“A 项目的约定出现在 B 项目的回答里”。项目隔离配置不严格就可能这样。检查点有三个是否每个项目都执行了 link数据库里的 project_id 是否各不相同搜索时有没有带项目过滤条件。关于敏感信息如果记忆库里混入了密钥、token、账号等这是很危险的。最好在配置里加 ignore_patterns对匹配到密码、AK/SK 的消息直接跳过提取。另外记忆库默认存在本地如果是团队共享明文存储要考虑加密方案。以下是我整理的一份快速排查参考。现象可能原因检查项记忆完全没有注入Hook 未触发 / PATH 异常手动执行 claude-mem inject记忆抓取不到新内容capture 没跑 / 抽取策略太严查看 debug 日志、检查会话长度注入内容太多上限过高 / 相关度权重低调低 max_inject_tokens项目记忆串味未做项目隔离检查 project_id 配置敏感信息被抓进去未配置忽略规则配置 ignore_patterns5.5 切换机器与备份恢复记忆库是单文件迁移成本低但也容易丢。换机器最稳妥的做法是定期执行 claude-mem dump把记忆导出成文本文件存到自己的备份渠道里。到了新机器先做 init再把备份文件 restore 进去最后重新 link 项目。不要试图直接拷贝 memory.db 到正在运行的进程上可能出现锁冲突。6. 进阶玩法与扩展思路6.1 用 pin 固化核心偏好跑了一段时间之后记忆库里最重要的几条基本固定下来了。比如“对外接口统一使用 OpenAPI 3.1 规范”“数据库迁移必须走迁移脚本不允许手动改表结构”这类条目我全部 pin 掉。固定之后它们总会出现在注入列表中不参与低权重淘汰也不受时间衰减影响。使用 pin 不要太随意我见过有人把一二十条都 pin 住结果每次注入全是固定内容新的重要信息反而挤不进来。我的建议是核心偏好控制在五条以内让固定项起到锚点作用就好。6.2 团队共享记忆库如果项目是团队协作可以让成员共享同一份记忆库文件比如放在一个共享盘或者同步目录里。这样一个人跟 Claude 确定的代码规范其他人打开新会话时也能继承到。注意并发访问同一个 SQLite 文件有锁问题最适合的模式是“单写多读”由一个人或一个定时任务统一写入其余人只读。另外一个折中方案是把记忆导出成文本放进项目仓库的 docs 目录让 Claude 在需要时自动读取。虽然失去了一些自动化但胜在透明Git 记录能清楚看到每条记忆的变更历史。6.3 跟任务管理、定时任务结合我额外做了一个定时任务每天凌晨跑一次 claude-mem capture把当天所有会话的剩余记忆一次性抓到库里。原理是把最近 24 小时的会话记录喂给抽取器让它可以跨多个会话总结出一个“今日决策汇总”。这样即使某些中间会话没有触发 capture后续也能补上。还可以把 claude-mem 和项目里的 Git 提交消息打通。每次提交代码前把当前提交的内容用模型总结成一句话追加到记忆里形成“哪天、因为什么、改了什么”的项目时间线。后续再开会话问“上次那个限流方案为什么改”模型能直接从记忆里找到答案比翻 Git log 快得多。6.4 把 claude-mem 当“第二大脑”的边界用它一段时间后我开始意识到记忆工具的最大价值不是“省 token”而是让对话真正有积累。人跟 AI 协作的过程中最有价值的部分不是某一次代码生成而是你在讨论中逐渐形成的决策链。这条链以前只存在于某个人的脑子和聊天记录里现在可以被持久化、被查询、被传播。但它也有边界它存储的是你已经说出来的内容不是你还没想清楚的东西它擅长记录事实和约定不擅长帮你做深度推理。别指望一个记忆库能把一个项目的完整背景全装下记忆库的意义是让你和模型每次都站在更新的起点上而不是替代你思考。我现在的习惯是每周花五分钟翻一下记忆库该合并的合并、该删的删把遗忘权重新掌握在自己手里。最后分享一个小技巧我平时会在重要项目里专门开一条 session命名为“项目决策日志”隔几天就跟 Claude 聊几句近期遇到的问题、做了什么决定。会话结束后让 claude-mem 把这段内容抓进记忆库相当于给整个项目不定期打“记忆快照”。这个习惯不花多少时间但长期积累下来模型对你的项目了解程度会越来越接近一个跟队多年的老成员。