Claude Code 源码泄露之三：记忆系统拆解与 TaoToken 接入实践

1. Claude Code 记忆系统到底解决了什么问题

Claude Code 的记忆系统，简单说就是让 AI 在多次对话之间不再“失忆”。它是一套三层结构的上下文持久化机制，适合正在用 Claude Code 做长期项目开发、又经常被“AI 忘记项目背景”折磨的开发者。你如果每次开新会话都要重新交代技术栈、目录结构、编码规范，那这套机制就是为你准备的。

我拿一个真实场景举例。假设你在开发一个 Express + TypeScript 项目，第一次对话你告诉它“我用 Express 和 TypeScript，测试用 Vitest，包管理用 pnpm”。如果没有记忆系统，五分钟后你问“我的项目用什么语言写的”，它会一脸茫然地反问你。有了记忆系统之后，它会记住“Express + TypeScript + Vitest + pnpm”这组事实，后续对话直接复用。

从泄露出来的源码结构看，Claude Code 把记忆分成了三个层次，每层的职责、存储位置、生命周期都不一样：

这个三层设计的关键在于“重要性过滤器”。不是所有对话内容都值得记住，比如你说“今天天气不错”这种话，系统会判定为低重要性直接丢弃；但你说“这个项目必须用 pnpm，不要用 npm”，它就会标记为高重要性，写入长期记忆甚至全局记忆。

核心数据结构定义在packages/core/src/memory/types.ts里，Memory接口包含id、type、content、importance（0.0 到 1.0 的重要性评分）、accessCount（访问次数）、embedding（1536 维向量，用于语义搜索）等字段。MemoryType枚举则区分了SHORT_TERM、LONG_TERM、GLOBAL、EPISODIC（情景记忆）、SEMANTIC（语义记忆）、PROCEDURAL（程序记忆）六种类型。

为什么要分这么细？因为不同类型的记忆，检索策略和淘汰策略完全不同。情景记忆记录“某天发生了什么”，语义记忆记录“某个事实是什么”，程序记忆记录“某件事怎么做”。你问“上次那个 bug 怎么修的”走的是情景记忆检索，你问“这个项目用什么框架”走的是语义记忆检索。

理解了这个分层逻辑，你就能明白为什么 Claude Code 在长会话里表现比普通对话工具稳定——它不是把所有历史都塞进上下文窗口，而是有选择地存储、检索、压缩。接下来我会拆解它的存储实现，然后给出通过 TaoToken 接入的完整配置步骤。

2. TaoToken 前置准备：统一 Key 与 API 通道

在动手拆解记忆系统的存储和检索代码之前，先把接入通道搭好。TaoToken 在这里扮演的角色是统一 API 网关——你不需要为每个模型单独申请 Key、单独配 Base URL，而是用一个 Key 走一个通道，切换模型只改 Model ID 就行。

这一步的目标很明确：拿到一个可用的 API Key，配好 Base URL，确认能正常发起请求。整个过程大概五分钟。

首先访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册账号。注册流程很标准，邮箱加密码就行，不需要额外验证步骤。登录之后进入控制台，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

在控制台里找到 API Keys 管理页面，路径是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。点击创建新 Key，系统会生成一串以sk-开头的密钥。这串 Key 只显示一次，复制下来存到安全的地方，后面配置环境变量要用。

这里有个细节要注意：TaoToken 的 API 端点统一是https://taotoken.net/api，这个地址不加任何 UTM 参数，直接作为 Base URL 使用。很多人在配置时习惯性把官网地址填进去，结果请求 404，就是因为官网和 API 端点是两个不同的地址。

拿到 Key 之后，先别急着写代码，用 curl 验证一下通道是否通畅：

export TAOTOKEN_API_KEY="sk-你的密钥" curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ | head -c 500

如果返回一个包含模型列表的 JSON，说明 Key 和通道都没问题。如果返回 401，检查 Key 是否复制完整；如果返回 404，检查 Base URL 是否写成了官网地址。

对于 Claude Code 这类编码工具，推荐使用 Coding Plan 套餐，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。这个套餐针对长会话、高频调用的场景做了优化，比按量计费更适合日常开发使用。

环境变量配置建议写进 shell 配置文件，这样每次开终端都自动生效：

# 写入 ~/.bashrc 或 ~/.zshrc echo 'export TAOTOKEN_API_KEY="sk-你的密钥"' >> ~/.zshrc echo 'export TAOTOKEN_BASE_URL="https://taotoken.net/api"' >> ~/.zshrc source ~/.zshrc

验证环境变量是否生效：

echo $TAOTOKEN_API_KEY echo $TAOTOKEN_BASE_URL

两个都输出正确值就说明前置准备完成了。接下来进入记忆系统的实际配置环节。

3. 可复制配置：记忆系统接入 TaoToken 的完整片段

这一节给出可以直接复制使用的配置文件。Claude Code 的记忆系统配置涉及三个地方：模型接入配置、记忆存储路径配置、以及 embedding 模型配置。我按文件路径逐个说明。

首先是 Claude Code 的主配置文件。在项目根目录创建.claude/settings.json，内容如下：

{ "apiProvider": { "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "model": "claude-sonnet-4-20250514" }, "memory": { "enabled": true, "shortTermCapacity": 1000, "longTermDbPath": ".claude/memory/long-term.db", "globalConfigPath": ".claude/memory/global.json", "embeddingModel": "text-embedding-3-small", "embeddingDimension": 1536, "importanceThreshold": 0.6, "compressionIntervalMs": 300000 } }

这里几个参数需要解释。baseUrl固定填https://taotoken.net/api，不要加尾部斜杠。apiKey用${TAOTOKEN_API_KEY}引用环境变量，避免把密钥硬编码进文件。model填你要用的模型 ID，这个 ID 可以从模型对话页面查询，地址是 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。

memory段里的参数对应前面拆解的三层结构。shortTermCapacity是 LRU 缓存的容量，默认 1000 条。longTermDbPath是 SQLite 数据库文件路径，建议放在项目内的.claude/memory/目录下，方便随项目一起版本管理（记得把.db文件加进.gitignore）。importanceThreshold是重要性过滤阈值，低于这个值的记忆不会写入长期存储，默认 0.6 比较合理。

如果你用的是 Claude Code 的 CLI 版本，还需要配置~/.claude/config.toml：

[api] base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" default_model = "claude-sonnet-4-20250514" [memory] enabled = true short_term_capacity = 1000 long_term_db = "~/.claude/memory/long-term.db" global_config = "~/.claude/memory/global.json" embedding_model = "text-embedding-3-small" importance_threshold = 0.6

TOML 格式和 JSON 格式的字段含义完全一致，只是写法不同。CLI 版本读 TOML，IDE 插件版本读 JSON，两个都配上就不会出错。

对于使用 Cline MCP 的场景，配置写在 MCP 的 settings 里：

{ "mcpServers": { "claude-code-memory": { "command": "npx", "args": ["-y", "@claude-code/memory-server"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}", "MEMORY_MODEL_ID": "claude-sonnet-4-20250514", "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small" } } } }

这里出现了三件套的完整写法：Base URL 是https://taotoken.net/api，Key 通过环境变量注入，Model ID 是claude-sonnet-4-20250514。三个缺一不可，少任何一个都会导致连接失败。

如果你用 Codex 并且需要配置auth.json，格式是这样的：

{ "base_url": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "model": "claude-sonnet-4-20250514", "memory": { "enabled": true, "db_path": ".codex/memory.db" } }

配置文件写完之后，先别急着跑。检查一遍：Base URL 是不是https://taotoken.net/api，Key 是不是通过环境变量引用，Model ID 是不是从模型列表里查到的有效值。这三个确认无误，再进入下一步验证。

4. 验证请求与成功结果：记忆读写实测

配置写好了，现在验证记忆系统是否真的在工作。我分三步验证：先验证 API 通道，再验证记忆写入，最后验证记忆检索。

第一步，验证 API 通道。用 curl 发一个最简单的对话请求：

curl -s https://taotoken.net/api/v1/messages \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": [ {"role": "user", "content": "回复 OK 两个字母即可"} ] }'

预期返回一个 JSON，content数组里包含text字段，值是OK。如果返回 401，说明 Key 无效；如果返回model not found，说明 Model ID 写错了，去模型列表页面核对。

第二步，验证记忆写入。启动 Claude Code 会话，输入一条明确的事实性信息：

我正在开发一个 Express 项目，使用 TypeScript，测试框架是 Vitest，包管理用 pnpm。

然后退出会话，检查 SQLite 数据库文件是否生成：

ls -la .claude/memory/ sqlite3 .claude/memory/long-term.db "SELECT id, type, content, importance FROM memories LIMIT 5;"

如果看到一条type为semantic或long_term、content包含 “Express TypeScript Vitest pnpm”、importance大于 0.6 的记录，说明记忆写入成功。

第三步，验证记忆检索。重新启动会话，直接问：

我的项目用什么语言写的？

预期回答是 “你的项目使用 TypeScript，基于 Express 框架，测试用 Vitest，包管理用 pnpm”。如果它回答 “我不确定” 或者反问，说明检索环节有问题，去排查 embedding 模型是否配置正确。

这里有个容易忽略的点：embedding 模型和对话模型是两个独立的配置。对话模型负责生成回复，embedding 模型负责把记忆内容转成向量存进数据库。如果 embedding 模型没配好，记忆能写入但检索不到，表现就是“它明明记住了但就是想不起来”。

验证 embedding 是否工作，可以直接查数据库里的向量表：

sqlite3 .claude/memory/long-term.db "SELECT COUNT(*) FROM memory_embeddings;"

如果返回 0，说明 embedding 没有生成。检查embeddingModel配置项是否填了有效的模型 ID，以及 TaoToken 通道是否支持该 embedding 模型。

完整的成功结果应该是这样的：对话请求返回正常文本，数据库里有记忆记录，向量表里有对应的 embedding，重新提问时能准确召回之前的信息。四个条件都满足，说明记忆系统接入完成。

5. 本篇常见错误排查

这一节列出实际配置过程中最容易踩的坑，每个都给出报错原文和解决方法。

报错一：401 Unauthorized

{"error":{"type":"authentication_error","message":"invalid api key"}}

原因通常是 Key 没复制完整，或者环境变量没生效。先执行echo $TAOTOKEN_API_KEY确认输出的是完整密钥。如果输出为空，说明环境变量没写进 shell 配置文件，或者写完没执行source。如果输出正常但请求还是 401，检查 Key 是否被误加了空格或换行。

报错二：local proxy failed / connection refused

Error: connect ECONNREFUSED 127.0.0.1:8080

这个报错说明请求被发到了本地代理端口，而不是 TaoToken 的 API 地址。检查配置文件里的baseUrl是否被其他工具的代理设置覆盖了。有些 IDE 插件会读取系统代理环境变量，如果HTTP_PROXY或HTTPS_PROXY指向了本地端口，请求就会走错地方。临时清掉这两个变量再试：

unset HTTP_PROXY unset HTTPS_PROXY

报错三：reading choices / unexpected response format

TypeError: Cannot read properties of undefined (reading 'choices')

这个报错说明返回的 JSON 结构不符合预期。常见原因是 Base URL 写成了官网地址https://taotoken.net而不是 API 地址https://taotoken.net/api。官网返回的是 HTML 页面，解析器拿不到choices字段就报错。把 Base URL 改成https://taotoken.net/api即可。

报错四：OAuth token expired / invalid_grant

{"error":"invalid_grant","error_description":"token expired"}

这个报错出现在使用 OAuth 认证方式的场景。TaoToken 走的是 API Key 认证，不需要 OAuth 流程。如果你在配置里同时保留了 OAuth 相关字段，删掉它们，只保留apiKey字段。

报错五：memory db locked

SqliteError: database is locked

这个报错说明多个 Claude Code 实例同时读写同一个 SQLite 文件。SQLite 默认的锁机制不支持高并发写入。解决方法有两个：一是确保同一时间只有一个实例在写记忆，二是把longTermDbPath改成每个项目独立路径，避免跨项目冲突。

报错六：embedding dimension mismatch

Error: expected 1536 dimensions, got 1024

这个报错说明 embedding 模型输出的向量维度与数据库 schema 定义的不一致。检查embeddingDimension配置项是否与embeddingModel实际输出的维度匹配。text-embedding-3-small输出 1536 维，如果你换成了其他模型，需要同步修改embeddingDimension并重建向量表。

排查顺序建议是：先确认 401 类认证问题，再确认连接地址问题，最后确认数据格式问题。大部分配置失败都集中在前两类，把 Base URL 和 Key 这两个点确认清楚，能解决八成以上的报错。

6. 长期使用建议与接入入口

记忆系统跑起来之后，有几个使用习惯能显著提升效果。

第一，重要信息用明确句式表达。比如“记住：这个项目必须用 pnpm”比“我一般用 pnpm”更容易被判定为高重要性。系统的重要性评分算法会参考用户反馈信号，明确的指令式表达权重更高。

第二，定期清理低价值记忆。SQLite 数据库会随着使用不断增长，虽然系统有压缩机制，但手动清理过期记忆能保持检索效率。可以写个定时任务，每周执行一次清理：

sqlite3 .claude/memory/long-term.db \ "DELETE FROM memories WHERE importance < 0.3 AND access_count = 0 AND created_at < datetime('now', '-30 days');"

第三，跨项目使用独立的记忆库。不同项目的技术栈和规范可能冲突，共用记忆库会导致检索到无关信息。建议每个项目用独立的longTermDbPath，全局偏好才写入global.json。

如果你还没接入 TaoToken，入口在这里：API Key 管理页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。长期做编码和 Agent 开发的话，Coding Plan 套餐 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 比按量计费更划算。

验证模型是否可用，可以直接在模型对话页面测试 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，不用写代码就能确认通道和模型 ID 是否正确。

最后说一个实际经验：记忆系统的价值不在于“记住更多”，而在于“记住对的”。我见过有人把所有对话都设成高重要性，结果检索时噪音太大，反而找不到关键信息。把重要性阈值设在 0.6 左右，只让真正重要的信息进入长期存储，检索准确率会高很多。