From ff0b86b7f9bde41bda9ce903dc8f59942064fe8b Mon Sep 17 00:00:00 2001
From: Carlos Ouyang <carlos@localhost.localdomain>
Date: Wed, 15 Apr 2026 11:18:55 +0800
Subject: [PATCH] docs: coolify README with banner, badges, and examples

---
 README.md | 161 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 114 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index fffe149..95644ea 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,39 @@
-# memabra
+<div align="center">
 
-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.
+</div>
 
-## 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 <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
 ```
 
-### 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 <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
+## 🧪 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.* ☕