Metadata-Version: 2.4
Name: contmemo
Version: 0.2.0
Summary: Memory custodian agent for the Cont Hive ecosystem (offline, air-gapped). Memory only — recipes live in contrecipe.
Author: Sertan
Keywords: cont-hive,pdna,memory,offline,agent,air-gapped
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# contmemo

<!-- v2 | 2026-05-03 | scope: memory only; recipes live in sibling contrecipe -->

> Memory custodian agent for the **Cont Hive** ecosystem.
> Offline, air-gapped, single-writer, deterministic-first.

`contmemo` is the kâtip ("scribe") of the Cont Hive. It is the **only** module
that writes to Cont's memory. Every other agent — including `cont` itself —
submits **proposals**; `contmemo` evaluates them and decides what gets persisted.

**Scope is memory only.** Recipe sanity, lifecycle, and evolution are the
responsibility of the sibling agent `contrecipe`. The two are peers, not nested.

See [`docs/architecture.md`](docs/architecture.md) for the full design.

## Status

**Sprint M1 — Skeleton.** Repo structure, CLI parser, test harness.
No runtime behavior yet. Each `core/*.py` module exposes a stub class so
later sprints can fill in their own corner without touching the wiring.

| Sprint | Scope                                    | Status |
| ------ | ---------------------------------------- | ------ |
| M1     | Skeleton                                 | done   |
| M2     | Event log (append-only JSONL + lookup)   | done   |
| M3     | Proposal inbox watcher + deterministic   | done   |
| M4     | Single-writer Cont memory writer         | next   |
| M5     | Light-mode runtime (trace watching)      | —      |
| M6     | Bulk mode + mini-LLM client              | —      |
| M7     | PyPI publish (offline-friendly artifact) | —      |
| M8     | Cont integration (shim layer in `cont`)  | —      |

## Install (dev)

```bash
git clone <repo>
cd contmemo
pip install -e ".[dev]"
pytest
```

## Usage (planned)

```bash
contmemo --watch              # light-mode daemon (Sprint M5)
contmemo --bulk --since "1h"  # one-shot reflection (Sprint M6)
contmemo --report --last 50   # event-log tail (Sprint M2)
```

In M1 these flags parse but exit with `2` and a "not yet implemented" notice
pointing at the responsible sprint.

## Design invariants

These never bend, regardless of sprint:

1. **Single-writer.** Cont memory is written by `contmemo` and nothing else.
2. **Proposal-only.** Cont thinks it writes; it actually submits.
3. **Deterministic before LLM.** Light path has no model. LLM only in bulk.
4. **Append-only event log.** Contmemo's own memory has no LLM in the loop —
   no recursion, no self-summarization.
5. **Air-gapped.** Zero cloud, zero outbound network, zero telemetry.

## License

Private — internal Cont Hive component. Not for redistribution.
