1. 为什么 Claude Code 需要 agentmemory 这类长期记忆层Claude Code 用久了会遇到一个很具体的问题每次开新会话它对你项目的理解都从零开始。昨天刚跟它讲清楚「这个仓库的鉴权走的是自研中间件别用 passport」今天再问它相关代码它照样给你推荐 passport。这不是模型笨而是会话之间没有共享的持久记忆。agentmemory 就是补这一块的。它是一个本地常驻服务把 Claude Code 会话里的关键信息抽取、压缩、存进本地记忆库下次会话再通过 MCP 或 hooks 把相关记忆召回注入上下文。你可以把它理解成给编码 Agent 外挂了一个「项目笔记本」它不改变 Claude Code 本身的推理能力但让跨会话的上下文连续性有了着落。适合谁用三类人比较典型。一是长期维护同一批仓库的开发者项目里的隐性约定多反复解释成本高二是同时开多个项目、需要各项目记忆隔离的人三是想把记忆压缩、召回这些环节接到统一 Key 通道上避免在多个供应商之间来回切 Key 的人。这篇就按「本地安装 → 服务启动 → Claude Code 接入 → endpoint 改到 TaoToken 统一 Key → 写入与召回验证」的顺序走一遍命令和配置片段都可以直接复制。需要先说明一点agentmemory 的记忆压缩和合并是可选的 LLM 功能纯 BM25 关键词召回也能跑。但如果你希望记忆被整理成结构化知识就需要一个 LLM endpoint。下面会把 endpoint 指向 TaoToken 的写法给全这样 Claude Code 和 agentmemory 可以共用一套 Key 管理少维护一份凭证。前置条件先确认三样Node.js 18 以上node -v看一眼、Claude Code CLI 已安装并登录、macOS 或 Linux 环境Windows 目前是实验性支持。这三样齐了再往下走能省掉不少「命令找不到」的排查时间。2. 安装 agentmemory 并启动本地记忆服务安装本身一条命令但 macOS 上有个坑要先讲清楚不然装完你会发现agentmemory这个命令根本不存在。全局安装npm install -g agentmemory/agentmemory agentmemory --version如果你是用 Homebrew 装的 Nodenpm 全局包的 bin 目录有时不在 PATH 里agentmemory --version会报 command not found。手动补一个软链即可ln -sf /opt/homebrew/lib/node_modules/agentmemory/agentmemory/dist/cli.mjs \ /opt/homebrew/bin/agentmemory chmod x /opt/homebrew/bin/agentmemory agentmemory --version版本号能打印出来说明 CLI 就位了。接下来启动服务。agentmemory 是常驻进程建议单独开一个终端窗口跑别和 Claude Code 挤在一起agentmemory启动后它会监听两个端口分工不一样别搞混端口用途访问方式3111API 服务MCP 和 hooks 的通信端口程序内部调用3113实时 Viewer看记忆写入情况浏览器打开服务起来后先做一次健康检查确认 API 端口活着curl http://localhost:3111/agentmemory/health返回{status:healthy,...}就对了。如果 curl 直接连接被拒八成是服务没起来或者端口被占先看启动终端有没有报错。不想每次开机手动跑可以装成系统服务agentmemory service install这一步在 Linux 上走 systemdmacOS 上走 launchd装完重启电脑服务会自动拉起。装之前建议先手动跑通一次确认配置没问题再固化否则开机自启失败会更难排查。到这里服务层就绪了。注意此时它还没有和 Claude Code 建立任何关系记忆库是空的Viewer 打开也是空的——这是正常的得先接入并产生会话数据。3. 把 Claude Code 接入 agentmemory 并改到 TaoToken 统一 Key接入分两种范围选哪种取决于你的项目结构。按项目接入推荐多项目场景各管各的cd ~/your-project agentmemory connect claude-code这条命令会把配置写进项目目录下的.claude/settings.json只对当前项目生效。全局接入则是agentmemory connect claude-code --global配置写进~/.claude.json所有会话都接入记忆。想撤销全局接入把~/.claude.json里的mcpServers.agentmemory字段删掉再重新按项目连就行。接入之后是这篇的重点把 LLM endpoint 指向 TaoToken 统一 Key 通道。agentmemory 的记忆压缩需要一个 LLM而 Claude Code 本身也要走模型通道两边如果各配各的 Key管理起来很碎。统一到 TaoToken 之后你只需要维护一份 Key。先建配置目录并写入环境变量文件mkdir -p ~/.agentmemory cat ~/.agentmemory/.env EOF OPENAI_API_KEY你的TaoToken-Key OPENAI_BASE_URLhttps://taotoken.net/api EOF这里用的是 OpenAI 兼容协议所以变量名是OPENAI_API_KEY和OPENAI_BASE_URL但值填的是 TaoToken 的 Key 和 API 地址。安装向导里如果问 LLM 供应商选 OpenAI 兼容那一项base URL 会被上面的配置文件覆盖。Claude Code 侧的 settings 片段长这样路径是项目级.claude/settings.json字段名和层级要和下面保持一致{ mcpServers: { agentmemory: { command: agentmemory, args: [mcp], env: { AGENTMEMORY_API: http://localhost:3111 } } }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken-Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }三件套对齐一下Base URL 是https://taotoken.net/apiKey 用你在控制台生成的那把Model ID 按你实际要用的模型填。这三样在 Claude Code 和 agentmemory 里要保持一致否则会出现「Claude Code 能跑但记忆压缩失败」这种半通不通的状态。如果你用的是 Codex 那套认证信息在~/.codex/auth.json同样把 base URL 和 Key 换成 TaoToken 的即可Model ID 单独在配置里指定。Cline 走 MCP 的话也是 Base URL Key Model ID 三件套逻辑一致。配置改完重启 Claude Code 会话让它重新读取 settings。这一步别偷懒热加载不一定生效。4. 验证记忆写入与召回链路是否打通配置对不对不靠猜靠一次完整的写入加召回。第一步确认服务还在跑健康检查再打一次curl http://localhost:3111/agentmemory/health第二步在已经接入的项目目录里开一个新的 Claude Code 会话正常让它干点活比如「读一下 src/auth 目录总结鉴权流程」。这一步的目的是产生会话数据agentmemory 会在会话结束的 hook 触发时把记忆写进去。第三步会话结束后打开 Viewer 看写入结果open http://localhost:3113Viewer 里应该能看到刚才那次会话抽取出来的记忆条目。如果还是空的先别急着怀疑配置——当前正在进行的会话数据要等会话结束 hook 触发后才落库会话没结束就是空的。第四步验证召回。再开一个新会话用 recap 命令看能不能把之前的记忆捞回来/agentmemory:recap如果 recap 能列出上一条会话里关于鉴权流程的记忆说明写入和召回这条链路是通的。到这一步Claude Code 的跨会话记忆就真正生效了。想更直接地验证 API 层也可以手动打一次召回请求curl -X POST http://localhost:3111/agentmemory/recall \ -H Content-Type: application/json \ -d {query:鉴权流程,limit:5}返回里带上你之前会话的记忆片段就说明 3111 端口的 API 和记忆库都工作正常。这一步能帮你把「Claude Code 侧配置问题」和「agentmemory 服务问题」区分开——如果 curl 能召回但 Claude Code 里 recap 没反应问题多半在 MCP 接入那一层而不是记忆库本身。5. 常见报错排查401、local proxy failed 与空 Viewer配置过程中有几类报错出现频率很高逐个拆。401 Unauthorized。这个基本都出在 Key 或 base URL 上。先确认~/.agentmemory/.env里的OPENAI_API_KEY是 TaoToken 控制台生成的 Key没有多余空格或换行再确认OPENAI_BASE_URL是https://taotoken.net/api结尾不要多加/v1之类的路径协议层会自己拼。Claude Code 侧如果也报 401检查.claude/settings.json里的ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL是否和 agentmemory 用的是同一套。两边 Key 不一致是常见坑。local proxy failed。这个报错通常意味着 agentmemory 尝试连 LLM endpoint 时网络层没通。先curl https://taotoken.net/api看能不能拿到响应排除本机网络问题再确认没有其他进程占用 3111 端口lsof -i :3111。如果服务启动日志里就有 proxy 相关报错多半是.env文件格式问题比如用了中文引号或者变量名拼错。重新按第 3 节的 heredoc 写一遍最稳。reading choices 报错。这类错误一般出现在解析 LLM 返回结构时说明请求发出去了但返回体不符合预期。常见原因是 Model ID 填错或者 base URL 指向了一个不兼容 OpenAI 响应格式的地址。把ANTHROPIC_MODEL换成你账号下确实可用的模型 ID再试一次。Viewer 打开是空的。前面提过会话没结束就不会有数据。另外确认你打开的是http://localhost:3113而不是 31113111 是 API 端口浏览器直接打开不会有界面。如果会话确实结束了还是空去启动终端看有没有 hook 执行失败的日志。connect 提示 already wired。说明这个项目或全局已经配置过。想覆盖重写agentmemory connect claude-code --force重启电脑后服务不在了。手动跑的服务不会自启要么每次手动agentmemory要么执行agentmemory service install固化成系统服务。OAuth 相关报错。如果你之前用订阅方式登录过 Claude Code切到 API Key 通道时可能残留 OAuth 凭证导致冲突。清掉旧的登录态确保走的是 settings 里的 Key 而不是缓存凭证。排查顺序建议固定成先 curl 健康检查 → 再 curl 召回接口 → 再看 Claude Code 会话 → 最后看 Viewer。从底层往上排能最快定位是哪一层断了。6. 把统一 Key 通道固定下来的几个实操建议跑通之后有几件事值得顺手做掉能省后面很多事。第一把~/.agentmemory/.env的权限收紧里面是明文 Keychmod 600 ~/.agentmemory/.env第二项目级.claude/settings.json建议加进.gitignore别把 Key 提交上去。团队协作时用环境变量注入而不是把 Key 写死在文件里。第三agentmemory 的记忆压缩是可选功能如果你暂时不想接 LLM纯 BM25 模式也能用召回靠关键词匹配基础功能完整。等确实需要结构化记忆了再补 LLM 配置不用一上来就全配齐。第四多项目场景坚持用项目级接入各项目记忆隔离避免 A 项目的约定污染 B 项目的召回结果。全局接入适合单项目或者你确实希望所有会话共享一份记忆的情况。第五Key 和 endpoint 统一到 TaoToken 之后Claude Code 和 agentmemory 共用一套凭证轮换 Key 时只需要改一处。控制台里生成和管理 Key 的入口在这里https://taotoken.net/api-keys 接入细节和字段说明看文档https://taotoken.net/doc 。想先验证模型通道是否正常可以直接在模型对话页发一条请求试https://taotoken.net/chat 。如果你打算长期用编码 Agent 跑项目Coding Plan 那条线更适合持续使用https://taotoken.net/coding-plan 。最后提醒一个容易忽略的点agentmemory 的记忆质量取决于会话里产生的信息密度。如果你每次会话都只问一句「帮我改个 bug」然后关掉记忆库里攒不下什么有用的东西。真正让长期记忆发挥作用的用法是在会话里把项目约定、架构决策、踩过的坑讲清楚让 agentmemory 有东西可压缩、可召回。工具搭好了喂给它什么决定了它下次能还给你什么。