Reference
Models
Pydantic models and data types.
The data types pgmem returns and accepts, all importable from pgmem. This is a
catalog — see the source for exhaustive field lists; the per-tier concept pages
explain what each model means.
Graph (Tier 4)
| Model | What it is |
|---|---|
EntityNode | A node in the semantic graph (name, summary, labels, attributes, name_embedding). |
EntityEdge | A relationship between entities, with bi-temporal validity bounds. |
EpisodicNode | A source episode ingested via add_episode. |
EpisodicEdge | Links an episode to the entities it mentioned. |
CommunityNode / CommunityEdge | Clusters from community detection and their membership. |
ExternalReference | A typed pointer to a record in a system of record (system, id, url, fetched_at). |
ExternalFact | An application-asserted verbatim fact with provenance — see Events vs state. |
Session (Tiers 1–3)
| Model | What it is |
|---|---|
Session | The session row (group, user, status, MAGE pointers, pins). |
SessionTurn | One turn (role, content, status, seq/step). |
WorkingMemory | Pins + recent turns + an approximate token count. |
StateNode | A MAGE execution-tree node (the compressed active path). |
Compaction | The audit record of one Compress + its validation verdict. |
Claim | An authoritative Tier 3 assertion with scope, subject, predicate, value, authority, evidence, and lifecycle state. |
Evidence | Immutable provenance supporting a claim. |
MemoryScope / SubjectRef | Generic caller-defined isolation and subject identifiers. |
Narrative (Tier 5) & promotion
| Model | What it is |
|---|---|
SagaNode / SagaEdge | A narrative thread and its session/episode links — see Narrative memory. |
NarrativeProjection | Rebuildable claim-backed saga summary and work lists. |
PromotionJob | A queued derived-claim projection refresh job. |
Results & handles
| Type | Returned by |
|---|---|
AddEpisodeResult / AddBulkEpisodeResult | add_episode / add_episode_bulk. |
SearchResults | mem.search (.nodes, .edges, …). |
CompiledContext | compile_context — see its fields in the Session API. |
CompactionTask | compact_async (await_result, done). |
CompactionResult / MaintainResult | Compaction + validation outcomes. |
Policy types
ClaimCandidate, MemoryDecision, ClaimPolicy, and DefaultClaimPolicy govern
claim formation. See Trust & memory formation.
Enums
Authority · ClaimStatus · MemoryDecisionAction · ConflictStrategy ·
EpisodeType · TurnRole ·
TurnStatus · SessionStatus · StateKind · StateStatus · TriggerReason ·
ValidationStatus · SagaStatus · SagaEdgeType · PromotionJobStatus.
Related
- Session API — methods that take/return these
- Protocols — the provider seams
- The five-tier model — what the tiers mean