# Design Decisions

## D-001: 不以端到端训练作为第一阶段目标

决定：
第一阶段采用分层架构，不直接训练一个从任务到动作的黑盒大模型。

原因：
- 反馈稀疏
- credit assignment 困难
- 数据量不足时容易学偏
- 可解释性太差，难 debug

影响：
项目先构建 observability、logging、router 和 reward 层。

## D-002: 将 memory、skill、tool 统一为候选对象接口，但不混淆类型

决定：
在召回和排序阶段，三者共享统一候选 schema；在存储、执行和评估阶段，保持强类型边界。

原因：
- 统一召回便于路由决策
- 保持类型边界可避免语义坍塌

影响：
后续 schema 设计需要同时支持统一特征和类型特有字段。

## D-003: 记忆分为 facts / procedures / episodes / working 四层

决定：
长期系统至少区分：
- facts
- procedures
- episodes
- working memory

原因：
“记忆”不是一坨文本，人的有效直觉来自多种记忆系统协同。

影响：
每个写入动作都要先判定落到哪一层，而不是直接塞进统一向量库。

## D-004: 先优化路由策略，再考虑学习基础模型内部权重

决定：
学习目标先放在 external policy 上，而不是 foundation model 的参数上。

原因：
- 小模型更便宜
- 训练更稳定
- 更容易比较实验结果
- 更适合本地部署

影响：
需要专门设计 router features、训练样本和离线评估框架。

## D-005: reward 必须拆分，不使用单一任务成败信号

决定：
reward 将拆分为 success、efficiency、retrieval_hit、user_correction、tool_error、latency、context_cost 等因子。

原因：
只看任务成功会掩盖大量中间行为质量问题。

影响：
需要事件级 logging，不能只存最终答案。

## D-006: 所有学习都建立在可回放轨迹上

决定：
任何策略更新都必须能追溯到完整 trajectory。

原因：
不可回放，就无法排查策略劣化；不可回放，也无法做人类审计。

影响：
trajectory schema 和 replay 工具会成为基础设施，而不是可选项。

## D-007: 项目正式命名为 memabra

决定：
项目正式名采用 `memabra`。

副标题：
An intuition-driven control plane for agent memory and action selection.

原因：
- 需要一个可品牌化、可传播的短名
- 技术本质由副标题补足
- 避免旧名把项目误导成“单纯记忆管理工具”

影响：
后续所有原型代码、文档、schema 标识、演示材料统一使用 memabra。