> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thrindex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store a memory

> POST /v1/memories — enqueue a memory for async processing.

## `POST /v1/memories`

Enqueue a memory for asynchronous processing by the cognition worker. Returns immediately with `202 Accepted` and the assigned memory UUID.

**Required scope:** `memory:write`

***

## Request

```bash theme={null}
curl -X POST https://api.thrindex.com/v1/memories \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers weekly email digests over push notifications.",
    "agent_id": "support-agent",
    "user_id": "user-42"
  }'
```

### Body

| Field        | Type    | Required | Default | Description                                                              |
| ------------ | ------- | -------- | ------- | ------------------------------------------------------------------------ |
| `content`    | string  | yes      | —       | The memory text. Maximum 8192 bytes.                                     |
| `agent_id`   | string  | yes      | —       | Agent identifier. Max 256 characters. Allowed charset: `[A-Za-z0-9._:-]` |
| `user_id`    | string  | yes      | —       | User identifier. Same constraints as `agent_id`.                         |
| `confidence` | number  | no       | `1.0`   | Your confidence in this memory's accuracy. Range: `0.0`–`1.0`.           |
| `metadata`   | object  | no       | —       | Arbitrary key-value pairs stored alongside the memory. Any JSON object.  |
| `extract`    | boolean | no       | `true`  | Controls LLM fact extraction in the cognition worker. See below.         |

<Note>
  Unknown fields in the request body are rejected with `400 validation_error`. The `org_id` is always derived from the API key — never accepted in the body.
</Note>

### The `extract` field

| Value            | Behaviour                                                                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true` (default) | The cognition worker runs LLM extraction on the raw content, transforming it into clean, discrete, retrievable facts before storage.                            |
| `false`          | Content is stored verbatim — no LLM call is made. Use this when you are supplying a pre-formatted, clean fact and want lower latency with zero extraction cost. |

***

## Response

### `202 Accepted`

```json theme={null}
{
  "id": "3f2e1d0c-1234-5678-abcd-ef0123456789",
  "status": "queued"
}
```

| Field    | Type          | Description                                                                      |
| -------- | ------------- | -------------------------------------------------------------------------------- |
| `id`     | string (UUID) | The memory's unique identifier. Use this to retrieve or delete the memory later. |
| `status` | string        | Always `"queued"` — the memory is being processed asynchronously.                |

The memory will be available for search within a few seconds, once the cognition worker completes processing.

***

## Examples

### Minimal request

```bash theme={null}
curl -X POST https://api.thrindex.com/v1/memories \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User timezone is Europe/Berlin.",
    "agent_id": "support-agent",
    "user_id": "user-42"
  }'
```

### With confidence and metadata

```bash theme={null}
curl -X POST https://api.thrindex.com/v1/memories \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User stated they prefer dark mode in their account settings.",
    "agent_id": "support-agent",
    "user_id": "user-42",
    "confidence": 0.95,
    "metadata": {
      "source": "settings-page",
      "session_id": "sess_abc123"
    }
  }'
```

### Bypass extraction (verbatim storage)

```bash theme={null}
curl -X POST https://api.thrindex.com/v1/memories \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode.",
    "agent_id": "support-agent",
    "user_id": "user-42",
    "extract": false
  }'
```

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from thrindex import Thrindex

    client = Thrindex(api_key="th_live_...")

    # Standard — LLM extraction runs on the content
    memory_id = client.add(
        content="User prefers weekly email digests over push notifications.",
        agent_id="support-agent",
        user_id="user-42",
        confidence=0.95,
        metadata={"source": "preference-survey"},
    )

    # Verbatim storage — no LLM call
    memory_id = client.add(
        content="User prefers dark mode.",
        agent_id="support-agent",
        user_id="user-42",
        extract=False,
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { ThrindexClient } from 'thrindex';

    const client = new ThrindexClient({ apiKey: 'th_live_...' });

    // Standard — LLM extraction runs on the content
    const memoryId = await client.add({
      content: 'User prefers weekly email digests over push notifications.',
      agentId: 'support-agent',
      userId: 'user-42',
      confidence: 0.95,
      metadata: { source: 'preference-survey' },
    });

    // Verbatim storage — no LLM call
    const memoryId2 = await client.add({
      content: 'User prefers dark mode.',
      agentId: 'support-agent',
      userId: 'user-42',
      extract: false,
    });
    ```
  </Tab>
</Tabs>

***

## Errors

| Status | Code                | Description                                                                                                       |
| ------ | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `400`  | `validation_error`  | Missing required field, invalid charset in `agent_id`/`user_id`, `confidence` out of range, unknown field in body |
| `401`  | `unauthorized`      | Missing or invalid API key                                                                                        |
| `401`  | `forbidden`         | API key lacks `memory:write` scope                                                                                |
| `413`  | `payload_too_large` | `content` exceeds 8192 bytes                                                                                      |
| `429`  | `rate_limited`      | Rate limit exceeded — respect `Retry-After` header                                                                |
| `500`  | `internal_error`    | Server error                                                                                                      |