Metadata-Version: 2.4
Name: mnemoir-provenance
Version: 0.2.0
Summary: Source-grounded memory for agents that learn over time.
Author: Mnemoir Provenance contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/sayyied/mnemoir-provenance
Project-URL: Repository, https://github.com/sayyied/mnemoir-provenance
Project-URL: Issues, https://github.com/sayyied/mnemoir-provenance/issues
Project-URL: Security, https://github.com/sayyied/mnemoir-provenance/blob/main/SECURITY.md
Keywords: agent-memory,local-first,provenance,sqlite,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == "release"
Requires-Dist: pytest<9,>=8; extra == "release"
Provides-Extra: external-benchmark
Requires-Dist: beir>=2.2; extra == "external-benchmark"
Requires-Dist: mteb>=2.15; extra == "external-benchmark"
Requires-Dist: ir_datasets>=0.5.11; extra == "external-benchmark"
Provides-Extra: hermes
Requires-Dist: hermes-agent>=0.18.2; extra == "hermes"
Dynamic: license-file

# Mnemoir Provenance

**Source-grounded memory for agents that learn over time.**

Mnemoir Provenance (pronounced “nem-wahr”) is a local-first, source-grounded memory core for agents, assistants, and multi-agent systems. It preserves citations, correction history, source coverage, and recoverable maintenance receipts so memory remains inspectable as it evolves.

Mnemoir Provenance is an independent open-source project and is not affiliated with other projects using similar names.

## Why it is different

- Cited recall reports which sources were searched and which were missing or degraded.
- Evidence, proposals, review, and durable writes are separate operations.
- Revisions, supersession, tombstones, and rollback preserve history.
- Overflow maintenance is preconditioned, authorized, auditable, and recoverable.
- The core works through Python or a JSON CLI; Hermes is an optional reference adapter.

## Quick start

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install .
export MNEMOIR_DB="$PWD/demo.sqlite"
mnemoir ingest --limit 5
mnemoir recall "source grounded memory" --limit 3
```

The response is JSON. A healthy result includes `cited_results` and `source_coverage`; insufficient evidence returns an explicit empty or degraded state instead of an uncited fallback.

## Mental model

```text
sources -> raw events -> evidence -> proposals -> versioned memories
   |                                               |
   +------ cited recall + coverage + receipts -----+
```

Canonical state is SQLite. Markdown/wiki output is derived and never becomes canonical merely because it is readable.

## Integration paths

- [Python API](docs/guides/integrate-python.md)
- [CLI JSON](docs/guides/integrate-cli-json.md)
- [Generic harness](docs/guides/integrate-generic-harness.md)
- [Hermes reference adapter](docs/guides/integrate-hermes.md)
- [Working-memory adapters](docs/guides/write-working-memory-adapter.md)

## Documentation

Start at [docs/index.md](docs/index.md). Security boundaries are in [SECURITY.md](SECURITY.md) and [the threat model](docs/operations/threat-model.md). Overflow and writeback are explained in [the operations guide](docs/guides/operate-overflow.md).

## Boundaries

This project is local/self-hosted software, not a hosted service. Installation does not grant access to arbitrary files, enable live writeback, start a network service, configure a host, or promote memory automatically. Citations identify evidence; they do not guarantee truth. Ranking heat affects attention, not authority.

## License

MIT. See [LICENSE](LICENSE).
