Metadata-Version: 2.4
Name: remaind
Version: 0.1.2
Summary: Durable context for long-running agents.
Project-URL: Homepage, https://github.com/magpiexyz-lab/Remaind
Project-URL: Repository, https://github.com/magpiexyz-lab/Remaind
Author: Magpie Labs
License: MIT
License-File: LICENSE
Keywords: agents,compaction,context,handover,ledger
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: jsonschema>=4.18
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: anthropic>=0.40; 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'
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == 'llm'
Description-Content-Type: text/markdown

# Remaind

[![tests](https://github.com/magpiexyz-lab/Remaind/actions/workflows/ci.yml/badge.svg)](https://github.com/magpiexyz-lab/Remaind/actions/workflows/ci.yml)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](#)
[![license](https://img.shields.io/badge/License-MIT-blue.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
git clone https://github.com/magpiexyz-lab/Remaind.git
cd Remaind
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

Requires Python ≥ 3.11.

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

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

MIT — see [LICENSE](LICENSE).
