pgmem docs

pgmem draws a hard line between execution state — what the agent is doing right now — and memory — what should survive the conversation. That line is the whole point: it stops an old session's half-finished reasoning from resurfacing later as established fact. The model has five tiers, plus a sixth slot for live state that is deliberately not memory.

Why it matters

Long-running agents fail the same way every time: a process restarts, picks up an old conversation's half-finished plan, and treats it as fact. Or the context window fills with stale reasoning that drowns out what matters. pgmem prevents this by giving execution state a lifecycle — it's sealed when a session ends and never reused — while memory stays explicit, attributed, and policy-controlled. Every session starts with a fresh execution tree, and memory is retrieved into it rather than carried over.

The tiers

The levels fall into three natures. That grouping is the model — it decides whether something is reused, retrieved, or fetched fresh.

Execution state · Tiers 1–2

The agent's live working set for the session it's in right now. Sealed when the session ends and never reused as memory.

Tier 1 · Working memory — recent turns, pins, and active tool output.
Tier 2 · Execution state — the active path through topics, decisions, and open questions (the MAGE tree).

Memory · Tiers 3–5

What outlives the conversation — formed and retrieved under explicit policy.

Tier 3 · Episodic memory — scoped, evidence-backed claims in the authoritative ledger; lifecycle controls whether they can be recalled.
Tier 4 · Semantic memory — rebuildable lexical, vector, and graph projections of active claims, alongside the independently ingested graph.
Tier 5 · Narrative memory — sagas, the ongoing stories that connect sessions; cross-session.

Live context · Tier 6

Not a memory tier at all. Current state fetched from a system of record at compile time and injected into the prompt — present to the model, never stored. It exists so that state you must not remember can still reach the model.

Tier 6 · Live context — a subscription's status, an account balance, a ticket's state: read live, never copied. See Events vs state.

How it works

Within a turn, the context compiler reads across the tiers — pinned blocks and execution-state summaries (Tiers 1–2), then recalled claims, semantic results, and narrative sagas (Tiers 3–5), plus any Tier 6 live context — and assembles the prompt under a token budget. Tier 2 is never dropped; the lower-priority memory tiers are shed first if the budget is tight. See How a turn flows.

Across sessions the lifecycle is:

Create a fresh session for each conversation — a new, empty execution tree.
Retrieve memory into it — the relevant saga, prior decisions, and facts are pulled in as needed; the old execution trace is never reused.
End the session — pgmem seals the working and execution state for audit, queues the relevant saga rebuild (Tier 5), then asynchronously refreshes derived projections for active claims (Tier 4).

Future sessions get the story and the facts — never a stale execution tree.

Tradeoffs & pitfalls

Don't resume() an old session to "continue" a past conversation as if it were memory — resume is for picking up a session interrupted mid-flight (e.g. a crashed voice worker). For continuity across conversations, create a fresh session and let retrieval bring back the saga and facts.

Projection refresh (Tier 3 → Tier 4) is asynchronous. Claims remain authoritative even while their derived projections are catching up; workers never change authority or lifecycle. See Trust & memory formation.
Tiers 3–5 cost retrieval budget; Tiers 1–2 mostly don't. Execution state is small and always present; the memory tiers are what you tune depth on.

Execution state vs memory — the boundary in depth
How a turn flows — the tiers in motion on a turn
Events vs state — why Tier 6 exists
The context compiler — how the tiers are assembled
Narrative memory (sagas) — Tier 5 in detail

The five-tier model