# 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 和失败事件归因