Store a memory - Thrindex docs

`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

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.

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.

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`

{
  "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

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

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)

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
  }'

Python
TypeScript

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,
)

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,
});

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

​POST /v1/memories

​Request

​Body

​The extract field

​Response

​202 Accepted

​Examples

​Minimal request

​With confidence and metadata

​Bypass extraction (verbatim storage)

​Errors

`POST /v1/memories`

Request

Body

The `extract` field

Response

`202 Accepted`

Examples

Minimal request

With confidence and metadata

Bypass extraction (verbatim storage)

Errors