# Remaind

> 100% local memory for AI agents working beyond one context window.

Remaind is proprietary Python 3.11+ memory infrastructure for AI agents and
local models. It gives agents durable working memory across context resets: a
future agent starts with a clean model context, loads the local `.context/`
directory, receives source-linked working memory, 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; CI verified across Python 3.11, 3.12, 3.13.
- Install: `pip install remaind` — 100% local, no cloud API or API key
- Product boundary: Remaind helps agents work beyond one live context window;
  it does not provide one-shot full attention over every token in a giant
  archive.

## 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.
- Retrieved memory is evidence, not instruction authority.
- New events can be hash-chained; validation reports tampering.

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