AI摘要

ai-memory是一个为AI编程助手如Codex、Claude Code等提供跨会话、跨助手、长期记忆的本地记忆基础设施。它采用Git、Markdown Wiki、SQLite和MCP等技术，强调Markdown Wiki作为真实知识源，SQLite作为检索索引。ai-memory支持多种AI助手，通过MCP和Hooks实现自动记忆功能，并具备记忆固化、工作交接单、Managed Workstream等功能。它不依赖向量数据库，而是采用混合检索方式，同时支持自动整理记忆和遗忘机制。尽管存在一些局限性，如偏重编码助手、企业权限体系不完整等，ai-memory在架构思想、跨助手能力和本地部署等方面表现出色，特别适合Codex等AI编程助手使用。

我看完了 akitaonrails/ai-memory 当前 README、架构文档以及针对 Codex 的实现说明。这个项目很值得关注，而且它的思路和很多“Agent Memory = 向量数据库”的项目明显不同。

一句话概括：

ai-memory 是一个专门给 Codex、Claude Code、Cursor、Gemini CLI 等 AI 编程 Agent 提供“跨会话、跨 Agent、长期记忆”的本地记忆基础设施。

它更像：

Git + Markdown Wiki + SQLite + MCP + Agent Hooks + LLM 整理器

而不是传统的：

Embedding + Vector DB + RAG。

截至 2026 年 8 月 25 日，仓库约 4,389 Stars、320 Forks，主要使用 Rust，MIT License；仓库创建于 2026 年 5 月，仍在非常高频地更新。当前主分支已经发布到 v1.32.0（2026-08-24）。

1. 它到底解决什么问题？

假设你今天用 Codex 开发一个 CRM：

09:00
Codex
↓
分析架构
↓
修改数据库
↓
尝试方案 A
↓
发现方案 A 有问题
↓
改用方案 B
↓
完成 70%

然后关闭 Codex。

第二天重新打开：

新的 Codex Session

Codex：
“你好，需要我帮你做什么？”

之前的大量信息：

为什么这样设计
哪些方案已经失败
数据库改了什么
当前做到哪里
有哪些 TODO
哪些坑不能再踩
为什么没有使用方案 A

都很容易丢掉。

更麻烦的是：

Claude Code
    ↓
开发一半

换成 Codex
    ↓

Codex 完全不知道
Claude Code 干了什么

而 ai-memory 要解决的就是：

Claude Code
      ↓
   ai-memory
      ↓
     Codex
      ↓
   ai-memory
      ↓
    Cursor
      ↓
   ai-memory

Agent 可以换，但项目记忆不换。

官方 README 甚至直接把典型场景描述为：退出 Claude Code，在同一个目录启动 OpenAI Codex，继续工作而无需重新解释架构、失败尝试或未解决问题。

2. ai-memory 最重要的设计思想

我认为这个项目最有价值的地方并不是代码，而是它的 Memory Architecture。

它没有把长期记忆直接设计成一个向量库。

而是：

                 AI Agent
                    │
        ┌───────────┼────────────┐
        │           │            │
     Codex     Claude Code     Cursor
        │           │            │
        └───────────┼────────────┘
                    │
                 Hooks
                    │
                    ▼
             ┌─────────────┐
             │  ai-memory  │
             └──────┬──────┘
                    │
          Capture / Sanitize
                    │
                    ▼
              Observations
                    │
             Session End
                    │
                    ▼
              Session Summary
                    │
              LLM Consolidate
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
     Markdown Wiki        SQLite Index
     真正知识源             检索索引
          │                   │
          └─────────┬─────────┘
                    │
                MCP Tools
                    │
                    ▼
            下一个 AI Agent

官方架构明确规定：

Markdown Wiki 是 Source of Truth，SQLite 只是派生索引。

Markdown 通过 Git 进行版本管理；SQLite 负责 FTS5、实体、链接邻居、Session、Observation、Handoff、Embedding 等检索和运行状态。

这点我很赞同。

3. 为什么不用传统向量数据库？

这是这个项目一个很重要的理念。

很多 Memory 系统是：

Conversation
      ↓
Embedding
      ↓
Vector Database
      ↓
Similarity Search

ai-memory 则认为：

长期记忆应该首先是可读、可编辑、可版本管理的人类知识资产。

所以它使用：

wiki/

├── concepts/
│   ├── authentication.md
│   └── billing-engine.md
│
├── decisions/
│   ├── use-postgresql.md
│   └── use-flowable.md
│
├── gotchas/
│   ├── postgres-deadlock.md
│   └── codex-windows-path.md
│
├── procedures/
│   └── deploy-production.md
│
├── sessions/
│   ├── 20260824-001.md
│   └── 20260825-001.md
│
└── _rules/
    └── coding-rules.md

这些本质上都是：

Markdown

所以你可以：

Obsidian
VS Code
vim
grep
Git
rsync

直接读取和管理。

README 明确强调 Wiki 是普通 Markdown，可以 grep、Obsidian 打开、rsync 备份，并且不要求必须维护一个向量数据库。

这是 ai-memory 与很多 Agent Memory 项目最大的差异之一。

4. 但它并不是放弃向量检索

这一点也很聪明。

它只是说：

Vector Search 不应该成为唯一记忆系统。

默认检索大致是：

                 Query
                   │
       ┌───────────┼──────────────┐
       │           │              │
      FTS5       Entity         Links
    全文检索      实体检索       图关系
       │           │              │
       └───────────┼──────────────┘
                   │
                  RRF
                   │
           Optional Vector
                   │
             Optional LLM
               Reranker
                   │
                   ▼
               Results

架构文档显示 memory_query 会综合：

SQLite FTS5
Entity Match
Link Neighbor
可选 Vector Cosine
RRF 融合
Authority Weight
可选 LLM Reranker

一起完成召回。

所以严格来说它属于：

Hybrid Retrieval

而不是单纯 Vector RAG。

5. Memory 不是简单“聊天记录”

这个设计也非常重要。

如果只是保存：

user: 修改登录页面

assistant: 好的

assistant: 修改完成

长期下来价值很低。

ai-memory 会把 Session 整理成更持久的知识。

例如：

Session

讨论 PostgreSQL
修改 BillingService
出现 deadlock
尝试方案 A
失败
最终采用 SELECT FOR UPDATE

之后 LLM Consolidation 可以整理为：

decisions/
    billing-lock-strategy.md

gotchas/
    postgres-billing-deadlock.md

concepts/
    billing-transaction-model.md

也就是说：

原始事件
   ↓
Session
   ↓
Summary
   ↓
Knowledge

它是在做：

Memory Consolidation —— 记忆固化。

官方架构中，LLM consolidation 可以将 Session 内容进一步整理进 concepts/、decisions/、gotchas/ 等长期 Wiki 页面。

6. Handoff 是这个项目特别实用的功能

Handoff 可以理解为：

Agent 工作交接单。

例如 Claude Code 工作到一半：

Claude Code
    │
    ▼
Session End
    │
    ▼
ai-memory

生成：

Current state:
BillingService 已重构完成 70%

Completed:
✓ 数据表
✓ Repository
✓ API

Remaining:
□ Flowable 接入
□ Integration Tests

Important:
不要重新采用 Redis distributed lock，
已验证存在 race condition。

第二天：

Codex
  ↓
SessionStart
  ↓
ai-memory
  ↓
Handoff

Codex 一开始就知道：

昨天做到哪里了。

这比普通 RAG 实用得多。

7. 对 Codex 的支持已经比较深入

这个项目现在明确把 Codex 标记为 Supported。

Codex 可以：

Codex
  │
  ├── MCP
  │
  ├── Lifecycle Hooks
  │
  ├── Memory Query
  │
  ├── Handoff
  │
  └── Managed Workstream

README 还特别说明了 Codex 的一个限制：

Codex 当前没有可靠的“真正 Session End Hook”。

因此当你希望正式结束一个工作 Session 时，可以执行：

ai-memory finalize-session

来触发完整的：

Session End
     ↓
Summary
     ↓
Handoff
     ↓
Consolidation

流程。

另外还有一个我认为更有意思的模式：

ai-memory run codex

它属于 Managed Workstream。

8. Managed Workstream 是它最值得关注的功能之一

普通模式：

Claude Session A

Codex Session B

Cursor Session C

三个 Agent 有各自的 Session。

Managed Workstream 则试图建立：

          Logical Workstream
                 │
        "CRM Billing Refactor"
                 │
     ┌───────────┼───────────┐
     │           │           │
 Claude Code    Codex      OpenCode
 Session A     Session B    Session C
     │           │           │
     └───────────┼───────────┘
                 │
              ai-memory

换句话说：

Session 属于 Agent，但 Workstream 属于项目。

例如：

ai-memory run claude

做一阵子。

然后：

ai-memory run codex --yolo

Codex 可以接着同一个逻辑 Workstream。

再换：

ai-memory run command-code

继续。

README 当前支持多种 Managed Workstream，包括 Codex、Claude Code、OpenCode、Pi、Kimi Code、Command Code、Kiro 等。

这个思想比简单“共享一个向量库”高级不少。

9. MCP 在这里扮演什么角色？

可以把 MCP 理解为：

AI Agent
   │
   │ MCP
   ▼
ai-memory

Agent 可以主动执行类似：

memory_query()
memory_recent()
memory_write_page()
memory_handoff_begin()
memory_handoff_accept()
memory_consolidate()
memory_auto_improve()

例如：

Codex：

memory_query(
    "为什么 billing service 没有使用 Redis lock?"
)

ai-memory：

找到：

decisions/billing-lock.md
gotchas/redis-race-condition.md
sessions/20260818.md

于是 Codex 就不会重新犯同样的问题。

MCP-only 与 MCP+Hooks 是两种不同模式：前者可以查询、写入、处理 Handoff 和 Consolidation；后者还可以自动捕获 Session 生命周期事件。

10. Hooks 才是“自动记忆”的关键

如果只使用 MCP：

Agent
 ↓
主动调用 memory_write

就有一个老问题：

Agent 可能忘记写。

所以 ai-memory 引入 Hooks：

SessionStart

UserPromptSubmit

PreToolUse

PostToolUse

PreCompact

PostCompaction

Stop

SessionEnd

自动记录：

Agent 干了什么
      ↓
Observation
      ↓
Session
      ↓
Summary
      ↓
Long-term Memory

官方架构对 Observation 类型做了严格归一化，包括 session-start、user-prompt、pre-tool-use、post-tool-use、pre-compact、post-compaction、stop 和 session-end 等。

因此它不是：

“Agent 自己想起来才记。”

而是：

基础设施自动观察 Agent。

这条路线更适合工程系统。

11. 还有“遗忘机制”

真正的 Memory 系统还必须解决另一个问题：

记忆越来越多怎么办？

ai-memory 已经加入：

TTL
Retention
Decay
Access Count
Salience
Pin
Supersede
Canonical
Historical

大概可以理解成：

经常访问
     ↓
强化

重要 Decision
     ↓
长期保存

旧 Session
     ↓
逐渐衰减

已经过期的信息
     ↓
Superseded

长期没价值
     ↓
Forget

它甚至会执行 Forget Sweep，根据 TTL、retention、cold threshold 等清理知识，同时维护 tombstone 和版本关系。

这个方向已经接近真正意义上的：

Memory Lifecycle Management

而不是“无限往向量库里面塞数据”。

12. AI 还能自己整理 Memory

现在还有一个比较激进的功能：

Auto Improvement

流程大概是：

Session
   ↓
Review
   ↓
LLM
   ↓
发现值得沉淀的知识
   ↓
Proposal
   ↓
Validation
   ↓
Wiki

自动形成：

concepts/

decisions/

gotchas/

procedures/

_rules/

甚至可以设置：

require_approval = true

让 AI 先生成候选知识：

AI Proposal
     ↓
Human Review
     ↓
Approve
     ↓
Memory

这对企业使用来说反而是我更推荐的模式。

官方架构明确把自动改进拆成“生成/验证 Proposal”和“批准写入”两个环节，也支持额外执行 Eval Gate。

13. 它支持哪些 Agent？

支持面现在已经相当广。

主要包括：

Agent	MCP	Hooks	Handoff
Claude Code	✅	✅	✅
OpenAI Codex	✅	✅	✅
Cursor	✅	✅	✅
Gemini CLI	✅	✅	✅
OpenCode	✅	✅	✅
Devin CLI	✅	✅	✅
Kimi Code	✅	✅	✅
Kiro CLI	✅	✅	✅
Command Code	✅	✅	✅
Pi / OMP	✅	✅	✅
VS Code Copilot	✅	❌	手工
Claude Desktop	✅	❌	手工
Zed	✅	❌	手工

不同 Agent 的生命周期 API 不一致，所以支持程度有所区别。README 有非常详细的 Support Matrix。

14. 为什么我认为它特别适合 Codex？

如果给 Codex 加这个东西：

以前：

Codex
 │
 ├─ 当前代码
 ├─ AGENTS.md
 ├─ 当前 Prompt
 └─ 当前 Context

现在可以变成：

                 Codex
                   │
      ┌────────────┼────────────┐
      │            │            │
   Current       Skills       MCP
    Code                        │
                                ▼
                           ai-memory
                                │
                ┌───────────────┼──────────────┐
                │               │              │
             Decisions       Gotchas       Procedures
                │               │              │
             Concepts         History        Handoff

于是 Codex 不仅知道：

现在代码是什么样。

还可以知道：

为什么代码变成这样。

这是非常大的区别。

15. ai-memory 与普通企业知识库又不一样

这个区别必须明确。

传统企业 RAG：

PDF
Word
制度
合同
知识库
   ↓
Chunk
   ↓
Embedding
   ↓
Vector DB

解决的是：

Knowledge Context

而 ai-memory 主要解决：

Agent 做过什么
为什么这样做
失败过什么
当前做到哪里
以前决定过什么
下一步该做什么

即：

Agent Working Memory + Historical Context + Decision Context

所以它不是拿来替代企业知识库的。

更合理的架构是：

              Enterprise Agent
                     │
        ┌────────────┼────────────┐
        │            │            │
 Knowledge       Business      Agent
 Context          Context      Memory
        │            │            │
   RAG/Vector     SQL/API      ai-memory
        │            │            │
        └────────────┼────────────┘
                     │
                  Codex

16. 我认为它现在最大的几个优点

① Markdown 做 Source of Truth

非常正确。

不会把企业宝贵的 Memory 锁死在某个 Vector DB 里面。

② Git Versioning

Decision 被修改以后：

旧版本
 ↓
Git
 ↓
新版本

可以审计。

③ 不依赖 Vector DB

部署复杂度明显降低：

Rust Binary
+
SQLite
+
Git
+
Markdown

就可以跑起来。

④ Hybrid Search

不是简单 Embedding Search：

FTS
+
Entity
+
Graph
+
Vector
+
RRF
+
Reranker

这条路线在工程知识检索上更合理。

⑤ Cross-Agent

我认为这是它最有商业价值的地方。

今天：

Codex

明天可能：

Claude Code

以后：

GPT-6 Coding Agent

Memory 仍然属于：

企业 / 项目

而不是属于：

某个模型厂商。

17. 但它现在也有明显局限

这一点不能忽略。

第一，它目前明显偏 Coding Agent

它的核心设计场景仍然是：

repository
checkout
coding CLI
session
tool use
git

所以它不是通用的：

Enterprise Agent Memory Platform

至少目前还不是。

第二，企业权限体系还不够完整

它有：

workspace
project
per-user slot
capture exclusion
auth

但 README 自己就特别说明 per_user Memory Slot 属于上下文注入隔离，而不是 RBAC；精确 Wiki 读取和搜索仍然属于 project-wide。

大型企业最终还需要：

Tenant
Organization
Department
User
Agent
Role
ACL
Classification
Row Security
Audit

这一整套体系。

第三，Hooks 并不等于完整 Transcript

官方也明确说明：

lifecycle Hook Observation 并不是完整的原生 Agent Transcript。

所以如果需要真正完整的 Agent 审计日志，还需要额外设计。

第四，自动学习要慎用

如果：

Agent 错误判断
      ↓
Auto Improve
      ↓
写入 Memory
      ↓
以后 Agent 都相信它

就可能产生：

Memory Poisoning / Knowledge Drift

企业环境最好采用：

AI Proposal
      ↓
Validation
      ↓
Human Approval
      ↓
Canonical Memory

而不是完全放开自动写。

18. 如果给这个项目定位，我会这样分层

┌───────────────────────────────┐
│        AI Coding Agent         │
│ Codex / Claude / Cursor / Kimi │
└───────────────┬───────────────┘
                │
               MCP
                │
┌───────────────▼───────────────┐
│          ai-memory             │
│                               │
│ Session Memory                │
│ Decision Memory               │
│ Handoff                       │
│ Gotchas                       │
│ Procedures                    │
│ Historical Context            │
└───────────────┬───────────────┘
                │
       ┌────────┴────────┐
       │                 │
┌──────▼──────┐   ┌──────▼──────┐
│ Markdown/Git│   │ SQLite Index │
│ Source Truth│   │ Search/State │
└─────────────┘   └─────────────┘

所以它真正的定位，我认为应该叫：

Agent Engineering Memory Infrastructure

而不是：

Vector Database

也不是：

RAG Knowledge Base。

19. 我的评价

如果从架构价值来评分：

项目	评价
架构思想	★★★★★
Codex 适配	★★★★★
跨 Agent 能力	★★★★★
本地部署	★★★★★
可审计性	★★★★★
企业 RBAC	★★★
通用企业 Memory	★★★
Coding Agent Memory	★★★★★
当前成熟度	★★★★

综合我会给 8.8/10。

而且我认为它的价值不只是“拿来用”。

更值得研究的是它提出的几个底层思想：

Memory ≠ Vector DB
Memory ≠ Chat History
Memory = Observations → Sessions → Knowledge → Decisions → Handoff
Memory 应该属于用户/企业，而不是属于某一个 Agent 厂商。

这几个判断，我认为方向是对的。

尤其对你一直在考虑的 Codex + 企业知识沉淀 + 多 Agent 协同 场景，ai-memory 非常值得作为一个基础组件研究；但我不会直接拿它承担整个 Enterprise Context，而会把它定位成 “Agent 历史上下文 / 工程经验记忆层”，再与企业 RAG、业务数据库、权限系统、流程引擎组合起来。