# 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 拆分方案。