claude-mem：为AI构建本地持久化记忆层，解决跨会话上下文遗忘

1. 项目缘起与核心定位

1.1 从一次“记忆断片”说起

做长期项目的人大概都遇到过这种场景：跟一个AI助手聊了半小时，把需求、约束、偏好都交代得清清楚楚，结果关掉窗口再打开，它像换了个人，之前说过的全忘了。你得重新解释一遍项目背景、代码规范、命名习惯，甚至上次踩过的坑。这种重复劳动消耗的不只是时间，更是耐心。

claude-mem这个项目，本质上就是在解决这个问题。它是一个给 Claude 系列工具做持久化记忆层的方案，让AI在跨会话、跨项目的时候，能记住你是谁、你在做什么、你偏好什么风格。你可以把它理解成给AI装了一个“外部大脑”，所有重要的上下文都存在本地，需要的时候自动调取，而不是每次从零开始。

我第一次接触这个方向是在做一个持续三个月的重构项目时。项目里有大量约定俗成的规则，比如某个模块的日志格式、某个接口的错误码规范，每次新开会话都要重新交代。后来我干脆把这些规则整理成一个结构化的记忆文件，每次对话前注入。claude-mem做的事情，就是把这种“手动注入”变成自动化、结构化的流程。

1.2 它到底解决什么问题

核心痛点有三个。第一是上下文窗口的物理限制，再大的窗口也有上限，长项目的历史信息不可能全部塞进去。第二是会话隔离，每次新对话都是白纸，缺乏连续性。第三是知识沉淀，项目过程中积累的经验、决策、踩坑记录，如果没有一个地方存下来，下次还会重复犯错。

claude-mem的思路是：把记忆分成不同层级，短期记忆放当前会话的临时上下文，长期记忆放项目级的稳定知识，还有一层是跨项目的个人偏好。每层用不同的存储策略和检索方式，需要的时候按相关性调取，而不是一股脑全塞进去。

这个方案适合谁？如果你只是偶尔问AI几个零散问题，那确实用不上。但如果你在做长期项目、维护多个代码库、或者需要AI持续扮演某个角色（比如固定的代码审查员、固定的写作助手），那这套东西的价值就体现出来了。

1.3 为什么选择本地化存储

市面上有一些云端记忆方案，把对话历史存在第三方服务器上。claude-mem走的是本地路线，记忆文件存在你自己的机器上，格式是纯文本或结构化标记。这么做有几个考虑。

首先是隐私。项目里的代码片段、业务逻辑、甚至一些敏感配置，不应该随便上传到外部。本地存储意味着数据不出机器，心里踏实。其次是可控性，你可以直接打开记忆文件看里面存了什么，想改就改，想删就删，不用依赖某个平台的黑盒接口。最后是可移植性，纯文本格式意味着你可以用Git管理它，可以同步到不同机器，可以随时迁移，不会被某个工具锁死。

我自己的做法是在项目根目录建一个.claude-mem/文件夹，里面按主题分文件，比如project-context.md、coding-standards.md、decisions-log.md。每次开始新会话，先让AI读这几个文件，它就能快速进入状态。这个习惯坚持了半年多，明显感觉重复解释的次数少了。

2. 记忆架构的分层设计

2.1 三层记忆模型的实际落地

claude-mem的记忆不是一坨，而是分层的。我把它分成三层：会话层、项目层、全局层。每层的生命周期、存储位置、检索优先级都不一样。

会话层是临时的，只在当前对话有效。比如你刚说“这次我们用Python 3.11”，这个信息就放在会话层，对话结束就丢弃。项目层是持久的，跟具体项目绑定，比如“这个项目的API前缀是/api/v2”，只要项目还在，这条记忆就一直在。全局层是跨项目的，比如“我习惯用4空格缩进”“我偏好简洁的注释风格”，这些不管做哪个项目都适用。

为什么要分层？因为检索的时候要有优先级。会话层的记忆最相关，优先用；项目层次之；全局层作为兜底。如果全混在一起，检索效率会很低，而且容易把不相关的信息带进来干扰判断。

实际落地时，我会在项目根目录放一个memory/文件夹，里面三个子目录：session/、project/、global/。会话层的文件在对话结束后可以归档或删除，项目层和全局层长期保留。每次启动时，按session → project → global的顺序加载，后面的层作为补充。

2.2 记忆条目的结构化格式

光有分层还不够，每条记忆本身也得有结构，不然检索的时候没法判断相关性。我用的格式是带元数据的Markdown，每条记忆包含几个字段：类型、内容、标签、时间戳、来源。

类型用来区分这是事实、偏好、决策还是待办。内容就是具体的描述。标签用于快速过滤，比如#api、#logging、#naming。时间戳记录什么时候写的，方便判断时效性。来源标记这条记忆是从哪次对话或哪个文件来的，便于追溯。

举个例子，一条项目层的记忆长这样：

--- type: decision tags: [api, versioning] timestamp: 2024-11-15 source: session-20241115-01 --- API版本号放在URL路径里，格式为 `/api/v{n}/`，不用header传递。 原因：团队里前端同学更习惯路径版本，调试时直观。

这种结构的好处是，检索的时候可以按标签过滤，按时间排序，按类型筛选。比如我要找所有跟API相关的决策，直接搜tags: [api]加type: decision就行，不用翻整个文件。

注意：元数据字段不要太多，超过六个就变成负担了。我试过加“优先级”“置信度”这些字段，后来发现根本用不上，反而每次写记忆都要纠结填什么。保持精简，够用就行。

2.3 检索策略：相关性优先于完整性

记忆多了之后，最大的问题不是存，而是取。你不可能每次把几百条记忆全塞给AI，那样既浪费窗口又引入噪音。所以检索策略很关键。

我的做法是两阶段检索。第一阶段用标签和类型做粗筛，把候选集缩小到十几条。第二阶段用关键词匹配做精排，挑出最相关的三到五条注入上下文。粗筛靠元数据，精排靠内容里的关键词重叠度。

具体实现上，我写了一个简单的脚本，输入是当前对话的摘要或关键词，输出是排序后的记忆列表。脚本逻辑不复杂：先按标签匹配度打分，再按内容关键词重叠度打分，最后按时间衰减加权。时间衰减的意思是，越新的记忆权重越高，但老记忆也不会完全忽略，只是优先级降低。

这个策略实测下来，注入的记忆条数控制在五条以内，基本能覆盖当前对话需要的大部分背景，同时不会让上下文变得臃肿。如果发现某次注入的记忆不相关，可以手动调整标签或关键词，下次就准了。

2.4 记忆的更新与淘汰机制

记忆不是只增不减的。项目在推进，有些决策会变，有些偏好会调整，老记忆如果不更新，反而会误导AI。所以需要一套更新和淘汰机制。

我的做法是版本化更新。每条记忆有唯一的ID，更新时不覆盖原记录，而是新增一条，并在新记录里标注supersedes: {旧ID}。这样历史决策还能追溯，但检索时默认只返回最新版本。淘汰则是定期归档，比如每季度把超过半年没被检索到的记忆移到archive/目录，不删除但不再默认加载。

触发更新的时机有两个：一是发现AI按老记忆行事导致错误，二是主动意识到某个约定变了。前者是被动修复，后者是主动维护。我一般每周花十分钟过一遍最近的记忆，看看有没有过时的，顺手更新掉。这个习惯成本很低，但能避免很多“AI怎么又按老规矩来了”的困惑。

3. 实操落地：从零搭建记忆系统

3.1 目录结构与初始化

搭建这套系统不需要什么复杂工具，一个文本编辑器加一个终端就够了。先在项目根目录创建记忆文件夹：

mkdir -p .claude-mem/{session,project,global,archive} touch .claude-mem/project/context.md touch .claude-mem/project/decisions.md touch .claude-mem/global/preferences.md

session/放临时记忆，project/放项目级记忆，global/放跨项目偏好，archive/放归档。初始的三个文件分别对应项目背景、决策记录、个人偏好，这是最常用的三类。

然后写一个简单的加载脚本，每次开始对话前运行，把相关记忆拼成一个文本块。脚本可以用Python写，逻辑就是读文件、按标签过滤、按时间排序、输出前N条。我用的版本大概五十行，核心就是文件读取和字符串处理，没有依赖任何外部库。

import os import re from datetime import datetime def load_memories(keywords, max_items=5): base = ".claude-mem" candidates = [] for layer in ["session", "project", "global"]: layer_path = os.path.join(base, layer) if not os.path.exists(layer_path): continue for fname in os.listdir(layer_path): if not fname.endswith(".md"): continue with open(os.path.join(layer_path, fname), encoding="utf-8") as f: content = f.read() score = sum(1 for kw in keywords if kw in content) if score > 0: candidates.append((score, content)) candidates.sort(key=lambda x: -x[0]) return "\n\n".join(c[1] for c in candidates[:max_items])

这个脚本很粗糙，但够用。关键词匹配虽然简单，但在记忆条数不多的时候效果不差。等记忆超过一百条，再考虑上向量检索也不迟。

3.2 记忆写入的时机与规范

什么时候该写记忆？我的经验是三个时机：决策发生时、偏好确认时、踩坑之后。决策发生时，比如选定了某个技术方案，立刻记下来，包括选它的理由和被放弃的备选。偏好确认时，比如你发现AI某种输出风格你更喜欢，记下来，下次让它保持。踩坑之后，比如某个配置项写错了导致报错，把正确写法和错误原因都记下来。

写入的规范有几点。第一，一条记忆只讲一件事，不要把多个决策混在一条里，不然检索时不好匹配。第二，写清楚“为什么”，光记“用A方案”没用，得记“用A方案因为B原因”，这样AI在遇到类似场景时能举一反三。第三，用陈述句，不用疑问句，记忆是事实，不是问题。第四，控制长度，一条记忆控制在三到五行，太长了检索时噪音大。

我见过有人把整段对话复制粘贴当记忆，这是大忌。记忆是提炼后的结论，不是原始素材。原始对话该归档归档，记忆只留精华。

3.3 与Claude工具的集成方式

claude-mem本身不是一个独立软件，它是一套约定和脚本，需要跟你的Claude使用方式结合。集成方式取决于你怎么用Claude。

如果你用的是网页版，那就在每次对话开始时，手动把加载脚本的输出粘贴进去，作为第一条消息。虽然手动，但也就多一步复制粘贴，习惯了不觉得麻烦。如果你用的是命令行工具或API，那可以在请求前自动调用加载脚本，把记忆拼进system prompt里，完全无感。

我自己的做法是在命令行工具里包一层shell函数，每次启动时自动读记忆、拼上下文、传给Claude。这样我打开终端就能直接聊，不用管记忆的事。函数大概长这样：

claude_with_memory() { local context=$(python3 ~/scripts/load_memories.py "$@") claude --system "$context" "$@" }

这个函数接受关键词参数，加载相关记忆，然后带着记忆启动Claude。用起来跟普通命令没区别，但AI已经知道项目背景了。

3.4 一个完整的记忆注入示例

光说理论太干，看一个实际例子。假设我在做一个电商后台项目，当前要讨论订单模块的日志规范。我的记忆库里可能有这么几条：

--- type: preference tags: [logging, style] --- 日志用结构化JSON格式，字段包括 level、timestamp、module、message、context。 不用纯文本拼接，方便后续用工具解析。

--- type: decision tags: [logging, order] --- 订单模块的日志必须包含 order_id 和 user_id，方便按订单或用户追踪。 原因：之前排查问题时发现缺这两个字段，定位困难。

--- type: fact tags: [order, api] --- 订单状态枚举：pending、paid、shipped、completed、cancelled。 状态流转只能单向，不允许回退。

这三条记忆注入后，AI在讨论日志规范时就会自动带上 order_id 和 user_id，用JSON格式，并且知道订单状态有哪些。我不需要再解释一遍，直接进入具体问题。这就是记忆系统的价值——把重复的背景交代变成一次性的沉淀。

4. 常见问题与排查实录

4.1 记忆不生效的几种原因

用了一段时间后，最常见的问题就是“我明明记了，AI怎么还是不知道”。排查下来，原因通常有这么几类。

第一类是检索没匹配上。你记的时候用的标签是#api，但检索时传的关键词是“接口”，标签对不上，自然搜不到。解决办法是标签要覆盖同义词，或者检索时做同义词扩展。我现在的做法是标签尽量用英文，因为英文词形变化少，匹配更稳定。

第二类是记忆被覆盖或归档了。检查一下archive/目录，看是不是被误归档了。或者检查有没有supersedes标记，新记忆把老记忆顶掉了。这种情况一般是有意为之，但如果新记忆写错了，就会导致老记忆失效而新记忆又不对。

第三类是注入顺序问题。如果记忆拼在system prompt里，但用户消息里又重复交代了相反的信息，AI可能会以用户消息为准。这时候要检查是不是记忆和当前指令冲突了，冲突时以哪个为准需要明确。

第四类是格式解析失败。元数据里的YAML格式如果写错了，比如冒号后面没空格，解析脚本可能读不出来。这种问题隐蔽性强，建议写完记忆后跑一遍校验脚本，确保格式正确。

4.2 记忆冲突的处理策略

项目做久了，记忆之间难免冲突。比如三个月前记了“用RESTful风格”，现在想改成GraphQL，老记忆还在，新记忆也写了，检索时两条都出来，AI就懵了。

处理冲突的原则是新覆盖旧，但保留追溯。具体做法是给每条记忆加status字段，取值active或superseded。新记忆写入时，把老记忆的status改成superseded，并加上superseded_by指向新记忆。检索时默认只返回active的，需要追溯历史时再手动查。

这个机制的关键是更新要及时。如果改了方案但忘了更新记忆，冲突就会一直存在。我的习惯是在每次做出重大决策后，立刻花一分钟更新记忆，把老记忆标记掉。这一分钟能省掉后面无数次的困惑。

还有一种冲突是层级冲突，比如全局层说“用4空格缩进”，项目层说“这个项目用2空格”。这种按优先级处理，项目层覆盖全局层。检索时如果发现同主题的记忆在不同层级都有，以更具体的层级为准。

4.3 性能与体积的平衡

记忆条数多了之后，加载和检索会变慢。我实测过，纯文本匹配的话，五百条记忆检索一次大概两百毫秒，还能接受。但超过一千条，就明显感觉到延迟了。

优化的方向有几个。一是分片加载，不要每次全量扫描，而是按标签建索引，先查索引再读文件。二是缓存，把最近用过的记忆缓存在内存里，避免重复读磁盘。三是定期归档，把半年没用的记忆移到archive/，不参与默认检索。

体积方面，单条记忆控制在1KB以内，整个记忆库控制在5MB以内，基本不会有什么性能问题。超过这个量级，就该考虑上向量数据库了。但说实话，大部分个人项目根本到不了这个量级，几百条记忆已经能覆盖绝大多数场景。

4.4 常见问题速查表

提示：这张表建议打印出来贴在显示器边上，遇到问题先对照排查，能省不少时间。我自己的经验是，八成问题都是检索匹配和更新不及时导致的，真正复杂的故障很少。

4.5 几个容易踩的坑

第一个坑是记忆写得太细。有人把每一行代码的改动都记下来，结果记忆库变成流水账，检索时全是噪音。记忆应该记结论和原则，不是过程。过程放Git日志里，记忆只留“为什么这么做”。

第二个坑是标签体系太复杂。一开始就设计几十个标签，结果记的时候不知道该用哪个，检索的时候也记不全。我的建议是标签从少到多，先只用五六个核心标签，用着用着发现不够再增加。标签是长出来的，不是设计出来的。

第三个坑是忘记备份。记忆文件虽然小，但丢了很麻烦。我现在把.claude-mem/纳入Git管理，每次更新记忆就提交一次。这样既有历史记录，又能多机同步，一举两得。

第四个坑是过度依赖记忆。记忆是辅助，不是万能。有些信息还是得在对话里明确说，特别是当前任务的即时约束。记忆解决的是“长期背景”，不是“当前指令”。分清楚这两者，用起来才顺手。

5. 进阶玩法与扩展思路

5.1 记忆的自动提取

手动写记忆虽然可控，但费时间。有没有办法让AI自己从对话里提取记忆？可以，但需要一些技巧。我的做法是在对话结束时，让AI总结这次对话产生的“可复用结论”，然后我审核一遍，确认后写入记忆库。

提示词大概是这样：“请从本次对话中提取三条最值得长期保留的结论，每条包含类型、标签、内容和理由，用Markdown格式输出。”AI输出的结果我快速过一遍，改掉不准确的，然后追加到记忆文件里。这样半自动的流程，比纯手动快很多，又比全自动可靠。

全自动提取的风险是AI可能提取出错误或冗余的信息，污染记忆库。所以审核这一步不能省。等积累足够多的样本，可以训练一个简单的分类器来辅助筛选，但那是后话了。

5.2 跨项目记忆的共享与隔离

如果你同时做好几个项目，记忆的共享和隔离就是个问题。全局层的记忆所有项目共享，项目层的记忆各自独立。但有些记忆是“几个项目共享，但不是全部”，比如“所有前端项目都用这个组件库”。

我的处理方式是引入标签组的概念。给记忆打上项目标签，比如#proj-a、#proj-b，检索时按当前项目过滤。共享的记忆打多个项目标签，独立的只打一个。这样一套记忆库就能服务多个项目，不用每个项目单独维护。

隔离方面，敏感项目的记忆可以加密存储，或者放在单独的目录里，不纳入全局检索。这个看具体需求，大部分情况下不需要这么复杂。

5.3 记忆与版本控制的结合

把记忆纳入Git管理之后，可以玩出一些花样。比如用git log看记忆的演变历史，了解某个决策是什么时候改的、为什么改。比如用分支管理不同方案，main分支是当前生效的记忆，experiment分支是试验中的方案，切换分支就切换了AI的“记忆状态”。

我还试过用Git hook在提交代码时自动检查记忆是否需要更新。比如改了API路径，hook会提醒“检测到API变更，是否需要更新记忆？”这个提醒不一定每次都采纳，但能防止遗忘。

5.4 未来可以扩展的方向

这套系统目前还是偏手动，未来可以往几个方向扩展。一是语义检索，用嵌入向量替代关键词匹配，提高检索准确率。二是自动摘要，定期把零散记忆合并成更高层的总结。三是多模态记忆，除了文本，还能存图表、截图、架构图。四是协作记忆，团队成员共享一套记忆库，新人加入时直接继承团队知识。

不过这些都是锦上添花。核心的三层结构、结构化格式、两阶段检索，已经能解决大部分问题了。先把基础打牢，再考虑扩展，不然容易本末倒置。

我个人在实际操作中的体会是，记忆系统的价值不在于技术多复杂，而在于坚持写、及时更新、定期清理。工具再先进，不写记忆等于零。我见过太多人搭好了框架，用了两天就荒废了。真正有用的，是把它变成习惯，像写日记一样自然。最后再分享一个小技巧：每次开始新项目时，先花十分钟把已知的背景、偏好、约束写成初始记忆，后面会省下几十倍的重复解释时间。这个投入产出比，高得离谱。