diff --git a/README.md b/README.md index fffe149..95644ea 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,39 @@ -# memabra +
-An intuition-driven control plane for agent memory and action selection. +``` + __ __ _ + | \/ | ___ _ __ ___ __ _ __| | ___ ___ + | |\/| |/ _ \ '_ ` _ \ / _` |/ _` |/ _ \/ __| + | | | | __/ | | | | | (_| | (_| | __/\__ \ + |_| |_|\___|_| |_| |_|\__,_|\__,_|\___||___/ +``` -## What is memabra? +**Intuition-driven control plane for agent memory & action selection.** -memabra is a local-first, observable, trainable, and replayable agent memory and action orchestration system. +[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Tests](https://img.shields.io/badge/tests-126%20passed-brightgreen.svg)]() -Instead of being a simple memory database, memabra acts as a meta-cognitive controller for agents: given a task, it quickly decides whether to answer directly, recall memory, load a skill, or invoke a tool โ€” and continuously improves this judgment based on task outcomes. +
-## Install +--- + +## ๐Ÿง  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 @@ -18,67 +43,109 @@ source venv/bin/activate pip install -e ".[dev]" ``` -## Quick start - -### 1. See the available commands - +### 1. Peek under the hood ```bash memabra --help ``` -### 2. Run a dry-run evaluation +### 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 +``` -A safe way to see the full workflow without actually promoting a new router version: +### 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 --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 ` | โช 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 ``` -### 3. Check system status +Sample output: -```bash -memabra status --format text +``` +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 ``` -### 4. List saved router versions +โœ… **Normalized booleans** (`yes/no/none`) +โœ… **Fixed-precision metrics** for easy comparison +โœ… **Sectioned layout** โ€” Summary โ†’ Baseline โ†’ Challenger โ†’ Deltas โ†’ Decision -```bash -memabra version list --format text -``` +--- -### 5. Roll back to a previous version - -```bash -memabra version rollback --format text -``` - -## CLI subcommands - -| Command | Description | -|---------|-------------| -| `memabra run` | Run the online learning workflow | -| `memabra status` | Show current system state | -| `memabra version list` | List all saved router versions | -| `memabra version rollback ` | Roll back to a specific version | - -## Text output format - -By default, memabra prints JSON. For operator-friendly summaries, add `--format text`: - -- **Status** โ€” current version, trajectory/report counts, latest report timing and promotion outcome. -- **Version list** โ€” total count, current active version highlighted. -- **Workflow** โ€” grouped into Summary, Baseline, Challenger, Deltas, and Decision sections with normalized `yes/no` flags and fixed-precision metrics. - -## Running tests +## ๐Ÿงช Running Tests ```bash pytest tests/ -q ``` -## Project status +Current status: **126 passed** ๐ŸŸข -See [docs/PROGRESS.md](docs/PROGRESS.md) for a detailed capability roadmap and [docs/DEMO.md](docs/DEMO.md) for walkthrough examples. +--- -## License +## ๐Ÿ“š Documentation -MIT +- [`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.* โ˜•