claude-mem 实战：为对话式 AI 构建持久记忆系统

1. 从“聊完就忘”说起：claude-mem 到底想解决什么

如果你用 Claude 这类对话式 AI 做过稍微长一点的项目，大概率遇到过这种尴尬：昨天聊了半小时把架构敲定了，今天开个新会话，它一脸无辜地问你“请问你想做什么项目”。你不得不把昨天的结论、约束、命名规范重新贴一遍，贴到第三遍的时候，人已经麻了。

claude-mem这个名字，直译过来就是“Claude 的记忆”。它不是一个官方产品，而是社区里围绕“给对话式 AI 加一层持久记忆”这个需求衍生出来的一类工具/方案的统称。核心诉求非常朴素：让 AI 在跨会话、跨项目的时候，记得住之前发生过什么，而不是每次都从零开始。

它解决的问题可以拆成三层。第一层是会话内的上下文管理，一次对话太长会超出上下文窗口，需要压缩、摘要、检索。第二层是跨会话的记忆持久化，把关键信息落到本地文件或数据库，下次开新会话时按需注入。第三层是项目级的知识沉淀，把某个代码库、某个写作项目的约定、决策、踩坑记录结构化保存，形成可复用的“项目记忆”。

适合谁来参考这篇内容？三类人最有用。一是重度使用 Claude 做开发或写作的从业者，每天要开很多会话，重复交代背景非常浪费时间。二是想自己动手搭一套记忆系统的人，市面上的方案要么太重、要么不透明，自己搭反而更可控。三是对 AI 工作流感兴趣的产品或技术同学，想理解“记忆”这件事在工程上到底怎么落地。

我自己的使用场景很典型：同时维护三四个项目，每个项目有自己的技术栈、命名习惯、历史决策。没有记忆层之前，我每天要花十几分钟做“上下文复述”，有了claude-mem这类方案之后，这部分时间基本省掉了。下面我把这套东西的来龙去脉、设计取舍、实操细节和踩过的坑，完整讲一遍。

2. 记忆系统的四种实现路线，以及为什么我最终选了文件加检索

在动手之前，先要搞清楚“给 AI 加记忆”这件事有哪几种做法。我调研和实践下来，大致分成四条路线，每条都有自己的适用边界。

2.1 路线一：纯上下文窗口硬塞

最原始的做法，就是把所有历史对话原封不动塞进新的上下文。优点是零实现成本，缺点是上下文窗口是有限且昂贵的资源。一次塞几万字，不仅费用上去了，模型对中间部分的注意力还会衰减，也就是常说的“lost in the middle”。这条路只适合极短期的记忆，比如同一个任务连续几轮对话。

2.2 路线二：摘要压缩后注入

把历史对话用模型自己总结成一段摘要，下次把摘要注入。这比硬塞聪明，但有个隐患：摘要是有损压缩，且压缩过程本身可能丢关键细节。比如你昨天说“这个字段不要用下划线，用驼峰”，摘要很可能把它概括成“统一了命名规范”，具体规则就丢了。所以摘要适合做“背景铺垫”，不适合做“精确约束”。

2.3 路线三：向量数据库做语义检索

把历史片段切块、向量化，存进向量库，新会话时用当前问题去检索最相关的片段。这是目前最主流的做法，优点是按需召回、容量几乎无限。缺点是引入了一个外部依赖，而且检索质量高度依赖切块策略和嵌入模型。切得太碎会丢上下文，切得太大会召回一堆无关内容。

2.4 路线四：结构化文件加关键词检索

这是我最终采用的路线，也是claude-mem这类轻量方案最常见的形态。核心思路是：把记忆写成人类可读的 Markdown 或 JSON 文件，按项目、按主题分目录存放，检索时先用关键词和元数据过滤，再决定是否注入。它没有向量库那么“智能”，但胜在透明、可编辑、可版本控制，出问题的时候你能直接打开文件看看到底记了什么。

四条路线的对比如下：

我选路线四的核心理由是可控性。向量检索召回错了，你很难调试；文件检索召回错了，你打开文件改一行就行。对于个人和小团队来说，透明比智能更重要。

3. 记忆文件该长什么样：目录结构与字段设计

确定了路线，接下来是设计记忆的“数据模型”。这一步决定了后面检索和注入好不好用，值得多花点时间。

3.1 目录按项目隔离，而不是按时间

很多人第一反应是按日期存，比如2024-06-01.md。我试过，很快就乱了，因为你回忆的时候是按项目回忆的，不是按日期回忆的。正确的做法是按项目建目录：

~/.claude-mem/ ├── projects/ │ ├── blog-system/ │ │ ├── context.md │ │ ├── decisions.md │ │ └── pitfalls.md │ └──>## [2024-06-01] 数据库选型 - tags: database, sqlite, decision - status: final - content: 选用 SQLite，理由是单机部署零依赖，数据量在 10 万行以内性能足够。 - related: pitfalls.md#sqlite-concurrency

tags用于关键词检索，status区分“已定稿”和“讨论中”，related做文件间跳转。这个格式看起来啰嗦，但当你三个月后回头看，会感谢当时写清楚的自己。

提示：不要追求一次设计完美。我第一版的字段只有 content，后来陆续加了 tags 和 status，都是被实际需求逼出来的。先跑起来，再迭代。

4. 检索与注入：怎么让 AI 在正确的时候想起正确的事

记忆存下来只是第一步，真正的难点是在开新会话时，怎么决定注入哪些记忆。注入太多，上下文被占满；注入太少，AI 又“失忆”。这里有几个我实测有效的策略。

4.1 分层注入：必选层加可选层

我把注入内容分成两层。必选层是当前项目的context.md，无论聊什么都要带上，因为它定义了“我们在哪个项目里”。可选层是根据当前问题关键词检索出来的decisions.md和pitfalls.md片段。

具体做法是：新会话开始时，先注入 context.md，然后对用户的第一句话做关键词提取，去 decisions 和 pitfalls 里匹配 tags，命中的片段追加注入。这样既保证了背景完整，又不会一次性塞爆。

4.2 关键词匹配的几个实用技巧

纯字符串匹配很容易漏，我加了几个小技巧：

• 同义词表：把“数据库/db/database”“接口/api/endpoint”这类映射维护成一张表，匹配时展开。
• 标签权重：status: final的决策权重高于status: draft，检索时优先注入。
• 时间衰减：越近的记忆权重略高，但不是线性衰减，而是给最近两周的内容一个加成。

这些逻辑用一个几十行的 Python 脚本就能实现，不需要任何外部服务。

4.3 注入格式要“像人话”，不要像数据库导出

一个容易忽略的细节：注入给模型的记忆，格式会显著影响它的使用效果。我试过直接注入 JSON，模型经常把它当数据而不是当指令。后来改成自然语言段落，效果好很多：

以下是本项目的历史记忆，供你参考： - 数据库选用 SQLite（2024-06-01 定稿），原因是单机部署零依赖。 - 注意：SQLite 在高并发写入下有锁竞争问题，见 pitfalls 记录。

用“以下是……供你参考”这种口吻，模型会更自然地把它当作背景知识，而不是待处理的数据。

5. 实操中真正会咬人的几个坑

前面讲的都是设计层面的东西，看起来挺顺。但实际跑起来，真正花时间的是下面这些坑。我把它们单独拎出来，因为每一个我都踩过，而且每一个都不在文档里。

5.1 记忆污染：错误信息被反复注入

最危险的情况是：某条记忆本身是错的，但因为被反复注入，模型越来越“确信”它是对的。我有一次把某个 API 的参数记错了，结果连续三天的新会话都在用错误参数，直到我手动发现。

解决办法是给记忆加过期机制。每条记忆带一个last_verified字段，超过 30 天没被验证的，注入时加一句“此信息较旧，请确认”。这不是万能的，但能提醒模型保持怀疑。

5.2 上下文膨胀：记忆越攒越多，注入越来越慢

项目跑了两个月，pitfalls.md 攒了上百条。如果全量注入，光记忆就占了几千 token。我的处理是分级归档：最近一个月的留在主文件，更早的移到archive/子目录，只在明确检索到相关关键词时才加载。

5.3 多项目串味：A 项目的记忆跑到 B 项目

这个坑很隐蔽。有一次我在写博客项目，模型突然建议我用某个数据管道的方案，我一查，是检索时没做项目隔离，把另一个项目的记忆召回了。项目隔离必须在检索层强制做，不能靠 tags 软过滤。我的做法是检索时先按项目目录限定范围，再做关键词匹配。

5.4 记忆和当前对话冲突时怎么办

有时候当前对话里用户明确说了新要求，但记忆里是旧要求。比如记忆里写“用 tabs 缩进”，用户现在说“改成 spaces”。这时候当前对话优先级必须高于记忆。我在注入记忆时会加一句“若与当前对话冲突，以当前对话为准”，避免模型死守旧记忆。

注意：记忆系统的价值在于“减少重复交代”，而不是“替代当前沟通”。任何时候，用户当下的明确指令都应该压过历史记忆。

6. 从零搭一套最小可用版本：我的实际步骤

讲了这么多原理和坑，最后给一套可以直接抄作业的最小实现。不需要向量库，不需要外部服务，一个 Python 脚本加几个 Markdown 文件就够。

6.1 第一步：建目录和初始化脚本

mkdir -p ~/.claude-mem/projects ~/.claude-mem/global touch ~/.claude-mem/global/preferences.md

然后写一个mem.py，提供三个命令：add（添加记忆）、search（检索）、inject（生成注入文本）。

6.2 第二步：实现添加和检索

import os, re, sys, datetime BASE = os.path.expanduser("~/.claude-mem") def add(project, category, content, tags): path = os.path.join(BASE, "projects", project, f"{category}.md") os.makedirs(os.path.dirname(path), exist_ok=True) date = datetime.date.today().isoformat() entry = f"\n## [{date}] {content[:20]}\n- tags: {tags}\n- status: draft\n- content: {content}\n" with open(path, "a", encoding="utf-8") as f: f.write(entry) def search(project, query): results = [] proj_dir = os.path.join(BASE, "projects", project) if not os.path.isdir(proj_dir): return results keywords = re.findall(r"\w+", query.lower()) for fname in os.listdir(proj_dir): with open(os.path.join(proj_dir, fname), encoding="utf-8") as f: text = f.read() for block in text.split("\n## "): if any(k in block.lower() for k in keywords): results.append(block) return results

这段代码很粗糙，但能跑起来比设计完美重要。先让它工作，再根据实际痛点优化。

6.3 第三步：生成注入文本

def inject(project, query): parts = [] ctx = os.path.join(BASE, "projects", project, "context.md") if os.path.exists(ctx): parts.append("【项目背景】\n" + open(ctx, encoding="utf-8").read()) for r in search(project, query)[:5]: parts.append("【相关记忆】\n" + r) parts.append("若以上记忆与当前对话冲突，以当前对话为准。") return "\n\n".join(parts)

把inject的输出贴到新会话开头，就完成了记忆注入。整个过程没有任何黑盒，出问题直接看文件。

6.4 第四步：养成“随手记”的习惯

工具搭好只是开始，真正决定效果的是使用习惯。我的经验是：每当一个决策定稿、一个坑被填平、一个约束被明确，立刻花十秒记一条。不要攒着，攒着就忘了。我甚至在编辑器里绑了个快捷键，选中文字一键存成记忆。

7. 关于记忆边界的一点个人体会

搭这套东西的过程中，我最大的体会是：记忆不是越多越好，而是越准越好。一开始我什么都记，结果检索噪音很大，模型经常被无关记忆带偏。后来我给自己定了个标准：只记“下次还会用到，且不看就会忘”的东西。决策、约束、坑，这三类必记；闲聊、临时讨论、已经被推翻的方案，一律不记。

另一个体会是，记忆系统本质上是在替你做“上下文管理”这件事，而上下文管理的能力，恰恰是区分 AI 重度用户和轻度用户的关键。轻度用户每次从零开始，重度用户有一套自己的记忆基础设施。claude-mem这类方案的价值，不在于它多智能，而在于它把这件事变得可见、可控、可迭代。

最后分享一个小技巧：定期花十分钟翻一遍自己的记忆文件，删掉过期的、合并重复的、修正错误的。这个“记忆维护”的习惯，比任何工具都重要。我一般每周五下午做一次，顺手把这一周的新决策归档，下周开工时上下文干净又完整。