pgmem docs

A session handle is minted by mem.session.create(...) or mem.session.resume(...) and represents one conversation. Every read and write on it is scoped to that session; the tenant (group_id) was authorised when the handle was created.

Minting a handle

# A new conversation (fresh execution tree).
session = await mem.session.create(group_id, *, user_id=None, saga_uuid=None,
                                   saga=None, compact_threshold=None, metadata=None)

# Re-open a session interrupted mid-flight (e.g. a crashed worker). Group-scoped.
session = await mem.session.resume(session_id, group_id)

Pass saga (a name) or saga_uuid to attach the session to a saga; its summary is pinned into the new session. Use create for continuity across conversations — not resume.

Properties

Property	Type	Description
`uuid`	`str`	Session id (persist this to `resume` later).
`group_id`	`str`	The tenant.
`status`	`SessionStatus`	`active` / `interrupted` / terminal.
`session`	`Session`	The underlying row (in-memory snapshot).

Turns & working memory (Tier 1)

async def add_turn(role, content, *, status="completed", turn_id=None,
                   parent_uuid=None, token_count=None, metadata=None) -> SessionTurn
async def pin(key, value) -> None          # survives compaction, always in context
async def unpin(key) -> None
async def get_working_memory(*, recent_limit=20) -> WorkingMemory

Reuse a turn_id across streaming chunks to update an in-flight turn until status="completed". Pinned blocks are injected into every compiled context.

Episodic memory (Tier 3)

async def observe(*, subject, predicate, value, authority, evidence,
                  scope=None, confidence=None, metadata=None) -> tuple[Claim, MemoryDecision]
async def retract_claim(claim_uuid, *, scope=None) -> Claim
async def corroborate_claim(claim_uuid, *, evidence, scope=None) -> Claim
async def supersede_claim(claim_uuid, *, value, authority, evidence, scope=None) -> Claim
async def expire_claim(claim_uuid, *, scope=None) -> Claim

observe forms a structured claim through ClaimPolicy; the returned decision records acceptance, holding, corroboration, supersession, discard, or live-state routing. Recall claims through mem.store.claims.recall(scope=..., query=...).

Context (Tiers 1–6)

`compile_context`

async def compile_context(*, recent_limit=20, token_budget=None, query=None,
                          strategy="conversation", retrieval_depths=None,
                          recall_k=None, include_episodic=True, include_narrative=True,
                          include_semantic=True, system_prompt=None,
                          injected_context=None) -> CompiledContext

Assemble the next-turn prompt with pure indexed reads under token_budget. strategy is conversation / task / recall; injected_context is the Tier 6 live-state slot. Returns a CompiledContext:

Field	Description
`messages`	Ready to send to your model.
`recalled_claims` / `recalled_sagas` / `recalled_semantic`	T3 / T5 / T4 provenance.
`injected`	T6 live context that survived the budget.
`dropped`	Tiers shed to fit, e.g. `["T4"]`.
`compaction_triggered`	Recent turns were trimmed for this prompt (not durable compaction).

Compaction (Tier 2)

async def compress(*, label, kind="topic", summary=None, trigger="explicit") -> StateNode | None
async def compact(*, force=False, strategy="auto") -> StateNode | None
async def compact_async(*, label="(async compaction)", validator_model=None) -> CompactionTask
async def maintain(*, compaction=None, validator_model=None) -> MaintainResult | None
async def revise(*, target_step, reason) -> StateNode | None

compact is threshold-gated (no-op below compact_threshold, default 20). compact_async runs Compress + Maintain off the turn — the voice-safe path. See Compaction (MAGE).

Lifecycle

async def end(*, status="completed", metadata=None) -> None

Seals the session's state, queues its saga rebuild, and enqueues async refresh of claim-derived projections. Returns as soon as the writes commit; derived work happens off-turn.

Integrate pgmem into your agent — the turn loop
The context compiler — what compile_context does
Trust & memory formation — how observe decides
PgMem — the composition root

Session API