Audit Trail

CortexDB logs every API operation for compliance, security monitoring, and debugging. Audit logging is enabled by default.

What Is Logged

Every API request generates an audit entry:

| Field | Description | |---|---| | timestamp | When the operation occurred | | operation | API operation (remember, recall, forget, search, link) | | tenant_id | Tenant identifier | | namespace | Namespace (if applicable) | | api_key_id | Which API key was used | | source_ip | Client IP address | | user_agent | Client user agent | | request_id | Unique request identifier | | status | success or error | | error_code | Error code (if failed) | | latency_ms | Request processing time | | episode_id | Episode ID (for write operations) | | result_count | Number of results (for read operations) |

Querying Audit Logs

# List audit entries
curl https://api.cortexdb.io/v1/admin/audit \
  -H "Authorization: Bearer admin-api-key" \
  -G -d "tenant_id=acme-corp" \
  -d "after=2026-03-01T00:00:00Z" \
  -d "operation=forget" \
  -d "limit=100"

Response

{
  "entries": [
    {
      "timestamp": "2026-03-15T10:30:01Z",
      "operation": "forget",
      "tenant_id": "acme-corp",
      "api_key_id": "key_abc123",
      "source_ip": "10.0.1.50",
      "request_id": "req_xyz789",
      "status": "success",
      "latency_ms": 5,
      "episode_id": "ep_forgotten_001",
      "metadata": {
        "reason": "user_requested"
      }
    }
  ],
  "total": 1
}

Audit Log Export

Export audit logs for external analysis:

cortexdb-cli audit-export \
  --after 2026-03-01 \
  --before 2026-04-01 \
  --output audit-march-2026.ndjson

Configuration

| Variable | Default | Description | |---|---|---| | CORTEX_AUDIT_LOG_ENABLED | true | Enable audit logging | | CORTEX_AUDIT_LOG_RETENTION_DAYS | 365 | Audit log retention period | | CORTEX_AUDIT_LOG_INCLUDE_QUERY | false | Include query text in audit (privacy consideration) |

Integration with SIEM

CortexDB audit logs can be forwarded to your SIEM system. Logs are available in structured JSON format via the export API or by tailing the audit log file at $CORTEX_DATA_DIR/audit/audit.log.