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_for_agent`, `open_default_in_memory`, `open_with_oracle_for_agent`, `open_with_oracle_in_memory`, `SqlitePersistenceStore`
`mempill-postgres`	docs.rs/mempill-postgres	`PostgresEngine` alias, `open_postgres`, `open_postgres_with_oracle`, `PostgresPersistenceStore`, `PoolConfig`

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_for_agent(base_dir, agent_id)`, `mempill.open_in_memory()`	`mempill.open_oracle_for_agent(base_dir, agent_id, oracle)`, `mempill.open_oracle_in_memory(oracle)`
Rust (SQLite)	`open_default_for_agent(base_dir, agent_id)`, `open_default_in_memory()`	`open_with_oracle_for_agent(base_dir, agent_id, 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)`

SQLite constructors are per-agent as of 0.4.0 — the database file is derived automatically as base_dir/agent_{agent_id}.db. See Changelog.

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
`query_subject`	`QuerySubjectRequest`	`QuerySubjectResponse`	Read the resolved belief for every predicate known about a subject (available as of 0.3.0)
`query_history` / `history()`	subject-line identifiers	`History` (Rust) / `HistoryResult` (Python)	Full ordered claim timeline for a `(subject, predicate)` line — `Current`/`Superseded` status per entry, each with honest per-endpoint date granularity (0.4.0; see below)
`reconcile`	`ReconcileRequest`	`ReconcileResponse`	Re-run conflict resolution
`query_audit`	`AuditQueryRequest`	`AuditQueryResponse`	Read immutable ledger

Ergonomic tier (`remember` / `recall`)

Both the Rust facade (mempill) and the Python wheel expose a simplified additive API on top of the full DTO surface above — remember(engine, ..., RememberOptions) and recall(engine, ...) — for callers who don’t need explicit provenance/confidence/cardinality control. See the Quickstart (Rust) and Quickstart (Python) for full usage; the full DTO API (ingest_claim / query_memory) remains available for advanced provenance control.

QuerySubjectRequest / QuerySubjectResponse fields

Field	Python key	Rust field	Type	Required
Agent identity	`"agent_id"`	`agent_id`	`str` / `AgentId`	Yes
Subject	`"subject"`	`subject`	`str`	Yes
Valid-time as-of	`"valid_at"`	`valid_at`	ISO-8601 string / `Option<DateTime<Utc>>`	No
Tx-time as-of	`"as_of_tx_time"`	`as_of_tx_time`	ISO-8601 string / `Option<DateTime<Utc>>`	No

Response is a list of per-predicate entries (Python) / QuerySubjectResponse { entries } (Rust), sorted by predicate. Each entry: predicate, value, status, valid_from_display, valid_until_display, provenance, claim_ref, conf.

HistoryEntry fields (0.4.0)

Each entry in query_history / history()’s timeline: claim_ref, value, valid_from, valid_until, status (Current | Superseded), provenance, value_confidence, plus (0.4.0) valid_from_granularity and valid_until_granularity (raw DateGranularity tags). The Python wheel additionally pre-renders valid_from_display / valid_until_display (same rendering rules as query_memory / query_subject).

valid_until_granularity is a derived value — valid_until itself is bounded by the successor claim in the timeline (supersession), not stored on the entry, so the honest granularity to report is the successor’s start_granularity (or None when the successor’s ordering key falls back to transaction_time). See Changelog: Date granularity on history() for the full rule and rationale.

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`	Non-conflicting `ModelDerived` claim — committed down-weighted, ineligible to overturn an existing belief until anchored
`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`	Belief-overturning accepted; the prior claim is bounded and retained in history
`Invalidated`	A validity assertion marks the claim as no-longer-true; retained in history
`Reinstated`	Valid-time window reopened by a new external/first-hand assertion (non-terminal)
`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