Initial standalone memabra release

docs/EXECUTION_AND_PERSISTENCE.md

@@ -0,0 +1,77 @@
+# 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 和失败事件归因