企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_content=ai_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 Key，ai-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.html

queue/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-memory"

3. TaoToken Key 只填在 LLM provider 这一层：零 LLM 与开 LLM 的对照

这是最容易配错的地方。ai-memory 本身是记忆服务，不是模型客户端；它只在开启“页面合并、矛盾检测、自动改进”这类能力时，才会调用 LLM provider。因此 Key 的填写位置应该是 ai-memory 的 provider 配置，而不是 ai-memory 的采集配置。零 LLM 模式下完全不需要 Key，采集、FTS5 检索、实体图邻域、规则摘要都能跑。

对照关系可以记成下面这张表：

如果你决定开启 LLM 能力，TaoToken 的 Key 只填在 ai-memory 的 LLM provider 环境变量里。Anthropic 兼容方式可以这样写：

export AI_MEMORY_LLM_PROVIDER=anthropic export ANTHROPIC_API_KEY=YOUR_API_KEY export ANTHROPIC_BASE_URL=https://taotoken.net/api ai-memory serve \ --bind 127.0.0.1:8787 \ --data-dir "$HOME/.ai-memory"

如果你更习惯 OpenAI 兼容协议，也可以用对应的 provider 变量。关键是 Base URL 统一指向 TaoToken：

export AI_MEMORY_LLM_PROVIDER=openai export OPENAI_API_KEY=YOUR_API_KEY export OPENAI_BASE_URL=https://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_source=taotoken_aicg_blog_end&utm_content=ai_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"

然后在环境变量里提供 Key：

export TAOTOKEN_API_KEY=YOUR_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_URL'

Base URL 应为https://taotoken.net/api，Key 为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_source=taotoken_aicg_blog_end&utm_content=ai_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_source=taotoken_aicg_blog_end&utm_content=ai_memory_chat

第二步，Coding Plan。如果你准备把 Claude Code、Codex 这类工具长期接到项目里，先看 Coding Plan 的额度与模型覆盖，再决定 ai-memory 是否开启 LLM 合并。入口：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=ai_memory_plan

第三步，创建 API Key。创建后把YOUR_API_KEY替换成真实 Key。这个 Key 只填给 LLM provider，不填给采集钩子。入口：

https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=ai_memory_keys

第四步，Claude Code 文档。如果你用 Claude Code，按文档写settings.json的ANTHROPIC_*；如果你用 Codex，按config.toml写model_providers.taotoken，不要把ANTHROPIC_*套过去。入口：

https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=ai_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 供 Key，Base URL 固定为https://taotoken.net/api。