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

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

分支3Tags111
文件最后提交记录最后更新时间
5 天前
5 天前
5 天前
3 小时前
13 天前
3 小时前
5 天前
3 小时前
7 天前
2 天前
1 天前
5 天前
1 天前
1 个月前
13 天前
8 天前
23 天前
7 天前
2 个月前
1 个月前
3 小时前
3 小时前
1 天前
5 天前
21 小时前
2 天前
3 个月前
5 天前
23 天前
23 小时前
22 天前
3 个月前

ai-memory

为 AI 编码智能体而生的长期记忆。在任务中途退出 Claude Code, 在同一目录启动 OpenAI Codex,即可继续工作,而无需重新解释架构、 失败的尝试或未决问题。

Release Rust License

为什么需要 ai-memory

你的编码智能体已经具备记忆能力。Claude Code 会自己记笔记,Cursor 会记住一些事情, 每个平台也在不断增加此类功能。但它们都面临同样的壁垒:笔记只留在某一台机器上、 只属于某一个智能体,并且在你切换工具——或更换队友——的瞬间便从视野中消失。

ai-memory 站在这些壁垒的另一侧。

  • 它会跟随你跨智能体迁移。 二十多种智能体框架——Claude Code、 Codex、Cursor、Gemini CLI、OpenCode、Grok、Devin、Kimi、Kiro 等—— 汇入同一份共享记忆。在任务中途退出 Claude Code,在同一目录启动 Codex, 下一个智能体接手的是一份真正的交接:你停在哪里、哪些尝试失败、哪些问题仍待解决。在这里,交接是一种协议, 而不是一种约定——带类型、有归属、仅被认领一次。

  • 它会跟随你跨机器迁移。 记忆存放在你自己运行的服务器中—— 可以是同一台笔记本、一台家庭实验室设备,或任何位置——因此你留在台式机上的项目, 就是你在笔记本上恢复的项目。相同的知识,相同的未决问题。

  • 它能胜任团队协作。 让所有人都指向同一台服务器, 某个人的会话所学到的内容,所有人的智能体都能检索到。知识按项目共享;个人交接仍归个人。多用户认证、 按人归因和审计日志均为内置能力——而非付费档位。

  • 你的记忆就是普通 Markdown。 真正的事实来源是由 git 支持的维基, 由普通的 .md 文件组成:用 grep 检索、在 Obsidian 中打开、手工编辑、 用 rsync 同步。数据库只是派生索引,始终可以从文件重建。没有需要照看的向量存储,也没有内容被锁在二进制文件中。

  • 它会静默地采集工作本身。 生命周期钩子会记录实际发生的内容—— 提示词、工具调用、会话边界——在存入之前,先于类型化的隐私边界处完成清洗,再整合为可读页面。没有“记住这个”的固定流程。而且默认路径 使用 零次 LLM 调用:采集、检索和交接均无需任何 API 密钥即可工作。

  • 它会如实呈现自身状态。 一个自包含的二进制文件。 Purge 命令会准确说明“删除”的确切含义。一个经过测量的写入上限(约 700/s),而非猜测得出的上限。每一项变更都有审计日志。无聊, 却正符合基础设施应有的样子。

工作原理

capture ──▶ consolidate ──▶ recall ──▶ handoff
 hooks        session-end      search     next agent,
 observe      summaries as     + brief    any harness
 silently     wiki pages       injection

智能体在你工作时通过生命周期钩子输出脱敏后的观察数据。 会话结束时,这些观察数据会成为项目的 wiki 中条理清晰的 Markdown 页面(可选由 LLM 生成;即使不生成也有用)。下一个 会话——无论是哪个智能体、哪台机器——都会获得一份有界简报,并可以检索 所有内容:全文、实体、链接,以及(可选)向量,融合为 统一排序。跨智能体交接会显式传递接力棒。

完整设计,包括保障多用户与 多会话使用安全的不变量,位于 docs/ARCHITECTURE.md

支持矩阵

以下每一行都是第一方集成——MCP 注册、生命周期 钩子,或两者兼备——并由 CI 持续校验准确性。包含每个智能体说明与 注意事项的完整矩阵位于 docs/support-matrix.md

范围 状态
Linux 支持
macOS 支持
通过 WSL2 的 Windows 支持
原生 Windows 实验性
Claude Code 支持
Codex 支持
Command Code 支持
Devin CLI 支持
OpenCode 支持
OpenCode 2(opencode2 beta) 支持
Cursor 支持
Gemini CLI 支持
Oh My Pi / OMP 支持
Pi 支持
Crush 仅受管
受管工作流 需显式启用
Claude Desktop 仅 MCP
OpenClaw 支持
Antigravity CLI 支持
Grok Build CLI 支持
Swival CLI 仅 MCP
Zero 支持
ZCode 支持
Kimi Code 支持
Kiro CLI 支持
Pool 仅钩子
VS Code Copilot 仅 MCP
Zed 仅 MCP
Hermes Agent 社区
LLM/身份验证提供商 支持
嵌入提供商 支持

快速开始

Arch Linux(AUR)

对于原生 Arch 安装,请使用 AUR 软件包。它们会安装 /usr/bin/ai-memory、打包的钩子源码,以及系统级和 用户级 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

系统服务安装会经由打包的 unit 使用 /var/lib/ai-memory/etc/ai-memory/。完整的用户服务、系统服务、身份验证以及提供商配置说明见 docs/install.md#arch-linux-native-packages-aur

Docker

你需要:Docker 或 Podman,外加来自支持矩阵的 agent CLI,或任何其他支持 MCP 的工具。

已发布的 Docker 镜像包含 linux/amd64linux/arm64 变体,因此 Apple Silicon Mac 和 ARM64 Linux 主机可以拉取 akitaonrails/ai-memory,无需借助 --platform linux/amd64 进行平台模拟。

默认快速开始无身份验证——服务器仅绑定到 loopback,因此在单用户笔记本电脑上,其他任何组件都无法访问它。当你准备将服务器暴露到 LAN 时,添加 bearer token 只需一行改动;请参阅下方的安全

# 1. Install the ai-memory CLI wrapper (a small shell script that
#    runs the binary inside a container 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-... \
    docker.io/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 opencode2`, `--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

示例中使用的是 docker;在 Podman 主机上,请将其替换为 podman。当未安装 Docker 时,wrapper 会自动使用 Podman。当两个引擎同时可用时,设置 AI_MEMORY_DOCKER=podman 可强制使用 Podman。

在 Linux/macOS 上,仅此而已。按正常方式启动一个 Claude Code 会话——现在每条提示和工具调用都会写入 ai-memory,你下次在该项目中启动的会话将看到从上次中断处继续的交接信息。 在 macOS 上,如果不需要 Docker,也支持并推荐使用原生发行版二进制文件;参见 docs/macos.md

接入另一个 agent 只需使用相同的两条命令并替换名称——例如 --client codex--agent codex,支持矩阵中的每一行都如此。针对每个 agent 的完整指南,包括 Windows 和远程服务器,见 docs/install.md

同一项目中同时使用两个 agent,或团队成员共用一台服务器?这开箱即用:默认情况下,“当前项目”指针会按调用方隔离(v1.39+)。有关可选的会话感知 Claude Code 桥接及详细信息,参见 docs/auto-scope.md

托管工作流可选,它能在共享记忆之上增加跨 harness 的 session 连续性:

ai-memory run claude
ai-memory run codex --yolo   # later: same workstream, different harness
ai-memory continue           # resume the newest managed checkout

ai-memory uninstall --apply 会移除 ai-memory 安装的全部内容,也仅移除它安装的内容。安装命令是幂等的,并会在任何被修改的文件旁写入带时间戳的备份。

日常使用

日常使用中,你基本不用考虑 ai-memory。Hooks 会捕获提示词、工具调用和会话边界;会话结束时,它们会被整理成易读的 Wiki 页面;下一次会话会从交接信息开始。

  • 询问“我们上次进行到哪里了?”即可从待处理交接中继续。
  • 询问“我们讨论过 X 吗?”或“在记忆中搜索 Y”即可查询 Wiki。
  • 询问“帮我梳理一下进展”即可获得近期项目活动的文字摘要。
  • 接手一个已有数月历史的现有项目时,运行一次 ai-memory bootstrap
  • 使用 --enable-web 启动服务器,即可通过浏览器以只读方式查看 Wiki,并通过 /api/v1 下的 JSON API 访问。

完整指南——搜索模式、实体、反馈、简报、Web API——见 docs/usage.mddocs/use-cases.md

团队与多台机器

将服务器部署在可访问的位置——家庭实验室设备、局域网主机——并让每台机器和每位团队成员都指向它。知识按项目共享;个人交接保持私有;每次写入都会记录来源并可供审计。多用户认证(密码、API 凭证)已内置。

先从 docs/users.md 了解账户与所有权, 再从 docs/deploy.md 了解服务器本身——其中包括实测的容量数据,而非估算值,以及一条至关重要的规则:每个数据目录只对应一个服务器实例,绝不能部署两个。

安全

快速开始的默认配置仅监听回环地址,且不启用认证——机器外部无法访问它。在此基础上,可以逐步加固:面向局域网启用 Bearer Token、创建用户账户、面向 Hooks 启用 OIDC 设备认证,并通过反向代理启用 TLS。捕获内容在存储之前,会在类型化隐私边界处完成脱敏处理;每个仓库的 [capture] 规则可以排除路径,或切换为白名单模式。

完整模型见 docs/security.mddocs/users.mddocs/https-via-proxy.md

LLM 提供商

可选。所有功能均可在零 LLM 调用下运行;添加提供商后可升级会话摘要,并启用语义搜索。记忆整合支持 Anthropic、OpenAI(包括 OAuth/Codex)、GitHub Copilot、Gemini、OpenCode(Go 和 Zen),以及任意 OpenAI 兼容端点(Ollama、LM Studio、vLLM);嵌入支持 OpenAI、Voyage、Gemini,以及无需密钥的 OpenAI 兼容端点。配置位于 docs/llm-providers.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

Hooks 通过 POST 将观察数据发送到服务器。服务器通过单个 SQLite writer 串行化写入,将会话观察数据编译为 Markdown 页面,并通过 FTS5、实体匹配和图邻居 RRF、可选向量 RRF、有界来源权威性调整,以及面向非全局搜索的有界原始观察回退提供检索。

如需了解数据流图、crate 划分、schema 说明和不变量,请参考 docs/ARCHITECTURE.md

Docs

文件 说明
docs/install.md 安装手册。 覆盖所有 agent CLI、所有替代方式(curl、源码构建、无 Docker、无认证),以及服务器部署到其他机器(家庭实验室 / LAN)的完整指南。如果你的环境不符合正常路径,可在快速入门后阅读。
docs/usage.md 交接、主动记忆查询、精简路由片段 + 托管 Agent Skills、从其他记忆工具迁移、Web UI、原始 wiki 检查,以及规则与事实工作流。
docs/managed-workstreams.md 跨 Claude Code、Codex、OpenCode、OpenCode 2 beta、Pi、Crush、Kimi Code、Command Code、Kiro CLI v2/v3、OMP、Grok Build CLI 和 Antigravity CLI 的可选 ai-memory run 连续性:自动 harness 选择、原生 resume、参数转发、ledger 搜索、隐私和恢复。
docs/managed-harness-contributions.md 为其他 harness 添加托管 resume、只读对话记录导入以及启动上下文投递的贡献者协议与验收标准。
docs/marker-file.md 用于多客户端目录树、mono-repo、worktree 和工作/个人分离的 .ai-memory.toml 工作区/项目路由。
docs/auto-scope.md 共享服务器的 [auto_scope] 模式:默认单槽位路由、会话感知隔离,以及多用户 per_actor 行为。
docs/macos.md macOS 安装方式:原生发布二进制文件(推荐)、源码构建、Docker 封装、hook 平台说明,以及当前 macOS 限制。
docs/windows.md Windows 安装模式:完整 WSL2、带 Docker Desktop 的原生 Windows、预构建原生发布 zip、原生源码构建,以及当前 hook/MCP harness 注意事项。
docs/mcp-install.md 各客户端的 MCP 与生命周期说明、handoff 注入限制,以及社区 bridge 指南。
docs/deploy.md 家庭实验室部署: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 前阅读。 涉及状态变更命令的安全矩阵、按项目划分的磁盘布局(隔离机制的实际工作方式)、基于 checkpoint 的页面恢复,以及“全新开始”、“高风险操作前快照”、“删除单个项目”和从 wiki 文件重建 SQLite 的运维工作流。
docs/auto-improvement-loop.md 自动改进设计说明:受 Hermes 启发的定期评审、默认自动审批、可选启用的手动评审、待处理提案存储,以及维护工作。
docs/companion-crates.md 可选配套项目的边界与实现计划,包括位于 companions/ai-memory-importer 的独立导入器,且不扩大核心 ai-memory 的范围。
docs/llm-provider-comparison.md 推荐 LLM 默认值背后的实证说明。
docs/llm-provider-fallback.md 面向临时 LLM provider 故障的可选 fallback-chain 设计提案;目前还不是受支持的配置能力。
docs/ARCHITECTURE.md 运维摘要:数据流、crate 布局、跨切面不变量、schema。
docs/design-decisions.md 完整的 v1 规格说明。
docs/ 下的研究文档 Karpathy LLM Wiki 笔记、Hermes Agent、agentmemory / basic-memory / cognee 深入解析,以及来自上游 issues 的经验教训。

影响与先前技术

  • 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 中记录的规划。

项目介绍

代理编码命令行界面长期记忆解决方案,以及促进不同代理供应商之间的交接【此简介由AI生成】

定制我的领域
416.44 K444访问 GitHub