为Claude Code打造持久记忆：SQLite与语义检索的本地记忆库实践

1. 没有记忆的Claude会话，正在逼你做无效劳动

1.1 每次冷启动，都是同一件事的重复劳动

如果你用过Claude Code这类跑在终端里的AI编程工具，大概率经历过下面这个场景：昨天还在跟Claude讨论某个服务的表结构设计，聊到一半决定换个思路，今天打开终端想继续推进，结果它完全不记得你是谁、我们在做哪个项目、之前决定过什么。你只能重新粘贴一遍项目背景，再把昨天没聊完的要点逐条复述。这件事，我在过去几个月里反复做了几十次，直到我意识到问题的本质不是"Claude不够聪明"，而是"会话本身就是无状态的"。

大模型的API默认是无状态设计，每一个请求都是独立的，服务器端不会自动保留上一次对话的内容。会话连续性其实是客户端帮你做的——Claude Code把当前对话的所有消息一股脑拼进上下文窗口，才让你感觉"它记得我刚刚说了什么"。一旦会话结束，上下文就被丢弃。更麻烦的是，终端崩溃、切换目录、超过上下文窗口长度，这些情况都会让"记忆"断档。于是我们被迫做大量的复制粘贴，把上个会话的结论搬进下个会话的开场白，既容易遗漏细节，又浪费宝贵的上下文配额。

claude-mem这个工具，就是为了治愈这种冷启动疲劳而出现的。它做的事情听起来很简单，但实现起来涉及不少细节：自动捕获Claude会话的输出，把对话内容存到本地SQLite数据库里，再通过语义检索在任意新会话中把相关记忆重新找回来，以只读上下文的形式注入给Claude。它让AI对话从"每次重启都失忆"，变成了"有一定长期记忆能力的协作伙伴"。

1.2 claude-mem想解决的，不只是"保存历史"这么简单

很多人第一次看到这种记忆工具，会觉得"这不就是聊天记录存档吗"。实际用下来你会发现，差的远。

存档只是把数据写进硬盘，但记忆的核心是"在正确的时候想起正确的事"。claude-mem做了三层工作：

• 捕获层：通过Claude Code的钩子（Hook）机制，在会话开始、用户提交消息、会话结束等节点自动记录对话，也可以手动用斜杠指令按需保存。
• 存储层：把消息、会话ID、文件路径、时间戳落在本地SQLite数据库，并对每条内容生成一个向量嵌入（Embedding），为后面的语义检索做准备。
• 检索层：新会话启动时，通过指令或钩子触发，对记忆库做语义搜索，召回与当前问题相关的历史片段，作为系统提示或上下文块注入到新会话中，让Claude"带着记忆回来"。

它还支持基于时间的回溯，比如"把昨天下午讨论的部署方案调出来"，以及基于关键词与语义混合的搜索。换句话说，它解决的痛点是"我记得我们聊过，但我找不到当时是怎么决定的了"。

如果你是重度使用Claude Code做项目开发、技术调研或者维护多线任务的用户，这类工具的价值会随着使用时间增长越来越明显。头几天感觉不到，等知识库积累起来，你会发现自己开新会话的启动成本明显下降。

2. claude-mem的架构：一条从终端输出到SQLite的完整链路

2.1 核心数据流：捕获、清洗、嵌入、存储、检索、回填

我习惯把记忆系统理解成一条流水线，六个环节串起来：

1. 捕获：钩子监听会话事件。Claude Code的Hook机制支持在特定事件触发时执行外部命令，claude-mem挂在这些事件上，把终端里流过的用户消息和AI响应捕捉下来。官方还支持通过编辑器或shell命令触发手动保存。
2. 清洗：原始终端输出里混着命令回显、状态行、代码块标记，不能直接全量入库。清洗阶段会按会话边界切割内容，识别哪条是用户输入，哪条是AI回复，剥离没有意义的控制字符，只保留有信息量的文本。
3. 嵌入：对清洗后的文本调用本地嵌入模型（比如通过Ollama运行的nomic-embed-text），生成固定维度的向量。这个向量是后面语义检索的"指纹"。
4. 存储：文本和向量一起写入SQLite。文本用于最终展示，向量以BLOB格式存储。
5. 检索：新会话触发检索时，先对当前问题做同样的嵌入，然后在库中做余弦相似度排序，取Top-K条最相关的记忆。
6. 回填：把召回的记忆按固定格式注入到新会话的上下文里，让Claude在回答问题前先"看到"这些历史片段。

整个链路里，我最想强调捕获和清洗这两个环节。很多人以为记忆工具准不准取决于模型，但实际经验告诉我：垃圾进，垃圾出。如果捕获时夹杂了大量命令回显和无关输出，后面检索出来的内容同样充满噪音。claude-mem早期版本在Windows终端下经常捕获到乱码，原因就是清洗环节没有处理好ANSI转义序列，后来加了剥离逻辑才稳定。

2.2 为什么是SQLite：一个"恰到好处"的存储选型

如果你自己造轮子，第一个选择就是"记忆到底存哪"。我见过有人直接存JSON文件，也见过非得上PostgreSQL的。这两种我都试过，最终都回到了SQLite。

JSON文件的问题在于：每做一次检索都要把整个文件加载到内存里做过滤，记忆条目到几千条以后，启动速度和检索速度就会肉眼可见地变慢。更别提多个会话同时在写同一个JSON文件时的并发冲突问题，不加锁就会丢数据。PostgreSQL呢？功能确实强，但对一个本地CLI工具来说太沉重了——你得装服务端、配连接、管权限，换一台机器还要搬数据。个人开发者的随身工具，经不起这样的运维成本。

SQLite正好卡在中间：零配置、单文件、支持事务和并发读、内置FTS全文索引，还有一个被低估的优点——单文件意味着记忆库可以直接备份和迁移。我通常把整个数据库文件丢进同步盘或者带上出差，到了新环境初始化一下就能接着用。另外SQLite有一个WAL模式，在并发写多的情况下表现更好，claude-mem会在初始化时默认启用，这个细节在长时间运行时能避免很多"database is locked"的烦恼。

2.3 嵌入模型的选择：把"语义相近"变成"向量相近"

记忆检索如果只靠关键词匹配，会有一个很尴尬的体验：你记得当时聊的是"接口返回结构"，但库里存储的原文写的是"API response schema"，关键词完全匹配不上。这时候就需要嵌入模型把两段语义相近但字面不同的文本映射到向量空间里的相邻区域。

嵌入模型的选择直接影响检索质量，而且没有银弹。下面是我实测过的几个方案的对比：

在本地跑的话，我目前固定用nomic-embed-text。原因很朴素：它对开发者日常对话里的中英文混排、代码片段和术语的语义理解都够用，模型体积不算大，CPU推理一条消息大约零点几秒，不会拖垮操作体验。如果你的文本以长篇技术文档为主，可以试试snowflake-arctic-embed，它在这个维度上比nomic更有优势。

3. 安装与配置：把记忆装进Claude Code全流程

3.1 环境准备与安装命令

开始之前，你需要满足几个前置条件：

• Python 3.10 或更高版本
• Claude Code 已安装并正常使用（当前主流版本支持Hook机制）
• 本地嵌入推理服务，我是用Ollama跑nomic-embed-text，如果你不想折腾本地模型，也可以在配置里指向OpenAI兼容接口
• 一个终端环境，macOS/Linux为主，Windows用WSL会少碰很多坑

安装很简单：

pip install claude-mem

接着把本地嵌入模型拉下来：

ollama pull nomic-embed-text

然后初始化：

claude-mem init

这一步会在你的用户目录创建~/.claude-mem/文件夹，生成默认配置文件和SQLite数据库。

3.2 钩子配置：决定记忆覆盖率的关键

claude-mem能不能帮你完整记录会话，关键在钩子配得全不全。只配一个"会话结束"钩子是远远不够的——如果会话中途崩了或终端直接关闭，结束事件可能根本没机会触发。

我建议至少配置三类钩子：

• SessionStart：会话开始时自动注入前一天或最近24小时的记忆，新会话起步就有上下文。
• UserPromptSubmit：每次用户提交消息时，触发一次记忆捕获，确保关键输入不遗漏。
• Stop：每次Claude输出结束时，捕获AI响应。

实际的配置方式是在Claude Code的配置文件里挂载外部命令，大致逻辑如下（以各版本实际Hook配置为准）：

{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "claude-mem gather --since 24h" } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "claude-mem capture --source prompt" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "claude-mem capture --source response" } ] } ] } }

注意：不同版本的Claude Code钩子API字段可能有差异，以你当前版本的官方文档为准。配置完记得用claude-mem doctor或者直接跑一个测试会话，确认钩子真的被触发了。

我踩过一个坑：只配置了Stop钩子，结果Chat的长回复还没写完终端就刷新了，记忆里存了半截回答。后来改成每次用户提交消息和AI输出完成时都捕获，覆盖率才算稳定在95%以上。

3.3 首次运行验证：一个可复用的验收脚本

配置完成后，不要直接进入项目开工，先花五分钟跑一个验证流程：

1. 新建一个Claude Code会话
2. 故意聊一段特征明显的技术内容，比如"我们决定用PostgreSQL替代MySQL，因为需要更复杂的JSON查询能力"
3. 结束会话
4. 再开一个新会话，执行:

claude-mem search "为什么换数据库"

如果返回结果里包含刚才那句关于PostgreSQL的内容，说明捕获、嵌入、存储、检索整条链路都是通的。如果结果漂移或者搜不到，先检查两个地方：Ollama服务是否在运行、模型名是否和配置一致。我遇到过的绝大多数首跑失败，都是因为Ollama没启动，或者配置里模型名写成了小写下划线格式，和实际模型名对不上。

4. 会话内实操：三个最常用的记忆召回姿势

4.1 斜杠指令 /memory：手动存档的黄金准则

自动捕获能帮你记录大部分内容，但自动捕获是"漫无目的"的——它把一切都保存下来，并不知道哪些信息值得长期记住。所以我很强调手动存档的习惯。

在Claude Code会话中直接输入/memory，claude-mem会把当前对话节点保存到记忆库，并自动带上相关的文件上下文和依赖信息。我实际操作时的节奏是：每完成一个里程碑（比如跑通一个接口、修复一个故障、确定一个技术选型），立刻执行一次/memory。这相当于给记忆打了一个"重点标记"。

这样做的结果就是，当你过两周回来搜索时，召回的前几条往往是这些手动标记过的重要片段，而不是流水账式的闲聊。

4.2 基于日期和范围的召回：让检索贴近时间线

语义搜索好用，但它有一个盲区：它不分时间前后。你问"部署方案"，它可能把三个月前和三天前的部署讨论一起召回，而你现在只想关注最近的决策。

claude-mem支持基于时间范围的过滤，这个功能对实际项目非常关键：

claude-mem search "部署方案" --from "2025-01-01" --to "2025-01-07"

在会话里也可以直接通过自然语言触发，比如问"我们上周五关于容器内存限制的结论是什么"——检索层会解析时间表达并过滤记忆库。我个人的经验是：时间过滤和语义搜索搭配使用，召回准确率能提升一个档次。因为开发工作的技术栈和关注点是随时变的，今天讨论的问题和三个月前大概率不相关，不加时间约束的Top-K召回很容易被旧记忆带偏。

4.3 上下文注入的取舍：Top-K与阈值的关系

记忆召回不是"越多越好"。每条召回记忆都会占用新会话的上下文Token，注入过多无用记忆反而会干扰Claude对当前问题的判断。

claude-mem默认使用Top-K检索，也就是对记忆库里的全部条目按相似度排序，取前K条。K值默认是5，但我用下来的感受是：

• 简单任务，K=3就够，减少噪音
• 复杂重构任务，可以适当调到8-10，让Claude看到更多背景
• 相似度阈值也很重要——如果召回条目的相似度低于阈值（比如0.4），说明它根本不相关，宁可少注入

我自己的经验配置：K=5，阈值设0.5。如果某一次搜索感觉相关记忆没被召回，先降低阈值看看是不是有边缘相关的内容被过滤了；如果召回内容太杂，再提高阈值。这个调节过程需要结合具体项目反复试。

5. 存储层拆解：表结构、手工查库与Top-K逻辑里的坑

5.1 记忆库表结构不是拍脑袋定的

如果只看CLI的交互，你可能觉得claude-mem就是个黑盒。但记忆类工具最值得研究的恰恰是存储层，因为存储设计决定了检索上限。

核心表大致可以这么理解：

• sessions：记录一次会话的起止时间、会话标题、关联项目路径
• messages：记录会话中的原始消息，包括角色（用户/AI）、内容、时间戳
• memory_entries：经过清洗和向量化的记忆条目，这是检索的主表，包含原始文本和嵌入向量
• file_snapshots：记录会话中涉及的文件快照，包括文件路径和内容哈希，方便在召回记忆时顺带定位到具体文件

设计上有一个细节值得学习：memory_entries把原始文本和嵌入向量分开存。文本是为了最后展示给模型看，向量是为了快速相似度排序。如果把向量嵌入到文本字段里，每次排序都要重新解析序列化数据，性能会差很多。

5.2 手工查库的成功率调试法

当检索结果不理想时，我第一个动作不是调参数，而是直接进数据库看原始数据：

sqlite3 ~/.claude-mem/memories.db \ "SELECT id, role, content, created_at FROM messages ORDER BY created_at DESC LIMIT 20;"

这一步能区分问题到底出在哪层：

• 如果库里根本没有那条应该存在的记忆，说明捕获钩子没触发，或者触发时机太晚，得回去检查配置。
• 如果库里有原文，但搜索搜不到，问题出在嵌入或检索逻辑。
• 如果搜到了但排名靠后，说明语义相似度计算有问题，可能要考虑换个嵌入模型，或者引入关键词加权。

我遇到过最典型的情况是：记忆库里有大量重复内容。原因是Stop钩子和用户手动/memory对同一条消息各存了一次，导致向量检索在相同语义上被重复条目"刷屏"，后面的不同信息被挤出了Top-K。解决办法是定期去重——按内容哈希清理重复条目，我在脚本里加了claude-mem dedupe的定期任务，这个习惯大幅提升了召回多样性。

5.3 余弦相似度的真相：短查询的长尾问题

记忆检索最核心的计算是余弦相似度：把两个文本映射到向量空间后，计算它们夹角之间的余弦值。语义越接近，夹角越小，余弦值越接近1。这个数学过程很漂亮，但实际使用有一个必须承认的缺陷：短查询和长记忆之间存在"长度偏差"。

一条用户的提问可能只有十几个字，而一条记忆可能是几百字的完整对话片段。短文本的向量信息量不足，和长文本计算余弦相似度时，经常出现"在主要方向上已经不同，但由于短向量的方向被稀释，分数仍然偏高"的情况。通俗地说，就是一句很短的问题可能错误匹配到很多语义边界模糊的长段落。

我应对这个问题的办法是"查询扩展"：在检索前，把一句话的query拆成几个同义问法，分别嵌入后取平均向量。虽然不能完全消除偏差，但能把偶发的误召回压低不少。另外一个辅助手段是引入BM25关键词匹配作为加权项，让字面重合度在最终排序里占一个次要但稳定的比例。

6. 资源与性能实测：嵌入延迟、库体积和内存占用

6.1 嵌入成本：一次对话到底要花多少时间

记忆工具的最大潜在风险不是存储空间，而是实时性。如果每次用户提交消息后都要等待嵌入计算完成才继续对话，体验会非常糟糕。

我在本地用Ollama跑nomic-embed-text做过一次粗测：

• 一个持续30分钟的开发会话，约产生120条消息
• 全部嵌入计算总计耗时约1分20秒，平均每条0.6秒左右
• 在低负载情况下，这个延迟基本不可感知，因为claude-mem把嵌入过程做成了异步任务，不阻塞对话主流程
• 但如果你的CPU比较老，同时开着浏览器、编辑器、容器，嵌入任务会明显拖慢终端响应

如果觉得0.6秒的延迟太长，可以考虑切换Ollama的嵌入请求为批量方式，隔一段时间集中处理一批消息，而不是实时逐条嵌入。代价是"刚刚的对话"在几分钟内还搜不到，但我实测下来影响不大——你通常不会在对话刚结束的下一秒就需要回忆它。

6.2 体积控制与SQLite文件维护

记忆库的纯文本部分增长很慢，一条普通消息几百字，积累几千条也才几MB。真正的体积增长来自向量数据。

以nomic-embed-text为例，每条768维向量用浮点数组存储大约需要3KB。算一笔账：

• 1万条记忆 ≈ 30MB向量数据
• 5万条记忆 ≈ 150MB向量数据

单看这个数字还能接受，但SQLite文件在持续追加和删除后会产生碎片和未回收页面，文件会虚胖。我实测一个积累了两个月的库，跑完VACUUM之后体积压缩了35%左右。建议每个月执行一次：

claude-mem vacuum

或者手动：

sqlite3 ~/.claude-mem/memories.db "VACUUM;"

6.3 记忆保质期：不是存得越久越好

很多人的直觉是"记忆越多，AI越懂我"。但实际经验恰恰相反：记忆库也有"熵增"问题。时间越久，过期信息越多，旧的技术决策可能已经随着需求变更而失效，旧的项目结构可能已经重写。如果你不控制记忆的时效性，检索时这些"僵尸记忆"会不断干扰新决策。

我采用的做法是分级管理：

• 90天以内的记忆：完整保留，正常参与检索
• 90天到180天：只保留摘要，不再保留完整对话
• 超过180天：除非手动标记为"长期重要"，否则清理

有些记忆工具支持时间衰减权重，也就是在计算相似度分数时乘一个时间衰减系数，让旧记忆天然排在后面。如果你在用claude-mem，可以在检索时加上时间过滤条件，把超过一个季度的内容排除掉。对于真的需要长期追踪的核心项目，单独建一个项目级记忆库，不受全局清理策略影响。

7. 把这套记忆流融入日常工作后的几点心得

7.1 记忆管理要变成习惯，不只是工具功能

工具再聪明，如果你不用，它也帮不上忙。我最初用claude-mem的半个月，完全依赖自动捕获，结果发现真正该记住的决策点，自动捕获经常认为是"常规对话"而没有额外标注。后来我强制自己在三个节点执行手动存档：思路定稿时、问题修复时、切换任务前。这三类时刻产生的记忆，在后续检索中价值最高。

我还习惯在新会话第一句就问"我们之前做到哪了"。这一步会触发claude-mem的记忆注入，让我快速回到上一个工作状态，省去重新读代码、翻历史的时间。看起来只是一句话，实际上等于给AI做了一个"状态恢复"。

7.2 多项目隔离：一个项目一个记忆库

如果你同时维护多个项目，共用一个记忆库会带来严重的检索污染。做前端项目的记忆，很可能被后端项目的术语干扰；更别说两个项目里都讨论过"用户登录"，召回结果就会混杂。

我的方案是项目级隔离：每个项目初始化独立的存储路径，在配置里指定当前项目对应的数据库文件。这样做的直接收益是，召回结果的相关性显著提升。付出的代价是，跨项目的经验复用变难了——但说实话，跨项目复用AI记忆的需求远没有我预想中高，多数项目的上下文都是独特的。

7.3 数据安全与清理：本地记忆不等于绝对安全

最后说一个很多人忽略的点：本地存储不等于绝对安全。

claude-mem把数据放在~/.claude-mem/memories.db，默认SQLite文件没有加密。如果你在记忆库里存了生产环境的库连接串、第三方API密钥、客户信息，这些内容就以明文形式躺在磁盘上。我对自己的要求是：

• 任何敏感信息绝不写进会被AI记忆的对话里
• 本地目录权限至少要限制为当前用户可读写
• 定期用脚本导出记忆内容做人工检查，看有没有误存了不该存的信息
• 备份记忆库时，先对文件做加密后再上传同步盘

记忆工具的便利性来自于"它替你记住了所有细节"，这既是优点也是风险。享受便利的同时，必然要对数据边界保持清醒。我现在把claude-mem当作一个"有记忆的同事"来用，它帮我省掉了很多重复劳动，也让我对自己在AI协作中的工作脉络有了更清晰的记录。它不是一个花哨的功能玩具，而是那种用了三个月之后，你已经想不起没有它时工作是怎么运转的基础设施。如果你也面临AI会话反复冷启动的低效，这套方案值得你花一个下午装起来跑一跑。