remaind 0.1.3

Durable context for long-running agents.

Remaind

Durable context for long-running agents.

Remaind is a local-first context ledger, compaction pipeline, and resume substrate for AI agents. It preserves the meaningful state of an agent run across context resets: a future agent can start with a clean model context, load Remaind's local state, understand what happened before, know what must happen next, and continue safely without asking the user to reconstruct the work.

Remaind is not a wiki — it is a machine-readable and human-readable continuity layer: raw event ledger, structured state, compact handover, searchable memory, structured validation, safe rollback, and a mechanical resume gate.

Install

pip install remaind                 # core: rule-based compaction
pip install 'remaind[llm]'          # + the Anthropic-backed LLM compactor

Requires Python ≥ 3.11.

Quick start

# Bootstrap a .context/ in the current directory.
remaind init

# Inspect what's there.
remaind validate
remaind status

# After work happens (events appended by your agent harness),
# compact when token band climbs.
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

Use it as a library

import remaind is the stable public API — remaind.__all__ is the whole surface. The underscore-prefixed modules are internal.

import remaind

base = "./my-agent-run"
remaind.init(base)

state = remaind.status(base)
writer = remaind.EventWriter.open(base)
writer.append(remaind.EventInput(
    type="user_message", actor="user", summary="Asked to refactor auth",
    session_id=state["session_id"], task_id=state["task_id"],
    content="Please refactor src/auth/...", importance=3,
))

if remaind.compaction_status(base).compaction_needed:
    remaind.compact(base, compactor=remaind.LLMCompactor.from_context(base))

packet = remaind.resume(base).packet   # inject packet.content into a fresh context

Full walkthrough — the agent-loop integration, choosing a compactor (including local models via CallableCompactor), the resume-injection pattern, and an exception reference — is in docs/integration.md.

What lives in .context/

.context/
├── README.md
├── CONTRACT.md           # the contract — read this first
├── active/
│   ├── state.json        # derived working state (atomic replace)
│   ├── handover.md       # compact continuity document (atomic replace)
│   └── (resume_packet.md, history/  — runtime, git-ignored)
├── 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           # 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, git-ignored)

Authority order

When sources disagree, lower wins:

1. Latest explicit user instruction
2. Raw event log (logs/events.jsonl)
3. active/state.json
4. active/handover.md
5. Derived memories

A stale summary or memory MUST NOT override a newer user instruction.

Commands

Command	What it does
remaind init	Bootstrap .context/; --force backs up existing
remaind validate	Walk the v1 checklist (structure, schemas, events, SQLite)
remaind status [--json]	State + thresholds + event counts + compaction recommendation
remaind compact	Run the compaction pipeline, gated by structured validation. --llm (Anthropic) or --compactor MODULE:FUNCTION (any model) for real summarization
remaind resume [--next-tool TOOL]	Build a resume packet; consult the resume gate
remaind rollback --to <ts>	Restore derived files from history; raw log untouched

Architecture

Phase	Subject
1	Frozen contract — schemas, configs, layout
2	Migration interfaces — state migrations + event adapters (Protocols)
3	init + validate + schema/config loaders + JSONL streaming
4	Redaction engine + content-addressed artifact store + append-only event writer
5	Atomic state/handover writes + history snapshots + threshold band recompute
6	status human/JSON inspector
7	SQLite memory + FTS5 (memories, memories_fts, events_index)
8	chars/4 token estimator + compaction-needed surface
9	Source-event selection + reference compactor
10	Structured compaction validator (reject-on-any-false)
11	Resume packet builder + mechanical resume gate
12	Rollback (restores derived files; raw log untouched)

V1 non-goals

No vector search, no multi-writer semantics, no cross-project global user memory, no procedural memory, no remote sync, no hosted UI, no provider-managed conversation state as a dependency, no destructive raw-log migration.

Hard rules

• Do not rewrite events.jsonl.
• Do not let summaries become source of truth.
• Do not store secrets in raw logs.
• Do not store huge outputs inline (threshold: 4096 bytes).
• Do not allow stale memory to override latest user instruction.
• Do not accept compaction without structured validation.
• Do not mutate files on resume if the resume packet is contradictory or unsafe.

Tests

.venv/bin/python -m pytest -q

177 tests covering every phase. Adding a feature? Add a test.

License

MIT — see LICENSE.