Metadata-Version: 2.4
Name: provalume
Version: 0.1.1
Summary: Verified, git-aware memory for autonomous software agents—tracking what worked, what failed, what is currently true, and the evidence that proved it.
Project-URL: Homepage, https://github.com/andyyaro/provalume
Project-URL: Repository, https://github.com/andyyaro/provalume
Project-URL: Issues, https://github.com/andyyaro/provalume/issues
Project-URL: Changelog, https://github.com/andyyaro/provalume/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/andyyaro/provalume/tree/main/docs
Author: Andy Yaro
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-memory,developer-tools,local-first,mcp,multi-agent,provenance,sqlite,verification
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: rich>=13.9
Requires-Dist: typer<1,>=0.15
Provides-Extra: fastembed
Requires-Dist: fastembed>=0.5; extra == 'fastembed'
Requires-Dist: numpy>=1.26; extra == 'fastembed'
Provides-Extra: model2vec
Requires-Dist: model2vec>=0.8; extra == 'model2vec'
Requires-Dist: numpy>=1.26; extra == 'model2vec'
Provides-Extra: signatures
Requires-Dist: cryptography>=42; extra == 'signatures'
Provides-Extra: vectors
Requires-Dist: numpy>=1.26; extra == 'vectors'
Description-Content-Type: text/markdown

# Provalume

**Facts your agents proved, not things they said.**

Your coding agents rediscover the same broken approach every week. One agent
learns that the integration suite deadlocks under `-n auto`; the next agent tries
it again on Tuesday. A fix gets rejected in review on a branch that is later
abandoned, and six weeks on something still "remembers" it as how the project
works.

Provalume is a local memory system that only trusts what was **proved**. A
verification command that passed. A reviewer who was not the author. A commit that
actually landed. Everything else is stored, labelled, and kept out of the way.

```
$ provalume preflight --command "pytest -n auto tests/integration"

  A similar approach failed previously.

  Previous attempt      pytest -n auto tests/integration   (2 occurrences)
  Failure evidence      exit 1 — deadlock in db fixture teardown
  What later worked     pytest -p no:xdist tests/integration  ✓ verified
  Applicability         current at this commit
  Provenance            failed in attempt 01JZ…9F, confirmed by reviewer-2
  Trust state           verified
```

Nothing in that output is a model's opinion. Every line traces to a recorded
event with a hash.

---

## Why this exists

Agent memory is a crowded field, and most of it stores what an agent *said*.
Provalume stores what a deterministic process *proved*, and keeps the evidence
attached:

| | Most memory systems | Provalume |
|---|---|---|
| Who writes memory | An LLM extracts or summarises | Deterministic functions of structured events |
| Why a fact is trusted | It was stored | A named rule promoted it, on listed evidence |
| Failed attempts | Discarded as noise | A first-class category — the most useful thing it holds |
| Rejected branch work | Indistinguishable from landed fact | Terminal state; can never become project truth |
| "Is this still true?" | Unanswerable | Bi-temporal validity, checked against the commit you asked about |
| Same input twice | May store different things | Byte-identical, every time |

**Provalume needs no LLM, no API key, and no network.** Three pure-Python
dependencies. One SQLite file in your project.

## Install

```sh
uv tool install provalume     # or: pipx install provalume, pip install provalume
```

## 60-second quickstart

```sh
provalume demo
```

Runs a complete scenario in a temporary directory — no API key, no agent CLI, no
network — using the real storage, policy, and retrieval code. It shows an agent
failing, the gotcha being recorded, a second agent being warned, a fix being
verified and independently reviewed, a procedure being promoted, a stale fact
being superseded, and a later query retrieving it all with provenance.

Then, in a real project:

```sh
provalume init                       # creates .provalume/
provalume doctor                     # checks environment, FTS5, permissions
provalume recall "database migration" --explain
provalume audit                      # prove the chain, projections, and pragmas hold
```

From Python:

```python
from provalume import Provalume

pv = Provalume.open(project_id="my-project")

pv.record_verification(
    command="pytest -n auto tests/integration",
    passed=False,
    excerpt="deadlock in db fixture teardown",
    branch="feature/parallel-tests",
)

warning = pv.preflight(command="pytest -n auto tests/integration")
if warning.matched:
    print(warning.summary)

digest = pv.recall("integration tests", branch="main").digest(char_budget=2000)
print(digest.text)      # always within budget, always banner-first
```

## How trust works

Five rungs, and you cannot skip one:

```
quarantined ──▶ observed ──▶ verified ──▶ reviewed ──▶ integrated
   agent          reported     a command    a non-author    it landed
   prose          from a run   returned     approved it     in history
```

Plus three terminal states — `invalidated`, `superseded`, `rejected` — which are
retained as history and never promoted.

Three rules do most of the work:

1. **Agents propose; they never promote.** The party making a claim is never the
   party granting it trust. This is what defeats a confident, well-written,
   entirely false statement — no heuristic can catch that, and it does not need
   to, because a lie does not generate evidence.
2. **Verification is not always enough.** A test passing in one worktree proves
   something happened *there*. To be served as a current project fact, a semantic
   record needs a commit that actually landed.
3. **Every promotion names its rule and its evidence.** `provalume explain <id>`
   tells you which rule fired and which event IDs it relied on. Refusals are
   recorded too.

Full specification: [`docs/security/TRUST_MODEL.md`](docs/security/TRUST_MODEL.md).

## What it remembers

| Category | Example |
|---|---|
| **Gotcha** | `pytest -n auto` deadlocks in the db fixture — and what worked instead |
| **Procedural** | The exact release command that passed verification |
| **Semantic** | This project uses `uv`, not `pip` — superseded, not overwritten, when it changed |
| **Decision** | We chose Typer over Click, and here is what we rejected and why |
| **Episodic** | Attempt 3 failed, attempt 4 passed after removing the fixture scope |
| **Performance** | Which agent profile actually succeeds at migration tasks |

## Being explicit

Because a memory system asking for your trust should say what it is.

**Deterministic, always:** every memory write, promotion, retrieval, ranking, and
export. The same inputs produce byte-identical output. `provalume rebuild`
reconstructs every projection from the journal.

**Never uses an LLM:** anything on the canonical path. There is no extraction
step, no summarisation step, and no model in the write path. This is the
constraint the whole design is built around
([ADR-0007](docs/adr/ADR-0007-deterministic-writers.md)).

**Optional, off by default:** vector retrieval (`provalume[vectors]`),
cryptographic signatures (`provalume[signatures]`). Both marked experimental in
0.1.0. Retrieval works fully without either.

**Leaves your machine only when you:** run `provalume export`, or install an
embedder extra, which downloads a model once and then runs locally. There is **no
telemetry, no analytics, no crash reporting, no update check, and no account.**
`tests/security/test_no_network.py` asserts there is no network code at all.

**Trusted:** records promoted by a named rule on deterministic evidence.
**Quarantined:** anything an agent asserted, and anything that tripped a poisoning
heuristic. Retrievable, always labelled, never presented as fact.

## What it does not do

- It does not defend against a malicious local operator. Tampering with
  `.provalume/provalume.db` is **detectable** via `provalume audit`, not
  preventable.
- It cannot force a model to honour the untrusted-data banner on a digest. That
  residual risk is real and is documented rather than glossed over
  ([`MEMORY_POISONING.md`](docs/security/MEMORY_POISONING.md) §2.4).
- It has no multi-user access control. Single-operator; use filesystem permissions.
- It has no hard deletion. The journal is append-only, so it is a poor fit for
  data under a deletion requirement.
- It does not do cross-project or global memory in 0.1.0 — deliberately, because
  cross-project leakage is the one Critical-rated confidentiality threat
  ([ADR-0016](docs/adr/ADR-0016-global-memory-deferral.md)).
- **It has not been dogfooded on production runs yet.** Its schema comes from the
  literature, a competitor review, and a replayable eval harness — not from mined
  production failure frequencies. That is the largest known weakness of 0.1.0 and
  it is stated in [`LIMITATIONS.md`](docs/reference/LIMITATIONS.md) rather than
  buried.

No benchmark superiority claim is published anywhere in this repository. The eval
harness compares Provalume against Provalume, on its own fixtures, and says so.

## Works with

- **Any MCP client** — `provalume serve-mcp`. Read tools plus `propose`. There is
  no promotion, invalidation, or delete tool on the MCP surface: not disabled,
  *absent*, and a test asserts it stays that way
  ([ADR-0012](docs/adr/ADR-0012-mcp-permissions.md)).
- **Orkestra** — reference integration, structured event ingestion and digest
  injection ([`docs/integration/ORKESTRA.md`](docs/integration/ORKESTRA.md)).
- **Anything else** — the Python SDK and a generic adapter.

## Documentation

| | |
|---|---|
| [Quickstart](docs/QUICKSTART.md) | 60 seconds to a useful memory |
| [Architecture](docs/architecture/OVERVIEW.md) | How the layers fit |
| [Trust model](docs/security/TRUST_MODEL.md) | What "verified" means, precisely |
| [Threat model](docs/security/THREAT_MODEL.md) | 26 threats and their controls |
| [Memory poisoning](docs/security/MEMORY_POISONING.md) | The attack this exists to survive |
| [Privacy model](docs/security/PRIVACY_MODEL.md) | What is stored, what can leave |
| [Data model](docs/reference/DATA_MODEL.md) | Every field, and why |
| [Retrieval](docs/reference/RETRIEVAL.md) | The ranking policy, with all constants |
| [Preflight](docs/reference/PREFLIGHT.md) | Failure signatures and the warning gate |
| [JSONL spec](docs/reference/JSONL.md) | Interchange format and merge semantics |
| [MCP guide](docs/reference/MCP.md) | Tools, permissions, bounds |
| [Benchmarks](docs/reference/BENCHMARKS.md) | Methodology and what is not claimed |
| [Limitations](docs/reference/LIMITATIONS.md) | Read this before adopting |
| [ADRs](docs/adr/) | 18 decisions, with what each cost |

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). Apache-2.0, no CLA, DCO optional.

Six changes require security review before they can land, because each would
re-open the poisoning channel — an LLM in the write path, exposing promotion to
MCP, letting payload influence its own trust state, cross-project promotion
without human approval, making vectors the authorisation gate, or serving
semantic records as truth without landed history.

## License

[Apache-2.0](LICENSE). See [`NOTICE`](NOTICE) for attribution of the ideas
Provalume borrowed — no code from any other project was copied.
