Concepts
The mental models behind pgmem — read these before building.
pgmem manages memory in levels — six of them — and keeps the active levels strictly apart from the durable ones. This section explains those levels and the rules that keep you out of trouble. Start with the map below, then the mental model.
How to read these docs. Understand the model first: the four essentials in The mental model prevent the common mistakes, and Going deeper covers the mechanisms. Then build — Guides are copy-paste tasks, Reference is the exact API, Operations is running it in production, and Examples are runnable apps.
The memory levels
Everything pgmem holds sits in one of six levels. Tiers 1–2 are execution state — scoped to the current session and never reused as memory. Tiers 3–5 are memory — they outlive the session under explicit policy. Tier 6 is live context — present in the prompt but never stored.
| Tier | Level | Holds | Lifetime |
|---|---|---|---|
| 1 | Working memory | Recent turns, pins, active tool output | Current session |
| 2 | Execution state | The active path — the MAGE tree | Current session |
| 3 | Episodic | Session facts, decisions, commitments | Session → promotion |
| 4 | Semantic | The durable knowledge graph | Cross-session |
| 5 | Narrative | Sagas — stories across sessions | Cross-session |
| 6 | Live context | System-of-record state, injected at compile time | Never stored |
Only retrieval reads across these levels on the turn; forming and promoting memory happens off it. For the full picture see The five-tier model and How a turn flows.
The mental model
The four ideas a developer needs before writing a line of pgmem. Skip these and you'll fight the tool; internalize them and it gets out of your way.
Execution state vs memory
The foundational boundary: what the agent is doing now vs. what should outlive the conversation.
Events vs state
The litmus test you apply on every write — store the event, fetch current state live.
How a turn flows
What runs on the response path, and what runs off it. This is your latency budget.
The five-tier model
The map: working, execution, episodic, semantic, and narrative memory — and what each is for.
Going deeper
The mechanisms behind the model. Read these when you're tuning behaviour or want to know exactly how something works.
The knowledge graph
How Tier 4 stores durable facts as a bi-temporal entity graph.
The context compiler
How compile_context assembles the next prompt under a token budget.
Trust & memory formation
Sources, confidence, and what earns a place in durable memory.
Compaction (MAGE)
Rolling summarization of the turn buffer into the state tree.
Narrative memory (sagas)
Narrative threads that connect one session to the next.
The bi-temporal model
When pgmem learned a fact versus when it was true.