POST /v1/remember

Store an episode in CortexDB. The episode is appended to the immutable event log and acknowledged synchronously. Entity extraction, embedding, and graph updates happen asynchronously.

Request

POST /v1/remember
Content-Type: application/json
Authorization: Bearer <api-key>

Body

{
  "tenant_id": "my-app",
  "namespace": "engineering",
  "episode": {
    "type": "message",
    "content": "We decided to use gRPC for internal APIs. REST will remain for public-facing endpoints.",
    "source": "slack",
    "author": "alice",
    "channel": "#architecture",
    "timestamp": "2026-03-15T10:30:00Z",
    "metadata": {
      "thread_id": "1234567890",
      "reaction_count": 5
    }
  },
  "idempotency_key": "slack-msg-1234567890"
}

Parameters

| Field | Type | Required | Description | |---|---|---|---| | tenant_id | string | Yes | Tenant identifier | | namespace | string | No | Namespace within tenant | | episode | object | Yes | Episode data (see below) | | idempotency_key | string | No | Prevents duplicate writes. Same key = same result. |

Episode Object

| Field | Type | Required | Description | |---|---|---|---| | type | string | Yes | message, document, code, event, decision, task, observation | | content | string | Yes | Episode text content (max 100KB) | | source | string | No | Source system (e.g., slack, github, jira) | | author | string | No | Author identifier | | channel | string | No | Channel or context | | timestamp | string | No | ISO 8601 timestamp (defaults to server time) | | metadata | object | No | Arbitrary key-value pairs |

Response

Status: 201 Created

{
  "event_id": 42,
  "episode_id": "ep_a1b2c3d4",
  "timestamp": "2026-03-15T10:30:01.234Z"
}

| Field | Type | Description | |---|---|---| | event_id | integer | Monotonically increasing event ID in the log | | episode_id | string | Unique episode identifier | | timestamp | string | Server-assigned timestamp |

Errors

| Status | Code | Description | |---|---|---| | 400 | validation_error | Missing required fields or invalid episode type | | 401 | authentication_error | Invalid or missing API key | | 413 | payload_too_large | Content exceeds 100KB limit | | 429 | rate_limit | Too many requests |

Example

curl -X POST https://api.cortexdb.io/v1/remember \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "episode": {
      "type": "decision",
      "content": "Chose CockroachDB for the payments service. Rationale: multi-region support, PostgreSQL compatibility.",
      "source": "meeting-notes",
      "author": "prashant",
      "timestamp": "2026-03-15T10:00:00Z"
    }
  }'

Notes

• The write is durable once you receive a 201 response. The episode is safe on disk.
• Entity extraction and graph updates happen asynchronously. Newly extracted entities may take a few seconds to appear in recall results.
• Use idempotency_key for exactly-once semantics when retrying failed writes.