ai-memory:基于 Rust 的 AI 编码代理长期记忆项目

面向 AI 编码代理的长期记忆。在任务中途退出 Claude Code，在同一目录启动 OpenAI Codex，也能继续推进，而无需重新解释架构、已失败的方案或尚未解决的问题。

支持矩阵

范围	状态	说明
Linux	已支持	主要面向 Docker/服务器场景及 CI 平台。已发布的 Docker 镜像支持 linux/amd64 和 linux/arm64。原生 Arch/AUR 软件包包含系统和用户级 systemd 单元。
macOS	已支持	工作区测试在 CI 中运行；带标签的版本会发布原生 ai-memory-macos-aarch64.tar.gz 和 ai-memory-macos-x86_64.tar.gz 二进制文件。Apple Silicon 上推荐使用原生二进制文件。详见 docs/macos.md。
Windows via WSL2	已支持	当编码代理运行在 WSL2 中时，使用 WSL2 内的 Linux 安装路径。
Native Windows	实验性	带标签的版本会发布包含 ai-memory.exe 的 ai-memory-windows-x86_64.zip；也可使用 Docker Desktop 封装和源码构建。本地受支持的配置默认使用宿主原生 hook 命令；Claude Code 可能会使用其 Windows exec 形式，而其他编码代理会使用与其 hook schema 匹配的原生单命令字符串。PowerShell/Git Bash 脚本作为兼容性回退方案。详见 docs/windows.md。
Claude Code	已支持	MCP 配置 + 生命周期钩子；原生命令强制执行捕获排除规则。install-mcp --session-aware 可选择通过本地 stdio 桥接启用按会话的自动作用域隔离。当以 --capture-assistant 安装且服务器启用 capture_assistant 时，可选择在 Stop 时捕获助手的最后一轮内容（双重显式开启，默认关闭）。
Codex	已支持	MCP 配置 + 生命周期钩子；原生命令强制执行捕获排除规则。没有自动的真实会话结束钩子，因此当需要最终总结/交接时，请运行 ai-memory finalize-session。
Command Code	已支持	MCP 配置（~/.commandcode/mcp.json）+ 其四个稳定的生命周期钩子事件（~/.commandcode/settings.json）；原生命令强制执行捕获排除规则，SessionStart 会注入交接内容。Stop 仅表示轮次边界，因此请在最终一轮结束后使用 ai-memory finalize-session --agent command-code。ai-memory run command-code 增加精确的 v3 原生会话恢复和可见事件导入；实验性的未沙箱化 Mods 仍被排除。
Devin CLI	已支持	MCP 配置 + 生命周期钩子。钩子使用 Devin 的 PostCompaction 事件，通过 hookSpecificOutput.additionalContext 注入交接内容；由于 Devin 未暴露子代理事件，因此省略子代理事件。
OpenCode	已支持	远程 MCP 配置 + 生成的 TypeScript 插件；生成的插件强制执行捕获排除规则。
Cursor	已支持	MCP 配置 + 生命周期钩子。
Gemini CLI	已支持	MCP 配置 + 生命周期钩子。
Oh My Pi / OMP	已支持	使用 --client omp / --agent omp（或 oh-my-pi）获得原生 .omp MCP 配置 + TypeScript 扩展；生成的扩展强制执行捕获排除规则。
Pi	已支持	生成的 ~/.pi/agent/extensions/ai-memory-pi.ts 扩展提供生命周期捕获和 HTTP MCP 桥接；生成的扩展强制执行捕获排除规则。
Crush	仅托管模式	ai-memory run crush 恢复其项目本地会话数据库，并通过临时受支持的全局上下文文件提供可移植上下文；不提供生命周期钩子安装器。
Managed workstreams	可选启用	ai-memory run 为 Claude Code、Codex、OpenCode、Pi、Crush、Kimi Code、Command Code、两个不兼容的 Kiro CLI 引擎、OMP、Grok Build CLI 和 Antigravity CLI 提供透明的跨 harness 连续性。直接启动保持不变。详见 docs/managed-workstreams.md。
Claude Desktop	仅 MCP	使用 mcp-remote；没有生命周期钩子。
OpenClaw	已支持	MCP 配置 + 原生插件生命周期钩子；生成的插件强制执行捕获排除规则。
Antigravity CLI	已支持	MCP 配置（serverUrl）+ 生命周期钩子（agy 别名）。只有 invocationNum = 0 的 PreInvocation 会映射到 SessionStart；后续模型调用无法使用下一会话的交接内容。没有自动的真实会话结束钩子，因此当需要总结、交接和可选的 SessionEnd 归并时，请在最终一轮结束后运行 ai-memory finalize-session --agent antigravity-cli。ai-memory run antigravity（别名 antigravity-cli、agy）通过 --conversation 增加托管工作流恢复；由于对话文本不会被解码，该 harness 的账本来自钩子捕获。
Grok Build CLI	已支持	MCP 配置（install-mcp --client grok → $GROK_HOME/config.toml，默认 ~/.grok/config.toml）+ 生命周期钩子（install-hooks --agent grok → $GROK_HOME/hooks/ai-memory.json，默认 ~/.grok/hooks/ai-memory.json，Grok 专用 hook 包）。捕获可用；没有钩子交接注入——Grok 会忽略 SessionStart 的 stdout，因此通过 MCP memory_handoff_accept 恢复交接。ai-memory run grok 增加托管工作流恢复，并通过 --rules 原生投递上下文包。Skills 根目录：.grok/skills / $GROK_HOME/skills（默认 ~/.grok/skills）。
Swival CLI	仅 MCP	install-mcp --client swival --apply 会将一个原生 HTTP 条目合并到项目根目录的 .swival/mcp.json 中，并保留同级服务器。由于 Swival 的回调契约未暴露稳定的会话标识符，因此暂不声明生命周期和托管工作流支持。
Zero	已支持	install-mcp --client zero（~/.config/zero/config.json 中的原生 HTTP + bearer）+ 通过 install-hooks --agent zero --apply 配置的生命周期钩子（~/.config/zero/hooks.json 中的 exec-form 原生命令，JSON 载荷经 stdin 传入，不使用 shell）。捕获可用，包含专家（子代理）事件；没有交接注入——Zero 会丢弃 sessionStart 的 stdout，因此通过 MCP memory_handoff_accept 恢复交接。
ZCode	仅 MCP	install-mcp --client zcode --apply 会将一个原生 HTTP 条目（严格 schema：仅 type/url/headers）合并到 ~/.zcode/cli/config.json 的 mcp.servers 映射中，并保留同级服务器。生命周期钩子尚不可用——见 #512。
Kimi Code	已支持	MCP 配置（~/.kimi-code/mcp.json 中的 url 条目）+ 生命周期钩子（~/.kimi-code/config.toml 中的 [[hooks]]，共 10 个事件，包括子代理开始/停止以及用于工具失败捕获的 PostToolUseFailure）；两条路径均遵循 $KIMI_CODE_HOME。交接通过 UserPromptSubmit 的 stdout 注入（Kimi Code 会丢弃 SessionStart 钩子 stdout）；ai-memory run kimi 增加托管工作流恢复。
Kiro CLI	已支持	MCP 配置使用 install-mcp --client kiro-cli（别名 kiro）和 Kiro 的 Bedrock 兼容 schema 变体。install-hooks --agent kiro-cli 会将 v2 钩子合并到现有编码代理配置中；显式指定 --agent kiro-cli-v3 会写入不兼容的独立 v3 注册项。两者都会保留无关条目、遵循 $KIRO_HOME、强制执行捕获排除规则，并在会话开始时注入待处理交接。Kiro 没有真正的 SessionEnd 钩子；请使用 ai-memory finalize-session --agent kiro-cli，并发会话时添加 --session-id <uuid>。ai-memory run kiro 管理 v2；如需版本安全的 v3 恢复，请添加 --v3、--mode 或 --agent-engine v3。
Pool	仅钩子	Poolside Agent CLI（pool）。通过 install-hooks --agent pool（别名 poolside）进行生命周期钩子捕获：Pool 会从仓库根目录的 .poolside/settings.yaml 读取项目范围钩子，因此 ai-memory 会准备脚本并打印一个可直接粘贴的 hooks: 片段，而不是写入项目本地文件；原生命令强制执行捕获排除规则。包含五个 Claude 风格事件（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop），没有真正的会话结束——Stop 是轮次边界，因此请在最终一轮结束后运行 ai-memory finalize-session --agent pool。SessionStart 的 stdout 注入尚未得到验证，因此捕获可用，但交接注入不可用——通过 MCP memory_handoff_accept 恢复交接。不声明官方 install-mcp 客户端，也不声明托管工作流（ai-memory run pool）：Pool 的原生会话存储契约尚未得到验证（见 docs/managed-harness-contributions.md）。已针对 Poolside CLI v1.0.16 验证。
ZCode	仅钩子	ZCode（z.ai、zcode，别名 zai）。通过 install-hooks --agent zcode --apply 进行生命周期钩子捕获：exec-form 原生命令（type: "process"，不使用 shell）会合并到 ~/.zcode/cli/config.json 的根 hooks 块中，并包裹任何第三方钩子；原生命令强制执行捕获排除规则。包含六个已文档化的触发器（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、Stop）；当工具抛出异常时，PostToolUseFailure 会替代 PostToolUse 触发，并落在同一捕获通道中，同时保留错误。PermissionRequest 故意不安装——其钩子链会与交互式权限客户端竞争，因此按设计无法可靠地被动捕获该事件。没有真正的会话结束——Stop 是每轮边界，因此请在最终一轮结束后运行 ai-memory finalize-session --agent zcode。与 Pool 和 Zero 不同，SessionStart 的 stdout 注入可用（hookSpecificOutput.additionalContext，已针对嵌入式引擎 v0.16.5 实测验证），因此上一会话的交接会自动投递。尚未声明官方 install-mcp 客户端，也尚未声明托管工作流。
VS Code Copilot	仅 MCP	使用 .vscode/mcp.json 支持 Copilot 代理模式；没有生命周期钩子（Copilot 尚未暴露这些钩子）。
Zed	仅 MCP	在 Zed 用户 settings.json 的 context_servers 下配置原生远程 MCP；不支持生命周期钩子或托管工作流。
Hermes Agent	社区	核心钩子接收逻辑可识别 agent=hermes，以及 Hermes 文档中 shell 钩子的 tool_name / tool_input 载荷，用于具体会话归属、工具族标题和捕获排除规则。有一个社区维护的 ai-memory-hermes-plugin 可用，但未附带官方安装器；使用前请审查其兼容性矩阵、安装/卸载脚本和敏感信息处理方式。Hermes 会忽略会话开始钩子的 stdout，因此通过 MCP 恢复交接。
LLM/auth providers	已支持	Anthropic、OpenAI、OpenAI OAuth/Codex、GitHub Copilot、Gemini、OpenCode Zen/Go、OpenAI 兼容端点，以及用于原生钩子的通用 OIDC 设备认证。
Embedding providers	已支持	OpenAI、Voyage、Google Gemini，以及无需密钥的 OpenAI 兼容端点，例如 Ollama、LM Studio 和 vLLM。

使用场景

• “退出 Claude Code，并在 Codex 中继续同一项工作。” 当你希望恢复原生会话，同时获得可移植的可见历史记录，而不是仅仅得到一份交接摘要时，可以使用可选的托管启动器：

  cd /path/to/project
  ai-memory run claude
  
  # 退出 Claude Code，然后在 Codex 中继续同一工作流。
  ai-memory run codex --yolo
  
  # 在 Command Code 中继续，并保留其自身完全一致的原生会话。
  ai-memory run command-code
  
  # 之后，省略名称即可在此恢复最新可用的托管会话。
  ai-memory run
  
  # 在同一工作流中启动新的 Codex 会话，并保留可移植历史。
  ai-memory run --fresh codex
  
  # Kiro 默认使用 v2；若需要使用其不兼容的 v3 引擎，请显式指定一次。
  ai-memory run kiro --v3
  
  # 列出可从当前 checkout 中选择的工作流。
  ai-memory workstreams
  
  # 修正一个你不满意的工作流名称；账本和当前选择保持不变。
  ai-memory rename-workstream --from typo-nmae --to refactor-db
  
  # 从任意已关联的本地 checkout 中选择一个托管工作流，然后恢复它。
  ai-memory resume
  
  # 列出未完成的跨 agent 交接，最早优先，并显示 id；
  # `memory_handoff_cancel` 可用该 id 清除过期项。
  ai-memory handoffs
  

• “选择项目，而不是记住它在哪里。” 从一个包含多个 checkout 的目录开始，在进入托管 harness 之前先选择要使用的 checkout：

  ai-memory show
  
  # 以机器可读方式发现可用项目，不启动任何进程。
  ai-memory show --json
  

  每次成功执行 ai-memory run 都会保存一个客户端本地的 checkout 链接，其键由配置的服务器、workspace 和 project 组成。show 会将这些链接与服务器公开的公开活动及页面数量元数据关联起来。对当前目录还会进行一次快速、限定深度的 1 层扫描，以发现带有项目标记的新 checkout（如 .git、Cargo.toml、package.json、go.mod、pyproject.toml 等），同时跳过依赖目录和构建目录。服务器从不暴露 checkout 路径，因此两台客户端机器可以安全地为同一项目在远程家庭服务器上使用不同的本地路径。

  列表始终以 + New project 开头：输入名称后，ai-memory 会校验一个可移植的目录名，私有地暂存新的 checkout，在 .ai-memory.toml 中固定其 workspace 和 project，并为所选 agent 安装路由块和托管 Agent Skills。只有当所有设置步骤都成功时，最终目录才会出现，然后 show 从该目录启动。

  harness 菜单只提供主机上实际已安装的 agent，并使用与 run 启动时执行相同的 PATH 查找。

  --no-scan 只使用已保存的链接；--workspace 会过滤两种来源；--yolo、--fresh 以及末尾的原生参数会原样转发。非终端使用必须传入 --json；JSON 模式只用于发现，不会启动任何 harness。

  第一次显式运行时，可以提供来自此确切 checkout 的现有会话，也可以启动一个新会话。切换 harness 时，会启动或恢复与共享工作流关联的原生会话，因此过时的本地会话无法覆盖更新的跨 harness 历史。正常退出后，如果上一个启动器仍在收尾，下一次启动会短暂等待；已处理的失败会立即释放工作流。如果关联的原生 transcript 已被删除，ai-memory 会在启动前检测到孤儿状态并重新开始；--fresh 可强制某一 harness 执行该恢复流程。托管模式当前支持 Claude Code、Codex、OpenCode、Pi、Crush、Kimi Code、Command Code、Kiro CLI v2/v3、OMP、Grok Build CLI 和 Antigravity CLI；直接启动 harness 的行为保持不变。参阅 Managed cross-harness workstreams。

• “把我恢复到上次所在的地方。” 从任意目录开始，无需输入名称，也无需阅读列表：

  ai-memory continue
  

  它会选择托管启动时间最近的那个 checkout，重新校验路径及其解析后的 scope，然后以与仅 ai-memory run 完全相同的方式继续。如果某个链接对应的目录已移动、已被替换、现在解析到了不同项目，或其排序时间戳损坏，则会在 stderr 中报告并跳过，因此恢复操作不会悄悄落入错误项目。--workspace 可缩小搜索范围；--yolo 和 --fresh 会被转发。

• “让我选择要恢复哪个工作流。” 从任意目录开始，从有效客户端本地托管 checkout 中选择最近的工作流之一：

  ai-memory resume
  ai-memory resume --workspace work
  

  选择器会显示工作流名称、项目 scope、活动情况和关联的 harness。使用上/下方向键（或 j/k）选择工作流，使用左/右方向键切换其启动 harness。每一行都从 auto 开始，以保留正常的会话发现；其他选项是当前在 PATH 中发现的支持的 harness。按 Enter 启动显示的组合。会先重新校验 checkout，而服务器继续接收指纹，而不是本地路径。如果已经身处某个 checkout，且只需要只读列表，请使用 ai-memory workstreams。

• “下午 4 点退出，早上 9 点换另一个 agent 继续。” 经典场景。下一个受支持的 hook 客户端中的 SessionStart hook 会在开头添加一份类型化交接，包含未决问题、后续步骤和会话摘要。Grok 会捕获生命周期事件，但会忽略 SessionStart stdout，因此请让它从交接恢复时调用 memory_handoff_accept。Zero 同样没有 stdout 行为，也必须调用 memory_handoff_accept。

• “六周前我们关于 X 做了什么决定？” 在 agent 中使用 memory_query X，它会将 FTS5 与实体匹配和关联页面扩展融合在一起（如果配置了 embedder，还会加入向量相似度）。若只想在终端中快速进行 FTS5 查询，请使用 ai-memory search X；该管理命令不会运行混合检索流。页面会经过 LLM 整合，因此命中结果是一个连贯的决策页面，而不是原始聊天记录。传入 explain: true 可以看到在项目检索或显式 scope 检索中，每条命中为何排在当前位置。跨项目的 global: true 搜索使用独立的纯 FTS 排序器，并报告该活动流，但不提供每条命中的 RRF 细节。

• “永久记住这件事。” 当某个内容值得保留在自动捕获的会话日志之外时——例如一个决定、一条约定、一个坑——请告诉 agent“保存一条永久笔记：我们针对 X 统一使用 Postgres”或“将此标注为项目规则”，它会调用 memory_write_page 写入一个持久化、由 git 版本管理的 wiki 页面。在终端中对应命令是 ai-memory write-page --path decisions/0007-db.md --body $'# Standardised on Postgres\n\n...' --pinned。--pinned 可使其免于衰减清理；--body 第一行的 H1 会成为页面标题（省略 --title ——它仍会被接受，但 LLM 调用者常常在 JSON 转义上栽跟头，参见 issue #67）。与 handoff（一次性）或自动合成的会话页面（在整合时会被重写）不同，write-page 笔记属于你：它会出现在 memory_query 中，在 /web 中渲染，并且会一直保留，直到你修改它。

• “你找到的那个页面已经过时了。” agent 会调用 memory_feedback，并传入页面路径和一个信号：helpful / not_helpful 用于调节留存机制在多大程度上保留一个可清理的 episodic 页面（它们会改变页面的显著性，而显著性会缩放衰减公式中的时间项）；stale / wrong 会将显著性压到下限，并且使任何当前页面在下一次 memory_lint 报告中作为 feedback_flagged 发现出现。反馈永远不会删除任何内容——它只会降低置信度并标记为待审查——并且它会附加到记录反馈时当前有效的版本，因此后续重写会清除该标记。检索到的页面文本不可信，仅凭它本身永远不会授权反馈。

• “记住这件事，但只到 sprint 结束为止。” 向 memory_write_page 传入 expires_at（RFC3339 或 YYYY-MM-DD = 当天结束，UTC）——或者手动在页面 frontmatter 中写入 expires_at:。超过 TTL 后，页面会从 search/recent/briefing 中消失（向 memory_query 传入 include_expired: true 仍可看到它），下一次 forget sweep 会硬删除该文件及其行。TTL 优先于 pin；memory_lint 会对 pinned + expiring 组合发出警告。

• “这个新项目在 ai-memory 之前已经有数月的历史。” cd /path/to/my-project && ai-memory bootstrap 会收集 git log、README、docs/、模块头、项目规则，并一次性将它们总结为种子 wiki 页面。未来的会话会在此基础上构建。

• “那次会话教会了我们什么持久经验？” 当配置了 LLM provider 后，ai-memory 会为每个项目中新完成的会话运行一个后台自动改进调度器。它会将建议的 wiki 编辑记录到 pending-writes 审计日志中，然后默认立即通过常规 wiki 写入路径批准它们。调度器 tick 不会重叠：如果审查所有项目所需时间超过间隔，下一次 tick 会延迟到当前 tick 完成后再执行。调度和审批是分开的：设置 [auto_improve.scheduler] enabled = false 可停止自动审查；或设置 [auto_improve] require_approval = true，使计划触发的和手动提出的提案都保持 pending，等待人工审查。ai-memory auto-improve --session-id <uuid> 和 MCP memory_auto_improve 仍然可用于手动补跑或针对性重跑。当省略 session_id 时，MCP 工具会选择最新一个尚未持久化自动改进运行的已完成会话，因此重复调用会越过那些短暂被 preflight 跳过的会话；显式指定 ID 则会重跑该会话。ai-memory auto-improve-report --workspace <w> --project <p> 会返回最近自动改进结果的只读 telemetry 报告，不会暂存或创建提案；添加 --stage 可创建一个 pending 报告页面，用于审计/审批。在区分 operator 的部署中，pending 学习提案会按完整的 operator 身份隔离，因此一个人对某个页面的提案不会阻塞另一个人；未归属和单用户部署仍保留共享 pending 队列。参阅 docs/auto-improve-eval-gates.md 中的可执行 eval 评分器示例。

  现有安装无需按项目迁移。调度器会初始化每个项目的首次运行水位线，以免升级后自动审查历史会话，然后记录每个会话的声明，使失败的计划审查不会无限重试；对于你想补跑的历史会话或失败的计划审查会话，请使用手动 auto-improve。旧配置中可能仍包含 [auto_improve] mode = ... 一行；当前 ai-memory 会忽略这个遗留 key，因此你可以在方便时将其移除。

• “我需要考虑哪些整理事项？” ai-memory curator 会对冷 episodic 页面、过期 slot、重复且完全一致的规范化标题，以及悬空的跨项目链接运行一份无需 LLM 的规则维护报告。除非传入 --stage，否则它只输出报告；staging 会为审批暂存一个报告页面，但本身仍不会执行任何维护操作。共享服务器可以选择启用 [decay] breadth_weight，让被多个已识别 operator 强化的页面获得留存加分；默认值 0.0 不会改变现有留存分数。

• “为整个家庭运行一个 ai-memory。” 在家庭实验室机器上以 0.0.0.0:49374 启动服务器，并配置 bearer token；每台笔记本/台式机都连接到它。按 cwd 路由可将每个项目的页面清晰隔离；局域网内任何位置的浏览器都可以访问 /web UI。

• “与队友分享之前，先审查已落地的内容。” 在 http://<server>:49374/web 浏览 wiki——启用 human auth 时，使用用户名和密码登录。可按项目查看树形结构、渲染后的 markdown，以及每个页面可见的取代链。

• “撤销一次糟糕的页面编辑，而不用回滚整个服务器。” ai-memory checkpoints 显示最近的 wiki 提交，然后 ai-memory restore-page --path notes/foo.md --from <rev> 恢复那一个 markdown 文件，并将其重新索引到 SQLite。对于仅存在于数据库中的状态，如 sessions、observations、handoffs、users、audit rows 和 embeddings，完整的 backup / restore 仍然是解决方案。

• “放弃一个实验，保留其余内容。” ai-memory purge-project --project experimental --confirm。原子操作：该项目的数据库行会级联删除，其 wiki 子目录会被 rm -rf 删除，所有兄弟项目按设计不受影响。

快速开始

Arch Linux (AUR)

对于原生 Arch 安装，请使用 AUR 软件包。它们将安装 /usr/bin/ai-memory、打包的 hook 源码，以及系统级和用户级 systemd 单元。

yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source

单用户工作站：

mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory
ai-memory --data-dir ~/.local/share/ai-memory \
  --config ~/.config/ai-memory/config.toml init
systemctl --user enable --now ai-memory.service
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

系统服务安装会通过打包的单元文件使用 /var/lib/ai-memory 和 /etc/ai-memory/。完整的用户服务、系统服务、认证与提供商配置见 docs/install.md#arch-linux-native-packages-aur。

Docker

你需要：Docker + 支持矩阵 中的一种智能体 CLI，或其他任何支持 MCP 的客户端。

已发布的 Docker 镜像包含 linux/amd64 和 linux/arm64 变体，因此 Apple Silicon Mac 和 ARM64 Linux 主机可以直接拉取 akitaonrails/ai-memory，无需通过 --platform linux/amd64 进行模拟。

默认快速开始未启用认证——服务仅绑定回环地址，因此在单用户笔记本上，其他进程无法访问它。若准备将服务暴露到局域网，添加 Bearer 令牌只需一行改动；参见下方安全。

# 1. Install the ai-memory CLI wrapper (a small shell script that
#    runs the binary inside docker with your $HOME mounted). This is
#    the only thing that needs to live on the host filesystem.
mkdir -p ~/.local/bin
wrapper_tmp="$(mktemp -d)"
trap 'rm -rf "$wrapper_tmp"' EXIT
wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper
curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper"
curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256"
expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")"
if command -v sha256sum >/dev/null 2>&1; then
    actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
else
    actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
fi
[ -n "$expected" ] && [ "$actual" = "$expected" ] || { echo "wrapper checksum mismatch" >&2; exit 1; }
install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory
rm -rf "$wrapper_tmp"
trap - EXIT
# Most distros put ~/.local/bin on PATH automatically. If `which
# ai-memory` comes up empty, add this to ~/.bashrc / ~/.zshrc:
#     export PATH="$HOME/.local/bin:$PATH"

# 2. Start the server. `--restart unless-stopped` makes it come back
#    on docker daemon restart and on machine boot (provided your
#    docker service is enabled at boot — `sudo systemctl enable
#    docker` on most distros). Loopback-only bind (`127.0.0.1:49374`)
#    so nothing outside this machine can reach it. Omit the LLM /
#    EMBEDDING lines for zero-LLM mode — FTS5 search still works
#    without any keys.
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    -e AI_MEMORY_EMBEDDING_PROVIDER=openai \
    -e OPENAI_API_KEY=sk-... \
    akitaonrails/ai-memory:latest

# 3. Wire your agent CLI in two commands. The wrapper takes care of
#    mounts and each client's config-path detection. Re-run with
#    `--agent codex`, `--agent command-code`, `--agent devin`, `--agent opencode`, `--agent gemini-cli`,
#    `--agent grok`, `--agent kimi-code`, `--agent kiro-cli`, `--agent omp`,
#    `--agent oh-my-pi`, `--client cursor`,
#    `--client gemini-cli`, `--client grok`, `--client kiro-cli`, etc.
#    for additional agents; full list in docs/install.md.
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply
# Grok Build CLI example:
# ai-memory install-mcp   --client grok --apply
# ai-memory install-hooks --agent  grok --apply
# Kiro CLI v2 example (requires an existing Kiro agent config):
# ai-memory install-mcp   --client kiro-cli --apply
# ai-memory install-hooks --agent  kiro-cli --apply
# Kiro CLI v3 example (standalone hook registration):
# ai-memory install-hooks --agent  kiro-cli-v3 --apply
# Command Code stable MCP + lifecycle example:
# ai-memory install-mcp   --client command-code --apply
# ai-memory install-hooks --agent  command-code --apply
# Pool (Poolside Agent CLI) example — stages scripts and prints the
# .poolside/settings.yaml snippet to paste into each repo (no MCP client yet):
# ai-memory install-hooks --agent  pool --apply
# ZCode (z.ai) example — merges exec-form native commands into the root
# hooks block of ~/.zcode/cli/config.json (handoff injection works; no true
# session-end, so run `ai-memory finalize-session --agent zcode` at the end):
# ai-memory install-hooks --agent  zcode --apply

在 Linux/macOS 上，操作至此即可完成。像往常一样启动一个 Claude Code 会话——现在，每条提示词和每次工具调用都会写入 ai-memory，而你在本项目的下一次会话中，将看到一份交接说明，标明你上次停留的位置。 在 macOS 上，如果你不需要 Docker，原生发布二进制文件也受支持并推荐使用；详见 docs/macos.md。

如果两个 Claude Code 会话并发使用同一服务器，请在服务器上启用按会话路由，并仅将 ai-memory MCP 条目替换为可选桥接：

# <ai-memory data dir>/config.toml
[auto_scope]
mode = "per_session"

ai-memory install-mcp --client claude-code --session-aware --apply

该桥接仍会连接已配置的本地或远程 HTTP 服务器，并转发其 bearer token，但还会将 Claude 的 lifecycle session id 附加到每个 MCP 请求中。现有静态 HTTP 安装仍为默认方式。关于 Claude 的 /clear 和 implicit-resume 限制，请参阅 docs/auto-scope.md。

install-mcp / install-hooks 命令在 AI_MEMORY_SERVER_URL / AI_MEMORY_AUTH_TOKEN 已设置时会使用它们；否则默认使用 http://127.0.0.1:49374（与上述服务器一致），且不携带 bearer token。如果已存在 ai-memory MCP 条目后再安装 hooks，install-hooks 会复用该 endpoint，以避免远程 MCP 配置静默重新生成仅限 loopback 的 hooks。这两个命令都是幂等的：重新执行时会替换 ai-memory 的条目，保留你已配置的所有其他 server / hook，并在每次写入修改前，在文件旁生成带时间戳的 .bak-<ts> 备份。hooks 脚本会自动暂存到 ~/.local/share/ai-memory/hooks/<agent>/；重新运行会覆盖这些脚本，以便未来镜像更新时携带更新后的 hooks。移除 --apply 时，只会打印配置片段，而不会修改文件。对于 Claude Code，CLAUDE_CONFIG_DIR 会将 MCP 注册移至 $CLAUDE_CONFIG_DIR/.claude.json，hooks 移至 $CLAUDE_CONFIG_DIR/settings.json，全局托管 skills 移至 $CLAUDE_CONFIG_DIR/skills。当该目录位于其现有 $HOME bind mount 下时，Docker 包装器会转发该变量。当 Claude 配置根目录位于 $HOME 之外时，请使用原生二进制文件。卸载会同时检查当前生效的重定位路径和 Claude 的 home 默认路径，因此启用该变量不会遗留旧的默认路径 ai-memory 安装。如果你的 agent 经常在仓库子目录或 linked worktrees 中启动，请为 install-hooks 添加 --project-strategy repo-root，以便将 captures 归并到主 git 仓库名；详见 docs/install.md 和 docs/marker-file.md。后续仅使用 --apply 的刷新（包括 ai-memory upgrade）会保留该选择；如需移除，请显式传入 --project-strategy basename。

Docker 包装器还会将 ai-memory status 和 ai-memory bootstrap 等 thin-client 命令桥接回 host 的 loopback 服务器。使用上述本地 Docker 快速启动方式时，无需覆盖 AI_MEMORY_SERVER_URL。

托管 workstreams 是可选项。它们会在宿主机上执行 harness，而 server 可保持本地或远程：

ai-memory run claude
# later, continue the same workstream in another harness
ai-memory run codex --yolo
# omit the name to continue the newest usable local harness session
ai-memory run
# or resume the newest managed checkout without changing directories first
ai-memory continue

若后续要移除 ai-memory，请在相同的主机环境中运行 ai-memory uninstall --apply。它会在匹配对应的 ai-memory 签名后，仅移除由 ai-memory 拥有的配置项、指令块、默认根目录下的受管技能文件以及生成的插件文件；通过 --target-dir 安装的自定义技能根目录需要手动清理。如果使用自定义端点安装了 MCP，请使用 --mcp-url；仅在需要将移除范围缩小到某一条匹配项时，才使用 --mcp-name。

安装说明

• SELinux： 在处于 enforcing 模式的 Linux 主机上，wrapper 会自动为那些会访问绑定挂载主机文件的短生命周期辅助命令添加 --security-opt label=disable。它不会修改长期运行的服务器容器，也不会重新标记 $HOME；不要在整个主目录绑定挂载上添加 :z/:Z。Rootless 引擎也会为这些命令添加 -u 0:0。Docker 和 podman 会在不同的 info 键下报告 rootless 模式和 SELinux 支持情况，两者都会被读取。每当 AI_MEMORY_DATA_DIR 选择主机目录，或显式 --config 读取主机文件时，相同处理同样适用。参见 docs/install.md。
• Windows： 在 WSL2 中使用 Linux 路径，或从 PowerShell/cmd 使用原生 Windows wrapper。本地受支持配置默认使用主机原生命令：Claude Code 可以使用其支持的 ai-memory.exe exec 形式，其他 agent 则使用符合其 hook schema 的原生命令字符串。Docker wrapper 通过 -EncodedCommand 保护 .ps1 回退命令，避免嵌套 PowerShell 展开；升级后请重新运行 install-hooks --agent <agent> --apply，使现有 hook 条目采用当前形式。 PowerShell/Git Bash 脚本包仅为兼容回退方案，不强制 capture-policy v1。不要混用不同的路径环境。参见 docs/windows.md。
• Docker compose： 支持 docker compose -f docker/docker-compose.yml up -d；agent 配置与上文步骤 3 相同。
• 远程服务器： 在客户端安装 MCP/hooks 之前，先设置 AI_MEMORY_SERVER_URL=http://<server-ip>:49374 和 AI_MEMORY_AUTH_TOKEN=<token>。显式 --server-url 参数仍然有效，但在已设置这些环境变量后不再是必需的。任何非 loopback 服务器都应使用 bearer auth。
• 受管启动 wrapper： ai-memory run、ai-memory show、ai-memory continue、ai-memory resume 和 ai-memory workstreams 必须由当前主机 wrapper 拦截，以便本地 checkout、原生 harness 和 session stores 仍可访问。旧版 wrapper 可能将这些命令传入 Docker，导致找不到 checkout 或主机可执行文件。请在 agent 机器上运行 ai-memory upgrade 以刷新它。主机原生 runner 会继承 AI_MEMORY_SERVER_URL、AI_MEMORY_AUTH_TOKEN 以及主机 PATH。
• 升级： 对于 Docker wrapper 安装，请在每台 agent 机器上运行 ai-memory upgrade。它会刷新本地 wrapper、拉取最新 image，并在 ~/.local/share/ai-memory/hooks/<agent>/ 下重新暂存 hook 脚本。原生包/源码安装应在升级 binary 后重新运行 ai-memory install-hooks --agent <agent> --apply。远程/homelab 服务器仍需单独重新部署；本地 wrapper 升级仅更新客户端机器。现有项目 prompt 文件仍可继续使用。当你希望获得新的工具指导时，刷新受管 ai-memory routing package（运行 ai-memory install-instructions，对于基于 AGENTS 的项目可使用 --target AGENTS.md）。刷新过程会从同一 binary 拥有的资源中写入精简的 markered snippet 和受管 Agent Skills。受管技能负载在所有发布平台均使用 LF 换行符，而用户编写的文件保持其现有换行符。

如需查看 支持矩阵 中列出的每个客户端，以及基于 curl 的 hook 安装、源码构建、CLI 环境变量和完整子命令参考，请参见 docs/install.md。

CLI 的 Tab 补全支持 bash、zsh、fish、PowerShell 和 elvish：

ai-memory completions fish > ~/.config/fish/completions/ai-memory.fish

有关其他 shell 的安装路径，请参见 docs/shell-completions.md。

安全

默认仅监听回环地址（127.0.0.1:49374）且无需认证，因为对于单用户笔记本电脑而言这是安全的：机器外部的任何进程都无法访问该服务。

未认证的非回环 HTTP 请求现在会按失败关闭原则被拒绝。请设置 AI_MEMORY_AUTH_TOKEN 或绑定到回环地址；--allow-insecure-no-auth 是仅面向纯 HTTP 的、有意提供的危险例外。认证并不会加密 Bearer 令牌：如需局域网或远程访问，请使用 HTTPS 反向代理指南 中介绍的现成 Caddy 或 Cloudflare Tunnel 模板。

当服务暴露到回环地址之外、同一台机器上存在不受信任的本地进程，或数据目录中保存了敏感项目历史时，请启用 Bearer 认证：

TOKEN=$(ai-memory generate-auth-token)

docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 0.0.0.0:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
    -e AI_MEMORY_ALLOWED_HOSTS="<server-ip>,localhost,127.0.0.1" \
    akitaonrails/ai-memory:latest

ai-memory install-mcp   --client claude-code --apply \
    --server-url "http://<server-ip>:49374/mcp" --auth-token "$TOKEN"
ai-memory install-hooks --agent  claude-code --apply \
    --server-url "http://<server-ip>:49374" --auth-token "$TOKEN"

Bearer 认证用于保护 /mcp、/hook、/handoff、/workstream/*，以及机器对 /admin/* 和 /api/v1/* 的调用。人类用户通过 POST /auth/login 登录；控制台使用 HttpOnly 会话 Cookie，并配合 CSRF 防护，而不是在 localStorage 中使用 Bearer 令牌。/web 下的自定义 SPA HTML 为公共静态资源。 当人类用户认证监听超出回环地址时，必须设置 AI_MEMORY_AUTH__SECURE_COOKIE=true，该设置表示可信 HTTPS 反向代理负责面向浏览器的边缘。它会使会话 Cookie 仅限 HTTPS。应关闭或重定向对该主机名的直接 HTTP 访问。非回环绑定还应设置 AI_MEMORY_ALLOWED_HOSTS，以防范 DNS 重绑定。

繁忙的共享 hook 服务器还可以设置 AI_MEMORY_HOOK_RATE_PER_SEC（每个 actor/session 来源的每秒令牌数），并可设置 AI_MEMORY_HOOK_RATE_BURST，以限制某个失控会话，同时不阻塞无关的 hook 来源。速率未设置或为 0 时，限流器保持禁用。

对于共享服务器，若每位开发者都应验证其自身的 hook 写入，原生 Claude Code hooks 可以使用已存储的 OIDC 设备令牌，而不是内嵌共享静态令牌：

ai-memory auth login oidc-device \
    --issuer "https://issuer.example.com/realms/team" \
    --client-id "ai-memory-cli"

ai-memory install-hooks --agent claude-code --apply \
    --server-url "http://<server-ip>:49374"

OIDC hook 认证要求使用原生 ai-memory hook ... 命令路径。Docker 封装默认保留 shell 脚本 hook；请使用原生发布二进制或源码安装来配置 OIDC。轻量客户端 HTTP 命令（例如 ai-memory status 和 ai-memory search）在未配置静态 AI_MEMORY_AUTH_TOKEN / [auth].bearer_token 时，也会使用已保存的 OIDC access token；若存在静态 bearer，则静态 bearer 仍然优先。这是为支持 OIDC 的网关/桥接器准备的；原生 ai-memory 服务器认证仍接受静态 root bearer / DB-user token，并且 /admin/* 保持仅限 root，除非网关将已接受的 OIDC 认证转换为 ai-memory 可接受的上游认证。

OIDC/Keycloak session id 是登录提供方会话，而不是 ai-memory agent 会话。依赖 [auto_scope] 会话隔离的共享服务器仍需显式指定 workspace + project / scopes，或需要一个桥接器，在 MCP 请求上转发真实的 lifecycle-hook session id。

想要 HTTPS？ ai-memory 有意不自行终结 TLS——正确做法是在其前面部署一个久经考验的反向代理。 docs/https-via-proxy.md 是部署指南，其中包含可直接复制粘贴的 docker compose 模板，位于 docker/compose.tls.caddy.yml（使用 Let's Encrypt 或内部 CA 的 Caddy）以及 docker/compose.tls.cloudflared.yml （Cloudflare Tunnel——无需开放端口）。一旦启用多用户或将服务绑定到 loopback 之外，两者都推荐使用。快速入门中单用户且仅绑定 loopback 的顺畅路径不需要 TLS——指南中已明确说明该场景，以免在不必要的地方增加额外流程。

多用户归因（v0.8，可选）与人类登录。 当多个用户共享同一服务器时，ai-memory 会将每次写入归因到指定用户。人类用户通过用户名/密码登录；agent 和 CLI 使用 Authorization: Bearer（root 自动化使用 AI_MEMORY_AUTH_TOKEN，或使用 ai-memory api-key add 生成的 aim_ key）。数据保持单租户——没有按页面划分的 RBAC。DB-user 认证需要 [auth].token_pepper，但创建第一条用户记录会立即将所有 /admin/* 端点切换为仅限 root，包括 status/search/read-page 和用户管理路由。ai-memory init 会为新安装生成 pepper，在添加用户之前不会改变单用户行为。SSO 网关也可以使用专用的 [auth].actor_proxy_bearer_token 和受信任的 X-Memory-Actor-* 请求头；其凭证有意与 root bearer 分离，以免缺失身份时变成 root。完整操作指南和四级认证阶梯见 docs/users.md。

完整家庭实验室模式见 docs/deploy.md，包含 bearer 认证、主机白名单以及 TLS/反向代理选项。

使用记忆

在日常使用中，你通常不会直接想到 ai-memory。生命周期钩子会捕获提示、工具调用、压缩检查点以及会话边界。SessionStart 钩子会在你向下一个 Agent 发送第一条提示之前，获取待处理的交接。

常用入口：

• 询问“我们上次进展到哪了？”即可从待处理的交接继续。

• 询问“我们讨论过 X 吗？”或“在记忆中搜索 Y”，即可查询 wiki。

• 询问“给我同步一下进展”，即可获取近期项目活动的文字摘要。

• 在已有数月历史的现有项目中引入 ai-memory 时，运行一次 ai-memory bootstrap。

• 使用 --enable-web 启动服务，并访问 /web，即可在浏览器中以只读方式查看 Markdown wiki。--enable-web 还会在 /api/v1 挂载一个只读 JSON 前端 API（包含 workspaces、projects、pages、recent、briefing、search），使自定义 Web UI 能够读取记忆，而无需直接打开 SQLite 或 wiki 文件。渲染后的页面会保持外部链接可点击，但图片地址必须使用相对路径或根相对路径；绝对路径的外部图片会被屏蔽，以避免查看已存储的 Markdown 时充当远程信标：

  GET  /api/v1/workspaces
  GET  /api/v1/projects?workspace=...
  GET  /api/v1/workspaces/{workspace}/projects/{project}/pages
  GET  /api/v1/workspaces/{workspace}/projects/{project}/pages/{path}
  GET  /api/v1/workspaces/{workspace}/projects/{project}/recent?limit=...
  GET  /api/v1/workspaces/{workspace}/projects/{project}/briefing?limit=...
  GET  /api/v1/workspaces/{workspace}/overview?limit=...
  GET  /api/v1/workspaces/{workspace}/projects/{project}/overview?limit=...
  GET  /api/v1/workspaces/{workspace}/projects/{project}/handoffs?state=...&limit=...
  GET  /api/v1/search?q=...&workspace=...&project=...&limit=...
  POST /api/v1/search   { "q": "...", "scopes": [{ "workspace": "...", "project": "..." }] }
  

  overview 将工作区或项目的未关闭交接、简报和记忆健康状态合并为一次调用（即项目总览页面所需的数据）。交接历史默认返回调用者自己的记录及共享记录；root 可以使用 all_owners=true 跨操作者进行恢复。

  完整集成指南： 请参阅 docs/frontend-api.md，了解身份验证配置、响应结构、错误模型、限制/分页、自定义 UI 托管、完整的 fetch/curl 示例，以及权威数据源文件。如果你正在构建前端，请先阅读该文档。

  如果你要使用自己的静态前端代替内置 UI，请将 --web-ui-dir 指向前端构建产物目录（它与 /api/v1、/mcp、/admin/* 同源，因此现有身份验证机制仍然生效）：

  ai-memory serve --transport http --bind 127.0.0.1:49374 \
    --enable-web --web-ui-dir ../ai-memory-ui/dist
  

  一个参考实现——带有截图和 e2e 测试的 SolidJS 知识库浏览器——位于 djalmajr/ai-memory-ui。

  更丰富的产品形态，例如导入/迁移流水线，以及支持写入的浏览器聊天/编辑器，应作为可选的伴生 crate 或项目实现，并通过调用 ai-memory 的公共 HTTP/MCP 接口完成集成。首个已实现的伴生 crate 是独立的 OMC wiki 导入器，位于 companions/ai-memory-importer。它有意不作为根工作区成员，因此不会包含在根目录 cargo test --workspace 中。边界说明请参阅 docs/companion-crates.md。

  当反向代理将 ai-memory 托管在 URL 子路径下时，请设置 --base-path（或 AI_MEMORY_BASE_PATH），让所有 HTTP 接口统一随子路径迁移。例如：--base-path /wiki 会将 MCP 暴露在 /wiki/mcp，hooks 暴露在 /wiki/hook，API 暴露在 /wiki/api/v1，默认浏览器界面暴露在 /wiki/web。如果你希望浏览器界面或自定义 SPA 直接位于 /wiki，请设置 --web-slug /。

只需安装一次托管路由包，以便 Agent 能够针对这些提示主动调用正确的 MCP 工具：

ai-memory install-instructions

该命令会写入或更新精简的 <!-- ai-memory:start --> 代码块，以及由 ai-memory 托管的 Agent Skills，其中包含详细的路由指引。 如需查看 handoff 示例、主动查询路由、bootstrap 细节、web UI 截图以及 raw-wiki 检查命令，请参见 docs/usage.md。CLI URL/auth 配置位于 docs/install.md。

Entity retrieval

整合过程会将具体技术、组件、服务、文件和领域名词提取到每个页面的规范 frontmatter 中。手工编辑的 wiki 页面也可以显式声明相同的有界索引：

---
title: Queue choice
entities:
  - nats jetstream
  - delivery guarantees
---

名称会被统一转为小写、规范化空白并去重；每页上限为 10 个，每个名称上限为 64 个字符，并会在 clean-store ai-memory reindex 期间从 Markdown 重建。 实体查找按项目隔离，默认忽略已过期页面，并会在 memory_query(..., explain: true) 下报告 entity_rank、其原始逆频率 entity_weight、matched_entities，以及其 RRF 贡献。

LLM 提供商

ai-memory 无需 LLM 即可运行：hooks 仍会捕获会话，搜索使用 FTS5 + 已声明实体 + 图邻居，摘要则回退到基于规则的输出。如果需要 LLM 整合（在 PreCompact 时触发、通过 memory_consolidate 按需触发，或通过 AI_MEMORY_CONSOLIDATE_ON_SESSION_END 在会话结束时启用）、更丰富的 linting 与 bootstrap，请添加一个 LLM 提供商。 实质性会话结束时，无论如何都会写入一个基于规则的摘要页 + 交接。仅包含 SessionStart / SessionEnd 边界的会话会关闭，而不生成页面、交接或 provider 任务。如果该空会话曾接受启动上下文，其会话绑定交接会回到开放池，供下一个接收者使用，而不是丢失。 启用会话结束选项后，provider 任务会在这些确定性写入之后持久入队，并由一个有界的服务器 worker 处理，因此 hook drain 延迟不会取消它。失败任务会按退避策略重试，并在服务器重启后仍然存在。恢复的原生会话只有在观测代次推进后才会再次结束；持久化的代次水位会使重复的 SessionEnd 投递和系统时钟偏差收敛，避免重复 provider 工作。结束水位和自动交接会原子提交；被打断的 keyed replay 会完成 wiki commit、queue insert 和 key completion，而不会重复该交接。下一次 SessionStart 时，最新的 cwd-eligible 自动交接优先生效；接受它会令较早且符合条件的自动交接失效，而不会消耗手动任务或同级目录任务。新的自动交接还会使来自其精确 cwd 的先前开放自动交接失效，因此在接收者启动之前，重复的 SessionEnd 不会在那里累积。

为了让整合风格保持项目特定，在该项目 wiki 中写入 _prompts/consolidation.md。其正文可以表达 偏好，例如“优先使用葡萄牙语标题”或“忽略常规 CI 噪音”。 自动、单页和多页整合都会使用该页面；手动 memory_consolidate 调用可以通过 instructions 临时覆盖一次。ai-memory 会清理该值并将其限制在 2,000 个字符内，在 user message 中进行 JSON 编码，并把它视为不可信的咨询数据。它不能提供事实、 请求使用工具或披露信息，也不能覆盖整合 schema 和 忠实性规则。TTL 已过期的偏好页面会被忽略。没有生效页面或参数时，不会追加偏好块。

推荐默认值：

Provider	Default	Use when
anthropic	claude-haiku-4-5	整合质量与规则分类的最佳默认值。
anthropic-oauth	claude-sonnet-4-6	通过 claude setup-token 使用 Claude Pro/Max 订阅，无需 API key。
openai	gpt-5.4-mini	更便宜且更快的托管选项。
openai-oauth	gpt-5.5	通过 ai-memory auth login openai-oauth 使用 ChatGPT Pro/Plus/Codex 后端；无需 Platform API key。
copilot	gpt-5.5	通过 ai-memory auth login copilot 或 COPILOT_GITHUB_TOKEN 使用 GitHub Copilot Chat 后端；需要 Copilot 订阅。
gemini	gemini-3.5-flash	Google 托管选项，免费额度较充足。
openai-compat	无默认	OpenRouter、Atlas Cloud、OrcaRouter、Ollama、vLLM、LM Studio 及其他兼容端点。

openai-oauth 将 refresh token 存储在 <data_dir>/auth.json 中，并与 ChatGPT/Codex Responses 后端通信，而不是 api.openai.com。对于 Docker 快速 启动，请通过 wrapper 运行 ai-memory auth login openai-oauth，使 token 落在与服务器相同的 ai-memory-data 卷中。

anthropic-oauth 访问与 anthropic 相同的 /v1/messages 端点，但 使用 OAuth bearer token 进行身份验证，而不是 API key。运行 claude setup-token 一次，然后设置 AI_MEMORY_LLM_PROVIDER=anthropic-oauth 和 ANTHROPIC_OAUTH_TOKEN=<token>（或 CLAUDE_CODE_OAUTH_TOKEN，该值会由 claude setup-token 自动写入）。无需 ANTHROPIC_API_KEY。Docker wrapper 会按名称将任一 token 转发给 llm-test 等短生命周期辅助命令； 长生命周期的服务器容器需要按照安装指南单独配置。

对于两种 Anthropic 提供商，ai-memory 会为 Claude 4.7 及更新模型以及 Claude Mythos Preview 省略 temperature，因为这些模型会拒绝 非默认采样参数。llm-test 在 provider 应用该兼容性规则之前， 会发送与普通 pipeline 相同的代表性 0.2 值。

⚠️ 非官方做法，且违反 Anthropic 使用政策——请自担风险； 这可能导致账户被限流或封禁。参见 docs/install.md 中的警告。

copilot 在同一个 auth file 中存储 GitHub user token，并通过 GitHub 的 /copilot_internal/v2/token 将其交换为短生命周期的 Copilot API token，然后使用带有 vscode-chat 集成头的 Copilot Chat 端点。你也可以在服务器上设置 COPILOT_GITHUB_TOKEN、GH_TOKEN 或 GITHUB_TOKEN。

对于小上下文本地模型，请同时配置两个整合限制。输入目标需覆盖完整渲染后的 prompt，包括有界 slot 和 当前页面上下文，以及结构化输出 schema；输出限制会发送给 provider。两者之和必须适合模型上下文窗口，并预留额外 余量，因为各 provider 的分词器不同：

[consolidation]
max_input_tokens = 6500
max_output_tokens = 1000

对应的环境变量是 AI_MEMORY_CONSOLIDATION__MAX_INPUT_TOKENS 和 AI_MEMORY_CONSOLIDATION__MAX_OUTPUT_TOKENS。在自动 PreCompact/PostCompaction 检查点期间，如果提供商失败，会回退到确定性的基于规则的页面；准入、存储和范围错误仍按失败关闭处理。经过验证的最小限制为 6,000 个输入 token 和 1,000 个输出 token。

每个聊天提供商都将每次 completion 请求限制为 300 秒 （可通过 AI_MEMORY_LLM_TIMEOUT_SECS 覆盖，或在 config.toml 中设置 llm_timeout_secs = 900；快速 openai-oauth token 刷新仍保留默认上限）。 默认值可以容忍本地引擎冷加载大型模型；对于长 completion 超过上限的慢速托管网关，每次请求都会以 http: error sending request 失败，因此应提高该值，而不是任由 consolidation 耗尽重试次数。

重排序是可选功能，默认关闭。在已配置 LLM 提供商的情况下， AI_MEMORY_RERANKER=llm 会让项目和显式范围的 memory_query 调用从混合阶段多取结果、融合范围，并最多发起一次 LLM 调用，以重新排列最佳候选项。它可以将 RRF 排在请求截断点以下的相关页面提升出来，代价是 LLM 延迟和用量。请求会将查询词，以及最多 30 个长度受限的页面标题和搜索摘要发送到已配置的提供商；所有值均经过 JSON 编码，并被视为不可信数据。遇到超时、提供商错误或评分集不完整/无效时，将保留原有顺序。global=true 以及补充性全局偏好命中项保留其现有非 RRF 排序。并发提供商调用上限为 4 次；达到饱和的查询保持本地排序，不等待。

嵌入是可选功能，并且独立于 LLM 提供商。如果你希望在 FTS5 + 实体 + 图邻居检索之外使用向量检索，请设置 AI_MEMORY_EMBEDDING_PROVIDER=openai、voyage、google/gemini 或 openai-compat。openai-compat 面向自托管引擎 （Ollama、LM Studio、vLLM）：它不需要 API key，但要求显式提供 AI_MEMORY_EMBEDDING_BASE_URL、AI_MEMORY_EMBEDDING_MODEL 和 AI_MEMORY_EMBEDDING_DIM。可选的 EMBEDDING_API_KEY 仅为 embedder 提供凭据，并且会在 OPENAI_API_KEY 和 LLM_API_KEY 之前被检查，因此嵌入可以运行在与 LLM 不同的提供商上。仅 FTS 路径和混合路径都会在候选生成后应用相同的有限制页面权威性调整；嵌入可以提高相关性召回，但不会决定哪个来源是权威来源。

有关环境变量以及 Ollama/OpenRouter/Atlas Cloud/OrcaRouter 示例，请参见 docs/install.md#llm-provider-tiers； 有关实证模型比较，请参见 docs/llm-provider-comparison.md。

架构

一个 Rust 二进制可执行文件运行 MCP/HTTP 服务器，并管理一个数据目录：

<data_dir>/
├── wiki/    # markdown source of truth, git-versioned
├── raw/     # immutable sanitized managed-workstream transcript segments
├── db/      # SQLite indexes, including FTS5, entities, and embeddings
├── models/  # reserved for local embedding models
└── logs/    # rolling tracing output

钩子通过 POST 请求将观察记录发送到服务器。服务器借助单个 SQLite 写入器串行化写入，将会话观察记录编译为 Markdown 页面，并通过 FTS5、实体匹配与图邻居 RRF、可选向量 RRF、有界来源权威度调整，以及面向非全局检索的有界原始观察记录回退提供检索服务。

请参阅 docs/ARCHITECTURE.md 查看数据流图、crate 划分、schema 说明和不变量。

文档

文件	说明
docs/install.md	安装手册。 覆盖所有 agent CLI 与替代方式（curl、source build、no-docker、no-auth），并说明如何在另一台机器上运行服务器（homelab/LAN）。如果你的环境偏离标准路径，请在快速入门后阅读。
docs/usage.md	交接、主动记忆查询、精简路由代码片段 + 托管式 Agent Skills、从其他记忆工具迁移、Web UI、raw-wiki 检视，以及规则与事实工作流。
docs/managed-workstreams.md	可选的 ai-memory run 在 Claude Code、Codex、OpenCode、Pi、Crush、Kimi Code、Command Code、Kiro CLI v2/v3、OMP、Grok Build CLI 和 Antigravity CLI 之间的连续性：自动 harness 选择、原生恢复、参数转发、ledger 搜索、隐私与恢复。
docs/managed-harness-contributions.md	贡献者协议与验收标准：为其他 harness 添加托管式恢复、只读 transcript 导入和启动上下文投递。
docs/marker-file.md	.ai-memory.toml 工作区/项目路由：多客户端目录树、monorepos、worktrees，以及工作与个人分离。
docs/auto-scope.md	共享服务器的 [auto_scope] 模式：默认单槽位路由、会话感知隔离，以及多用户 per_actor 行为。
docs/macos.md	macOS 安装方式：原生 release 二进制（推荐）、source build、Docker 包装器、hook 平台说明，以及当前 macOS 限制。
docs/windows.md	Windows 安装模式：完整 WSL2、带 Docker Desktop 的原生 Windows、预构建原生 release zip、原生 source builds，以及当前 hook/MCP harness 注意事项。
docs/mcp-install.md	各客户端的 MCP 与生命周期说明、handoff 注入限制，以及社区 bridge 指南。
docs/deploy.md	Homelab 部署：bin/deploy、bearer-token 认证，以及指向 TLS 指南的链接。
docs/users.md	多用户归属与人类登录。 四级 bearer 权限阶梯、密码会话、ai-memory user / api-key 操作说明，以及存量 aim_ 迁移。
docs/https-via-proxy.md	通过反向代理启用 HTTPS。 何时需要 TLS（多用户、非 loopback），何时不需要（loopback / stdio）。提供可直接复制粘贴的 docker compose 模板，适用于 Caddy + Let's Encrypt、Caddy + 内部 CA（仅 LAN）、Cloudflare Tunnel（无需开放端口）以及外部证书文件；另有 native-Caddy + nginx 配方。并明确点出那些看似安全实则不安全的失效模式。
docs/lifecycle-ops.md	运行 purge / rename / backup / restore / reset / reindex / restore-page 前请先阅读。 涉及状态变更命令的安全矩阵、按项目划分的磁盘布局（隔离实际如何工作）、基于检查点的页面恢复，以及“全新开始”“高风险操作前快照”“删除单个项目”和从 wiki 文件重建 SQLite 的运维工作流。
docs/auto-improvement-loop.md	自动改进设计说明：受 Hermes 启发的定时评审、默认自动批准、可选择开启手动评审、待处理提案存储，以及 curator 工作。
docs/companion-crates.md	可选配套 crate 的边界与实现计划，包括位于 companions/ai-memory-importer 的独立 importer，且不扩大核心 ai-memory 的范围。
docs/llm-provider-comparison.md	推荐 LLM 默认值背后的实证说明。
docs/ARCHITECTURE.md	运维概要：数据流、crate 布局、横切不变量、schema。
docs/design-decisions.md	完整 v1 规格说明。
docs/ 下的研究文档	Karpathy LLM Wiki 笔记、Hermes Agent、agentmemory / basic-memory / cognee 深入分析，以及来自上游问题的经验教训。

影响与既有成果

• Karpathy LLM Wiki - “编译而非检索”模式。
• agentmemory - 它拥有许多正确的理念；本项目是其 Rust 继任者。
• basic-memory - 基于磁盘 Markdown 的事实来源模型。
• cognee - 流水线编排与三元组嵌入。
• Hermes Agent - 自我改进闭环：轮次后复盘、审批关卡与策展边界。
• A-MEM - 支持链接演进的 Zettelkasten 风格原子笔记。

许可证

MIT - 见 LICENSE。

致谢

本代码库正在与 Claude Code （Anthropic Claude Opus 4.7）协作开发， 并遵循 docs/design-decisions.md 中记录的方案。