项目标题里的“claude-mem”让我挺好奇从命名看大概率是围绕 Claude 的对话记忆能力做文章。这类工具在真实项目里其实非常实用——我自己的体会是Claude 这类大模型本身有很强的单轮对话能力但一旦涉及多轮、跨会话的上下文保持很快就会把前面聊过的关键信息忘得干干净净。做个记忆层、把“长期记忆”这件事从模型能力里剥离出来自己接管就成了很多实际项目的刚需。“claude-mem”这类项目要做的事通俗讲就是给 Claude 装一个外挂大脑。模型本身只负责“理解与生成”记忆部分由外部模块来管——每次对话结束后把重要信息抽出来存好下次对话开始时再自动塞回上下文里。这个思路几乎是一切 AI 会话工具的通用解法只是不同项目在“记什么”“怎么存”“什么时候塞回去”这几个问题上的取舍完全不一样。这篇文章我会从“为什么模型记不住”“记忆管理该拆成哪几个模块”“实际跑通需要哪些代码和配置”“真实使用中会踩哪些坑”这几个维度来写把一个带记忆功能的 Claude 会话工具从需求拆分到落地实现完整过一遍。文本里的代码和配置我给的是基于常见实践的示例方案你可以当成脚手架直接改着用。1. 为什么原生对话总是“聊了就忘”模型上下文的本质限制先说一个反直觉的事实Claude 这类大模型并不是“记性差”而是它根本没有“记忆”这个模块。你看到的“记忆”其实完全来自输入上下文。每次调用接口你都要把历史对话重新完整发给它一次模型只是基于你这次给的文本做预测。所以所谓的“多轮对话记忆”本质是“把历史文本反复灌回输入框”。只要窗口够大理论上能聊很久但只要关掉会话、或者对话长度超出上下文限制前面聊的内容就从物理上消失了。我在实际项目里测过一个稍复杂的需求对话大概 20 到 30 轮之后早期讨论过的项目约束、命名规则、技术选型就会开始被模型“选择性遗忘”。这不是模型变笨了而是它真的看不全。上下文窗口是有限的前面的内容被挤出去了。这引出一个很实际的结论别指望模型自己记住要靠工程手段把“重要的事”摘出来放到模型看得到的地方。“claude-mem”这类记忆增强工具要做的事情本质上就是把“对话历史”和“长期记忆”拆成两层对话历史最近几轮的完整文本保证上下文连贯。长期记忆跨会话仍然有效的关键事实、偏好、约定以结构化形式存放每次开头自动注入。这两个层分开管理之后Claude 的每次请求都变成了“记忆摘要 最近几轮对话 当前问题”既不需要把几百轮历史全塞进去也不会丢掉关键约束。我猜“claude-mem”这个项目名大概就是“Claude memory”的组合定位很直接。下面我按自己实现类似系统时的思路把这个项目拆开讲重点放在最容易踩坑的几个决策点上。2. 记忆系统的三个核心模块抽取、存储、注入把一个“会记忆的 Claude 工具”拆开看核心就是三段流水线。搞清楚这三个模块各自解决什么问题再写代码就顺了。2.1 抽取什么信息值得被记住不是所有对话内容都值得存。真正需要长期记住的通常是这几类用户明确的偏好和约束比如“以后回复都用中文”“代码风格用 TypeScript strict mode”。项目级关键事实比如“后端端口是 8080”“部署走 Docker Compose”“数据库用 PostgreSQL”。决策记录为什么选了 A 方案而不是 B 方案避免下次重复讨论。用户的身份或背景信息比如“我是后端开发者不太熟悉前端”。抽取实现方式有很多种。我自己用的是“提示词引导分类抽取”让 Claude 阅读当前轮对话按照上面几类提取结构化摘要以 JSON 格式返回。示例提示词大概长这样从以下对话中提取值得长期记忆的信息。 只提取明确表达的内容不要推断。 输出 JSON 数组每项包含 field信息类别、content具体内容、importance1-5。 对话内容 ...这种做法好处是不需要自己写 NLP 逻辑完全借助模型的语义理解能力。坏处是每次抽取都有 token 成本所以实际使用时我不会每轮都抽而是每 3 到 5 轮、或当对话中出现明显的关键决策时再触发一次。2.2 存储用合适的载体保存“长期记忆”存储层选择直接决定了后面读取和注入的方便程度。我用过三种方案各有适用场景存储方式优点缺点适用场景JSON 文件简单零依赖直接可读可改并发写入要小心数据量大了查询慢单用户本地工具、原型验证SQLite单文件、支持结构化查询、并发安全需要一点点 SQL 基础个人工具、轻量多会话管理向量数据库支持语义检索可以找“相关记忆”部署重、需要 embedding 模型对话量大、需要模糊召回记忆的场景“claude-mem”这种工具的原始版本大概率走的是 JSON 文件或 SQLite 路线。理由很实在记忆的写入和读取频率不高数据规模撑不起上百万条用向量库属于过度设计。但存储结构上有个特别容易踩坑的地方不要按“会话 ID”存记忆要按“事实主体”存。我第一次实现时直接把整段会话摘要存成一个文件结果发现一个问题跨会话查询时根本不知道某条信息属于哪个话题。后来改成每一条记忆都带独立的 ID、类别、创建时间、最后访问时间、来源会话 ID查询和注入都灵活得多。每一条记忆的字段大概是这样{ id: mem_001, category: project_fact, content: 后端服务端口为 8080部署在 Docker Compose 的 app 服务中, importance: 4, created_at: 2025-02-10T10:00:00Z, last_accessed_at: 2025-02-11T15:30:00Z, source_conversation: conv_003 }last_accessed_at这个字段一开始我根本没加后来发现没有它就没法做“重要记忆自动衰减”高频使用的记忆会和不常用的混在一起每次都一股脑全注入上下文白白被占掉不少。2.3 注入在正确的时间把正确记忆塞回去记忆存好了不会自己用注入策略才是决定“记忆好不好用”的关键。粗暴做法是每次都把所有记忆全部注入让 Claude “全知全能”。但实测下来问题很明显token 消耗大、无关信息会干扰当前对话的专注度。比如你明明在问前端样式问题模型非要提一句“用户是后端开发者”虽然不至于出错但总有种答非所问的味道。正确的做法是分层注入全局记忆用户身份、通用偏好、核心价值观每次对话开头注入。会话相关记忆通过关键词提取和当前对话主题匹配的记忆按重要程度排序截取前 N 条。最近对话历史只保留最近 4 到 6 轮完整文本。这套“分级注入”策略最关键的地方在于构建system prompt的模板设计。模板要告诉模型哪些是记忆、哪些是当前对话、两者优先级如何。我是这样组织的你是一个有长期记忆能力的助手。以下是关于用户的长期记忆供你参考 【重要偏好】 - 用户偏好中文回复技术术语可以保留英文 - 用户是后端开发者前端代码需要更详细的注释 【项目事实】 - 项目使用 FastAPI 作为 Web 框架Python 3.11 - 认证方式为 JWT密钥存放在环境变量 JWT_SECRET 中 注意以上记忆仅作为背景信息如果与当前对话冲突以当前对话为准。 --- 最近对话 --- ... --- 当前问题 --- ...“以当前对话为准”这行字看着不起眼实际非常重要。我在测试中就遇到过如果记忆里写了一条过时的项目状态而用户在当前对话里已经明确更改了方案模型因为优先遵循记忆而把新的要求忽略了。有了这行提示模型就会把当前对话当作更高优先级的决策依据。3. 从零实现一个带记忆的 Claude 会话工具代码路径拆解说明一下以下是基于常见实践给出的示例实现方案不是某个现成项目的源码。你完全可以用这个结构去搭自己的版本也可以拿去找开源项目的对应模块。3.1 环境准备与依赖选型我用 Python 做原型因为 Claude 官方 SDK 支持好而且处理 JSON 格式的记忆数据非常顺手。需要准备的依赖pip install anthropic python-dotenv如果要做 SQLite 存储Python 标准库自带的sqlite3就够了不需要额外装 ORM。环境变量.env里配好 API KeyANTHROPIC_API_KEYsk-ant-...3.2 记忆存储模块用文件还是 SQLite我建议第一版直接用 SQLite。理由很现实JSON 文件在并发写入时容易损坏SQLite 天然支持事务而且查询语句写起来也不复杂。建表语句可以参考下面这个结构CREATE TABLE memories ( id TEXT PRIMARY KEY, category TEXT NOT NULL, content TEXT NOT NULL, importance INTEGER DEFAULT 3, created_at TEXT NOT NULL, last_accessed_at TEXT, source_conversation TEXT ); CREATE INDEX idx_memories_category ON memories(category);加索引是因为注入时要按类别过滤没有索引的话数据量大了查询会变慢。SQLite 的索引对这个小工具来说完全够用。Python 操作代码段import sqlite3 import uuid from datetime import datetime, timezone class MemoryStore: def __init__(self, db_pathmemory.db): self.db_path db_path self._init_db() def _init_db(self): with sqlite3.connect(self.db_path) as conn: conn.executescript( CREATE TABLE IF NOT EXISTS memories ( id TEXT PRIMARY KEY, category TEXT NOT NULL, content TEXT NOT NULL, importance INTEGER DEFAULT 3, created_at TEXT NOT NULL, last_accessed_at TEXT, source_conversation TEXT ); ) def add_memory(self, category, content, importance3, source_conversationNone): with sqlite3.connect(self.db_path) as conn: conn.execute( INSERT INTO memories VALUES (?, ?, ?, ?, ?, ?, ?), ( uuid.uuid4().hex, category, content, importance, datetime.now(timezone.utc).isoformat(), None, source_conversation, ) ) def get_memories_by_category(self, category, limit20): with sqlite3.connect(self.db_path) as conn: rows conn.execute( SELECT content, importance FROM memories WHERE category ? ORDER BY last_accessed_at DESC NULLS LAST, importance DESC LIMIT ?, (category, limit) ).fetchall() return rows这段代码里有个细节last_accessed_at DESC NULLS LAST的处理。第一次写入时last_accessed_at是空的如果直接用DESCNULL 会排在最前面新写入但没被用过的记忆反而不容易出现在注入列表里。这算是 SQLite 排序的一个小坑处理办法就是加NULLS LAST或者写入时就把last_accessed_at初始化为当前时间。3.3 记忆抽取与注入的调用链封装封装一个ClaudeMemoryClient把“抽取 → 存储 → 注入 → 调用模型”整个流程串起来。核心方法代码如下from anthropic import Anthropic class ClaudeMemoryClient: def __init__(self, api_key, store: MemoryStore): self.client Anthropic(api_keyapi_key) self.store store # 记录当前会话的对话列表 self.history [] def _extract_memories(self, conversation_text: str): 让 Claude 抽取值得长期记忆的信息 extract_prompt f 从以下对话中提取值得长期记忆的信息。只提取明确表达的内容不要推断。 输出严格的 JSON 数组每项包含 category、content、importance 三个字段。 category 可选值preference、project_fact、decision、user_info。 importance 取 1 到 5 的整数。 对话内容 {conversation_text} response self.client.messages.create( modelclaude-sonnet-4-20250514, max_tokens2000, messages[{role: user, content: extract_prompt}] ) text response.content[0].text # 注意这里必须做健壮性处理模型偶尔会输出 json 包裹的格式 json_text text.strip() if json_text.startswith(): json_text json_text.split(\n, 1)[1].rsplit(, 1)[0] import json return json.loads(json_text) def _build_prompt(self, user_input: str): 组装 system prompt 记忆 最近对话 # 从存储中取全局记忆和会话相关记忆 global_memories self.store.get_memories_by_category(preference, limit10) global_memories self.store.get_memories_by_category(user_info, limit10) project_memories self.store.get_memories_by_category(project_fact, limit15) decision_memories self.store.get_memories_by_category(decision, limit10) mem_block if global_memories: mem_block 【重要偏好】\n \n.join(f- {c} for c, _ in global_memories) \n\n if project_memories: mem_block 【项目事实】\n \n.join(f- {c} for c, _ in project_memories) \n\n if decision_memories: mem_block 【历史决策】\n \n.join(f- {c} for c, _ in decision_memories) \n\n system_prompt f 你是一个有长期记忆能力的助手。以下是关于用户的长期记忆供你参考 {mem_block or (暂无长期记忆)} 注意以上记忆仅作为背景信息如果与当前对话冲突以当前对话为准。 return system_prompt def chat(self, user_input: str): # 1. 检查是否需要抽取记忆每 3 轮或遇到关键决策词触发 if len(self.history) % 3 2: recent_conversation \n.join( f{msg[role]}: {msg[content]} for msg in self.history[-6:] ) try: memories self._extract_memories(recent_conversation f\nuser: {user_input}) for mem in memories: self.store.add_memory( categorymem[category], contentmem[content], importancemem[importance], source_conversationcurrent_session ) except Exception as e: # 抽取失败不影响主对话 print(f[memory extract warning] {e}) # 2. 组装消息 self.history.append({role: user, content: user_input}) messages [{role: user, content: user_input}] # 实际使用中这里把 history 转成 anthropic 的消息格式 # 3. 调用模型 response self.client.messages.create( modelclaude-sonnet-4-20250514, max_tokens4096, systemself._build_prompt(user_input), messages[{role: user, content: user_input}], ) assistant_text response.content[0].text self.history.append({role: assistant, content: assistant_text}) return assistant_text上面这段代码里有个故意留的坑messages只传了当前用户输入没传完整历史。实际使用时如果要多轮对话历史消息必须一并传进去否则模型看不到前文。我这里简化处理是为了突出记忆部分的逻辑真正落地时把self.history的最近几轮转成 API 格式传进去就行。抽取触发条件“每 3 轮抽一次”也是拍脑袋定的你完全可以根据场景调整。我后来发现更实用的触发逻辑是检测用户输入里是否包含“改成”“重新选”“我决定”“以后都用”这类信号词一旦出现立刻触发抽取因为这些词后面往往跟着长期有效的决策。3.4 记忆去重与更新的关键实现这个环节是最容易被忽略、但实际影响最大的。不加去重的话跑几天之后同一个事实会被存储成好几条相似记录注入时全是重复内容白白浪费上下文空间。我实现的一个简单去重方式是“语义相似度检查”。每次写入新记忆前先跟同类别已有记忆做个简单对比。不一定要上向量模型简单的关键词重叠就能过滤大部分重复def _is_duplicate(self, new_content: str, category: str) - bool: existing self.store.get_memories_by_category(category, limit50) new_words set(new_content.split()) for old_content, _ in existing: old_words set(old_content.split()) overlap len(new_words old_words) / max(len(new_words), len(old_words), 1) if overlap 0.6: return True return False用 0.6 这个阈值看起来粗糙但实际效果很不错。因为同一个事实的表述方式通常高度相似比如“后端端口 8080”和“我们的后端端口是 8080”分词后的重叠率会非常高。如果两条记忆说的是完全不同的话题词重叠率很难超过 0.6。当然这只能处理“近义重复”处理不了“反义更新”。用户在记忆里约定用 JWT 认证隔几天又说“以后不用 JWT 了改 OAuth”这时候关键词重叠率照样高直接判定为重复跳过写入就出大事了。所以我在写入前还会加一个“否定词检测”negation_markers [不, 别, 取消, 停止, 换掉, 不要, 改为, 改成] if any(marker in new_content for marker in negation_markers): # 将同类别、相似度高的旧记忆标记为过期而不是直接跳过 self.store.mark_outdated(category, new_content)“改为”“改成”这类词表示的是变更而非重复处理逻辑应该是“把旧记忆过期 写入新记忆”。我给memories表加了status字段来标记active/outdated注入时只查active的记录。这样既保留了决策历史又不会让过时约定干扰当前对话。4. 多会话记忆的实际效果一个完整的项目场景推演纸上谈兵太干了用一个实际的项目工作流推演一遍你就能直观看到记忆系统的价值。假设你在维护一个叫“某内部工具平台”的 Web 项目技术栈是 FastAPI Vue 3 PostgreSQL。你第一天跟 Claude 聊了后端接口设计约定了“所有接口返回格式统一为{code, data, message}”。第二天你打开新会话想继续讨论前端页面怎么对接这些接口。没有记忆系统的 Claude你需要在开头重新解释一遍接口返回格式甚至把所有接口文档重新粘贴进去。如果你的问题不够完整模型可能会给出不符合约定的对接代码。有记忆系统的 Claude系统在第二次对话开头已经注入了一条项目事实“所有接口返回格式统一为 {code, data, message}”你直接说“帮我把用户列表页的前端请求封装一下”模型输出的代码自动就有res.data.data的解包逻辑完全符合你昨天定下的约定。这就是记忆系统最核心的价值消除“重复解释成本”让每一次新会话都能站在之前的决策基础上继续走。再推演一个更复杂的场景你在 20 轮对话中不断调整某个数据处理流程中间提到了“敏感字段需要脱敏”“脱敏规则用 SHA-256 哈希”“白名单里的内部用户不脱敏”。这些关键决策会在第 3、6、9 轮等节点被抽取为独立记忆。等到你第 30 轮问“整体流程再梳理一遍”时Claude 看到的不是压缩到极限的 30 轮历史文本而是三条干净的项目事实回答质量自然更稳定。5. 真实使用中的翻车现场记忆工具最容易踩的五个坑工具写出来是一回事真正用起来是另一回事。我把自己和身边朋友使用这类记忆工具遇到的高频问题整理一遍这些问题几乎每个实现记忆层的项目都会碰到。5.1 模型把记忆当成指令执行引发“记忆幻觉”如果 system prompt 里那行“记忆仅作背景信息与当前对话冲突时以当前对话为准”被省略模型极有可能把过时记忆当成硬约束即使当前对话已经明确改了方案。我在测试时遇到过最离谱的一次记忆里存着一位用户的旧身份信息新对话里用户说“我现在是产品经理了”模型仍然按“用户是后端开发者”来调整回复的术语深度。原因就是模型先读了 system prompt 里的记忆然后把它当成了比当前对话更权威的信息。解决办法就是那行提示必须写清楚优先级。有些项目还会在记忆条目后面加来源时间和置信度比如“采集自 2025-01-15 的对话置信度 4/5”模型看到时间戳会更倾向于使用更新的信息。5.2 抽取任务污染主对话的 token 配额每次让 Claude 抽取记忆都要额外消耗一次请求的 token。如果每轮对话都触发抽取成本可能翻倍。对于 API 按 token 计费的实际使用场景来说这是真金白银的差异。我自己一开始每轮都抽跑了半天发现费用实在扛不住。后来改成“3 轮抽一次 信号词触发”成本降到原来的三分之一抽取质量并没有明显下降。还有个折中方案用更小更快的模型做抽取任务主对话用强模型这样成本还能再降一截。5.3 上下文注入顺序错了记忆全白搭模型对上下文不同位置的注意力分布并不均匀。实践中我发现长期记忆放在 system prompt 的开头比放在接近用户消息的位置效果更好。如果记忆夹在对话历史中间很容易被后面的用户问题冲淡。具体做法上我是把“身份定位 长期记忆 当前会话指令”依次排列在 system prompt 里。长期记忆不要堆太多条控制在 15 到 20 条以内。超出这个量模型执行第一条和最后一条记忆的权重差异非常明显。5.4 并发会话互相覆盖记忆一个记忆库同时给多个会话使用时如果没有会话隔离A 会话写入的记忆可能污染 B 会话的内容抽取结果。举个具体例子你在同一个库里跑了“项目 A”和“项目 B”两套对话抽取阶段模型很容易把 A 项目的技术选型当成 B 项目的事实存下来后面 B 的对话就开始胡说。解决办法是给记忆加一层 namespace 字段每个项目或每个会话组用独立的命名空间物理上分开存、分开查。最简单的实现就是 SQLite 里加一列namespace所有查询都加上这个过滤条件。我甚至建议一个项目一个库文件省心得多。5.5 记忆内容隐私问题别把敏感信息写进明文库记忆内容往往包含用户身份、项目细节、内部决策如果直接明文存在 SQLite 或 JSON 文件里一旦文件泄露或者被其他进程读取后果不太好。最少要做的是对敏感内容做加密存储或者至少把库文件权限收紧。我记得有个项目因为把数据库连接串和内部系统账号信息写进了记忆库后来这个文件被误传到公共代码仓库虽然及时发现但处理起来相当麻烦。所以抽取阶段最好就加一个敏感信息过滤规则比如正则匹配内网域名、密钥格式直接跳过不写入记忆库。6. 进阶配置给记忆工具加分的小改动基础流程跑通之后有几个改动会让工具更“聪明”属于投入小回报高的优化项。6.1 记忆重要性衰减机制前面提到每条记忆有last_accessed_at和importance两个字段。注入时不只是按重要程度排序还要结合“最近是否被使用过”做加权。一个简单有效的公式score importance * 0.7 recency_score * 0.3recency_score可以根据last_accessed_at距当前时间的天数映射到 1 到 5。规则是一周内访问过的记忆得 5 分一个月内得 3 分超过三个月得 1 分。这个机制能保证高频使用的记忆始终排在注入队列前面而那些“存了但再也没提过”的冷门记忆慢慢沉底。我在实现里还加了一个定期清理任务对超过 90 天未访问且 important 小于 3 的记忆做软删除。这样记忆库不会无限膨胀查询速度也能保持稳定。6.2 记忆导出与可视化纯文本的记忆库很难直观检查“机器到底记住了什么”。我给工具加了一个简单的导出功能把 SQLite 里的记忆按类别汇总成 Markdown 文件定期人工 review 一遍。这一步看着不起眼实际相当有用。Review 时能发现三类问题一是抽取出来的记忆明显偏离对话原意二是敏感信息混进来了三是过时决策没有正确过期。人工抽查是保证长期记忆准确性的最后一道防线完全依赖自动流程迟早会翻车。6.3 会话结束时的“总结钩子”在正常对话结束而不是强制中断时触发一次完整的记忆抽取把整个会话的决策和约定补录进库。这个操作对长会话特别有用因为会话中按 3 轮一次的节奏抽取可能漏掉最后几轮的收尾结论。实现方式也不难显式监听会话结束事件把整个历史消息拼成一段文本送给抽取模块处理。成本比中途多次抽取低效果反而更好因为模型能看到全局而不是片段。7. 把“claude-mem”落地到自己的项目我的实操建议最后给一套可以直接抄作业的落地顺序省得你从零开始排优先级。第一步先不做完整工具只写一个最小闭环Claude 单轮对话 SQLite 存储 手动注入。验证记忆读和写的基本路径通不通。第二步加上自动抽取。用固定的提示词模板让模型输出 JSON注意做好json包裹内容的清洗这是模型输出里最常见的不稳定因素。第三步优化注入策略。实现“全局记忆 相关记忆 最近对话”三层组装观察模型回复质量的变化调整各类别记忆的条数上限。第四步加上去重和过期机制。这一步不做的话工具用一星期后记忆库会变得越来越脏迟早要花大量时间清理。第五步根据实际使用情况决定要不要上向量检索。我的判断标准很简单如果你发现按关键词过滤已经无法从记忆库里找出一条特定的事实说明记忆条数已经多到需要语义检索了。在那之前关键词匹配和分类过滤足够解决问题。整个过程中最重要的心态是“记忆系统是给模型补上下文用的不是给模型当知识库用的。”不要试图把所有知识都塞进去只放那些“跨会话仍然稳定有效、且会影响后续回答”的事实。想明白这一条很多设计取舍都会变得简单。我对这类工具的未来走向也挺好奇——随着上下文窗口越来越长原生记忆能力会变强但“抽取重要信息 长期结构化存储”这个思路不太可能被完全替代毕竟窗口再大也有成本上限。如果你也在折腾类似的东西建议从最小版本跑起跑通之后再不断迭代很快就能感受到“每次新会话都记得你是谁”的体验差异。 
长河君 · 2026/10/26 11:51:52 · 阅读 1.2k 给Claude装外挂大脑：记忆增强工具的设计与实现
项目标题里的“claude-mem”让我挺好奇从命名看大概率是围绕 Claude 的对话记忆能力做文章。这类工具在真实项目里其实非常实用——我自己的体会是Claude 这类大模型本身有很强的单轮对话能力但一旦涉及多轮、跨会话的上下文保持很快就会把前面聊过的关键信息忘得干干净净。做个记忆层、把“长期记忆”这件事从模型能力里剥离出来自己接管就成了很多实际项目的刚需。“claude-mem”这类项目要做的事通俗讲就是给 Claude 装一个外挂大脑。模型本身只负责“理解与生成”记忆部分由外部模块来管——每次对话结束后把重要信息抽出来存好下次对话开始时再自动塞回上下文里。这个思路几乎是一切 AI 会话工具的通用解法只是不同项目在“记什么”“怎么存”“什么时候塞回去”这几个问题上的取舍完全不一样。这篇文章我会从“为什么模型记不住”“记忆管理该拆成哪几个模块”“实际跑通需要哪些代码和配置”“真实使用中会踩哪些坑”这几个维度来写把一个带记忆功能的 Claude 会话工具从需求拆分到落地实现完整过一遍。文本里的代码和配置我给的是基于常见实践的示例方案你可以当成脚手架直接改着用。1. 为什么原生对话总是“聊了就忘”模型上下文的本质限制先说一个反直觉的事实Claude 这类大模型并不是“记性差”而是它根本没有“记忆”这个模块。你看到的“记忆”其实完全来自输入上下文。每次调用接口你都要把历史对话重新完整发给它一次模型只是基于你这次给的文本做预测。所以所谓的“多轮对话记忆”本质是“把历史文本反复灌回输入框”。只要窗口够大理论上能聊很久但只要关掉会话、或者对话长度超出上下文限制前面聊的内容就从物理上消失了。我在实际项目里测过一个稍复杂的需求对话大概 20 到 30 轮之后早期讨论过的项目约束、命名规则、技术选型就会开始被模型“选择性遗忘”。这不是模型变笨了而是它真的看不全。上下文窗口是有限的前面的内容被挤出去了。这引出一个很实际的结论别指望模型自己记住要靠工程手段把“重要的事”摘出来放到模型看得到的地方。“claude-mem”这类记忆增强工具要做的事情本质上就是把“对话历史”和“长期记忆”拆成两层对话历史最近几轮的完整文本保证上下文连贯。长期记忆跨会话仍然有效的关键事实、偏好、约定以结构化形式存放每次开头自动注入。这两个层分开管理之后Claude 的每次请求都变成了“记忆摘要 最近几轮对话 当前问题”既不需要把几百轮历史全塞进去也不会丢掉关键约束。我猜“claude-mem”这个项目名大概就是“Claude memory”的组合定位很直接。下面我按自己实现类似系统时的思路把这个项目拆开讲重点放在最容易踩坑的几个决策点上。2. 记忆系统的三个核心模块抽取、存储、注入把一个“会记忆的 Claude 工具”拆开看核心就是三段流水线。搞清楚这三个模块各自解决什么问题再写代码就顺了。2.1 抽取什么信息值得被记住不是所有对话内容都值得存。真正需要长期记住的通常是这几类用户明确的偏好和约束比如“以后回复都用中文”“代码风格用 TypeScript strict mode”。项目级关键事实比如“后端端口是 8080”“部署走 Docker Compose”“数据库用 PostgreSQL”。决策记录为什么选了 A 方案而不是 B 方案避免下次重复讨论。用户的身份或背景信息比如“我是后端开发者不太熟悉前端”。抽取实现方式有很多种。我自己用的是“提示词引导分类抽取”让 Claude 阅读当前轮对话按照上面几类提取结构化摘要以 JSON 格式返回。示例提示词大概长这样从以下对话中提取值得长期记忆的信息。 只提取明确表达的内容不要推断。 输出 JSON 数组每项包含 field信息类别、content具体内容、importance1-5。 对话内容 ...这种做法好处是不需要自己写 NLP 逻辑完全借助模型的语义理解能力。坏处是每次抽取都有 token 成本所以实际使用时我不会每轮都抽而是每 3 到 5 轮、或当对话中出现明显的关键决策时再触发一次。2.2 存储用合适的载体保存“长期记忆”存储层选择直接决定了后面读取和注入的方便程度。我用过三种方案各有适用场景存储方式优点缺点适用场景JSON 文件简单零依赖直接可读可改并发写入要小心数据量大了查询慢单用户本地工具、原型验证SQLite单文件、支持结构化查询、并发安全需要一点点 SQL 基础个人工具、轻量多会话管理向量数据库支持语义检索可以找“相关记忆”部署重、需要 embedding 模型对话量大、需要模糊召回记忆的场景“claude-mem”这种工具的原始版本大概率走的是 JSON 文件或 SQLite 路线。理由很实在记忆的写入和读取频率不高数据规模撑不起上百万条用向量库属于过度设计。但存储结构上有个特别容易踩坑的地方不要按“会话 ID”存记忆要按“事实主体”存。我第一次实现时直接把整段会话摘要存成一个文件结果发现一个问题跨会话查询时根本不知道某条信息属于哪个话题。后来改成每一条记忆都带独立的 ID、类别、创建时间、最后访问时间、来源会话 ID查询和注入都灵活得多。每一条记忆的字段大概是这样{ id: mem_001, category: project_fact, content: 后端服务端口为 8080部署在 Docker Compose 的 app 服务中, importance: 4, created_at: 2025-02-10T10:00:00Z, last_accessed_at: 2025-02-11T15:30:00Z, source_conversation: conv_003 }last_accessed_at这个字段一开始我根本没加后来发现没有它就没法做“重要记忆自动衰减”高频使用的记忆会和不常用的混在一起每次都一股脑全注入上下文白白被占掉不少。2.3 注入在正确的时间把正确记忆塞回去记忆存好了不会自己用注入策略才是决定“记忆好不好用”的关键。粗暴做法是每次都把所有记忆全部注入让 Claude “全知全能”。但实测下来问题很明显token 消耗大、无关信息会干扰当前对话的专注度。比如你明明在问前端样式问题模型非要提一句“用户是后端开发者”虽然不至于出错但总有种答非所问的味道。正确的做法是分层注入全局记忆用户身份、通用偏好、核心价值观每次对话开头注入。会话相关记忆通过关键词提取和当前对话主题匹配的记忆按重要程度排序截取前 N 条。最近对话历史只保留最近 4 到 6 轮完整文本。这套“分级注入”策略最关键的地方在于构建system prompt的模板设计。模板要告诉模型哪些是记忆、哪些是当前对话、两者优先级如何。我是这样组织的你是一个有长期记忆能力的助手。以下是关于用户的长期记忆供你参考 【重要偏好】 - 用户偏好中文回复技术术语可以保留英文 - 用户是后端开发者前端代码需要更详细的注释 【项目事实】 - 项目使用 FastAPI 作为 Web 框架Python 3.11 - 认证方式为 JWT密钥存放在环境变量 JWT_SECRET 中 注意以上记忆仅作为背景信息如果与当前对话冲突以当前对话为准。 --- 最近对话 --- ... --- 当前问题 --- ...“以当前对话为准”这行字看着不起眼实际非常重要。我在测试中就遇到过如果记忆里写了一条过时的项目状态而用户在当前对话里已经明确更改了方案模型因为优先遵循记忆而把新的要求忽略了。有了这行提示模型就会把当前对话当作更高优先级的决策依据。3. 从零实现一个带记忆的 Claude 会话工具代码路径拆解说明一下以下是基于常见实践给出的示例实现方案不是某个现成项目的源码。你完全可以用这个结构去搭自己的版本也可以拿去找开源项目的对应模块。3.1 环境准备与依赖选型我用 Python 做原型因为 Claude 官方 SDK 支持好而且处理 JSON 格式的记忆数据非常顺手。需要准备的依赖pip install anthropic python-dotenv如果要做 SQLite 存储Python 标准库自带的sqlite3就够了不需要额外装 ORM。环境变量.env里配好 API KeyANTHROPIC_API_KEYsk-ant-...3.2 记忆存储模块用文件还是 SQLite我建议第一版直接用 SQLite。理由很现实JSON 文件在并发写入时容易损坏SQLite 天然支持事务而且查询语句写起来也不复杂。建表语句可以参考下面这个结构CREATE TABLE memories ( id TEXT PRIMARY KEY, category TEXT NOT NULL, content TEXT NOT NULL, importance INTEGER DEFAULT 3, created_at TEXT NOT NULL, last_accessed_at TEXT, source_conversation TEXT ); CREATE INDEX idx_memories_category ON memories(category);加索引是因为注入时要按类别过滤没有索引的话数据量大了查询会变慢。SQLite 的索引对这个小工具来说完全够用。Python 操作代码段import sqlite3 import uuid from datetime import datetime, timezone class MemoryStore: def __init__(self, db_pathmemory.db): self.db_path db_path self._init_db() def _init_db(self): with sqlite3.connect(self.db_path) as conn: conn.executescript( CREATE TABLE IF NOT EXISTS memories ( id TEXT PRIMARY KEY, category TEXT NOT NULL, content TEXT NOT NULL, importance INTEGER DEFAULT 3, created_at TEXT NOT NULL, last_accessed_at TEXT, source_conversation TEXT ); ) def add_memory(self, category, content, importance3, source_conversationNone): with sqlite3.connect(self.db_path) as conn: conn.execute( INSERT INTO memories VALUES (?, ?, ?, ?, ?, ?, ?), ( uuid.uuid4().hex, category, content, importance, datetime.now(timezone.utc).isoformat(), None, source_conversation, ) ) def get_memories_by_category(self, category, limit20): with sqlite3.connect(self.db_path) as conn: rows conn.execute( SELECT content, importance FROM memories WHERE category ? ORDER BY last_accessed_at DESC NULLS LAST, importance DESC LIMIT ?, (category, limit) ).fetchall() return rows这段代码里有个细节last_accessed_at DESC NULLS LAST的处理。第一次写入时last_accessed_at是空的如果直接用DESCNULL 会排在最前面新写入但没被用过的记忆反而不容易出现在注入列表里。这算是 SQLite 排序的一个小坑处理办法就是加NULLS LAST或者写入时就把last_accessed_at初始化为当前时间。3.3 记忆抽取与注入的调用链封装封装一个ClaudeMemoryClient把“抽取 → 存储 → 注入 → 调用模型”整个流程串起来。核心方法代码如下from anthropic import Anthropic class ClaudeMemoryClient: def __init__(self, api_key, store: MemoryStore): self.client Anthropic(api_keyapi_key) self.store store # 记录当前会话的对话列表 self.history [] def _extract_memories(self, conversation_text: str): 让 Claude 抽取值得长期记忆的信息 extract_prompt f 从以下对话中提取值得长期记忆的信息。只提取明确表达的内容不要推断。 输出严格的 JSON 数组每项包含 category、content、importance 三个字段。 category 可选值preference、project_fact、decision、user_info。 importance 取 1 到 5 的整数。 对话内容 {conversation_text} response self.client.messages.create( modelclaude-sonnet-4-20250514, max_tokens2000, messages[{role: user, content: extract_prompt}] ) text response.content[0].text # 注意这里必须做健壮性处理模型偶尔会输出 json 包裹的格式 json_text text.strip() if json_text.startswith(): json_text json_text.split(\n, 1)[1].rsplit(, 1)[0] import json return json.loads(json_text) def _build_prompt(self, user_input: str): 组装 system prompt 记忆 最近对话 # 从存储中取全局记忆和会话相关记忆 global_memories self.store.get_memories_by_category(preference, limit10) global_memories self.store.get_memories_by_category(user_info, limit10) project_memories self.store.get_memories_by_category(project_fact, limit15) decision_memories self.store.get_memories_by_category(decision, limit10) mem_block if global_memories: mem_block 【重要偏好】\n \n.join(f- {c} for c, _ in global_memories) \n\n if project_memories: mem_block 【项目事实】\n \n.join(f- {c} for c, _ in project_memories) \n\n if decision_memories: mem_block 【历史决策】\n \n.join(f- {c} for c, _ in decision_memories) \n\n system_prompt f 你是一个有长期记忆能力的助手。以下是关于用户的长期记忆供你参考 {mem_block or (暂无长期记忆)} 注意以上记忆仅作为背景信息如果与当前对话冲突以当前对话为准。 return system_prompt def chat(self, user_input: str): # 1. 检查是否需要抽取记忆每 3 轮或遇到关键决策词触发 if len(self.history) % 3 2: recent_conversation \n.join( f{msg[role]}: {msg[content]} for msg in self.history[-6:] ) try: memories self._extract_memories(recent_conversation f\nuser: {user_input}) for mem in memories: self.store.add_memory( categorymem[category], contentmem[content], importancemem[importance], source_conversationcurrent_session ) except Exception as e: # 抽取失败不影响主对话 print(f[memory extract warning] {e}) # 2. 组装消息 self.history.append({role: user, content: user_input}) messages [{role: user, content: user_input}] # 实际使用中这里把 history 转成 anthropic 的消息格式 # 3. 调用模型 response self.client.messages.create( modelclaude-sonnet-4-20250514, max_tokens4096, systemself._build_prompt(user_input), messages[{role: user, content: user_input}], ) assistant_text response.content[0].text self.history.append({role: assistant, content: assistant_text}) return assistant_text上面这段代码里有个故意留的坑messages只传了当前用户输入没传完整历史。实际使用时如果要多轮对话历史消息必须一并传进去否则模型看不到前文。我这里简化处理是为了突出记忆部分的逻辑真正落地时把self.history的最近几轮转成 API 格式传进去就行。抽取触发条件“每 3 轮抽一次”也是拍脑袋定的你完全可以根据场景调整。我后来发现更实用的触发逻辑是检测用户输入里是否包含“改成”“重新选”“我决定”“以后都用”这类信号词一旦出现立刻触发抽取因为这些词后面往往跟着长期有效的决策。3.4 记忆去重与更新的关键实现这个环节是最容易被忽略、但实际影响最大的。不加去重的话跑几天之后同一个事实会被存储成好几条相似记录注入时全是重复内容白白浪费上下文空间。我实现的一个简单去重方式是“语义相似度检查”。每次写入新记忆前先跟同类别已有记忆做个简单对比。不一定要上向量模型简单的关键词重叠就能过滤大部分重复def _is_duplicate(self, new_content: str, category: str) - bool: existing self.store.get_memories_by_category(category, limit50) new_words set(new_content.split()) for old_content, _ in existing: old_words set(old_content.split()) overlap len(new_words old_words) / max(len(new_words), len(old_words), 1) if overlap 0.6: return True return False用 0.6 这个阈值看起来粗糙但实际效果很不错。因为同一个事实的表述方式通常高度相似比如“后端端口 8080”和“我们的后端端口是 8080”分词后的重叠率会非常高。如果两条记忆说的是完全不同的话题词重叠率很难超过 0.6。当然这只能处理“近义重复”处理不了“反义更新”。用户在记忆里约定用 JWT 认证隔几天又说“以后不用 JWT 了改 OAuth”这时候关键词重叠率照样高直接判定为重复跳过写入就出大事了。所以我在写入前还会加一个“否定词检测”negation_markers [不, 别, 取消, 停止, 换掉, 不要, 改为, 改成] if any(marker in new_content for marker in negation_markers): # 将同类别、相似度高的旧记忆标记为过期而不是直接跳过 self.store.mark_outdated(category, new_content)“改为”“改成”这类词表示的是变更而非重复处理逻辑应该是“把旧记忆过期 写入新记忆”。我给memories表加了status字段来标记active/outdated注入时只查active的记录。这样既保留了决策历史又不会让过时约定干扰当前对话。4. 多会话记忆的实际效果一个完整的项目场景推演纸上谈兵太干了用一个实际的项目工作流推演一遍你就能直观看到记忆系统的价值。假设你在维护一个叫“某内部工具平台”的 Web 项目技术栈是 FastAPI Vue 3 PostgreSQL。你第一天跟 Claude 聊了后端接口设计约定了“所有接口返回格式统一为{code, data, message}”。第二天你打开新会话想继续讨论前端页面怎么对接这些接口。没有记忆系统的 Claude你需要在开头重新解释一遍接口返回格式甚至把所有接口文档重新粘贴进去。如果你的问题不够完整模型可能会给出不符合约定的对接代码。有记忆系统的 Claude系统在第二次对话开头已经注入了一条项目事实“所有接口返回格式统一为 {code, data, message}”你直接说“帮我把用户列表页的前端请求封装一下”模型输出的代码自动就有res.data.data的解包逻辑完全符合你昨天定下的约定。这就是记忆系统最核心的价值消除“重复解释成本”让每一次新会话都能站在之前的决策基础上继续走。再推演一个更复杂的场景你在 20 轮对话中不断调整某个数据处理流程中间提到了“敏感字段需要脱敏”“脱敏规则用 SHA-256 哈希”“白名单里的内部用户不脱敏”。这些关键决策会在第 3、6、9 轮等节点被抽取为独立记忆。等到你第 30 轮问“整体流程再梳理一遍”时Claude 看到的不是压缩到极限的 30 轮历史文本而是三条干净的项目事实回答质量自然更稳定。5. 真实使用中的翻车现场记忆工具最容易踩的五个坑工具写出来是一回事真正用起来是另一回事。我把自己和身边朋友使用这类记忆工具遇到的高频问题整理一遍这些问题几乎每个实现记忆层的项目都会碰到。5.1 模型把记忆当成指令执行引发“记忆幻觉”如果 system prompt 里那行“记忆仅作背景信息与当前对话冲突时以当前对话为准”被省略模型极有可能把过时记忆当成硬约束即使当前对话已经明确改了方案。我在测试时遇到过最离谱的一次记忆里存着一位用户的旧身份信息新对话里用户说“我现在是产品经理了”模型仍然按“用户是后端开发者”来调整回复的术语深度。原因就是模型先读了 system prompt 里的记忆然后把它当成了比当前对话更权威的信息。解决办法就是那行提示必须写清楚优先级。有些项目还会在记忆条目后面加来源时间和置信度比如“采集自 2025-01-15 的对话置信度 4/5”模型看到时间戳会更倾向于使用更新的信息。5.2 抽取任务污染主对话的 token 配额每次让 Claude 抽取记忆都要额外消耗一次请求的 token。如果每轮对话都触发抽取成本可能翻倍。对于 API 按 token 计费的实际使用场景来说这是真金白银的差异。我自己一开始每轮都抽跑了半天发现费用实在扛不住。后来改成“3 轮抽一次 信号词触发”成本降到原来的三分之一抽取质量并没有明显下降。还有个折中方案用更小更快的模型做抽取任务主对话用强模型这样成本还能再降一截。5.3 上下文注入顺序错了记忆全白搭模型对上下文不同位置的注意力分布并不均匀。实践中我发现长期记忆放在 system prompt 的开头比放在接近用户消息的位置效果更好。如果记忆夹在对话历史中间很容易被后面的用户问题冲淡。具体做法上我是把“身份定位 长期记忆 当前会话指令”依次排列在 system prompt 里。长期记忆不要堆太多条控制在 15 到 20 条以内。超出这个量模型执行第一条和最后一条记忆的权重差异非常明显。5.4 并发会话互相覆盖记忆一个记忆库同时给多个会话使用时如果没有会话隔离A 会话写入的记忆可能污染 B 会话的内容抽取结果。举个具体例子你在同一个库里跑了“项目 A”和“项目 B”两套对话抽取阶段模型很容易把 A 项目的技术选型当成 B 项目的事实存下来后面 B 的对话就开始胡说。解决办法是给记忆加一层 namespace 字段每个项目或每个会话组用独立的命名空间物理上分开存、分开查。最简单的实现就是 SQLite 里加一列namespace所有查询都加上这个过滤条件。我甚至建议一个项目一个库文件省心得多。5.5 记忆内容隐私问题别把敏感信息写进明文库记忆内容往往包含用户身份、项目细节、内部决策如果直接明文存在 SQLite 或 JSON 文件里一旦文件泄露或者被其他进程读取后果不太好。最少要做的是对敏感内容做加密存储或者至少把库文件权限收紧。我记得有个项目因为把数据库连接串和内部系统账号信息写进了记忆库后来这个文件被误传到公共代码仓库虽然及时发现但处理起来相当麻烦。所以抽取阶段最好就加一个敏感信息过滤规则比如正则匹配内网域名、密钥格式直接跳过不写入记忆库。6. 进阶配置给记忆工具加分的小改动基础流程跑通之后有几个改动会让工具更“聪明”属于投入小回报高的优化项。6.1 记忆重要性衰减机制前面提到每条记忆有last_accessed_at和importance两个字段。注入时不只是按重要程度排序还要结合“最近是否被使用过”做加权。一个简单有效的公式score importance * 0.7 recency_score * 0.3recency_score可以根据last_accessed_at距当前时间的天数映射到 1 到 5。规则是一周内访问过的记忆得 5 分一个月内得 3 分超过三个月得 1 分。这个机制能保证高频使用的记忆始终排在注入队列前面而那些“存了但再也没提过”的冷门记忆慢慢沉底。我在实现里还加了一个定期清理任务对超过 90 天未访问且 important 小于 3 的记忆做软删除。这样记忆库不会无限膨胀查询速度也能保持稳定。6.2 记忆导出与可视化纯文本的记忆库很难直观检查“机器到底记住了什么”。我给工具加了一个简单的导出功能把 SQLite 里的记忆按类别汇总成 Markdown 文件定期人工 review 一遍。这一步看着不起眼实际相当有用。Review 时能发现三类问题一是抽取出来的记忆明显偏离对话原意二是敏感信息混进来了三是过时决策没有正确过期。人工抽查是保证长期记忆准确性的最后一道防线完全依赖自动流程迟早会翻车。6.3 会话结束时的“总结钩子”在正常对话结束而不是强制中断时触发一次完整的记忆抽取把整个会话的决策和约定补录进库。这个操作对长会话特别有用因为会话中按 3 轮一次的节奏抽取可能漏掉最后几轮的收尾结论。实现方式也不难显式监听会话结束事件把整个历史消息拼成一段文本送给抽取模块处理。成本比中途多次抽取低效果反而更好因为模型能看到全局而不是片段。7. 把“claude-mem”落地到自己的项目我的实操建议最后给一套可以直接抄作业的落地顺序省得你从零开始排优先级。第一步先不做完整工具只写一个最小闭环Claude 单轮对话 SQLite 存储 手动注入。验证记忆读和写的基本路径通不通。第二步加上自动抽取。用固定的提示词模板让模型输出 JSON注意做好json包裹内容的清洗这是模型输出里最常见的不稳定因素。第三步优化注入策略。实现“全局记忆 相关记忆 最近对话”三层组装观察模型回复质量的变化调整各类别记忆的条数上限。第四步加上去重和过期机制。这一步不做的话工具用一星期后记忆库会变得越来越脏迟早要花大量时间清理。第五步根据实际使用情况决定要不要上向量检索。我的判断标准很简单如果你发现按关键词过滤已经无法从记忆库里找出一条特定的事实说明记忆条数已经多到需要语义检索了。在那之前关键词匹配和分类过滤足够解决问题。整个过程中最重要的心态是“记忆系统是给模型补上下文用的不是给模型当知识库用的。”不要试图把所有知识都塞进去只放那些“跨会话仍然稳定有效、且会影响后续回答”的事实。想明白这一条很多设计取舍都会变得简单。我对这类工具的未来走向也挺好奇——随着上下文窗口越来越长原生记忆能力会变强但“抽取重要信息 长期结构化存储”这个思路不太可能被完全替代毕竟窗口再大也有成本上限。如果你也在折腾类似的东西建议从最小版本跑起跑通之后再不断迭代很快就能感受到“每次新会话都记得你是谁”的体验差异。