Metadata-Version: 2.5
Name: context-motilis
Version: 0.1.0
Summary: A local-first runtime for resumable context.
Project-URL: Homepage, https://github.com/cetatec/context-motilis
Project-URL: Source, https://github.com/cetatec/context-motilis
Author: cetatec
License-Expression: MIT
License-File: LICENSE
Keywords: context,local-first,mcp,provenance,runtime
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: mcp==2.2.0
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: typer<1,>=0.16
Description-Content-Type: text/markdown

# context-motilis

A local-first runtime for resumable context.

A **context** is a durable unit — a matter, later an entity or an archive — that
can be suspended for months and resumed by a person or by any model, with its
evidence, history, accepted state, commitments in both directions, and dates
intact. The runtime captures inputs durably before it processes them, keeps time
and fires reminders without a model, authorizes changes by their consequences,
records every version with its provenance, and produces a deterministic **brief**
that answers "where were we?" without rereading history.

The model interprets and proposes; the runtime preserves, schedules, and
authorizes. A dormant context owns no running process; the shared runtime reacts
to indexed dates and events on its behalf.

Tools provide capabilities. context-motilis provides continuity.

## Status

**Stage 1, one gate from complete.** Tasks 1 through 8 of §10 are merged: the
store, contexts, the scheduler, capture, the brief, export and import, the CLI
host with `motilis demo`, and the MCP host with `motilis serve`. All thirty
stage-1 acceptance cases are real tests, the thirtieth being the one stage 1
had been missing: capture a document, restart, and get it back -- in the brief,
by search, and by `why` -- still marked as something that arrived rather than
something you said ([#74](https://github.com/cetatec/context-motilis/issues/74),
[ADR 0018](docs/adr/0018-a-source-is-in-the-body-from-stage-1.md)).

What is still absent: a real assistant build recorded in
[`docs/hosts.md`](docs/hosts.md) -- the second clause of checkpoint 1 (§1.3),
run by the owner and the gate before stage 2 -- and `v0.1.0`. The release
pipeline itself is proven: `0.0.1` is on PyPI.

Two things a new user should know before typing. The CLI is the human's host:
`note`, `commit`, `remind`, `capture`, `open`, `ask`, `why`, `search`, `due`
and `tick` work on a clean checkout with no model anywhere. `say` needs a
model, this repository holds none (§11.1), and in stage 1 free text is
interpreted through MCP, where the model is the client; on the CLI `say`
replays a recorded reading and refuses plainly without one. The demo is the way
to see the whole loop:

```
uvx --from git+https://github.com/cetatec/context-motilis motilis demo
```

[`docs/roadmap.md`](docs/roadmap.md) says what each milestone gives you and
what stands between here and it.

## The brief

[`docs/brief-v7.md`](docs/brief-v7.md) is the controlling specification, committed
verbatim. Every `§` reference in this repository, in its tests and in its commit
messages points into it. It is authoritative: where it and any other document in
this repository disagree, it governs. Revisions supersede one another by number,
and v7 is the one in force.

[`docs/roadmap.md`](docs/roadmap.md) lays §7's stages out as milestones a person
can review by hand, with the §8 rows that evidence each; it decides nothing.

## Install

From PyPI -- `0.0.1`, a pre-alpha whose job was to prove the pipeline:

```
uvx --from context-motilis motilis version
# or
uv tool install context-motilis && motilis version
```

From `main`, with access to the repository:

```
uvx --from git+https://github.com/cetatec/context-motilis motilis version
```

The package name and the executable name differ; `--from` is not optional.

## Develop

Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/).

```
uv sync --group dev
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest
```

Enable the hygiene hook once per clone, so household data and store files cannot
be committed:

```
git config core.hooksPath .githooks
```

The same check runs in CI, so a bypassed hook still fails the build.

## What is never in this repository

Household data, real names, real documents, `.sqlite` files, `artifacts/` and
`cultures/`. CI runs with no model, no network and no secrets.

## Layout

```
src/context_motilis/   the runtime and its hosts
tests/invariants/      one property test per invariant of §3
tests/acceptance/      the §8 acceptance suite, by stable name
docs/brief-v7.md       the controlling specification; every § points here
docs/adr/              decisions the brief does not settle, and why
docs/hosts.md          pinned protocol revision, SDK, and tested client builds
docs/roadmap.md        the milestones: what each gives you, and what is left
fixtures/              generated fixtures only
tools/                 repository tooling, not part of the package
```

## Licence

MIT. See [`LICENSE`](LICENSE), and [ADR 0001](docs/adr/0001-mit-licence.md) for
why. Reuse is meant to be straightforward, commercial reuse included.

## Two sentences

*Runtime:* A context is a durable boundary that can be suspended and
independently resumed. It retains evidence and history, may carry commitments
and deterministic behavior, and exposes a bounded brief to whichever human or
model attends to it next.

*Development principle:* What exactly must survive this kill? A feature that
cannot name what survives its kill is not added.
