Entity Model

Postgram stores everything as structured entities with a small common schema and optional metadata.

What this page covers

This page explains the main entity fields, common entity types, and what happens when entities are created or updated.

Core workflow

1. Create an entity using REST, MCP, or the pgm CLI.
2. Set a type (memory, person, project, task, interaction, document), content, tags, visibility, and optional metadata.
3. Read it back by id and keep the returned version for future writes.
4. Update using a write with the latest version (optimistic locking).
5. Delete only when you want it removed from active views; Postgram uses soft-delete semantics in the database layer.

Typical fields:

• content: free-form text payload.
• type: one of the known entity categories.
• tags: one or many labels for filtering and search.
• visibility: personal, work, or shared.
• status: commonly used for tasks.
• metadata: arbitrary JSON for system or client-specific context.
• enrichment_status: pending, completed, or failed for background work.

Notes

• Entities include immutable IDs and monotonically increasing version values.
• PATCH updates must pass the latest version; stale versions can return a conflict response.
• Task-like entities and people/projects can be linked using graph edges for fast context jumps.