akitaonrails/ai-memory

返回只读遥测报告，展示近期自动改进结果，不会暂存或创建提案；添加–stage 则会创建待审核/批准的报告页面。在区分操作符身份的部署环境中，待处理的改进提案按已验证的操作符身份隔离，因此一个人的页面提案不会阻塞其他人的；未归属和单用户部署则保持共享的待处理队列。参见 [docs/auto-improve-eval-gates.md](docs/auto-improve-eval-gates.md) 获取可执行评估评分器示例。现有安装无需逐项目迁移。调度器会初始化每个项目的首次运行标记，这样在升级后不会自动审查历史会话，然后记录每次会话的认领信息，使失败的定期审查不会无限重试；对于旧会话或失败的定期会话，可使用手动自动改进来补全。旧版配置中可能仍包含 [auto_improve] mode = …` 行；当前 ai-memory 会忽略该遗留键值，您可方便时移除。

• “应该考虑哪些维护工作？” ai-memory curator 对冷周期页面、过时槽位、完全规范化的重复标题以及跨项目悬挂链接运行无需大语言模型的、基于规则的维护报告。除非传递 --stage，否则仅生成报告；暂存时会将一个报告页面加入审批队列，但自身仍不执行任何维护操作。共享服务器可启用 [decay] breadth_weight，为获得多个已识别操作符强化的页面提供保留加分；默认值 0.0 保持现有保留分数不变。

• “为整个家庭运行一个 ai-memory 实例。” 在家庭实验室机器上以 0.0.0.0:49374 和承载令牌启动服务器；所有笔记本/台式机都连接它。基于当前工作目录的路由确保每个项目的页面清晰分离；/web 界面可从局域网内任何浏览器访问。

• “在与队友共享前审核已落地内容。” 访问 http://:49374/web 浏览维基（如启用认证则会弹出 HTTP Basic 对话框，将令牌作为密码粘贴）。支持按项目树状视图、渲染后的 Markdown，每页可查看更新链条。

• “撤销单次错误页面编辑，无需回滚整个服务器。” ai-memory checkpoints 显示最近的维基提交，然后 ai-memory restore-page --path notes/foo.md --from <hash> 可恢复该 Markdown 文件并重新索引入 SQLite。完整 backup / restore 仍是数据库状态（如会话、观察、交接、用户、审计行和嵌入向量）的解决方案。

• “丢弃实验项目，保留其余内容。” ai-memory purge-project --project experimental --confirm。原子操作：该数据库行级联删除，其维基子目录 rm -rf 删除，设计上确保其他兄弟项目不受影响。

快速开始

Arch Linux (AUR)

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

yay -S ai-memory-bin  # 预构建 Linux x86_64/aarch64 二进制
yay -S ai-memory      # 从源码构建

单用户工作站：

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 模拟。默认快速开始无认证 - 服务器仅绑定到环回接口，因此在单用户笔记本上无其他进程可访问。准备在局域网公开服务器时，添加承载令牌只需一行配置；请参阅下方安全部分。

# 1. 安装 ai-memory CLI 包装器（一个小型 shell 脚本，在 docker 中运行二进制文件并挂载您的 $HOME）。
#    这是唯一需要驻留在主机文件系统上的内容。
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。如果 `which ai-memory`
# 查找为空，请将其添加到 ~/.bashrc / ~/.zshrc：
# export PATH="$HOME/.local/bin:$PATH"

# 2. 启动服务器。`--restart unless-stopped` 使其在 docker 守护进程重启和
#    机器启动时恢复（前提是您的 docker 服务在启动时已启用 —— 大多数发行版为
#    `sudo systemctl enable docker`）。仅环回绑定 (`127.0.0.1:49374`)
#    因此本机外无其他进程可访问。省略 LLM / EMBEDDING 行可进入零 LLM 模式
#    —— FTS5 搜索在无任何密钥时仍可工作。
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. 通过两条命令连接您的代理 CLI。包装器处理挂载和每个客户端的配置路径检测。
#    使用 `--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` 等重新运行以添加其他代理；完整列表见 docs/install.md。
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

# Grok Build CLI 示例：
# ai-memory install-mcp --client grok --apply
# ai-memory install-hooks --agent grok --apply

# Kiro CLI v2 示例（需要现有的 Kiro 代理配置）：
# ai-memory install-mcp --client kiro-cli --apply
# ai-memory install-hooks --agent kiro-cli --apply

# Kiro CLI v3 示例（独立钩子注册）：
# ai-memory install-hooks --agent kiro-cli-v3 --apply

# Command Code stable MCP + 生命周期示例：
# ai-memory install-mcp --client command-code --apply
# ai-memory install-hooks --agent command-code --apply

在 Linux/macOS 上，到此完成。像往常一样启动 Claude Code 会话 - 每个提示和工具调用现在都会进入 ai-memory，您在此项目中打开的下一个会话将看到交接信息，包含您的进度。在 macOS 上，无需 Docker 时也支持并推荐使用原生发布二进制文件；请参阅 docs/macos.md。

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

# /config.toml
[auto_scope]
mode = "per_session"

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

桥接器仍连接到已配置的本地或远程 HTTP 服务器并转发其承载令牌，同时将 Claude 的生命周期会话 ID 附加到每个 MCP 请求。现有静态 HTTP 安装仍为默认。请参阅 docs/auto-scope.md 了解 Claude 的 /clear 和隐式恢复限制。

install-mcp / install-hooks 命令在设置时使用 AI_MEMORY_SERVER_URL / AI_MEMORY_AUTH_TOKEN；否则默认为 http://127.0.0.1:49374（匹配上述服务器）且无承载令牌。如果钩子在 ai-memory MCP 条目已存在后安装，install-hooks 会重用该端点，因此远程 MCP 设置无法静默重新生成仅环回钩子。两个命令都是幂等的 - 重复运行会替换 ai-memory 的条目，保留您配置的其他每个服务器/钩子，并在每次修改写入前在文件旁写入带时间戳的 .bak- 备份。

钩子脚本会自动暂存到 ~/.local/share/ai-memory/hooks//；重新运行会覆盖它们，因此未来的镜像更新会包含更新的钩子。省略 --apply 则打印代码片段而非修改。

对于 Claude Code，CLAUDE_CONFIG_DIR 会将 MCP 注册重定位到 $CLAUDE_CONFIG_DIR/.claude.json，钩子重定位到 $CLAUDE_CONFIG_DIR/settings.json，全局托管技能重定位到 $CLAUDE_CONFIG_DIR/skills。当目录在其现有 $HOME 挂载下时，Docker 包装器会转发此变量。当 Claude 配置根目录在 $HOME 之外时，请使用原生二进制文件。卸载会检查活动的重定位路径和 Claude 的 home 默认路径，因此启用该变量不会遗留旧默认路径的 ai-memory 安装。

如果您的代理经常在仓库子目录或链接的工作树中启动，请向 install-hooks 添加 --project-strategy repo-root，以便捕获会折叠为主 git 仓库名称；详情请参阅 docs/install.md 和 docs/marker-file.md。后续的裸 --apply 刷新（包括 ai-memory upgrade）会保留该选择；明确传递 --project-strategy basename 可移除它。Docker 包装器还会将 ai-memory status 和 ai-memory bootstrap 等瘦客户端命令桥接回主机的环回服务器。使用上述本地 Docker 快速开始时，无需 AI_MEMORY_SERVER_URL 覆盖。

托管工作流是可选的。它们在主机上执行测试框架，而服务器可保持本地或远程：

ai-memory run claude
# 后续在另一个测试框架中继续同一工作流
ai-memory run codex --yolo
# 省略名称则继续最新的可用本地测试框架会话
ai-memory run
# 或恢复最新的托管签出而不必先更改目录
ai-memory continue

如需后续移除 ai-memory，请从相同主机环境运行 ai-memory uninstall --apply。它会移除 ai-memory 拥有的配置条目、指令块、默认根目录托管技能文件和生成的插件文件，但仅在匹配其 ai-memory 签名后；使用 --target-dir 安装的自定义技能根目录需手动清理。如果使用自定义端点安装了 MCP，请使用 --mcp-url，仅当需要缩小移除范围到匹配条目时使用 --mcp-name。

安装注意事项

• SELinux： 在强制模式的 Linux 主机上，包装器仅自动向触及绑定挂载主机文件的短期辅助命令添加 --security-opt label=disable。它不会更改长期运行的服务器容器或重新标记 $HOME；不要在 whole home 绑定上添加 :z/:Z。无根引擎也会为这些命令添加 -u 0:0。Docker 和 podman 在不同的 info 键下报告无根模式和 SELinux 支持；两者都会被读取。当 AI_MEMORY_DATA_DIR 选择主机目录或显式 --config 读取主机文件时，同样的处理也适用。请参阅 docs/install.md。

• Windows： 在 WSL2 内使用 Linux 路径，或从 PowerShell/cmd 使用原生 Windows 包装器。本地支持的配置默认使用主机原生命令：Claude Code 可能使用其支持的 ai-memory.exe 可执行形式，而其他代理使用匹配其钩子架构的原生单命令字符串。Docker 包装器使用 -EncodedCommand 保护 .ps1 回退命令免受嵌套 PowerShell 展开；升级后重新运行 install-hooks --agent --apply 以便现有钩子条目接收当前形式。PowerShell/Git Bash 脚本捆绑包是兼容性回退，不强制执行捕获策略 v1。不要混合路径世界。请参阅 docs/windows.md。

• Docker compose： 支持 docker compose -f docker/docker-compose.yml up -d；代理设置与上述步骤 3 相同。

• 远程服务器： 在安装 MCP/钩子前，在客户端设置 AI_MEMORY_SERVER_URL=http://:49374 和 AI_MEMORY_AUTH_TOKEN=。显式 --server-url 标志仍有效，但当环境变量已设置时不再是必需的。任何非环回服务器都应使用承载认证。

• 托管启动包装器： ai-memory run、ai-memory show 和 ai-memory continue 必须由当前主机包装器拦截，以便本地签出、原生测试框架和会话存储保持可访问。旧包装器可能将这些命令传入 Docker 并无法找到签出或主机可执行文件。在代理机器上运行 ai-memory upgrade 进行刷新。主机原生运行器继承 AI_MEMORY_SERVER_URL、AI_MEMORY_AUTH_TOKEN 和主机 PATH。

• 升级： 对于 Docker 包装器安装，在每个代理机器上运行 ai-memory upgrade。它会刷新本地包装器、拉取最新镜像并在 ~/.local/share/ai-memory/hooks// 下重新暂存钩子脚本。原生包/源码安装应在升级二进制文件后重新运行 ai-memory install-hooks --agent --apply。远程/家庭实验室服务器仍需单独重新部署；本地包装器升级仅更新客户端机器。现有项目提示文件保持有效。当您需要新的工具指导时，刷新托管的 ai-memory 路由包（ai-memory install-instructions，或对于基于 AGENTS 的项目使用 --target AGENTS.md）。刷新会从相同的二进制文件资产写入精简的带标记代码片段和托管代理技能。

有关支持矩阵中的每个客户端，以及基于 curl 的钩子安装、源码构建、CLI 环境变量和完整子命令参考，请参阅 docs/install.md。CLI 的标签补全在 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 的危险例外。认证不加密承载令牌：对于局域网或远程访问，请使用HTTPS 反向代理指南中描述的现成 Caddy 或 Cloudflare Tunnel 模板。当服务器暴露到环回之外、不受信任的本地进程共享机器或数据目录包含敏感项目历史时，启用承载认证：

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=",localhost,127.0.0.1" \
    akitaonrails/ai-memory:latest

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

承载认证保护 /mcp、/hook、/handoff、/admin/* 和 /web/*。浏览器访问 /web 使用 HTTP Basic 认证，令牌作为密码。当 /web 通过反向代理暴露时