1. 从聊完就忘说起claude-mem 到底想解决什么如果你用 Claude 这类对话式 AI 做过稍微长期一点的项目大概率遇到过这种尴尬昨天花了半小时跟它对齐的代码规范、目录结构、命名习惯今天开个新会话它全忘了又得从头讲一遍。更别提那种跨天、跨周的持续开发——每次都要把背景重新喂一遍token 烧得心疼人也被磨得没脾气。claude-mem这个项目从名字就能看出它的野心给 Claude 装一个记忆。它不是官方功能而是社区里有人实在受不了这种金鱼记忆自己动手做的一套记忆层方案。核心思路很朴素——把对话里值得留存的信息抽出来存到本地下次开新会话时再按需注入回去。听起来简单但真要做稳里面有一堆细节要处理存什么、怎么存、什么时候取、取多少、怎么防止污染上下文。这篇内容适合三类人看一是天天跟 Claude 打交道、被上下文窗口折磨的开发者和写作者二是想自己搭一套AI 长期记忆的折腾党三是单纯好奇记忆这件事在工程上到底怎么落地的人。我会把 claude-mem 这类方案的底层逻辑、实操步骤、踩坑经验一次讲透代码和配置都能直接抄。先说结论记忆系统的难点从来不是存而是取和忘。存谁都会往文件里一写就完事但要在正确的时机、把正确的信息、以正确的粒度塞回上下文这才是真正拉开差距的地方。claude-mem 的价值就在于它把这套存取策略工程化了。2. claude-mem 的记忆模型它到底在存什么2.1 三种记忆类型的分层设计一个能用的记忆系统绝不会把所有东西一股脑塞进一个池子。claude-mem 这类方案通常会把记忆分成几层我按实际项目里最常见的划分来讲会话级记忆Session Memory当前这次对话里的临时上下文比如你刚说的这个函数先别改它只在本次会话有效会话结束就丢。这层其实靠模型自带的上下文窗口就够了不需要额外存储。项目级记忆Project Memory跟具体项目绑定的长期信息比如技术栈、目录约定、API 规范、已知的坑。这层是 claude-mem 的主战场通常以结构化文件形式存在项目目录下。用户级记忆User Memory跨项目的个人偏好比如我喜欢用 TypeScript 严格模式注释写中文别给我写过度设计的抽象。这层跟着人走不跟着项目走。为什么要分三层因为它们的生命周期和作用范围完全不同。会话级的东西存下来就是噪音用户级的偏好塞进项目文件又会污染仓库。分层之后每层可以独立设置过期策略和注入优先级这是整个系统能保持干净的前提。2.2 记忆的粒度为什么整段对话是最差的选择新手最容易犯的错是把整段对话历史原封不动存下来下次直接贴回去。这么干有两个致命问题一是 token 爆炸二是信噪比极低——对话里 80% 是寒暄、试错、重复确认真正有价值的可能就两三句话。claude-mem 的做法是抽取式记忆从对话里提炼出事实和决策而不是保留原始文本。比如一段关于数据库选型的讨论最终存下来的可能就一行[决策] 数据库选用 PostgreSQL 15理由是团队熟悉 JSONB 支持好这种粒度有几个好处体积小、可读性强、方便人工审阅和修改。你可以直接打开记忆文件看到 AI记住了什么发现记错了随手改掉。这一点非常重要——记忆必须可审计否则一旦 AI 记了个错误的前提后面所有对话都会被带偏而且你还不知道问题出在哪。2.3 存储格式为什么我推荐 Markdown 而不是向量库很多人一提到记忆就想到向量数据库觉得不上个 embedding 就不够高级。但实际用下来对于个人和小团队场景纯 Markdown 文件 关键词检索往往比向量库更实用。原因有三第一可读可改。Markdown 你随时能打开看向量库里的东西你得写脚本才能查。第二无依赖。不用跑一个数据库服务不用管 embedding 模型的版本一个文件夹搞定。第三检索可控。向量检索是黑盒你不知道它为什么召回了这条而不是那条关键词检索虽然笨但行为完全可预测。向量库不是没用它适合记忆量极大几千条以上、语义检索需求强的场景。但对绝大多数人来说你的项目记忆可能就几十上百条Markdown 完全够用而且省心得多。claude-mem 的轻量路线恰恰是它比那些重型记忆框架更好落地的原因。3. 把 claude-mem 跑起来从零到可用的完整步骤3.1 环境准备与目录结构假设你已经有一个在用的 Claude 工作流不管是网页版还是 API 调用我们要做的是在项目根目录建一套记忆文件并让每次对话开始时自动加载。先建目录结构我习惯这样组织your-project/ ├── .claude-mem/ │ ├── project.md # 项目级记忆 │ ├── user.md # 用户级偏好可软链到全局 │ └── sessions/ # 会话级临时记忆可定期清理 │ └── 2024-06-01.md ├── src/ └── ....claude-mem/这个隐藏目录放在项目根下跟着 git 走user.md可以加进.gitignore因为它是个人偏好。为什么用隐藏目录因为它不该干扰正常的项目浏览但又必须离项目足够近方便脚本定位。3.2 记忆文件的初始模板project.md我建议用固定的小节结构这样 AI 读起来有预期抽取信息时也更容易对齐# 项目记忆 ## 技术栈 - 语言TypeScript 5.xstrict 模式 - 框架React 18 Vite - 数据库PostgreSQL 15 ## 目录约定 - 组件放 src/components一个组件一个文件夹 - 工具函数放 src/utils纯函数优先 ## 已知的坑 - Vite 的 HMR 在 monorepo 下偶尔失效改配置后重启 ## 重要决策 - [2024-05-20] 状态管理选 Zustand 而非 Redux理由是轻量user.md则更简单就是一堆偏好条目# 用户偏好 - 代码注释用中文 - 不要写过度设计的抽象层 - 回答先给结论再给理由 - 涉及命令时给出可直接复制的完整命令这套模板的关键在于小节固定、内容自由。固定小节让检索和注入有章可循自由内容保证灵活性。3.3 自动加载让记忆在会话开始时注入光有文件没用得让 Claude 每次开新会话时读到它。最土但最稳的办法是在你的调用脚本里把记忆内容拼到 system prompt 前面。如果你用 API大概长这样import pathlib def build_system_prompt(project_root: str) - str: mem_dir pathlib.Path(project_root) / .claude-mem parts [] for name in [user.md, project.md]: f mem_dir / name if f.exists(): parts.append(f# 来自 {name}\n{f.read_text(encodingutf-8)}) base 你是一个严谨的开发助手以下是需要长期记住的背景信息\n\n return base \n\n.join(parts)如果你用的是网页版 Claude没法改 system prompt那就退而求其次把记忆内容做成一个开场白模板每次新会话第一句话就粘贴进去。虽然手动但胜在零门槛。提示注入顺序有讲究。用户偏好放最前面项目记忆放后面。因为偏好是怎么回答的元规则项目记忆是回答什么的素材元规则优先级更高。3.4 记忆的写入什么时候该记什么时候不该记自动写入是最容易翻车的地方。我的建议是初期手动为主、自动为辅。具体做法在对话里约定一个触发词比如你说记一下AI 就把当前结论追加到project.md对应小节。这样你能完全掌控记什么。等用顺了再考虑半自动让 AI 在每次会话结束时输出一段本次值得留存的内容你扫一眼确认后追加。全自动写入我试过问题在于 AI 判断什么值得记的标准跟你不一致经常记一堆废话或者漏掉关键决策。记忆的写入质量直接决定整个系统的可用性这一步千万别偷懒。4. 检索与注入策略记忆系统的真正难点4.1 全量注入 vs 按需检索最简单的策略是每次把整个project.md全量注入。项目小的时候没问题但记忆一旦超过几百行全量注入就开始吃 token 了而且会稀释真正相关的信息。按需检索的思路是根据当前对话内容只挑相关的记忆条目注入。实现方式可以很朴素——关键词匹配。比如当前对话提到数据库就把project.md里含数据库PostgreSQL的条目挑出来。别小看这种笨办法实测在几十到几百条记忆的规模下效果比想象中好。我一般会设一个阈值记忆总量小于 200 行就全量注入超过就切到关键词检索。这个数字不是拍脑袋200 行大约 3000-4000 token对大多数模型的上下文来说是可以接受的固定开销。4.2 关键词检索的一个可落地实现import re def retrieve_memory(memory_text: str, query: str, top_k: int 10) - str: # 按空行切分成条目 entries [e.strip() for e in memory_text.split(\n\n) if e.strip()] # 提取 query 里的关键词简单按非字母数字切分 keywords set(re.findall(r[\w\u4e00-\u9fa5], query.lower())) scored [] for e in entries: e_lower e.lower() score sum(1 for kw in keywords if kw in e_lower) if score 0: scored.append((score, e)) scored.sort(keylambda x: -x[0]) picked [e for _, e in scored[:top_k]] return \n\n.join(picked) if picked else 这段代码很糙但能跑。它的核心逻辑是把记忆切成条目按关键词命中数排序取前 K 条。你可以在此基础上加权重——比如重要决策小节的条目权重更高或者最近修改的条目优先。4.3 注入位置为什么放在 system prompt 末尾更好记忆内容放 system prompt 的哪个位置效果是有差别的。放最前面模型可能读完就忘放最后面离用户输入最近模型注意力更集中。我的经验是放在 system prompt 的末尾紧挨着用户消息召回效果最好。另外注入时最好加个明确的分隔标记比如 长期记忆开始 记忆内容 长期记忆结束 这样模型能清楚知道哪部分是背景知识哪部分是当前任务不容易混淆。5. 实测中踩过的坑与应对5.1 记忆污染AI 把错误前提当成了事实这是最坑的一个问题。有次我在对话里随口说了句这个接口应该是返回数组的其实是我记错了。结果 AI 把这条记进了project.md之后连续几天所有相关对话都基于这个错误前提直到我某天翻记忆文件才发现。应对办法有两个一是记忆写入必须人工确认别让 AI 自动写二是定期审阅记忆文件我习惯每周扫一遍project.md把过时和错误的条目删掉。记忆系统跟代码一样需要维护不是建好就一劳永逸。5.2 上下文膨胀记忆越攒越多token 越烧越狠用了一个月后我的project.md涨到了 500 多行每次全量注入光记忆就吃掉 8000 token。这时候必须做减法。我的做法是给记忆条目加最后验证时间超过 30 天没被引用过的条目移到archive.md归档不再注入。真正活跃的记忆其实就那么几十条剩下的都是历史包袱。5.3 冲突记忆新旧决策打架项目演进过程中决策会变。比如早期决定用 Redux后来换成 Zustand。如果两条都留在记忆里AI 就会精神分裂。解决办法是决策类记忆必须带时间戳且新决策要显式覆盖旧决策。我在project.md里维护一个重要决策小节每次新决策就替换掉旧的而不是追加。历史决策如果需要保留移到归档文件。5.4 跨项目串味用户偏好和项目记忆的边界有次我把一个项目的技术栈记忆误同步到了另一个项目导致 AI 在新项目里一直推荐旧项目的方案。根源是user.md和project.md的职责没分清。技术栈、目录约定这类东西属于项目级绝不能进用户级只有回答风格注释语言这种跨项目通用的才进用户级。这条边界一旦模糊记忆系统就会开始互相污染。6. 让记忆系统真正好用的几个进阶思路6.1 给记忆加引用计数自动识别冷热前面提到归档冷记忆怎么判断冷热可以给每条记忆加一个引用计数每次被检索命中并注入计数加一。定期把计数低的条目归档。这个机制能让记忆库自动新陈代谢不用你手动清理。实现上就是在条目后面加个!-- ref: 12 --这样的注释脚本读取和更新。6.2 记忆的版本化跟 git 一起管理.claude-mem/目录跟着 git 走意味着记忆的每次变更都有历史记录。这带来一个额外好处你可以git diff看记忆是怎么演变的某条错误记忆是什么时候、在哪次提交里混进来的一目了然。我甚至会给记忆文件单独写 commit message比如mem: 更新数据库选型决策方便回溯。6.3 分场景的多记忆文件当项目复杂到一定程度单个project.md会变得臃肿。这时候可以按领域拆分memory/frontend.md、memory/backend.md、memory/deploy.md。检索时根据当前对话涉及的领域只加载对应的文件。这样既控制了单次注入量又保持了记忆的组织性。拆分维度按你的项目实际来没有标准答案。6.4 和 RAG 的关系什么时候该上向量检索如果你的记忆条目超过几千条或者需要语义相似而非关键词命中的检索比如用户问性能优化你想召回所有跟慢卡顿延迟相关的记忆那可以考虑上向量检索。但我的建议是先用关键词方案跑三个月确认记忆量真的到了瓶颈再升级。过早引入向量库只会增加维护成本收益却未必明显。7. 我个人的使用体会折腾 claude-mem 这类方案大半年最大的感受是记忆系统的价值不在于记得多而在于记得准和忘得掉。一个只有 50 条精炼记忆的系统远比一个塞了 500 条垃圾的系统好用。很多人一上来就想搞全自动、搞向量库、搞花哨的检索算法结果基础的信息质量控制没做好系统很快就变成一团乱麻。如果你刚开始我的建议就三条第一从手动写入开始每条记忆都经过你确认第二用 Markdown 存别急着上数据库第三每周花十分钟审阅和清理记忆文件。把这三件事坚持一个月你会发现自己跟 AI 协作的效率有质的提升——不用再反复交代背景AI 真的开始懂你的项目了。最后分享一个小技巧我会在project.md开头放一句如果记忆内容与当前对话冲突以当前对话为准。这句话能有效防止过时记忆压制新信息是个成本极低但很管用的保险。