完整解析 Maka AI Agent 的 SQLite 存储架构为什么 runtime.sqlite 是唯一权威【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/makaMakaApache Incubating是一个 local-first 的 AI Agent 工作区。它把 Agent 的模型消息、工具调用、工具结果、权限决策和终止事件全部记录为一条只增不改append-only的日志——而这条日志的唯一权威载体就是工作区目录下的那个runtime.sqlite文件。本文带你快速看懂它的存储架构这个 SQLite 数据库里存了什么、为什么其他文件说不上话以及它对普通用户意味着什么。runtime.sqlite 是什么AI Agent 工作区的总账本Maka 的 Workspace 数据默认存放在 Electron 的userData目录下结构非常扁平Electron userData/workspaces/default/ runtime.sqlite ← 唯一的权威运行记录 connection-catalog.json credential-vault.json settings.json artifacts/其中runtime.sqlite承载了 Agent 运行过程中一切关键事实每一次模型请求、每一次工具调用、每一次权限判定都是账本上的一行。你可以把它理解成 Agent 世界的流水账 状态机合体。为什么它是唯一权威Single Source of Truth很多项目会把会话记录写成 JSONL 文本文件出问题后再想办法。Maka 的设计刻意反着来核心规则只有三条1️⃣ 单向导入永不回头打开 RuntimeEvent writer → 创建或迁移 runtime.sqlite → 批量、幂等导入 legacy RuntimeEvent JSONL → RuntimeEvent 只写 SQLite旧版 JSONL 只会在首次写入时被一次性导入导入完成后就退居幕后只承担遗留导入和显式导出的角色。2️⃣ 没有 backend 开关系统里根本不存在用 JSONL 还是用 SQLite的开关。runtime.sqlite一旦存在所有读取方Reader只读 SQLite绝不会再去和过期的 JSONL 合并或回退fallback。这从机制上杜绝了两个数据源各说各话的经典事故。3️⃣ 升级即边界官方文档明确说明runtime.sqlite是当前活记录更早的 JSONL transcript 和旧凭据不会导入升级后会话可能是空的。这不是 bug而是设计——权威只有一个迁移责任清晰。 相关文档runtime-resume-architecture.zh-CN.md、runtime-managed-workspace-baseline-open-v1.zh-CN.md核心表结构一览账本里到底记了什么数据库 Schema 定义在packages/storage/src/sqlite-runtime-schema.ts当前版本为12通过 12 个带编号的迁移步骤演进。核心表可以归为四类runtime_events只增不改的事件日志这是整个账本的心脏。每个事件携带event_id、session_id、run_id、turn_id和自增的event_seq并用UNIQUE (invocation_id, event_seq)约束保证同一调用内事件序号绝不重复——想篡改历史数据库层面就过不了关。tool_journal_events tool_operations工具调用状态机工具调用不是一次性的它经历调用 → 派发 → 执行 → 结果的完整生命周期。tool_journal_events记录每一步的状态流转tool_operations则保存当前状态、参数哈希canonical_args_hash和版本号。这正是崩溃后判断这个工具到底跑完没有的依据。Partial Snapshots流式输出不丢半句模型还在流式输出时进程就崩了怎么办runtime_partial_snapshots和runtime_partial_segments两张表会把已产出的部分文本分段持久化恢复时接上就能继续而不是从头再来。Continuation Claims给续跑上锁想续跑一个中断的回合必须先登记一条 continuation claim数据库用多重UNIQUE约束来源前缀摘要、目标 Run ID、边界 digest保证同一段历史只能被续跑一次从存储层防住了重复消耗 token 的续跑。此外还有工作区版本权威表runtime_workspace_epochs/runtime_workspace_versions/runtime_workspace_heads和存储根绑定表runtime_storage_root_binding确保账本与这个工作区、这一代数据的对应关系不可混淆。抗崩溃工程WAL 模式与严格持久化Schema 文件里的初始化函数configureSqliteRuntimeDatabase只有四行 pragma却处处是求稳的考量配置作用journal_mode WAL读写并发不阻塞且 WAL 模式是持久化属性老库只需校验synchronous FULL每次提交都完整落盘崩溃不丢已提交事件foreign_keys ON表间引用完整性由数据库强制busy_timeout 5000并发打开时排队等待而非直接失败配套测试如packages/storage/src/__tests__/sqlite-runtime-crash.test.ts、sqlite-recovery-concurrency.test.ts专门模拟崩溃与并发写入场景验证账本在极端情况下依然自洽。这对普通用户意味着什么✅可审计Agent 的每一步行为都能在runtime.sqlite里找到对应事件出了问题有据可查✅可恢复中断的回合可以安全续跑默认关闭设置MAKA_RUNTIME_SAFE_BOUNDARY_RESUME1后启用 Desktop 安全恢复与 CLI/resume✅可迁移账本是一个自包含的 SQLite 文件配合 Session Bundle 契约packages/storage/src/session-bundle-*.ts可以整体导出迁移⚠️注意续跑路径会重新打模型、消耗 token请按需开启。延伸阅读存储实现入口packages/storage/src/sqlite-runtime-store.tsSchema 与迁移packages/storage/src/sqlite-runtime-schema.ts事件不变量与权威校验packages/storage/src/runtime-event-invariants.ts、runtime-event-authority.ts架构总览ARCHITECTURE.zh-CN.md、隐私说明 workspace-privacy-context.md一句话总结Maka 选择用一个SQLite 文件当唯一权威牺牲了多格式兼容的灵活性换来了 Agent 运行历史在崩溃、并发和升级场景下的确定性与可恢复性——这正是 local-first AI Agent 工作区最值得学习的存储取舍。【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考