Skip to main content
POST
/
ingestion
/
memory
Ingest conversation memory
curl --request POST \
  --url https://api.getmetacognition.com/ingestion/memory \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope.org_id": "<string>",
  "scope.user_id": "<string>",
  "scope.session_id": "<string>",
  "turns": [
    {}
  ],
  "options": {},
  "metadata": {}
}
'
{
  "job_id": "<string>",
  "active_fragment_ids": {},
  "passive_job_id": {},
  "usage": {}
}
This is the REST version of tex.conversations.remember. Use it to write turns under a scope. Tex saves active memory first, then continues enrichment in the background.

​
Headers

Authorization: Bearer <access_token>
Content-Type: application/json

​
Body

{
  "scope": {
    "org_id": "org_...",
    "user_id": "user_...",
    "session_id": "chat-1"
  },
  "turns": [
    {
      "role": "user",
      "text": "I'm allergic to shellfish.",
      "timestamp": "2026-05-08T14:00:00Z"
    },
    {
      "role": "assistant",
      "text": "Got it.",
      "timestamp": "2026-05-08T14:00:01Z"
    }
  ],
  "options":  { "write_active": true, "write_passive": true },
  "metadata": { "channel": "support" }
}
​
scope.org_id
string
required
Your org id. Minimum length is 1 character. The server still uses the JWT’s org_id claim for tenancy; this field is required for request validation.
​
scope.user_id
string
End-user partition. Defaults to the JWT’s user.
​
scope.session_id
string
Conversation/channel/task id. Defaults to the JWT’s session_id if set, else "default-session".
​
turns
array
required
At least one turn (min_length=1). Each turn: {role, text, timestamp, observations?}. See How memory works.
​
options
object
Optional write toggles: { write_active: bool = true, write_passive: bool = true }. Advanced callers can disable one storage tier.
​
metadata
object
Free-form metadata. It is stored today and reserved for future filters.

​
Response — 202 Accepted

​
job_id
string
Stable id for this write.
​
active_fragment_ids
array[string]
Active-memory fragment ids. These are already recallable.
​
passive_job_id
string | null
Background enrichment job id, when one is needed.
​
usage
object
{tokens_in, tokens_out} billed for this call.
Response
{
  "job_id": "1737f27b090743bab9f129b48fd44831",
  "active_fragment_ids": [
    "c9fcfbf51b03bbc3c05075671b5fa5aa7e34d803c13b554391746188bfa22d22"
  ],
  "passive_job_id": null,
  "usage": { "tokens_in": 6, "tokens_out": 0 }
}

​
Example

curl -X POST https://api.getmetacognition.com/ingestion/memory \
  -H "Authorization: Bearer $JWT" \
  -H 'content-type: application/json' \
  -d '{
    "scope": {"org_id":"org_…","session_id":"chat-1"},
    "turns": [
      {"role":"user","text":"hello","timestamp":"2026-05-08T14:00:00Z"}
    ]
  }'

​
Idempotency

Tex computes a stable hash per turn from role, text, and timestamp. Re-sending the same turn is a no-op. It does not create duplicate fragments or double bill the turn. It is safe to retry after a network failure.