memabra/docs/EXECUTION_AND_PERSISTENCE.md

Execution and Persistence

目标

给 memabra 补上两块真正让系统“落地”的骨头：

• execution：让路由决策进入可执行动作层
• persistence：让 trajectory 和 memory record 能落到磁盘

当前实现

execution.py

提供：

• ActionResult
• MemoryExecutor
• SkillExecutor
• ToolExecutor （原 MockToolExecutor，现已升级为可接真实后端）
• ExecutionEngine
• ToolBackend 协议（支持 params 传参）
• LocalFunctionToolAdapter — 将工具映射到本地 Python 函数
• SubprocessToolAdapter — 将工具映射到 shell 命令
• ToolRegistry — 按 tool_id 注册、查找和执行工具

当前行为：

• inject_memory 会产出 memory_injected 事件，并在有 memory store 时标记 last_used_at
• load_skill 会产出 skill_loaded 事件
• call_tool 会通过 ToolBackend 协议调用真实后端，产出 tool_called 和 tool_result 事件
• RouteDecision 现在携带 selected_payloads，可以将候选参数经由 ToolExecutor 传递给后端
• 其他 decision_type 先走 noop

这一步的意义是： memabra 第一次有了 execution stage，而不是只有 policy stage。 并且 tool 层现在可以接入真实的本地函数或子进程后端，不再是纯 mock。

persistence.py

提供：

• PersistenceStore

当前能力：

• 保存 trajectory 到 artifacts/trajectories/
• 读取 trajectory
• 列出 trajectory 文件
• 保存 memory record 到 artifacts/memories/
• 读取 memory record
• 列出 memory 文件

这意味着 prototype artifacts 已经不再只是内存态漂浮物。

runner writeback integration

runner 现在支持：

• 挂 execution engine
• 挂 persistence store
• 挂 memory store
• 执行后扩展 execution events
• 可选把 trajectory 落盘
• 对 memory inject 决策进行基本 writeback / mark_used

当前闭环

现在的最小系统流程已经变成： 任务 -> retrieval -> router -> execution -> trajectory -> validation -> persistence -> replay

这就真正有点 agent runtime 的味儿了。

当前限制

• tool 执行还是 mock 的 已升级为可插拔式真实后端
• skill 执行只是事件层，不是真加载技能
• writeback 逻辑还很粗糙
• persistence 目前是 JSON 文件，没有索引层

下一步建议

1. 做真实 ToolExecutor / SkillExecutor adapter 协议 tool adapter 已完成
2. 做真实 SkillExecutor adapter（从文件系统加载 skill payload）
3. 把 persistence 接到 replay 默认数据源
4. 给 runner 增加 outcome / reward 的真实更新逻辑
5. 做 richer telemetry 和失败事件归因