# 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