memabra/docs/PROTOTYPE_LAYOUT.md

Prototype Layout

目标

为 memabra 建立一个最小可运行的原型目录结构，让后续 rule-based router、replay harness、sample trajectories 和训练样本生成都能有明确落点。

目录结构

src/memabra/
├── __init__.py
├── candidate_types.py      # 统一候选对象与决策类型
├── router.py               # Rule-based router baseline
├── telemetry.py            # 事件、reward、轨迹的运行时结构
├── reward.py               # reward 聚合逻辑
├── retrieval.py            # 后续：候选召回接口
├── memory_store.py         # 后续：长期记忆存取
├── replay.py               # 后续：trajectory 回放与评估
└── schemas.py              # 后续：schema 装载/校验

tests/memabra/
└── test_router_smoke.py    # baseline 冒烟测试

当前已落地

已创建：

• src/memabra/__init__.py
• src/memabra/candidate_types.py
• src/memabra/router.py
• src/memabra/telemetry.py
• src/memabra/reward.py
• tests/memabra/test_router_smoke.py

模块边界

candidate_types.py

负责：

• CandidateObject
• DecisionType
• 后续可扩展 memory/skill/tool type-specific adapter

router.py

负责：

• TaskContext
• RouteDecision
• RuleBasedRouter

当前只实现 baseline 启发式，后续升级为：

• 特征打分器
• reranker
• learned policy

telemetry.py

负责：

• 原子事件结构
• reward breakdown
• 后续 trajectory runtime objects

reward.py

负责：

• reward 组合与计算
• 后续权重版本化

设计原则

1. 先有可运行 baseline，再抽象复杂接口
2. 数据结构先简单，但字段命名与 Phase 0 schema 保持一致
3. 先保证 replayable，再考虑高性能
4. 不提前引入数据库或向量库耦合

下一步落点

• retrieval.py：定义候选召回接口
• replay.py：实现 trajectory 读取、回放和指标计算
• schemas.py：把 JSON schema 转成运行时校验入口
• sample_data/：放示例 candidates 和 trajectories

验证建议

在项目根目录运行：

source venv/bin/activate
python -m pytest tests/memabra/test_router_smoke.py -q

期望：

• baseline router 冒烟测试通过
• 说明最小原型骨架已可被导入和调用