CortexDB API Reference v1

Accuracy note (2026-07-12). Parts of this reference have drifted from the live router (audit DISC-009): a few documented admin/erasure routes were never implemented, and several live routes (/v1/compose, /v1/recall/stream, /v1/experiences, concepts/claims/conflicts, /v1/scopes/list, /v1/health) are newer than this document. The authoritative route list is API_ROUTES.md (auto-generated from the router), and the machine-readable contract is served at GET /v1/openapi.json. Semantics described here remain correct for the routes that exist. view=local is an alias of view=granular.

Status: Draft for review Last updated: 2026-05-14 Owner: pmalik Scope: the precise external HTTP / SDK contract for CortexDB. This is the reference manual. Companion: API_DESIGN_V1.md is the narrative walkthrough — read that first if you are new to CortexDB. This document is for implementers and SDK authors who need exact shapes, capability mappings, and error codes. Normative source: the JSON schemas in docs/schemas/ are the authoritative contract. Where this document disagrees with a schema, the schema wins. Both documents are explanatory views into the schemas. Predecessors: docs/ARCHITECTURE_REMEMBER_INDEX_RECALL.md, docs/storage-engine-architecture.md, docs/investor_deck/cortexdb_investor_deck_explainer.md. Constraint: there are no production users on a prior API. We may break freely; we are not designing v2-compatible.

Table of Contents

0. Glossary
1. Executive Summary
2. Design Philosophy
3. Core Concepts
4. Authentication & Identity
5. Authorization Framework
6. HTTP Conventions
7. Layer Reference
8. Endpoint Reference
9. The Stratified Pack
10. Streaming
11. Forget Semantics
12. Temporal Model
13. Lifecycle Events Catalog
14. Audit Log Schema
15. Importer Mappings
16. Error Catalog
17. Compatibility Matrix
18. Deferred Decisions
19. Implementation Order
20. Appendices

0. Glossary

1. Executive Summary

CortexDB exposes a layer-aware, scope-unified, bi-temporal memory API for AI agents. It differs from peer systems on nine points:

1. Five addressable memory layers, not one flat memory pool. Clients can read Beliefs, Facts, Episodes, Events, and Understanding separately or as a stratified pack.
2. Unified scope paths that subsume "workspaces" — there is one namespace primitive, hierarchical with opt-in registration and ACLs.
3. Four-tier authorization (deployment → tenant → scope → actor) with capability-level attribution on every denial.
4. Signed-token identity mandatory on every call; tokens can only narrow what policy already allows.
5. Async-first writes with an SSE lifecycle stream; sync available via wait parameter.
6. Bi-temporal everywhere, with as_of, valid_during, recorded_during, and natural-language temporal qualifiers across all layer reads.
7. Reference-counted GDPR erasure — events are deleted when refcount drops to zero, otherwise PII is redacted while preserving cross-scope referential integrity.
8. Streaming recall in both granular (per-layer-as-ready) and narrative (token-by-token) modes.
9. Native importers for Mem0, Zep, Letta, OpenAI memory exports, and generic JSONL — in both strict_temporal and batch_throughput ordering modes.

The public surface comprises roughly 30 endpoints under /v1/ plus an SSE channel and a token verifier protocol.

2. Design Philosophy

2.1 Five non-negotiables

1. Events are immutable. The WAL is the source of truth. Every derived layer is reproducible by replay. There is no API that mutates a stored event payload.
2. Bi-temporal at the boundary. The API accepts and returns both valid_* and recorded_* timestamps on every layer record. Single-time-axis models are not interoperable with us.
3. Async writes are normal. Captures return immediately. Clients that need read-after-write must opt in via wait.
4. Policy is observable. Every denial cites the tier and the specific capability. No opaque 403s.
5. Forget means forget, but proportionally. Default forget wipes derived layers and keeps events. GDPR forget is reference-counted: shared evidence survives without authorship.

2.2 What we explicitly reject

• Soft delete. No tombstones in the user-visible API. Records are either present or gone.
• A single flat memory bag. Mem0's pattern; we will not adopt it.
• Implicit tenancy. Every call carries a token whose sub and aud are explicit.
• Opaque ranking. Recall responses include the plan, the filters applied, and the scoring contribution from each signal.
• Backwards-compat shims. There is no v0; there will be no v0-to-v1 adapter.

2.3 Inspirations and what we did differently

2.4 Stability Tiers

The full conceptual surface ships at v1. To remove ambiguity for implementers and SDK consumers, every endpoint and capability is assigned a stability tier. The tier governs change semantics, not feature completeness:

2.4.1 Stable surface (SDK-committed)

2.4.2 Beta surface (shape solid, semantics maturing)

2.4.3 Experimental surface (documented, ship-with-flag)

Gated by CORTEX_ENABLE_EXPERIMENTAL=1 outside on_prem_enterprise and dev_local. Calls return X-Cortex-Stability: experimental plus X-Cortex-Experimental-Notice with the migration link when the surface settles.

2.4.4 Per-response signal

Every response carries X-Cortex-Stability with the tier of the endpoint hit. SDKs surface a one-time deprecation warning when calling non-Stable endpoints unless the caller has explicitly opted in via client.allow_unstable(true) or equivalent.

2.4.5 Tier promotion criteria

3. Core Concepts

3.1 The Five Memory Layers

3.1.1 Why these five and not three

• Mem0 has "facts" only — they cannot distinguish "what I observed" (Events) from "what I concluded" (Beliefs), so they cannot answer "why do you think that?"
• Zep has facts + episodes — they collapse Belief into Fact, losing confidence as a first-class field.
• We separate lossless capture (Events), bounded recall (Episodes), structured assertion (Facts), probabilistic conclusion (Beliefs), and conceptual synthesis (Understanding). This is the minimum set that lets us answer every recall mode the deck promises.

3.1.2 Layer derivation graph

                                      (synthesize)
Events  ──(window)──▶  Episodes  ──(extract)──▶  Facts  ──(rank+revise)──▶  Beliefs
   │                                                │                          │
   └──────────────────(group + abstract)────────────┴──────────────────────────┴──▶  Understanding

Every derived record carries a supports: [event_id, ...] field. Walking this is the "why" trail.

3.2 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.

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

3.3 Bi-temporal Model

Every record (except Events, which carry only the two timestamps below as singletons) has four time fields:

Events have observed_at and recorded_at as singletons — events are atomic in time and never superseded.

Why both axes: the question "what did the system believe about Acme on April 15 when looked at from May 1?" requires recorded_from ≤ May 1 AND valid_from ≤ Apr 15 < valid_to. Single-axis systems can only answer one or the other.

as_of queries (see §12.3) pin both axes. By default as_of pins recorded_* to now and valid_* to the query time.

3.4 Scope Paths

A scope is a /-delimited path of type:id segments. The path is the namespace. There is no separate "workspace" concept.

3.4.1 Grammar

scope         := segment ("/" segment)*
segment       := type ":" id
type          := lowercase identifier, [a-z][a-z0-9_]*
id            := URL-safe identifier, [A-Za-z0-9_\-]+

Maximum 32 segments. Maximum 4096 characters total.

Reserved types (the system attaches special semantics):

Any other type is user-defined and treated as opaque.

3.4.2 Hierarchy and inheritance

Path order is hierarchical: ancestors precede descendants. A read with view=holistic traverses upward; view=descend traverses downward (admin only).

view=local means exactly this scope — no traversal. This is the default.

3.4.3 Workspaces as scopes

A scope like ws:acme-q3-launch is structurally identical to org:acme/user:alice. It differs only in:

• Convention: workspace scopes are typically not nested under user/org trees.
• Membership: workspaces usually have multiple members, declared via POST /v1/scopes.
• Policy: workspaces typically register a consolidation policy.

There is no API distinction. A scope is a scope.

3.4.4 Registration

A scope path exists as soon as anything is written to it. Registration is optional and grants:

• ACL enforcement (writers/readers/owners)
• Audit logging at scope granularity
• Custom consolidation policy
• Inheritance directives (which ancestors to read up to)

Unregistered scopes are the "scratchpad" tier — any caller with the deployment-level write capability can use them. First write auto-registers with members=[caller] and role=owner (see §8.8.1 for the auto-register schema).

3.5 The Experience Envelope

The input to POST /v1/experience. It generalizes over conversation messages, tool calls, document ingest, observations, and feedback.

3.5.1 The three identities

The envelope carries up to three distinct identities. Collapsing them is the most common API design error in this space; we keep them explicit:

Examples of when these diverge:

• A user wires their agent to ingest Slack messages. caller = agent:ingester, observed_actor = user:alice (the message author), subject = user:alice.
• An admin writes a correction. caller = user:admin_bob, observed_actor = user:admin_bob, subject = user:alice (whose memory is being corrected).
• An import job replays Mem0 exports. caller = service:importer_v1, observed_actor = user:alice (preserved from source), subject = user:alice.

3.5.2 Time fields

Two timestamps, with distinct ownership:

• observed_at (client-supplied, required) — the moment in the world the experience occurred. Always client-side. This is event-time.
• recorded_at (server-assigned, optional on input) — when CortexDB ingested it. Server overrides any client-supplied value with its own wall clock. Clients in import flows may pass source_recorded_at to preserve the upstream system's ingest timestamp; server stores it alongside its own recorded_at.

The previous spec used happened_at and required clients to supply recorded_at. Both are now retired. Use observed_at (event time) and let the server own recorded_at (ingest time).

3.5.3 Envelope shape

{
  "scope": "org:acme/dept:eng/user:alice",
  "observed_actor": {
    "id": "user:alice",
    "type": "user",
    "session": "run_abc"
  },
  "subject": {
    "id": "user:alice",
    "type": "user"
  },
  "modality": "conversation",
  "content": {
    "kind": "message",
    "role": "user",
    "text": "Acme moved to 200 seats and signed by 3:42pm",
    "media": []
  },
  "context": {
    "observed_at": "2026-05-13T15:42:00Z",
    "source_recorded_at": null,
    "location": null,
    "preceded_by": ["evt_01H..."],
    "intent": "deal_close",
    "labels": ["sales", "q3-launch"]
  },
  "directives": {
    "extract": ["facts", "entities", "beliefs"],
    "consolidate_into": "ws:acme-q3-launch",
    "confidence_floor": 0.5,
    "ttl_for_belief_layer": "P30D",
    "embed": "lazy"
  },
  "idempotency_key": "alice-msg-1747147320-001"
}

The server adds the following to the stored event:

Modalities are open-set; unknown values are accepted with a 202 and stored verbatim, but only the listed values trigger structured extraction.

3.5.4 Multimodal content in v1

content.media[] accepts blob references for multimodal payloads, but v1 ships text-only embeddings (§18.2 item 18). The semantic vector space is computed from content.text only. Blob references are indexed by metadata (content-type, size, perceptual hash for images) and reachable via blob_id — but not embedded into the recall vector space. Multimodal embedding is a v1.x add-on; the envelope shape is forward-compatible for that addition (content.media[] already accepts additional indexing hints when they arrive).

3.6 ID Namespaces

Different resources use different ID prefixes to make every identifier self-describing in logs, audit trails, and client code. Mixing namespaces is an error — evt_ IDs are not interchangeable with lce_ IDs.

Lifecycle event IDs. SSE event resume uses since_lifecycle_id=lce_..., NOT memory event IDs. A memory event (evt_) progresses through multiple lifecycle events (lce_) as it moves through Capture → Extract → Index → Consolidate → Compress. Older drafts used since=evt_... for SSE resume; this was ambiguous and is retired.

4. Authentication & Identity

4.1 Signed Tokens

Every request requires a signed bearer token. CortexDB issues PASETO v4 public (asymmetric, Ed25519-signed) via the reference issuer cortex-auth-ref. CortexDB accepts both PASETO v4 public and JWT (RS256, ES256) — the JWT acceptance path exists so customers can integrate their existing OIDC identity providers (Okta, Auth0, Keycloak, Azure AD) without minting separate CortexDB-specific tokens.

The verifier inspects the token's wire format and routes to the appropriate validator. Both formats share the same claim schema (token_claims.schema.json).

Authorization: Bearer <token>
X-Cortex-Actor: agent:planner_v3

The X-Cortex-Actor header is an explicit assertion of actor identity, required to match the token's sub claim. Mismatch → 401 actor_mismatch. The header is required because some clients send tokens that contain multiple identities (e.g., admin-impersonating); we force one identity per call.

Rust library choices (recorded here so engineers do not re-litigate): PASETO uses pasetors; JWT uses jsonwebtoken with the RS256/ES256 algorithms only.

4.2 Claims

4.3 Validation order

1. Signature verification (against issuer's public key)
2. iss in deployment allowlist
3. aud matches deployment's tenant binding
4. exp > now, iat ≤ now + 60s
5. jti not on revocation list
6. X-Cortex-Actor equals sub
7. Token caps intersected with policy stack to produce effective capabilities
8. The specific capability for this endpoint must be in the effective set

Any failure ⇒ 401 with body {error, hint, retriable: false}.

4.4 Service accounts

For server-to-server calls (importer workers, scheduled jobs), sub is of form service:<name> and tokens may have longer exp (up to 30d). Service tokens cannot perform forget.gdpr (must come from a user-authenticated session).

4.5 Revocation

POST /v1/auth/revoke {jti} (operator-only) adds a jti to the revocation list. Lists are TTL-keyed by exp and auto-pruned. Maximum list size 1M; tenants with high revocation volume should issue shorter-lived tokens.

4.6 Token issuer

In production presets the cortexdb binary only VERIFIES tokens. Two issuance paths exist:

0. Local development only: under the default dev_local preset with no CORTEX_API_KEY, the binary runs an in-process ephemeral PASETO minter (POST /v1/auth/signup / POST /v1/auth/tokens) so the zero-config quickstart works. Setting CORTEX_API_KEY disables it unless CORTEX_V1_MINTER_ENABLE=1; tokens do not survive restart unless CORTEX_V1_MINTER_KEY_DIR is set. This minter is not a production issuer.

For production, operators integrate one of:

1. Their existing OIDC provider (Okta, Auth0, Keycloak, Azure AD, custom). The provider's JWKS endpoint is registered in deployment policy; tokens it issues are accepted automatically. This is the recommended path for any enterprise that already runs an IdP.
2. cortex-auth-ref, our reference issuer, which mints PASETO v4 public tokens. Backed by Turso (cloud) or SQLite (self-hosted). Ships as a separate binary alongside cortexdb. Recommended for self-hosted deployments without an existing IdP, for service accounts (importer workers, benchmark harness, scheduled jobs), and for the dev environment.

The two are not mutually exclusive — a deployment can register one or more JWT issuers AND run cortex-auth-ref for service accounts in parallel. The four-tier policy treats them identically once verified.

5. Authorization Framework

5.1 The Four-Tier Stack

Deployment policy   ← operator, at server boot
   ↓ narrows
Tenant policy       ← tenant admin
   ↓ narrows
Scope policy        ← scope owner
   ↓ narrows
Actor policy        ← scope owner or self

A capability is allowed iff every tier allows it. A tier's silence on a capability defaults to its parent's value (inherit-up).

5.1.1 Monotonicity rule

No tier can grant a capability its parent denies. Token caps, when present, are further narrowed against the effective tier stack — they cannot expand.

5.1.2 Decision attribution

Every 403 must cite the tier that denied:

{
  "error": "policy_denied",
  "capability": "scope.create.global",
  "denied_by_tier": "deployment",
  "deployment_preset": "cloud_shared_saas",
  "remediation": "global scopes are not available on cloud-shared deployments"
}

5.2 Capability Catalog

Capabilities are dot-delimited and form a shallow hierarchy. Wildcards allowed in policy expressions (scope.read.*) but not in token caps.

The full enumeration with defaults per preset is in Appendix A.

5.3 Deployment Presets

Operators pick one preset at server boot via CORTEX_DEPLOYMENT_PRESET=<name> or a custom YAML.

5.3.1 on_prem_enterprise

preset: on_prem_enterprise
allow: ["*"]
deny: []
defaults:
  actor.require_signed: true
  scope.auto_register: true
  forget.cascade.default: derived_only
  audit.retention: "P1Y"

Everything is on. Customer is responsible for their own internal policy.

5.3.2 cloud_shared_saas

preset: cloud_shared_saas
allow:
  - "scope.create.org"
  - "scope.create.user"
  - "scope.create.agent"
  - "scope.create.ws"
  - "scope.write"
  - "scope.read.local"
  - "scope.read.holistic"
  - "scope.read.descend"
  - "understanding.read"
  - "understanding.synthesize"
  - "forget.cascade.derived_only"
  - "forget.cascade.redact_events"
  - "forget.gdpr"
  - "forget.gdpr.cross_workspace"
  - "import.*"
  - "export.*"
  - "lifecycle.subscribe"
  - "audit.read"
  - "blob.*"
  - "policy.administer.tenant"
  - "policy.administer.scope"
  - "policy.administer.actor"
deny:
  - "scope.create.global"
  - "scope.create.cross_tenant"
  - "scope.read.cross_tenant"
  - "understanding.read.cross_scope"
  - "audit.read.cross_actor"
defaults:
  actor.require_signed: true
  scope.auto_register: true
  forget.cascade.default: derived_only
  audit.retention: "P2Y"
  rate_limit.write: "100/s"
  rate_limit.read: "500/s"

5.3.3 cloud_private

preset: cloud_private
# Single-tenant cloud — global is "their private public"
allow: ["*"]
deny:
  - "scope.create.cross_tenant"
  - "scope.read.cross_tenant"
defaults:
  actor.require_signed: true
  scope.auto_register: true
  forget.cascade.default: derived_only
  audit.retention: "P3Y"

5.3.4 dev_local

preset: dev_local
allow: ["*"]
deny: []
defaults:
  actor.require_signed: false   # ONLY for local dev
  scope.auto_register: true
  forget.cascade.default: derived_only
  audit.retention: "P7D"

For make dev. The only preset where unsigned actors are allowed.

5.4 Policy Propagation

A policy mutation (PUT on any tier) takes effect immediately for new requests. In-flight requests complete under the policy snapshot they started with.

For SSE lifecycle streams:

• A policy change that affects an open stream takes effect at the next event boundary.
• The current event is delivered if already in progress.
• The stream is then either continued (if still allowed) or closed with event: policy_revoked followed by HTTP close.

5.5 Policy Endpoints

Policy introspection is read-only in v1. The deployment preset and per-tenant policy lists are set at boot from configuration, not over HTTP. Mutation endpoints (PUT) and the per-scope / per-actor policy tiers are deferred to a later phase and are not wired — see cortex-auth::policy for why this is not an authorization gap (scope access is enforced via scope-registry membership and token caps, not per-scope policy lists).

Effective policy response:

{
  "actor": "user:alice",
  "scope": "org:acme/dept:eng/user:alice",
  "deployment_preset": "cloud_shared_saas",
  "allowed": [
    "scope.write", "scope.read.local", "scope.read.holistic",
    "understanding.read", "forget.cascade.derived_only", "lifecycle.subscribe", "..."
  ],
  "denied": [
    {"capability": "scope.create.global", "denied_by_tier": "deployment"},
    {"capability": "scope.read.cross_tenant", "denied_by_tier": "deployment"}
  ],
  "rate_limits": {"write": "100/s", "read": "500/s"}
}

6. HTTP Conventions

6.1 URLs and versioning

• Base path: /v1
• One major version. Breaking changes increment to /v2; the old major stays online for 90 days minimum once a successor exists. (Not relevant pre-launch.)
• No minor version in the URL; additive changes ship freely.

6.2 Content types

• Request body: application/json; charset=utf-8
• Standard response: application/json; charset=utf-8
• Streaming responses: text/event-stream; charset=utf-8
• Blob upload: raw file bytes to /v1/blobs with Content-Type: <mime> (multipart/JSON bodies are rejected with 415)

6.3 Idempotency

Every write endpoint accepts an idempotency_key field in the body. A duplicate (same key + same body) replays the original result: the single-write response carries replayed_from_idempotency: true and each bulk item carries the same flag in its results[] entry. (There is no X-Cortex-Replay response header — the signal is in the body.)

• Keys are scoped to (actor, endpoint, idempotency_key).
• Keys expire after 24 hours.
• Without a key, writes are not idempotent. The SDK supplies one by default.
• Status lookup: GET /v1/experience/status?idempotency_key=<key> answers "did my write land?" without re-sending the body — the resume path after an ambiguous client timeout (see §8.18).
• Failure eviction: when a write is accepted but its indexing then fails (INDEXING_FAILED), its idempotency record is dropped — re-sending the same key re-processes the write instead of replaying the dead event. A key that answers found: false on the status endpoint is always safe to re-send.
• Unicode canonicalization: both the key and the "same body" comparison are Unicode-normalization-insensitive (NFC). A retry whose text round-tripped through an NFC-normalizing system (Slack, macOS, many databases) and came back canonically equivalent but byte-different still replays — it is not an IDEMPOTENCY_CONFLICT. Stored content is never rewritten; only the dedup identity is canonicalized.

6.4 Pagination

Cursor-based pagination on all list endpoints.

GET /v1/facts?scope=...&limit=50
→
{
  "items": [...],
  "next_cursor": "eyJpZCI6ImZhY3RfMDFIWC4uLiJ9",
  "has_more": true
}

GET /v1/facts?scope=...&limit=50&cursor=eyJpZCI6ImZhY3RfMDFIWC4uLiJ9

• Default limit 50, max 1000.
• Cursors are opaque, base64url-encoded JSON. Clients MUST treat them as opaque.
• Cursors are stable across policy changes (they encode a snapshot point).

6.5 Rate limits

Per-actor token bucket. Limits set by deployment defaults, overridable per tenant.

Headers on every response:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1715750460

On limit hit: 429 Too Many Requests with Retry-After.

6.6 Errors

Standard envelope. All error codes are UPPER_SNAKE_CASE — there is one casing rule, applied everywhere. The redundant lower-snake error field used in older drafts is retired.

{
  "error_code": "POLICY_DENIED",
  "message": "Cannot create scope under global:* on this deployment.",
  "request_id": "req_01HX...",
  "details": {
    "capability": "scope.create.global",
    "denied_by_tier": "deployment"
  },
  "retriable": false,
  "documentation": "https://docs.cortexdb.ai/errors/POLICY_DENIED"
}

Normative shape: error_envelope.schema.json in Appendix D. Fields:

Validation failures (422 INVALID_BODY) carry field-level metadata in details: field_path (where in the payload serde stopped, e.g. items[3].context.observed_at), reason (the parser's own message), and schema (the /v1/schemas/... URL of the normative contract to validate against).

6.7 Request IDs

Every response includes X-Cortex-Request-ID. Clients may set their own via the same header on request; if absent, server generates a UUID v7. Older X-Request-ID header is accepted on input as a fallback for compatibility but is not echoed in responses.

6.8 Headers we set

6.9 Headers we accept

6.10 Payload limits

Exceeding the body limit returns a structured 413 PAYLOAD_TOO_LARGE with details.max_body_bytes and remediation pointers. Recommended chunking: normalize captured data into message/turn-level items (one experience per message, stable source IDs as idempotency keys) and batch them through POST /v1/experience/bulk rather than posting whole conversation snapshots — smaller items index faster, dedupe better, and retrieve more precisely. For files, upload bytes via POST /v1/blobs and reference them as blob_ref content.

For large single writes, prefer ?wait=captured (§8.1): the response returns at the durable accept point and indexing proceeds in the background, so write latency stays flat regardless of payload size.

7. Layer Reference

7.1 Events

The append-only WAL. Source of truth.

Record shape:

{
  "id": "evt_01HX...",
  "scope": "org:acme/dept:eng/user:alice",
  "actor": "agent:support_bot_v3",
  "modality": "conversation",
  "content": { /* exactly as submitted in the envelope */ },
  "context": {
    "observed_at": "2026-05-13T15:42:00Z",
    "recorded_at": "2026-05-13T15:42:09Z",
    "preceded_by": ["evt_..."],
    "intent": "deal_close",
    "labels": [...]
  },
  "derives": ["fact_01HX...", "belief_01HX...", "ep_01HX..."],
  "wal_offset": 134892,
  "_partial": false
}

Lifecycle: Created on Capture. Never updated. Deleted only by forget.gdpr with refcount=0.

7.2 Episodes

A causal chain of events.

{
  "id": "ep_01HX...",
  "scope": "org:acme/dept:eng/user:alice",
  "name": "Acme deal Q3 close",
  "summary": "Multi-day negotiation culminating in 200-seat signature on May 13.",
  "events": ["evt_01HX...", "evt_01HX...", "..."],
  "started_at": "2026-05-08T...",
  "ended_at": "2026-05-13T15:42:00Z",
  "valid_from": "2026-05-08T...",
  "valid_to": null,
  "recorded_from": "2026-05-13T15:42:09Z",
  "recorded_to": null,
  "actors_involved": ["user:alice", "user:priya@acme"],
  "centrality_score": 0.78,
  "causal_chain": [
    {"event": "evt_...", "role": "trigger"},
    {"event": "evt_...", "role": "decision"},
    {"event": "evt_...", "role": "outcome"}
  ],
  "_partial": false
}

Lifecycle: Built by the episode builder as related events accumulate. Sealed at Compress stage; once sealed, episode's events[] is immutable. New events with related context produce a new episode that may link as causal_successor.

7.3 Facts

Triple-shaped, optionally temporal.

{
  "id": "fact_01HX...",
  "scope": "org:acme/dept:eng/user:alice",
  "subject": {"type": "entity", "id": "ent_acme_corp", "name": "Acme Corp"},
  "predicate": "moved_to_seat_count",
  "object": {"type": "literal", "datatype": "integer", "value": 200},
  "supports": ["evt_01HX..."],
  "valid_from": "2026-05-13T15:42:00Z",
  "valid_to": null,
  "recorded_from": "2026-05-13T15:42:09Z",
  "recorded_to": null,
  "confidence": 0.94,
  "extractor": "gpt-4o-mini",
  "superseded_by": null,
  "supersedes": "fact_01HW...",
  "_partial": false
}

Lifecycle: Created at Update (extract stage). Superseded by a newer fact via the conflict resolver. When superseded, the old fact gets recorded_to=now and superseded_by; it remains queryable via as_of.

7.3.1 Predicate vocabularies

Predicates are free-text by default. Tenants may register a controlled vocabulary:

POST /v1/vocabularies
{
  "name": "sales_v1",
  "predicates": [
    {"id": "deal_stage", "datatype": "string", "values": ["intro","poc","close","signed","lost"]},
    {"id": "seat_count", "datatype": "integer"},
    {"id": "contact_at", "datatype": "entity"}
  ]
}

When a vocabulary is active for a scope, the extractor maps free-text predicates to vocabulary terms (with confidence). Unmapped predicates remain free-text.

7.4 Beliefs

Probabilistic claims with explicit stance, calibration, and revision policy.

{
  "id": "belief_01HX...",
  "scope": "org:acme/dept:eng/user:alice",
  "claim": {
    "subject": {"type": "entity", "id": "ent_acme_corp"},
    "predicate": "is_likely_to_renew",
    "object": {"type": "literal", "datatype": "boolean", "value": true}
  },
  "stance": "supported",
  "confidence": 0.62,
  "confidence_interval": {"lower": 0.48, "upper": 0.74, "method": "beta_posterior", "level": 0.90},
  "calibration": {
    "model": "platt_v2",
    "brier_score_30d": 0.18,
    "samples": 47,
    "last_calibrated_at": "2026-05-13T00:00:00Z"
  },
  "supports": [
    {"type": "fact",    "id": "fact_01HX...", "weight": 0.34, "polarity": "supports"},
    {"type": "fact",    "id": "fact_01HX...", "weight": 0.28, "polarity": "supports"},
    {"type": "episode", "id": "ep_01HX...",   "weight": 0.22, "polarity": "supports"}
  ],
  "contradicts": [
    {"belief_id": "belief_01HW...", "tension": 0.41, "resolution": "newer_wins"}
  ],
  "revision_policy": {
    "trigger": "new_supporting_evidence_or_contradiction",
    "min_evidence_delta": 0.05,
    "cooldown": "PT5M",
    "max_revisions_per_hour": 12
  },
  "valid_from": "2026-05-13T15:42:09Z",
  "valid_to": null,
  "recorded_from": "2026-05-13T15:42:09Z",
  "recorded_to": null,
  "last_revised_at": "2026-05-13T15:42:09Z",
  "revision_count": 3,
  "supporting_evidence_redacted": false,
  "supporting_evidence_redacted_fraction": 0.0,
  "why_url": "/v1/beliefs/why?belief_id=belief_01HX...",
  "_partial": false
}

7.4.1 Stance enum

Lifecycle: Created at Consolidate. Revised when revision_policy.trigger fires; revision bumps last_revised_at and revision_count. When supporting_evidence_redacted_fraction == 1.0, confidence decays per policy and stance moves to uncertain. If confidence < tenant.confidence_floor (default 0.3), the belief is deleted and surfaces as 410 RESOURCE_DELETED on direct ID lookup; list endpoints silently omit it.

7.5 Understanding

Synthesized conceptual nodes. Beta tier in v1.

7.5.1 Identity, versioning, and staleness

7.5.2 Shape

{
  "id": "concept_01HX...",
  "scope": "org:acme/dept:eng",
  "name": "B2B SaaS Sales Cycle",
  "canonical_id": null,
  "version": 3,
  "previous_version": "concept_01HW...",
  "derived_from": [],
  "summary": "Multi-stage process typically involving prospecting, qualification, POC, negotiation, signature, onboarding.",
  "summary_embedding": null,
  "synthesis_inputs": {
    "layers": ["facts", "episodes", "beliefs"],
    "filters": {"topic": "sales_process"},
    "as_of": "2026-05-13T00:00:00Z",
    "synthesizer": "claude-opus-4-6",
    "synthesizer_version": "2026-05-08"
  },
  "supported_by": {
    "facts":    ["fact_01HX...", "..."],
    "episodes": ["ep_01HX...", "..."],
    "beliefs":  ["belief_01HX...", "..."],
    "external": [
      {"source": "wikipedia", "id": "Sales_process", "url": "..."}
    ]
  },
  "edges": [
    {"to": "concept_01HX...", "relation": "specializes", "weight": 0.81, "vocabulary": "default"},
    {"to": "concept_01HX...", "relation": "depends_on",   "weight": 0.55, "vocabulary": "default"}
  ],
  "valid_from": "2026-04-01T00:00:00Z",
  "valid_to": null,
  "recorded_from": "2026-05-13T15:42:09Z",
  "recorded_to": null,
  "last_synthesized_at": "2026-05-13T15:42:09Z",
  "stance": "supported",
  "confidence": 0.78,
  "staleness_score": 0.0,
  "staleness_reason": null,
  "support_loss_fraction": 0.0,
  "coverage_score": 0.91,
  "_partial": true,
  "_partial_reason": "consolidation_in_progress",
  "_progress": 0.42
}

Lifecycle: Created/updated at Compress. Versioning is append-only — old versions retained for as_of. Coalescence and splitting do not delete history. Re-synthesis is triggered by (a) explicit POST /v1/understanding/synthesize, (b) staleness threshold breach, or (c) support_loss threshold breach.

8. Endpoint Reference

8.1 POST /v1/experience — Write

Capability: scope.write (or scope.write.elevated if writing above the actor's natural level)

Request: Experience envelope (see §3.5).

Response (async, default):

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Cortex-Policy: tier=scope; decision=allow; capability=scope.write
X-Cortex-Request-ID: req_01HX...

{
  "event_id": "evt_01HX...",
  "status": "captured",
  "wal_offset": 134892,
  "lifecycle_stream": "/v1/lifecycle/stream?event_id=evt_01HX..."
}

Response (sync via ?wait=indexed):

HTTP/1.1 200 OK

{
  "event_id": "evt_01HX...",
  "status": "indexed",
  "wal_offset": 134892,
  "stages_completed": ["captured", "extracted", "indexed"],
  "derives": ["fact_01HX...", "belief_01HX..."],
  "elapsed_ms": {"capture": 4, "extract": 410, "index": 88}
}

wait parameter values:

Any other value is rejected with 422 INVALID_BODY; the error message lists the valid values. accepted is an alias for the omitted default.

The response body's status field is "captured" in all async-accept cases; the distinction is the barrier the connection was held for.

Errors:

8.2 POST /v1/experience/bulk — Bulk Write

Capability: scope.write

Request:

{
  "items": [
    {"scope": "org:acme/dept:eng/user:alice", "modality": "...", "content": {...}, "context": {...}, "idempotency_key": "..."},
    ...
  ],
  "ordering": "strict_temporal" | "batch_throughput"
}

Each item is a full experience envelope carrying its own scope — there is no batch-level scope/actor/directives (items in one batch may target different scopes). experiences is accepted as an alias for items.

Maximum 1000 items per call. Larger imports should use /v1/import/jsonl.

Response (async, 202; or 200 with ?wait=):

{
  "batch_id": "batch_01HX...",
  "accepted": 999,
  "event_ids": ["evt_...", "..."],
  "results": [
    {"index": 0, "event_id": "evt_...", "replayed_from_idempotency": false},
    {"index": 1, "event_id": "evt_...", "replayed_from_idempotency": true}
  ],
  "lifecycle_stream": "/v1/lifecycle/stream?batch_id=batch_01HX..."
}

accepted and event_ids count distinct persisted events: items deduplicated by a shared idempotency_key (within the batch, or against a prior write) store one event, repeat its event_id in the index-aligned results array, and carry replayed_from_idempotency: true (v0.7.9 report F2).

Status contract (v0.7.9 report F1):

• Every envelope is validated before anything commits. Any invalid item rejects the whole batch — 422 INVALID_ENVELOPE with per-index details.failures[] — and a 4xx/5xx bulk response guarantees nothing was written (safe to retry the whole batch).
• Runtime faults on some items with others committed return 207 Multi-Status with partial: true, the committed results, and per-index failures[] — retry only the failed items. Indexing failures drop their idempotency records, so re-sending exactly those items re-processes them.
• Whole-batch indexing failure (v0.8.7): when indexing fails for the entire batch after capture (e.g. an embedding-provider outage), the captured-but-unindexed rows are tombstoned server-side — they do not linger as "acked but unretrievable" events, and the retry (which re-processes as fresh events) leaves no duplicates behind. Before v0.8.7 these rows stranded permanently and tripped boot-time index-loss warnings that POST /v1/admin/index-audit {"repair": true} could not fix.

Items with content.kind: "triple" write their fact deterministically (no LLM) on the direct-fact path, same as the single-write endpoint — since v0.8.7 this holds for bulk too (previously bulk stored the triple event but produced no fact unless an enrichment LLM was configured). The batch's triples are embedded in one provider call; if the embedder is down, the facts are still written (without vectors) rather than dropped.

?wait=captured on bulk (v0.8.11) is the raw-first/derive-later fast path: every item acks at its WAL-durable capture point and the batched mirror (embedding + indexing + triple facts) runs in the background under admission control. This is the recommended mode for large backfills — previously bulk always awaited the mirror, so a 25-row batch could block ~90s in embedding and clients hit their own timeouts while the server kept working. Poll GET /v1/experience/status?idempotency_key=... per item (or the lifecycle stream) for indexing progress; a background indexing failure frees the item's idempotency key so re-sending exactly that item re-processes it.

Per-item write status is also queryable by idempotency_key via GET /v1/experience/status?idempotency_key=<key> (§8.18).

8.3 POST /v1/recall — Read

Capability: scope.read.local (always); scope.read.holistic if view=holistic; scope.read.descend if view=descend; diagnostics.read if diagnostics ≠ "none".

Request:

{
  "scope": "org:acme/dept:eng/user:alice",
  "view": "holistic",
  "query": "What did we decide about the Q3 launch?",
  "include": ["beliefs", "facts", "episodes"],
  "exclude_content": false,
  "temporal": {
    "as_of": null,
    "valid_during": null,
    "natural": "last 30 days",
    "reference_date": null
  },
  "filters": {
    "metadata": {
      "observed_actor": ["user:alice", "agent:planner_v3"],
      "labels": ["decision"]
    }
  },
  "budgets": {
    "max_tokens": 4000,
    "per_layer_limits": {
      "events": 0,
      "episodes": 5,
      "facts": 20,
      "beliefs": 10,
      "understanding": 3
    }
  },
  "citation_mode": "inline_with_markers",
  "diagnostics": "summary",
  "stream": false,
  "idempotency_key": "recall-alice-q3-001"
}

Field reference:

Response (non-streaming): The stratified pack (see §9), including a pack_id that can be referenced by /v1/answer for follow-up.

Response (streaming, stream=true): SSE (see §10.1).

8.4 POST /v1/answer — Recall + LLM

Capability: scope.read.local + any traversal caps + llm.invoke + diagnostics.read if diagnostics ≠ "none".

/v1/answer shares the recall provenance contract: the same pack_id, provenance, and citations blocks appear in the response. It is recall composed with an LLM call, not a separate opaque endpoint.

{
  "scope": "org:acme/dept:eng/user:alice",
  "view": "holistic",
  "question": "Did Acme renew?",
  "answer_model": "claude-opus-4-6",
  "answer_max_tokens": 1500,
  "include": ["beliefs", "facts", "episodes"],
  "exclude_content": false,
  "temporal": {"as_of": null, "natural": "last 30 days"},
  "filters": {},
  "budgets": {"max_tokens": 4000, "per_layer_limits": {"facts": 20, "beliefs": 10}},
  "citation_mode": "inline_with_markers",
  "diagnostics": "summary",
  "use_pack_id": null,
  "stream": false
}

Response:

{
  "pack_id": "pack_01HX...",
  "answer": "Acme upgraded to 200 seats on May 13. They did not renew their previous contract; they signed a new one. [1][2]",
  "citations": [
    {"marker": "[1]", "layer": "fact",  "id": "fact_01HX...", "support_strength": 0.91},
    {"marker": "[2]", "layer": "event", "id": "evt_01HX...", "support_strength": 0.87}
  ],
  "provenance": {
    "trail": [...],
    "citations": {...}
  },
  "diagnostics": {
    "recall_ms": 412,
    "llm_ms": 814,
    "total_ms": 1240,
    "pack_used": {"facts": 5, "beliefs": 2, "episodes": 1},
    "answer_model": "claude-opus-4-6",
    "answer_tokens": {"prompt": 1284, "completion": 218}
  },
  "as_of": "2026-05-13T15:42:09Z"
}

provenance and citations have the same shape as in /v1/recall (§9). as_of reflects the effective temporal anchor used.

Streaming variant: token-by-token answer, followed by pack_id, citations, provenance, diagnostics, and as_of (§10.2).

8.5 POST /v1/forget — Selective Forget

Capability: forget.cascade.<mode> matching the requested cascade.

Note: Earlier drafts used DELETE /v1/forget with a JSON body. We use POST instead because (a) DELETE with bodies is unreliable across HTTP clients/proxies, (b) forget is a job that may be long-running, and (c) it composes uniformly with the /v1/erasures job family for true erasure (§8.6).

{
  "scope": "org:acme/dept:eng/user:alice",
  "layers": ["beliefs", "facts"],
  "selector": {
    "about_subject": "user:alice",
    "about_entity": "ent_acme_corp",
    "predicate": "is_likely_to_renew",
    "memory_ids": [],
    "valid_during": null,
    "recorded_during": null
  },
  "cascade": "derived_only",
  "confirm_all": false,
  "audit_note": "User retracted speculation",
  "idempotency_key": "forget-alice-001"
}

Response:

{
  "deleted": {
    "events": 0,
    "episodes": 0,
    "facts": 2,
    "beliefs": 1,
    "understanding": 0
  },
  "audit_id": "audit_01HX..."
}

Cascade modes:

events_too is NOT a cascade value here — true erasure of events goes through /v1/erasures (§8.6).

confirm_all flag. When the selector is empty (or only layers is set), the server requires confirm_all: true to proceed — otherwise it 422s with EMPTY_SELECTOR_WITHOUT_CONFIRMATION. This is the foot-gun guard for "forget everything in this scope."

8.6 /v1/erasures — Reference-Counted GDPR Erasure

This family replaces the prior DELETE /v1/forget/gdpr endpoint. It is the only path to true event deletion. It exposes preview, manifest, status, and cancel — long-running jobs deserve a proper lifecycle.

8.6.1 POST /v1/erasures/preview — Dry-run

Capability: forget.gdpr (read-only preview is gated by the same cap as the destructive action, so callers can't enumerate without authorization).

{
  "scope": "org:acme/user:alice",
  "audit_note": "DSR #1234 — preview"
}

Response:

{
  "preview_id": "ervw_01HX...",
  "scope": "org:acme/user:alice",
  "estimated_affected": {
    "events": 9420,
    "episodes": 318,
    "facts": 4120,
    "beliefs": 318,
    "understanding": 12
  },
  "refcount_breakdown": {
    "in_scope_events":       12480,
    "events_to_delete":       9420,
    "events_to_redact":       3060,
    "events_under_legal_hold":   0
  },
  "estimated_duration_ms": 240000
}

estimated_affected.events is the headline delete count; refcount_breakdown carries the full in-scope tally (in_scope_events) and the delete-vs-redact split. There is no separate manifest endpoint or manifest_url in v1 — the plan above IS the preview. Execute returns the running job's manifest_url, which is its status resource GET /v1/erasures/{erasure_id} (§8.6.4), not a distinct manifest route.

8.6.3 POST /v1/erasures — Execute

Capability: forget.gdpr. Cross-workspace propagation additionally requires forget.gdpr.cross_workspace.

{
  "scope": "org:acme/user:alice",
  "from_preview_id": "ervw_01HX...",
  "audit_note": "DSR #1234 — Alice exercised right to erasure",
  "idempotency_key": "erasure-dsr-1234"
}

If from_preview_id is set and not expired, the server validates the manifest is still current (no new events under the scope since the preview); if drift exceeds a tenant-configurable threshold, the request 409s and a fresh preview is required. If from_preview_id is omitted, the server runs a preview inline before executing.

Response (always async, 202):

{
  "erasure_id": "erasure_01HX...",
  "status": "running",
  "manifest_url": "/v1/erasures/erasure_01HX...",
  "lifecycle_stream": "/v1/lifecycle/stream?erasure_id=erasure_01HX..."
}

8.6.4 GET /v1/erasures/{erasure_id} — Status

{
  "erasure_id": "erasure_01HX...",
  "status": "running",
  "phase": "delete",
  "fraction_complete": 0.78,
  "progress": {
    "deleted_events": 9420,
    "redacted_events": 3060,
    "demoted_beliefs": 18,
    "elapsed_ms": 180000
  },
  "audit_id": null
}

When status: "completed", the audit_id field is populated.

8.6.5 POST /v1/erasures/{erasure_id}/cancel

Best-effort cancellation. The server stops at the next phase boundary; already-deleted events cannot be restored (their WAL slots are gone). The response indicates what was completed before cancellation took effect.

{
  "erasure_id": "erasure_01HX...",
  "cancellation_accepted": true,
  "deleted_events_before_cancel": 4280,
  "audit_id": "audit_01HX..."
}

8.6.6 Lifecycle events emitted

event: erasure_progress
data: {"erasure_id": "...", "phase": "enumerate", "fraction_complete": 0.12}

event: erasure_progress
data: {"erasure_id": "...", "phase": "refcount",  "fraction_complete": 0.45}

event: erasure_progress
data: {"erasure_id": "...", "phase": "delete",    "fraction_complete": 0.78,
       "deleted_events": 9420, "redacted_events": 3060}

event: erasure_complete
data: {"erasure_id": "...", "summary": {...}, "audit_id": "audit_01HX..."}

Detailed semantics in §11.3.

8.7 Layer-Scoped Reads

8.7.1 GET /v1/events

Capability: scope.read.local + traversal as appropriate. Default view is local — see §18.2 item 14.

GET /v1/events
  ?scope=org:acme/dept:eng/user:alice
  &view=local
  &since=2026-04-01T00:00:00Z
  &observed_actor=user:alice
  &modality=conversation
  &limit=50
  &cursor=...

Pass view=holistic explicitly to walk up the scope hierarchy.

Response:

{
  "items": [ /* Event records (see §7.1) */ ],
  "next_cursor": "...",
  "has_more": true
}

8.7.2 GET /v1/episodes

GET /v1/episodes?scope=...&view=...&actor=...&overlapping=2026-04-01..2026-05-01&with_causal_chain=true&limit=50&cursor=...

8.7.3 GET /v1/facts

Default view is local — pass view=holistic explicitly for hierarchy traversal.

GET /v1/facts
  ?scope=...
  &view=local
  &subject=ent_acme_corp
  &predicate=deal_stage
  &as_of=2026-04-15T00:00:00Z
  &min_confidence=0.6
  &include_superseded=false
  &include_vectors=false
  &limit=50

as_of × include_superseded interaction (§18.2 item 1): both filters apply independently and conjunctively. as_of clips both axes (recorded_* ≤ as_of, valid_from ≤ as_of < valid_to). include_superseded=true returns superseded historical versions whose recorded_to ≤ as_of.

include_vectors (v0.8.11, also on GET /v1/beliefs and GET /v1/understanding[/{id}]): embedding vectors (summary_embedding) are omitted by default — two operator reports flagged hundreds of floats per record making listings unreadable for inspection. Pass include_vectors=true to opt back in.

8.7.4 GET /v1/facts/timeline

Returns the supersession chain for (subject, predicate):

{
  "subject": {"id": "ent_acme_corp", "name": "Acme Corp"},
  "predicate": "deal_stage",
  "timeline": [
    {"fact_id": "fact_01HV...", "value": "poc",    "valid_from": "...", "valid_to": "2026-04-10T..."},
    {"fact_id": "fact_01HW...", "value": "close",  "valid_from": "2026-04-10T...", "valid_to": "2026-05-13T..."},
    {"fact_id": "fact_01HX...", "value": "signed", "valid_from": "2026-05-13T...", "valid_to": null}
  ]
}

8.7.5 GET /v1/beliefs

GET /v1/beliefs?scope=...&about=ent_acme_corp&min_confidence=0.6&as_of=...&limit=50

8.7.6 GET /v1/beliefs/why

The "why do you think that?" endpoint. Unique to CortexDB.

GET /v1/beliefs/why?belief_id=belief_01HX...

Response:

{
  "belief": { /* belief record (§7.4) */ },
  "support_graph": {
    "nodes": [
      {"id": "fact_01HX...",  "type": "fact",   "weight": 0.34, "summary": "..."},
      {"id": "ep_01HX...",    "type": "episode","weight": 0.22, "summary": "..."},
      {"id": "evt_01HX...",   "type": "event",  "summary": "..."},
      {"id": "evt_01HX...",   "type": "event",  "summary": "..."}
    ],
    "edges": [
      {"from": "fact_01HX...", "to": "evt_01HX...", "relation": "extracted_from"},
      {"from": "fact_01HX...", "to": "evt_01HX...", "relation": "extracted_from"},
      {"from": "ep_01HX...",   "to": "evt_01HX...", "relation": "contains"},
      {"from": "belief_01HX...","to": "fact_01HX...", "relation": "supported_by"}
    ]
  },
  "narrative": "I think Acme is likely to renew because on May 13 they upgraded to 200 seats (fact_01HX), and this followed a positive POC episode (ep_01HX) in April. The signal weight is 0.62 with CI [0.48, 0.74].",
  "narrative_model": "claude-haiku-4-5"
}

8.7.7 GET /v1/understanding

GET /v1/understanding?scope=...&topic=B2B+SaaS&depth=2&limit=50

8.7.8 GET /v1/understanding/{concept_id}

Returns full concept record (§7.5).

8.7.9 GET /v1/understanding/{concept_id}/related

GET /v1/understanding/{concept_id}/related?relation=specializes&depth=2&limit=50

8.7.10 GET /v1/understanding/coverage

GET /v1/understanding/coverage?scope=org:acme/dept:eng

Response:

{
  "scope": "org:acme/dept:eng",
  "concept_count": 421,
  "by_topic": [
    {"topic": "sales_process",   "concepts": 38, "avg_confidence": 0.74},
    {"topic": "product_features","concepts": 92, "avg_confidence": 0.81},
    {"topic": "customer_personas","concepts": 24, "avg_confidence": 0.62}
  ],
  "synthesis_lag": "P2D",
  "_partial": true
}

8.7.11 POST /v1/understanding/synthesize

Capability: understanding.synthesize Async (audit FRI-10) — returns 202 immediately with a job id; the synthesizer runs in the background.

{
  "scope": "org:acme/dept:eng",
  "topics": ["sales_process"],
  "force": false
}

Response: 202 + lifecycle stream URL.

{
  "job_id": "synth_019e...",
  "status": "running",
  "lifecycle_stream": "/v1/lifecycle/stream?job_id=synth_019e..."
}

Poll pattern:

job = client.synthesize(scope=SCOPE)
# Subscribe to the SSE stream or poll until status == "complete":
#   GET {job['lifecycle_stream']}
# Then read derived concepts:
summary = client.understanding(scope=SCOPE)

Model + cost note (audit POL-1): the synthesizer renders concepts with Claude Opus 4.6, the most capable model for long-context reasoning. That's the differentiator — and the cost driver. Background concept reflection triggers per scope after ≥25 new writes or ≥1h staleness (CORTEX_V1_LAYERS_CONCEPT_MIN_WRITES / _MAX_AGE_SECS; the legacy CORTEX_V1_LAYERS_CONCEPT_EVERY tick-parity override still throttles globally when set), so frequent synthesize() calls on busy scopes can add up on usage-based plans. With enrichment (CORTEX_ENRICHMENT_DELAY_SECONDS) unset, background reflection is gated off entirely unless CORTEX_V1_LAYERS_AUTO=1 opts in — manual synthesize() calls are never gated.

8.8 Scopes

8.8.1 POST /v1/scopes — Register

Capability: policy.administer.scope for the path being created.

{
  "path": "ws:acme-q3-launch",
  "members": [
    {"actor": "user:alice",       "role": "owner"},
    {"actor": "agent:planner_v3", "role": "writer"},
    {"actor": "agent:summarizer", "role": "reader"}
  ],
  "policies": {
    "consolidation": "merge_compatible_beliefs",
    "conflict_resolution": "latest_wins_within_confidence_band",
    "inherit_from": ["org:acme"],
    "audit": "full",
    "children": {"auto_register": true}
  }
}

Response: 201 Created with the canonical scope record.

8.8.2 GET /v1/scopes — Lookup by path

Routing note: scope paths contain /, so we cannot put them in URL path segments without ambiguity. Scope lookup, member edit, and delete all use the query parameter ?path=... form. SDKs canonicalize and percent-encode the value.

GET /v1/scopes?path=org:acme%2Fdept:eng%2Fuser:alice

Returns the scope record including auto-provisioned status. 404 if the path has never been written to.

8.8.3 PUT /v1/scopes/members?path=...

Atomic member edit. Full member list submitted; server computes diff.

PUT /v1/scopes/members?path=ws:acme-q3-launch
{
  "members": [
    {"actor": "user:alice",       "role": "owner"},
    {"actor": "agent:planner_v3", "role": "writer"},
    {"actor": "agent:summarizer", "role": "reader"}
  ]
}

8.8.4 DELETE /v1/scopes?path=...

Capability: policy.administer.scope AND forget.gdpr if records=forget and any records exist.

Deletes the scope's policy and (configurably) its records. Two modes via query param:

• ?records=keep (default) — Only deletes the policy/registration; records remain accessible to other allowed scopes.
• ?records=forget — Runs a POST /v1/erasures for this scope first, then removes the policy.

8.8.5 GET /v1/scopes — List

GET /v1/scopes?prefix=org:acme/&auto_provisioned=false&limit=50

8.8.6 POST /v1/scopes/prune — Cleanup

Capability: policy.administer.tenant

Removes auto-provisioned scopes that have had no writes in N days and no explicit owner action.

{
  "older_than": "P90D",
  "dry_run": true
}

Response:

{
  "candidates": [
    {"path": "org:acme/.../user:bob/temp:debug",
     "last_write": "2026-02-01T...",
     "records": {"events": 4, "facts": 0}}
  ],
  "total": 73
}

8.9 Lifecycle

8.9.1 GET /v1/lifecycle/stream — SSE

Capability: lifecycle.subscribe

GET /v1/lifecycle/stream?scope=org:acme/user:alice&since_lifecycle_id=lce_01HX...
Accept: text/event-stream

The since_lifecycle_id parameter takes a lifecycle event ID (lce_...), not a memory event ID (evt_...). Server keeps a 1h replay buffer keyed by lifecycle event arrival time.

Filter to a specific memory event via ?event_id=evt_01HX... (subscribe only to the lifecycle stages of one event). Filter to a job via ?job_id= or one of ?import_id=, ?export_id=, ?erasure_id=, ?batch_id=.

Filter to event types via ?events=captured,consolidated (subscribe to a subset; full catalog §13).

Response: SSE stream. See §10 and §13.

8.9.2 GET /v1/lifecycle/event/{lce_id} — Poll one lifecycle event

Returns one lifecycle event row:

{
  "lifecycle_id": "lce_01HX...",
  "event_id": "evt_01HX...",
  "stage": "extracted",
  "ts": "2026-05-13T15:42:09.418Z",
  "payload": {"derived": {"facts": 3, "entities": 2, "beliefs": 1}}
}

8.9.3 GET /v1/lifecycle/memory-event/{evt_id} — Aggregated view

Returns the current aggregated state of a memory event (which stages are complete, which are pending):

{
  "event_id": "evt_01HX...",
  "stages_completed": ["captured", "extracted", "indexed"],
  "stages_pending":   ["consolidated"],
  "lifecycle_event_ids": ["lce_01HX...", "lce_01HX...", "lce_01HX..."],
  "derives": ["fact_01HX...", "belief_01HX..."],
  "errors": []
}

8.9.4 GET /v1/lifecycle — Catch-up paginated

GET /v1/lifecycle?scope=...&since_lifecycle_id=lce_01HX...&limit=100&cursor=...

For clients that can't hold SSE connections. Returns lifecycle event rows in lce_ order.

8.9.5 POST /v1/lifecycle/memory-event/{evt_id}/cancel

Capability: scope.write on the event's home scope; the caller must also be the event's caller OR have scope.administer on the home scope.

Cancels queued lifecycle stages (extracted, indexed, consolidated, compressed) for a memory event that has already been captured. The WAL capture itself is not reversible — the event remains in the WAL and remains directly addressable via GET /v1/events/{evt_id} — but the event is flagged excluded_from_recall: true and will not appear in /v1/recall, /v1/answer, or layer-scoped list endpoints.

Use cases: client submitted by accident; client realized post-submit that the content shouldn't be derived from; client wants to retry with corrected content.

Request:

{
  "audit_note": "Caller cancelled (incorrect content); will resubmit"
}

Response:

{
  "event_id": "evt_01HX...",
  "stages_cancelled": ["extracted", "indexed", "consolidated"],
  "stages_already_completed": ["captured"],
  "excluded_from_recall": true,
  "audit_id": "audit_01HX..."
}

If any non-captured stage had already completed before the cancel arrived, the derived records produced by that stage are also marked excluded_from_recall: true (they are not deleted — to delete, the caller follows up with a POST /v1/forget).

8.10 Audit

8.10.1 GET /v1/audit

Capability: audit.read. audit.read.cross_actor additionally required to query for actors other than self.

GET /v1/audit
  ?scope=org:acme/...
  &actor=agent:planner_v3
  &capability=scope.write
  &decision=deny
  &since=2026-05-01T00:00:00Z
  &limit=100

Returns audit log rows (§14).

8.10.2 GET /v1/audit/{audit_id}

Single row by ID.

8.10.3 POST /v1/audit/verify

Tamper-evidence check. Submit a request body; server hashes it and confirms whether it matches an audit row.

{
  "audit_id": "audit_01HX...",
  "body": "{ ... raw JSON of the original request ... }"
}

Response:

{
  "match": true,
  "hashed_at": "2026-05-13T15:42:09Z",
  "algorithm": "sha256",
  "tenant_pepper_version": 3
}

8.11 Import

8.11.1 POST /v1/import/mem0

Capability: import.from.mem0

{
  "scope_template": "org:acme/user:{user_id}",
  "source": {
    "format": "mem0_export_v3",
    "url": "s3://bucket/mem0-export.jsonl.gz",
    "inline": null,
    "credentials_ref": "secret:s3_reader_v1"
  },
  "options": {
    "ordering": "strict_temporal",
    "preserve_timestamps": true,
    "map_categories_to": "understanding",
    "extract": ["facts", "entities", "beliefs"],
    "embed": "lazy",
    "skip_on_conflict": false
  }
}

Response:

{
  "import_id": "imp_01HX...",
  "status": "running",
  "estimated_items": 12480,
  "lifecycle_stream": "/v1/lifecycle/stream?import_id=imp_01HX..."
}

Mapping table in §15.1.

8.11.2 POST /v1/import/zep

Capability: import.from.zep

Same shape; Zep-specific options:

{
  "options": {
    "preserve_bi_temporal": true,
    "ontology_mapping": {
      "PreferenceEdge": "user_preference",
      "PurchaseEdge": "purchase"
    }
  }
}

Mapping in §15.2.

8.11.3 POST /v1/import/letta

Capability: import.from.letta

{
  "scope_template": "agent:{agent_name}",
  "source": {"format": "letta_af", "url": "..."},
  "options": {
    "map_core_blocks_to": "understanding",
    "map_archival_to": "events"
  }
}

Mapping in §15.3.

8.11.4 POST /v1/import/openai

Capability: import.from.openai

For ChatGPT memory exports (JSON dump format).

8.11.5 POST /v1/import/jsonl

Capability: import.from.jsonl

Generic line-delimited envelope JSON. Each line is a full experience envelope.

8.11.6 GET /v1/import/{import_id}

Status poll.

{
  "import_id": "imp_01HX...",
  "status": "running",
  "fraction_complete": 0.42,
  "processed": 5240,
  "total": 12480,
  "errors": [
    {"line": 1208, "error": "invalid_envelope", "detail": "missing scope"}
  ]
}

8.11.7 POST /v1/import/{import_id}/cancel

8.12 Export

8.12.1 POST /v1/export

Capability: export.format.<target> matching requested format.

{
  "scope": "org:acme/user:alice",
  "format": "jsonl" | "mem0" | "zep" | "letta",
  "layers": ["events", "facts", "beliefs"],
  "as_of": null,
  "destination": {
    "kind": "url",
    "url": "s3://bucket/export.jsonl.gz",
    "credentials_ref": "secret:s3_writer_v1"
  }
}

Response:

{
  "export_id": "exp_01HX...",
  "estimated_size_bytes": 4823648,
  "lifecycle_stream": "/v1/lifecycle/stream?export_id=exp_01HX..."
}

8.12.2 GET /v1/export/{export_id}

Status poll.

8.13 Blobs

For multimodal content.

8.13.1 POST /v1/blobs — Upload

Capability: blob.upload

The request body is the raw file bytes; Content-Type declares the file's MIME type (e.g. application/pdf). Do not wrap in multipart/form-data or JSON — those are rejected with 415 unsupported_media_type. Maximum 100MB per blob by default.

curl -X POST https://api-v1.cortexdb.ai/v1/blobs \n  -H "Authorization: Bearer $CORTEX_TOKEN" \n  -H "X-Cortex-Actor: $CORTEX_ACTOR" \n  -H "Content-Type: application/pdf" \n  --data-binary @report.pdf

Response:

{
  "blob_id": "blob_01HX...",
  "size_bytes": 4823648,
  "content_type": "image/png",
  "sha256": "..."
}

Reference in an experience envelope via content.media: [{"blob_id": "blob_01HX..."}].

8.13.2 GET /v1/blobs/{blob_id}

Capability: blob.read

Returns the raw bytes. Content-Type reflects the original.

8.13.3 DELETE /v1/blobs/{blob_id}

Capability: blob.delete — authorized by ownership: only the actor that uploaded the blob may delete it, exactly as for GET. A blob owned by someone else answers 404 (the same answer a read gets — it never confirms the id exists).

Purges the stored object and its metadata.

{ "blob_id": "blob_01HX...", "bytes_deleted": true }

bytes_deleted: false means the metadata was dropped but the backing store already had no object; the end state is the same.

Use this when the source file is deleted upstream. Redacting the experience that references a blob removes the memory; it does not remove the object, so a right-to-be-forgotten flow over uploaded files must do both:

# 1. redact the experience that referenced the file
curl -X POST $CORTEX_URL/v1/forget -H "Authorization: Bearer $CORTEX_TOKEN" \n  -H "X-Cortex-Actor: $CORTEX_ACTOR" -H 'Content-Type: application/json' \n  -d '{"scope":"user:alice","selector":{"memory_ids":["evt_01HX..."]},"cascade":"redact_events"}'
# 2. purge the bytes
curl -X DELETE $CORTEX_URL/v1/blobs/blob_01HX... \n  -H "Authorization: Bearer $CORTEX_TOKEN" -H "X-Cortex-Actor: $CORTEX_ACTOR"

Deleting an unknown or already-deleted id returns 404; the call is safe to retry.

8.14 Vocabularies

8.14.1 POST /v1/vocabularies

Capability: policy.administer.tenant

See §7.3.1.

8.14.2 GET /v1/vocabularies/{name}

8.14.3 PUT /v1/vocabularies/{name}

8.15 Admin (existing surface, retained)

GET /v1/admin/layers/stats health section (extended in v0.8.14 — the layer-observability asks from the vault-migration report): llm_roles separates the four LLM cost centers (enrichment extraction, recall expansion + synthesis, answers, verifier) with per-role configured/model, and states explicitly that entity extraction is rule-based with no LLM cost; layer_sources gives every layer its derivation source and current gate (events: raw, episodes: raw_derived_no_llm, facts: llm_extracted_plus_deterministic_triples with status deterministic_triples_only when no enrichment model is set — which is why a text-only backfill adds no facts, beliefs: derived_from_facts_no_llm, concepts: llm_synthesized with the spend gate); and enrichment_backlog_stalled (+ note) flags the deferred-scanner backlog that can never drain because CORTEX_ENRICHMENT_MODEL is unset.

POST /v1/admin/scopes/migrate (v0.8.13) — the scope migration/merge workflow: applications that change their memory model (e.g. per-source scopes user:x/source:chatgpt folding into one root user:x) get a first-class copy/move instead of hand-rolled re-sync scripts. Body:

{ "from": "user:x/source:chatgpt", "to": "user:x",
  "mode": "copy",              // or "move"
  "dry_run": false,
  "batch_size": 100,
  "confirm_erase_source": false }

Returns 202 {job_id, status_url}; poll GET /v1/admin/scopes/migrate/{job_id} (job records are process-local, like erasure jobs). Semantics: events copy through the normal write path with event_time, content, and metadata (labels, extraction directives) preserved; destination event ids are deterministic functions of the source ids, so re-running resumes (already- copied events are skipped) and never duplicates. [triple] events regenerate their deterministic facts under the target synchronously; other derived layers regenerate through the deployment's normal enrichment/synthesis (enrichment-off deployments: trigger POST /v1/understanding/synthesize on the target, or wait for organic activity). mode: "move" additionally erases the source through the standard scope-wide forget — gated on a clean, count-verified copy AND an explicit confirm_erase_source: true; on any verification failure the source is left untouched and the job reports why. Requires admin.compact. Migrates the EXACT scope string only — migrate a subtree by calling once per scope.

POST /v1/admin/index-audit body: {"repair": bool, "scope": "user:...", "vectors": bool}, all optional. repair=false (default) reports events whose search-index entries are missing; repair=true re-indexes them — since v0.8.7 this includes rebuilding missing content-store rows from the WAL event content (previously such events were unrepairable: "content row missing; cannot repair from stored state"). scope restricts the audit and the repair to one scope subtree (exact or descendant); before v0.8.7 it was accepted and silently ignored (repair always ran globally). Caveat: if a failed bulk batch was already re-sent under fresh events (pre-v0.8.7 behavior), repairing its stranded originals re-indexes duplicate content — erase those scopes first.

vectors (default false, since v0.8.21) widens the membership test to the VECTOR index. The default check is BM25-only on purpose: a cold-tier demotion removes the in-memory graph node while the vector stays intact and searchable, so treating "not in the graph" as missing would flag healthy consolidated data. With vectors: true the audit asks whether a stored row exists in either tier, which separates "demoted" from "truly gone" — the state an embedding outage leaves behind, since the fulltext document is written whether or not embedding succeeded. Such events stay keyword-findable but are invisible to semantic recall, and nothing else reports them. The counts are separate: missing_vectors / missing_vectors_total / vectors_repaired alongside the fulltext missing / missing_total / repaired, so existing consumers read unchanged. With repair: true the lost vectors are re-embedded from stored content — so fix a broken embedding key BEFORE repairing, or every chunk lands in vector_repair_skipped instead.

GET /v1/admin/metrics (JSON, gated on diagnostics.read) reports, beyond the request/error/rate-limit counters: version, per-route endpoints[] (call count, errors, p50/p95/p99/max latency ms), errors_by_code[] (structured error responses grouped by error_code), writes.indexing_failures_total (accepted-but-unindexed writes), and storage.data_dir_bytes_approx (on-disk footprint, cached ~60s). The /metrics Prometheus endpoint exposes the same counters as cortexdb_* series including cortexdb_indexing_failures_total and cortexdb_errors_by_code_total{code=...}.

8.16 Auth

8.16.1 POST /v1/auth/revoke

Capability: auth.revoke (operator or, for self-revocation, the token holder).

Adds a token's jti to the revocation list. The token becomes invalid for all subsequent calls until exp passes.

{
  "jti": "01HX...",
  "reason": "rotated"
}

Response: 204 No Content.

Revocation lists are TTL-keyed by exp and auto-pruned. Maximum list size 1M; tenants with high revocation volume should issue shorter-lived tokens.

8.16.2 GET /v1/auth/whoami

Capability: (open to authenticated callers)

Returns the effective identity and capability set for the current token. Useful for clients and SDKs to introspect their environment.

{
  "caller": "agent:planner_v3",
  "tenant_id": "acme",
  "deployment_preset": "cloud_shared_saas",
  "token": {"jti": "01HX...", "iss": "...", "exp": 1715836800},
  "effective_capabilities": ["scope.write", "scope.read.holistic", "lifecycle.subscribe", "..."]
}

8.16.3 POST /v1/auth/tokens — Mint scoped tokens

Capability: auth.mint — 🔒 not in free-tier tokens (audit FRI-3). Free-tier signups can't mint child tokens; you'll get 403 POLICY_DENIED with "caller lacks auth.mint capability". This is by design — auth.mint is granted to operator/tenant-admin tokens on Starter+, or to any token on self-hosted on_prem_enterprise deployments.

Self-hosted (free): flip the deployment preset to on_prem_enterprise and you get auth.mint deployment-wide. Cloud: upgrade to Starter+ to get auth.mint on your tenant scope, or contact sales for an operator token if you're building multi-tenant infrastructure.

{
  "subject": "user:bob",
  "scope": "org:acme/team:design",
  "ttl_seconds": 3600,
  "caps": ["scope.read.local", "scope.write"]
}

Response: 200 with the minted token, or 403 when the caller lacks auth.mint, or 503 NOT_CONFIGURED when the deployment has no minter wired (e.g., dev_local without CORTEX_V1_MINTER_ENABLE=1).

8.17 Temporal Phrases

8.17.1 POST /v1/temporal/phrases

Capability: temporal.phrases.write (tenant admin)

Register a custom natural-language temporal phrase. See §12.4 for the parsing model.

{
  "name": "fiscal_q3",
  "pattern": "fiscal Q3",
  "resolves_to": {"valid_during": ["2026-07-01", "2026-10-01"]}
}

Response: 201 Created.

8.17.2 GET /v1/temporal/phrases

Capability: temporal.phrases.read (any authenticated reader)

{
  "items": [
    {"name": "fiscal_q3", "pattern": "fiscal Q3", "resolves_to": {...}}
  ]
}

8.17.3 DELETE /v1/temporal/phrases/{name}

Capability: temporal.phrases.write

8.18 GET /v1/experience/status — Write Status

Capability: scope.write (same auth as the write itself; keys are scoped per-caller, so one tenant can never probe another's keys).

Answers "did my write land, and how far has it progressed?" — the resume path after a client-side timeout, and the poll target for ?wait=captured async-accept writes.

GET /v1/experience/status?idempotency_key=<key>    # by key (24h window)
GET /v1/experience/status?event_id=evt_01HX...     # by event id

{
  "found": true,
  "event_id": "evt_01HX...",
  "status": "indexed",
  "stages_completed": ["captured", "extracted", "indexed"],
  "note": "stored and queryable"
}

status is "captured" | "indexed" | "failed". "failed" adds failure_reason and means: re-send the write with the same idempotency key — it will re-process (the record was dropped). found: false means never stored / expired (>24h) / failed-and-evicted — in every case re-sending is safe.

8.19 GET /v1/schemas — Machine-Readable Contracts

Unauthenticated (like /v1/admin/health). Lists and serves the normative JSON Schemas for every request/response shape, embedded in the binary at build time so the running server and its published contract cannot drift.

GET /v1/schemas                        → {"schemas": [{"name": "...", "url": "..."}]}
GET /v1/schemas/experience_envelope    → the JSON Schema (application/schema+json)
GET /v1/schemas/error_envelope         → the error envelope contract

Use these for client-side preflight validation before runtime — 422 responses reference the matching schema in details.schema.

9. The Stratified Pack

The output of POST /v1/recall in non-streaming mode.

{
  "request_id": "req_01HX...",
  "scope": "org:acme/dept:eng/user:alice",
  "view": "holistic",
  "context_block": "Acme is a B2B SaaS in late-stage negotiation. They moved to 200 seats on May 13, 2026 and signed. Prior history includes a successful POC in April and an executive intro in February.",
  "layers": {
    "beliefs": [
      {"id": "belief_01HX...", "claim": {...}, "confidence": 0.62, "ranked_position": 1, "score": 0.94}
    ],
    "facts": [
      {"id": "fact_01HX...", "subject": {...}, "predicate": "...", "object": {...}, "ranked_position": 1, "score": 0.91}
    ],
    "episodes": [
      {"id": "ep_01HX...", "name": "Acme deal Q3 close", "summary": "...", "ranked_position": 1, "score": 0.88}
    ],
    "events": [],
    "understanding": [
      {"id": "concept_01HX...", "name": "B2B SaaS Sales Cycle", "ranked_position": 1, "score": 0.42}
    ]
  },
  "provenance": {
    "trail": [
      {"phase": "ARIL_classify", "plan": "DIRECT_LOOKUP_RECHECK", "elapsed_ms": 12},
      {"phase": "hybrid_retrieve", "bm25_hits": 124, "hnsw_hits": 2000, "elapsed_ms": 88},
      {"phase": "rerank", "model": null, "elapsed_ms": 0},
      {"phase": "graph_expand", "added_nodes": 14, "elapsed_ms": 22},
      {"phase": "score", "weights": {"semantic": 0.4, "graph": 0.2, "recency": 0.15, "importance": 0.15, "confidence": 0.1}, "elapsed_ms": 4},
      {"phase": "mmr", "lambda": 0.7, "elapsed_ms": 6}
    ],
    "citations": {
      "belief_01HX...": ["fact_01HX...", "fact_01HX...", "ep_01HX..."],
      "fact_01HX...":   ["evt_01HX..."],
      "ep_01HX...":     ["evt_01HX...", "evt_01HX...", "evt_01HX..."]
    }
  },
  "diagnostics": {
    "policy": {"tier_attribution": "scope", "capability": "scope.read.holistic"},
    "filters_applied": ["actor.in", "confidence.gte"],
    "scopes_traversed": ["org:acme/dept:eng/user:alice", "org:acme/dept:eng", "org:acme"],
    "time_ms": {
      "auth": 3, "policy_check": 1, "recall": 412, "rerank": 0,
      "rank": 8, "render_context_block": 84, "total": 508
    },
    "_partial": false
  }
}

9.1 Views

9.2 Ranking and limits

budgets.per_layer_limits caps each layer's array (applied first), and budgets.max_tokens is a cross-layer token budget over the whole pack: lowest-priority items are evicted from the tail until it fits, with the count in diagnostics.knapsack_evictions. context_block is bounded to the same budget and never truncated mid-item. Degraded/partial retrieval is reported via diagnostics._partial and diagnostics.degraded_sources.

9.3 Citation map

provenance.citations is a directed acyclic graph from derived records back to events. Walking it gives the "why" trail for any item in the pack. The same data is reachable via /v1/beliefs/why for beliefs specifically.

10. Streaming

10.1 Granular streaming

Used for /v1/recall with stream=true (any view except narrative).

event: plan
data: {"plan": "DIRECT_LOOKUP_RECHECK", "filters_applied": [...]}

event: layer
data: {"layer": "facts", "items": [...], "elapsed_ms": 210}

event: layer
data: {"layer": "beliefs", "items": [...], "elapsed_ms": 315}

event: layer
data: {"layer": "episodes", "items": [...], "elapsed_ms": 488}

event: layer
data: {"layer": "understanding", "items": [...], "elapsed_ms": 612}

event: context_block
data: {"text": "Acme is a B2B SaaS in late-stage..."}

event: provenance
data: {"trail": [...], "citations": {...}}

event: diagnostics
data: {"time_ms": {...}, "scopes_traversed": [...]}

event: done
data: {"total_ms": 1042}

10.2 Narrative streaming

Used for /v1/answer with stream=true and /v1/recall with view=narrative&stream=true.

event: token
data: {"text": "Acme"}

event: token
data: {"text": " upgraded"}

event: token
data: {"text": " to 200"}

...

event: citations
data: [{"marker": "[1]", "layer": "fact", "id": "fact_01HX..."}, ...]

event: diagnostics
data: {"recall_ms": 412, "llm_ms": 814, "total_ms": 1240}

event: done
data: {}

10.3 Lifecycle streaming

Used for /v1/lifecycle/stream. Full event catalog in §13.

10.4 Reconnection and resume

Clients pass Last-Event-ID: lce_01HX... (standard SSE) or ?since_lifecycle_id=lce_01HX... on reconnect. The ID is a lifecycle event ID (lce_ prefix), not a memory event ID.

Server-side: every recall job's events are cached for 60s under the request's idempotency_key. Reconnect-with-resume replays from the next unsent event.

Lifecycle subscriptions support ?since_lifecycle_id=lce_01HX... for resume — server keeps a 1-hour replay buffer anchored from lifecycle-event arrival (§18.2 item 10). The window is "any lifecycle event whose server-side arrival timestamp is within the last hour is available for resume." Subscriber lifecycle (connect/disconnect timing) is irrelevant. Buffer is per-server-node; in cluster mode, replay across node failover may be incomplete for events that were in-flight during the failover.

10.5 Backpressure

We rely on HTTP/2 flow control. No application-level token bucket on streaming responses; we don't buffer events beyond the OS socket buffer.

If a client falls > 30s behind on a lifecycle stream, the connection is closed with event: lagging and they must reconnect with ?since=.

11. Forget Semantics

11.1 Cascade modes

11.2 Selector semantics

The selector block on /v1/forget is conjunctive:

{
  "about_entity": "ent_acme_corp",
  "predicate": "is_likely_to_renew",
  "memory_ids": [],
  "valid_during": ["2026-04-01", "2026-05-01"],
  "created_during": null
}

A record matches if ALL non-null filters match. Empty selector matches every record in the named layers within scope.

memory_ids is an "OR" with the other filters — if present, those IDs are deleted regardless of other filters (within the scope).

11.3 GDPR reference-counted erasure

Triggered by DELETE /v1/forget/gdpr. Five-phase pipeline.

Phase 1 — Enumerate. Walk WAL and find every event where author_actor matches the scope's owners OR home_scope ⊆ <scope>. Emit event: erasure_progress phase=enumerate.

Phase 2 — Refcount. For each candidate event E:

• refcount(E) = count of cross-scope citations to E from scopes NOT under the GDPR scope.
• Cross-scope citations come from: (a) derived records (facts/beliefs/episodes/understanding) in other scopes whose supports[] contains E, (b) explicit cross_scope_reference ledger rows.

Phase 3 — Categorize.

• delete_set = { E : refcount(E) == 0 }
• redact_set = { E : refcount(E) > 0 }

Phase 4 — Execute.

• For each E in delete_set: delete WAL entry, compact downstream indexes, remove from derives back-pointers in surviving events. Truly gone.
• For each E in redact_set:
  • Replace actor with redacted:gdpr_<erasure_id>
  • Replace content with {"kind": "redacted", "original_kind": "..."}
  • Keep id, wal_offset, scope, context.observed_at, context.recorded_at
  • For each entry in this event's derives[] that points to a record being deleted in the same erasure, replace the entry with redacted:<original_id> (e.g., redacted:fact_01HX...). See §18.2 item 2. This preserves the audit signal that something was derived without leaking what.
  • Mark all surviving derived records citing this E with supporting_evidence_redacted: true

Phase 5 — Demote. Any belief whose supporting_evidence_redacted_fraction == 1.0 is demoted: confidence decays by confidence_after_full_redaction_factor from policy (default 0.5), _partial: true with _partial_reason: "supporting_evidence_redacted". If the resulting confidence falls below tenant.confidence_floor (default 0.3), the belief is deleted.

Audit. A single audit row with gdpr: true, erasure_id, and a summary {deleted_events, redacted_events, deleted_facts, demoted_beliefs} is written. GDPR audit rows are exempt from normal retention TTLs.

11.4 Cross-workspace propagation

When forget.gdpr.cross_workspace is enabled and the actor exercising erasure is a member of cross-workspace scopes:

• Workspace scopes containing references to Alice's events are scanned.
• For each: same refcount logic, but the "outside the GDPR scope" set is updated to exclude the workspace itself if Alice was its sole owner.
• Workspaces co-owned by other actors retain the redacted evidence; Alice-only workspaces are fully deleted.

11.5 What forget does NOT do

• Does not affect audit log entries (audit is the immutable history of policy decisions, not memory content).
• Does not delete tokens (revoke separately via /v1/auth/revoke).
• Does not propagate to imported source systems (you must delete from Mem0/Zep/etc separately).

12. Temporal Model

12.1 Time axes

Two independent axes, four endpoints per axis:

valid_from ─────────────────── valid_to
              event time

recorded_from ─────────────── recorded_to
              ingest time

Events have observed_at and recorded_at as singletons.

12.2 Temporal query primitive

The temporal block on any layer read or recall:

{
  "temporal": {
    "as_of": "2026-04-15T00:00:00Z",
    "valid_during": ["2026-03-01", "2026-04-01"],
    "recorded_during": null,
    "natural": "last 30 days"
  }
}

Semantics:

• as_of pins both axes. recorded_* ≤ as_of, and valid_from ≤ as_of < valid_to. This answers "what did we believe at point T?"
• valid_during filters records whose [valid_from, valid_to) overlaps the range. recorded_* is pinned to now unless recorded_during is also set.
• recorded_during filters by ingest-time range only.
• natural is parsed server-side and reduced to valid_during. Supported phrases: "last N {days|weeks|months|years}", "yesterday", "this week", "between X and Y", "since X". Locale-aware. Anchored to request_time unless reference_date is also set.

12.3 As-of semantics

as_of defaults:

?include_superseded=true on layer reads disables the recorded_to=null filter, returning all historical versions.

12.4 Natural-language parsing

A small deterministic parser handles common phrases. Unparseable strings 422 with unparseable_temporal. Tenants can register custom phrase mappings:

POST /v1/temporal/phrases
{
  "name": "fiscal_q3",
  "pattern": "fiscal Q3",
  "resolves_to": {"valid_during": ["2026-07-01", "2026-10-01"]}
}

12.5 The bi-temporal record store (implemented)

The axes above are populated and enforced by the bi-temporal engine (BITEMPORAL_CONFLICT_DESIGN.md; crates/cortex-bitemporal). Rollout is mode-gated: CORTEX_BITEMPORAL_MODE = off | shadow (default) | enforce. In shadow mode the engine runs on every triple-derived fact, persists BITEMPORAL WAL events, detects conflicts, and exports coverage metrics — without changing legacy Fact fields. In enforce mode stated dates ground t_valid_from/t_valid_to (real world-time, not ingest time).

The record-level query surface:

• GET /v1/claims?scope=&subject=&predicate=&valid_as_of=&known_as_of= — the two-axis point query ("what was true at X, as known at Y"). valid_during=start..end / recorded_during=start..end switch to interval-overlap mode.
• GET /v1/claims/history?scope=&subject=&predicate= — the full change-log of one claim: every valid interval, every record-time correction, plus its conflicts.
• GET /v1/conflicts?scope=&status=open|all / GET /v1/conflicts/{id} / POST /v1/conflicts/{id}/resolve (pick | split | new_information | dismiss) — the conflict queue and manual resolution (§5.4 of the design). Every resolution is an audited, append-only WAL event.
• GET /v1/beliefs/history?belief_id= and GET /v1/concepts/{id}/history — semantic-delta version history (§5.3): superseded versions carry temporal.recorded_to closed.

Every finite validity boundary carries a basis: stated (the source asserted the world date — render "on/since ") or observed (we bounded it by when we learned it — render "by ", never "on"). This is how undated state changes stay honest.

13. Lifecycle Events Catalog

All events delivered via SSE on /v1/lifecycle/stream. Every event has event_id, timestamp, scope, and an event-specific payload.

Filtering: ?events=captured,consolidated to subscribe to a subset.

14. Audit Log Schema

Every policy-gated call writes one row. Schema:

{
  "id": "audit_01HX...",
  "ts": "2026-05-13T15:42:09.018Z",
  "actor": "agent:planner_v3",
  "token_jti": "...",
  "tenant_id": "acme",
  "scope": "org:acme/dept:eng/user:alice",
  "endpoint": "POST /v1/experience",
  "capability": "scope.write.elevated",
  "decision": "allow",
  "decided_by_tier": "scope",
  "request": {
    "method": "POST",
    "path": "/v1/experience",
    "body_hash": "sha256:abc...",
    "headers_hash": "sha256:def...",
    "body_bytes": 4823
  },
  "response_status": 202,
  "event_id": "evt_01HX...",
  "client_ip": "1.2.3.4",
  "user_agent": "cortex-py/1.0.0",
  "request_id": "req_01HX...",
  "elapsed_ms": 12,
  "gdpr": false
}

Hashes:

• body_hash = sha256(body || tenant_pepper) — per-tenant pepper prevents cross-tenant rainbow attacks
• headers_hash = sha256(canonicalized_headers_minus_Authorization || tenant_pepper)

tenant_pepper_version is rotated quarterly. Old peppers are retained for audit.retention + audit.pepper_retention_buffer (default P3M buffer) so any audit row hashed under that pepper remains verifiable for the duration of its retention window plus the safety margin. See §18.2 item 11.

Body bytes storage. The body_bytes field is controlled by tenant setting audit.store_body_bytes (default true; see §18.2 item 15). When false, the audit row omits the field but retains the hash.

Retention:

• Default 2 years.
• gdpr: true rows: never deleted.
• Configurable per tenant: 90 days minimum, 7 years maximum.

Storage: Audit rows are appended to a dedicated RocksDB column family + mirrored to Tantivy for search. Not indexed in HNSW; not part of the recall pipeline.

15. Importer Mappings

15.1 Mem0

Graph memory (legacy v1 exports only): edges become Facts with predicate= the edge label.

15.2 Zep

15.3 Letta

15.4 OpenAI memory export

Format: ChatGPT's JSON dump.

15.5 Generic JSONL

Each line MUST be a full experience envelope. No mapping needed.

{"scope":"...", "actor":{...}, "modality":"...", "content":{...}, "context":{...}}
{"scope":"...", "actor":{...}, "modality":"...", "content":{...}, "context":{...}}

16. Error Catalog

Selected entries. Full list maintained at docs/errors/.

17. Compatibility Matrix

Framing. Peer systems are not flat. Mem0 has conversation/session/user/org scopes with filter/rerank operators; Zep ships bi-temporal facts on graph edges plus context blocks plus semantic/full-text/graph retrieval; Letta has tiered memory tools and shared blocks; Cognee has 14 search strategies. CortexDB's differentiation is not "they're simple, we're rich." It is event-sourced provenance, all-layer first-class access, policy with attribution, lifecycle observability, and reference-counted erasure — the rows below reflect that re-framing. We also benchmark our ergonomics against Supermemory's "raw content in + customId + tags" simple-SDK happy path: CortexDB keeps the rich contract, but the SDK MUST offer a one-liner experience for the happy path.

(⚠️ = partial / different shape; ❌ = absent; ✅ = present)

Reading the matrix. The right way to look at CortexDB vs the field is not "do they have it" but "is it observable, addressable, and explainable through the API." Mem0 has reranking — but you cannot ask why a result ranked where it did. Zep has bi-temporal facts — but only on facts. Letta has shared memory — but no policy. Our bar: every claim has a trail, every trail has an endpoint, every endpoint has a stability tier.

18. Deferred Decisions & Open Ambiguities

18.1 Deferred (intentionally out of v1)

1. Federation / multi-region replication API. Cluster mode exists internally; the API contract for cross-region writes is deferred until we have a paying customer that needs it.
2. Differential privacy on recall. Mentioned by enterprise prospects; not standard enough to commit a shape.
3. Vector store BYO. Letting customers point at their own pgvector / Pinecone. Out of v1 scope.
4. Memory editing tool surface for agents. Letta's tool-callable memory editing is interesting but conflicts with our "events are immutable" stance. Could ship as a higher-level shim that maps tool calls to experience + forget; deferred.
5. Webhook (push) lifecycle in addition to SSE. SSE covers most use cases; webhooks add infra (retries, signing). Deferred until requested.
6. GraphQL surface. REST + SDK feels sufficient; GraphQL adds maintenance burden. Deferred.

18.2 Resolved Ambiguities (formerly "Open before Implementation")

All 22 items from the prior round of disambiguation have been resolved on 2026-05-14. Each item below states the canonical resolution that the schemas and prose sections of this document have been updated to reflect. These are normative — if the schemas or prose disagree, the schemas win; if both disagree with this section, this section is authoritative for design intent.

The Stable surface gating list at the bottom of the prior version is cleared. Phase 1 of §19 is unblocked.

1. as_of × include_superseded interaction (Stable: §8.7.3 facts). Resolved: both filters apply independently and conjunctively. as_of clips both axes (recorded_* ≤ as_of, valid_from ≤ as_of < valid_to). include_superseded toggles whether the recorded_to=null constraint is enforced — when true, superseded versions whose recorded_to ≤ as_of are returned alongside the current versions. Conformance: schema fact.schema.json declares both query params; an integration test pair exists in §12 examples.

2. Orphan derives[] back-pointers after GDPR redaction (Experimental: §11.3). Resolved: option (c). When a derived record is deleted by GDPR and its source event is redacted-but-kept, the event's derives[] entries pointing at the deleted record are replaced with redacted:<original_id> (e.g., redacted:fact_01HX...). This preserves the audit signal that something was derived without leaking what. Conformance: event.schema.json derives entries match pattern ^(evt_|ep_|fact_|belief_|concept_|redacted:[a-z]+_)[A-Za-z0-9_-]+$.

3. Lifecycle event ordering within a single event_id (Stable: §8.9, §13). Resolved: strict ordering within one memory event. The stages for any single evt_<id> are emitted in fixed order: captured → extracted → indexed → consolidated → (optionally) compressed. No cross-event ordering guarantee. Conformance: SSE delivery has a per-event sequence number; an SSE conformance test validates monotonicity within event_id.

4. view=descend with partial read access (Stable: §8.3 recall). Resolved: option (b) — opaque placeholders with count-only stats. When admin descends into a tree containing child scopes the caller cannot read, the response's scopes_traversed includes {scope, denied: true, item_count: N, denied_reason} entries. Counts reveal existence without leaking content; denied_reason cites the policy tier. Conformance: stratified_pack.schema.json scopes_traversed[] item is a discriminated union over {scope, items} and {scope, denied, item_count, denied_reason}.

5. "Natural level" for scope.write.elevated (Stable: §5.2). Resolved: the deepest scope path in which the caller appears as an explicit owner or writer member. Writes to any scope at or below this depth do not require scope.write.elevated; writes to ancestor scopes do. For unregistered scopes (no membership), the caller's natural level is null and any write requires the capability. Conformance: capability_set.schema.json includes natural_level: scope-path | null.

6. Bulk import rate-limit attribution (Beta: §8.11). Resolved: synthetic per-tenant bucket service:importer_<tenant_id>, with default capacity = 10× the rate_limit.write value from the deployment preset. Importer-job submissions consume from this bucket; the originating caller's personal bucket is not charged. Override via tenant policy rate_limit.importer. Conformance: policy.schema.json allows rate_limit.importer override.

7. Cancellation of in-flight async writes (Stable: §8.1). Resolved: ship POST /v1/lifecycle/memory-event/{evt_id}/cancel. Drops queued stages (extract, index, consolidate, compress). The WAL capture itself cannot be reversed (it has already happened). The cancellation marks the event as excluded_from_recall: true; it remains queryable directly via GET /v1/events/{evt_id} but does not surface in /v1/recall or /v1/answer. Endpoint added to §8.9; see §8.9.5 below.

8. _partial: true outside Understanding (Beta: §7.4 Belief). Resolved: the _partial/_partial_reason/_progress triple is promoted to every derived layer (Episode, Fact, Belief, Understanding). Events never carry these fields. Each layer's enum of _partial_reason values is its own (e.g., Belief uses revision_in_progress, supporting_evidence_redacted, calibration_stale; Understanding uses consolidation_in_progress, insufficient_supporting_facts, etc.). Conformance: each layer schema declares the fields and its specific reason enum.

9. idempotency_key collision scope (Stable: §6.3). Resolved: scope is (scope, caller, endpoint_family, key), where scope is the full scope path the write targets (org:acct_46/team:eng/user:alice). Keys are therefore independent across tenants even when the tenants share one caller identity (a single deployment API key writing into many org: scopes): cross-tenant reuse of a key is a plain miss, never a 409 IDEMPOTENCY_CONFLICT, and a conflict body can only ever carry an existing_event_id from the requester's own tenant (v0.7.8 bug_12). Since v0.8.20 the namespace is the whole path rather than just its tenant root, so two sibling scopes under one tenant are also independent: writing the same item into …/project:a and …/project:b stores both, where it previously 409'd the second (report C4). Records written by an earlier binary still replay a genuine retry for the remainder of their 24h TTL, but never produce a conflict. Endpoint family buckets by logical write resource, not raw path: /v1/experience and /v1/experience/bulk share ONE family (v0.7.9 report F3 — they are two transports for the same write, so a retry that switches single↔bulk, or a proxy that coalesces single writes into a batch, replays instead of double-storing); /v1/import/mem0 and /v1/import/zep remain separate (the same external id from two sources is two writes, not a retry); /v1/erasures and /v1/erasures/preview are separate. GET /v1/experience/status?idempotency_key= accepts an optional scope= for an exact probe — it must be the SAME scope the write named, since that is the namespace the record lives under; without it, all of the calling actor's own namespaces are searched (never another caller's).

10. SSE replay buffer window (Stable: §10.4). Resolved: anchored from lifecycle-event arrival at the server. The 1-hour window means "any lifecycle event whose server-side arrival timestamp is within the last hour is available for resume via ?since_lifecycle_id=." Subscriber lifecycle (when they connected, when they disconnected) is irrelevant. Buffer is per-server-node; in cluster mode, replay across node failover may be incomplete for events that were in-flight during the failover.

11. Tenant pepper rotation (Stable: §14). Resolved: peppers rotate quarterly. Old peppers are retained for audit.retention + 1 quarter — i.e., for as long as any audit row hashed under that pepper might still be present (plus a one-quarter safety margin for verification). When audit.retention = P2Y, peppers persist for ~2.25 years. Conformance: policy.schema.json deployment-level audit.pepper_rotation_period (default P3M) and audit.pepper_retention_buffer (default P3M).

12. directives.consolidate_into cross-scope write (Stable: §3.5, §8.1). Resolved: dual capability required — scope.write on both the write scope and the consolidation target. No implicit elevation. If the caller lacks scope.write on the consolidation target, the envelope is rejected at validation time (422 INVALID_ENVELOPE, details.field = "directives.consolidate_into").

13. Empty-selector forget (Stable: §8.5). Resolved: POST /v1/forget with empty selector (all filter fields null/empty AND memory_ids: []) requires confirm_all: true. Without it, 422 EMPTY_SELECTOR_WITHOUT_CONFIRMATION. Schema validation rule: selector is "empty" iff selector.about_subject ∈ {null, ""} ∧ selector.about_entity ∈ {null, ""} ∧ selector.predicate ∈ {null, ""} ∧ selector.memory_ids = [] ∧ selector.valid_during = null ∧ selector.recorded_during = null.

14. Default view on layer reads (Stable: §8.7). Resolved: default is local for all GET /v1/events|episodes|facts|beliefs|understanding. Principle of least surprise: a caller passing a scope gets exactly that scope. To aggregate up the tree, they must pass view=holistic explicitly. The /v1/recall endpoint is the only one whose default is holistic (rationale: recall is intent-aware; layer reads are not).

15. Audit row body_bytes (Stable: §14). Resolved: add tenant-level setting audit.store_body_bytes (boolean), defaulting to true. When false, the audit row omits the field. Preset defaults: on_prem_enterprise = true, cloud_shared_saas = true (overridable per tenant), cloud_private = true, dev_local = true. Conformance: audit_row.schema.json makes body_bytes optional.

16. Belief deletion threshold behavior (Beta: §7.4). Resolved: confirmed as documented. When confidence < tenant.confidence_floor (default 0.3), the belief record is deleted (not soft-deleted, no tombstone). Direct ID lookup at GET /v1/beliefs/{id} returns 410 RESOURCE_DELETED. List endpoints (GET /v1/beliefs?...) silently omit deleted beliefs. The audit_id of the deletion is recorded in the audit log.

17. view=raw and temporal filters (Stable: §8.3, §9). Resolved: for view=raw (events-only response), recorded_during and as_of apply (to recorded_at on events); valid_during is ignored with no error (events have no validity interval, so the filter is a no-op). A valid_during filter present in a view=raw request causes X-Cortex-Warning: valid_during_ignored_for_view_raw to be set on the response.

18. Multimodal embedding strategy (Stable: §3.5). Resolved: v1 ships text-only embeddings. Image and other binary blobs are indexed by metadata (content-type, size, perceptual hash) and reachable via blob_id, but not embedded into the semantic vector space. Multimodal embedding is a v1.x add-on; the API contract is forward-compatible (envelope content.media[] is already structured to accept additional indexing hints).

19. Capability scope.create.* granularity (Stable: §5.2). Resolved: the enumerated scope.create.<type> set is closed at the deployment policy tier. The default set is {org, user, agent, service, ws, project, team, dept, global, system}. Operators may extend the set via the deployment YAML's allowed_scope_types. Any user-defined scope type not in the allowed set is rejected at scope registration time with 422 UNREGISTERED_SCOPE_TYPE. A single capability scope.create.custom controls whether custom (non-builtin) types may be registered at all.

20. use_pack_id lifetime in /v1/answer (Stable: §8.4). Resolved: 60 seconds from pack creation, no extension on reuse. Consistency over caching efficiency. After 60s the pack ID is invalid; the caller must re-run recall.

21. pack_id and stateless recall (Stable: §8.3, §8.4). Resolved: ephemeral, 60s server-side TTL, not a stable client handle. Clients that need durable references should extract and store the constituent evt_/fact_/belief_/... IDs from provenance.citations immediately after receiving the pack.

22. Error envelope casing consistency (Stable: §6.6, §16). Resolved 2026-05-14: unified on error_code (UPPER_SNAKE) as the single error identifier field; lower-snake error field retired. See §6.6. Normative source: error_envelope.schema.json.

Resolution discipline going forward. Any future contract change that is non-additive against a Stable endpoint requires:

1. An entry in this section documenting the prior behavior, the new behavior, and the rationale.
2. A schema update in docs/schemas/.
3. An updated example in the affected endpoint section.
4. A regression test under tests/api_contract/.
5. A bump of X-Cortex-Stability to stable-revising for one minor release before the change becomes default.

19. Implementation Order

Updated 2026-05-14 to match the grounded gap analysis (docs/GAP_ANALYSIS.md). The earlier numbered plan was theoretical; this version is informed by what actually exists in the codebase. Each phase is shippable in isolation; phases 1-3 are prerequisite (they reshape the contract). Estimated cumulative time: 10-14 weeks at full focus; the agent's gap-analysis estimate of 19 weeks is the conservative upper bound.

Phase 1 — Foundation (Weeks 1-2)

Goal: every request authenticates, identifies three actors, names a scope, and gets a policy decision with attribution.

• PASETO v4 public + JWT (RS256, ES256 only) token verifier
• Scope path parser + canonical form + grammar enforcement (ABNF in Appendix B)
• Auto-registration on first write
• Three-identity extraction (caller from token; observed_actor and subject from envelope)
• Four-tier policy evaluator skeleton (deployment + tenant tiers wired up; scope and actor tiers stubbed for phase 7)
• X-Cortex-Policy header on every response with tier, decision, capability
• Deployment-preset loader (reads crates/cortexdb/presets/*.yaml)
• Capability catalog enum + intersection logic
• GET /v1/policy/effective, GET /v1/policy/deployment
• GET /v1/auth/whoami, POST /v1/auth/revoke

Phase 2 — Core Memory Layers (Weeks 3-4)

Goal: every layer has its full record shape in storage, even if the layer's full pipeline isn't running yet.

• Facts: triple storage (subject, predicate, object), bi-temporal (valid_from/to, recorded_from/to), supersession chain, confidence + extractor identifier
• Beliefs: stance enum, confidence_interval, calibration, weighted supports with polarity, revision_policy, _partial reasons
• Understanding: concept nodes, versioning, edges, derived_from/canonical_id for split/merge, staleness + coverage scores (synthesizer stub returns _partial: true with _partial_reason: no_implementation_yet)
• Lifecycle event types (5 stages: Capture, Extract, Index, Reconcile, Compress) defined in cortex-types
• _partial triple promoted to every derived layer (per §18.2 item 8)

Phase 3 — Async Write Pipeline (Week 5)

Goal: write path returns 202 on capture, derives asynchronously, exposes wait modes.

• POST /v1/experience accepts the new envelope shape (three identities, scope path, observed_at, directives, idempotency_key)
• WAL append becomes the synchronous part; everything else queues to background workers
• wait=captured|indexed|consolidated modes
• POST /v1/experience/bulk (single + bulk paths share the worker pool)
• Idempotency deduplication (key scope: (scope, caller, endpoint_family, idempotency_key) — the full scope path, §18.2 item 9)
• directives.consolidate_into cross-scope write validation (dual capability check, §18.2 item 12)

Phase 4 — Stratified Recall (Week 6)

Goal: recall returns a stratified pack, not a flat context string.

• POST /v1/recall returns {pack_id, context_block, layers, provenance, diagnostics}
• View modes: raw, granular, holistic, structured (narrative deferred to phase 13)
• Per-layer budgets + exclude_content + citation_mode
• temporal block parser including as_of, valid_during, recorded_during, natural
• Provenance trail (every phase, every elapsed_ms, every filter applied)
• provenance.citations map (derived-record → events trail)
• pack_id 60s TTL cache for /v1/answer use_pack_id reuse

Phase 5 — Lifecycle + SSE (Week 7)

Goal: the async pipeline is observable in real time.

• Lifecycle event log (new RocksDB column family or dedicated event store)
• lce_ ID namespace
• GET /v1/lifecycle/stream (SSE) with since_lifecycle_id resume, 1h server-side buffer (§18.2 item 10)
• GET /v1/lifecycle/event/{lce_id}, GET /v1/lifecycle/memory-event/{evt_id}, paginated catch-up
• POST /v1/lifecycle/memory-event/{evt_id}/cancel (drops queued stages, §8.9.5)
• Emit lifecycle events at every pipeline stage hand-off

Phase 6 — Layer Reads (Week 8)

Goal: every layer has its own GET endpoint.

• GET /v1/events (with derives[], labels filtering, default view=local)
• GET /v1/episodes (with causal_chain tagging)
• GET /v1/facts, GET /v1/facts/timeline (with as_of × include_superseded semantics, §18.2 item 1)
• GET /v1/beliefs, GET /v1/beliefs/why (with the full support graph + narrative)
• GET /v1/understanding, /{id}, /{id}/related, /coverage (all returning _partial: true until phase 11)

Phase 7 — Scopes + ACL (Week 9)

Goal: scope registration, member ACLs, holistic reads with denied placeholders.

• POST /v1/scopes, GET /v1/scopes?path=..., PUT /v1/scopes/members?path=..., DELETE /v1/scopes?path=...
• Scope tier of the policy stack wired up (members, roles, inheritance)
• Holistic read traversal (view=holistic walks up; view=descend walks down with denied placeholders, §18.2 item 4)
• 403 NOT_A_MEMBER denials with tier attribution
• Auto-provisioned vs explicitly-registered tracking

Phase 8 — Forget + Erasures (Weeks 10-11)

Goal: hard delete works in proportional + reference-counted modes.

• POST /v1/forget with derived_only + redact_events cascades
• Selector grammar (about_subject, about_entity, predicate, memory_ids, valid_during, recorded_during)
• confirm_all flag for empty-selector forget (§18.2 item 13)
• POST /v1/erasures/preview (refcount breakdown + delete/redact split returned inline)
• POST /v1/erasures (executes), GET /v1/erasures/{id}, POST /v1/erasures/{id}/cancel
• Reference-counted erasure pipeline (§11.3): enumerate → refcount → categorize → delete/redact → demote
• Belief demotion logic when supporting evidence is fully redacted
• Orphan derives[] replacement with redacted:<id> markers (§18.2 item 2)

Phase 9 — Audit + Compliance (Week 12)

Goal: every policy decision is tamper-evidently logged.

• Audit log writer (RocksDB CF + Tantivy mirror)
• Per-tenant pepper rotation (P3M default, retention buffer P3M, §18.2 item 11)
• Body + headers hash (sha256(body || pepper))
• audit.store_body_bytes tenant setting (§18.2 item 15)
• GET /v1/audit, GET /v1/audit/{audit_id}, POST /v1/audit/verify
• audit.read.cross_actor capability enforcement

Phase 10 — Imports + Exports (Weeks 13-14)

Goal: customers can move data in and out.

• POST /v1/import/jsonl first (smallest; generic envelope ingest)
• POST /v1/import/mem0 (mapping per §15.1)
• POST /v1/import/zep (preserves bi-temporal per §15.2)
• POST /v1/import/letta (Agent File .af per §15.3)
• POST /v1/import/openai (ChatGPT export per §15.4)
• Order modes (strict_temporal vs batch_throughput)
• Per-tenant importer rate-limit bucket (§18.2 item 6)
• POST /v1/export for each format, async destination routing (URL or inline)
• Bidirectional round-trip tests

Phase 11 — Understanding Synthesizer (Weeks 15-16)

Goal: drop _partial: true on the Understanding layer.

• Real concept synthesis pipeline (consolidation stage)
• Coalescence, splitting, version chaining
• Coverage + staleness scoring jobs
• POST /v1/understanding/synthesize (admin-triggered re-synthesis)
• GET /v1/understanding/coverage
• Vocabularies for relation labels (vocabulary.read/write capabilities)

Phase 12 — Vocabularies + Temporal Phrases + Blobs (Week 17)

• POST/GET/PUT /v1/vocabularies/...
• POST/GET/DELETE /v1/temporal/phrases/...
• POST /v1/blobs, GET /v1/blobs/{blob_id} (raw-byte upload, text-only embedding for v1)
• POST /v1/scopes/prune cleanup automation

Phase 13 — Streaming + Narrative (Weeks 18-19)

Goal: streaming surfaces for the experimental tier.

• Streaming recall (POST /v1/recall stream=true) — granular per-layer SSE
• Streaming answer (POST /v1/answer stream=true) — token-by-token
• Narrative view (view=narrative)
• use_pack_id answer reuse (60s TTL)

Risk gates between phases

19.1 Benchmark Regression Bar

Concrete thresholds for any PR that touches the read or write pipeline (and therefore could regress retrieval quality).

LongMemEval-S (full 500 questions):

• Floor: 92.5% (≥462/500 correct)
• Shipped baseline: 93.8% (commit 83ca464, 2026-05-08)
• Tolerance: 1.3 percentage points
• Bench command: benchmarks/longmemeval/reproduce.sh
• CI gate: PR may not merge if the bench reports below the floor.

LoCoMo (categories 1-4, judge score):

• Floor: 83.5%
• Recovered baseline: 85.5% (2026-05-11)
• Tolerance: 2.0 percentage points
• Bench command: python benchmarks/locomo/run_locomo.py then llm_judge_memori.py
• CI gate: Same.

Recovery PRs. A PR may merge below the floor if and only if it is explicitly tagged regression-fix and the previous (last-green) commit is identified. The next non-fix PR must restore the bar.

Latency budgets (informational, not gating for v1):

• Recall p50 ≤ 3500ms (currently ~2882ms; we have headroom)
• Answer p50 ≤ 8500ms end-to-end
• Capture (sync portion of /v1/experience) p50 ≤ 50ms

These are tracked in docs/LATENCY_BASELINE.md; deviations beyond 20% trigger a perf-review checkbox on the PR.

Cost budget:

• Per-question LongMemEval-S cost ≤ $0.10 (currently ~$0.10 at 93.8%; this is a hard cap)
• Recovery PRs may temporarily exceed; restore within two PRs.

What is NOT in the bar. Code-correctness tests, API contract tests, and unit tests live separately and are not part of this gate — they are independent merge requirements. The regression bar is specifically about retrieval and answer quality.

20. Appendices

Appendix A: Capability Reference (Full)

Defaults per preset. Y = allowed, N = denied, ~ = configurable per tenant default.

Y(op) = operator-only (deployment-tier admin).

Appendix B: Scope Path Grammar (ABNF)

scope         = segment *( "/" segment )
segment       = type ":" id
type          = ALPHA *( lowercase / DIGIT / "_" )
id            = 1*( ALPHA / DIGIT / "_" / "-" )
ALPHA         = %x61-7A   ; a-z
lowercase     = %x61-7A
DIGIT         = %x30-39

Constraints:

• 1 ≤ segments ≤ 32
• 1 ≤ total length ≤ 4096
• type ≤ 32 chars; id ≤ 128 chars

Appendix C: Sample Token (PASETO v4 public)

Decoded payload:

{
  "iss": "https://auth.acme.com/cortexdb",
  "sub": "agent:planner_v3",
  "aud": "cortexdb:tenant:acme",
  "exp": 1715836800,
  "iat": 1715750400,
  "jti": "01HX...",
  "deployment": "cloud_shared_saas",
  "caps": [
    "scope.write",
    "scope.read.local",
    "scope.read.holistic",
    "lifecycle.subscribe"
  ],
  "scopes": [
    "scope.write:org:acme/dept:eng/*",
    "scope.read.holistic:org:acme/*"
  ]
}

Appendix D: JSON Schemas (Normative)

Status: normative. The schemas in docs/schemas/ define the contract. Where this prose spec disagrees with a schema, the schema wins. SDK code generators, request validation middleware, and server-side validators all run against these files. Spec text is explanatory; schemas are authoritative.

Schemas (JSON Schema draft 2020-12):

Change discipline. A schema change accompanies every breaking change in this doc, in the same PR. CI fails if the schemas don't validate the examples in this spec.

Appendix E: SDK shape (illustrative, Python)

client = CortexClient(
    base_url="https://api-v1.cortexdb.ai",
    token_provider=OktaTokenProvider(...),
)

# Write
res = client.experience(
    scope="org:acme/dept:eng/user:alice",
    modality="conversation",
    content={"kind": "message", "role": "user", "text": "..."},
    context={"happened_at": "...", "recorded_at": "..."},
    wait="indexed",
)
print(res.event_id, res.stages_completed)

# Recall (stratified pack)
pack = client.recall(
    scope="org:acme/dept:eng/user:alice",
    view="holistic",
    query="What did we decide about Q3?",
    layers=["beliefs", "facts", "episodes"],
    temporal={"natural": "last 30 days"},
)
print(pack.context_block)
for b in pack.layers.beliefs:
    print(b.claim, b.confidence)

# Why
why = client.beliefs.why(belief_id="belief_01HX...")
print(why.narrative)

# Streaming recall
async for chunk in client.recall_stream(
    scope="...", view="narrative", query="...",
):
    print(chunk.text, end="", flush=True)

# Forget
client.forget(
    scope="org:acme/user:alice",
    layers=["beliefs"],
    selector={"about_entity": "ent_acme_corp"},
    cascade="derived_only",
)

# GDPR
job = client.forget_gdpr(scope="org:acme/user:alice", audit_note="DSR #1234")
async for ev in client.lifecycle(erasure_id=job.erasure_id):
    print(ev)

Sign-off

This spec is the contract we will implement against. Each phase in §19 ships an internally consistent slice; the spec evolves only through explicit revision PRs that update this file and the schemas in Appendix D in lockstep.

Open items (acknowledged):

• The Understanding layer remains partial in v1; the API surface is honest about it via _partial.
• Federation, BYO vector store, GraphQL, and webhook lifecycle are deferred (§18).
• All deployment-policy presets ship YAML examples in crates/cortexdb/presets/ (TBD by phase 1).