AI Memory 记忆管理工具

项目定位

ai-memory 是面向 AI 编程代理的长期记忆层。它让开发者在 Claude Code、Codex、Cursor、Gemini CLI 等二十余种工具之间切换时，无需反复解释项目架构、失败方案和未决问题。记忆不再绑定某一台机器、某一个代理或单个用户，可跨代理、项目和设备延续，也可供团队共享。

核心特性

• 跨代理接力：所有工具向同一记忆库写入。交接采用类型化协议，包含负责人且只能被认领一次，避免多个代理重复处理同一任务。
• 完整会话延续：ai-memory run 可在启动新代理时注入共享工作流，以及上一代理可见历史的私有临时投影；远端仅接收代理与会话标识，不上传本地记录。
• 跨项目与跨机器：新会话自动获得常用包管理器、测试布局和架构习惯。记忆集中存放于自托管服务器，可在桌面、笔记本或内网设备间恢复工作。
• 团队协作：内置多用户认证、身份归属和审计日志。项目知识可共享，个人交接信息保持私有，且不属于付费功能。
• 纯 Markdown：事实源是受 Git 管理的普通 .md Wiki，可直接搜索、编辑、Obsidian 打开或同步。数据库仅是可重建的派生索引。
• 静默采集：生命周期钩子记录提示词、工具调用和会话边界；内容在存储前经过隐私净化，会话结束时整理为可读页面。默认全程不调用大模型，也不需要 API 密钥。
• 记忆老化机制：按层级衰减记忆，使用频率会减缓衰减；冷会话可压缩为文件路径、错误码和决策等持久事实，近重复内容可合并，矛盾会被标记。内容不会被硬删除，可通过版本链恢复。
• 可选后台整理：配置大模型后，可在空闲时将冷笔记重写为连贯页面；用户返回工作时立即取消。该功能默认关闭，且必须先通过召回评估。
• 透明与可审计：单个自包含二进制提供清理、状态检查和管理能力；写入上限约为每秒 700 次，所有变更均写入审计日志。

技术架构

采集 → 整理 → 召回 → 交接
生命周期钩子  会话结束  搜索与简报  下一代理
静默观察    Markdown 页面  混合排序   显式认领

代理通过生命周期钩子提交净化后的观察结果；会话结束时生成项目 Wiki 页面。后续会话在任意代理或设备上获得有长度上限的简报，并可组合全文、实体、链接及可选向量进行检索。管理界面是可选功能，构建时需启用 management-ui，运行时还需：

serve --transport http --enable-management-ui

安装与启动

Linux 和 macOS 可直接安装：

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup

安装脚本会校验发布包的 SHA-256，创建数据目录、用户服务及访问令牌，并为检测到的代理配置 MCP、钩子和 Agent Skills。--plan 仅展示计划，--yes 跳过确认，--agent 可指定代理。

Windows PowerShell：

irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex
ai-memory setup

关键 CLI 用法

推荐通过托管启动器运行代理，它会自动安装缺失的集成、绑定正确项目范围，并支持会话连续性：

ai-memory run claude
ai-memory run codex --yolo
ai-memory continue
ai-memory resume
ai-memory resume --search auth
ai-memory resume --all

若启动器异常退出并遗留租约，可在确认旧进程不存在后执行：

ai-memory run --force-unlock codex

服务不可达时，代理仍会启动并使用本地采集队列；恢复服务后可运行 ai-memory recover。要求服务可用时使用：

ai-memory run --require-server codex

手动接入其他代理时，分别安装 MCP 与生命周期钩子：

ai-memory install-mcp --client codex --apply
ai-memory install-hooks --agent codex --apply

卸载时仅移除本项目创建的内容：

ai-memory uninstall --apply

配置与部署

Docker 镜像支持 linux/amd64 与 linux/arm64。默认仅绑定回环地址，可通过端口映射向本机代理提供 MCP 服务：

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

省略大模型和嵌入相关环境变量即可运行零 LLM 模式，全文检索仍然可用。NixOS 模块可声明服务、监听地址及日志级别；API 密钥、认证令牌和请求头必须放入 ageSecret、sopsSecret 或 environmentFile，不可写入可公开读取的 Nix Store。局域网或公网监听还应在服务前部署 TLS 代理。