AI Memory 记忆管理工具

项目定位

ai-memory 是面向 AI 编程代理的长期记忆系统。它通过捕获各代理生命周期事件，将净化后的观察结果编译为可共享的 Git 仓库 wiki，从而在代理之间传递任务进度、失败尝试与未决问题。停止一个 Claude Code 任务后，可在同一目录启动 Codex 而无需重新解释架构。

核心特性

生命周期捕获

通过生命周期 hook 收集提示词、工具调用与会话边界事件。用户提示与压缩后摘要保留至 16 KiB，通知与工具节选保留至 2 KiB，每个观察体设有 16 KiB 的持久后限。原生命令强制执行捕获排除规则。

跨代理托管工作流

通过 ai-memory run 启动托管会话，在 Claude Code、Codex、Command Code、OpenCode、Pi、Crush、Kimi Code、Kiro CLI v2/v3、OMP、Grok Build CLI、Antigravity CLI 之间保持统一的逻辑工作流，并携带原生会话与可见事件账本。首次显式运行可交互接管已有会话，后续切换仅限同一检出目录下的原生历史。原生参数透传，仅 --yolo 与 --fresh 由包装器管理。

跨代理交接

SessionStart hook 在下次会话首条提示前注入类型化的交接块，包含开放问题、下一步骤与会话摘要。Grok 与 Zero 会忽略 SessionStart stdout，需通过 MCP memory_handoff_accept 恢复交接。

项目隔离

每个项目按 <wiki_root>/<workspace_id>/<project_id>/ 组织，通过稳定 UUID 标识。CLI 子命令沿 git 主根目录解析项目，hook 路由器默认使用 basename($cwd)。可在任意祖先目录放置 .ai-memory.toml 标记文件覆盖二者。工作树共享同一项目身份。

检索能力

FTS5、实体匹配 RRF、图邻居 RRF 与可选向量 RRF 生成候选结果。在截断前，权威感知调整优先采用 _rules/、decisions/、procedures/、gotchas/ 目录下的维护页面，而非相近的情节性会话证据。检索到的文本始终作为不可信历史证据，不可因其命名空间获得指令权威。

内置 Web 浏览器

只读 HTML 界面，提供项目列表、目录树、FTS5 搜索、Markdown 渲染与暗色模式，与 MCP 共享同一 axum 服务器。

按操作员隔离的内存槽

共享服务器上 [slots] per_user = true 配置将引擎写入的 _slots/ 上下文限定到经过身份验证的操作员命名空间。项目简介与合并提示接收共享槽与调用者自有槽，而精确 wiki 读取与搜索仍保持项目级范围。

支持矩阵摘要

原生二进制覆盖 Linux（amd64/arm64）、macOS（aarch64/x86_64）与 Windows x86_64。支持代理包括 Claude Code、Codex、Command Code、Devin CLI、OpenCode、Cursor、Gemini CLI、Antigravity CLI、Grok Build CLI、Kimi Code、OpenClaw、OMP、Pi 等。Crush 仅托管模式，VS Code Copilot、Zed、Claude Desktop 仅 MCP。LLM 提供商支持 Anthropic、OpenAI、GitHub Copilot、Gemini、OpenCode Zen/Go 等；嵌入提供商支持 OpenAI、Voyage、Gemini、Ollama、LM Studio、vLLM。

关键 CLI 用法

托管会话续接

cd /path/to/project
ai-memory run claude             # 启动托管 Claude 工作流
ai-memory run codex --yolo       # 切换到 Codex，保留原生会话
ai-memory run                    # 续接最近可用的托管会话
ai-memory run --fresh codex      # 在同一工作流中开启新 Codex 会话
ai-memory run kiro --v3          # Kiro v3 引擎显式选择

快速定位项目

ai-memory show            # 显示可访问项目
ai-memory show --json     # 机器可读发现，不启动任何代理
ai-memory continue        # 回到最近托管启动的检出目录

Wiki 维护

# 写入永久页面（--pinned 豁免衰减扫描）
ai-memory write-page --path decisions/0007-db.md \
  --body $'# Standardised on Postgres\n\n...' --pinned

# 查看与恢复
ai-memory checkpoints
ai-memory restore-page --path notes/foo.md --from <rev>

# 项目级操作
ai-memory purge-project --project experimental --confirm
ai-memory rename-project / move-project / move-session

# 审计与清理
ai-memory lint / curator / auto-improve / forget-sweep / audit-contamination

冷启动导入

cd /path/to/my-project
ai-memory bootstrap    # 收集 git log、README、docs 一次性摘要为种子页面

手动终接会话

无真正 SessionEnd hook 的代理使用：

ai-memory finalize-session --agent codex
ai-memory finalize-session --agent kiro-cli --session-id <uuid>

快速部署

Arch Linux

yay -S ai-memory-bin    # 预编译二进制，或
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

零 LLM 模式默认启用 FTS5、实体匹配与图邻居搜索；配置提供商后启用页面合并、矛盾检查与分阶段自动改进提案。