1. 当 Claude Code 反复读同一批文档Token 真正的去向如果你用 Claude Code 做中大型项目大概率见过这样的场景项目里有十几份设计说明、接口约定、踩坑记录CLAUDE.md里写不下于是你每次开新会话都手动一遍或者让模型Read一整个目录。会话跑通了但输入 token 的曲线非常难看——模型第 3 轮还在读第 1 轮已经读过的东西第 10 轮开始你甚至不确定它到底记住了哪一份。这不是模型变笨了是上下文里塞了大量和当前问题无关、但被整份粘贴进来的正文。要解决这个问题除了控制你自己的检索习惯还需要一层专门的记忆运行时。本文围绕开源项目 agent-memory 的「路径检索」路线展开同时把 Claude Code 的模型调用链路切到 TaoToken 上跑一遍完整可复现流程。开始之前先把入口放出来可以用浏览器打开 TaoToken 官网 完成注册然后在控制台申请一个用于 Claude Code 的 API KeyBase URL 统一填https://taotoken.net/api。下面的配置、对照实验和排障清单都建立在Key 已到手、Base URL 已明确这两个前提上。需要先讲清楚一件事本文里所有关于 token 消耗的讨论消耗主体都是Claude Code 这一侧的模型调用。agent-memory 本身是本地运行时索引和检索不产生云端调用真正把 token 烧掉的是 Claude Code 把哪些内容塞进了发给模型的请求体。所以「省 Token」这件事一半靠记忆层少喂正文一半靠推理入口本身可观测、可换模型。2. agent-memory 的关键取舍返回路径而不是返回正文业界做 AI 长期记忆主流做法是向量库 语义检索把记忆切片、embedding、存库召回时把命中片段整段拼进上下文。这条路能跑通但有两个副作用——召回内容长度不可控以及数据形态是个黑盒出了偏差不好定位。agent-memory 选了一条更工程化的路子它的核心设计有四点第一Markdown 文件是唯一事实来源。所有记忆以普通.md文件落地可以被编辑器直接打开、被 git 追踪、被 diff 审查。旁边那个 SQLite 索引只承担加速角色删掉之后重建即可不会丢数据。这一点对团队协作尤其重要记忆不再藏在某个二进制文件里代码评审的那套流程可以直接搬过来。第二检索的返回值是路径不是正文。这是与向量召回最大的分歧点。它给你的 agent 是一组排序后的文件路径外加极短摘要agent 判断这条和当前任务相关才会去打开对应文件、读取那段内容。用到多深读多深不相关的不读。省下来的 token 全部来自这里。第三写入发生在会话边界不依赖模型自觉。让模型记得把学到的东西写下来是不可靠的它经常忘。agent-memory 选择在会话结束这类边界点自动触发写入再配合一个异步的整合过程做价值筛选——高价值的保留、低价值的淘汰。第四local-first零第三方 API Key。记忆数据全部留在本地不需要外部服务参与这既是隐私考虑也顺带砍掉了 embedding 调用带来的额外成本与延迟。值得强调的是这套机制不绑定某一家 CLI。任何能执行 shell 命令的 agent 都能读写它所以 Claude Code 和 Codex CLI 可以共用同一个记忆目录——你在 Claude Code 里踩过的坑切到 Codex CLI 依然能检索到。3. 接入前的第一步在 TaoToken 拿到 Claude Code 用的 Key 和 Base URLClaude Code 默认把请求发往 Anthropic 官方端点。要把它切到可控的入口需要三样东西Base URL、API Key、模型标识。第一步是拿到 Key打开 TaoToken 官网完成账号注册与登录进入控制台创建 API Key。建议给这个 Key 起一个可识别的名字例如claude-code-local-memory方便后续在用量面板里区分项目把 Key 存到本地环境变量或密钥管理工具里不要直接写进会被提交到 git 的配置文件记录 Base URLhttps://taotoken.net/api。Key 创建页的直达地址是 API Keys 控制台创建完成后先别关页面后面配置 Claude Code 会立刻用到。至于具体用哪个模型跑记忆检索场景可以在 模型对话 里先手动试几个观察同一段记忆路径列表在不同模型下的引用准确率再决定长期用哪个。一个容易忽略的点Base URL 不要写成https://taotoken.net/api/v1或者带斜杠结尾的形式。Claude Code 会自行拼接路径多写一段前缀往往表现为 404而不是参数错误排查时容易被带偏。4. Claude Code 侧配置settings.json 与 ANTHROPIC_* 环境变量Claude Code 读取配置的方式有两种项目级/用户级的settings.json以及进程环境变量。两种都指向同一组ANTHROPIC_*变量。方式一写入settings.json用户级路径通常是~/.claude/settings.json项目级放在仓库的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 } }方式二直接在当前 shell 里导出环境变量适合临时验证# 仅对当前终端会话生效关闭终端即失效 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELclaude-sonnet-4-5 # 验证变量是否写进去了注意不要把 Key 打印到会被记录的地方 echo ${ANTHROPIC_BASE_URL}方式三如果团队里多人共用一套配置建议只提交settings.json里的ANTHROPIC_BASE_URL和ANTHROPIC_MODEL把ANTHROPIC_AUTH_TOKEN留给每个人自己的环境变量或密钥工具注入。这样配置文件可以进版本库Key 不进。配置完成后的验收动作很简单在项目根目录启动 Claude Code随便问一个不需要读文件的问题。如果返回正常说明链路已通如果报 401先检查 Key 是否有多余空格或换行如果报模型不存在回到模型列表页确认模型标识的准确拼写。更多细节可以对照 Claude Code 文档 里的配置说明逐项核对。5. 可复现对照实验路径检索 vs 全文粘贴的 Token 消耗这一节是本文的核心产出。我们设计一个任何人都能复现的实验用同一批记忆内容比较两种喂给 Claude Code 的方式。实验准备。在本地准备 24 份 Markdown 记忆文件覆盖接口约定、历史故障、性能基线、第三方 SDK 注意事项等主题。假设每份文件平均 600 token 正文这个数字可以用任何 tokenizer 在你自己的文件上实测替换。实验目标是让 Claude Code 完成一项需要参考其中 2 份文件的任务。方案 A全文粘贴。每次提问都把 24 份文件内容整段贴进上下文。单轮输入 24 × 600 14400 token连续 5 轮对话每轮都重新贴 14400 × 5 72000 token方案 B路径检索。先让 agent-memory 返回排序后的路径列表每条约 18 token含相对路径与一行摘要由 Claude Code 自行判断需要打开哪几份实际打开 2 份。路径列表 24 × 18 432 token按需打开 2 份 2 × 600 1200 token单轮输入 ≈ 1632 token连续 5 轮 1632 × 5 8160 token汇总成表对比项方案 A全文粘贴方案 B路径检索单轮输入 token估1440016325 轮累计输入 token估720008160相对降幅—约 88.7%记忆写入额外云端调用无无本地运行时召回内容长度可控性不可控可控数据可审计性取决于工具Markdown 可直接 diff实验怎么自己做。用git init建两个分支或无关联的两个目录分别模拟方案 A 和方案 B 的上下文构造方式把每次实际发给模型的请求体保存下来用 tokenizer 统计输入长度。不要凭感觉估算一定要拿真实请求体统计——不同模型的 tokenizer 对中文、代码块、路径字符串的切分差异不小尤其在路径字符串这种短文本密集的场景里估算和实测经常差 10% 以上。这个实验说明了什么。结论不是路径检索永远更快而是记忆层返回路径时把要不要读的决策权交还给了 agent。当任务只依赖少数几份记忆时省下的量非常可观当任务本身就需要通读全部记忆时路径检索的优势会收窄。所以选型前先观察自己的真实调用模式而不是把 88.7% 当成通用数字。6. 把记忆读写接到会话边界CLAUDE.md 与 hooks 的落地写法链路通了、实验做完了接下来是把 agent-memory 真正挂到 Claude Code 的会话生命周期上。这里分三件事。第一件事在项目记忆入口里声明检索约定。在项目根目录的CLAUDE.md中写清楚记忆库位置与使用规则例如## 本地记忆库 - 记忆根目录.memory/Markdown 文件即事实来源 - 检索入口执行记忆仓库 README 中给出的检索命令获取排序后的路径列表 - 使用规则 1. 先取路径列表再按需打开文件默认不超过 3 个 2. 不要一次性读取整个 .memory/ 目录 3. 打开文件后只引用与当前任务直接相关的段落注意这里刻意没有写死具体命令名——agent-memory 仍在 0.x 阶段快速迭代命令和参数可能变化。正确做法是以你本地拉取的仓库 README 或--help输出为准把真实命令填进去而不是照抄网上任何一篇教程。第二件事用 hooks 在会话边界触发写入。Claude Code 支持在会话开始、结束等时机执行 shell 命令可以把本地记忆的写入动作挂上去{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: bash ~/.claude/scripts/memory-session-start.sh } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: bash ~/.claude/scripts/memory-flush.sh } ] } ] } }两个脚本你自己写内容就是调用记忆仓库提供的检索/写入命令把结果输出到 stdout 或落盘#!/usr/bin/env bash # ~/.claude/scripts/memory-session-start.sh # 作用在会话开始时输出当前记忆库的路径索引供模型按需读取 set -euo pipefail MEMORY_ROOT${MEMORY_ROOT:-$PWD/.memory} cd $MEMORY_ROOT # 将 memory-cmd 替换为 agent-memory 仓库 README 中实际提供的命令 # 输出保持精简路径 一行摘要避免把正文带进上下文 memory-cmd index --format path-only --limit 40第三件事确认写入是幂等的。会话边界触发写入意味着同一段经验可能被反复写。要保证重复写入不会产生大量语义相同的碎片文件。如果你的记忆库还不支持去重就在脚本里加一层简单判断例如按日期主题命名文件同一天同一主题写入同一份文件并追加段落。7. Codex CLI 与 CC Switch另一条链路的配置要点前面反复提到 Claude Code 与 Codex CLI 可以共享同一个记忆库。但两者供应商配置完全不通用把ANTHROPIC_*变量套到 Codex 上是错误做法。Codex CLI 用config.toml。典型形态如下路径通常在~/.codex/config.tomlmodel gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat对应的环境变量单独设置export TAOTOKEN_API_KEYYOUR_API_KEY注意这里是TAOTOKEN_API_KEY而不是ANTHROPIC_AUTH_TOKEN。混用变量名最典型的症状是配置文件看起来对但启动即报鉴权失败而错误信息里不会告诉你你少导出了一个 OpenAI 侧的环境变量。CC Switch 三件套。如果你用 CC Switch 这类配置切换工具在多套供应商之间来回切切换时只需要核对三件套是否成组生效Base URLhttps://taotoken.net/apiAPI Key控制台创建的 Key占位符统一记为YOUR_API_KEY模型名目标模型标识注意 Claude Code 侧和 Codex 侧的模型命名体系不同不要交叉填写这三个值必须来自同一份配置方案。最常见的翻车方式是Base URL 换了、Key 换了模型名还是上一个供应商的表现为请求能发出但立刻报模型不可用。记忆库共享的处理。两个 CLI 指向同一个.memory/目录时要注意并发写入。如果两个 CLI 同时在一个仓库里工作建议给每个 agent 的写入动作加文件锁或者在不同分支上各自提交记忆文件、定期合并。文本文件的好处在这里再次体现合并冲突是可见的、可人工裁决的不会像二进制索引那样直接损坏。8. 排障清单从 401 到上下文超限的定位顺序把供应商切到新入口后问题排查建议按固定顺序走不要跳步。症状一401 / 鉴权失败。依次检查Key 是否包含首尾空格或换行环境变量是否在启动 Claude Code 的那个 shell 里导出settings.json里的ANTHROPIC_AUTH_TOKEN是否被更高优先级的配置覆盖。注意 Claude Code 的配置存在多层级覆盖关系项目级会覆盖用户级排查时先确认当前生效的是哪一层。症状二404 / 路径不存在。九成是 Base URL 写多了。正确值是https://taotoken.net/api不要追加/v1不要带结尾斜杠。症状三模型不存在或不可用。到模型列表页核对标识的准确拼写注意区分大小写和连字符。如果同时配置了主模型和快速小模型两个都要核对。症状四上下文超限。这类报错往往不是配置问题而是记忆检索没有生效——agent 把整个目录读进来了。回到CLAUDE.md确认先取路径、按需打开、默认不超过 3 个这条规则是否写在模型一定会看到的位置。同时检查 hooks 输出是否被截断路径列表过长时应当设--limit。症状五响应变慢但没报错。多半是每轮都在重复读同一批文件。开启请求日志把连续几轮的输入长度打出来对比如果每轮长度几乎相同且都很大说明路径检索没有真正拦住正文注入。9. 什么时候用路径检索什么时候直接粘工具选型要落到场景上。根据上面的实验和自己的使用经验可以给出一个粗糙但实用的判断标准优先用路径检索的场景记忆条目数量在几十份以上单个条目篇幅较长每次任务只依赖其中一小部分多轮对话中会反复切换主题记忆内容涉及内部约定、故障记录等敏感信息希望留在本地。直接整段粘贴反而更划算的场景记忆总量很小三五份短文件任务本身就要通读全部材料做整体分析一次性任务没有第二轮。两者混用的场景把稳定的、长期有效的约定放在路径索引里把当前任务临时需要的短材料直接贴。不要让一条规则统治所有情况。另外要提醒一个 agent-memory 的边界它定位是开发者工具面向自己搭 agent 工作流的人不是开箱即用的消费级产品。版本号还在 0.x接口可能变化把它引入正式工作流之前先在小仓库里跑两周观察记忆文件的实际增长速度和检索命中率再决定要不要推广到主力项目。10. 常见问题Qagent-memory 需要额外的 API Key 吗不需要。它的索引与检索在本地完成不依赖外部服务。你唯一需要准备的 Key 是给 Claude Code 或 Codex CLI 这类模型调用方用的也就是本文第 3 节在控制台创建的那一个。Q路径检索会不会让模型漏掉关键信息会存在这个风险取决于索引排序质量和摘要的信息密度。缓解办法有两个一是控制索引规模条目太多时先按主题分流二是在CLAUDE.md里明确要求模型在不确定时扩大读取范围把省 token和别漏信息之间的边界交给模型判断而不是硬性设成只能读一个文件。Q为什么要把 Base URL 改成https://taotoken.net/api再配记忆因为它让整条链路可观测。记忆层负责减少喂进去的内容入口层负责让每次调用可见、可统计。只做前一半你无法验证省下来的 token 是否真的省下来了两边都做第 5 节的对照实验才有意义。QClaude Code 和 Codex CLI 的配置可以互相复制吗不可以。Claude Code 走settings.json加ANTHROPIC_*环境变量Codex CLI 走config.toml加 OpenAI 侧的环境变量命名。可以共享的是.memory/目录和其中的 Markdown 文件。Q记忆文件应该进 git 吗建议进。Markdown 作为事实来源最大的价值就是它可以被版本管理、被 diff、被回滚。但要确保里面不写入任何密钥、令牌、个人身份信息——记忆库记录的是经验不是凭证。11. 下一步把这条链路跑通再谈优化把整件事拆开看其实只有三个动作第一在 模型对话 里先确认要用的模型能稳定复现你要的效果第二在控制台创建 Key、把 Base URL 固定为https://taotoken.net/api让 Claude Code 的每一次调用都可统计第三把 agent-memory 的路径索引挂到会话边界上用第 5 节的对照方法量化收益。如果你还没有可用的调用入口可以直接从 API Keys 控制台 创建第一个 Key如果打算长期把 Claude Code 作为主力开发工具Coding Plan 里给出了适合持续编码场景的方案配置细节对照 Claude Code 文档 逐项落地即可。最后提醒一句不要指望一次配置就拿到最优的 token 曲线。先跑通再拿真实请求体统计输入长度然后一轮一轮收紧读取规则。记忆层的收益是调出来的不是配出来的。
省 Token 的 agent-memory 路径检索，TaoToken 给 Claude Code 发 Key
1. 当 Claude Code 反复读同一批文档Token 真正的去向如果你用 Claude Code 做中大型项目大概率见过这样的场景项目里有十几份设计说明、接口约定、踩坑记录CLAUDE.md里写不下于是你每次开新会话都手动一遍或者让模型Read一整个目录。会话跑通了但输入 token 的曲线非常难看——模型第 3 轮还在读第 1 轮已经读过的东西第 10 轮开始你甚至不确定它到底记住了哪一份。这不是模型变笨了是上下文里塞了大量和当前问题无关、但被整份粘贴进来的正文。要解决这个问题除了控制你自己的检索习惯还需要一层专门的记忆运行时。本文围绕开源项目 agent-memory 的「路径检索」路线展开同时把 Claude Code 的模型调用链路切到 TaoToken 上跑一遍完整可复现流程。开始之前先把入口放出来可以用浏览器打开 TaoToken 官网 完成注册然后在控制台申请一个用于 Claude Code 的 API KeyBase URL 统一填https://taotoken.net/api。下面的配置、对照实验和排障清单都建立在Key 已到手、Base URL 已明确这两个前提上。需要先讲清楚一件事本文里所有关于 token 消耗的讨论消耗主体都是Claude Code 这一侧的模型调用。agent-memory 本身是本地运行时索引和检索不产生云端调用真正把 token 烧掉的是 Claude Code 把哪些内容塞进了发给模型的请求体。所以「省 Token」这件事一半靠记忆层少喂正文一半靠推理入口本身可观测、可换模型。2. agent-memory 的关键取舍返回路径而不是返回正文业界做 AI 长期记忆主流做法是向量库 语义检索把记忆切片、embedding、存库召回时把命中片段整段拼进上下文。这条路能跑通但有两个副作用——召回内容长度不可控以及数据形态是个黑盒出了偏差不好定位。agent-memory 选了一条更工程化的路子它的核心设计有四点第一Markdown 文件是唯一事实来源。所有记忆以普通.md文件落地可以被编辑器直接打开、被 git 追踪、被 diff 审查。旁边那个 SQLite 索引只承担加速角色删掉之后重建即可不会丢数据。这一点对团队协作尤其重要记忆不再藏在某个二进制文件里代码评审的那套流程可以直接搬过来。第二检索的返回值是路径不是正文。这是与向量召回最大的分歧点。它给你的 agent 是一组排序后的文件路径外加极短摘要agent 判断这条和当前任务相关才会去打开对应文件、读取那段内容。用到多深读多深不相关的不读。省下来的 token 全部来自这里。第三写入发生在会话边界不依赖模型自觉。让模型记得把学到的东西写下来是不可靠的它经常忘。agent-memory 选择在会话结束这类边界点自动触发写入再配合一个异步的整合过程做价值筛选——高价值的保留、低价值的淘汰。第四local-first零第三方 API Key。记忆数据全部留在本地不需要外部服务参与这既是隐私考虑也顺带砍掉了 embedding 调用带来的额外成本与延迟。值得强调的是这套机制不绑定某一家 CLI。任何能执行 shell 命令的 agent 都能读写它所以 Claude Code 和 Codex CLI 可以共用同一个记忆目录——你在 Claude Code 里踩过的坑切到 Codex CLI 依然能检索到。3. 接入前的第一步在 TaoToken 拿到 Claude Code 用的 Key 和 Base URLClaude Code 默认把请求发往 Anthropic 官方端点。要把它切到可控的入口需要三样东西Base URL、API Key、模型标识。第一步是拿到 Key打开 TaoToken 官网完成账号注册与登录进入控制台创建 API Key。建议给这个 Key 起一个可识别的名字例如claude-code-local-memory方便后续在用量面板里区分项目把 Key 存到本地环境变量或密钥管理工具里不要直接写进会被提交到 git 的配置文件记录 Base URLhttps://taotoken.net/api。Key 创建页的直达地址是 API Keys 控制台创建完成后先别关页面后面配置 Claude Code 会立刻用到。至于具体用哪个模型跑记忆检索场景可以在 模型对话 里先手动试几个观察同一段记忆路径列表在不同模型下的引用准确率再决定长期用哪个。一个容易忽略的点Base URL 不要写成https://taotoken.net/api/v1或者带斜杠结尾的形式。Claude Code 会自行拼接路径多写一段前缀往往表现为 404而不是参数错误排查时容易被带偏。4. Claude Code 侧配置settings.json 与 ANTHROPIC_* 环境变量Claude Code 读取配置的方式有两种项目级/用户级的settings.json以及进程环境变量。两种都指向同一组ANTHROPIC_*变量。方式一写入settings.json用户级路径通常是~/.claude/settings.json项目级放在仓库的.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-5 } }方式二直接在当前 shell 里导出环境变量适合临时验证# 仅对当前终端会话生效关闭终端即失效 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELclaude-sonnet-4-5 # 验证变量是否写进去了注意不要把 Key 打印到会被记录的地方 echo ${ANTHROPIC_BASE_URL}方式三如果团队里多人共用一套配置建议只提交settings.json里的ANTHROPIC_BASE_URL和ANTHROPIC_MODEL把ANTHROPIC_AUTH_TOKEN留给每个人自己的环境变量或密钥工具注入。这样配置文件可以进版本库Key 不进。配置完成后的验收动作很简单在项目根目录启动 Claude Code随便问一个不需要读文件的问题。如果返回正常说明链路已通如果报 401先检查 Key 是否有多余空格或换行如果报模型不存在回到模型列表页确认模型标识的准确拼写。更多细节可以对照 Claude Code 文档 里的配置说明逐项核对。5. 可复现对照实验路径检索 vs 全文粘贴的 Token 消耗这一节是本文的核心产出。我们设计一个任何人都能复现的实验用同一批记忆内容比较两种喂给 Claude Code 的方式。实验准备。在本地准备 24 份 Markdown 记忆文件覆盖接口约定、历史故障、性能基线、第三方 SDK 注意事项等主题。假设每份文件平均 600 token 正文这个数字可以用任何 tokenizer 在你自己的文件上实测替换。实验目标是让 Claude Code 完成一项需要参考其中 2 份文件的任务。方案 A全文粘贴。每次提问都把 24 份文件内容整段贴进上下文。单轮输入 24 × 600 14400 token连续 5 轮对话每轮都重新贴 14400 × 5 72000 token方案 B路径检索。先让 agent-memory 返回排序后的路径列表每条约 18 token含相对路径与一行摘要由 Claude Code 自行判断需要打开哪几份实际打开 2 份。路径列表 24 × 18 432 token按需打开 2 份 2 × 600 1200 token单轮输入 ≈ 1632 token连续 5 轮 1632 × 5 8160 token汇总成表对比项方案 A全文粘贴方案 B路径检索单轮输入 token估1440016325 轮累计输入 token估720008160相对降幅—约 88.7%记忆写入额外云端调用无无本地运行时召回内容长度可控性不可控可控数据可审计性取决于工具Markdown 可直接 diff实验怎么自己做。用git init建两个分支或无关联的两个目录分别模拟方案 A 和方案 B 的上下文构造方式把每次实际发给模型的请求体保存下来用 tokenizer 统计输入长度。不要凭感觉估算一定要拿真实请求体统计——不同模型的 tokenizer 对中文、代码块、路径字符串的切分差异不小尤其在路径字符串这种短文本密集的场景里估算和实测经常差 10% 以上。这个实验说明了什么。结论不是路径检索永远更快而是记忆层返回路径时把要不要读的决策权交还给了 agent。当任务只依赖少数几份记忆时省下的量非常可观当任务本身就需要通读全部记忆时路径检索的优势会收窄。所以选型前先观察自己的真实调用模式而不是把 88.7% 当成通用数字。6. 把记忆读写接到会话边界CLAUDE.md 与 hooks 的落地写法链路通了、实验做完了接下来是把 agent-memory 真正挂到 Claude Code 的会话生命周期上。这里分三件事。第一件事在项目记忆入口里声明检索约定。在项目根目录的CLAUDE.md中写清楚记忆库位置与使用规则例如## 本地记忆库 - 记忆根目录.memory/Markdown 文件即事实来源 - 检索入口执行记忆仓库 README 中给出的检索命令获取排序后的路径列表 - 使用规则 1. 先取路径列表再按需打开文件默认不超过 3 个 2. 不要一次性读取整个 .memory/ 目录 3. 打开文件后只引用与当前任务直接相关的段落注意这里刻意没有写死具体命令名——agent-memory 仍在 0.x 阶段快速迭代命令和参数可能变化。正确做法是以你本地拉取的仓库 README 或--help输出为准把真实命令填进去而不是照抄网上任何一篇教程。第二件事用 hooks 在会话边界触发写入。Claude Code 支持在会话开始、结束等时机执行 shell 命令可以把本地记忆的写入动作挂上去{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: bash ~/.claude/scripts/memory-session-start.sh } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: bash ~/.claude/scripts/memory-flush.sh } ] } ] } }两个脚本你自己写内容就是调用记忆仓库提供的检索/写入命令把结果输出到 stdout 或落盘#!/usr/bin/env bash # ~/.claude/scripts/memory-session-start.sh # 作用在会话开始时输出当前记忆库的路径索引供模型按需读取 set -euo pipefail MEMORY_ROOT${MEMORY_ROOT:-$PWD/.memory} cd $MEMORY_ROOT # 将 memory-cmd 替换为 agent-memory 仓库 README 中实际提供的命令 # 输出保持精简路径 一行摘要避免把正文带进上下文 memory-cmd index --format path-only --limit 40第三件事确认写入是幂等的。会话边界触发写入意味着同一段经验可能被反复写。要保证重复写入不会产生大量语义相同的碎片文件。如果你的记忆库还不支持去重就在脚本里加一层简单判断例如按日期主题命名文件同一天同一主题写入同一份文件并追加段落。7. Codex CLI 与 CC Switch另一条链路的配置要点前面反复提到 Claude Code 与 Codex CLI 可以共享同一个记忆库。但两者供应商配置完全不通用把ANTHROPIC_*变量套到 Codex 上是错误做法。Codex CLI 用config.toml。典型形态如下路径通常在~/.codex/config.tomlmodel gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat对应的环境变量单独设置export TAOTOKEN_API_KEYYOUR_API_KEY注意这里是TAOTOKEN_API_KEY而不是ANTHROPIC_AUTH_TOKEN。混用变量名最典型的症状是配置文件看起来对但启动即报鉴权失败而错误信息里不会告诉你你少导出了一个 OpenAI 侧的环境变量。CC Switch 三件套。如果你用 CC Switch 这类配置切换工具在多套供应商之间来回切切换时只需要核对三件套是否成组生效Base URLhttps://taotoken.net/apiAPI Key控制台创建的 Key占位符统一记为YOUR_API_KEY模型名目标模型标识注意 Claude Code 侧和 Codex 侧的模型命名体系不同不要交叉填写这三个值必须来自同一份配置方案。最常见的翻车方式是Base URL 换了、Key 换了模型名还是上一个供应商的表现为请求能发出但立刻报模型不可用。记忆库共享的处理。两个 CLI 指向同一个.memory/目录时要注意并发写入。如果两个 CLI 同时在一个仓库里工作建议给每个 agent 的写入动作加文件锁或者在不同分支上各自提交记忆文件、定期合并。文本文件的好处在这里再次体现合并冲突是可见的、可人工裁决的不会像二进制索引那样直接损坏。8. 排障清单从 401 到上下文超限的定位顺序把供应商切到新入口后问题排查建议按固定顺序走不要跳步。症状一401 / 鉴权失败。依次检查Key 是否包含首尾空格或换行环境变量是否在启动 Claude Code 的那个 shell 里导出settings.json里的ANTHROPIC_AUTH_TOKEN是否被更高优先级的配置覆盖。注意 Claude Code 的配置存在多层级覆盖关系项目级会覆盖用户级排查时先确认当前生效的是哪一层。症状二404 / 路径不存在。九成是 Base URL 写多了。正确值是https://taotoken.net/api不要追加/v1不要带结尾斜杠。症状三模型不存在或不可用。到模型列表页核对标识的准确拼写注意区分大小写和连字符。如果同时配置了主模型和快速小模型两个都要核对。症状四上下文超限。这类报错往往不是配置问题而是记忆检索没有生效——agent 把整个目录读进来了。回到CLAUDE.md确认先取路径、按需打开、默认不超过 3 个这条规则是否写在模型一定会看到的位置。同时检查 hooks 输出是否被截断路径列表过长时应当设--limit。症状五响应变慢但没报错。多半是每轮都在重复读同一批文件。开启请求日志把连续几轮的输入长度打出来对比如果每轮长度几乎相同且都很大说明路径检索没有真正拦住正文注入。9. 什么时候用路径检索什么时候直接粘工具选型要落到场景上。根据上面的实验和自己的使用经验可以给出一个粗糙但实用的判断标准优先用路径检索的场景记忆条目数量在几十份以上单个条目篇幅较长每次任务只依赖其中一小部分多轮对话中会反复切换主题记忆内容涉及内部约定、故障记录等敏感信息希望留在本地。直接整段粘贴反而更划算的场景记忆总量很小三五份短文件任务本身就要通读全部材料做整体分析一次性任务没有第二轮。两者混用的场景把稳定的、长期有效的约定放在路径索引里把当前任务临时需要的短材料直接贴。不要让一条规则统治所有情况。另外要提醒一个 agent-memory 的边界它定位是开发者工具面向自己搭 agent 工作流的人不是开箱即用的消费级产品。版本号还在 0.x接口可能变化把它引入正式工作流之前先在小仓库里跑两周观察记忆文件的实际增长速度和检索命中率再决定要不要推广到主力项目。10. 常见问题Qagent-memory 需要额外的 API Key 吗不需要。它的索引与检索在本地完成不依赖外部服务。你唯一需要准备的 Key 是给 Claude Code 或 Codex CLI 这类模型调用方用的也就是本文第 3 节在控制台创建的那一个。Q路径检索会不会让模型漏掉关键信息会存在这个风险取决于索引排序质量和摘要的信息密度。缓解办法有两个一是控制索引规模条目太多时先按主题分流二是在CLAUDE.md里明确要求模型在不确定时扩大读取范围把省 token和别漏信息之间的边界交给模型判断而不是硬性设成只能读一个文件。Q为什么要把 Base URL 改成https://taotoken.net/api再配记忆因为它让整条链路可观测。记忆层负责减少喂进去的内容入口层负责让每次调用可见、可统计。只做前一半你无法验证省下来的 token 是否真的省下来了两边都做第 5 节的对照实验才有意义。QClaude Code 和 Codex CLI 的配置可以互相复制吗不可以。Claude Code 走settings.json加ANTHROPIC_*环境变量Codex CLI 走config.toml加 OpenAI 侧的环境变量命名。可以共享的是.memory/目录和其中的 Markdown 文件。Q记忆文件应该进 git 吗建议进。Markdown 作为事实来源最大的价值就是它可以被版本管理、被 diff、被回滚。但要确保里面不写入任何密钥、令牌、个人身份信息——记忆库记录的是经验不是凭证。11. 下一步把这条链路跑通再谈优化把整件事拆开看其实只有三个动作第一在 模型对话 里先确认要用的模型能稳定复现你要的效果第二在控制台创建 Key、把 Base URL 固定为https://taotoken.net/api让 Claude Code 的每一次调用都可统计第三把 agent-memory 的路径索引挂到会话边界上用第 5 节的对照方法量化收益。如果你还没有可用的调用入口可以直接从 API Keys 控制台 创建第一个 Key如果打算长期把 Claude Code 作为主力开发工具Coding Plan 里给出了适合持续编码场景的方案配置细节对照 Claude Code 文档 逐项落地即可。最后提醒一句不要指望一次配置就拿到最优的 token 曲线。先跑通再拿真实请求体统计输入长度然后一轮一轮收紧读取规则。记忆层的收益是调出来的不是配出来的。
