ai-memory SQLite迁移史：50+个版本Schema演进全梳理（终极指南）

ai-memory SQLite迁移史：50+个版本Schema演进全梳理（终极指南）

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory

ai-memory 是一款为 AI 编码 CLI 提供长期记忆的开源项目，它的核心存储是一张 SQLite 数据库，而这张库的 Schema 至今已经演进到V63——从最初的 4 张表，成长为一个覆盖多 Agent、多用户、向量检索、实体时间线与自动改进闭环的完整记忆系统。本文按阶段带你快速读完这段 ai-memory SQLite 迁移史，看懂每个版本背后的设计动机。

如果你正在评估 agent 记忆方案，或者对「一个生产级 SQLite 库如何平滑迭代 60 次不翻车」感兴趣，这篇文章会是一份省时间的路线图。

第一阶段（V01–V08）：奠基——记忆的核心四元组

整个数据模型的基石在 V01__init.sql 中一次成型：

V01 里有个刻意的决定：身份主键是(workspace_id, project_id, path)三元组，并配了 FTS5 全文索引。紧随其后的几个版本各有所指：

• V02__handoffs.sql：新增handoffs表——这是 ai-memory 的招牌能力「跨 Agent 接力」。一个 Agent 会话结束时留下类型化的上下文快照（摘要、未决问题、下一步），下一个 Agent CLI 启动时认领，实现 vendor 之间的无缝交接。
• V03__decay.sql：引入遗忘机制，在pages上加访问计数与软删除时间戳，为「记忆衰减」提供数据。
• V04__embeddings.sql：page_embeddings表落地向量检索，向量直接打包为 BLOB 存库，零外部依赖。
• V05–V08：纯性能工程——级联删除索引、Wiki 层迁移记录表（V06__wiki_migrations.sql）、观察事件 FTS（V07__observations_fts_and_link_index.sql）和 FTS 触发器收窄。

第二阶段（V09–V13）：从 4 种 Agent 到「全家桶」

早期sessions.agent_kind只允许 4 个值，随着支持的 CLI 越来越多，V09 用整表重建的方式扩开了 CHECK 约束（SQLite 无法原地改约束，这是本项目反复使用的标准手法）。

这一阶段还有两个值得新手学习的迁移：

• V12__fts_remove_diacritics.sql：换掉 FTS 分词器（remove_diacritics 2），让descricao也能命中descrição。因为分词器在 CREATE 时固定，只能删表重建索引——而 FTS 表是 contentless 的，源数据一行不动。
• V13__cross_project_links.sql：链接支持[[project:path]]跨项目引用，把各自为政的 Wiki 连成一张图。

第三阶段（V14–V20）：多用户归属与数据自愈

这一阶段的主题是**「谁写了这条记忆」**：

• V14__users.sql：新增users表。注意注释里明确写着数据模型仍是单租户——没有 RBAC，只做归属（attribution）。
• V15 / V16：pages.author_id与audit_log.author_id，审计日志记录「操作发生时」的作者，而非页面当前作者，保住时间点真相。
• V17：把页面路径本身索引进 FTS，搜 slug 也能命中。
• V18__enforce_project_workspace_pairing.sql：用 BEFORE INSERT 触发器堵住「workspace 与 project 错配」的脑裂写入，让陈旧写入直接失败而非静默污染。
• V19 / V27：两次数据修复迁移，把历史上被错误归入「碎片项目」的观察事件重新归位——Schema 演进中「修数据」和「加列」同样重要。
• V20：为 Grok CLI 扩展 Agent 枚举，从此每接入一个新 Agent 就是一个版本（V25 Pi、V26 Zero、V28 Devin、V30 Kimi Code、V32 Crush、V44 Hermes、V45 Kiro CLI、V47 Command Code、V50 Pool、V51 ZCode……），这个「一个 Agent 一个版本」的模式贯穿始终，非常稳定且可回查。

第四阶段（V21–V34）：自动改进闭环与幂等摄取

这是记忆系统从「存」走向「自我进化」的段落：

• V21–V24：auto_improve四连发——待审提案表、后台调度器、补丁式提案（只改一小段而非整页）、以及被拒提案的持久化缓冲区，让系统记住「用户否决过什么」，避免反复推荐。
• V29__maintenance_scheduler.sql：全局维护作业节奏表。
• V31__managed_workstreams.sql：ai-memory run托管工作流登场，让多个 Agent 协作跑长任务。
• V33__ingest_keys.sql：Hook 事件幂等键——重复投递的事件不会重复写入，崩溃重放可安全续跑。
• V34__session_consolidation_jobs.sql：会话结束后的 LLM 整合任务做成持久化工作队列，异步消费、失败重试。

第五阶段（V35–V43）：精细化——水位、TTL、反馈与所有权

• V35：用「观察数量水位」替代墙钟比较，防止时钟漂移导致会话被反复重结。
• V36__page_expiry.sql：页面级 TTL，过期即隐藏并清删。
• V37：检索质量显式反馈，salience取代单一访问计数。
• V38__entities.sql：实体索引成为与 FTS、向量、链接邻居并列的第四条检索流。
• V39–V43：交接棒加 owner、会话加 owner、按操作者统计页面热度——共享服务器上的多人隔离逐层补齐。

第六阶段（V44–V63）：2.0 时代——认证、时间线与证据

• V54__human_auth.sql / V55__api_credentials.sql：人类登录（密码/角色）与原生 API 凭据分离，旧 token 平滑迁移。
• V56–V58 / V62：「双时间线」系列——实体链接与页面版本各自携带valid_from / valid_to摄取窗口，支持as_of查询「某个时点的记忆长什么样」，并回补修复了退役页面时间线窗口未关闭的缺陷。
• V57：跨会话「经验蒸馏」pass 的调度状态落库。
• V52 / V59：purge 墓碑表——删库删目录后，客户端积压事件重放也不会「复活」已清除的数据。
• V60：bootstrap 分块进度持久化，崩溃续跑不重复烧 LLM 调用。
• V61__page_abstract_embeddings.sql：摘要行独立嵌入，成为第五路 RRF 检索流。
• V63__page_evidence.sql：证据底表，记录「哪些独立来源支撑了这个版本」，为置信度信号铺路——这也是最新的一个版本。

一张图看懂：63 个版本全景

给新手的 4 个工程启示

1. 只追加，不破坏：V07、V53、V63 等大量迁移是纯增量列/表，旧数据零改写，升级永远向前兼容。
2. 整表重建是 SQLite 的正规武器：改约束、改主键（V09、V13、V20……）都走「建新表 → 拷数据 → 换名」的固定剧本，且每次都在注释里提醒「保留全部现有索引与触发器」。
3. 迁移即文档：每个 SQL 文件头部都用大段注释解释「为什么」，migrations 目录本身就是一份可读的架构演进史。
4. 防呆设计：migrations.rs 会把「数据库比二进制更新」的情况翻译成可读的DataSchemaAhead错误，而不是抛底层库的晦涩报错。

更多背景可参考项目文档：ARCHITECTURE.md、MIGRATION-2.0.md、temporal.md 与 design-decisions.md。

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory