Docs

Reference for the Remaind CLI, the .context/ directory it manages, and the schemas that make it verifiable. To wire Remaind into an agent, see Integrate.

Install

pip install remaind            # core
pip install 'remaind[llm]'     # + the Anthropic LLM compactor

Requires Python 3.11+. The core install has no optional dependencies.

CLI reference

Six commands cover the full lifecycle. Every state-mutating command snapshots the prior version before writing.

Command	What it does
remaind init [--path P] [--force]	Create .context/. --force backs up an existing one first.
remaind validate [--path P]	Walk the v1 checklist: structure, schemas, state, handover, events, SQLite.
remaind status [--path P] [--json]	Goal, status, next step, token band, event counts, compaction recommendation.
remaind compact [--path P]	Run the compaction pipeline (rule-based by default), gated by structured validation.
remaind compact --llm [--model M]	Compact with the Anthropic-backed LLM compactor. Needs remaind[llm] + ANTHROPIC_API_KEY.
remaind compact --compactor MOD:FN	Compact with any model — imports MOD:FN as a (system, user) → str \| dict callable.
remaind resume [--path P] [--next-tool T]	Build active/resume_packet.md and consult the resume gate.
remaind rollback [--path P] --to TS	Restore derived files from history as of TS. The raw log is never touched.

The .context/ directory

One directory per project. Files under active/ are derived and atomically replaced; events.jsonl is append-only and authoritative; schemas/ is the contract. Runtime files (resume_packet.md, history/, db/, artifacts/) are git-ignored.

.context/
├── CONTRACT.md                 the binding contract — read this first
├── active/
│   ├── state.json              derived working state (atomic replace)
│   ├── handover.md             compact continuity document (atomic replace)
│   ├── resume_packet.md        runtime — assembled fresh-context packet
│   └── history/                runtime — snapshots of every prior version
├── logs/
│   └── events.jsonl            append-only raw timeline (source of truth)
├── schemas/
│   ├── event.schema.json       JSON Schema Draft 2020-12
│   ├── state.schema.json
│   ├── memory.schema.json
│   ├── validation.schema.json
│   ├── thresholds.yaml         token-band math
│   ├── redaction.yaml          secret patterns redacted before logging
│   ├── tools.yaml              mechanical tool-risk flags
│   └── migrations/{state,events}/
├── db/context.sqlite           runtime — memory index + FTS5
└── artifacts/                  runtime — large + binary outputs

Schemas

JSON Schemas are canonical — runtime data is validated against them, not the other way around. The YAML files are configuration.

File	Purpose
event.schema.json	Every line of events.jsonl — validated before append.
state.schema.json	active/state.json — validated on every write.
memory.schema.json	Rows in the SQLite memory index.
validation.schema.json	The compaction validator's structured result.
thresholds.yaml	Token-band math and the compaction budget.
redaction.yaml	Regex patterns + replacement format for secret redaction.
tools.yaml	Per-tool mutates / spends_money / external_side_effect flags.

Importance levels

Every event carries an importance 0–3. Compaction must preserve all importance ≥ 2 events; importance = 3 items must be explicitly represented in state or handover.

Level	Meaning
0	trace / debug
1	normal useful event
2	decision, correction, constraint, file change, blocker, meaningful result
3	remember-instruction, active next step, active blocker, critical user instruction

Threshold bands

The token estimate drives a band. Defaults below — all configurable in thresholds.yaml.

Band	Estimated tokens	Recommendation
normal	< 60,000 tokens	continue
warning	≥ 60,000	mark compaction pending
hard	≥ 70,000	compact before the next substantial step
emergency	≥ 80,000	compact immediately

Integrate — wire Remaind into your agent loop: the public API, event logging, compaction, and resume, with runnable code. How it works — the mechanics behind the commands. The full binding contract ships as .context/CONTRACT.md after remaind init.