Metadata-Version: 2.4
Name: remaind
Version: 0.9.25
Summary: Local-first memory and context continuity for AI agents working beyond one context window.
Project-URL: Homepage, https://remaind.draftlabs.org
Project-URL: Documentation, https://remaind.draftlabs.org/integrate
Author: Draft Labs
License: Proprietary
License-File: LICENSE
Keywords: agents,compaction,context,handover,ledger
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: cryptography<49,>=48.0.1
Requires-Dist: jsonschema<5,>=4.18
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-jsonschema>=4.18; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Remaind

[![pypi](https://img.shields.io/pypi/v/remaind)](https://pypi.org/project/remaind/)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](#)
[![license](https://img.shields.io/badge/license-proprietary-lightgrey.svg)](LICENSE)

**Local-first continuity and handoff infrastructure for AI work across sessions, models, agents, and tools.**

Remaind is a local-first context ledger, compaction pipeline, resume substrate,
and universal handoff system for AI agents, local models, OpenAI-compatible API
models, coding agents, and automation workflows. It lets agents handle work
that is larger than a model's live context window by preserving the meaningful
state of the run across resets and handoffs: 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 and handoff layer**: raw event ledger, structured state, compact
handover, searchable memory, structured validation, safe rollback, a mechanical
resume gate, and model-neutral handoff bundles that another LLM or harness can
read.

Remaind also treats retrieved memory as evidence, not instructions. The resume
gate uses mechanical, defense-in-depth heuristics to flag known hostile
instruction shapes before a fresh model sees retrieved memories or raw excerpts,
and the compaction validator rejects poisoned local model output before it can
become durable memory. These checks improve hygiene around untrusted content;
they are not a standalone security boundary.

New events are also hash-chained in their metadata. `remaind validate` verifies
that chain and reports tampering when a chained event edit, deletion, or reorder
breaks continuity. Resume packets label retrieved events and memories with
mechanical trust hints such as `user`, `verified_tool`, `assistant`, or
`source_linked_memory`.

## Install

```sh
python3 -m pip install --upgrade remaind
remaind --version
remaind launch
```

Requires Python ≥ 3.11. The install gives you the `remaind` terminal command,
local memory/state storage, context packets, plan reconciliation, rollback,
monitoring, large-document tools, and model-agnostic launch/run flows.

Remaind does not install Python, local model runtimes, model files, or API
credentials. For model-generated answers, choose one of these at launch:

- a local Ollama model
- a local OpenAI-compatible server such as llama.cpp, vLLM, or LM Studio
- an API-backed OpenAI-compatible endpoint, including Qwen-style services
- packet-only / no-model workflows when you only need memory, context
  inspection, or recovery artifacts

If `python3` is missing, install Python 3.11+ first, then run the install
command above.

## Sovereign Memory Starter Kit

Remaind now ships a portable product kit for users who want a complete local
agent memory setup rather than only the Python library:

```text
starter-kits/sovereign-memory-starter/
```

The starter kit adds:

- one-command bootstrap/setup, readiness checks, and launch
- managed Python bootstrap through local, checksum-verified `uv` when Python 3.11+ is missing
- model profiles for Qwen, DeepSeek, DeepSeek v4 Flash, GLM, Minimax-style, Llama, and custom local models
- Ollama and OpenAI-compatible local compaction/chat, including llama.cpp server
- Qwen Code and built-in console adapters
- a synthetic continuity proof (`make proof`) that verifies fresh-process retrieval
- a beyond-context benchmark (`make bench`) for distant contradiction,
  revocation pressure, source-link, and adversarial checks
- a direct large-prompt runner (`remaind run FILE "TASK"`) that builds a
  compact evidence packet before calling the configured local model
- a model battle-test harness (`make model-test`) for deterministic Remaind
  retrieval checks plus optional local model matrix testing
- privacy-safe sharing: each user gets their own `.context/` ledger

Quick start from the repo:

```sh
cd starter-kits/sovereign-memory-starter
./bootstrap.sh --profile qwen-large --agent qwen-code
remaind
```

Console-only local proof:

```sh
cd starter-kits/sovereign-memory-starter
./bootstrap.sh --agent console --profile llama
make proof
```

Build the distributable zip:

```sh
scripts/build-sovereign-memory-starter.sh
```

This writes a release archive under `dist/`.

See the full product guide in
[docs/sovereign-memory-starter.md](docs/sovereign-memory-starter.md).
For the day-one workflow of starting a product and later continuing from
memory without manual packet management, see
[docs/zero-to-continuation.md](docs/zero-to-continuation.md).

## Quick start

```sh
# Install or upgrade from PyPI.
python3 -m pip install --upgrade remaind

# Check the installed version.
remaind --version

# Run the 5-minute deterministic proof path.
remaind proof

# Optional: prove a real local DeepSeek can continue from a Remaind packet.
export REMAIND_OPENAI_BASE_URL=http://127.0.0.1:11442/v1
export REMAIND_OPENAI_MODEL=deepseek-v4-flash
export REMAIND_OPENAI_API_KEY="$(cat /path/to/local-deepseek-api-key)"
export REMAIND_OPENAI_API=completions
remaind demo agent-continuity --force

# Start the guided workflow after the proof passes.
remaind launch

# Or bootstrap a .context/ in the current directory manually.
remaind init

# Inspect what's there.
remaind validate
remaind status
remaind doctor

# One front-door startup: product/workspace lookup first, model/runtime
# selection next, then ask, paste, file, resume, handover, or empty mode.
remaind launch

# 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

# Start a guided Codex -> DeepSeek transfer with capture + receiver guide.
remaind transfer start \
  --from-model "Codex" \
  --to-model "local DeepSeek" \
  --target codex \
  --completed "wired retry route" \
  --decision "use provider + event_id for idempotency" \
  --next-step "run focused retry tests"

# After the receiving model writes its final output, capture it back.
remaind transfer finish \
  --from-model "local DeepSeek" \
  --from-file deepseek-output.md

# Register a huge local Markdown/text file, then retrieve exact evidence
# by search or line range without loading the whole file into the prompt.
remaind large-doc ingest /path/to/large-archive.md
remaind large-doc search /path/to/large-archive.md "final synthesis phrase" --verify
remaind large-doc slice /path/to/large-archive.md --start 33557 --end 33565 --verify

# Or execute a task against a huge local prompt/document in one command.
remaind run /path/to/huge-prompt.md "solve this task"

# 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.

```python
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)   # uses your local model if one is running

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

**Full walkthrough — the agent-loop integration, how compaction uses your
local model, the resume-injection pattern, and an exception reference — is
in [docs/integration.md](docs/integration.md).**

Adversarial memory behavior is documented in
[docs/adversarial-hardening.md](docs/adversarial-hardening.md).
Executable product proofs are documented in
[docs/benchmarks.md](docs/benchmarks.md).
The fastest public trust path is `remaind proof`: it creates isolated local
proof workspaces, verifies the Basic/offline plan boundary, runs the
project-continuity benchmark, runs the sovereign beyond-context benchmark,
verifies universal capture/handoff export, and prints one PASS/FAIL report with
the claims each check proves. `remaind proof --secure`
adds the secure workspace lock/unlock, encrypted core-storage, and
encrypted-handoff proof. The proof contract is documented in
[docs/proofs/golden-proof-path.md](docs/proofs/golden-proof-path.md).
The finance policy-exception continuity walkthrough is in
[docs/proofs/finance-policy-exception-continuity.md](docs/proofs/finance-policy-exception-continuity.md).

## Large Local Documents

Agent terminals can read files that agent UI file-readers often refuse to load.
Remaind exposes that as a product feature through `remaind large-doc`.
For the guided terminal workflow, `remaind launch` activates memory, verifies
runtime readiness, and only then asks whether to ask a project question, paste
text, load a file, prepare a resume packet, or start empty:

```sh
remaind launch
remaind launch --project "Rutwais"
remaind launch --path ./my-project --input ask --task "status of Rutwais?"
remaind context inspect --project "Rutwais" "what is the current plan and next step?"
remaind launch --path ./my-project --input file --file /absolute/path/to/huge.md
cat /absolute/path/to/huge.md | remaind launch --path ./my-project --input paste --task "solve this task"
```

In an interactive terminal, `remaind launch` opens a session home first. Use the
Up/Down keys and Enter to choose `New session`, `Open by name or topic`,
`Continue last project`, one of the last 10 recent projects, the current folder,
or a manual path. New sessions get their own timestamped workspace folder by
default, so each product session can keep a dedicated `.context/`.

When you choose `Open by name or topic`, type something like `Rutwais` or
`local llm test`. Remaind builds a workspace-memory index from existing
`.context` folders, then searches folder names, paths, handover, state, recent
packets, and recent events. The lookup tolerates hyphens, close spellings, and
related topic phrases such as `merchant refunds`. Only strong matches open
automatically; weak or ambiguous matches are shown as selectable full paths. If
nothing matches, launch offers to create a new session named after what you
typed, browse existing projects, or try another name. Remaind remembers safe
project-name aliases, but ignores generic shell phrases such as `which remaind`
so Recent Projects stay readable.

`Activate memory and return to terminal` and `Prepare resume packet` are
memory-only flows and do not probe, load, or call a model. Model/runtime
selection is delayed until you choose a mode that needs generation, such as
asking Remaind memory, loading a file, pasting text, or updating handover. The
empty terminal path reports `Runtime: not selected for this mode`; that means
model selection was skipped for speed, not that DeepSeek or another configured
model is unavailable. The model picker lists detected local
Ollama/OpenAI-compatible models before the readiness check. If a selected model
fails its smoke test, launch lets you choose another detected model before
offering packet-only fallback. File mode lists registered large documents and
nearby Markdown/text/JSON-style files. Use the visible `Back` row to return to
the previous step without restarting.
Press `m` for a manual path when the path you need is not listed. The
continuation picker also includes `Update handover.md`; in terminal selectors,
`Ctrl+H` activates that handover update shortcut.

For the closest thing to always-on memory, install the daemon shell hook:

```sh
eval "$(remaind daemon shell-init --shell zsh)"
```

Or install it once:

```sh
remaind daemon install-shell-hook --shell zsh
```

The hook keeps the active-memory prompt hint and records privacy-safe work
signals after each command: sanitized command preview, exit code, rough
duration, current folder, git branch, and changed files. It never records
terminal output. Meaningful developer commands and failed developer commands
update the product status and product-plan reconciliation automatically, so
Remaind can recover the latest activity and map it back to the active plan even
if the terminal closes unexpectedly.
On zsh, the hook also routes plain-English questions typed at an active-memory
prompt through `remaind ask` before zsh treats them as shell commands. For
example, after opening a workspace, `is the repo cloned locally?` is converted
to a Remaind memory question instead of producing a shell glob error. The last
workspace opened through `remaind launch` becomes the active memory target for
these follow-up questions.

After choosing a workspace, the default path is normal terminal/LLM usage:
press Enter and choose `Activate memory and return to terminal` to activate
memory and return control without putting Remaind between you and the model. You
are back in your shell after this path; plain natural-language questions should
be asked through your normal LLM interface or with `remaind ask "your question"`.
Type memory-specific questions such as `what is the next step?`,
`latest progress and TODOs`, or `ask what did we finish last?` when you want
Remaind to build context and answer from memory. Type `prepare memory packet`,
`update handover`, `paste`, `file`, or a document path to route to those
explicit Remaind workflows. Generic LLM prompts typed at this point are saved as
lightweight launch notes and returned to the normal session instead of being
processed before the LLM.

On MOSAI/DeepSeek installs that include the profile switcher, launch also shows
a `DeepSeek mode` picker before model selection. Choose `Turbo - faster, 65k
context` for day-to-day speed or `Stable - larger, 131k context` when the task
needs the widest local context. The switch restarts the supervised DeepSeek
server, updates Remaind's packet/context settings, and then continues through
the normal readiness checks.

If you do not have a local LLM, choose
`Connect API model (OpenAI-compatible)` from the model picker. Remaind asks for
the service's `/v1` endpoint, accepts an optional bearer token for the current
launch only, lists the API models it can discover, and then runs the same
readiness check before any project question or large prompt is processed. The
API key is not written into `.context/`.

Ask Remaind memory mode runs your question against the current resume packet.
It is intentionally a memory-QA path, not the default chat path. If you choose
`Prepare resume packet only`, interactive launch offers to ask a question from
that packet before returning to the shell, so natural text like
`status of Rutwais?` is captured by Remaind instead of being interpreted as a
terminal command. Follow-up questions in the same launch carry the current
terminal conversation forward, so corrections like “the model is already
working” are treated as newer than stale packet failures. If you ask for recent
packets, launch includes the latest run packets and answer notes as evidence for
that question. More generally, memory questions now include a workspace packet
inventory so the model knows which prior packets and answer notes exist. Normal
questions include recent packet context; requests for `all packets` or
`full history` load every packet and answer note that fits the fixed
question-source budget and clearly list anything omitted.
For speed, launch answers operational checks such as “is Remaind active?” and
terminal-command inputs such as `gh repo clone ...` locally instead of sending
them through the model. Model-backed memory questions use a launch-specific
timeout cap, `REMAIND_LAUNCH_ASK_MODEL_TIMEOUT` (default `45` seconds), so a
slow or stalled local model cannot leave the interactive chat waiting for the
general model timeout.
The same context-engineering trace is now part of all model-facing context:
resume packets, `remaind run` retrieval-planner prompts and evidence packets,
handover compaction prompts, and deep-document compaction prompts all label
selected evidence by authority, freshness, and budget status before a model
sees it.
When your goal is to resume work, use normal language such as
`continue working on this project`, `what is the next step?`, or
`latest progress and TODOs`. Remaind treats that as a continuation request:
the LLM receives the resume packet plus budgeted packet-library context and is
asked to reconstruct the product scope, active plan, latest progress, blockers,
next TODOs, and the immediate implementation step before it answers.
On activation, Remaind also seeds a durable product-status record when one does
not exist yet. That seed is intentionally conservative: it says memory is
active, no product progress or blocker has been captured yet, and the next
answer should use the workspace plan, handover, and packet evidence to choose
the real next step. Remaind also writes
`.context/active/plan_reconciliation.md` and
`.context/active/plan_reconciliation.json`, which turn loaded plan/status files
plus saved activity into a plain-English map of completed, blocked,
in-progress, pending, and planned work. Continuation answers use that
reconciliation before old packets or old model answers.

For advanced local setups, each detected model is available in normal mode and
YOLO mode, for example `deepseek-v4-flash` and
`deepseek-v4-flash (YOLO / skips model test)`. That lets you choose the model
without typing or thinking about provider endpoints. The `Model not listed`
entry is only for unusual cases where a local model exists but does not appear
in discovery. The rest of readiness still runs, and the launch report labels
the model as unverified. The same path is available in scripts with:

```sh
remaind launch --runtime ollama --model any-local-model:latest --yolo-model
```

Paste mode is intentionally available after readiness. It captures pasted or
stdin text into `.context/artifacts/launch-pastes/` and routes that captured
file through the same large-prompt packet path, so a long terminal session can
start naturally without pushing raw text into the model before memory is active.

For the shortest one-shot workflow, `remaind run FILE "TASK"` combines
initialization, ingest, retrieval, packet writing, local-model execution, and
event logging:

```sh
remaind run /absolute/path/to/huge-prompt.md "solve this task"
remaind run /absolute/path/to/huge-prompt.md "solve this task" --deep-compact
```

The source file stays on disk. Remaind writes a compact evidence packet to
`.context/active/run_packet.md`, writes the model response to
`.context/active/run_answer.md`, and records the task in the append-only event
log.

For million-token class files, add `--deep-compact`. Remaind first checkpoints
a baseline packet, then uses the selected local model to extract source-linked
chunk summaries, validates quote and line bounds, quarantines hostile derived
content, reduces the evidence, and expands exact raw lines for answer-affecting
claims. If a local model request stalls or is interrupted, the baseline packet
and pending answer file already exist, so the run does not leave you empty
handed. Lenient runs with unrecovered chunks report `partial`; `strict` mode
fails on any unrecovered chunk.

Slower local runtimes can use smaller extraction chunks for faster checkpoint
cadence:

```sh
remaind run /absolute/path/to/huge-prompt.md "solve this task" --deep-compact --deep-compact-chunk-tokens 2000
```

The chunk target is part of the deep-compaction cache key. Reuse with
`--reuse-deep-compact` only picks up an interrupted or completed run with the
same source, task, model, prompts, settings, and chunk target. The default
target is `8000` tokens; lower it for timeout-prone local runtimes and raise it
only for stable long-context models.

Deep-compaction artifacts live under
`.context/large-docs/<doc_id>/deep-compactions/<run_id>/` and can be inspected
or pruned without copying the raw source into `.context/`:

```sh
remaind large-doc inspect /absolute/path/to/huge-prompt.md
remaind large-doc prune-deep-compactions --doc /absolute/path/to/huge-prompt.md --keep-latest 2
```

Use it when a source file is too large for a direct `@file` read, too large for
one prompt, or too important to summarize without exact evidence:

```sh
remaind large-doc ingest /absolute/path/to/archive.md
remaind large-doc search /absolute/path/to/archive.md "needle phrase" --verify --json
remaind large-doc slice /absolute/path/to/archive.md --start 1000 --end 1040 --verify --json
```

`ingest` writes a durable local manifest under `.context/large-docs/`, appends
a source-linked event, and stores a searchable memory pointer with the exact
commands future agents should use. The source document is **not** copied into
`.context/`; it remains at its original local path. `search`, `slice`, `head`,
and `tail` stream the file through the terminal and return line-numbered
evidence.

Use `--verify` when retrieving from an ingested document. Remaind compares the
current file against the stored manifest and stops if the source has changed.
If you launch an agent UI and type raw `@/path/to/huge.md`, that UI may still
hit its own file-reader size limit; the Remaind path is the `large-doc`
command, not direct `@file` loading.

This does not give a model one-shot full attention over every token. It gives
the agent a reliable local way to retrieve the relevant slices from documents
bigger than its live context or file-reader limit, then reason over those
slices with the normal Remaind resume and validation loop.

## 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)
├── large-docs/           # runtime manifests for huge local documents
├── 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            # 13 default secret patterns
│   ├── tools.yaml                # mechanical risk flags
│   └── migrations/{state,events}/ future schema migration hooks
└── (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 init --secure` | Bootstrap and seal a secure workspace: sensitive core files are encrypted at rest and plaintext handoff export is disabled |
| `remaind unlock --ttl 30m` | Decrypt sealed core files and open a bounded secure-handoff window |
| `remaind lock` | Reseal sensitive core files and close the secure-handoff window |
| `remaind key rotate` | Re-encrypt locked secure workspace storage with a new passphrase |
| `remaind validate` | Walk the v1 checklist (structure, schemas, event hash chain, SQLite) |
| `remaind status [--json]` | State + thresholds + event counts + compaction recommendation |
| `remaind plan [--json]` | Show the local Basic/Pro entitlement boundary; Phase 1 has no network, billing, or license checks |
| `remaind doctor [--json]` | Read-only health check: validation, status readability, and local model runtime detection |
| `remaind monitor [--json]` | Scheduler-friendly health and alert check; exits non-zero on invalid context, urgent compaction, or unhealthy deep-compaction runs |
| `remaind launch [--project NAME] [--input ask\|paste\|file\|resume\|handover\|empty]` | Primary startup flow: open session home, create or activate project memory, delay runtime checks until generation is needed, then route into ask/paste/file/resume/handover/empty mode |
| `remaind ask [--project NAME] "QUESTION"` | Ask the active workspace memory in plain language |
| `remaind chat [--project NAME]` | Stay inside an interactive Remaind memory chat |
| `remaind context inspect [--project NAME] "QUESTION"` | Print the engineered memory context Remaind would send for a question, without calling a model |
| `remaind context checkpoint --active-tokens N --context-window M` | Model-agnostic context guard: create a fresh handoff/reset prompt when any agent reaches the 70% window guard |
| `remaind compact [--no-model]` | Run the compaction pipeline, gated by structured validation. Uses a local model automatically (Ollama auto-detected; OpenAI-compatible servers via `REMAIND_OPENAI_BASE_URL`), else the rule-based fallback. Use `--no-model` to force the deterministic fallback when a local runtime is slow or unhealthy |
| `remaind resume [--next-tool TOOL]` | Build a resume packet; consult the resume gate |
| `remaind capture --from-file OUTPUT.md` | Capture completed model/agent work into events, state, progress, and structured memory |
| `remaind handoff --to-model MODEL --target codex` | Build a universal cross-model handoff bundle with markdown packet, manifest, and adapter files |
| `remaind transfer start --from-model Codex --to-model "local DeepSeek"` | Build a guided cross-LLM transfer with receiver instructions, universal handoff bundle, manifest, adapters, and finish command |
| `remaind transfer finish --from-model "local DeepSeek" --from-file OUTPUT.md` | Capture the receiving model's completed work back into the same local continuity memory |
| `remaind context checkpoint --agent qwen-code --model qwen --active-tokens 92000 --context-window 131072` | Create the same tiny fast-start handoff for any agent/model with token telemetry; DeepCode is optional |
| `remaind context checkpoint --telemetry-text "status: processing · tokens: 115904" --context-window 131072 --agent gemma-terminal --model gemma-4` | Parse a plain terminal status line and create the same fast task-slice checkpoint without a custom adapter |
| `remaind context watch --telemetry-file agent-status.log --context-window 131072 --agent gemma-terminal` | Watch a generic agent status/log file and trigger the fast checkpoint automatically when the 70% guard is crossed |
| `remaind context start` | Print the smallest safe startup prompt for the latest handoff so the next agent reads the task slice first |
| `remaind context warm --path PATH` | Precompute the tiny zero-load startup cache so the next Hermes/model session starts from a hot file read |
| `remaind hooks status --agent deepcode --require-auto` | Search local hook surfaces and verify that an external agent has a real automatic checkpoint hook; exits non-zero instead of claiming unsupported automation |
| `remaind hooks install --agent deepcode --context-window 65536` | Install and verify the native DeepCode checkpoint hook |
| `remaind hooks probe --agent codex --require-discovered` | Safely prove a discovered external hook contract can generate a checkpoint handoff using synthetic token telemetry |
| `remaind hermes activate --workspace PATH [--launch-profile dev]` | Install Hermes plugins, select Remaind, and set the Hermes CLI/TUI low-noise toolset profile, with a config backup |
| `remaind hermes activate --workspace PATH --verify --verify-report-dir reports` | Activate Hermes, run installed-readiness, low-noise UX, and local proof-suite verification, then save Markdown/JSON evidence |
| `remaind hermes deactivate` | Remove Remaind's Hermes config selections with a backup, leaving unrelated settings intact |
| `remaind hermes restore --backup PATH` | Restore Hermes config from a Remaind-created backup, preserving the current config first |
| `remaind hermes status --require-ready` | Check Hermes plugin files, config, and workspace readiness before opening Hermes Desktop |
| `remaind hermes speed --checkpoint-smoke --require-ready` | Measure Hermes startup context size/time and write a real fast checkpoint/reset smoke proof |
| `remaind hermes ux-proof --require-ready [--low-noise-profile minimal\|file\|terminal\|dev]` | Verify the recommended low-noise Hermes/Remaind launch path, prompt-size warnings, profile-specific tool budget, and checkpoint/reset proof |
| `remaind hermes verify --force --report-dir reports` | Verify installed Hermes readiness, low-noise UX readiness, and the local Remaind/Hermes proof suite, then save Markdown/JSON evidence |
| `remaind hermes support-bundle --out reports/hermes --force --zip` | Write a redacted Hermes/Remaind support bundle with status, UX proof, proof reports, config evidence, checksums, and an optional zip archive |
| `remaind hermes support-bundle-check --bundle reports/hermes.zip` | Verify a support bundle archive, sidecar hash, manifest checksums, UX proof evidence, and privacy flags before trusting it |
| `remaind hermes install` | Install or refresh Remaind's Hermes memory-provider and context-engine plugins under `$HERMES_HOME` |
| `remaind deepcode install-hook --context-window 65536` | Install a project-local DeepCode notify hook that uses the universal context guard against DeepCode's local token counter |
| `remaind deepcode checkpoint --context-window 65536` | Inspect DeepCode's local session index and prepare a reset prompt/handoff when the latest session is near the model window |
| `remaind handoff --secure --ttl 30m` | Encrypt the exported handoff bundle, write a secure manifest, and remove plaintext export files from the handoff folder |
| `remaind handoff-decrypt --bundle secure_handoff.remaind.enc --out DIR` | Decrypt a secure handoff bundle into an explicit folder for the receiving model or harness |
| `remaind rollback --to <ts>` | Restore derived files from history; raw log untouched |
| `remaind memory plan\|block\|decision\|promote\|changed ...` | Record plan updates, blockers, decisions, durable memories, and changes through the append-only memory layer |
| `remaind run FILE "TASK"` | Execute a task against a huge local prompt/document through a compact evidence packet and the selected local or OpenAI-compatible model runtime |
| `remaind run FILE "TASK" --deep-compact` | Run hierarchical local-model document compaction before answering; artifacts are resumable and source-linked |
| `remaind large-doc ...` | Index, search, and slice huge local documents through terminal-backed access without copying the source file into `.context/` |
| `remaind demo finance-handoff` | Run a product-facing finance handoff demo through a real local `.context/` ledger and write a private customer validation artifact pack |
| `remaind demo agent-continuity` | Prove a loopback local DeepSeek model can continue a software-agent task from a Remaind resume packet and cite source event evidence |
| `remaind proof` | Run the golden clean-install proof path: plan boundary, continuity, sovereign beyond-context, handoff, hot-packet, context-engine, context-matrix, and agent-hook checks |
| `remaind proof --secure` | Add secure workspace checks: plaintext export rejection, unlock, encrypted storage, encrypted handoff, decrypt, cleanup, key rotation, and lock |
| `remaind bench sovereign` | Run the beyond-context product proof in an isolated benchmark workspace |
| `remaind bench context-engine --force` | Prove strict fast-context budgets, active brief quality, stale-state boundaries, and forced-reset checkpoint behavior |
| `remaind bench context-matrix --force` | Prove model-agnostic 70% checkpoints across DeepSeek, Qwen, Gemma-style, and 200k-class context windows |
| `remaind bench hermes-suite --force` | Run the local Hermes proof battery: lifecycle, acceptance, quality, comparison, and long-run reset loop |
| `remaind bench hermes-live` | Verify the installed Hermes config, plugin files, provider tools, context engine, workspace resolution, and reset telemetry |
| `remaind bench hermes-compare --force` | Compare Remaind against no-memory/raw-transcript/built-in baselines and inventory installed Hermes providers |
| `remaind bench hermes-quality --force` | Prove Hermes receives current source-linked Remaind task context under stale/noisy long-history pressure |
| `remaind bench hermes-lifecycle --force` | Prove Hermes activate, deactivate, restore, dry-run, backup, and managed-file cleanup behavior |
| `remaind bench hermes-longrun --force` | Prove repeated Hermes/Remaind reset cycles beyond a 500k-token job load |
| `remaind bench finance-handoff` | Run the Oz-aligned finance policy-exception continuity proof |
| `remaind bench finance-handoff --write-fixture-template customer.json` | Write a customer-validation fixture template for private design-partner workflow labels |
| `remaind bench finance-handoff --fixture customer.json` | Run the deterministic finance proof against customer-provided reviewed-memory cases and gold labels |

Hermes activation defaults to `memory.remaind.tool_mode: lean`, which exposes
only `remaind_context` as a model-visible Remaind tool while hooks and the
context engine handle captures, checkpoints, and resets. Activation also writes
`memory.remaind.launch_profile: dev` and narrows `platform_toolsets.cli` to the
low-noise development profile (`terminal,file,memory,context_engine`) so Hermes
CLI/TUI sessions do not start with the broad default tool surface. Use
`remaind hermes activate --launch-profile preserve` when you intentionally want
to keep an existing Hermes toolset configuration. Use `tool_mode: full` only
for explicit advanced/manual Remaind tool testing. For Hermes launch budgeting,
`ux-proof` supports low-noise profiles: `minimal` (memory only), `file` (file
operations), `terminal` (shell operations), and `dev` (terminal + file).

Plain telemetry accepts status text such as `tokens: 115.9k/131k`,
`tokens: 115904 of 131072`, or `status: processing · tokens: 115904`. If the
status line reports only the current token count, pass `--context-window` or set
`REMAIND_CONTEXT_WINDOW` so Remaind can evaluate the 70% guard honestly.

## Plan Boundary

Remaind ships as one local-first CLI. In Phase 1, `remaind plan` reports the
offline entitlement boundary:

- Basic is the default and works offline forever.
- Basic includes local `.context`, local memory, resume packets, handoff
  read/export, basic continuity proof, secure local storage basics, and
  readable/exportable user data.
- Pro gates are prepared locally for advanced workflows, governed/reviewed
  memory, finance/compliance proof packs, richer reports, model integration
  automation, and future sync/backups/team features.
- No project content, memory, packets, briefs, handoffs, workspace names, or
  source notes are sent to any server in Phase 1.

Doctrine: **Pro unlocks advanced workflows, not ownership of user memory.**

The repo includes a runnable design-partner starter fixture at
`docs/fixtures/finance-policy-exception-design-partner-template.json`. It is a
schema and evaluator starter, not a real customer validation result.

The Sovereign Memory starter also includes `make adversarial`, a deterministic
proof for prompt-injection, fake tool-result, phase-2 poison archives,
superseded-memory, and poisoned compaction-output handling.

It also includes `make bench`, which generates a large source archive and
proves fresh-process final-phrase retrieval, a single distant contradiction,
revocation pressure, source links, and adversarial quarantine.

For a terminal-visible local model A/B demo, the starter kit includes
`make proof-2m`: direct raw 2M prompt versus compact sovereign-memory resume
packet against the configured local model.

For model compatibility work, the starter kit includes `make model-test`.
Run it without model generation for a fast deterministic Remaind check:

```sh
make model-test MODEL_TEST_ARGS="--skip-model --force"
```

Run it against explicit local models:

```sh
make model-test MODEL_TEST_ARGS="--models qwen3.6-35b-a3b-full:latest,gpt-oss-120b-fast:latest --force"
```

## 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) |
| 13 | Doctor/readiness checks + release proofs |
| 14 | Trust labels + tamper-evident event chain |

## 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.

## Versioning

Remaind is in the `0.x` alpha line. The public API exported from
`remaind.__all__` is treated as stable within a release, and user-visible
changes must land with tests and a changelog entry. Breaking changes remain
possible before `1.0`; `1.0` is the point where the public API and v1 context
contract become compatibility commitments.

## License Posture

Remaind is proprietary and all rights are reserved. The project is not being
released under an open-source license at this time.

## 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 follow instructions embedded inside retrieved memories, handovers, raw
  excerpts, archives, or tool output.
- Do not accept compaction without structured validation.
- Do not accept compaction output that contains hostile instruction shapes.
- Do not mutate files on resume if the resume packet is contradictory or unsafe.

## Tests

```sh
.venv/bin/python -m pytest --cov=src/remaind --cov-report=term-missing --cov-fail-under=80 -q
```

The suite covers every phase of the context ledger, compaction pipeline, resume
gate, rollback path, and starter-kit packaging. Adding a feature? Add a test.

## Security

Current-tree secret scanning and product guardrails run in CI. Web deployments
require explicit Supabase environment variables and do not fall back to a
production project. Docs/marketing surfaces must not hard-code volatile test
counts. See [docs/security.md](docs/security.md) for rotation, history
scanning, and local hardening guidance. Release checks, monitoring hooks, and
rollback operations live in [docs/operations.md](docs/operations.md). Web setup
details live in [web/README.md](web/README.md).

## License

Proprietary — all rights reserved. Remaind is not yet released under an
open-source license; see [LICENSE](LICENSE).
