信息卡

一句话定位

Rust 实现的长期记忆服务器：用生命周期钩子捕获各编程 Agent 会话中的决策与教训，编译成 git 版本化的 Markdown wiki，让开发者换 Agent 继续工作而无需重新解释背景。

趋势解读：为什么火

CLI Agent 各自闭管会话上下文、换工具即失忆是 agentic coding 最痛的断点之一。ai-memory 的解法克制：不搞黑盒向量库，产出 grep 友好、可用 Obsidian 打开的 Markdown wiki；支持矩阵覆盖 Claude Code、Codex、Cursor、Gemini CLI、Kimi Code 等 20 余种客户端。本月净增 3300+ 星、增速榜第 3 名，证明跨厂商交接正成为刚需。

核心功能拆解

• 生命周期捕获：hooks 以 fire-and-forget 方式记录脱敏限长的提示词、工具调用与会话边界观察；
• 跨 Agent 交接（handoff）：新会话开始时自动注入"上次进行到哪里"结构化摘要，含开放问题与后续步骤；
• wiki 化知识：页面由会话结束时的观察编成连贯条目而非原始日志，支持追替链与 git 回滚单页；
• 托管工作流：ai-memory run claude 换 run codex 无缝续接同一逻辑工作流，附带便携事件账本与原生会话恢复；
• 实体辅助召回：每页存最多 10 个规范名词构成词法 RRF 流，查询措辞不同也能命中；
• 权威感知排序：全文检索、实体匹配、图谱邻居与可选向量多路融合，规则决策类页面排序靠前，召回内容仅作历史证据不充当指令；

7. 内置只读 /web 浏览器与 CLI 全家桶：status、bootstrap（生成种子页）、checkpoints、curator 维护报告、auto-improve 学习调度。

架构与技术栈浅析

C/S 架构：axum 服务器同供 HTTP 与 MCP 双协议，持有 SQLite（FTS5 索引）与 wiki 仓库；CLI 与钩子作为薄客户端经 HTTP 访问，保证单一事实源。LLM 完全可选——零 LLM 模式仍有全文检索加规则摘要，接入模型端点后才启用智能整合与向量召回。bearer token 支撑多操作员隔离；项目按 workspace/project UUID 硬隔离，`.ai-memory.toml` 可路由 monorepo 与 worktree。

安装与环境要求

Arch 用户最省事：yay -S ai-memory-bin（或源码包），自带 systemd 单元：

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

Docker 路线提供 amd64/arm64 双架构镜像，装官方 wrapper 脚本即可全容器运行；Windows 原生版为实验态，推荐 WSL2。Rust 工具链要求 1.95+。

快速上手示例

ai-memory run claude        # 托管启动并开始捕获
# ……干活、退出……
ai-memory run codex --yolo  # 换 Codex 续接，开场即收到 handoff
ai-memory run               # 省略名称则自动恢复最近的托管会话
ai-memory continue          # 任意目录直达最近一次检出的工作现场
ai-memory search "数据库选型"   # 终端快速 FTS5 检索

想让某条结论永久保存：让 Agent 执行 memory_write_page，或终端 write-page 命令写入并 `--pinned` 固定。

进阶使用要点

• capture-mode allowlist 反转为白名单模式：无标记目录零上报，适合涉密环境；
• Codex 等无真会话结束钩子的客户端可用 finalize-session 命令手动收尾交接；
• 共享服务器可开 per_session 作用域加 Claude session-aware 桥实现按会话隔离；
• 敏感路径用仓库级 ignore_paths 策略在源头丢弃匹配事件。

典型应用场景

• 跨天接力：晚间 Claude Code 半途退场，晨会前 Codex 凭交接摘要续写；
• 共用的 homelab 记忆服务：一台服务器管全家所有电脑，项目互不串味；
• 新项目冷启动：bootstrap 吞掉既有 git 历史与文档，一键生成种子页；
• 决策考古：问"六周前为何放弃方案 X？"秒答决策页而非翻记录。

同类生态位对比

Mem0、Letta 等向量库式记忆面向应用层 API，重 embedding、轻工作流钩子；CLAUDE.md 类静态文件方案无跨工具同步与衰减治理。ai-memory 的独特组合拳是"harness 钩子矩阵 + git 化 Markdown wiki + 可选 LLM"——记忆留在你手里而非黑盒服务里，这正是它踩中增长曲线的原因。

资源导航

• 架构设计：docs/ARCHITECTURE.md · 安装细则 docs/install.md
• 标记与白名单策略：docs/marker-file.md · 托管工作流 docs/managed-workstreams.md
• 平台指南：docs/macos.md、docs/windows.md、docs/users.md