# Remaind

> Durable context for long-running AI agents — local-first ledger,
> compaction pipeline, and resume substrate.

Remaind is an open-source Python 3.11+ library that preserves the
meaningful state of an agent run across context resets. A future agent
starts with a clean model context, loads the local `.context/` directory,
understands what happened before, and continues without asking the user
to reconstruct the work.

## Key facts
- Source: https://github.com/magpiexyz-lab/Remaind
- License: MIT
- Status: v0.1.0 alpha; 177 tests passing across Python 3.11, 3.12, 3.13.
- Install: `pip install -e .` (PyPI release pending)

## Architecture
- Append-only JSONL event log is the source of truth.
- Derived files (state.json, handover.md, resume_packet.md) are written
  atomically with history snapshots.
- Authority order (lower wins): user instruction > raw log > state.json >
  handover.md > derived memories.
- Compaction proposes; a structured validator with six required booleans
  decides. Any false → reject.
- Resume gate is mechanical, consults tools.yaml for risk classification.
- Rollback restores derived files; raw log untouched.

## Commands
- `remaind init` — bootstrap `.context/`
- `remaind validate` — checklist over schemas, state, handover, events
- `remaind status [--json]` — counts + thresholds + compaction recommendation
- `remaind compact` — validated compaction
- `remaind resume [--next-tool TOOL]` — build packet, consult gate
- `remaind rollback --to <ts>` — restore from history
