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

**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

```sh
pip install remaind
```

Requires Python ≥ 3.11. **100% local** — two runtime dependencies, no cloud
API, no API key. Model-backed compaction talks to a local model runtime
(Ollama) over HTTP using only the standard library.

## Quick start

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

```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).**

## 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. Uses a local model (Ollama) automatically if one is running, else the rule-based fallback |
| `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

```sh
.venv/bin/python -m pytest -q
```

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

## License

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