Audit Logging

Cortex logs every read, write, and denial to an append-only audit trail. This ensures complete provenance tracking for compliance and debugging.

Audit Entry Structure

{
  "id": "uuid",
  "org_id": "uuid",
  "actor_type": "agent",
  "actor_id": "uuid",
  "on_behalf_of": "uuid",
  "action": "recall",
  "target_id": "uuid",
  "scope_key": "engineering",
  "result": "allowed",
  "tokens_in": 45,
  "tokens_out": 320,
  "created_at": "2025-01-15T10:30:00Z"
}

Fields

Action Types

What Gets Logged

graph TB
    A[Agent Request] --> B{Policy Check}
    B -->|Allowed| C[Execute Operation]
    B -->|Denied| D[Log Denial]
    C --> E[Log Success]
    E --> F[Audit Trail]
    D --> F

Every operation logs:

1. Who — Actor identity and the user they're acting for
2. What — Action type and target memory
3. Where — Scope accessed
4. Result — Allowed or denied
5. Tokens — Input/output token counts (for AI queries)
6. When — Timestamp

Who can read the audit log

The audit trail spans every scope and actor in the org, so it is treated as administrative governance data: only the workspace owner (CEO) can view or export it (GET /api/audit, /api/audit/export). Lower roles receive a 403 and the Audit Log entry is hidden from their navigation — the same owner-only gate applied to the Policy matrix and Scopes. This prevents a lower-clearance member from learning about activity in scopes they cannot otherwise read.

Querying Audit Logs

# List recent entries
curl -H "Authorization: Bearer crtx_..." \
  https://your-cortex-host/api/audit?limit=100

# Filter by action
curl -H "Authorization: Bearer crtx_..." \
  "https://your-cortex-host/api/audit?action=recall&result=denied"

Compliance Properties