Metadata-Version: 2.4
Name: memproof
Version: 0.1.0
Summary: Evidence-first health checks for Markdown knowledge vaults.
Author: memproof contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/hsys123/memproof
Project-URL: Repository, https://github.com/hsys123/memproof
Project-URL: Issues, https://github.com/hsys123/memproof/issues
Keywords: markdown,obsidian,knowledge-base,memory,audit,provenance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Dynamic: license-file

# memproof

Evidence-first health checks for Markdown knowledge vaults.

`memproof` answers one question: **can you prove what your knowledge base claims?**
Every finding carries a `path:line`, the evidence behind it, and a concrete fix.
It is read-only, offline, and deterministic.

## Install

```bash
uv tool install memproof
# or
pip install memproof
```

## Use

```bash
memproof check ~/my-vault
memproof check ~/my-vault --format json --fail-on high
memproof check ~/my-vault --output report.md
```

Exit codes: `0` clean (or below `--fail-on`), `1` findings at/above the threshold, `2` usage/environment error.

Archives often contain frozen snapshots with dead links. Exclude them explicitly:

```bash
memproof check ~/my-vault --exclude 'archive/**' --exclude 'templates/**'
```

## What it checks (v0.1)

| Check | What it catches |
|---|---|
| `frontmatter` | missing/unparseable frontmatter, missing required keys, unknown status, invalid dates |
| `links` | dead wikilinks, ambiguous bare-name targets, duplicate basenames, orphan pages |
| `provenance` | agent-authored notes missing `author` / `sink` / `generated_by` |
| `freshness` | drafts older than 30 days; evergreen pages older than 180 days with no inbound links |
| `structure` | empty sections; memory atoms not registered in their `_index.md` |

## Example

```text
# memproof report — demo-vault
Score: 64/100 · Files: 12 · Links: 18 · Findings: 2 high / 6 medium / 1 low

## High
- [provenance] notes/agent-note.md:1 — agent-authored note missing generated_by
  Evidence: author=agent, sink=agent, generated_by missing.
  Fix: add `generated_by: <tool>` or remove the agent marker.
```

A full generated report is in [`docs/sample-report.md`](docs/sample-report.md).

## Roadmap

- **v0.1** — five vault checks (current).
- **v0.2** — archive profile, fold/derived checks.
- **v0.3** — `memproof skills`: capability contracts and with/without evaluation.

## Design principles

- **Read-only**: never edits the vault, no network access, no LLM calls.
- **Evidence-first**: every finding points to a line; no aggregate-only claims.
- **Deterministic**: same vault + same date = same report.
- **Small surface**: five checks, not fifty. Add a check only with a failing fixture.

## Development

```bash
python -m pytest
ruff check .
mypy memproof
```

License: MIT.
