Crate mempill 

mempill

Temporally-correct memory for AI agents.

This crate is a thin facade that re-exports the public API of mempill-core and makes the persistence adapters available behind feature flags so a downstream user only needs:

# Cargo.toml
[dependencies]
mempill = "0.2"                          # default features = ["sqlite"]
# or:
mempill = { version = "0.2", features = ["postgres"] }

Quick start (SQLite, default)

Most code only needs two calls — remember and recall — with sane defaults:

use mempill::{open_default_in_memory, remember, recall, RememberOptions};

let engine = open_default_in_memory()?;

// Remember a fact — 3 args + sane defaults. Dates are lenient: "2020",
// "2020-03", "2020-03-01", or full RFC3339 all work.
remember(&engine, "my-agent", "user", "city", "Berlin",
         RememberOptions::default().valid_from("2020")).await?;

// Two conflicting facts are NEVER silently overwritten — they surface as Contested.
remember(&engine, "my-agent", "acme:ceo", "held_by", "Alice", RememberOptions::default()).await?;
remember(&engine, "my-agent", "acme:ceo", "held_by", "Bob",   RememberOptions::default()).await?;

// Recall — a flat result; Contested is explicit (can't be mistaken for "no memory").
let r = recall(&engine, "my-agent", "acme:ceo", "held_by").await?;
if r.is_contested() {
    println!("contested: {:?}", r.candidates);
} else {
    println!("ceo = {:?}", r.as_str());
}

Need full control — provenance channels, cardinality, criticality, explicit confidence, or derivation lineage? Drop to the full claim API (engine::IngestClaimRequest / engine::QueryMemoryRequest); see the type reference. The ergonomic tier is additive — the rigorous core is unchanged.

Feature flags

Feature	Default	Description
sqlite	yes	Enables mempill_sqlite — embedded SQLite adapter (topology-a)
postgres	no	Enables mempill_postgres — shared PostgreSQL adapter (topology-b)

Both features can be enabled simultaneously (e.g., for tests that verify both backends).

Architecture

The dependency direction is one-way:

mempill (this facade)
  ├── mempill-core   (engine, port traits, use-cases)
  ├── mempill-sqlite (feature = "sqlite")
  └── mempill-postgres (feature = "postgres")

The engine core has zero dependency on either adapter crate.

Re-exports

pub use ergonomic::remember;

pub use ergonomic::recall;

pub use ergonomic::history;

pub use ergonomic::RememberOptions;

pub use ergonomic::RememberReceipt;

pub use ergonomic::RecallResult;

pub use ergonomic::ContestCandidate;

pub use ergonomic::BeliefDetail;

pub use ergonomic::History;

pub use ergonomic::MempillDxError;

pub use ergonomic::CanIngestClaim;

pub use ergonomic::CanQueryMemory;

pub use ergonomic::CanQueryHistory;

pub use ergonomic::IngestClaimRequestExt;

pub use ergonomic::IngestClaimRequestBuilder;

Modules

date

Lenient date normalization for the Tier-1 / Tier-2 ergonomic surface.

engine

Core engine surface for power users and adapter authors.

ergonomic

Tier-1 ergonomic API — remember + recall

postgres

PostgreSQL persistence adapter (feature = "postgres").

sqlite

SQLite persistence adapter (feature = "sqlite").

types

Domain value types shared across the mempill engine.

Structs

AgentId

Opaque stable identifier for a memory agent. Primary partition key everywhere.

ClaimRef

Opaque, stable, immutable identity of a committed claim. Minted once at injection time.

Confidence

Two separate confidence scores: one for the value itself, one for the valid-time extraction.

EngineHandle

The sole public async entry point for mempill.

Fact

The atomic asserted statement: a (subject, predicate, value) triple.

HistoryEntry

Re-export core’s HistoryEntry so callers only need use mempill::HistoryEntry. One slot in the history timeline for a subject-line.

IngestClaimRequest

Public write request. Maps to domain Claim at the application boundary.

QueryMemoryRequest

Request to retrieve the current belief for a (subject, predicate) subject-line.

SubjectLineRef

Compound key identifying the (agent_id, subject, predicate) subject-line.

ValidTime

Valid-time interval — fallible and host-extracted (confidence-tagged). When start/end are None, belief ordering falls back to TransactionTime.

Enums

BeliefStatus

Resolved belief status for a subject-line at read time.

Cardinality

Cardinality of the (subject, predicate) subject-line — always a caller proposal; the gate decides.

Criticality

Criticality class — reflects the importance of the claim, distinct from its freshness (currency).

CurrencyState

Derived currency state at read time.

Disposition

The 12-state disposition model.

ExternalKind

Sub-channel for External provenance.

HistoryEntryStatus

Re-export core’s HistoryEntryStatus so callers can match on Current/Superseded. History entry status for query_history — whether the claim is the current belief or was superseded by a later one.

Marker

Active signal flags on a BeliefProjection at read time.

MemError

Top-level error type for the mempill engine. Every invariant violation surfaces as a typed variant here — never silently swallowed.

ProvenanceLabel

The provenance channel assigned to every write — required, typed, and immutable.

Functions

open_default

Open a file-backed sqlite::DefaultEngine at the given path.

open_default_in_memory

Open an in-memory sqlite::DefaultEngine.