Metadata-Version: 2.4
Name: memoryos-governance
Version: 1.0.2
Summary: Local-first semantic memory governance toolkit for AI-human collaboration.
Author: Dale Eyles
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/daz-rad/MemoryOS
Project-URL: Repository, https://github.com/daz-rad/MemoryOS
Project-URL: Issues, https://github.com/daz-rad/MemoryOS/issues
Project-URL: Releases, https://github.com/daz-rad/MemoryOS/releases
Keywords: ai,governance,local-first,memory,semantic-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: jsonschema<5,>=4.22
Provides-Extra: dev
Requires-Dist: build<2,>=1.2.1; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.4.8; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

# Tenetra

**Evidence-governed continuity infrastructure for persistent human-AI systems.**

Tenetra is the public and umbrella-platform identity of the project historically and technically identified as MemoryOS. Existing imports under `memoryos`, the `memoryos` CLI command and `memoryos.cli:main` entry point, schemas, configuration keys, runtime artifacts, and historical evidence remain compatible and unchanged during the initial brand transition.

Tenetra is an independent project and is not affiliated with or endorsed by BAI-LAB/MemoryOS or its authors.

This repository now contains the accepted Leg 1 baseline plus a v1 local-completion layer. v1 remains inside the canonical assisted-mode boundary: deterministic local tooling, explicit proposal artifacts, archive preservation, rollback inspection, and no implicit or external live runtime mutation.

## Scope lock

- Python only
- Local-first
- Deterministic and inspectable outputs
- Markdown, JSON, and JSONL-compatible artifact strategy
- No TypeScript
- No database
- No vector store
- No runtime network dependency
- No UI
- No autonomous deletion
- No implicit or external live runtime mutation
- No hidden Leg 2 automation

## Installation

Install from a local checkout:

```bash
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
memoryos --version
memoryos self-test --pretty
```

After public PyPI publication is independently verified, use the public distribution name:

```bash
python -m pip install memoryos-governance
python -c "import memoryos; print(memoryos.__file__)"
memoryos --version
memoryos self-test --pretty
```

Current status: `memoryos-governance==1.0.1` is published on PyPI and independently verified from a clean Python 3.11 environment. The `memoryos` PyPI name belongs to another project and is not used here.

Install from a local wheel after building:

```bash
python3.11 -m build
python3.11 -m pip install dist/memoryos_governance-1.0.2-py3-none-any.whl
memoryos --version
memoryos --help
```

The wheel includes the CLI, packaged schemas, and a packaged stage9 smoke-test corpus. When the repository fixture corpus is present, `self-test` validates that source tree. Otherwise it falls back to the packaged smoke-test corpus and installed package scope scan.

Public distribution for this repository uses `memoryos-governance`. The Python import package remains `memoryos`, and the CLI command remains `memoryos`. The PyPI `memoryos` namespace belongs to a different project and is not this repository.

## Documentation map

- [Getting Started](docs/GETTING_STARTED.md): first local install and verification path.
- [CLI Reference](docs/CLI_REFERENCE.md): supported commands and safety defaults.
- [Concepts](docs/CONCEPTS.md): artifact model, local MVP boundary, and integration vocabulary.
- [Safety and Mutation Boundaries](docs/SAFETY_AND_MUTATION_BOUNDARIES.md): dry-run, execute, rollback, and no-mutation rules.
- [Release Notes](docs/RELEASE.md): current release state, GitHub release expectations, and PyPI distribution status.
- [Production Hardening Roadmap](docs/ROADMAP_PRODUCTION_HARDENING.md): remaining production, release, runtime, ledger, and CI/CD work.
- [Production and Commercial Readiness Matrix](docs/PRODUCTION_COMMERCIAL_READINESS.md): current local proof, target-specific evidence needs, and external commercial gates.

## Implemented local v1 capabilities

- Canonical schemas for memory items, archives, governance kernels, dependency graphs, compression decisions, runtime states, and validation reports.
- Archive engine that preserves `original_memory_text` before any classification or proposal work.
- Deterministic policy-driven classifier with normalized 0-5 scoring metadata and score evidence.
- Governance kernel extraction with one-to-one kernels plus additive fused-kernel proposals.
- Dependency graph builder with preservation, derivation, support, shared-tag, classification, rollback, and replacement-proposal edge semantics.
- Runtime builder that excludes fused proposals from active runtime until human approval.
- Local batch pipeline for directory-based memory item processing.
- ConversationHarvester fixture ingestion and one-command MVP runner that emit source evidence, candidate/proposal packets, generated-state bridge fixtures, and validation reports under `runtime/preflight_candidates/`.
- Runtime integration command that dry-runs by default, validates a runtime state, and writes an accepted runtime target only with explicit `--execute`.
- Live local promotion command that dry-runs by default and can append/create explicit repo-local MemoryOS runtime and MemoryLedgerOps ledger targets only with `--execute`, source hashes, manifests, idempotency checks, and rollback evidence.
- Assisted-use trial runner for operator-supplied local transcript, note, or handoff files under `runtime/preflight_candidates/memoryos_assisted_trials/`.
- Assisted-use trial batch runner for repo-local documentation and note directories under `runtime/preflight_candidates/memoryos_assisted_trials_batch/`.
- Assisted-use batch review pack summarizer that compresses a generated batch into operator review artifacts under `runtime/preflight_candidates/memoryos_assisted_trials_batch/BATCH_REVIEW_PACK/`.
- Rollback/recovery inspection for archive preservation and rollback pointer integrity.
- Scope guardrail scanner for forbidden v1 runtime components.
- Workspace hygiene audit for tracked edits, untracked files, and ignored residue.
- Local MVP workflow registry with `workflow status`, `workflow validate`, and `workflow next` routing, plus `workflow prove-core-stack` for executable, two-run, local-only acceptance of MemoryOS, ConversationHarvester, Axiom, and DaleOps. NeuroSweep remains optional downstream context and is not a core-stack completion gate.
- Bootstrap provenance guard that requires explicit acknowledgement before regeneration helpers can run.
- Unified CLI with `--version`, `self-test`, `process-batch`, `inspect-rollback`, `scope-audit`, `workspace-audit`, and `workflow`.
- Stage 9 baseline examples and v1 completion examples.

## Quick verification

```bash
pytest -q --disable-warnings
PYTHONPATH=. python3 -m memoryos.cli validate-all \
  --memory-items examples/stage9/memory_items \
  --archives examples/stage9/archives \
  --kernels examples/stage9/kernels \
  --graphs examples/stage9/graphs \
  --decisions examples/stage9/decisions \
  --runtime-states examples/stage9/runtime_states \
  --pretty
PYTHONPATH=. python3 -m memoryos.cli validate-all \
  --memory-items examples/v1/memory_items \
  --archives examples/v1/output/archives \
  --kernels examples/v1/output/kernels \
  --graphs examples/v1/output/graphs \
  --decisions examples/v1/output/decisions \
  --runtime-states examples/v1/output/runtime_states \
  --pretty
PYTHONPATH=. python3 -m memoryos.cli inspect-rollback \
  --archives examples/v1/output/archives \
  --decisions examples/v1/output/decisions \
  --pretty
PYTHONPATH=. python3 -m memoryos.cli scope-audit --root . --pretty
PYTHONPATH=. python3 -m memoryos.cli self-test --pretty
```

## Batch processing

```bash
PYTHONPATH=. python3 -m memoryos.cli process-batch \
  --memory-items examples/v1/memory_items \
  --output-dir /tmp/memoryos-v1-output \
  --pretty
```

This writes archives, decisions, kernels, graph, runtime state, and a batch manifest into the output directory. It does not mutate the input memory items, delete anything, or alter live runtime memory.

## Runtime Integration

Runtime integration accepts one schema-valid `runtime_state` JSON file and an explicit accepted runtime target path. It defaults to dry-run mode and writes nothing unless `--execute` is supplied:

```bash
PYTHONPATH=. python3 -m memoryos.cli integrate-runtime \
  --source-runtime examples/v1/output/runtime_states/runtime-v1.json \
  --target-runtime /tmp/memoryos-runtime/accepted-runtime.json \
  --pretty
```

Execute mode writes the accepted runtime file, a manifest, a validation report, and rollback instructions:

```bash
PYTHONPATH=. python3 -m memoryos.cli integrate-runtime \
  --source-runtime examples/v1/output/runtime_states/runtime-v1.json \
  --target-runtime /tmp/memoryos-runtime/accepted-runtime.json \
  --execute \
  --pretty
```

Existing targets are refused unless `--overwrite` is provided. The integration boundary records source and target SHA-256 hashes, validates the target runtime state, writes no network state, performs no deletion, and does not mutate the source runtime file.

Validate or inspect an integration manifest:

```bash
PYTHONPATH=. python3 -m memoryos.cli validate-runtime-integration \
  --manifest /tmp/memoryos-runtime/accepted-runtime.json.integration_manifest.json \
  --pretty

PYTHONPATH=. python3 -m memoryos.cli inspect-runtime-integration \
  --manifest /tmp/memoryos-runtime/accepted-runtime.json.integration_manifest.json \
  --pretty
```

## MemoryLedgerOps Integration

MemoryLedgerOps integration accepts ConversationHarvester task proposal JSONL, or a generated package directory containing `07_TASK_CANDIDATES.jsonl`, and appends accepted entries to an explicit ledger JSONL path. It defaults to dry-run and writes nothing unless `--execute` is supplied:

```bash
PYTHONPATH=. python3 -m memoryos.cli integrate-ledger \
  --package-dir runtime/preflight_candidates/memoryos_mvp_sample/ConversationHarvester_Prototype_Result_20260614_150816 \
  --ledger /tmp/memoryos-ledger/memoryledgerops-ledger.jsonl \
  --pretty
```

Execute mode appends ledger entries and writes a manifest, approval record, and rollback record:

```bash
PYTHONPATH=. python3 -m memoryos.cli integrate-ledger \
  --package-dir runtime/preflight_candidates/memoryos_mvp_sample/ConversationHarvester_Prototype_Result_20260614_150816 \
  --ledger /tmp/memoryos-ledger/memoryledgerops-ledger.jsonl \
  --execute \
  --pretty
```

Duplicate entry IDs are refused by default. Exact replay can be confirmed with `--idempotent`; conflicting duplicates fail closed. The command never rewrites source evidence, never deletes ledger data, and does not infer a canonical ledger path. The operator must provide the ledger target explicitly.

Validate or inspect ledger evidence:

```bash
PYTHONPATH=. python3 -m memoryos.cli validate-ledger-integration \
  --manifest /tmp/memoryos-ledger/memoryledgerops-ledger.jsonl.integration_manifest.json \
  --pretty

PYTHONPATH=. python3 -m memoryos.cli inspect-ledger \
  --ledger /tmp/memoryos-ledger/memoryledgerops-ledger.jsonl \
  --pretty
```

## ConversationHarvester MVP loop

The preferred single-command local bridge loop is:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli run-mvp-loop \
  --output-root runtime/preflight_candidates/memoryos_mvp_loop \
  --pretty
```

It creates two validated package trees, one under `fixture/` for the source fixture ingest and one under `sample/` for the synthetic sample emission. If you want the individual steps instead, run them directly:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli ingest-file \
  --input tests/fixtures/conversation_harvester/single_transcript.md \
  --output-root runtime/preflight_candidates/memoryos_mvp_loop \
  --pretty

/opt/homebrew/bin/python3.11 -m memoryos.cli emit-sample \
  --output-root runtime/preflight_candidates/memoryos_mvp_sample \
  --pretty
```

Each run creates a timestamped package directory containing:

- source evidence in `01_SOURCE_MANIFEST.jsonl` and `01_SOURCE_MANIFEST.csv`
- MemoryOS candidate packets in `06_CLAIM_CANDIDATES.jsonl` and `08_MEMORY_CANDIDATES.jsonl`
- MemoryLedgerOps proposal routing in `07_TASK_CANDIDATES.jsonl`
- generated-state bridge proof in `10_RUNTIME_EXPORT_BRIDGE_FIXTURE.json`
- validator-backed proof in `11_VALIDATION_REPORT.md`
- no-mutation and rollback evidence in `12_NO_MUTATION_MANIFEST.json`, `14_MUTATION_LEDGER.json`, and `15_ROLLBACK_NOTES.md`

The generated package is self-validating and remains local-only. If your default `python3` is already 3.11+, you can substitute it for the explicit interpreter path above.

### Bridge package proof

When you already have a validated ConversationHarvester package, you can turn it into the source-linked bridge package used for MemoryOS and MemoryLedgerOps proof:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli build-bridge-package \
  --source-package-dir runtime/preflight_candidates/memoryos_mvp_sample/<validated-package-dir> \
  --output-root runtime/preflight_candidates/memoryos_bridge_package \
  --pretty

/opt/homebrew/bin/python3.11 -m memoryos.cli validate-bridge-package \
  --package-dir runtime/preflight_candidates/memoryos_bridge_package/<bridge-package-dir> \
  --pretty
```

The bridge package keeps explicit source linkage, generated-state-only authority, no-mutation evidence, and validator-backed package metadata. It does not mutate live runtime or ledger state.

The assisted-use trial runner accepts an operator-supplied local file and writes a separate trial manifest plus validated package tree:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli run-assisted-trial \
  --input tests/fixtures/conversation_harvester/assisted_trial_handoff.md \
  --output-root runtime/preflight_candidates/memoryos_assisted_trials \
  --pretty
```

The trial directory contains `ASSISTED_TRIAL_MANIFEST.json` with the input hash, generated package path, and local-preflight-only mutation boundary.

The batch-assisted trial runner scans a local directory, keeps only supported text-like files, and runs the assisted trial flow for each selected file:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli run-assisted-trial-batch \
  --input-dir docs/build_reports \
  --output-root runtime/preflight_candidates/memoryos_assisted_trials_batch \
  --pretty
```

The batch directory contains `ASSISTED_TRIAL_BATCH_MANIFEST.json` with the selected trial reports, skipped files, and batch-level validation counts.

The batch review pack summarizer reads an existing assisted-trial batch output directory and writes a compact review bundle:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli summarize-assisted-trial-batch \
  --batch-dir runtime/preflight_candidates/memoryos_assisted_trials_batch/MemoryOS_Assisted_Trial_Batch_20260615_103018 \
  --pretty
```

The review pack is written under `BATCH_REVIEW_PACK/<review_id>/` and includes markdown, JSON, CSV, and a review manifest for operator triage.

The one-command batch loop runs batch generation and review-pack generation together, then writes a single local MVP status manifest:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli run-assisted-trial-batch-loop \
  --input-dir docs/build_reports \
  --output-root runtime/preflight_candidates/memoryos_assisted_trials_batch_loop \
  --pretty
```

The loop directory contains `ASSISTED_TRIAL_BATCH_LOOP_MANIFEST.json` alongside the batch and review-pack outputs.

The local MVP proof command runs the MVP loop and batch loop together, then writes a single proof manifest:

```bash
/opt/homebrew/bin/python3.11 -m memoryos.cli prove-local-mvp \
  --input-dir docs/build_reports \
  --output-root runtime/preflight_candidates/memoryos_local_mvp_proof \
  --pretty
```

The proof directory contains `LOCAL_MVP_PROOF_MANIFEST.json`, `LOCAL_MVP_PROOF_SUMMARY.md`, and `LOCAL_MVP_COMMAND_RESULTS.json`.

## Canonical source

The canonical source of truth is `docs/MemoryOS_Complete_Build_Plan_v2.md`. The v1 implementation follows its assisted-mode boundary: human approval is required for destructive, compressive, or live runtime operations.

## Completion status

MemoryOS is locally complete to the current canonical v1 boundary and now includes explicit, operator-targeted runtime and MemoryLedgerOps integration commands. It is not globally production-complete: the PyPI `memoryos` namespace remains blocked for this project, runtime and ledger writes still require explicit local targets, and Leg 2+ automation remains outside the v1 boundary.

## ConversationHarvester Phase 1 baseline

ConversationHarvester Phase 1 is a separate repo-local scaffold for the local-first evidence-capture lane. It is intentionally narrower than the MemoryOS v1 implementation:

- local CLI first
- no browser access
- no network access
- no live transcript ingestion
- no downstream authority decisions
- JSONL as the canonical bundle format

Phase 1 files live under `src/conversation_harvester`, `schemas/`, `docs/`, `tests/fixtures/`, and `scripts/`. The scaffold CLI exposes help and version output, but it refuses browser, network, and live integration modes until later phases authorize them.

Useful entry points:

- `PYTHONPATH=src python3 -m conversation_harvester.cli --help`
- `PYTHONPATH=src python3 -m conversation_harvester.cli --version`
- `docs/PHASE1_SCOPE_FREEZE.md`
- `docs/NO_MUTATION_BOUNDARY.md`
- `docs/NO_FAKE_COMPLETION_BOUNDARY.md`
