# 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
- Package: https://pypi.org/project/remaind/
- Docs: https://remaind.draftlabs.org/integrate
- License: Proprietary — all rights reserved
- Status: alpha; 221 tests passing across Python 3.11, 3.12, 3.13.
- Install: `pip install remaind` — 100% local, no cloud API or API key

## 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
