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.

Check Agent Skills (agentskills.io)

Point memproof skills at a directory of skills/<name>/SKILL.md to validate the agentskills.io contract: kebab-case names that match their directory, description limits, optional-field types and unknown keys. Add --registry skills.json to diff the disk against a declared skill registry in both directions.

memproof skills ./skills --registry config/skills.json --fail-on high

Install

uv tool install memproof
# or
pip install memproof

# before the PyPI release, install straight from GitHub:
uv tool install git+https://github.com/hsys123/memproof

Use

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:

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

What it checks (v0.1)

Example

# 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.

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

python -m pytest
ruff check .
mypy memproof

License: MIT.