pgmem docs

pgmem is transparent by design: compactions, memory provenance, promotion decisions, and retrieval results are all inspectable. When you need to answer "why did the agent say that?" or "what did it remember?", you read it directly — nothing is hidden in an opaque cache.

Prerequisites

A PgMem instance and a session.uuid (or group_id) to inspect.

What you can inspect

Compiled context — what the model saw

The CompiledContext returned by compile_context carries full provenance and the budget decisions:

context = await session.compile_context(query=user_text, token_budget=12_000)
print(context.recalled_claims)     # T3 claims that were injected
print(context.recalled_sagas)      # T5 narrative
print(context.recalled_semantic)   # T4 graph facts
print(context.injected)            # T6 live context
print(context.dropped)             # tiers shed to fit, e.g. ["T4"]

Episodic claims — what was remembered and why

claims = await mem.store.claims.active_by_session(session.uuid)
for claim in claims:
    print(claim.predicate, claim.value, claim.status.value,
          claim.authority.value, claim.retention_until)

status, authority, evidence, and retention_until explain formation and retrieval. Derived projection rows never replace the ledger's lifecycle state.

Compactions — the summarization audit trail

Every Compress writes an audit row with its validation verdict:

comps = await mem.store.session_compactions.by_session(session.uuid)
for c in comps:
    print(c.trigger_reason.value, c.validation_status.value,
          c.token_count_before, "→", c.token_count_after, c.validation_note)

Semantic graph — durable facts across sessions

results = await mem.search("annual billing", group_ids=["acme"])
print([n.name for n in results.nodes])

Notes

Raw turns are never deleted by compaction — they remain queryable, so a summary can always be checked against what it covered.
The graph is bi-temporal: a fact's history survives corrections, so you can reconstruct what was believed at the time of a past decision. See The bi-temporal model.

mem.store is the low-level repository surface — handy for inspection and tooling. For building a turn's context, use compile_context, not the repos directly.

Trust & memory formation — what status/retention mean
Compaction (MAGE) — the audit trail's meaning
The context compiler — CompiledContext provenance

Inspecting memory