Initial standalone memabra release

docs/README.md

@@ -0,0 +1,87 @@
+# memabra
+
+An intuition-driven control plane for agent memory and action selection.
+
+## Quick start
+
+If you are working from this repository, activate the virtualenv and install the project in editable mode so the dedicated `memabra` command is available:
+
+```bash
+source venv/bin/activate
+uv pip install -e ".[dev]"
+memabra --help
+memabra run --base-dir /tmp/memabra-demo --format text --dry-run
+```
+
+The dedicated CLI is the fastest way to experience the alpha. It supports subcommands for different operations:
+
+- `memabra run` — run the online-learning loop
+- `memabra status` — show system status
+- `memabra version list` — list saved router versions
+- `memabra version rollback <id>` — roll back to a version
+
+memabra 的目标，不是做一个“会存东西的记忆库”，而是做一个本地 agent 的元认知控制器：
+在面对任务时，能像人的直觉一样，快速判断该直接回答、查记忆、加载 skill、还是调用工具；并且根据任务结果持续优化这种判断。
+
+一句话定义：
+这是一个 local-first、可观测、可训练、可回放的 agent memory and action orchestration system。
+
+## 为什么要做
+
+传统 agent 的常见问题：
+- 上下文越来越胖，什么都往 prompt 里塞
+- 记忆、skill、工具是三套割裂系统
+- 成功或失败后，很难知道到底是哪一步起了作用
+- 想“学习”时，缺少可归因的轨迹数据
+
+memabra 要解决的本质问题是：
+什么时候该依赖什么。
+
+## 核心观点
+
+先不要一上来做端到端神经网络大一统训练。
+先建立 4 层结构：
+1. 检索层：召回候选 memory / skill / tool
+2. 路由层：决定调用什么，以及先后顺序
+3. 执行层：真正注入记忆、加载 skill、调用工具
+4. 评估层：记录结果，分配 credit，形成训练样本
+
+如果这 4 层都看不清，直接端到端训练，大概率会学成“少调工具、靠模型硬猜”的歪路子。
+
+## 项目输出
+
+当前目录先以方案与设计文档为主：
+- `ARCHITECTURE.md`：系统架构
+- `ROADMAP.md`：分阶段路线图
+- `DECISIONS.md`：关键设计决策
+- `PROGRESS.md`：当前进度和下一步
+- `schemas/`：Phase 0 的统一 schema
+- `reward_spec.md`：奖励设计草案
+
+后续可以补：
+- `experiments/`：训练与评估实验
+- `src/`：原型代码
+- `tests/`：验证与回归测试
+
+## 目标能力
+
+最终希望具备：
+- 统一管理 facts / procedures / episodes 三类长期信息
+- 给 memory、skill、tool 建立统一候选召回机制
+- 让一个“直觉策略器”做快速动作选择
+- 通过任务结果反推策略好坏
+- 逐步从规则系统过渡到可学习策略
+- 在本地环境下可持续演化
+
+## 当前状态
+
+项目已初始化，并已进入 Phase 0 基础定义阶段：
+- 完成方向澄清
+- 确立分层路线
+- 完成命名
+- 建立项目目录
+- 写入首版架构、路线图、决策和进度文档
+- 准备补齐 schema 与 reward 规范
+
+下一步建议直接进入 Phase 0：
+定义统一对象模型、轨迹日志结构、reward 拆分方案。