[Github] ai-memory – 面向多 Agent 的跨机器长期记忆服务器

如果你在 Claude Code、Codex、Cursor 或其他 Agent 之间切换，真正丢失的往往不是聊天记录，而是“已经试过什么、为什么失败、下一步要接着做什么”。ai-memory 把这些状态收进一个可自托管的长期记忆服务器：hooks 负责捕获，Markdown wiki 保存源数据，检索和 handoff 再把上下文交给下一个 Agent。本文会按工作流、部署位置、会话边界和安全配置说明它到底适合什么场景。

它解决的是记忆断层

单个 Agent 的内置记忆通常跟着平台、机器或账号走；换客户端后，原来的失败路径、架构决定和未完成问题就要重新解释。akitaonrails/ai-memory 选择了另一条路线：把记忆放进你运行的服务器，让多个 Agent、多个工作目录和多个操作者共享同一套项目知识，同时保留个人 handoff 的归属。

它不是把所有对话永久塞进向量库，而是把“跨 Agent 交接”当成协议来设计。项目 README 把差异概括为跨 Agent、跨机器、团队共享、普通 Markdown 源数据和默认零 LLM 捕获；如果你想比较另一种把资源、记忆和技能组织成目录的思路，可以顺带查看 WarpNav 的 OpenViking 详情，但两者的存储和检索模型并不相同。

四段链路如何协作

ai-memory 的核心流程不是一个“记忆按钮”，而是四个相互衔接的阶段。每阶段解决的读者任务不同：

这套拆分带来一个实际好处：你可以先让系统捕获和全文检索工作起来，再决定是否接入 LLM 做摘要或 Embedding。它不会因为缺少 API key 就完全失效，也不会把“生成摘要”和“保存事实”混成同一件事。

Markdown 是源数据

ai-memory 的数据目录把 wiki/ 作为 git-backed Markdown 源数据，raw/ 保存经过清洗的托管工作流片段，db/ 只放 SQLite、FTS5、实体和向量索引，logs/ 则保存运行日志。索引可以重建，页面可以用 grep、Obsidian、编辑器或 rsync 检查；这比把全部知识锁在不可读的二进制存储里更容易备份、审计和迁移。

仓库提供的官方 Web 只读界面也沿用了项目边界：Projects 页面先列出工作区和项目，再进入某个项目查看页面。它适合审计“哪些东西已经落盘”，但 README 明确说 MCP 工具才是 Agent 的主要入口，不应把这个浏览器当成普通项目文档站。

一个项目如何被检索

进入项目后，页面按命名空间组织，例如 concepts/、decisions/、gotchas/ 和 sessions/。项目详情页同时列出页面树与最近活动，方便确认某条决定、失败记录或会话摘要是否真的写入 wiki；这类页面是“可审计的记忆”，不是模型凭空回忆出来的上下文。

日常使用可以按问题选择入口：问“我们讨论过 X 吗？”调用 memory_query；离开一段时间后用 memory_explore 获取摘要；准备切换 Agent 时用 memory_handoff_begin 保存开放问题和下一步。若检索命中 _rules/、decisions/ 或 gotchas/，仍应回到当前代码和用户要求重新验证，不能把历史页面当作自动授权。

安装先看运行位置

最容易复用的路径是 Docker：服务器绑定到本机回环地址，数据放在 Docker volume，再为目标 Agent 写入 MCP 和 lifecycle hooks。下面是 README 的最小形态，默认不启用 LLM，也不会把端口暴露给局域网：

docker run -d --name ai-memory \
  --restart unless-stopped \
  -p 127.0.0.1:49374:49374 \
  -v ai-memory-data:/data \
  akitaonrails/ai-memory:latest

ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

如果你使用 Codex，只需把客户端和 Agent 名称换成 codex；其他平台按 support matrix 选择对应值。Windows 用户要先判断 Agent 实际运行在哪：WSL2 中运行就把安装和 hooks 都放在 WSL2，原生 Windows 进程则使用 Windows wrapper 或 v1.38.0 的原生 zip。不要混用两套路径，否则生成的可执行文件和配置位置很容易对不上。

Codex 与 Windows 的边界

官方 support matrix 把 Codex 标为 Supported，但特别注明它没有自动的真正 session-end hook；需要最终摘要或交接时，应主动运行 ai-memory finalize-session --agent codex。这不是 bug，而是 Agent 生命周期接口的差异：捕获可以自动发生，收尾动作却要按客户端能力补齐。

Windows 目前分三种实际路径：

• WSL2：按 Linux 方式安装，适合 Agent 本身就在 WSL2 中运行的场景。
• Docker Desktop + 原生 Agent：用 Windows wrapper 启动 Linux 容器，配置和 hooks 写入 Windows 用户目录。
• 原生二进制：下载 ai-memory-windows-x86_64.zip，无需 Rust 工具链；Native Windows 在 support matrix 中仍标为 Experimental。

文章核验时仓库最新 release 是 v1.38.0。README 和 Windows 文档都建议从同一个环境执行 install-mcp 与 install-hooks，并在升级后重新生成 hooks，以免旧路径继续指向已移动的二进制。

团队共享的安全边界

单机试用和团队服务器不能用同一套默认值。默认服务只绑定 127.0.0.1:49374 且不开认证，适合单用户笔记本；一旦绑定到 LAN 或远程主机，就应启用 bearer token、设置 AI_MEMORY_ALLOWED_HOSTS，并在反向代理上提供 HTTPS。认证只负责身份验证，不会替你加密明文 HTTP。

多人共享时，项目页面是共享知识，个人 handoff 默认只回到创建者；需要交给全组时才显式使用 shared: true。系统有用户归属和审计日志，但 README 的数据模型仍是单租户，没有逐页面 RBAC；因此真正的隔离边界仍是服务器、数据目录、项目命名和反向代理配置。

安全升级可以按这个顺序做：

1. 单机先保持 loopback，只验证 capture、query 和 handoff 是否形成闭环。
2. 需要跨机器时添加 bearer token 与 host allowlist，不要直接把无认证 HTTP 暴露到公网。
3. 团队使用时再加入用户/API key、TLS 反向代理、备份和删除/过期策略。

零 LLM 模式够不够

如果你的目标是“先把事实留下并能找回”，够用：capture、全文搜索、handoff 和 Web 审计都可以在没有模型 API key 的情况下运行。接入 LLM 后，系统可以把会话整理成更连贯的页面；接入 Embedding provider 后，检索才增加语义向量路径。两者都属于增强，不是 ai-memory 的启动前置条件。

README 还给出过约 700 次写入/秒的饱和测量，这是项目在特定存储和并发条件下对单写入器的参考值，不是所有磁盘、网络或 HTTP 前端的性能保证。更重要的取舍是：你获得了可读、可重建的源数据，却需要自己承担数据目录备份、过期页面清理和权限边界设计。

版本、许可与取舍

截至 2026 年 9 月 1 日，GitHub 页面显示 ai-memory 约有 5,408 stars、371 forks，仓库未归档，默认分支为 main；最新 release 是 v1.38.0，最近提交已进入 v1.39 的 scope、Windows 修复和 2.0 roadmap 讨论。这里的 stars、forks 和开发分支都会变化，不能当成稳定性承诺。

仓库 LICENSE 是 MIT，允许使用、复制、修改、发布和分发，但分发时要保留版权与许可声明。它更适合愿意运行一个服务、管理 Markdown 数据目录，并能接受按客户端补齐 session-end 的技术团队；如果你只想在单个 Agent 里保留几条个人偏好，部署服务器和 hooks 的维护成本可能超过收益。

相关链接

• GitHub 仓库：https://github.com/akitaonrails/ai-memory
• 安装文档：https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md
• 使用说明：https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md
• 支持矩阵：https://github.com/akitaonrails/ai-memory/blob/main/docs/support-matrix.md
• 安全模型：https://github.com/akitaonrails/ai-memory/blob/main/docs/security.md
• 最新 Release：https://github.com/akitaonrails/ai-memory/releases/tag/v1.38.0
• WarpNav 相关条目：OpenViking：https://warpnav.com/sites/openviking

本文依据 ai-memory 官方 README、docs/install.md、docs/usage.md、docs/support-matrix.md、docs/windows.md、docs/security.md、LICENSE、v1.38.0 release notes 与仓库官方界面图片核验整理；图片来自官方仓库并按原比例处理。