1. 单二进制 ai-memory 为什么值得单独讲MCP、HTTP、wiki 与 SQLite 索引都在一个进程里你在 Claude Code 里把重构做到一半关掉会话切到 Codex结果新会话连src/agent/router.ts为什么拆成两层都不知道。更具体一点Claude Code 的会话上下文只存在于当前进程关闭即清空Codex 重新进入同一目录时不会读取 Claude Code 的历史。要让它们共享记忆需要一个常驻的、按项目隔离的记忆服务——ai-memory。它把会话观察洗成 Markdown wiki落在 git 仓库里并用 SQLite 做索引。本文不铺热点只讲单二进制架构怎么跑起来以及 TaoToken 在这里只负责一件事给 ai-memory 的 LLM provider 供 Key。Key 到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_intro 拿Base URL 填https://taotoken.net/api。ai-memory 最值得先讲清楚的是它的“单二进制”形态。很多记忆工具会拆成向量库、后端服务、同步器、Web 前端好几块装完先要维护一套依赖。ai-memory 不是这个路线同一个二进制进程里同时提供 MCP 服务与 HTTP 服务数据目录下就是wiki/的 Markdown 源文件和index.sqlite的 SQLite 索引。你不需要额外跑一个向量数据库也不需要为了记一条决策专门去“写一条笔记”。MCP 入口给 Claude Code、Codex、Cursor 这类支持 MCP 的客户端用HTTP 入口给不支持 MCP、但能发 HTTP 请求的工具用还有一个只读的/web界面用来浏览项目树、全文检索和渲染 Markdown。这个架构直接决定了 Token 消耗的位置。ai-memory 自己不会因为采集会话就调用大模型。零 LLM 模式下钩子照样采集会话检索退化为 SQLite FTS5 全文检索加显式声明的实体与图邻域摘要由规则生成。只有当你开启页面合并、矛盾检测、自动改进这类能力时ai-memory 才会作为 LLM provider 的客户端去消耗 Token。也就是说TaoToken 的 Key 不是填给“ai-memory 本体”的而是填给“ai-memory 要调用的那个 LLM provider”的。这一点如果搞混后面配置很容易串味。单二进制还带来一个实际好处项目隔离很直接。ai-memory 按 git 仓库根映射到独立目录每个项目用稳定的 UUID 分组。同一个仓库的不同 worktree 共享同一个项目身份重命名项目只涉及一条字段更新删除项目直接rm -rf对应目录不会影响其他项目。这比在数据库里维护多租户关系简单得多也更容易审计Markdown 能用grep搜能拖进 Obsidian能用rsync备份git 本身还能给你版本记录。2. 先把服务跑起来Docker / 原生二进制启动命令与数据目录结构先不要急着接 LLM。推荐第一步用零 LLM 模式跑通采集、检索和 Web 浏览确认数据确实落了盘再决定要不要开页面合并和矛盾检测。这样即使不填任何 API Keyai-memory 也能工作只是摘要和合并能力弱一些。原生二进制方式适合 macOS、Linux 和 WSL2。把ai-memory放进PATH后初始化数据目录并启动服务# 初始化默认数据目录通常在 ~/.ai-memory ai-memory init --data-dir $HOME/.ai-memory # 启动常驻服务默认只绑定本地回环避免局域网暴露 ai-memory serve \ --bind 127.0.0.1:8787 \ --data-dir $HOME/.ai-memory如果你更想先体验 Docker思路是把数据目录挂进容器并把端口只映射到本机回环# 镜像名请以你本地构建或官方发布名为准这里用 ai-memory:latest 代称 docker run -d \ --name ai-memory \ -p 127.0.0.1:8787:8787 \ -v $HOME/.ai-memory:/data \ -e AI_MEMORY_DATA_DIR/data \ ai-memory:latest serve启动后先看状态ai-memory status --data-dir $HOME/.ai-memory数据目录结构大体如下。不同版本可能在子目录命名上有差异但核心就两块wiki/是 Markdown 源index.sqlite是索引。~/.ai-memory/ ├── config.toml ├── queue/ │ └── pending.jsonl ├── projects/ │ └── 6f1c0d2e-9a7b-4c3d-8e1f-2a5b6c7d8e9f/ │ ├── meta.json │ ├── wiki/ │ │ ├── index.md │ │ ├── decisions/ │ │ ├── rules/ │ │ └── sessions/ │ └── index.sqlite └── web/ └── index.htmlqueue/pending.jsonl是本地队列。会话钩子采集到的观察先进入这里敏感内容会在进入本地队列之前被 native hook 拦截。wiki/下面是普通 Markdown你可以直接用编辑器打开也可以提交到项目仓库。index.sqlite负责全文检索和实体匹配。/web是只读浏览界面适合不想开编辑器时快速查历史。接助手的时候原则是ai-memory 先常驻再把客户端接上来。不同客户端接入命令名称可能不同但流程一致——安装钩子、确认会话事件写入本地队列、在下一个会话开始前读取 handoff。可以用以下命令检查采集是否正常ai-memory status --data-dir $HOME/.ai-memory ai-memory search 上次为什么拆 router --data-dir $HOME/.ai-memory如果你用的工具没有真正的“会话结束”钩子比如 Codex、Grok 这类就需要手动收尾。手动 finalize 不会调用 LLM除非你已经开启了 LLM 合并或矛盾检测。ai-memory finalize-session --data-dir $HOME/.ai-memory对于已经有历史的项目不需要从今天开始重新积累。跑一次 bootstrap它会读 git log、README、docs 和模块头把既有历史总结成种子页面。这个步骤是否消耗 Token取决于你有没有开 LLM 模式零 LLM 模式下它用规则生成摘要。ai-memory bootstrap \ --repo /path/to/your/repo \ --data-dir $HOME/.ai-memory3. TaoToken Key 只填在 LLM provider 这一层零 LLM 与开 LLM 的对照这是最容易配错的地方。ai-memory 本身是记忆服务不是模型客户端它只在开启“页面合并、矛盾检测、自动改进”这类能力时才会调用 LLM provider。因此 Key 的填写位置应该是 ai-memory 的 provider 配置而不是 ai-memory 的采集配置。零 LLM 模式下完全不需要 Key采集、FTS5 检索、实体图邻域、规则摘要都能跑。对照关系可以记成下面这张表模式是否采集会话是否调 LLM是否需要 TaoToken Key检索能力零 LLM 模式是否不需要FTS5 实体/图邻域规则摘要开 LLM 合并是是需要填给 provider全文检索 页面合并 矛盾检测开 LLM 矛盾检测是是需要填给 provider同上额外标记冲突只接 MCP/HTTP 客户端是取决于 ai-memory 配置不一定取决于是否开 LLM如果你决定开启 LLM 能力TaoToken 的 Key 只填在 ai-memory 的 LLM provider 环境变量里。Anthropic 兼容方式可以这样写export AI_MEMORY_LLM_PROVIDERanthropic export ANTHROPIC_API_KEYYOUR_API_KEY export ANTHROPIC_BASE_URLhttps://taotoken.net/api ai-memory serve \ --bind 127.0.0.1:8787 \ --data-dir $HOME/.ai-memory如果你更习惯 OpenAI 兼容协议也可以用对应的 provider 变量。关键是 Base URL 统一指向 TaoTokenexport AI_MEMORY_LLM_PROVIDERopenai export OPENAI_API_KEYYOUR_API_KEY export OPENAI_BASE_URLhttps://taotoken.net/api ai-memory serve \ --bind 127.0.0.1:8787 \ --data-dir $HOME/.ai-memory注意这里的ANTHROPIC_*是给 ai-memory 的 provider 用的不是让你把它抄到 Codex 的配置里。Codex 不读ANTHROPIC_*强行套用只会出现 Key 不识别、provider 不匹配、请求 401 之类的问题。TaoToken 的 Key 和 Base URL 到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_llm_provider 获取创建后填YOUR_API_KEY的位置。还有一个边界要强调ai-memory 检索返回的页面内容是“证据”不是“指令”。它告诉你上次怎么想的但不能替代你阅读当前代码、运行测试。涉及数据库、生产环境、部署脚本的操作不要让 MCP/Agent 直连 Oracle 或生产库SQL 和命令由你在本地终端执行再把结论写回项目规则或决策页。这样既保留记忆又不把记忆当成执行授权。4. Claude Code / Codex / CC Switch 的配置别串味ANTHROPIC_* 与 config.toml 分开写ai-memory 支持一批主流客户端包括 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、Devin、Kiro、Grok Build CLI、Kimi Code、Zed仅 MCP、VS Code Copilot仅 MCP等。接入 ai-memory 是一件事把客户端本身接到 TaoToken 是另一件事。两者配置不要互相覆盖。Claude Code 用settings.json走ANTHROPIC_*这一套。典型配置如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5 } }把这段放进 Claude Code 的settings.json后重启会话。模型名按你在 TaoToken 模型对话页选定的模型替换不要照抄一个不存在的 ID。Claude Code 文档在文末 CTA 里配置有疑问先看文档。Codex 用config.toml不要用ANTHROPIC_*。它走的是 OpenAI 兼容 provider 配置典型写法如下model_provider taotoken model gpt-4o [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat然后在环境变量里提供 Keyexport TAOTOKEN_API_KEYYOUR_API_KEY这里的env_key TAOTOKEN_API_KEY是告诉 Codex 去读哪个环境变量不是让你在 TOML 里直接写 Key。这样配置和 ai-memory 的 provider 配置互不干扰。如果你用 CC Switch 这类切换工具把它当成“客户端配置管理器”。三件套建议统一为Base URL: https://taotoken.net/api API Key: YOUR_API_KEY Model: claude-sonnet-4-5其中 Model 换成你实际要用的模型。CC Switch 只负责切换客户端配置不参与 ai-memory 的采集和索引。ai-memory 是否消耗 Token仍然由它自己的 LLM 模式开关决定。5. 把 ai-memory 接进现有项目bootstrap、finalize、检索与 Web 只读界面真正让 ai-memory 有用的不是装完那一刻而是把它接进日常开发循环。建议按下面的顺序落地。第一步在项目根目录确认 git 仓库身份。ai-memory 按 git 仓库根映射项目同一个仓库的不同 worktree 共享同一个项目身份。你在主 worktree 里记录的历史切到另一个 worktree 也能看到。cd /path/to/your/repo git rev-parse --show-toplevel第二步对老项目跑 bootstrap。它会读 git log、README、docs 和模块头把既有历史总结成种子页面。注意这是“总结既有历史”不是“替你做决策”。生成的页面仍然是 Markdown你可以手动改。ai-memory bootstrap \ --repo /path/to/your/repo \ --data-dir $HOME/.ai-memory第三步正常开 Claude Code 或 Codex 会话。每次提示和工具调用会自动落进 ai-memory。对于没有会话结束钩子的工具记得手动收尾ai-memory finalize-session --data-dir $HOME/.ai-memory第四步用检索查历史决策。比如你想知道“当时为什么选 Postgres”可以用全文检索加实体匹配ai-memory search 为什么选 Postgres \ --data-dir $HOME/.ai-memory \ --explain--explain这类参数可以让你看到每条结果排在这个位置的原因。不同版本参数名可能有差异核心是“检索 可解释排序”。第五步写常驻笔记。有些内容值得超出自动会话日志单独留存例如一条决策、一条约定、一个踩过的坑。你可以让助手“把这条记成项目规则”它就会写一页带 git 版本号的 wiki 页。之后这页会一直出现在检索结果里直到你主动修改。第六步用只读/web界面浏览。启动服务后访问http://127.0.0.1:8787/web可以看项目树、全文检索、Markdown 渲染。它不提供写入所以不会误改数据。隐私方面仓库内可以声明忽略规则。匹配路径的采集事件会在写入本地队列前被丢弃也可以反向配置为仅在有标记的文件内采集。敏感内容由 native hook 在进入本地队列之前拦截。这个顺序很重要不是先写进库再过滤而是进入本地队列之前就拦掉。项目隔离方面删除一个项目直接rm -rf对应目录即可不影响其他项目。重命名只涉及元数据字段更新。如果你只是不想让某个项目继续采集优先用忽略规则不要直接删全局数据目录。6. 常见故障排查端口、数据目录、Key 未生效、钩子没跑问题一服务启动后curl 127.0.0.1:8787不通。先看端口占用和绑定地址。ss -ltnp | grep 8787 ai-memory status --data-dir $HOME/.ai-memory默认只绑回环是安全设计不要为了图方便改成0.0.0.0暴露到公网。单用户笔记本上本地访问就够了。问题二数据目录没权限。Docker 方式最容易出现宿主机目录归属和容器用户不一致。确认挂载目录可写ls -la $HOME/.ai-memory test -w $HOME/.ai-memory echo writable问题三开了 LLM 合并但 Key 不生效。先确认 Key 是填给 ai-memory 的 provider而不是填在 Claude Code 或 Codex 的客户端配置里。两者是不同进程。检查环境变量env | grep -E AI_MEMORY_LLM_PROVIDER|ANTHROPIC_BASE_URL|OPENAI_BASE_URLBase URL 应为https://taotoken.net/apiKey 为YOUR_API_KEY的实际值。如果你只是想先跑通把AI_MEMORY_LLM_PROVIDER去掉回到零 LLM 模式采集和 FTS5 检索仍然可用。问题四Codex 没有自动 finalize。Codex 这类工具没有真正的会话结束钩子需要手动跑ai-memory finalize-session。你可以在每天收工前执行一次或者把它写进 shell 函数。ai-memory finalize-session --data-dir $HOME/.ai-memory问题五Claude Code 改了settings.json但没生效。Claude Code 通常在启动时读取配置改完要重启会话。确认 JSON 没有尾逗号ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY都在env对象里。问题六记忆检索结果和当前代码不一致。这是预期边界。ai-memory 检索返回的是历史证据不是权威指令。落地前以当前代码库为准配合 LSP、符号检索等活的结构化工具使用。涉及数据库操作不要在 MCP/Agent 里直连生产库本地执行 SQL把结论写回 wiki。如果你在排障时需要重新创建 Key 或确认模型 ID可以到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_troubleshoot 查看控制台。官网、模型对话、Coding Plan、API Keys、Claude Code 文档这几个入口按下面顺序走。7. 从模型对话到 Claude Code 文档按这条路径把 Key 和 Base URL 落到位如果你还没开始建议按高转化路径走一遍不要一上来就开 LLM 合并。先跑零 LLM 模式确认 ai-memory 单二进制服务、wiki、SQLite 索引都正常再决定要不要开页面合并和矛盾检测。第一步模型对话。先确认你要用哪个模型以及这个模型在 TaoToken 上的调用方式。入口https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_chat第二步Coding Plan。如果你准备把 Claude Code、Codex 这类工具长期接到项目里先看 Coding Plan 的额度与模型覆盖再决定 ai-memory 是否开启 LLM 合并。入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_plan第三步创建 API Key。创建后把YOUR_API_KEY替换成真实 Key。这个 Key 只填给 LLM provider不填给采集钩子。入口https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_keys第四步Claude Code 文档。如果你用 Claude Code按文档写settings.json的ANTHROPIC_*如果你用 Codex按config.toml写model_providers.taotoken不要把ANTHROPIC_*套过去。入口https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentai_memory_claude_code最后再回到 ai-memory 这一侧零 LLM 模式先跑采集确认~/.ai-memory/projects/uuid/wiki/和index.sqlite有数据需要页面合并或矛盾检测时再把AI_MEMORY_LLM_PROVIDER、ANTHROPIC_API_KEY或OPENAI_API_KEY、Base URL 填成 TaoToken。这样 Token 消耗方和执行路径都清楚采集不耗LLM 合并/矛盾检测才耗TaoToken 只给 LLM provider 供 KeyBase URL 固定为https://taotoken.net/api。