Trending 排名：#4｜快照日期：2026-09-22｜Stars：7,893｜Forks：530｜主语言：Rust｜License：MIT
写代码的人现在有个很烦的小问题：工具越来越多，记忆反而更碎了。Claude Code 记住一部分，Codex 另起一段，Gemini CLI、Cursor、OpenCode 又各有自己的上下文。你换一个 CLI，就要把架构、踩坑、待办重新讲一遍；换一台机器，很多上下文直接断掉。
aio-memory 要解决的就是这件事。它不是再做一个聊天记录搜索框，而是把 Agent 会话里的提示词、工具调用、会话结束点整理成一个 Git 化的 Markdown Wiki，再用 SQLite 派生索引做检索和交接。源码里最打动我的地方很朴素：Markdown 文件是事实源，数据库只是可重建的索引。这比“把一切丢进向量库”更像工程系统。
这篇文章按 2026-09-22 Trending 快照写成。榜单快照只保留仓库顺序；Stars、Forks、语言、Release 信息来自同日 GitHub 元数据与本地浅克隆核验。快照没有保留“今日新增 Stars”，所以增长部分不会编一个数字。
📋 项目概览
| 项目 | 内容 |
|---|---|
| 项目名 | akitaonrails/ai-memory |
| 一句话 | 给编码 Agent 做跨工具、跨机器、团队共享的长期记忆层 |
| GitHub | github.com/akitaonrail… |
| Stars | 7,893 |
| Forks | 530 |
| 语言 | Rust（API 语言统计约 9.45MB Rust，另有 Shell、PowerShell、HTML、Nix 等） |
| License | MIT |
| 版本 | GitHub 最新 Release：v2.4.0；main 分支 Cargo workspace：v2.3.2 |
| 默认分支 | main |
| 创建时间 | 2026-05-21 |
| 最近活动 | 2026-09-21 仍有合并提交，浅克隆 HEAD 为 5157c6b |
| 本地源码规模 | 712 个 Git 跟踪文件，295 个 Rust 文件，约 252,714 行 Rust |
🔥 为什么值得关注
Agent 记忆系统有两条常见路线。一条是“事实抽取”：每轮对话抽几个 atom，存到数据库或向量库里。另一条是“上下文导出”：会话结束时生成一段总结，下次手动贴回来。前者容易变成碎片，后者很快变成复制粘贴劳动。ai-memory 的取舍不一样：它把会话加工成可读、可改、可版本化的 Wiki 页面，然后再把全文检索、实体、链接、图邻居和可选向量叠在上面。
这使它看起来更像基础设施，而不是一个“记住我说过什么”的小插件。README 里有一句很关键：数据库是 derived index，可以从文件重建。源码架构也围绕这个约束展开：wiki 目录是事实源，SQLite 做 FTS5、实体、链接、handoff、audit、embedding 等派生能力；写入由单写者 actor 串行化，生命周期 hook 走有界超时，避免把 Agent 热路径卡死。
对团队协作来说，另一个点更现实：ai-memory 不绑定某个 Agent 厂商。它支持 Claude Code、Codex、OpenCode、Gemini CLI、Kimi Code、Kiro CLI、Cursor、VS Code Copilot MCP 等二十多个入口，完整矩阵写在 docs/support-matrix.md。这类项目真正有价值的不是“支持很多名字”，而是它尝试把交接变成协议：handoff 是 typed、owner-scoped、claim-once 的记录，而不是一段随手写在 README 里的备注。
🏗️ 核心特性
- 跨 Agent 的会话捕获和交接
ai-memory 通过 MCP 注册和生命周期 hooks 接入不同 CLI。Agent 开始会话、提交提示词、调用工具、停止、结束会话时，hook 把事件发给本地或远端服务器。会话结束后，系统生成 session summary，并打开一个可被下一个 Agent 认领的 handoff。
Claude Code / Codex / Gemini / OpenCode / Kimi ...
│
│ lifecycle hooks: SessionStart / UserPrompt / ToolUse / Stop / SessionEnd
▼
/hook ingress → sanitizer → writer actor → observations/session/handoff
│
├─ wiki/pages: Markdown source of truth
└─ SQLite: FTS5, entities, links, audit, optional embeddings
- Git-backed Markdown Wiki，而不是只有数据库
源码和文档反复强调一条边界：<data_dir>/wiki/ 是权威数据，SQLite 是派生索引。用户可以 grep、用 Obsidian 打开、手动编辑、git diff，也可以在数据库损坏或索引过期时重建索引。这种设计牺牲了一点“全托管记忆平台”的顺滑感，但换来可审计和可迁移。
<data_dir>/
├── wiki/ # Markdown source of truth, git-versioned
├── raw/ # sanitized managed-workstream JSONL segments
├── db/ # SQLite indexes: FTS5, entities, embeddings, handoffs, audit
├── models/ # local embedding model cache
└── logs/ # tracing logs
- 零 LLM 默认路径
README 和 DATA_HANDLING.md 都写得很直白：默认路径可以不调用任何 LLM。捕获、FTS5 搜索、handoff 都能跑；配置 LLM 后，系统才会做更强的会话整理、语义检索或 rerank。默认本地 embedding 使用 all-MiniLM-L6-v2，外部 embedding、assistant final turn 捕获、LLM rerank 都需要显式打开。
- 混合检索，不把向量搜索当万能答案
架构文档显示，memory_query 走 FTS5、entity-match、graph-neighbor RRF，可选 vector RRF，再做 bounded source-authority adjustment。也就是说，它不是“先 embedding 后召回”的单通道设计。项目给出的 LongMemEval-S 数字也把零 LLM FTS 和 local embeddings 分开列，边界比较清楚。
| 模式 | 指标 | 项目文档给出的结果 | 说明 |
|---|---|---|---|
| zero-llm，pre-2.0 FTS | overall hit@5 | 0.617 | 旧 FTS 基线 |
| zero-llm，stopword-filtered FTS | overall hit@5 | 0.668 | 去停用词后的本地检索 |
| local embeddings，2.0 default | overall hit@5 | 0.823 | FTS5 + entity + graph + 本地向量融合 |
这些是项目自带 eval harness 产出的数字，不是我在当前机器重新跑出的独立 benchmark。它们的好处在于条件写得比较清楚：commit、dataset sha256、硬件、模式在 docs/benchmarks/ 下有记录。
- 多用户、认证和审计不是后补贴片
docs/security.md 里能看到完整的暴露边界：默认 loopback-only 且无认证，非 loopback HTTP 无认证会 fail closed；局域网或远端部署需要 bearer token、allowed hosts，TLS 交给 Caddy、nginx 或 Cloudflare Tunnel 这类成熟反向代理。共享服务器可以启用用户、API key、OIDC device auth；每次 mutation 进 audit log。
- 管理式 workstream
ai-memory run 是项目里很有野心的一层。它不是只安装 hook，而是尝试管理跨 harness 的连续工作流：选择或恢复 workstream，启动指定 Agent，把之前的可见事件范围注入给新进程，进程退出后导入 transcript tail 和 Git checkpoint。这里有很明显的工程复杂度，也最容易出边界问题，所以文档把 lease、claim、递归注入过滤、checkout 匹配都写得很细。
🔬 技术架构深度解析
ai-memory 可以拆成四个平面看，分别是捕获、知识、注入和治理。
capture/storage plane
agent hooks
→ bounded event payload
→ typed sanitizer
→ single SQLite writer
→ observations / sessions / handoffs / audit
→ Markdown wiki commits
knowledge plane
wiki markdown pages
→ FTS5 index
→ entity index
→ wikilink graph
→ optional local/cloud embeddings
→ hybrid retrieval
injection plane
MCP / CLI / managed run
→ scope resolver: workspace + project + actor
→ briefing / query / handoff accept
→ bounded startup packet
→ next Agent session
governance plane
users / bearer / OIDC / API keys
→ attribution
→ audit log
→ purge / backup / restore / reindex
→ pending auto-improve proposals
1. 写入路径：热路径短，重活后移
架构文档里的 steady-state loop 说明，hook 事件先经过短超时发送。服务器入口做 sanitizer 和类型归一化，然后把写入交给 writer actor。会话结束才触发 summary/handoff，LLM consolidation 又是可选项。这个拆法很重要：Agent 每次工具调用都可能触发 hook，如果 hook 写入链路慢，编码体验会被拖垮。
源码约束也比较硬：crates/ai-memory-core 放 domain types，ai-memory-hooks 负责 payload 和 sanitizer，ai-memory-store 负责 SQLite writer actor 和 reader pool，ai-memory-wiki 负责原子 Markdown 写入与 git，ai-memory-mcp 暴露工具面，ai-memory-cli 只做入口和 HTTP 薄客户端。
crates/
├── ai-memory-core domain types, ids, errors
├── ai-memory-hooks hook payload schemas and sanitizer
├── ai-memory-store SQLite writer actor, reader pool, decay math
├── ai-memory-wiki Markdown file writes, watcher, git history
├── ai-memory-mcp MCP transport and tool router
├── ai-memory-llm provider auth and embedder traits
├── ai-memory-consolidate consolidation, lint, sweep, auto-improve
├── ai-memory-workstream managed run and native transcript adapters
├── ai-memory-web read-only web UI
└── ai-memory-cli binary entry and thin commands
本地浅克隆统计显示，仓库不是一个 README 驱动的小壳：712 个跟踪文件，295 个 Rust 文件，约 21.7 万行非测试/非 eval Rust，约 3.6 万行测试、eval、test-support Rust。这个 LOC 粒度只是物理行数，不等于复杂度评分，但能说明它的实现量已经越过“演示项目”的范围。
2. 记忆状态机：从 observation 到 page，再到 handoff
ai-memory 的原始输入不是“记忆条目”，而是 Agent 生命周期事件。每个事件归一到一个封闭集合：session-start、user-prompt、pre-tool-use、post-tool-use、pre-compact、post-compaction、notification、stop、session-end、other。未知事件默认收敛成 other，第三方扩展可以保留 source event，但不能绕过 sanitizer、backpressure 和 writer actor。
会话结束时，系统生成 sessions/<id>.md 页面并创建 handoff。这个 handoff 有 owner、状态和 claim 语义，下一次合适的 Agent 会话可以领取。它解决的不是“搜索以前发生过什么”，而是“我现在该接着哪里做”。这和一般 memory/RAG 工具有差别。
observation stream
├─ prompts
├─ tool calls
├─ compaction notes
└─ stop/session-end
│
▼
rule-based session summary
│
├─ optional LLM consolidation → concepts / decisions / gotchas / procedures
└─ automatic handoff → pending → accepted / expired / cancelled
3. 检索：FTS5、实体、图和向量的 RRF 融合
docs/ARCHITECTURE.md 说明，memory_query 默认先做 FTS5、entity-match 和 link-neighbour RRF；配置 embedder 后，向量 cosine 结果加入同一个 RRF；配置 AI_MEMORY_RERANKER=llm 后，项目/作用域查询会在最终候选上做一次 LLM rerank。rerank 失败、超时、结果非法或并发饱和时保留本地排序。
这套设计有两个好处。第一，零 LLM 模式不是残废路径，FTS5 和实体/图依然能用。第二，向量是增强项，不是唯一入口。对代码项目记忆来说，这点很实用：很多查询是“上次那个 migration 名字是什么”“某个模块为什么不能删”，关键词、文件路径、实体和链接经常比 embedding 更可靠。
4. 安全边界：权限、隐私、网络暴露分开讲
这类 Agent 基建最容易把“权限回调”说成“安全沙箱”。ai-memory 的文档没有这么写。它明确区分了几件事：默认 loopback-only；非 loopback 无认证会拒绝启动或访问；Bearer/OIDC/API key 负责应用层身份；TLS 由反向代理负责；本地静态数据没有内建加密，依赖 OS 文件权限；cloud embedding、assistant capture、LLM rerank 都是外发数据路径，需要显式开启。
local-only default
├─ server binds 127.0.0.1:49374
├─ no telemetry
├─ wiki + SQLite live under operator-controlled data dir
└─ local embeddings can run without API key
external-data opt-ins
├─ cloud embedding provider: page text leaves host
├─ assistant final-turn capture: double opt-in
└─ LLM reranker: query + bounded snippets leave host
这里还有一个现实限制：没有每页 RBAC。多用户共享服务器能做身份、归属和审计，但它不是一个强隔离的多租户知识库。把它放进生产团队前，仍然要看网络边界、token 管理、备份、机器权限和日志保留。
5. 版本面：Release、源码、包版本要分开看
同日核验时，GitHub Releases 显示最新稳定版为 v2.4.0，发布时间 2026-09-21；main 分支浅克隆的 workspace package version 是 2.3.2，HEAD 为 5157c6b。这个差异不一定是问题，可能是发布自动化、分支同步或标签内容的时间差，但写报告时不能把它折成一个“当前版本”。
| 版本面 | 观测值 | 来源 |
|---|---|---|
| 最新 GitHub Release | v2.4.0 | GitHub 元数据 |
| main 分支 Cargo workspace | 2.3.2 | Cargo.toml |
| Rust 工具链 | rustc 1.95.0 | rust-toolchain.toml 与本地 rustc --version |
| 默认分支 HEAD | 5157c6b | 本地浅克隆 |
| Docker 镜像 | akitaonrails/ai-memory:latest | README 快速上手 |
📖 README 核心内容摘要
README 的主线很清楚：ai-memory 是给 AI coding agents 用的长期记忆。它想让你在 Claude Code 做到一半时退出，切到 Codex，仍然能拿到之前的架构背景、失败方案和未解决问题。这个目标听起来像“上下文同步”，但实现方式更偏知识库编译。
README 里列出的核心承诺包括：
- 支持二十多个 harness 或 MCP 客户端，包括 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Grok、Devin、Kimi、Kiro 等。
- 记忆存在你运行的服务器里，可以是本机、homelab 或团队共享机器。
- Markdown Wiki 是事实源，SQLite 是可重建索引。
- hooks 自动捕获工作过程，默认不需要 LLM API key。
- 支持多用户归属、审计日志、purge、backup、restore、reindex 等运维动作。
README 的快速路径分两类：AUR/native 和 Docker。Docker 方案会先安装一个 host wrapper，再启动容器服务，最后用 install-mcp 和 install-hooks 接入 Agent。CLI 参数来自 README 与 crates/ai-memory-cli/src/cli.rs 的 Clap 定义核对，install-mcp --client、install-hooks --agent、--apply、--server-url、--auth-token、run --no-autowire 都是当前源码里存在的参数。
常见使用方式也很接地气：
# 查看状态
ai-memory status
# 搜索 Wiki 记忆
ai-memory search "database migration rollback"
# 读取某个页面，或者按查询取最相关页面
ai-memory read-page --path decisions/0001.md
ai-memory read-page "why did we change auth middleware"
# 手动结束没有 SessionEnd hook 的 agent 会话
ai-memory finalize-session --agent codex
MCP 工具面比 CLI 更适合 Agent 自己调用。架构文档列出 23 个 MCP tools，其中读工具包括 memory_query、memory_recent、memory_read_page、memory_briefing、memory_explore；写工具包括 memory_write_page、memory_delete_page、memory_feedback、memory_auto_improve、memory_forget_sweep；交接工具包括 memory_handoff_begin、memory_handoff_list、memory_handoff_accept、memory_handoff_cancel；跨项目消息还有 memory_message_send/list/pop/cancel。
🚀 快速上手
下面是单机 Docker 路线。它适合先验证 capture 和 handoff，不适合一上来暴露到公网。
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")"
actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
[ -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
启动本机服务：
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
接入 Claude Code：
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
也可以走 managed workstream：
ai-memory run claude
ai-memory run codex --yolo
ai-memory continue
如果要放到局域网共享，先生成 token，再改为非 loopback bind。这个例子来自安全文档里的参数形态，真实部署还应该加 TLS 反向代理和 host allowlist。
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="<server-ip>,localhost,127.0.0.1" \
akitaonrails/ai-memory:latest
ai-memory install-mcp --client claude-code --apply \
--server-url "http://<server-ip>:49374/mcp" --auth-token "$TOKEN"
ai-memory install-hooks --agent claude-code --apply \
--server-url "http://<server-ip>:49374" --auth-token "$TOKEN"
📊 增长速度与社区热度数据
ai-memory 的仓库创建于 2026-05-21。按快照 Stars 7,893 粗算，创建到 2026-09-22 约 124 天，生命周期平均约 63.7 Stars/天。这个数只能当长期基线，不能等同于当天增量；Trending 快照没有保留 daily stars。
| 指标 | 数值 | 说明 |
|---|---|---|
| Trending 排名 | #4 | 2026-09-22 快照顺序 |
| Stars | 7,893 | 同日 GitHub 元数据 |
| Forks | 530 | 同日 GitHub 元数据 |
| Fork/Star | 6.7% | Forks / Stars |
| Open issues count | 27 | GitHub API 字段，包含 Issues 与 PR 的合并计数 |
| 最新 Release | v2.4.0 | 2026-09-21 发布 |
| 本地源码文件 | 712 | git ls-files -z 写盘后解析，避免 stdout 截断 |
| Rust LOC | 252,714 | 物理行数，包含测试和 eval |
| Test-like 文件 | 105 | 路径或文件名含 test/tests/eval/support 的近似分类 |
完整 Trending 榜单如下。Stars、Forks、语言是同日 API 补充核验；“今日新增”字段在快照中没有保留。
| Rank | Repository | Language | Stars | Forks | 今日新增 |
|---|---|---|---|---|---|
| 1 | BuilderIO/agent-native | TypeScript | 6,182 | 558 | 未保留 |
| 2 | trycua/cua | HTML | 25,850 | 1,778 | 未保留 |
| 3 | Open-Dev-Society/OpenStock | TypeScript | 18,092 | 2,225 | 未保留 |
| 4 | akitaonrails/ai-memory | Rust | 7,893 | 530 | 未保留 |
| 5 | coder/coder | Go | 16,536 | 1,572 | 未保留 |
| 6 | anthropics/financial-services | Python | 35,969 | 5,278 | 未保留 |
| 7 | cloudflare/quiche | Rust | 12,441 | 1,139 | 未保留 |
| 8 | mvt-project/mvt | Python | 13,729 | 1,335 | 未保留 |
| 9 | zhouxiaoka/autoclip | Python | 8,532 | 1,589 | 未保留 |
| 10 | ruanyf/weekly | - | 104,286 | 4,460 | 未保留 |
| 11 | Crosstalk-Solutions/project-nomad | TypeScript | 38,023 | 3,776 | 未保留 |
| 12 | yynxxxxx/Codex-X | Rust | 3,800 | 468 | 未保留 |
社区活跃度上，ai-memory 的 release 节奏很密：v2.4.0、v2.3.2、v2.3.1 都集中在 2026-09 月下旬。浅克隆 HEAD 显示 2026-09-21 仍在合并修复类 PR。由于未使用认证 API 时触发 rate limit，Issues/PR 拆分和完整贡献者总数没有在这里展开；上表只使用已核验字段，避免把 GitHub 的 open_issues_count 误写成纯 Issues 数。
🎯 适用场景
| 场景 | 适合程度 | 原因 |
|---|---|---|
| 个人同时使用 Claude Code、Codex、Gemini CLI | 高 | 共享一个项目级 Wiki 和 handoff，减少重复交代上下文 |
| 团队内部共享 Agent 项目记忆 | 高 | 支持多用户归属、API key、审计日志和局域网部署 |
| 对外部 LLM API 敏感的代码库 | 中高 | 默认零 LLM，可用本地检索；但仍要管好本机数据目录和日志 |
| 想把会话沉淀成可读知识库 | 高 | Markdown Wiki 是事实源，适合人工审阅和 Git diff |
| 只想要简单向量搜索 | 中 | 它能做检索，但完整系统包含 hook、handoff、server、MCP、运维动作，可能偏重 |
| 强多租户 SaaS 记忆平台 | 低 | 文档明确没有每页 RBAC，本质是自托管单租户/团队工具 |
| 生产级远程共享服务 | 中 | 有认证、审计和部署文档，但还需要 TLS、备份、权限、监控等运维配套 |
💡 总结
aio-memory 最有意思的地方，是它没有把“Agent 记忆”简化成 embeddings。它把工作流里的事实源放回文件系统：Markdown 页面、Git 历史、SQLite 派生索引、MCP 工具、hook 捕获和 handoff 协议。这套东西并不轻，但方向是对的。随着 Agent CLI 变成开发者日常工具，真正麻烦的不是“模型能不能回答”，而是“上一轮工作怎么可靠地交给下一轮”。
我会把它看成团队 Agent 基建的早期候选，而不是一个装上就完事的插件。个人使用可以从 loopback Docker 开始；团队试点要先决定三件事：数据目录放哪、谁能访问、哪些内容允许发给外部 provider。只要这几件事讲清楚，ai-memory 的文件优先架构会比黑盒记忆服务更容易被工程团队接受。
