Docs

python3 -m pip install --upgrade remaind

Requires Python 3.11+. Remaind is local-first: no hosted Remaind memory service is required, and project continuity lives in your .context/ directory.

Model-backed compaction can use Ollama automatically, or any OpenAI-compatible endpoint through REMAIND_OPENAI_BASE_URL. If no runtime is reachable, deterministic rule-based bookkeeping keeps the system safe. If you point Remaind at an external API endpoint, that provider receives the compact prompt you send it.

These commands cover the public lifecycle. Every state-mutating command snapshots the prior version before writing.

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/
├── README.md                   local operating guide
├── 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
│   ├── run_packet.md           runtime — evidence packet from remaind run
│   ├── run_answer.md           runtime — latest answer from remaind run
│   └── history/                runtime — snapshots of every prior version
├── logs/
│   └── events.jsonl            append-only raw timeline + event chain
├── large-docs/                 runtime — manifests for huge local documents
├── handoffs/                   runtime — universal cross-model handoff bundles
├── 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}/ future schema migration hooks
├── db/context.sqlite           runtime — memory index + FTS5
└── artifacts/                  runtime — large + binary outputs

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

Remaind is built for continuity, but it does not treat old memory as an instruction source. Retrieved memory is evidence. The latest user instruction and raw event log remain higher authority.

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.

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

The Sovereign Memory starter kit packages Remaind into a complete local operator workflow: bootstrap, profiles, readiness checks, Qwen Code and console adapters, and executable product proofs. Model profiles include API-backed models, local runtimes, and custom model servers. Starter profiles use local project folders that the operator controls.

The 2M proof is an A/B demonstration, not a claim of one-shot full attention: direct raw prompt fails or loses distant facts; the compact, source-linked Remaind packet fits the current window and recovers the tested facts.

The finance proof path is separate from the starter kit: remaind demo finance-handoff shows reviewed exceptions moving through a real local ledger, while remaind bench finance-handoff prints the compact deterministic scorecard.

For a real local-model proof, run remaind demo agent-continuity --force after pointingREMAIND_OPENAI_BASE_URL and REMAIND_OPENAI_MODELat a local or private OpenAI-compatible model server. That proof is separate from the golden proof because it measures model honor behavior, not only Remaind's deterministic packet machinery.

For the Hermes launch path, run remaind hermes status --require-ready, remaind hermes speed --checkpoint-smoke --require-ready, then remaind hermes verify --force --include-live. The launch gate checks installed readiness, low-noise UX, provider comparison, live Hermes loading, and the 500k-token reset loop.

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