Memory Roles

Postgram uses explicit memory roles so you can store both long-term memory and conversation continuity without mixing them.

What this page covers

This page explains when to use durable_memory versus session_context, how to query each role, how memory participates in extraction, and how to groom stale or noisy memory safely.

Core workflow

1. Store durable operational memory with role metadata:

pgm store "Prefer GraphQL for search result caching." \
  --type=memory \
  --tags architecture \
  --metadata '{"memory_role":"durable_memory"}'

2. Store session context for thread continuity:

pgm memory session-context "We discussed entity graph boundaries." \
  --tags session-context \
  --topic postgram-memory

3. Query a specific role:

pgm search "entity graph boundaries" --type=memory --memory-role session_context

4. Clean up session context when it grows stale. Normal users use --dry-run, then an explicit duration, then --yes.

5. Review durable memory quality as an admin workflow:

./bin/pgm-admin memory groom-durable --dry-run --older-than 30d
./bin/pgm-admin memory groom-durable --mode mark --yes --older-than 30d

6. Apply reviewed durable grooming labels only after checking a dry-run:

./bin/pgm-admin memory apply-durable-grooming --dry-run
./bin/pgm-admin memory apply-durable-grooming --yes

Memory extraction

Both memory roles are embedded for semantic recall. By default, memories do not run through graph/entity extraction:

EXTRACTION_MEMORY_MODE=embed_only

Operators can opt durable memories into graph extraction with EXTRACTION_MEMORY_MODE=extract_durable, or opt both durable memories and session context into graph extraction with EXTRACTION_MEMORY_MODE=extract_all. Use ordinary memory_role filters for memory recall when graph extraction is not enabled.

Durable grooming labels

pgm-admin memory groom-durable reviews active durable memories, including legacy memory rows with no explicit metadata.memory_role. Dry-run previews candidates. Mark mode writes metadata.durable_grooming with an outcome, reason, review timestamp, and optional LLM suggestions.

Possible outcomes are:

• keep
• needs_grooming
• archive
• superseded

These outcomes are labels for follow-up work until an operator applies them. They do not rewrite memory content, archive rows, merge duplicates, or make a durable memory safe to delete by themselves.

pgm-admin memory apply-durable-grooming turns labels into action. In default auto mode, needs_grooming rows are rewritten from stored suggestions or the configured extraction LLM, while archive and superseded rows are archived. Rewrites clear stale chunks and queue embedding enrichment again.

Notes

• Durable memory is intended for long-term, future-agent truth.
• Session context is typically scoped to a client identity and used for short-term continuity.
• memory_role filters are available on search/list surfaces so grooming and recall can target the right role.
• The admin CLI supports broader session-context maintenance options such as --all-clients, promotion, and archiving modes.