API Reference

mempill’s canonical Rust API reference is auto-generated from source and hosted on docs.rs. The guides in this documentation are the authoritative human-readable reference with full examples and decision rationale.

Rust crates (docs.rs)

The Rust API is documented inline via rustdoc and served on docs.rs. The table below links to each crate’s reference page.

Crate	docs.rs link	Description
`mempill-core`	docs.rs/mempill-core	`EngineHandle`, port traits (`PersistencePort`, `OraclePort`, `VectorPort`), use-cases, DTOs (`IngestClaimRequest`, `QueryMemoryRequest`, `ReconcileRequest`, `AuditQueryRequest`)
`mempill-types`	docs.rs/mempill-types	Domain types: `ProvenanceLabel`, `Disposition`, `Cardinality`, `Confidence`, `Criticality`, `ValidTime`, `BeliefProjection`, `LedgerEntry`, `ClaimRef`, `AgentId`
`mempill-sqlite`	docs.rs/mempill-sqlite	`DefaultEngine` alias, `open_default`, `open_default_in_memory`, `open_with_oracle`, `open_with_oracle_in_memory`, `SqlitePersistenceStore`
`mempill-postgres`	docs.rs/mempill-postgres	`PostgresEngine` alias, `open_postgres`, `open_postgres_with_oracle`, `PostgresPersistenceStore`

To browse docs locally:

cd mempill
cargo doc --workspace --open

Python API

The Python API is documented via PyO3 docstrings in mempill-python/python/mempill/_mempill.pyi and types.py. A pdoc-generated reference is planned at https://api.mempill.dev/python/. Until then, generate it locally:

cd mempill-python
pip install pdoc
pdoc mempill --output-dir docs/python
open docs/python/mempill.html

The type stubs (_mempill.pyi, types.py) are the authoritative type source and are readable directly in any editor.

Key operations at a glance

Constructors

Language	No-oracle	With oracle
Python (SQLite)	`mempill.open(path)`, `mempill.open_in_memory()`	`mempill.open_oracle(path, oracle)`, `mempill.open_oracle_in_memory(oracle)`
Rust (SQLite)	`open_default(path)`, `open_default_in_memory()`	`open_with_oracle(path, arc_oracle)`, `open_with_oracle_in_memory(arc_oracle)`
Rust (Postgres)	`open_postgres(conn_str, None, None, config)`	`open_postgres_with_oracle(conn_str, arc_oracle, None, config)`

Core methods (all engines)

Method	Request type	Response type	Description
`ingest_claim`	`IngestClaimRequest`	`IngestClaimResponse`	Write a belief claim
`query_memory`	`QueryMemoryRequest`	`QueryMemoryResponse`	Read canonical belief
`reconcile`	`ReconcileRequest`	`ReconcileResponse`	Re-run conflict resolution
`query_audit`	`AuditQueryRequest`	`AuditQueryResponse`	Read immutable ledger

Oracle methods (OracleEngine only)

Method	Description
`list_pending_adjudications(agent_id)`	Return pending conflict queue for an agent
`submit_adjudication({handle_id, verdict, evidence_provenance})`	Resolve a pending conflict
`sweep_expired_adjudications()`	Return TTL-expired adjudications to Contested

IngestClaimRequest fields

Field	Python key	Rust field	Type	Required
Agent identity	`"agent_id"`	`agent_id`	`str` / `AgentId`	Yes
Subject	`"subject"`	`subject`	`str`	Yes
Predicate	`"predicate"`	`predicate`	`str`	Yes
Value	`"value"`	`value`	any JSON / `serde_json::Value`	Yes
Provenance	`"provenance"`	`provenance`	dict or `ProvenanceLabel`	Yes
Cardinality	`"cardinality"`	`cardinality`	`"Functional"` / `"SetValued"` / `"Unknown"`	Yes
Valid time	`"valid_time"`	`valid_time`	dict with `start`, `end`, `valid_time_confidence` / `Option<ValidTime>`	No
Confidence	`"confidence"`	`confidence`	`{value_confidence, valid_time_confidence}` / `Confidence`	Yes
Criticality	`"criticality"`	`criticality`	`"Low"` / `"Medium"` / `"High"` / `"Critical"`	Yes
Derived from	`"derived_from"`	`derived_from`	`list[str]` / `Vec<ClaimRef>`	Yes (empty ok)

IngestClaimResponse fields

Field	Python key	Rust field	Description
Claim reference	`"claim_ref"`	`claim_ref`	UUID of the written claim
Disposition	`"disposition"`	`disposition`	One of the 12-state model values
Contested with	`"contested_with"`	`contested_with`	UUIDs of conflicting claims (empty unless Contested/PendingConflict)

Disposition values (12-state model)

Value	Meaning
`CommittedCheap`	Fast-path commit — external provenance, no conflict
`CommittedInferred`	Committed after reconciliation
`Contested`	Conflict; both values preserved; no winner
`QueuedForAdjudication`	Oracle wired; conflict queued for resolution
`PendingConflict`	Conflict detected; challenger parked (oracle said Deny)
`PendingReview`	Flagged for review before commit
`PendingLowConfidence`	Held pending due to low confidence
`Superseded`	Superseded by a newer valid-time-successor claim
`Invalidated`	Explicitly invalidated by adjudication
`Reinstated`	Reinstated after a Deny verdict was overturned
`Quarantined`	Blocked by Amplification Guard (RecallReEntry echo)
`Rejected`	Rejected by validation or gate rules

Python exceptions

Exception	Inherits from	Meaning
`MempillError`	`Exception`	Base — catch-all
`ValidationError`	`MempillError`	Bad request shape or domain invariant violation
`NotFoundError`	`MempillError`	Agent, claim, or adjudication handle not found
`ConflictError`	`MempillError`	Write-lock contention — safe to retry
`StorageError`	`MempillError`	Persistence layer failure
`ConfigError`	`MempillError`	Invalid calibration parameter
`InternalError`	`MempillError`	Engine invariant violated — indicates a bug

Guides as the primary reference

The API reference above captures the stable surface. For full usage with examples, edge cases, and decision rationale, consult the guides:

Rust (Advanced) — all field semantics, valid_time, reconcile, audit, oracle constructors
Python (Advanced) — dict shapes, TypedDicts, async, error handling
Writing an Oracle — request_adjudication protocol, submit_adjudication, HumanOracle pattern
Query Patterns — belief shape, Contested handling, AuditQueryRequest
MCP Integration — tool signatures, environment contract, config files
PostgreSQL Backend — open_postgres, connection string, topology-b