v0.1.0 — alpha, 177 tests, MIT

Durable context for long-running agents.

Remaind is a local-first context ledger, compaction pipeline, and resume substrate. 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.

pip install remaind  # PyPI release pending — for now: git clone + pip install -e .

View on GitHub See the CLI

Not on PyPI yet — get an email the moment it lands.

The continuity layer agents need.

Naive summarization loses important details. Stale summaries override newer instructions. Fresh runs restart work incorrectly. Remaind separates immutable raw truth from derived state, with mechanical gates at every boundary.

Append-only event ledger

Every user message, tool call, decision, and file change lands in a JSONL log validated against a JSON Schema before write. The raw log is the source of truth — never rewritten, never lossy.

Redaction-by-default

Nine secret patterns (OpenAI, Anthropic, JWT, AWS, private keys, bearer tokens, …) replaced with deterministic hashes before the event ever touches disk. Same secret → same hash, no leakage.

Validated compaction

Compaction proposes; a six-check structured validator decides. Any required boolean false → reject and keep the prior handover. No stale summary can override newer user intent.

Mechanical resume gate

Resume is internal and seamless until raw log, state, and handover conflict — or the next planned tool has mutates / spends_money / external_side_effect flagged in tools.yaml.

Safe rollback

Every state and handover write atomically snapshots the prior version. `remaind rollback --to <timestamp>` restores derived files; events.jsonl stays untouched. Rollback is itself reversible.

Atomic on disk

Write target.tmp + fsync, rename over target, fsync parent dir. POSIX-correct, no partial writes, history captured on every replacement.

One folder.
Three sources of truth.

A single .context/ directory per project. Append-only raw log + derived working state + compact human-readable handover. When sources disagree, an explicit authority order resolves truth.

1Latest explicit user instruction

2Raw event log

3active/state.json

4active/handover.md

5Derived memories

.context/
├── README.md
├── CONTRACT.md           # the contract — read this first
├── active/
│   ├── state.json        # derived working state (atomic replace)
│   ├── handover.md       # compact continuity document
│   └── (resume_packet.md, history/  — runtime)
├── logs/
│   └── events.jsonl      # append-only raw timeline
├── schemas/
│   ├── event.schema.json         # JSON Schema Draft 2020-12
│   ├── state.schema.json
│   ├── memory.schema.json
│   ├── validation.schema.json
│   ├── thresholds.yaml           # 40k/60k/70k/80k band math
│   ├── redaction.yaml            # 9 default secret patterns
│   ├── tools.yaml                # mechanical risk flags
│   └── migrations/{state,events}/
└── (db/context.sqlite, artifacts/  — runtime)

Six commands. End-to-end lifecycle.

From bootstrap to rollback. Every state-mutating command snapshots the prior version atomically, so the system is self-healing.

Bootstrap a .context/ in the current directory.

remaind init

Inspect what's there.

remaind validate
remaind status

When the token band climbs, run a validated compaction.

remaind compact

Build a resume packet for a fresh agent run.

remaind resume --next-tool deploy_prod

Roll back if something went wrong.

remaind rollback --to 2026-05-14T03:54:33Z

Ship it as the persistence layer for your agent.

Python 3.11+. No services to run, no cloud to provision. Everything lives in .context/.

Get the launch email:

github.com/magpiexyz-lab/Remaind README