claude-mem 实战：为 AI 助手构建分层长期记忆系统

1. 从零认识 claude-mem：它到底解决什么问题

第一次看到claude-mem这个名字，很多人会以为它又是一个“给对话套壳”的小工具。但真正用过一段时间之后你会发现，它想解决的是一个非常具体、也非常痛的场景：让 AI 助手在跨会话、跨项目、跨时间的情况下，依然记得你是谁、你在做什么、你之前做过哪些决定。

我们平时用 AI 助手，最大的割裂感就来自“失忆”。今天上午你花了半小时跟它解释你的项目结构、命名规范、技术栈偏好，下午开个新会话，它又变成一张白纸，你得从头再讲一遍。这种重复劳动在单次对话里不明显，但当你每天要开十几个会话、处理三四个不同项目时，累积起来的时间损耗非常可观。claude-mem的核心价值，就是给 AI 助手装上一套可检索、可维护、可分层的长期记忆系统。

它适合谁？我梳理了三类人。第一类是重度 AI 编码用户，每天用 AI 写代码、改 bug、做重构，项目上下文复杂，需要 AI 记住架构决策和历史踩坑记录。第二类是多项目并行的人，手上同时跑着好几个方向，每个项目的技术选型、业务规则都不一样，靠脑子记容易串味。第三类是把 AI 当长期协作者的人，希望 AI 不只是“临时工”，而是能积累经验、越用越顺手的搭档。

claude-mem本质上是一套围绕“记忆”构建的工作流和数据结构。它把记忆分成不同层级：有短期的会话上下文，有中期的项目笔记，也有长期的个人偏好和通用经验。不同层级的记忆有不同的写入时机、检索方式和过期策略。这个分层设计是整个项目最值得琢磨的地方，也是它区别于“把聊天记录存成 txt”这种粗暴方案的关键。

我最初接触它的时候，心里是有疑虑的：记忆系统听起来很美，但实际用起来会不会变成“垃圾进垃圾出”？存了一堆没用的信息，检索时反而干扰判断。用下来发现，它的分层和检索机制确实做了不少取舍，后面我会详细拆解。先给结论：如果你每天和 AI 的交互超过 5 次，且涉及 2 个以上项目，这套东西值得花一个下午搭起来。

2. 核心设计思路拆解：为什么是分层记忆而不是一个大仓库

2.1 记忆分层的底层逻辑

很多人第一反应是：记忆嘛，不就是把重要信息都存起来，用的时候搜一下？这个思路在信息量小的时候没问题，但一旦记忆条目超过几百条，检索质量会断崖式下跌。原因很简单：不同性质的信息，检索方式根本不一样。

你的个人偏好（比如“我喜欢用 tab 而不是空格”“回复尽量简洁”）是高频、稳定、全局的，它应该每次都加载，不需要检索。你某个项目的架构决策（比如“这个服务用事件驱动而不是轮询”）是中频、项目内稳定的，它应该在该项目相关会话里自动带出。而你三天前调试某个 bug 时记下的临时结论，是低频、易过期的，它应该按需检索，甚至定期清理。

claude-mem的分层正是对应这三种性质。我把它归纳成一张表，方便你对照理解：

这个设计的精妙之处在于加载成本的控制。全局层内容少而精，每次加载不心疼；项目层按需加载，避免无关项目的信息污染当前上下文；会话层走检索，只有真正相关时才被拉出来。如果全部塞进一个大仓库，每次都要全量加载或全量检索，要么慢，要么乱。

2.2 为什么不做成“自动全量记忆”

有人会问：现在向量检索这么成熟，为什么不把所有对话都存进去，用的时候语义搜索？我实测过这种方案，问题有三个。第一，噪音太大。你随口说的一句“这个变量名先这样吧”也会被存进去，检索时经常冒出来干扰判断。第二，时效性混乱。三个月前的一个临时决定，和昨天的正式决策，在向量空间里可能距离很近，但重要性天差地别。第三，维护成本高。全量存储意味着全量维护，你得定期清理、去重、更新，否则记忆库会越来越臃肿。

claude-mem选择的是主动写入 + 分层管理。也就是说，不是所有对话都自动变成记忆，而是由你（或 AI 根据规则）判断哪些值得记。这个“主动”二字很关键，它把记忆质量的控制权交回给人。我一开始觉得这样麻烦，后来发现恰恰是这种“麻烦”保证了记忆库的干净。就像笔记软件，自动全量记录的工具往往最后没人看，而手动整理过的笔记才会反复翻阅。

2.3 检索策略的取舍

在检索层面，claude-mem没有一味追求“最先进”的向量方案，而是用了关键词 + 标签 + 时间衰减的混合策略。这个选择很务实。向量检索擅长语义相似，但对精确匹配（比如某个函数名、某个配置项）反而不如关键词。而实际工作中，我们检索记忆时经常是“我记得之前定过一个关于 X 的规则”，这个 X 往往是具体名词。

时间衰减的意思是，越新的记忆权重越高。这符合直觉：上周的决定比去年的决定更可能仍然有效。但衰减不是一刀切，项目层的核心决策可以标记为“长期有效”，不参与衰减。这种灵活性是纯向量方案很难做到的。

提示：分层和检索策略是claude-mem的两条腿，缺一不可。只分层不检索，记忆调用效率低；只检索不分层，记忆质量差。理解这一点，后面的实操才不会走偏。

3. 核心细节解析与实操要点

3.1 记忆条目的结构设计

要让记忆可维护，条目的结构必须统一。我参考常见实践，把每条记忆设计成包含以下字段的结构：

• id：唯一标识，建议用“层级-项目-序号”的格式，比如proj-webapp-007，方便人工识别。
• 层级：global / project / session 三选一。
• 标签：3 到 5 个关键词，用于快速过滤。
• 内容：记忆主体，要求一句话说清结论，必要时附上下文。
• 来源：记录这条记忆来自哪次对话或哪个文件，方便追溯。
• 创建时间 / 更新时间：用于时间衰减计算。
• 有效期：长期 / 中期 / 短期，决定清理策略。

这个结构看起来简单，但每一条都有讲究。比如“内容”要求一句话说清结论，是为了强制你提炼。我见过太多人把整段对话复制进去，结果检索出来一大坨，还得重新读一遍。记忆的价值在于提炼，不在于完整。再比如“来源”，很多人觉得多余，但当你发现某条记忆和当前情况矛盾时，能快速找到原始上下文核对，这个字段就救命了。

3.2 写入时机的判断标准

什么时候该写一条记忆？这是实操中最容易纠结的地方。我总结了一个简单的判断流程，你可以直接套用：

1. 这个信息未来还会用到吗？如果只是一次性操作，不写。
2. 如果不写，下次我会重新解释一遍吗？如果会，写。
3. 它属于哪个层级？全局偏好写全局，项目相关写项目，临时结论写会话。
4. 能用一句话说清吗？如果不能，说明还没想清楚，先别写。

这个流程帮我过滤掉了大量“伪记忆”。比如“今天下午三点要开会”这种，属于日程管理，不该进记忆库。“这个项目用 PostgreSQL 而不是 MySQL，因为需要 JSONB 字段”这种，属于项目层决策，必须写。“刚才那个报错是因为缓存没清”这种，属于会话层临时结论，可以写但设短有效期。

注意：不要为了“完整”而记录。记忆库不是日志，日志求全，记忆求准。一条精准的记忆胜过十条模糊的记录。

3.3 检索时的优先级规则

检索记忆时，优先级顺序直接影响 AI 的回答质量。我的实践顺序是：

1. 全局层全量加载：内容少，直接全带，保证基本偏好不丢。
2. 项目层按当前项目过滤：只加载当前项目相关的记忆，避免串项目。
3. 会话层按关键词 + 标签检索：取相关性最高的前 N 条，N 建议控制在 5 到 8 条。
4. 时间衰减加权：对会话层结果按时间排序，新的优先。

这个顺序的关键在于先保证稳定信息，再补充动态信息。全局层和项目层是“底座”，会话层是“增量”。如果反过来，先检索一堆临时结论，再加载偏好，AI 容易被临时信息带偏。我踩过这个坑：有一次会话层里存了一条“暂时用轮询方案”的临时决定，检索时被优先带出，结果 AI 在后续讨论里一直坚持轮询，直到我手动纠正。后来调整了优先级，问题就没了。

3.4 存储介质的选择

存储介质看似小事，但影响长期维护成本。常见选择有三种：纯文本文件、轻量数据库、向量数据库。我的建议是从纯文本开始。原因很简单：可读、可编辑、可版本控制。你随时能用编辑器打开看，出问题了直接改，还能用 Git 管理变更历史。

当记忆条目超过 500 条，或者检索变慢时，再考虑迁移到轻量数据库（比如 SQLite）。向量数据库我建议放到最后，除非你确实需要大规模语义检索，否则它的运维复杂度会抵消收益。claude-mem的很多实践者最后都停留在“文本 + 简单索引”的方案上，因为够用。

4. 实操过程与核心环节实现

4.1 目录结构搭建

先搭目录。我用的结构是这样的，你可以直接抄：

claude-mem/ ├── global/ │ ├── preferences.md │ └── conventions.md ├── projects/ │ ├── webapp/ │ │ ├── decisions.md │ │ ├── rules.md │ │ └── glossary.md │ └── datapipeline/ │ ├── decisions.md │ └── rules.md ├── sessions/ │ ├── 2024-06-01.md │ └── 2024-06-02.md └── index/ └── tags.json

global放全局偏好和通用规范，projects按项目分目录，sessions按日期存临时记录，index放标签索引。这个结构的好处是层级清晰，人工可导航。你打开文件夹就知道有什么，不需要查文档。

preferences.md里放什么？我放的是“回复语言用中文”“代码示例尽量给完整可运行版本”“解释概念时先给类比再给定义”这类。conventions.md放通用规范，比如“变量命名用驼峰”“提交信息用祈使句”。这些内容不多，但每次会话都加载，收益很高。

4.2 记忆写入的具体操作

写入一条记忆，我建议走一个固定流程，避免随手乱写。以项目层为例：

1. 打开对应项目的decisions.md。
2. 在文件末尾追加一条，格式如下：

## [proj-webapp-012] 使用事件驱动替代轮询 - 标签: 架构, 消息队列, 性能 - 时间: 2024-06-01 - 有效期: 长期 - 来源: 2024-06-01 架构讨论会话 - 内容: 订单状态同步改用事件驱动，因为轮询在高峰期延迟超过 30 秒，事件驱动可降到秒级。

3. 更新index/tags.json，把新标签加进去。

这个流程看起来繁琐，但熟练后一条记忆 30 秒就能写完。关键是格式统一，这样后续检索脚本才能正确解析。我一开始图快，格式写得随意，结果检索时经常漏掉条目，后来统一格式才解决。

提示：写入时“内容”字段一定要写“结论 + 原因”。只写结论（“改用事件驱动”）不够，下次看到会忘了为什么；只写原因（“轮询太慢”）也不够，不知道最终决定了什么。两者都写，记忆才完整。

4.3 检索脚本的实现

检索是记忆系统真正发挥价值的地方。我写了一个简单的 Python 脚本，逻辑分三步：加载全局层、过滤项目层、检索会话层。核心代码如下：

import json import os from datetime import datetime def load_global(base): prefs = open(os.path.join(base, 'global/preferences.md')).read() convs = open(os.path.join(base, 'global/conventions.md')).read() return prefs + "\n" + convs def load_project(base, project): proj_dir = os.path.join(base, 'projects', project) content = "" for fname in ['decisions.md', 'rules.md', 'glossary.md']: path = os.path.join(proj_dir, fname) if os.path.exists(path): content += open(path).read() + "\n" return content def search_sessions(base, keywords, top_n=5): results = [] sess_dir = os.path.join(base, 'sessions') for fname in os.listdir(sess_dir): path = os.path.join(sess_dir, fname) text = open(path).read() score = sum(1 for kw in keywords if kw in text) if score > 0: mtime = os.path.getmtime(path) results.append((score, mtime, text)) results.sort(key=lambda x: (x[0], x[1]), reverse=True) return [r[2] for r in results[:top_n]] def build_context(base, project, keywords): ctx = load_global(base) ctx += "\n" + load_project(base, project) ctx += "\n" + "\n".join(search_sessions(base, keywords)) return ctx

这个脚本不复杂，但覆盖了核心逻辑。load_global全量加载，load_project按项目加载，search_sessions按关键词打分并取前 N 条。打分逻辑我用了最简单的“关键词命中数”，实测够用。如果你想要更精细，可以加时间衰减权重，把mtime纳入打分。

4.4 与 AI 会话的集成方式

脚本有了，怎么让它和 AI 会话结合？我的做法是在会话开始时手动或半自动调用脚本，把生成的上下文粘贴到会话开头。具体流程：

1. 确定当前项目名和本次会话的关键词。
2. 运行python build_context.py webapp "订单 事件驱动"。
3. 把输出粘贴到 AI 会话的第一条消息里，前面加一句“以下是我的项目记忆，请参考”。

这个方式看起来“土”，但非常可靠。它不依赖任何特定平台的接口，你在任何 AI 工具里都能用。我试过做全自动集成，但发现每次会话的关键词判断还是人工更准，自动提取的关键词经常偏。所以最后保留了“人工定关键词 + 脚本生成上下文”的半自动方案。

注意：粘贴上下文时，建议在末尾加一句“以上记忆仅供参考，如与当前情况冲突请指出”。这样 AI 不会盲目遵循旧记忆，遇到矛盾会提醒你，避免用过时信息做决策。

5. 常见问题与排查技巧实录

5.1 记忆检索不准怎么办

这是最常见的问题。表现是：明明存过某条记忆，检索时却没带出来。排查顺序如下：

我遇到最多的是“关键词不匹配”。比如我存记忆时写的是“事件驱动”，检索时搜的是“消息队列”，虽然语义相关，但关键词没命中。解决办法是在写入时多打几个同义标签。这个习惯养成后，检索命中率明显提升。

5.2 记忆库越来越臃肿

用了一段时间后，会话层会积累大量临时记录。如果不清理，检索时噪音越来越多。我的清理策略是：

• 每周清理一次会话层：把超过 7 天且未被检索命中的条目归档或删除。
• 每月审视项目层：把已经失效的决策标记为“已废弃”，而不是直接删，保留历史。
• 全局层季度回顾：偏好和规范变化慢，但也要定期确认是否还适用。

清理时有个原则：宁可归档，不要硬删。归档的条目移到archive/目录，不参与检索，但需要时还能查。硬删的风险是，某条你以为没用的记忆，其实后面还会用到。

5.3 AI 不遵循记忆内容

有时候记忆带出来了，但 AI 还是按自己的来。原因通常有两个。第一，记忆内容太模糊，AI 无法判断如何应用。比如“代码要写得好”这种，等于没说。第二，记忆与当前指令冲突，AI 优先遵循了当前指令。这种情况其实是对的，当前指令应该优先。

解决第一个问题的办法是让记忆具体可执行。“代码要写得好”改成“函数不超过 50 行，参数不超过 4 个”。解决第二个问题的办法是，如果确实希望记忆优先，在会话里明确说“请严格遵循我提供的记忆，即使与当前描述有出入”。

5.4 多设备同步的坑

如果你在多台设备上用，记忆库同步是个问题。我试过几种方案，最后用的是 Git 仓库。好处是版本清晰，冲突可解。坏处是每次切换设备要 pull，写完要 commit。如果你嫌麻烦，用云盘同步也行，但要注意冲突文件。我的经验是：记忆库用 Git，会话层可以不同步。因为会话层是临时的，不同设备各自维护反而更干净。

提示：Git 同步时，建议把sessions/加入.gitignore，只同步global/和projects/。这样既保证了核心记忆的一致性，又避免了临时记录的同步冲突。

5.5 记忆写入的“过度”与“不足”

最后说一个心态问题。刚开始用的时候，容易走两个极端。一个是过度写入，什么鸡毛蒜皮都记，结果记忆库迅速膨胀，检索质量下降。另一个是写入不足，觉得“这个我肯定记得”，结果下次真的忘了，又得重新解释。

我的平衡点是：凡是需要向 AI 解释超过两句话的信息，就值得记。一句话能说清的，靠脑子记；超过两句的，写进记忆库。这个标准帮我过滤掉了大部分噪音，同时保住了真正有价值的信息。用了一个月后，我的记忆库稳定在 200 条左右，检索命中率很高，维护成本也可控。

6. 我个人的使用体会与扩展思路

用claude-mem这套东西大半年，最大的感受是：它改变的不是 AI 的能力，而是我和 AI 协作的方式。以前我把 AI 当“临时工”，每次都要重新交代背景；现在更像“长期同事”，它记得项目的来龙去脉，我也更愿意把决策过程讲清楚，因为知道这些会被记住。这种双向的“认真”，反而提升了协作质量。

扩展方向上，我最近在尝试两件事。一是给记忆加“置信度”字段，区分“确定”“待验证”“已废弃”，检索时优先带出高置信度的。二是做记忆的自动摘要，当某个项目的记忆超过 50 条时，自动生成一份“项目记忆概览”，会话开始时先加载概览，再按需加载细节。这两个方向都还在摸索，有进展再分享。

如果你刚开始搭，我的建议是别追求一步到位。先把全局层和项目层建起来，用起来，感受到“AI 记得我”的好处后，再逐步完善会话层和检索逻辑。记忆系统的价值在于长期积累，不在于初始设计的完美。先跑起来，再优化，这是我踩过坑之后最想分享的一点。