ai-memory（akitaonrails/ai-memory）：把编码智能体的长期记忆做成 git 版 Markdown wiki，默认零 LLM 调用跑出 hit@5 0.951

一、导读

编码智能体最大的浪费不是 token，而是「重复解释」：昨天在 Claude Code 里讲清的架构约束、试错路径、遗留问题，今天换到 Codex 就得再讲一遍；换台机器、交给同事，又归零。ai-memory 的判断是：记忆不该是某个工具的私有笔记本，而应是项目目录里一份 git 版本管理的 Markdown wiki，由所有智能体共享读写。

它交出三个可核验的答卷：默认零 LLM 调用（无 API key 也能完成捕获、检索、交接）；LongMemEval-S 全 470 题 zero-LLM hit@5 达 0.951（3.0 版引入观察流后，从 0.662 跃升）；以及一个单一 Rust 二进制里同时承载 24 个 MCP 工具、20+ 智能体接入与多用户鉴权。当日涨星 +666、总星 11,265（2026-10-19 抓取）。

二、项目速览

项目	内容
仓库	`akitaonrails/ai-memory`（官网 aimemory.sh）
作者	Fabio Akita（GitHub `akitaonrails`，巴西知名 Rails 布道者，博客 akitaonrails.com）
主语言 / 许可	Rust（workspace 10–11 个 crate）/ MIT
Star 总数 / 当日涨星	11,265 / +666（GitHub API 与 Trending 日榜，2026-10-19 抓取）
Fork / 未决 Issue	798 / 14
首次提交	2026-05-21（仓库创建同日）；v1.0.0 于 2026-06-12 发布
最新版本	v3.1.1（2026-10-17），此前 v3.1.0（10-16）、v3.0.1（10-15）、v3.0.0（10-14）、v2.6.7（10-13）——近一周连发 5 个版本
代码 / 文档规模	仓库 1,394 个文件；`README.md` 42 KB、`docs/ARCHITECTURE.md` 122 KB、`CHANGELOG.md` 104 KB
平台支持	Linux、macOS、NixOS、Windows 原生（实验性）、WSL2、Docker/Podman、AUR、RPM
智能体接入	20+ 家（Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Grok Build CLI、Kimi Code、Kiro、Copilot CLI、Factory Droid、Meta Muse Code、IBM Bob、Antigravity、OpenClaw 等）

一句话概括：把「编码智能体的长期记忆」做成一份可 grep、可 git diff、可由团队共用的 Markdown wiki，数据库只是可重建的派生索引。

三、为什么是它：问题背景与定位

第一，每个智能体都在造自己的孤岛记忆。 Claude Code 有自己的笔记，Cursor 记得一些东西，各家平台都在补记忆功能——但官方文档写得很直白：这些笔记只活在一台机器上、只属于一个智能体，一旦换工具或把活交给同事，就掉出视野。这不是实现问题，而是所有权问题：记忆被绑定到了产品，而不是绑定到项目。

第二，交接（handoff）比检索更难。 单纯的「向量检索历史对话」解决不了「我昨天做到哪、什么试过没用、什么还悬着」。ai-memory 把交接做成类型化协议：每条 handoff 有 owner，且只被认领一次（claim-once），配合 memory_handoff_begin / accept / cancel / list 形成闭环节拍。这是它区别于「事实抽取型」记忆工具的核心。

第三，零 LLM 默认值是一个产品判断。 记忆系统若每次写入都要过一次大模型，成本与隐私都难以接受。ai-memory 的默认路径是：捕获、检索、规则式摘要、记忆老化全程 0 次 API 调用；LLM 只在需要更丰富整合（memory_consolidate）或重写冷集群时按需开启。

第四，涨星动因是双引擎：工程口碑 + 生态顺风。 项目在 2026-08-19 前后约 3,220 星，两个月涨到 1.1 万星；其间 10 月中旬连续发布 3.0 与 3.1 大版本，同时 GitHub 日榜被编码智能体与配套基建占满——记忆层正是这条链上被反复讨论的缺口。作者本人的工程随笔（「软件是黏土不是乐高」）也在开发者社区二次传播。

四、【重点】架构原理

4.1 整体架构：捕获 → 整合 → 召回 → 交接

graph TB
    subgraph HARNESS["智能体宿主（20+ 家）"]
        A1["Claude Code / Codex / Cursor / Gemini CLI"]
        A2["OpenCode / Kimi Code / Grok Build / Copilot CLI"]
        A3["Antigravity / Droid / Muse / IBM Bob / OpenClaw"]
    end
    subgraph HOOK["捕获层 ai-memory-hooks"]
        H1["生命周期钩子 SessionStart / UserPromptSubmit / PostToolUse / SessionEnd"]
        H2["Sanitized 观察唯一构造器 sanitize()"]
        H3["最近标记捕获策略：被丢弃事件不进 spool"]
    end
    subgraph SVC["服务层 单一 Rust 二进制"]
        S1["/hook 入口 → hook router → WriteCmd"]
        S2["ai-memory-mcp：24 个 memory_* 工具"]
        S3["ai-memory-web：/web 只读 UI + /api/v1"]
        S4["ai-memory-consolidate：ingest / lint / sweep / auto-improve"]
        S5["ai-memory-workstream：原生 transcript 只读适配"]
    end
    subgraph STORE["存储层"]
        W1["ai-memory-wiki：原子写 + 文件监视 + git 版本"]
        W2["源真相：git-backed Markdown wiki（OKF v0.2）"]
        D1["ai-memory-store：单写者 actor + 读者池 + decay 数学"]
        D2[("SQLite：FTS5 / 实体 / 链接 / 向量（派生索引）")]
    end
    subgraph EXT["可选外部能力（默认关闭）"]
        L1["ai-memory-llm：provider 鉴权边界 + LlmProvider / Embedder trait"]
        L2["本地嵌入 all-MiniLM-L6-v2 384 维（candle 纯 Rust）"]
        L3["向量检索 / LLM 整合 / dream 重写 / answer 合成"]
    end
    A1 --> H1
    A2 --> H1
    A3 --> H1
    H1 --> H2 --> H3 --> S1
    S1 --> S2
    S1 --> S4
    S2 --> D1
    S3 --> D1
    S4 --> W1
    S4 --> L1
    D1 --> D2
    W1 --> W2
    D1 -.派生索引可从 Markdown 重建.-> W2
    L2 --> D2
    L3 -.opt-in.-> D1

核心不变量只有一条：Markdown wiki 是源真相，SQLite 是派生索引。 索引永远可以从文件重建（reindex-from-wiki），所以没有内容被锁进二进制块；wiki 是纯 Markdown + YAML frontmatter，可以直接 grep、用 Obsidian 打开、手工编辑，或用 rsync 搬走。这条不变量决定了后面几乎所有设计取舍。

4.2 分层模块拆解

crate 划分（10 个生产 crate，职责单一、无循环依赖）：

crate	职责
`ai-memory-core`	领域类型、错误、ID。不做任何 IO
`ai-memory-store`	SQLite + 单写者 actor + 读者池 + decay 数学
`ai-memory-wiki`	Markdown 原子写、文件监视、git
`ai-memory-mcp`	rmcp transport + 工具路由
`ai-memory-hooks`	payload schema、sanitizer、`/hook` 入口
`ai-memory-llm`	provider 鉴权边界 + `LlmProvider` / `Embedder` trait
`ai-memory-consolidate`	Karpathy 式 ingest / lint / sweep / auto-improve 流水线
`ai-memory-web`	只读 `/web` UI 与 `/api/v1` JSON 路由
`ai-memory-workstream`	原生 transcript 的只读读取与启动适配
`ai-memory-cli`	`ai-memory` 二进制入口 + 薄 HTTP 子命令

「层」是按数据流走的，不是按目录走的：

捕获层——智能体在工作时通过生命周期钩子发出已脱敏的观察（observations）。Shell 钩子用 curl 把事件 JSON POST 到 /hook，硬超时 ≤200 ms；原生 ai-memory hook --event ... 走本地 spool，用稳定的幂等键，会话结束时交给脱离进程的 hook-drain 处理。智能体热路径永不阻塞在网络 IO 上，服务器饱和时直接返回 429 而不是无限排队。
整合层——SessionEnd 时服务器合成 sessions/<id>.md 摘要页（规则式，不用 LLM），并开启一条 handoff 供下一个智能体认领。若配置了 LLM，memory_consolidate 会把摘要重写成更耐久的页面，或展开成 concepts/、decisions/、gotchas/ 多页批次。
召回层——memory_query 融合四条流：FTS5 全文、实体匹配、链接邻居（图）、可选向量，用 RRF（倒数排名融合）合并成单一排名，再叠加观察证据流与按 kind/tier/pinned/tag 的有界权威度调整。
交接层——claim-once 的 handoff，以及跨项目信箱（memory_message_send / list / pop / cancel）。

契约层的两个抓手：OKF 与 as_of。

OKF（Open Knowledge Format）原生合规：从 2.0 起，wiki 的每个页面文件本身就是 OKF v0.2 概念文件——有可解析 YAML frontmatter 与非空 type，bundle 根 index.md 声明 okf_version: "0.2"。type 由路径族派生：sessions/→Session Summary、decisions/→Decision、gotchas/→Gotcha、procedures/→Procedure、concepts/→Concept、_rules/→Rule。这意味着记忆跨工具可移植：换一个 OKF 兼容工具、甚至不用任何工具，拿到的仍是带标准元数据的普通 Markdown。
bi-temporal-lite（as_of 查询）：entity_page_links 与 pages 都携带摄取时间窗口（valid_from / valid_to、链接粒度的 superseded_at），于是「那次决定做出时，wiki 上写的是什么」可以答。作者对范围很诚实：只记「我们何时学到或替换」而非「事实在世界上何时为真」，因为后者需要信任 LLM 给事实标注时间，而零 LLM 默认路径永远无法填充这些字段。

4.3 核心机制一：观察证据流——0.662 到 0.951 的那一跃

3.0 最大的检索改进是观察流（observation stream，默认开启）。它把原始观察当作对页面的「投票」证据参与排名，而这一步带来的是本次调研中最值得记录的单一数字：

模式	hit@1	hit@5	hit@10	p50 / p95	平均上下文 token
2.4/2.6 零 LLM FTS（流关闭）	0.511	0.662	0.687	—	—
3.0 零 LLM FTS（流开启）	0.857	0.951	0.972	12 ms / 101 ms	528
2.4/2.6 本地嵌入（流关闭）	0.543	0.800	—	—	—
3.0 本地嵌入（流开启）	0.766	0.945	0.972	98 ms / 228 ms	528

（470 题 LongMemEval-S，官方 benchmark，3.0.0 版本对比同一构建的流开与流关；来源 docs/benchmarks/README.md，2026-10-13 记录。）零 LLM FTS 净增 +0.285，其中 139 题变好、仅 3 题变差；本地嵌入净增 +0.130。代价是 top-5 命中的上下文 token 分别上升 3.8%（FTS）与 17.0%（本地嵌入）——一次用少量上下文预算换大幅 recall 的典型交易。

3.1 版本复测（2026-10-16）确认无回归：FTS 各切点完全一致（hit@5 0.951），本地嵌入 hit@5 从 0.943 到 0.940，落在预先登记的 ±0.005 噪声带内。分切片看，knowledge-update（72 题）、single-session-assistant（56 题）、single-session-user（64 题）的 FTS hit@5 均为 1.000；最弱的是 single-session-preference（30 题）0.700。

4.4 核心机制二：零 LLM 的记忆老化——衰减公式与「可逆删除」

记忆系统真正的长期难题是遗忘。ai-memory 的 retention 是一个纯函数（crates/ai-memory-store/src/decay.rs）：

retention = salience·exp(−λ·age_days)
          + σ·ln(1+access_count)·exp(−μ·days_since_access)·breadth

默认参数：λ=0.02（约 35 天半衰期）、σ=0.6、μ=0.04、salience_default=1.0、cold_threshold=0.20、hard_delete_after_days=180；salience 钳制在 [0.25, 2.0]，步长 0.25。

三个设计细节值得记下：其一，访问会强化记忆——bump_access 只更新 access_count、last_accessed_at 与按 actor 的广度行，走单写者 actor 的异步 fire-and-forget 路径，按 (page, operator) 每 60 秒最多一次，且不改写搜索索引（FTS-exempt）。其二，评分只用于清扫与策展，不参与检索排序——文档明确写「retention_score 只被 forget-sweep 和 curator 消费，读与搜路径不读这个分数」，任何想让老化影响排名的提案都属于新行为。其三，删除是可逆的：用 supersede-not-delete 加 restore-page，原文留在 git 里、版本链可回退；会重写或丢弃内容的机制（压缩、去重、分档曲线）默认关闭，而只会让记忆留得更久的「访问加权保留」始终开启。

4.5 性能与互操作优化手段、以及设计取舍

热路径不碰网络（钩子 ≤200 ms 硬超时、202 立即返回、饱和返 429）→ 代价是可能出现投递重试，收益是绝不拖慢智能体本身。
索引与数据同事务提交（不做事后后台重建索引）→ 代价是写路径更重，收益是不会出现「数据写了但搜不到」的窗口。
单写者 SQLite actor（所有写经一个 mpsc 通道到专用 OS 线程）→ 代价是写入受队列约束（文档称写入上限约 700/s，并注明是实测值），收益是并发写不坏库。
本地嵌入默认开启（candle 纯 Rust + all-MiniLM-L6-v2 384 维，无需 key、无需 GPU、无需外部服务）→ 代价是首次启动要后台下载模型，收益是语义召回不用把记忆送出本机。
Windows 原生标记为实验性（NTFS 文件索引、瞬时错误的有界重试）→ 代价是跨平台一致性成本高，收益是覆盖真实开发环境。
诚实标注边界：docs/temporal.md 明说只有摄取时间、没有世界时间；ui / answer / reasoning 等 LLM 路径默认关闭，且文档注明 answer 质量尚未经评测验证。

4.6 与其他记忆架构路线的差异

路线	代表	记忆形态	相对 ai-memory 的取舍
事实抽取	Mem0 / LangMem	原子事实行	便宜但丢失关系与因果上下文；依赖 LLM 抽取；非 file-first；其编码插件需云端 key
时序知识图谱	Zep/Graphiti、Cognee	双时态知识图谱	时序推理更强，但需要独立图数据库；ai-memory 只用双时态精简版 + 类型化边，单二进制搞定
文件优先	basic-memory	磁盘 Markdown	同样 file-first，但缺自动生命周期捕获、缺 claim-once 交接与多用户共享
编码智能体钩子捕获	claude-mem、MemPalace、agentmemory	钩子 + 库	生态成熟、用户多；但 claude-mem 对每条观察都跑 LLM observer 且有付费云层；ai-memory 的差异是零 LLM 默认 + claim-once 交接 + 类型化跨项目消息
托管记忆 API	Supermemory、LiquidLM	云服务	开箱即用、连接器丰富；但云优先、默认存储不透明，自托管二进制不开源且默认带遥测
用户建模	Honcho	记住「用户」	问题不同：它记人，ai-memory 记项目

值得注意的行业趋势：作者在对比文档里承认，过去几个「独门」选择如今已成共识——git-backed 可编辑 Markdown 与钩子捕获已有多家跟进。真正还剩下的差异是零 LLM 默认、claim-once 交接、单一自托管二进制上的按项目多用户鉴权。

五、【重点】应用场景

以下五个场景均可复现，命令取自官方 README 与文档。

场景一：换智能体不断档

业务痛点。 任务做到一半配额耗尽，或想用另一个模型的长处。重启新会话意味着重新解释架构、重新试错。

做法。 用 ai-memory run 启动宿主，它会在首次运行时自动为该宿主装好钩子与 MCP，并带上跨宿主的会话连续性。

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

接收方会被告知：当你说「继续」而有限的启动包缺少细节时，去读环境变量 AI_MEMORY_PREVIOUS_SESSION_HISTORY 指向的临时 Markdown 投影；该文件随托管子进程退出而消失，且只存在于本机。远端服务器只收到宿主与会话身份，永远不收到本地 transcript 的路径或正文。

收益与量化指标。 量化锚点以检索为主：全 470 题 zero-LLM hit@5 0.951，knowledge-update 切片 hit@5 1.000——这类「后来信息覆盖先前说法」的场景正是换手时最容易踩的坑。摄取吞吐方面，官方评测中 FTS 模式处理 278,946 个条目、1,403 个请求，吞吐 12 items/s 每问题流。

适用边界。 ①跨机器切换拿不到原生 transcript 投影——只能拿到服务器侧的可移植账本与交接。②需要 3.1.0 或更新版本的宿主客户端；若 PATH 里存在更早的旧二进制，会遮蔽更新后的 wrapper（用 type -a ai-memory 排查）。③只有加 --require-server 才会在服务器不可达时 fail-closed。

场景二：跨项目画像

业务痛点。 每个新仓库都要重新交代一遍：我用 pnpm 不用 npm、测试放哪、目录怎么组织、审查流程是什么。

做法。 启用跨项目画像（单用户默认开启）。会话开始时，画像以小段围栏块的形式排在最前面（在任何 handoff、project brief 或收件箱通知之前）。

# 单用户时默认 on，跨所有 workspace 共享，位置：default/_global 下的 profile/
# 多用户服务器：默认 off，需显式开启，且每人一份私有画像
ai-memory setup     # 交互式确认；--plan 只打印计划不改动

优先级顺序是硬规则：①当前对话指令 → ②仓库规则文件（AGENTS.md / CLAUDE.md）→ ③项目记忆 → ④跨项目画像。所以规则文件写了 npm，画像里的「我通常用 pnpm」就不生效；当没人说话时，智能体采用画像默认值，并主动说明用了哪个默认值以便你纠正。

收益与量化指标。 定量收益在提示词层面：画像放在会话开头且只在「你的习惯改变时」才变化，因而落在宿主提示词可被缓存的部分，直接影响前缀缓存命中率。定性收益是省掉每仓库一次的重复交代。安全性上有一条明确边界：画像条目是偏好，不是命令——它可以选工具、选布局、选约定，但不能授权任何当前指令不允许的事。

适用边界。 ①多用户服务器上默认关闭，需每人单独开启，避免一个人的习惯泄漏给另一个人。②它不覆盖更具体的东西，不要指望用画像强制团队规范——那是仓库规则文件的职责。

场景三：团队共享一个记忆服务器

业务痛点。 新人接手老项目，最贵的是「那个坑我们踩过了」这类隐性知识；而单人笔记天然无法共享。

做法。 团队指向同一台服务器。多用户鉴权、按人归属与审计日志内建而非付费层。

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
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

收益与量化指标。 知识按项目共享、个人交接仍保持私有；鉴权梯度为 root → DB 用户 token → OIDC，配合按人归属与审计日志。存储上是「一服务器一存储卷」，内嵌 SQLite 与 vendored libgit2，不需要外部服务，因此笔记本、homelab、局域网服务器都能跑，且没有付费层。

适用边界。 ①服务器之间不自动复制；跨服务器同步要用 3.0 的 ai-memory-wikisync companion。②settings（含 llm_headers）会落到全局可读的 Nix store 路径，密钥必须走 agenix / sops-nix / environmentFile。③LAN/WAN 绑定必须前置 TLS。

场景四：让智能体去问另一个项目的智能体

业务痛点。 你在 A 项目开着 Kimi，B 项目开着 Claude，A 需要 B 改一个接口。让 Kimi 去读 B 的代码既浪费 token 又污染 A 的记忆。

做法。 用类型化消息，让 A 写一封自包含的请求投进 B 的收件箱；B 里的 Claude 取件后照办。

# 在 A（Kimi）里说：
「让 default/project-b 的智能体加一个 /v1/export 端点，流式输出 NDJSON，保留现有鉴权中间件，用 ai-memory 发过去。」
# Kimi 调用 memory_message_send(to_workspace="default", to_project="project-b", body="...")

# 在 B（Claude）里说：
「检查我的 ai-memory 收件箱。」
# Claude 调用 memory_message_pop 取出并清空队列；只看不取用 memory_message_list

收益与量化指标。 这是 ai-memory 唯一故意跨出按项目隔离边界的地方，且跨界是显式且有方向性的：一个项目只能看到发给它的（收件箱）或它发出的（发件箱）。队列语义严格：消息在接收项目某会话 pop 之前是 pending，pop 后变 claimed——且只被认领一次，第二次 pop 返回空；发件人可 cancel（已被取走的不能撤回）。收件箱上限 256 条待处理消息，满了拒绝新发送；收件项目必须已存在，拼错的项目名会被拒绝，而不是变成没人读的死信箱。

适用边界。 ①不要用 wiki 页当消息——写页面只是把知识存进目标项目，永远不会作为邮件浮出，一份「报告」会静默躺在那里没人读。②消息正文必须是完整提示词，因为接收方看不到发件项目。③静态 MCP 客户端（含 Claude Code 的 MCP 连接）不转发会话 id：pop / cancel / send 会拒绝服务器推断出的作用域（shared_slot、startup_seed、default），因为读错信箱已经够糟，而 pop 会认领别人的消息、cancel 会清空别人的发件箱。

场景五：把智能体会话变成可审计的项目档案

业务痛点。 事故复盘时最常问的是「这个坑我们以前知道吗」。单纯的聊天记录既不可查询也不可重放。

做法。 用 as_of 做摄取时间审计，用 explain 看排名为什么是这样。

# 当时知道什么？（摄取时间语义，非世界时间）：memory_query(as_of=..., scopes=[...])
# 为什么这条排在前面？memory_query(query="...", explain=true)

explain=true 会附带每条命中的 score_details：各流排名、匹配到的实体、原始 FTS/cosine/实体逆频分数、投票的观察 id、RRF 贡献、图来源（含 causes / fixes / contradicts 类型化边）、页面证据数、权威度乘子，以及可选的 rerank 分数；顶层还有 streams_active 与 timings（fts_ms、entity_ms、vector_ms、graph_ms、observation_ms、rerank_ms）。

收益与量化指标。 延迟是实打实的：FTS 在 470 题上 p50 12 ms / p95 101 ms，本地嵌入 p50 98–99 ms / p95 225–228 ms，平均返回上下文 528 token。也就是说审计路径的检索成本对交互式使用是可接受的。

适用边界。 ①普通 memory_query 回答「我们现在知道什么」，是 99% 情况下的正确调用；as_of 只用于审计与复盘。②删除就是删除——显式 purge 会级联清掉实体链接，时间线不会在 purge 后存活。③timings 只在 explained 查询里读取，普通路径不取时钟，别指望从普通响应里拿性能数据。

六、快速上手

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup
ai-memory setup --plan     # 只打印计划，不做改动
ai-memory setup --web      # 把计划作为网页展示，勾选后应用
yay -S ai-memory-bin && ai-memory setup              # Arch（AUR）
sudo dnf install ./ai-memory-*.rpm && ai-memory setup # Fedora（RPM）
claude plugin marketplace add akitaonrails/ai-memory && claude plugin install ai-memory@ai-memory
ai-memory setup --agent codex   # 只装一个宿主

然后重启宿主，问它一句「What do you remember about this project?」，如果它通过 ai-memory 回答，说明链路打通了。安装类命令都是幂等的，且在改动任何文件前写带时间戳的备份。

七、横向对比

事实核对于 2026-10-19，来源为各项目仓库与官方文档。注意：各家公布的数字口径不同，因此下表不做排名，只列口径。

对比项	ai-memory	claude-mem / MemPalace	Mem0 / LangMem	Zep / Graphiti	basic-memory
记忆形态	git 版 Markdown wiki（源真相）+ SQLite 派生索引	钩子捕获 + 库	原子事实行	双时态知识图谱	磁盘 Markdown
默认是否需 LLM	否（零 LLM 路径完整可用）	是（对每条观察跑 LLM observer）	是（抽取）	是	否
跨智能体交接	claim-once 类型化协议	部分	否	否	否
跨项目消息	有（类型化收件箱，上限 256）	否	否	否	否
多用户 / 归属 / 审计日志	内建，非付费层	团队服务器（MemPalace）	云侧	云侧	否
外部依赖	无（内嵌 SQLite + vendored libgit2）	各异	云 API key	需图数据库	无
公布检索口径	LongMemEval-S hit@5 0.951（零 LLM，470 题）	MemPalace 96.6% R@5、98.4%（450 留出题），纯检索	端到端 QA 准确率	端到端 QA 准确率	无
可移植性	OKF v0.2 原生，页面即标准文件	导出	不透明	不透明	Markdown

一句话选型：要「跨工具、跨机器、跨人共享的项目记忆」并且不想被云与 LLM 费用绑住，选 ai-memory；只要个人单机事实抽取、且愿意付费换开箱即用，托管路线更省事。

八、局限、风险与社区观察

第一，作者对评测口径非常诚实，这既是优点也是提醒。 docs/comparison.md 明确写道：Mem0、Zep、Hindsight、EverOS 公布的是端到端问答准确率（LLM 读检索上下文、LLM 判分，各自有 reader 与 judge 模型和上下文预算），与 ai-memory 的 hit@5 不是同一种东西，因此「本页不主张任何排名」。同理，agentmemory 的 95.2% recall_any@5 来自「整段原始会话、关闭 reranker」的组件级夹具，与流水线级数字不可比。技术选型时不要跨口径比大小。

第二，检索数字受过夹具修正影响。 官方披露：首次公布的观察流数字（0.666 → 0.868）来自一个在问题间复用 session id、且漏掉部分会话页面的夹具；2026-10-13 修正后的夹具逐题按各自 session id 回放，才得出 0.951。另外，组件模式（跳过捕获、整段原始会话索引、只比排名）下零 LLM FTS 可达 0.972，差值来自捕获管线本身而非 2 KB 摘录上限（把恰好是捕获所留文本的页面拿来测，得 0.968）。这说明：读这类数字必须连夹具一起读。

第三，写入有上限，且是实测值。 文档给的写入天花板约 700/s，并明确说是「测出来的，不是猜的」。对个人与中小团队足够，但别当成高并发采集后端。

第四，Windows 原生仍是实验性；生态成熟度不均。 支持矩阵里 Native Windows 标注 Experimental；Crush 是 Managed-only，CodeBuddy Code 是 Hooks-only，而 Claude Desktop、VS Code Copilot、Zed、DeepSeek Harness 等则是 MCP-only。也就是说不同宿主的接入深度差异很大，跨宿主无缝的前提是你用的两家都是「一方集成」。

第五，记忆系统的安全面必须自己评估。 仓库维护了一份 docs/security-boundaries.md（约 255 KB），逐条列出边界、强制代码、对抗性测试与覆盖率判定（STRONG / PARTIAL / FUTURE），并说明「快乐路径或单租户测试看不到隔离缺陷」。文档也多次强调信任边界：仓库文本、观察、wiki 页面与既有提案一律当作不可信数据而非指令。这类纪律值得肯定，但仍建议生产前自行审阅写入范围与凭据处理。

第六，版本迭代极快，API 与文档会持续漂移。 一周内 5 个 Release（2.6.7 → 3.1.1），CHANGELOG.md 已达 104 KB。好处是活跃，坏处是任何引用的行为细节都应以你安装的版本为准。

第七，商业化与 License。 仓库 MIT，未发现强制云端绑定。需注意 MIT 只覆盖本仓库代码——你接入的 LLM/Embedding provider 与宿主智能体自身的许可各自独立。

九、小结与行动建议

ai-memory 最值得借鉴的不是功能清单，而是三条被反复执行的工程纪律：源真相必须是你能用 grep 和 git 检查的普通文件；默认路径不该依赖外部模型（隐式成本会杀死长期使用）；结构从使用中长出来，而不是先设计好再往里灌——作者自述 ScopeResolver 不是一开始猜出来的，而是在多用户需求真实出现后，从重复代码里提取出来的（那次重构 +1,239 / −249 行，形成 601 行集中式解析器）。

五条建议：

先用 --plan 看它要改什么，再决定装哪些宿主。 确认后再挑 --agent，避免一次性改动你所有工具链的配置文件。
把「零 LLM 路径」当作基线，把 LLM 当作加速器。 先跑一周不配任何 provider，看纯 FTS + 规则摘要够不够用；真正卡住了再开 memory_consolidate。
团队共享前先设计密钥与 TLS。 非环回绑定必须配 AI_MEMORY_AUTH_TOKEN，并在 LAN/WAN 绑定前置于 TLS 代理。
跨项目协作坚持用消息而不是页面。 页面只是知识、消息才是通知；要求发送方写自包含正文。
引用任何数字前先对版本与夹具。 写进内部评估时，务必带上「版本 + 数据集 sha256 + 模式 + 时间」四元组；官方自己都因夹具修正改过一次数，跨口径比较更不成立。

最后一个观察：这段时间 GitHub 日榜上，编码智能体与配套基建几乎占满——插件目录、技能库、沙箱、检索层，以及这一层的记忆。当每个团队都开始并行运行三五个不同厂商的智能体时，「上下文在工具之间如何流动」就会从便利性问题变成工程问题。ai-memory 给出的答案很朴素：别把记忆交给任何一家智能体厂商，把它放在你自己的 git 仓库里。

资料来源（均抓取于 2026-10-19）：GitHub Trending 日榜与 GitHub REST API；仓库 README.md（42 KB）、CHANGELOG.md（104 KB）、docs/ARCHITECTURE.md（122 KB）、docs/comparison.md、docs/support-matrix.md、docs/benchmarks/README.md、docs/benchmarks/longmemeval-s-3.1.0-release.md、docs/temporal.md、docs/okf.md、docs/local-embeddings.md、docs/design-memory-aging.md、docs/cross-project-profile.md、docs/agent-messaging.md、docs/security-boundaries.md、crates/ai-memory-mcp/src/server.rs；作者博客 akitaonrails.com（2026-05-23 / 2026-06-14 两篇）；第三方观察（Reddit r/BestGitHubRepos、note.com 2026-08-19 星数记录）。未能独立核实的信息已限定版本或标注待确认。