153 lines
4.5 KiB
Markdown
153 lines
4.5 KiB
Markdown
<div align="center">
|
||
|
||
```
|
||
███╗ ███╗███████╗███╗ ███╗ █████╗ ██████╗ ██████╗ █████╗ ╭────────╮
|
||
████╗ ████║██╔════╝████╗ ████║██╔══██╗██╔══██╗██╔══██╗██╔══██╗ ╱ ◉──◉ ╲
|
||
██╔████╔██║█████╗ ██╔████╔██║███████║██████╔╝██████╔╝███████║ │ ╱ ││ ╲ │
|
||
██║╚██╔╝██║██╔══╝ ██║╚██╔╝██║██╔══██║██╔══██╗██╔══██╗██╔══██║ │ ││ │
|
||
██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║██║ ██║██████╔╝██║ ██║██║ ██║ ╲ ◉──◉ ╱
|
||
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╰────────╯
|
||
```
|
||
|
||
**Intuition-driven control plane for agent memory & action selection.**
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[]()
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 🧠 What is memabra?
|
||
|
||
> *Most agents memorize. memabra **intuits**.*
|
||
|
||
memabra is a **local-first, observable, trainable, and replayable** control plane for agent memory and action orchestration.
|
||
|
||
Instead of acting like a dusty filing cabinet, memabra functions as a **meta-cognitive controller**: given any task, it rapidly decides whether to answer directly, recall memory, load a skill, or invoke a tool — then **learns from outcomes** to sharpen those instincts over time.
|
||
|
||
- 🏠 **Local-first** — no cloud lock-in, your data stays on disk
|
||
- 📊 **Observable** — every decision is tracked, versioned, and inspectable
|
||
- 🎓 **Trainable** — online learning loop improves routing automatically
|
||
- 🔄 **Replayable** — replay trajectories, audit decisions, roll back versions
|
||
|
||
---
|
||
|
||
## ⚡ Quick Start
|
||
|
||
```bash
|
||
git clone https://github.com/TacitLab/memabra.git
|
||
cd memabra
|
||
python -m venv venv
|
||
source venv/bin/activate
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
### 1. Peek under the hood
|
||
```bash
|
||
memabra --help
|
||
```
|
||
|
||
### 2. Run a safe dry-run evaluation
|
||
See the full workflow **without** actually promoting a new router version:
|
||
```bash
|
||
memabra run --dry-run --format text
|
||
```
|
||
|
||
### 3. Check system pulse
|
||
```bash
|
||
memabra status --format text
|
||
```
|
||
|
||
### 4. Inspect your router lineage
|
||
```bash
|
||
memabra version list --format text
|
||
```
|
||
|
||
### 5. Time-travel (rollback)
|
||
```bash
|
||
memabra version rollback <version-id> --format text
|
||
```
|
||
|
||
---
|
||
|
||
## 🎮 CLI Commands
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `memabra run` | 🚀 Execute the online learning workflow |
|
||
| `memabra status` | 💓 Show current system health & metrics |
|
||
| `memabra version list` | 📜 List all saved router versions |
|
||
| `memabra version rollback <id>` | ⏪ Roll back to a specific version |
|
||
|
||
---
|
||
|
||
## 🖨️ Operator-Friendly Output
|
||
|
||
By default, memabra speaks JSON. For humans, add `--format text`:
|
||
|
||
```bash
|
||
memabra run --dry-run --format text
|
||
```
|
||
|
||
Sample output:
|
||
|
||
```
|
||
Memabra online learning result
|
||
Summary
|
||
Report ID: report-58f9f22
|
||
Skipped: no
|
||
Promoted: yes
|
||
Dry run: yes
|
||
|
||
Baseline
|
||
Reward: 0.7200
|
||
Error rate: 0.1200
|
||
Latency (ms): 145.0000
|
||
|
||
Challenger
|
||
Reward: 0.8100
|
||
Error rate: 0.0800
|
||
Latency (ms): 132.5000
|
||
|
||
Deltas
|
||
Reward delta: 0.0900
|
||
Error rate delta: -0.0400
|
||
Latency delta (ms): -12.5000
|
||
|
||
Decision
|
||
Accepted: yes
|
||
Reason: challenger improved reward and reduced error rate
|
||
```
|
||
|
||
✅ **Normalized booleans** (`yes/no/none`)
|
||
✅ **Fixed-precision metrics** for easy comparison
|
||
✅ **Sectioned layout** — Summary → Baseline → Challenger → Deltas → Decision
|
||
|
||
---
|
||
|
||
## 🧪 Running Tests
|
||
|
||
```bash
|
||
pytest tests/ -q
|
||
```
|
||
|
||
Current status: **126 passed** 🟢
|
||
|
||
---
|
||
|
||
## 📚 Documentation
|
||
|
||
- [`docs/PROGRESS.md`](docs/PROGRESS.md) — Capability roadmap & what's shipped
|
||
- [`docs/DEMO.md`](docs/DEMO.md) — Hands-on walkthroughs & examples
|
||
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — System design & mental model
|
||
|
||
---
|
||
|
||
## 🏷️ License
|
||
|
||
MIT — use it, break it, improve it.
|
||
|
||
*Built with caffeine and curiosity.* ☕
|