1. Claude Code 会话失忆agent-memory 中文 README 想解决什么如果你在 Claude Code 里花半小时讲清了项目结构、接口约定、历史坑点关掉终端再开一个新会话它很可能又问你「这个项目是做什么的」。这不是模型突然变笨而是 Claude Code 默认没有跨会话的长期记忆。每次新会话都是白纸上下文窗口再大也装不下你过去几周踩过的坑。agent-memory这个 Python 项目要解决的就是这件事给 AI agent 一个长期记忆运行时让 Claude Code、Codex CLI 这类能执行 shell 命令的 agent 共享同一份记忆。中文版 README 的价值在于把安装、初始化、记忆写入、检索路径这些关键步骤翻译成了中文降低了阅读门槛让开发者能更快跑通工作流。与此同时Claude Code 终究要发模型请求。你可以继续用默认供应商也可以把模型入口换到 TaoToken先到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-intro 注册并拿到 Key然后把 Claude Code 的 Base URL 填成https://taotoken.net/api。注意这个 Base URL 不加 UTM配置里保持干净。下面按「模型入口配置 → agent-memory 中文 README 落地 → 接入 Claude Code → 排障与控本」的顺序写尽量给出可复制片段。agent-memory的核心设计并不复杂但很扎实它把 Markdown 文件当作唯一的事实来源所有记忆都以普通.md文件存在本地你能用编辑器打开、用 Git 做版本管理、用肉眼审计。旁边的 SQLite 索引只是缓存删掉也能从 Markdown 重建。这意味着记忆不是黑盒不会因为某个向量库损坏就全部丢失。对 Claude Code 工作流用户来说这种透明性很重要你可以随时检查 agent 记住了什么也可以手动修正错误记忆。它还有几个直接好处。第一Claude Code、Codex CLI 可以共享同一个记忆库你在 Claude Code 里积累的排障经验切到 Codex CLI 还在。第二检索在本地完成并且返回的是 Markdown 文件路径而不是把一大段文本直接塞进上下文Claude Code 按需打开文件用到多深读多深能减少无效 Token。第三写入不依赖 agent「记得」去写它会在会话边界触发写入并在后台做整合按价值保留或遗忘。第四agent-memory本身零 API Key完全本地运行不需要第三方服务。但要分清真正调用模型、消耗 Token 的是 Claude Code不是agent-memory。项目目前仍处于早期版本定位偏开发者工具适合愿意自己搭 agent 工作流的人。中文版 README 已经把核心文档中文化你可以直接在 GitHub 搜索agent-memory-cn找到中文仓库。接下来先从模型入口开始配置否则 Claude Code 无法发请求记忆工作流也无从跑起。2. 模型入口先跑通去 TaoToken 拿 Key填 Claude Code settings.jsonClaude Code 发模型请求前需要知道两件事请求发往哪里以及用什么 Key 认证。TaoToken 的官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-claude-code-config。注册后进控制台创建 API KeyKey 只显示一次复制后放到安全位置。本文所有示例统一用占位符YOUR_API_KEY你替换成自己的真实 Key。Claude Code 常见配置方式有两种写入settings.json或者用环境变量。推荐先写settings.json它更稳定也方便项目级覆盖。用户级配置通常在~/.claude/settings.json项目级配置在项目根目录.claude/settings.json。项目级只对当前项目生效适合给不同项目配不同模型或 Key。用户级~/.claude/settings.json示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }如果你更习惯环境变量Linux/macOS 可以这样写export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELclaude-sonnet-4-5-20250929Windows PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_AUTH_TOKENYOUR_API_KEY $env:ANTHROPIC_MODELclaude-sonnet-4-5-20250929上面ANTHROPIC_MODEL只是示例具体模型 ID 以 TaoToken 控制台可用列表为准。不要凭记忆填一个不存在的模型名否则 Claude Code 会直接报模型不存在。配置完成后运行claude进入交互界面问一句「请回复你当前使用的模型名称」。如果返回正常说明 Base URL 和 Key 已经生效。如果报 401先检查ANTHROPIC_AUTH_TOKEN是否复制完整如果报 404检查 Base URL 是否写成了https://taotoken.net/api不要多加/v1或末尾斜杠。这里有一个容易混淆的点ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL是 Claude Code 的配置项不要把它们套到 Codex CLI 上。Codex CLI 使用另一套配置和环境变量后面会单独写。混用会导致 Codex 读不到配置或者把请求发到错误的端点。3. agent-memory 中文 README 最小落地Markdown 记忆库 SQLite 索引模型入口跑通后开始处理记忆层。agent-memory是 Python 项目建议放在独立虚拟环境里避免污染系统 Python。中文版 README 已经把安装步骤中文化实际命令以仓库为准下面给出通用流程。# 1. 拉取中文版仓库具体地址以你搜索到的 agent-memory-cn 为准 git clone agent-memory 中文版仓库地址 cd agent-memory-cn # 2. 创建虚拟环境 python -m venv .venv source .venv/bin/activate # Windows PowerShell 用 # .venv\Scripts\Activate.ps1 # 3. 安装依赖具体命令看 README pip install -e .安装完成后先看帮助确认可用的子命令agent-memory --help不同版本命令名可能略有差异中文 README 通常会给出初始化命令。初始化的核心动作是创建一个记忆工作区里面包含 Markdown 记忆文件和 SQLite 索引。你可以把它放在项目根目录下的.agent-memory/也可以放到独立目录。示例# 以中文 README 实际命令为准下面仅表示初始化动作 agent-memory init --workspace .agent-memory初始化后目录结构大致如下。具体文件名以实际生成为准但设计思路是Markdown 是事实来源SQLite 只是索引。.agent-memory/ memory/ project.md decisions.md pitfalls.md index.sqlite3 config.tomlproject.md可以放项目背景、技术栈、模块职责decisions.md放架构决策和原因pitfalls.md放历史报错、排障过程和规避方案。你可以直接用编辑器改这些 Markdown 文件改完让agent-memory重建索引即可。因为事实来源是 Markdown即使index.sqlite3损坏或误删也能从 Markdown 重新生成。这一点比纯向量数据库方案更可控。agent-memory的写入逻辑也值得注意。它不要求 agent 每次主动记得写入而是会在会话边界触发写入并在后台做类似「睡眠期整合」的处理按价值保留或遗忘。对 Claude Code 用户来说这意味着你不需要在提示词里反复强调「请记住这个」只要会话边界和整合流程配置正确可复用的结论会沉淀到 Markdown 里。检索时它返回的是文件路径而不是把整个记忆库拼成上下文Claude Code 可以按需打开文件减少 Token 浪费。4. 把 agent-memory 接进 Claude CodeCLAUDE.md 约定与检索路径agent-memory本身不绑定 Claude Code它更像一个本地记忆运行时任何能执行 shell 命令的 agent 都能调用。Claude Code 支持读取项目根目录的CLAUDE.md你可以把记忆使用约定写进去让 Claude Code 在每次任务开始时先检索记忆在任务结束时把可复用结论写回记忆库。在项目根目录创建或编辑CLAUDE.md加入类似内容## 长期记忆约定 - 开始任务前先调用 agent-memory 检索当前任务关键词。 - 检索结果通常返回 Markdown 文件路径只打开与任务相关的文件不要把整个记忆库粘贴进上下文。 - 完成任务后将可复用的结论、踩坑记录、架构决策写入记忆库。 - 记忆以 Markdown 为事实来源不要直接修改 SQLite 索引。 - 如果检索结果与当前代码冲突以当前代码和最新文档为准并修正记忆文件。这段约定的关键点是「返回路径、按需打开」。很多记忆方案会把检索到的文本全部拼进提示词导致上下文迅速膨胀。agent-memory返回路径的方式更适合 Claude CodeClaude Code 可以自己决定读哪个文件、读多少内容既能利用历史经验又不至于把无关记忆塞进 Token 预算。具体调用命令以中文版 README 为准。通常会有「检索」「写入」「重建索引」三类命令。你可以手动执行一次确认记忆库可用# 检索示例具体命令名以 README 为准 agent-memory search 数据库连接池 超时 # 写入示例具体命令名以 README 为准 agent-memory remember --file .agent-memory/memory/pitfalls.md如果中文 README 给出的命令是短别名比如am那就用短别名替换agent-memory。核心不是记住某个固定命令而是让 Claude Code 在会话开始和结束时各做一次记忆操作。你可以在CLAUDE.md里写清楚「本项目的记忆命令是 xxx」这样 Claude Code 每次都会按约定执行。还有一个实用技巧把记忆文件按主题拆分而不是写成一个巨大的memory.md。比如database.md、deploy.md、frontend.md、api-contract.md。检索命中后返回的路径更精准Claude Code 打开的文件更小Token 消耗也更低。agent-memory的本地排序检索会优先返回相关路径你只需要保证 Markdown 标题和关键词清晰。Claude Code 和 Codex CLI 可以共享同一个.agent-memory目录。只要两个工具都在同一个项目根目录运行并且都按约定调用同一套记忆命令你在 Claude Code 里记录的排障经验切到 Codex CLI 时仍然可检索。这就是「共享记忆库」的实际意义换工具不换记忆减少重复交代背景的成本。5. Codex CLI 与 CC Switch 三件套配置不要混用 ANTHROPIC_*如果你同时用 Claude Code 和 Codex CLI配置要分开。Claude Code 用ANTHROPIC_*Codex CLI 用 OpenAI 兼容配置写进config.toml。不要把ANTHROPIC_BASE_URL或ANTHROPIC_AUTH_TOKEN塞给 Codex否则 Codex 读不到甚至会报认证失败。Codex CLI 的配置文件通常在~/.codex/config.toml项目级也可以用.codex/config.toml。示例model gpt-5-codex # 替换成 TaoToken 控制台可用模型 ID 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_KEYWindows PowerShell$env:TAOTOKEN_API_KEYYOUR_API_KEY注意Codex 的base_url也建议使用https://taotoken.net/api但环境变量名是TAOTOKEN_API_KEY不要写成ANTHROPIC_AUTH_TOKEN。模型名同样以 TaoToken 控制台为准。Codex CLI 更适合代码任务Claude Code 更适合长上下文对话和工具编排两者共享agent-memory记忆库但模型入口配置各管各的。如果你用 CC Switch 管理多个供应商可以把「Claude Code、Codex CLI、CC Switch」理解成三件套Claude Code 和 Codex CLI 是实际干活的 agentCC Switch 负责在多个配置之间切换。在 CC Switch 里新建 TaoToken 供应商时通常需要填三项名称、Base URL、API Key。名称可以写taotokenBase URL 填https://taotoken.net/apiAPI Key 填YOUR_API_KEY。如果 CC Switch 支持分别管理 Claude Code 和 Codex一定要给它们建两份配置不要以为一份ANTHROPIC_*配置能同时喂饱两个工具。配置完成后分别验证# Claude Code claude 请回复当前模型名称 # Codex CLI codex 请回复当前模型名称两个都能正常返回才说明模型入口配置没有互相污染。6. 排障清单401、404、模型名与 Base URL 的常见坑配置过程中最容易遇到四类问题401 未授权、404 路径错误、模型名不存在、settings.json 不生效。下面按现象给排查顺序。第一401 Unauthorized。优先检查 Key 是否复制完整有没有多空格、少字符。检查ANTHROPIC_AUTH_TOKEN或TAOTOKEN_API_KEY是否写在正确的配置文件里。如果你同时设置了环境变量和settings.json要确认实际生效的是哪一个。Claude Code 一般会读取settings.json的env字段项目级配置可能覆盖用户级配置。可以临时把环境变量清掉只保留一份配置减少干扰。第二404 Not Found。最常见原因是 Base URL 写错。Claude Code 的ANTHROPIC_BASE_URL应填https://taotoken.net/api不要擅自加/v1也不要加末尾斜杠。Codex CLI 的base_url同样建议先按https://taotoken.net/api填如果控制台明确给出了 OpenAI 兼容路径再以控制台为准。Base URL 不加 UTM保持干净。第三模型不存在。ANTHROPIC_MODEL和 Codex 的model都必须填 TaoToken 控制台实际可用的模型 ID。不要从其他平台复制模型名也不要凭印象写。先去控制台的模型列表确认再填进配置。如果模型名正确但依然报错检查该模型是否对当前 Key 开放。第四settings.json不生效。检查文件路径用户级是~/.claude/settings.json项目级是项目根目录.claude/settings.json。JSON 格式必须合法不能有注释、不能有尾随逗号。改完后重启 Claude Code或者退出当前会话重新进入。如果你在 IDE 终端里运行 Claude Code注意 IDE 可能注入了自己的环境变量可以用env | grep ANTHROPIC检查当前 shell 里是否有旧变量。agent-memory侧也有常见问题。检索不到记忆先确认初始化工作区路径是否正确Claude Code 当前工作目录是否和记忆库根目录一致。如果误删了 SQLite 索引按中文 README 的重建命令重新生成即可因为 Markdown 才是事实来源。如果写入没有触发检查会话边界钩子是否配置或者手动执行一次写入命令确认权限没问题。最后不要让 agent 直接操作生产数据库agent-memory只记录本地 MarkdownSQL 和命令应由你在本地终端执行。遇到不确定的配置可以回到 TaoToken 官网核对入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-troubleshoot。先确认 Key、Base URL、模型名三件事再去看agent-memory的记忆目录能省下大量排查时间。7. Token 归属与控本谁在消耗 Token怎么观察必须说清楚agent-memory本身零 API Key、完全本地它不会调用模型也不直接消耗 Token。真正发模型请求的是 Claude Code 或 Codex CLI。你在 Claude Code 里每问一句、每次工具调用、每个子代理执行都会消耗 Token。TaoToken 在这里扮演的是模型 API 入口Key 用来认证Base URL 用来定位请求端点。谁消耗 Token答案是 Claude Code 工作流里的模型调用。因此控本要从 Claude Code 侧入手。第一利用agent-memory返回路径的特性让 Claude Code 按需打开记忆文件而不是把整个记忆库拼进上下文。第二把CLAUDE.md里的记忆约定写清楚避免 Claude Code 反复检索无关主题。第三长会话及时收尾把可复用结论写入 Markdown新会话只带必要背景。第四在 TaoToken 控制台观察用量如果发现某个模型消耗过快可以换更合适的模型 ID或者把简单任务交给更轻量的模型。agent-memory的「会话边界写入 睡眠期整合」也能间接帮助控本。它按价值保留或遗忘避免记忆库无限膨胀。记忆库越干净检索返回的路径越精准Claude Code 需要读取的上下文越少模型请求的 Token 也越少。这是一个正向循环记忆越有条理Token 浪费越少。如果你同时跑 Claude Code 和 Codex CLI建议分别观察用量。两个工具的模型配置不同消耗曲线也不同。不要因为共享了agent-memory就以为它们共享 Token 额度。记忆库共享模型入口和认证各自独立。8. 从试模型到长期工作流文末 CTA到这里完整链路已经清晰Claude Code 负责发模型请求TaoToken 提供模型入口agent-memory负责跨会话长期记忆。中文版 README 降低了agent-memory的阅读门槛你只需要按步骤安装、初始化、在CLAUDE.md里写入记忆约定就能让 Claude Code 在新会话里先检索历史记忆再开始干活。模型入口配置则集中在settings.json或环境变量Base URL 填https://taotoken.net/apiKey 用YOUR_API_KEY占位模型 ID 以控制台为准。如果你还没开始建议按下面顺序走一遍先到模型对话页试一下模型是否可用https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-chat如果准备长期跑 Claude Code看 Coding Plan 是否适合你的用量https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-coding-plan创建 API Key替换配置里的YOUR_API_KEYhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-api-keys按 Claude Code 文档核对ANTHROPIC_*配置和 Base URLhttps://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentagent-memory-claude-code-doc最后再提醒一次agent-memory解决的是记忆持久化TaoToken 解决的是模型入口。两者组合起来Claude Code 才能在新会话里既有记忆、又能稳定发请求。配置时把 Claude Code 和 Codex CLI 的认证项分开把 Base URL 写成https://taotoken.net/api把 Key 占位符替换成真实值然后从一个小项目开始跑通会话边界写入和检索路径。跑通之后你再回头看「agent 越用越笨」这个问题会发现它其实不是模型能力问题而是工作流缺少长期记忆层。