AI-Memory 详细部署教程：为 AI 编码代理构建长期记忆

AI-Memory 是一个为 AI 编码代理（如 Claude Code、Codex、Cursor 等）提供长期记忆和跨代理、跨机器、跨团队协作的开源解决方案。它能让你在一个代理中开始任务，在另一个代理中无缝继续，无需重复解释架构、失败尝试或未决问题。本教程将详细介绍其部署与使用方法。

1. 核心价值与准备工作

1.1 它能解决什么问题？

跨代理记忆：20 多种 AI 编程代理（Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin 等）共享一个记忆库，实现真正的任务交接。
跨机器同步：记忆存储在你自建的服务器上（可以是本机、家庭服务器等），在台式机上留下的任务，可以在笔记本上无缝继续。
团队共享：团队成员指向同一个服务器，个人知识变为团队共享，同时保留个人手记。具备多用户认证、操作审计日志。
透明与可控：所有记忆以普通 Markdown 文件存储（可被 Git 版本管理），数据库索引始终可从文件重建，无厂商锁定。

1.2 系统要求

操作系统：Linux (原生支持)、macOS (原生支持)、Windows (通过 WSL2 原生支持，原生 Windows 为实验性)。
网络：服务器默认监听 127.0.0.1（仅本机访问）。如需跨机器或团队使用，需配置认证和网络。
可选依赖：如需语义搜索和 AI 生成的会话摘要，需配置 LLM 提供商（如 Anthropic, OpenAI）的 API Key。即使不配置 LLM，基础的文件捕获、搜索和交接功能（基于 SQLite FTS5 全文搜索）仍然完全可用。

2. 部署方式一：使用 Docker（推荐）

这是最快捷的部署方式，特别适合熟悉容器化环境的用户。以下步骤已包含对 linux/amd64 和 linux/arm64 架构的支持。

安装 ai-memory 命令行包装器：这个脚本让你能在主机上像使用原生命令一样调用容器内的 AI-Memory。

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

# 确保 ~/.local/bin 在 PATH 中，可将其加入 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

启动 AI-Memory 服务器：使用 Docker 运行容器，默认监听 127.0.0.1:49374，仅本机可访问（安全）。以下命令启用了可选的 LLM 功能（示例使用 Anthropic），若不需要可移除 -e 开头的行。

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

将 AI-Memory 接入你的 AI 编码代理：以 Claude Code 为例，只需两条命令，AI-Memory 便会自动配置好 MCP 服务器和生命周期钩子。
1
2
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
- 对于其他代理（如 Codex, Cursor），只需替换 --client 和 --agent 的参数即可（例如 --client codex --agent codex）。完整列表参见项目文档。

3. 部署方式二：原生二进制 (Native Binary)

对于追求性能或不想依赖 Docker 的 macOS/Linux 用户，可以直接下载预编译的二进制文件。

下载二进制文件：从项目的 GitHub Releases 页面下载适用于你操作系统和架构的 ai-memory 可执行文件。
安装到系统路径：将下载的文件重命名为 ai-memory，赋予执行权限，并移动到 PATH 目录（如 /usr/local/bin）。
1
2
chmod +x ai-memory
sudo mv ai-memory /usr/local/bin/

初始化并启动服务器：

# 创建数据目录并初始化
mkdir -p ~/.local/share/ai-memory
ai-memory --data-dir ~/.local/share/ai-memory init

# 启动服务器（前台运行，可按 Ctrl+C 停止）
ai-memory serve

接入代理：步骤与 Docker 部署的第 3 步完全相同，使用 ai-memory install-mcp 和 install-hooks 命令。

4. 日常使用与核心工作流

一旦部署完成，AI-Memory 会在后台静默工作，你几乎无需直接操作它。

自动捕获：当你通过支持的 AI 代理编码时，AI-Memory 的生命周期钩子会自动记录提示词、工具调用和会话边界。
会话总结：当会话结束时（如关闭 Claude Code），AI-Memory 会将捕获的观察结果编译成可读的 Markdown 页面，存储在项目的 wiki 目录下。
跨代理交接：下次你在同一个项目目录中启动任何支持的代理时，AI-Memory 会自动注入一个“交接简报”，让新代理了解之前的进展、失败尝试和未决问题。
主动检索：你可以在对话中直接向代理提问，例如：
- “我们在哪里停下了？”（继续未完成的手记）
- “我们讨论过 X 吗？”或“搜索内存中关于 Y 的内容”（查询 wiki）
- “给我讲讲最新的情况”（获取最近项目活动的文字摘要）

5. 关键配置与安全

5.1 环境变量与配置

AI-Memory 的配置主要通过环境变量或在 ~/.config/ai-memory/config.toml 文件中进行。常用配置项包括：

配置项	说明	示例
`AI_MEMORY_LLM_PROVIDER`	用于生成摘要的 LLM 提供商	`anthropic`, `openai`, `gemini`
`ANTHROPIC_API_KEY`	Anthropic API 密钥	`sk-ant-...`
`OPENAI_API_KEY`	OpenAI API 密钥	`sk-...`
`AI_MEMORY_EMBEDDING_PROVIDER`	用于语义搜索的嵌入提供商	`openai`, `voyage`, `local`
`AI_MEMORY_SERVER_PORT`	服务监听端口	`49374`
`AI_MEMORY_BEARER_TOKEN`	为 HTTP 端点设置静态 Bearer Token	`your-secure-token`

5.2 安全模型

默认安全：开发时的默认配置是 127.0.0.1 无认证，仅本机可访问。
网络暴露：若要在局域网或公网访问，必须添加认证。最简单的方式是设置 AI_MEMORY_BEARER_TOKEN 环境变量。
多用户：正式的多用户、审计功能需通过 ai-memory user 和 api-key 子命令配置，并建议配置 HTTPS 反向代理（参见 docs/https-via-proxy.md）。
数据隐私：捕获的数据在存储前会在类型化的隐私边界进行脱敏处理。

6. 故障排查与常用命令

查看日志：日志默认存储在数据目录下的 logs/ 文件夹中。
手动触发汇总：如果你想立即为当前项目生成记忆总结，可以运行 ai-memory consolidate。
搜索记忆：使用 ai-memory search "你的查询" 可以在终端直接搜索记忆库。
检查状态：运行 ai-memory status 查看服务器连接状态和当前项目的手记信息。
完全卸载：ai-memory uninstall --apply 会移除所有 AI-Memory 安装的钩子和 MCP 配置，但不会删除数据目录。如需删除数据，请手动移除 ~/.local/share/ai-memory 目录。