claude-mem 记忆系统实战：让 AI 助手跨会话记住项目上下文

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

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

我们平时用 AI 助手写代码、写文档、做方案，最大的割裂感来自哪里？不是模型不够聪明，而是每次开新对话，它就像失忆一样。你昨天刚跟它讲清楚项目用的是 PostgreSQL 而不是 MySQL，今天它又默认给你生成 MySQL 的建表语句；你上周刚说过团队不用某个框架，这周它又热情地推荐那个框架。这种反复“重新自我介绍”的体验，是效率杀手。

claude-mem的核心定位，就是给 AI 助手装上一套可持久化的记忆层。它把对话中产生的关键信息——项目背景、技术选型、个人偏好、历史决策、常见错误——抽取出来，存到一个结构化的记忆库里，然后在后续对话中按需检索、注入上下文。你可以把它理解成给 AI 配了一个“随身笔记本”，而且这个笔记本会自己整理、自己归档、自己按相关性翻页。

它适合谁？我梳理了三类人：

• 长期维护同一批项目的开发者：项目周期长、上下文多，每次都要重新交代背景，成本极高。
• 把 AI 当主力生产力工具的内容创作者和产品经理：需要 AI 记住自己的写作风格、受众定位、历史选题。
• 多项目并行、频繁切换上下文的团队：不同项目有不同的技术栈和规范，记忆隔离和按项目检索是刚需。

这篇文章我会从设计思路、核心机制、实操落地、问题排查四个层面，把claude-mem这类记忆系统讲透。不管你是想直接用它，还是想自己搭一套类似的记忆层，都能拿到可复现的方案。

2. 记忆系统的整体设计与思路拆解

2.1 为什么“把历史对话全塞进上下文”是错的

很多人第一反应是：记忆嘛，简单，把之前的对话记录全部拼起来塞进 prompt 不就行了？我早期也这么干过，实测下来问题一大堆。

第一个问题是上下文窗口是有限且昂贵的。就算模型支持很长的上下文，把几十万字的聊天记录全塞进去，token 成本会飙升，而且响应速度明显变慢。第二个问题是信噪比极低。历史对话里 90% 是寒暄、试错、废弃方案，真正有价值的决策可能就那几句话。全量塞进去，模型反而容易被无关信息干扰，抓不住重点。第三个问题是冲突信息无法处理。你三个月前说用方案 A，上个月改成了方案 B，全量塞进去模型根本不知道该听哪个。

所以claude-mem这类系统的设计哲学，不是“记住所有”，而是**“记住该记的，忘掉该忘的，检索时只取相关的”**。这背后其实是三个独立的技术环节：抽取、存储、检索。每个环节做得好不好，直接决定记忆系统的可用性。

2.2 抽取、存储、检索：三段式架构的取舍

我把claude-mem的工作流拆成三段，这也是我推荐任何自建记忆系统都遵循的骨架。

抽取阶段，核心任务是从原始对话流里识别出“值得记住”的信息。这里有个关键判断：不是所有信息都值得存。我一般把值得记忆的内容分成四类——事实类（项目用什么技术栈、部署在哪）、偏好类（用户喜欢简洁回答还是详细解释）、决策类（为什么选 A 不选 B）、教训类（某个坑踩过一次别再踩）。抽取方式有两种主流做法：一种是规则触发，比如检测到“我们决定用”“以后都用”“不要用”这类句式就标记；另一种是用一个小模型做摘要和分类。实测下来，规则 + 小模型摘要的混合方案性价比最高，纯规则太死板，纯模型成本高且不稳定。

存储阶段，要解决的是“记忆怎么组织”。最粗暴的是存成纯文本列表，但检索时很难精准命中。我推荐的是结构化 + 向量化双写：每条记忆既有结构化的元数据（时间、项目、类型、标签），又有向量表示用于语义检索。元数据负责精确过滤，向量负责模糊匹配，两者结合才能既准又全。存储介质上，轻量场景用 SQLite 加一个向量扩展就够了，团队协作场景可以上 PostgreSQL 配 pgvector。

检索阶段，是决定体验的关键。用户提一个新问题，系统要快速从记忆库里捞出最相关的几条。这里的核心是混合检索：先用元数据做硬过滤（比如只查当前项目的记忆），再用向量相似度做语义排序，最后按时间衰减加权——越新的记忆权重越高。我试过纯向量检索，问题是它会把语义相近但项目不对的记忆也捞出来，加了元数据过滤之后准确率提升非常明显。

2.3 记忆的“遗忘机制”为什么必须要有

这一点很多人会忽略，但它是记忆系统能不能长期用的分水岭。如果只增不减，记忆库会越来越臃肿，检索噪声越来越大，最后系统变得不可用。

claude-mem的思路里，遗忘不是删除，而是分层降权。我的做法是给每条记忆打一个“活跃度分数”，初始为 1，每次被检索命中并确认有用就加分，长期没被命中就按时间衰减。分数低于阈值的记忆转入“冷存储”，检索时默认不参与，但保留可手动唤醒的能力。这样既控制了活跃记忆的规模，又不会真的丢失历史信息。

还有一个细节是冲突消解。当新记忆和旧记忆矛盾时（比如技术选型变了），不能简单覆盖，而要标记旧记忆为“已废弃”并记录变更原因。这样模型在检索时能看到演进脉络，而不是被过时信息误导。这个机制我在实际项目里踩过坑——早期直接覆盖，结果后来想回溯“为什么当初改了方案”时，历史全没了。

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

3.1 记忆抽取的触发规则怎么设计

抽取规则设计得好不好，直接决定记忆库的质量。我总结了一套经过实战验证的触发策略，分三个层次。

第一层是显式指令触发。当对话中出现明确的记忆意图词，比如“记住”“以后都”“别再”“我们决定”，就强制触发抽取。这类信号最可靠，误报率极低。我一般会维护一个关键词表，覆盖中英文常见表达。

第二层是结构化信息触发。当对话中出现技术栈名称、文件路径、配置参数、版本号这类结构化信息时，触发抽取并自动打标签。比如检测到PostgreSQL 15、/api/v2/users、timeout=30s这类模式，就归类为“技术事实”。

第三层是周期性摘要触发。每 N 轮对话或每次会话结束时，用一个小模型对整段对话做一次摘要，提炼出决策和教训。这一层负责捕捉那些没有显式信号、但整体有价值的上下文。

三层配合下来，抽取的召回率和准确率都能接受。要注意的是触发频率不能太高，否则记忆库会被碎片化信息淹没。我的经验是每轮对话最多触发一次抽取，且同一主题短时间内不重复抽取。

3.2 记忆条目的数据结构设计

一条好的记忆条目，应该让人和机器都能快速理解。我推荐的结构包含这些字段：

这里有个关键设计原则：content 必须自包含。什么意思？就是单独看这一条记忆，不需要上下文也能理解。反面例子是“改成 30 了”，正面例子是“用户 API 的超时时间从 10s 改成 30s，因为批量导出场景经常超时”。自包含的记忆在检索注入时不会产生歧义，这一点极其重要。

3.3 检索排序的加权公式

检索排序是记忆系统的“大脑”，我用的加权公式大致是这样：

final_score = w1 * vector_similarity + w2 * recency_decay + w3 * hit_frequency + w4 * type_priority

其中vector_similarity是语义相似度，归一化到 0 到 1；recency_decay是按时间衰减的新鲜度，我一般用指数衰减，半衰期设 30 天；hit_frequency是历史命中次数归一化；type_priority是类型优先级，决策类和教训类通常比普通事实更重要。

权重的取值需要根据场景调。我实测下来，语义相似度占 0.5，新鲜度占 0.2，命中频率占 0.15，类型优先级占 0.15是个不错的起点。如果你的场景更看重历史决策，可以把类型优先级调高；如果项目变化快，把新鲜度调高。

注意：权重不要拍脑袋定，一定要用真实查询做 A/B 测试。我早期凭感觉设的权重，实际效果比调优后差了将近 30% 的命中准确率。

3.4 上下文注入的预算控制

检索出记忆之后，怎么注入到 prompt 里也有讲究。不能把所有命中的记忆都塞进去，要控制预算。

我的做法是设一个token 预算上限，比如 2000 token 专门留给记忆。然后按 final_score 从高到低填充，直到接近预算。同时做去重和合并：语义高度重复的记忆只保留分数最高的那条；同一主题的多条记忆可以合并成一段。

注入的格式也很关键。我习惯用清晰的分区标注，比如：

[项目记忆] - 技术栈：PostgreSQL 15 + Redis 7 - 部署：Docker Compose，生产环境用独立数据库实例 [用户偏好] - 回答偏好：先给结论再给细节，代码示例要能直接运行 [历史决策] - 2024-03 选择 PostgreSQL 而非 MySQL，原因是需要 JSONB 和全文检索

这种结构化注入让模型能快速定位信息，比一大段自然语言描述效果好得多。

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

4.1 环境准备与依赖选型

动手之前先把环境理清楚。我推荐的起步配置是这样的：

• 运行环境：Python 3.10 以上，或者 Node.js 18 以上，看你熟悉哪个生态。
• 存储：SQLite 加sqlite-vec扩展，单机场景足够；团队场景用 PostgreSQL 加pgvector。
• 向量模型：本地跑的话用bge-small-zh这类小模型，追求效果可以用 API 调用更大的嵌入模型。
• 摘要模型：抽取阶段用的小模型，本地 7B 级别就够，或者调用轻量 API。

为什么起步推荐 SQLite？因为零运维、单文件、迁移方便。我见过太多人一上来就上重型向量数据库，结果光环境就折腾两天，热情全耗没了。先用 SQLite 把流程跑通，验证有效之后再考虑升级。

安装核心依赖：

pip install sqlite-vec openai tiktoken

如果你用 PostgreSQL：

pip install psycopg2-binary pgvector

4.2 记忆库的初始化

先建表。SQLite 场景下，核心表结构大概是这样：

CREATE TABLE memories ( id TEXT PRIMARY KEY, content TEXT NOT NULL, type TEXT NOT NULL, project TEXT NOT NULL, tags TEXT, embedding BLOB, created_at INTEGER NOT NULL, last_hit_at INTEGER, score REAL DEFAULT 1.0, status TEXT DEFAULT 'active' ); CREATE INDEX idx_project ON memories(project); CREATE INDEX idx_status ON memories(status); CREATE INDEX idx_type ON memories(type);

向量索引用sqlite-vec的虚拟表来建：

CREATE VIRTUAL TABLE memory_vectors USING vec0( memory_id TEXT PRIMARY KEY, embedding FLOAT[384] );

这里384是嵌入维度，要和你选的嵌入模型对齐。bge-small-zh是 512 维，text-embedding-3-small是 1536 维，建表前一定确认清楚，维度不匹配会直接报错。

提示：向量维度和模型必须严格对应，这是新手最容易踩的坑。我见过有人换了模型忘了改表结构，排查了半天才发现是维度问题。

4.3 抽取逻辑的实现

抽取模块我写成一个独立函数，输入是一段对话，输出是记忆条目列表。核心逻辑分三步：

def extract_memories(conversation, project): memories = [] # 第一步：显式指令触发 trigger_patterns = ["记住", "以后都", "别再", "我们决定", "不要用"] for turn in conversation: if any(p in turn.text for p in trigger_patterns): memories.append(build_memory(turn.text, "decision", project)) # 第二步：结构化信息触发 tech_pattern = r"(PostgreSQL|MySQL|Redis|Docker|Kubernetes)[\s\d\.]*" for turn in conversation: matches = re.findall(tech_pattern, turn.text) if matches: memories.append(build_memory(turn.text, "fact", project, tags=matches)) # 第三步：周期性摘要 if len(conversation) > 20: summary = summarize(conversation) memories.append(build_memory(summary, "lesson", project)) return deduplicate(memories)

build_memory负责生成自包含的 content、计算嵌入、初始化分数。deduplicate负责去掉语义重复的条目，我一般用余弦相似度大于 0.9 作为去重阈值。

这里有个实操心得：摘要触发不要每轮都做，成本高且容易产生冗余。我一般设成每 20 轮或会话结束时触发一次，效果和成本的平衡最好。

4.4 检索与注入的完整流程

检索函数接收用户当前问题，返回要注入的记忆文本。完整流程：

def retrieve_memories(query, project, token_budget=2000): # 1. 计算查询向量 query_vec = embed(query) # 2. 元数据硬过滤：只查当前项目的活跃记忆 candidates = db.query( "SELECT * FROM memories WHERE project=? AND status='active'", (project,) ) # 3. 向量相似度计算 scored = [] for mem in candidates: sim = cosine_similarity(query_vec, mem.embedding) recency = exp_decay(mem.created_at, half_life_days=30) freq = normalize(mem.hit_count) type_pri = TYPE_PRIORITY[mem.type] final = 0.5*sim + 0.2*recency + 0.15*freq + 0.15*type_pri scored.append((final, mem)) # 4. 排序并按预算填充 scored.sort(reverse=True, key=lambda x: x[0]) selected = [] used_tokens = 0 for score, mem in scored: mem_tokens = count_tokens(mem.content) if used_tokens + mem_tokens > token_budget: break selected.append(mem) used_tokens += mem_tokens update_hit(mem.id) # 更新命中时间和分数 # 5. 格式化注入 return format_for_injection(selected)

format_for_injection按类型分组，输出前面提到的结构化格式。这个流程跑通之后，你会发现 AI 助手的“记忆感”立刻就不一样了。

4.5 遗忘与衰减的定时任务

遗忘机制靠一个定时任务来维护，我一般每天跑一次：

def decay_and_archive(): now = time.time() memories = db.query("SELECT * FROM memories WHERE status='active'") for mem in memories: days_since_hit = (now - (mem.last_hit_at or mem.created_at)) / 86400 decay = 0.5 ** (days_since_hit / 30) # 30天半衰期 new_score = mem.score * decay if new_score < 0.1: db.update(mem.id, status='cold', score=new_score) else: db.update(mem.id, score=new_score)

冷存储的记忆默认不参与检索，但保留手动唤醒接口。这样活跃记忆库始终保持在合理规模，检索速度和准确率都不会随时间劣化。

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

5.1 记忆检索不准的排查思路

检索不准是最常见的问题，表现是“明明存过，但就是捞不出来”或者“捞出来的全是无关的”。我整理了一套排查顺序：

我踩过最坑的一次是嵌入模型换了但没重新生成历史向量，导致新旧向量不在同一语义空间，检索结果完全乱套。后来我加了一条规则：换嵌入模型必须全量重建向量索引，并在代码里做了版本校验。

5.2 记忆冲突与过时信息处理

当用户改了技术选型，旧记忆还在，新记忆也进来了，检索时两条都命中，模型就懵了。我的处理方案是显式废弃 + 变更记录。

当抽取模块检测到新记忆和已有记忆语义矛盾时（比如同一主题的决策变了），不删除旧的，而是把旧的 status 改成deprecated，并在新记忆里加一个supersedes字段指向旧记忆。检索时默认只取 active 的，但如果用户问“为什么改方案”，可以主动把 deprecated 的也捞出来展示演进过程。

这个机制的价值在于保留了决策的历史脉络。很多团队复盘时最想知道的就是“当初为什么这么定”，如果记忆系统只会覆盖，这个信息就永远丢了。

5.3 性能优化的几个实操技巧

记忆库大了之后，检索会变慢。我总结了几个立竿见影的优化点：

• 向量索引必须建。SQLite 用sqlite-vec的虚拟表，PostgreSQL 用pgvector的 HNSW 索引。不建索引的话，几万条记忆检索就要几百毫秒。
• 元数据过滤前置。先用 project、status 这些字段做硬过滤，把候选集缩小到几百条，再做向量计算。这一步能把检索时间砍掉一大半。
• 嵌入计算批量化。写入记忆时不要一条一条算嵌入，攒一批一起算，吞吐能提升好几倍。
• 缓存高频查询。同一个问题短时间内重复问，直接返回缓存结果，省掉向量计算。

我实测下来，优化前 5 万条记忆检索要 800ms，优化后降到 50ms 以内，体验完全不一样。

5.4 隐私与数据隔离的注意事项

记忆系统存的是用户的真实项目信息，隐私和隔离必须重视。我的做法是：

• 项目级隔离：不同项目的记忆物理隔离或至少逻辑隔离，查询时强制带 project 过滤，杜绝串项目。
• 敏感信息过滤：抽取阶段就过滤掉密钥、密码、token 这类敏感串，绝不入库。我维护了一个正则黑名单，命中就跳过。
• 本地优先：能本地跑的嵌入和摘要模型就本地跑，减少数据外传。
• 可导出可删除：提供一键导出和按项目删除的能力，用户对自己的记忆有完全控制权。

注意：记忆系统一旦上线，数据只会越积越多，隐私设计必须在第一天就做好，事后补救成本极高。

6. 我个人的一些实战体会

用claude-mem这套思路跑了几个月之后，最大的感受是：记忆系统的价值不在于“记得多”，而在于“记得准”。我早期贪多，什么都想存，结果检索噪声大到没法用。后来狠心砍掉一半抽取规则，只保留高置信度的信号，体验反而好了很多。

另一个体会是遗忘机制比记忆机制更难做，也更值得做。人脑的高效恰恰在于它会遗忘，记忆系统也一样。一个不会遗忘的系统，用三个月就会变成垃圾场。我现在把衰减和归档当成核心功能来维护，而不是可有可无的附加项。

最后分享一个小技巧：给记忆加一个“手动确认”入口。当系统检索到某条记忆并注入后，如果用户明确表示“对，就是这个”，就把这条记忆的分数大幅提升；如果用户纠正了，就降低分数甚至标记废弃。这个反馈闭环能让记忆系统越用越懂你，比任何静态权重都有效。我加了这个小功能之后，两周内检索准确率肉眼可见地提升了。

这套东西后续还能往几个方向扩展：比如做跨设备的记忆同步，比如把记忆按主题自动聚类生成“项目知识图谱”，比如接入多个 AI 助手共享同一套记忆。核心骨架搭好之后，这些都是自然的延伸。