How Remaind works

Remaind is a local-first CLI and Python package that turns project activity into source-linked continuity. It stores the work in a local .context ledger, builds compact markdown handoff packets, and lets the next model session continue from current state.

Live continuity chain
A

Work

linked to next point

B

Capture

linked to next point

C

State

linked to next point

D

Handoff

linked to next point

E

Continue

linked to next point

F

Save

saved as next start

In ten seconds: work gets captured, state stays local, handoff writes a portable packet, and the next model continues without replaying the old chat.

Five-minute proof path

One copy-paste path from claim to local proof.

This path installs the published package, creates local memory, checks the offline plan boundary, verifies readiness, runs the finance handoff proof, and then runs the golden continuity and handoff proof suite. remaind launch, remaind capture, and remaind handoff are the work commands after the proof path is trusted.

python3 -m pip install --upgrade remaind

remaind plan
remaind init
remaind doctor
remaind demo finance-handoff \
  --force
remaind proof
InstallFetch the published Remaind package.
PlanConfirm Basic is offline, local, and not tied to billing or accounts.
InitializeCreate a local .context workspace in the current project.
DoctorCheck local memory structure, state, and runtime readiness.
Finance demoRun the governed policy-exception proof with scoped reviewed memory.
ProofRun continuity, handoff, speed, context-engine, matrix, and agent-hook checks.

Full command output includes local workspace paths and detailed evidence tables. Those paths vary by machine; the PASS lines below are the stable checks to look for. See the Demo page for the interactive reset comparison.

Short version

A handoff layer around AI work.

Remaind does not replace your model or chat app. It keeps the working memory around them: what happened, what is true now, what evidence supports it, and what the next session needs.

CLI + Python package

Run it from the terminal or call the API from an agent loop.

Local .context ledger

Project memory lives in the workspace you choose.

Markdown handoff packet

The next model gets a compact handoff, not a transcript dump.

Evidence-first memory

State keeps source links, authority, stale checks, and conflicts visible.

The loop

Work, capture, handoff, continue.

The flow is intentionally mechanical. Each step has one job, so the packet is useful without becoming a mystery summary.

1

Work

Your model, agent, or terminal workflow does the job.

2

Capture

`remaind transfer start` records what changed before the handoff.

3

Store

Remaind updates the local event log, state, progress, artifacts, and memory records.

4

Handoff

Remaind writes a receiver guide, markdown packet, manifest, and adapter files.

5

Continue

Any next model can read the packet and continue from current truth.

6

Save

`remaind transfer finish` captures the receiver output so the loop starts current again.

Packet contract

The model-facing packet is markdown. The durable records behind it remain structured, local, and source-linked.

Raw logWhat happened, with source event IDs
StateCurrent goal, plan, decisions, blockers, next step
EvidenceFiles, command output, artifacts, reviewed decisions
SafetyStale state, conflicts, scope failures, adversarial warnings
Active packetA markdown packet at .context/active/resume_packet.md

What the next model sees

A focused handoff, not every old message. Your harness decides where to place it.

# .context/active/resume_packet.md

## Current state
Goal: continue the active implementation
Decision: keep the rollback path available
Constraint: do not touch refund handling yet

## Evidence
- file_change: webhooks/v2.py mapped all 6 event types
- tool_result: tests passed

## Next step
Wire v2 into the router.

Use it

Start in the terminal, then connect any agent workflow.

Remaind does not own the model session. It prepares the handoff packet, then your terminal, Python loop, agent harness, or chat workflow decides where that packet goes.

Run the handoff loop

After the proof path, capture finished work and export the next model packet from the terminal.

remaind plan
remaind proof
remaind transfer start \
  --from-model "source model" \
  --to-model "receiving model" \
  --completed "Implemented the retry route" \
  --decision "Use event_id + provider as the idempotency key" \
  --next-step "Run the focused retry tests" \
remaind transfer finish \
  --from-model "receiving model" \
  --from-file receiver-output.md

handoff can capture the work and write the universal packet in one command.

Wire your agent

Remaind prepares the continuity packet. Your workflow decides how it reaches the next model context.

Top-level CLIRun `remaind transfer start` to hand work to the next model, then `remaind transfer finish` to capture the result.
Python APICall the package from your loop to write events, update state, and build handoffs.
Agent harnessShell out to Remaind before a fresh model context starts.
Closed chatGenerate the handoff packet, then paste or prepend it when the app has no adapter.

Choose runtime

Use local models, hosted API models, or both without turning Remaind into the model provider.

Local modelsUse Ollama or any OpenAI-compatible local runtime for compaction and answers.
API modelsPoint Remaind at OpenAI-compatible hosted endpoints when that workflow needs them.
Key handlingConfigure keys at runtime; Remaind does not write them into .context.

Differentiation

Continuity outside one chat app.

App-native memory helps inside one product. Remaind is for work that has to survive resets, model swaps, source files, reviewed decisions, and terminal workflows.

Model-neutral

The same project state can move across local models, API models, and agent shells.

Source-linked

The packet points back to events, artifacts, files, reviewed decisions, and state records.

Small by design

Remaind carries the smallest useful brief instead of replaying every old token.

Governed handoffs

Reviewed decisions can fail closed on scope, expiry, missing provenance, and conflict.

Small context

The live model receives only the useful working memory.

Auditable evidence

Important claims retain a path back to source material.

Owned memory

The local .context workspace stays under your control.