每天一个开源项目#107 ai-memory：7.9K Stars 的跨 Agent 记忆层

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 里的备注。

🏗️ 核心特性

1. 跨 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

2. 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

3. 零 LLM 默认路径

README 和 DATA_HANDLING.md 都写得很直白：默认路径可以不调用任何 LLM。捕获、FTS5 搜索、handoff 都能跑；配置 LLM 后，系统才会做更强的会话整理、语义检索或 rerank。默认本地 embedding 使用 all-MiniLM-L6-v2，外部 embedding、assistant final turn 捕获、LLM rerank 都需要显式打开。

4. 混合检索，不把向量搜索当万能答案

架构文档显示，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/ 下有记录。

5. 多用户、认证和审计不是后补贴片

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。

6. 管理式 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 的文件优先架构会比黑盒记忆服务更容易被工程团队接受。