Metadata-Version: 2.4
Name: remaind
Version: 0.4.1
Summary: 100% local memory 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: jsonschema>=4.18
Requires-Dist: pyyaml>=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)

**100% local memory for AI agents working beyond one context window.**

Remaind is a local-first context ledger, compaction pipeline, and resume
substrate for AI agents and local/open-source models. 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: 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 auto-detected; vLLM / llama.cpp / LM Studio via an env var) over
HTTP using only the standard library.

## 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 setup, readiness checks, and launch
- model profiles for Qwen, DeepSeek, GLM, Minimax-style, Llama, and custom local models
- Ollama-backed local compaction/chat
- Qwen Code and built-in console adapters
- a synthetic continuity proof (`make proof`) that verifies fresh-process retrieval
- privacy-safe sharing: each user gets their own `.context/` ledger

Quick start from the repo:

```sh
cd starter-kits/sovereign-memory-starter
make setup SETUP_ARGS="--profile qwen-large --agent qwen-code"
sovereign
```

Console-only local proof:

```sh
cd starter-kits/sovereign-memory-starter
make setup SETUP_ARGS="--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).

## 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 automatically (Ollama auto-detected; OpenAI-compatible servers via `REMAIND_OPENAI_BASE_URL`), 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
```

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.

## License

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