Lifecycle & Async Writes

CortexDB writes are async by default. POST /v1/experience returns 202 Accepted as soon as the WAL append succeeds — typically ~5 ms — and the heavier work (extraction, indexing, consolidation) runs in the background.

Every event then flows through a fixed sequence of stages. You observe these via the lifecycle stream.

The six atomic operations

Adopted from Du et al. (arXiv:2505.00675). They are not separate endpoints — they are observable lifecycle events that fire as the async view builder works.

| Operation | Fires when | Visible via | |---|---|---| | Capture | WAL append succeeds | event: captured on SSE; wait=captured returns | | Index | Event indexed in BM25 + HNSW | event: indexed; wait=indexed returns | | Update | Fact ADD / UPDATE / NOOP decision | event: extracted and event: consolidated | | Consolidate | Beliefs revised; Understanding nodes touched | event: consolidated; wait=consolidated returns | | Forget | Records deleted | event: forgotten | | Compress | Episodes sealed; Understanding versions bumped | event: compressed |

Note: Retrieve is not in this list — recall is request/response, not a lifecycle event.

Opting into sync

Pass ?wait= to POST /v1/experience when you need read-after-write within the same call:

| Value | Returns when | Typical latency | |---|---|---| | (omitted) | WAL append | ~5 ms (202) | | captured | WAL fsync | ~10 ms (200) | | indexed | BM25 + HNSW insert | ~100–500 ms (200) | | consolidated | Beliefs/Understanding touched | ~500–3000 ms (200) |

Subscribing to the lifecycle stream

The recommended pattern for UIs / agents is fire-and-forget writes + an SSE subscription on the lifecycle stream:

GET /v1/lifecycle/stream?scope=org:acme/dept:eng&events=indexed,consolidated
Accept: text/event-stream
Authorization: Bearer ...
X-Cortex-Actor:   user:alice

event: indexed
data: { "event_id": "evt_01HX...", "lifecycle_id": "lce_01HX..." }

event: consolidated
data: { "event_id": "evt_01HX...", "lifecycle_id": "lce_01HY..." }

Use the Last-Event-ID header (or ?since_lifecycle_id=<lce>) to resume after disconnect — the server replays missed events.

Async jobs

Lifecycle events cover async jobs too, with their own progress shape:

| Job | Events | Status endpoint | |---|---|---| | Bulk write | captured per item, plus aggregate import_progress/import_complete | — | | Import | import_progress, import_complete, import_error | GET /v1/import/ | | Erasure | erasure_progress, erasure_complete | GET /v1/erasures/ | | Synthesize | progress events | GET /v1/understanding/synthesize/ | | Export | export_progress, export_complete | GET /v1/export/ |

A lagging event is emitted when the consolidator queue depth exceeds a tenant-configurable threshold — surface this in dashboards to detect index drift.