ai-memory 的至少一次语义与崩溃恢复重放收敛机制完整指南【免费下载链接】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-memoryai-memory 是一个为 AI 编码 AgentClaude Code、Codex、Gemini CLI 等提供长期记忆共享的 Rust 系统。它最容易被新手忽略、却最保证可靠性的设计是至少一次at-least-once语义与崩溃恢复当事件在服务端处理中途丢失响应、进程崩溃时系统依靠重放收敛机制保证记忆宁可重复、绝不丢失并最终收敛到一致状态。本文用零代码的方式带你完整看懂这套机制。一、为什么至少一次是记忆系统的必选项 记忆写入发生在 Agent 与 CLI 之间的生命周期钩子会话开始、工具调用、会话结束等中。这条链路上有两类典型故障事件丢了钩子脚本发出事件后服务端已处理但响应丢失客户端以为失败处理断了服务端在写库完成之后、生成会话页面/交接单之前进程崩溃。如果追求恰好一次系统必须处理海量分布式锁与补偿逻辑ai-memory 选择了工程上更稳的方案至少一次 幂等去重 重放收敛。也就是说——同一事件可以重试、可以重复到达系统保证每条记忆至少被完整处理一次不丢重复到达的事件不会产生重复观察记录不重崩溃后重放时未完成的部分会被补做已完成的部分被跳过收敛。ai-memory Web 端项目记忆页面视图二、事件旅程本地 Spool 与幂等密钥 崩溃恢复的第一块拼图在客户端。原生ai-memory hook --event ...命令不会傻等服务端而是把事件先写入本地spool暂存队列由独立的hook-drain后台进程负责投递每个 spool 条目携带一个稳定的幂等密钥idempotency key跨所有重试保持不变会话结束类事件stop、pre-compact、session-end会启动脱离式 drain 助手投递不依赖某一个关闭钩子存活4xx 是永久性拒绝、不重试5xx 与网络不可达则入队重试。关键承诺即使服务端处理成功但批次响应丢失客户端重放不会造成重复观察也不会重复会话已结束的下游效果。 细节见 docs/install.md。三、服务端去重ingest_keys 表的三种结局 ️服务端用一张项目级去重表ingest_keys接收密钥表定义在 V33__ingest_keys.sql 中只有两个核心状态位seen_at见到与completed_at完成。一次带密钥的写库操作insert_observation_keyed在同一 SQLite 事务中认领密钥 插入观察记录只有三种结局结局含义服务端行为Inserted密钥首次出现正常记录观察继续处理AlreadyComplete密钥已标记完成整个事件确认并跳过不产生任何副作用ResumePending密钥见过但未完成不重复插观察只补做下游效果wiki 提交、交接单等密钥认领与观察写入原子绑定在同一个事务里崩溃不可能出现密钥被认领但记忆没落库的中间态。密钥本身也有 30 天 TTL到期后借机清理防止无限膨胀。四、崩溃恢复收敛路径从重复到收敛 这是整套机制最精彩的部分。完成标记completed_at只在所有下游效果全部结束后才写入见 complete_observation_ingest_if_claimed。在此之前任何下游效果都是至少一次的崩溃窗口内进程在效果中途挂掉重放时可能重复执行一个已生效的动作比如再提交一次 wiki——这是被接受的代价但绝不会静默丢失剩余效果重放会沿ResumePending路径把没做完的补齐重叠重试不竞速每个项目 密钥有一把进程内门闩IngestGates保证并发的重试不会和原始处理互相踩踏。路由层对三种结局的处理一目了然AlreadyComplete直接返回、ResumePending记录恢复未完成的带密钥事件后继续补做router.rs。SessionEnd 的特殊收敛水位线与交接单同事务会话结束事件最重要生成会话摘要页、自动交接单、LLM 整合入队。ai-memory 的约定是结束水位线与自动交接单在同一个 SQLite 事务里提交——恢复时永远不会只看到一半的数据库效果。之后若同一 SessionEnd 被重放发现事务已完成 → 只补齐中断的 wiki 提交、持久化 LLM 任务与密钥完成标记不会追加第二条观察、第二张交接单重放收敛而非叠加。整体设计叙述可对照 docs/ARCHITECTURE.md 与 docs/design-decisions.md 查看。五、总结新手如何判断这套机制在生效 ✅记住三个信号即可验证崩溃恢复是否按设计工作重放不重复同一个带密钥事件重放观察表行数不变AlreadyComplete生效补做不遗漏处理中途崩溃后重放会话页面、交接单等缺失效果被补齐ResumePending生效收敛不叠加SessionEnd 重放后交接单只有一张水位线不重复推进。一句话概括ai-memory 用本地 spool 幂等密钥 服务端三态去重 完成标记水位线三层结构把脆弱的网络与进程环境收敛成一条不丢、不重、最终一致的记忆写入流水线。【免费下载链接】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辅助生成（AIGC），仅供参考
