Initial standalone memabra release

README.md

@@ -0,0 +1,84 @@
+# memabra
+
+An intuition-driven control plane for agent memory and action selection.
+
+## What is memabra?
+
+memabra is a local-first, observable, trainable, and replayable agent memory and action orchestration system.
+
+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
+
+```bash
+git clone https://github.com/TacitLab/memabra.git
+cd memabra
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### 1. See the available commands
+
+```bash
+memabra --help
+```
+
+### 2. Run a dry-run evaluation
+
+A safe way to see the full workflow without actually promoting a new router version:
+
+```bash
+memabra run --dry-run --format text
+```
+
+### 3. Check system status
+
+```bash
+memabra status --format text
+```
+
+### 4. List saved router versions
+
+```bash
+memabra version list --format text
+```
+
+### 5. Roll back to a previous version
+
+```bash
+memabra version rollback <version-id> --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 <id>` | 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
+
+```bash
+pytest tests/ -q
+```
+
+## Project status
+
+See [docs/PROGRESS.md](docs/PROGRESS.md) for a detailed capability roadmap and [docs/DEMO.md](docs/DEMO.md) for walkthrough examples.
+
+## License
+
+MIT