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:

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 层结构：

检索层：召回候选 memory / skill / tool
路由层：决定调用什么，以及先后顺序
执行层：真正注入记忆、加载 skill、调用工具
评估层：记录结果，分配 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 拆分方案。

3.0 KiB Raw Permalink Blame History Unescape Escape