Skip to content
mempill

Examples

The primary examples live in the mempill-demo repository, a separate project that depends on the mempill Python wheel and shows two real agent front-ends.

mempill-demo repository

Section titled “mempill-demo repository”

Location: mempill-demo/ (separate repo, not the same as the mempill library repo).

The demo is structured as two importable Python packages under src/:

Package Entry point Description
mempill_demo python -m mempill_demo Console REPL agent — human user, text commands
mempill_langgraph python -m mempill_langgraph LangGraph chat agent — Claude or GPT as the AI

Both share the same mempill engine adapter (adapters/memory_mempill.py), the same oracle adapter (adapters/human_oracle.py), and the same /review HITL flow (app/review.py).

Example 1 — Console agent

Section titled “Example 1 — Console agent”

The console agent is a command-line REPL that lets you drive a mempill engine interactively. It demonstrates:

  • Claim ingestion — asserting beliefs about a subject with provenance, cardinality, and confidence.
  • Conflict surfacing — when two Functional claims overlap, the engine returns Contested and the REPL shows both values.
  • Oracle resolution — the /review command lists pending adjudications and lets you choose the winner (challenger, incumbent, abstain, skip).
  • Valid-time succession — ingesting two claims with non-overlapping windows commits both cleanly; query_memory returns the correct value for any point in time.
  • Amplification firewall — the auto-play scenario re-ingests the same value five times with RecallReEntry provenance; the engine quarantines the echoes and the belief is unchanged.
  • Audit ledger — /audit shows every disposition event for the session.

Run the auto-play scenario (no user interaction needed):

Terminal window
cd mempill-demo
uv run python -m mempill_demo --scenario

Run the interactive REPL:

Terminal window
uv run python -m mempill_demo

Example 2 — LangGraph chat agent

Section titled “Example 2 — LangGraph chat agent”

The LangGraph agent wires the mempill engine as a memory backend behind a LangGraph graph. Claude (or another LLM) extracts claim triples from user messages and writes them to mempill via ingest_claim. It demonstrates:

  • Agent memory extraction — the LLM extracts (subject, predicate, value) triples from free-form conversation.
  • Memory recall — the agent queries mempill before responding to ground answers in committed beliefs.
  • Contested surfacing in conversation — when beliefs are Contested, the agent says “I have conflicting information” rather than picking a value silently.
  • Human oracle in chat — the /review command in the LangGraph REPL lets the user resolve pending adjudications without leaving the chat interface.

Run:

Terminal window
cd mempill-demo
export ANTHROPIC_API_KEY=sk-ant-...
uv run python -m mempill_langgraph

Verified end-to-end snippet

Section titled “Verified end-to-end snippet”

The following Python snippet is verified against the live engine (run in the demo venv):

oracle_quickstart.py
import mempill
from mempill import ProvenanceLabel
import uuid


# Step 1: implement the oracle protocol (duck-typed — no imports from mempill needed).
class HumanOracle:
    def request_adjudication(self, agent_id: str, request: dict) -> str:
        return str(uuid.uuid4())  # engine stores the conflict; we just supply a handle


# Step 2: open an oracle-enabled engine.
engine = mempill.open_oracle_in_memory(HumanOracle())
agent_id = "demo-agent"


# Step 3: ingest Alice as CEO (no conflict yet).
r1 = engine.ingest_claim({
    "agent_id": agent_id,
    "subject": "acme:ceo", "predicate": "held_by", "value": "Alice",
    "provenance": ProvenanceLabel.external_first_hand(),
    "cardinality": "Functional",
    "valid_time": {"start": "2020-01-01T00:00:00Z", "valid_time_confidence": 0.95},
    "confidence": {"value_confidence": 0.95, "valid_time_confidence": 0.95},
    "criticality": "Medium", "derived_from": [],
})
print("Alice:", r1["disposition"])  # CommittedCheap


# Step 4: ingest Bob as CEO — conflict detected, queued for oracle.
r2 = engine.ingest_claim({
    "agent_id": agent_id,
    "subject": "acme:ceo", "predicate": "held_by", "value": "Bob",
    "provenance": ProvenanceLabel.external_first_hand(),
    "cardinality": "Functional",
    "valid_time": {"start": "2023-03-15T00:00:00Z", "valid_time_confidence": 0.9},
    "confidence": {"value_confidence": 0.9, "valid_time_confidence": 0.9},
    "criticality": "Medium", "derived_from": [],
})
print("Bob:", r2["disposition"])  # QueuedForAdjudication


# Step 5: belief is Contested while pending.
q = engine.query_memory({"agent_id": agent_id, "subject": "acme:ceo", "predicate": "held_by"})
print("Before resolve:", q["belief"]["status"])  # Contested


# Step 6: resolve — human (or oracle) picks the challenger (Bob).
pending = engine.list_pending_adjudications(agent_id=agent_id)
engine.submit_adjudication({
    "handle_id": pending[0]["handle_id"],
    "verdict": "Affirm",  # challenger wins
    "evidence_provenance": ProvenanceLabel.external_first_hand(),
})


# Step 7: belief is now Resolved.
q2 = engine.query_memory({"agent_id": agent_id, "subject": "acme:ceo", "predicate": "held_by"})
print("After resolve:", q2["belief"]["status"])         # Resolved
print("Winner:", q2["belief"]["primary"]["fact"]["value"])  # Bob

Verified output:

Alice: CommittedCheap
Bob:   QueuedForAdjudication
Before resolve: Contested
After resolve:  Resolved
Winner:         Bob

MCP session example

Section titled “MCP session example”

See MCP Integration for the working Claude Desktop and Claude Code config files (sourced from mempill-demo/mcp/). The MCP server provides the same four tools (ingest_claim, query_memory, reconcile, audit) over stdio — no Python code required on the agent side.

Section titled “Related guides”