``` __ __ _ | \/ | ___ _ __ ___ __ _ __| | ___ ___ | |\/| |/ _ \ '_ ` _ \ / _` |/ _` |/ _ \/ __| | | | | __/ | | | | | (_| | (_| | __/\__ \ |_| |_|\___|_| |_| |_|\__,_|\__,_|\___||___/ ``` **Intuition-driven control plane for agent memory & action selection.** [![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)]()
--- ## ๐Ÿง  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 --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 ``` 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.* โ˜•