Claude跨会话长期记忆工具claude-mem：从安装到实战

很多用 Claude 的朋友都有过这种经历：上午刚聊完一个项目的技术选型，下午新开一个会话，又得把背景资料从零讲一遍；上次明明已经确认过偏好是“输出要克制、不要贴大段代码”，这次它又给你丢来一篇长篇大论。并不是 Claude 不够聪明，而是它的工作方式决定了每次对话都从一张白纸开始。claude-mem 想解决的，就是这个问题——给 Claude 加一层跨会话的长期记忆，让对话从“一次性的纸条”变成“越聊越懂你的老同事”。

这篇内容适合三类人：重度使用 Claude 写代码、做方案的人；需要把 AI 对话成果沉淀下来的团队；以及那些已经厌倦每次开新会话都要重新自我介绍一遍的普通用户。下面我会从设计思路、安装配置、日常操作到踩坑排查，把 claude-mem 的完整用法拆开讲一遍。

1. 为什么需要 claude-mem：先看看 Claude 的“失忆”困境

1.1 会话隔离带来的重复劳动

大语言模型的会话机制有个天然限制：上下文窗口再大，也只在“当前对话”内生效。你关掉窗口，或者新开一个会话，上一轮聊过的所有内容就全部归零。这在实际工作中非常难受。

举个我自己的例子。我负责一个中型的开源项目，经常需要让 AI 帮忙梳理 issue、写 release notes、给新模块做代码评审。每个任务都涉及相同的背景信息：项目技术栈是 Python 3.12 + FastAPI、数据库用 PostgreSQL、代码风格要求类型注解完整、测试必须跑通某个覆盖率门槛。过去我的做法是每次新开会话，都把这些背景重新打一遍，然后再补充一句话“这次的重点是 X”。

一次两次还好，时间长了你会发现，你花在“让 AI 了解背景”上的时间，可能比真正干正事的时间还多。而且人的记忆会偷懒——今天想起来要交代数据库版本，明天就漏了；明天想起来要交代分支策略，后天又忘了。模型本身没有错，它的能力边界是“上下文即时计算”，不是“跨会话回忆”。这就是 claude-mem 这类记忆层工具存在的根本原因。

1.2 记忆不是简单堆文本，而是结构化积累

有人可能会说，我把所有背景整理成一个 Markdown 文件，每次开会话先把文件丢给 Claude 不就行了？这也是一种做法，但很粗糙。

第一，文件内容会随项目演进而过期，你得手动维护；第二，把所有信息无差别塞进上下文，等于让 Claude 在长篇资料里自己找重点，既消耗你的额度，也稀释它真正应该关注的指令。claude-mem 的思路不一样：它把记忆拆成事实、偏好、任务进展、会话摘要、待办事项这几种结构化类型，按需提取、按需注入。

打一个比方：普通做法是把所有会议纪要复印一份放在桌上，让新同事自己翻；claude-mem 的做法是，每天上班前先由助理把和今天工作直接相关的要点写在白板上，其余内容留在档案柜里。同样是“有记忆”，后者的效率高得多。

1.3 它到底适合谁、不适合谁

就我实际体验来看，claude-mem 最值钱的场景有三个：

• 你在同一个项目上持续和 AI 协作超过一周，且项目背景信息经常复用。
• 你希望 AI 能记住你的输出偏好、命名风格、文档格式等“软规则”，而不是每次重复叮嘱。
• 你在带团队，想把 AI 会话中沉淀出来的结论、决策记录、遗留问题同步给同事。

反过来，如果你只是偶尔问一句常识、查一个命令参数，用完就走，那记忆层带来的收益很小，反而增加了配置成本。这种工具是给“长期协作”设计的，不是给“一次性问答”设计的。

2. 核心设计拆解：记忆从哪来、存哪里、怎么用

2.1 记忆收集层：从对话里挖出“值得记住的东西”

claude-mem 的第一个核心问题是：记忆从哪里来？答案不是让用户手动输入一条条笔记，而是从已有的对话记录中自动提取。

我在实际使用中体会最深的一点是，它提取的不是对话原文，而是经过 LLM 二次加工的结构化信息。比如我在对话里说“这个模块不要用同步 IO，全部改成异步，否则并发一上来就卡”，原始这句话充满了语气词和场景依赖，直接存进去意义不大。claude-mem 会把它抽取成一条事实：“该项目后端模块必须使用异步 IO”，并附上来源会话 ID 和时间戳。

收集层通常还会做几个关键的过滤动作：去掉寒暄和无意义内容、识别指令性语句、区分“一次性命令”和“长期规则”。比如“这次帮我把第二段改成文言文”是一次性任务，不该进记忆；“以后所有文案帮我用简体中文”是长期偏好，必须进记忆。这个区分做不好，记忆库就会变成一堆垃圾文本的堆砌，检索时什么都搜得到，什么都帮不上忙。

2.2 存储层：本地优先的 SQLite 是一个聪明的选择

收集完成之后，结构化数据需要一个存放的地方。以目前常见的 claude-mem 实现来看，默认存储格式是 SQLite 数据库，路径一般在家目录下的.claude-mem文件夹里，也可以按项目隔离。

用 SQLite 有什么好处？首先它是单文件数据库，整个记忆库就是磁盘上的一个文件，备份就是复制一个文件，迁移就是把文件拷到新机器，不需要额外部署数据库服务。其次它天然支持 SQL 查询，做时间范围过滤、按来源过滤、统计记忆总量这类操作非常简单。第三，它对个人项目和中小团队来说性能完全够用，几千条、几万条记忆的查询都是毫秒级。

在数据表设计上，常见的做法至少包含几个维度：

这种结构化的好处是，后续不仅可以用关键词搜索，还可以按主体、时间、类型做组合查询。比如“上周关于登录模块的所有偏好”，这种问题用结构化存储回答起来就非常轻松。

2.3 注入层：让 Claude 在合适的时机“想起”合适的事

存储本身没有价值，价值在于使用。claude-mem 的第三个核心机制，是把已经存好的记忆注入到下一次对话的提示词里。

注入不是把整个数据库倒进上下文，那样窗口根本装不下。它采用的是一个“检索 + 排序 + 限量”的策略。收到用户的新问题之后，首先在记忆库中做关键词相关度检索，找出可能与当前问题有关的记忆；然后按时间衰减排序，越近的记忆优先级越高；最后设置一个注入数量上限，比如最多注入 5 条记忆、总字符数不超过 1500 字，用系统提示词的格式拼接到用户消息之前。

有一点特别值得说明：Claude 原生支持在系统提示词中携带背景知识，claude-mem 正是利用了这一点，把记忆渲染成一页结构清晰的“简报”，而不是混在用户问题里。这样 Claude 区分“背景信息”和“当前需求”的成本更低，生成的答案也更精准。

2.4 为什么不直接改模型？

很多人第一次听到“让模型记住东西”时，会以为要微调或训练。claude-mem 走的是完全不同的路线：外部记忆层。它不修改模型的任何参数，只在“输入”和“输出”两侧做文章——对话结束后把信息提取出来存进数据库，对话开始前把相关记忆注入提示词。

这个设计的好处是显而易见的。第一，成本低，不需要训练机器，没有 GPU 依赖；第二，可插拔，想用随时可以用，不想用就把注入关掉；第三，记忆内容对用户完全透明，存在哪里、存了什么、怎么过滤，你都可以查、可以删，不会出现黑盒式的不确定性。

3. 安装与初始化：十分钟跑通第一段持久化记忆

3.1 环境要求与安装方式

claude-mem 的安装很简单，前提是电脑上已经有一个可用的 API 密钥，因为记忆的提取工作本身需要调用模型来完成。以当前常见的实现为例，推荐用 pipx 安装，避免污染系统级 Python 环境。

pipx install claude-mem

如果你用的是 Node 生态，也可以走 npm 的包名安装方式，两者只是安装入口不同，核心模块逻辑一致。安装完成后，先确认命令是否被正确识别：

claude-mem --version

如果提示找不到命令，多半是 pipx 的 bin 目录没有加入 PATH，把~/.local/bin加进去即可。

3.2 初始化：生成目录、配置文件和密钥绑定

安装完成后的第一步是初始化。执行：

claude-mem init

这个命令会做三件事：创建.claude-mem目录、生成默认配置文件、初始化 SQLite 数据库。初始化完成后，你需要把自己的 API 密钥写入环境变量，或者通过登录命令完成鉴权绑定。

claude-mem login

登录做完，最好先跑一次自检，确认提取、存储、检索三个环节都正常工作：

claude-mem test

这个命令会尝试向 API 发一个简单的提取请求，然后把返回结果写入一个临时记忆条目，再做一次检索验证。如果输出显示三个步骤全部通过，说明核心链路没问题。

3.3 第一次手动捕获：把手动输入变成一条记忆

初始化完成后，用一个最简单的命令体验一下“记忆从无到有”的过程。假设你在对话中产生了一个值得记住的信息，可以直接手动投喂给 claude-mem：

claude-mem capture "项目代码评审标准：必须通过 ESLint，且不允许有 any 类型出现"

命令执行完成后，可以用claude-mem query "代码评审标准"来检索。如果能看到刚才那条内容，说明存储和检索都已经跑通了。这一步虽然简单，但是非常重要——它能帮你建立一个直观的心智模型：capture 是写入口，query 是读出口，二者循环起来，就是整个记忆系统运转的雏形。

4. 核心配置与高频操作：把记忆用起来的五个动作

4.1 配置文件里应该关注哪些字段

默认配置文件的位置一般是~/.claude-mem/claude-mem.yaml。打开之后你会发现字段不算多，但有几个值得认真调。以下是我经过多轮使用后认为最关键的配置：

storage: path: ~/.claude-mem/memory.db backup_dir: ~/.claude-mem/backups injection: enabled: true max_items: 5 max_chars_per_item: 300 min_relevance: 0.35 retention: default_ttl_days: 90 auto_prune: true filters: deny_keywords: - "password" - "token" - "secret"

injection.max_items决定了一次最多注入几条记忆。这个值不宜设得太大，因为背景信息过多反而会干扰 Claude 对当前指令的专注度。我试过 10 条和 5 条的对比，5 条在大多数场景下效果更好。retention.default_ttl_days控制记忆的默认过期时间，90 天适合项目开发，如果你在做知识管理类的事情，可以改成 365。

filters.deny_keywords是一个很实用的安全功能：匹配到关键词的记忆条目不会被注入，也不会被查询返回。比如你把“password”“token”加进去，这些敏感内容就从记忆的出口被挡住了。

4.2 高频命令速查表

日常使用中最常碰到的命令其实就是下面这张表，建议存一份：

这些命令分开来看都很简单，但组合起来能构建出完整的工作流。比如一个标准动作是：开始任务前session start，任务过程中边聊边干，结束后session end，它会自动把这一轮对话里的关键决策、产出物、遗留问题全部提取进记忆库，第二天新开会话直接query "昨天的结论"就能无缝接上。

4.3 实操：一个完整的“今日接昨日”闭环

我不喜欢讲空洞的概念，直接用一个具体的场景说明。假设昨天我在和 Claude 讨论一个支付模块的退款流程，中间确认了一条规则：“退款必须走异步任务，不能阻塞主流程”。

昨天的操作是这样的：

claude-mem session start # 然后正常和 Claude 对话，讨论各种边界情况 claude-mem session end

session end 之后，claude-mem 会把这一轮对话里的规则自动提取出来。今天早上我新开一个会话，要开始写退款回调的代码，不需要重新描述任何背景，只需要跑：

claude-mem query "退款 异步规则"

这时 claude-mem 会把那条记忆连同其他相关记忆注入到系统提示词里。接着我正常向 Claude 提问“帮我写退款回调的伪代码”，它给出的方案会直接遵守“异步、不阻塞主流程”这个约束，而不需要我再重复一遍。

实际用下来，这种“结束即沉淀、开始即唤醒”的节奏，是 claude-mem 最舒服的打开方式。

5. 把 claude-mem 嵌进日常工作流：从个人到团队

5.1 和 Claude Code 配合：让每一个本地会话都自带记忆

如果你和我一样，日常主力是 Claude 的命令行工具或 Claude Code，那 claude-mem 还能更进一步——它可以把整个会话过程作为记忆提取的原料。

具体做法是在 shell 的 rc 文件里加一个包装函数。原始命令不能覆盖，但可以定义一个别名，让每次调用会话命令时自动带上记忆上下文。大致思路是：

alias claude="claude-mem inject -- claude"

这个别名会在你启动 Claude 之前先执行一次记忆检索，把相关背景注入到本次会话的起始提示词里。当然这个方案不一定适合每个人的使用习惯，但对长期在同一项目下跨会话工作的场景，它节省的时间非常可观。

另外一个更推荐的做法是，给claude-mem session end绑定一个 hook，让它在每次对话结束时自动执行。这样你不需要刻意去记“要收尾了”，会话结束的瞬间记忆提取已经悄悄完成。

5.2 团队场景怎么做共享记忆

个人使用只需要本地 SQLite，但团队协作天然需要共享。常见的做法是把.claude-mem/memory.db抽象成一个同步文件，纳入团队的代码仓库。每次有新的记忆写入，就提交一次变更；其他人拉取最新代码时，也就同步了最新的记忆库。

但这里有一个坑：多人同时写入同一个 SQLite 文件，合并冲突会非常痛苦。我一开始天真地把整库放进了 git，结果同事改了一条记忆，我在另一边改了三条，合并时直接把库弄坏了。后来换成一个更稳的做法：不直接共享数据库文件，而是约定每人把自己的记忆以 JSON 格式导出到memories/目录下，按日期命名文件，再通过claude-mem import导入。

claude-mem export --since 2025-06-01 --format json > memories/2025-06-01.json claude-mem import memories/2025-06-01.json

这个方案用下来，核心体验就一句话：数据库是私有的，记忆的“原材料”是共享的。每个人可以自由裁剪哪些记忆要进自己的库，不会因为同步冲突丢掉数据。

5.3 记忆的维护：不清理的记忆迟早变成负担

记忆库和现实中的笔记本一样，只进不出就会逐渐失控。我发现最有效的维护节奏是每周做一次轻量整理，每月做一次批量清理。

周整理的动作包括：翻一遍本周新增的 preference 类型记忆，看有没有已经失效的规则；把临时任务的 progress 记忆迁移到“已完成任务”里。月清理则主要是执行prune，把超过有效期的记忆批量删除，并且用 VACUUM 压缩一下数据库文件。

如果你用的是 Claude Code 这类自动化工具，还可以写一个定时脚本，每天凌晨自动执行记忆归档。归档不是删除，而是把 30 天前的高频记忆摘要化，只保留结论不保留过程，这对控制记忆库的体积很有帮助。

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

6.1 为什么新会话里没有注入任何记忆

这个问题我见过最多。明明昨天存了好几条记忆，今天开新会话却像失忆一样。排查顺序如下。

第一，确认注入开关没有关掉。检查配置里的injection.enabled是否为 true。第二，确认本次会话和昨天的记忆存在相关性。claude-mem 的检索是基于相关度的，如果你问的是完全无关的话题，它不会硬塞几条旧记忆进来，这其实是设计上的优点。第三，查看日志。

claude-mem debug --tail 50

如果日志里显示 query 执行成功但返回 0 条结果，说明检索条件太严格；如果显示 “injection skipped”，说明相关度没有达到阈值。把injection.min_relevance从 0.35 调低到 0.25，通常就有改善了。

6.2 记忆注入后挤占了太多上下文预算怎么办

Claude 的上下文窗口虽然大，但也不是无限大。如果你发现加了记忆之后，模型反而开始“啰嗦”或者跑偏，大概率是注入内容过多了。这时候优先调max_items和max_chars_per_item两个参数。

我个人的建议是，把单条记忆的字数上限压到 150 字以内，注入条数控制在 3 到 5 条。记忆不是作文，它只需要保留最核心的约束和结论，细节应该放在用户消息里，而不是塞进背景简报。如果你的记忆内容普遍超过 300 字，说明提取阶段的摘要没做好，可以考虑在捕获前先让模型对原始内容做一层压缩。

6.3 如何防止敏感信息被记住、被注入

这是一个非常实际的问题。默认情况下 claude-mem 会提取对话中的所有结构化信息，包括一些你未必想留下的内容。虽然它把数据库放在本地，但你也不能保证每台机器都绝对安全。

我的习惯是两道防线同时用。第一道在配置层：把deny_keywords配上password、token、secret、private key这些词，确保包含这些关键词的记忆不会被提取也不会被注入。第二道在操作层：真正敏感的内容，我根本不会在开启记忆捕获的会话里讨论，宁可在普通会话里聊完，再手动选择哪些结论值得入库。

还需要说明的是，claude-mem 的记忆提取过程本身会调用模型接口，也就是说你的会话摘要在提取阶段会被发送到模型服务端。如果你对私密性要求极高，建议用本地部署的模型来做提取，或者干脆关闭自动提取，全部走手动 capture。

6.4 数据库体积膨胀和检索性能变慢怎么办

跑久了之后，SQLite 文件膨胀到几百 MB 并不奇怪，毕竟里面存了大量会话快照和过程记录。性能下降通常发生在全表扫描的时候，因为记忆条目多了之后，没有有效索引的模糊查询会变慢。

先做减法，再做优化。减法就是prune --before 某个日期，把过期数据删掉一批。然后执行 SQLite 的 VACUUM，重组数据库文件，回收空洞空间。优化层面，确认表上有没有建立时间戳和主体字段的索引：

CREATE INDEX IF NOT EXISTS idx_memories_timestamp ON memories(timestamp); CREATE INDEX IF NOT EXISTS idx_memories_entity ON memories(entity);

这两个索引建完之后，按时间和主体做范围过滤的速度会有数量级的提升。如果还是慢，还有一个偷懒但有效的办法：按月归档，每月一个独立的库文件，查询只在当前月份的库上执行，旧的库留作存档。

6.5 记忆内容出现了事实性错误怎么办

AI 提取记忆的过程中，偶尔会出错。比如把“不要用 Redis 做消息队列”记成了“用 Redis 做消息队列”，这种错误一旦进入记忆库，会在后续所有会话里持续误导模型，危害比“没有记忆”大得多。

所以我的建议是：不要让任何记忆“永久生效”。给每条记忆设定有效期，定期 Review 高频记忆。发现错误的时候不要犹豫，直接用claude-mem delete --id xxx删除错误条目，再手动 capture 一条正确的。如果错误条目已经被多次注入到历史会话，不需要去翻旧账，只要新会话不再注入它，影响自然就会消失。

我个人在实际操作中的体会是：claude-mem 最值得投入精力的地方，不在于把工具本身调到多完美，而在于建立一套“持续沉淀 + 定期核查”的习惯。工具只是给了你一档案柜，能不能变成有价值的知识资产，取决于你愿不愿意每次关掉对话之前多想一句：“这一轮有什么值得留下的？”

最后再分享一个小技巧。我后来几乎不再靠手动 capture 来记录规则了，而是直接在对话里告诉 Claude 一句话：“这条结论对后续工作很重要，请按 JSON 格式输出成一条记忆草稿。”然后把模型输出的 JSON 用claude-mem import导入。这个方法比我自己敲总结要准确得多，而且省掉了二次思考的时间。这个内容后续还可以这样扩展：把记忆库接上定时导出，配合周报生成、项目复盘这些场景，你会发现 AI 协作的积累效应，比想象中大得多。