Async Enrichment

Postgram writes entities first, then enriches them in the background.

What this page covers

This page explains the lifecycle of enrichment jobs, status flags, and what to expect when waiting for embeddings, extraction, or searchability.

Core workflow

1. Store or update an entity.
2. The worker enqueues enrichment tasks with enrichment_status = pending.
3. The system creates chunks and embeddings for semantic retrieval.
4. Optional LLM extraction may enrich entity relationships.
5. Enrichment completion updates status to completed; failures become failed.

You can inspect queue health from:

pgm queue

and from REST:

curl http://127.0.0.1:3100/api/queue -H "Authorization: Bearer $PGM_API_KEY"

Notes

• Failed jobs are retried up to 3 times with a 5-minute backoff.
• A newly written entity is not reliably searchable until its embedding finishes. If the embedding provider is unreachable, writes can succeed but search fails until the provider recovers.
• Requeue or maintenance commands are available via pgm-admin for bulk recovery.