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": {}
}
'import requests
url = "https://api.getmetacognition.com/ingestion/memory"
payload = {
"scope.org_id": "<string>",
"scope.user_id": "<string>",
"scope.session_id": "<string>",
"turns": [{}],
"options": {},
"metadata": {}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
'scope.org_id': '<string>',
'scope.user_id': '<string>',
'scope.session_id': '<string>',
turns: [{}],
options: {},
metadata: {}
})
};
fetch('https://api.getmetacognition.com/ingestion/memory', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.getmetacognition.com/ingestion/memory",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'scope.org_id' => '<string>',
'scope.user_id' => '<string>',
'scope.session_id' => '<string>',
'turns' => [
[
]
],
'options' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.getmetacognition.com/ingestion/memory"
payload := strings.NewReader("{\n \"scope.org_id\": \"<string>\",\n \"scope.user_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"turns\": [\n {}\n ],\n \"options\": {},\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.getmetacognition.com/ingestion/memory")
.header("Content-Type", "application/json")
.body("{\n \"scope.org_id\": \"<string>\",\n \"scope.user_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"turns\": [\n {}\n ],\n \"options\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.getmetacognition.com/ingestion/memory")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"scope.org_id\": \"<string>\",\n \"scope.user_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"turns\": [\n {}\n ],\n \"options\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>",
"active_fragment_ids": {},
"passive_job_id": {},
"usage": {}
}Memory
Ingest conversation memory
Write turns under a scope. Active memory is saved first; enrichment continues in the background.
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": {}
}
'import requests
url = "https://api.getmetacognition.com/ingestion/memory"
payload = {
"scope.org_id": "<string>",
"scope.user_id": "<string>",
"scope.session_id": "<string>",
"turns": [{}],
"options": {},
"metadata": {}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
'scope.org_id': '<string>',
'scope.user_id': '<string>',
'scope.session_id': '<string>',
turns: [{}],
options: {},
metadata: {}
})
};
fetch('https://api.getmetacognition.com/ingestion/memory', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.getmetacognition.com/ingestion/memory",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'scope.org_id' => '<string>',
'scope.user_id' => '<string>',
'scope.session_id' => '<string>',
'turns' => [
[
]
],
'options' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.getmetacognition.com/ingestion/memory"
payload := strings.NewReader("{\n \"scope.org_id\": \"<string>\",\n \"scope.user_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"turns\": [\n {}\n ],\n \"options\": {},\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.getmetacognition.com/ingestion/memory")
.header("Content-Type", "application/json")
.body("{\n \"scope.org_id\": \"<string>\",\n \"scope.user_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"turns\": [\n {}\n ],\n \"options\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.getmetacognition.com/ingestion/memory")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"scope.org_id\": \"<string>\",\n \"scope.user_id\": \"<string>\",\n \"scope.session_id\": \"<string>\",\n \"turns\": [\n {}\n ],\n \"options\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>",
"active_fragment_ids": {},
"passive_job_id": {},
"usage": {}
}This is the REST version of
Response —
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" }
}
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.string
End-user partition. Defaults to the JWT’s user.
string
Conversation/channel/task id. Defaults to the JWT’s
session_id if set, else "default-session".array
required
At least one turn (
min_length=1). Each turn: {role, text, timestamp, observations?}. See How memory works.object
Optional write toggles:
{ write_active: bool = true, write_passive: bool = true }. Advanced callers can disable one storage tier.object
Free-form metadata. It is stored today and reserved for future filters.
Response — 202 Accepted
string
Stable id for this write.
array[string]
Active-memory fragment ids. These are already recallable.
string | null
Background enrichment job id, when one is needed.
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"}
]
}'
import httpx
resp = httpx.post(
"https://api.getmetacognition.com/ingestion/memory",
headers={"Authorization": f"Bearer {jwt}"},
json={
"scope": {"org_id": "org_…", "session_id": "chat-1"},
"turns": [
{"role": "user", "text": "hello", "timestamp": "2026-05-08T14:00:00Z"}
],
},
timeout=10,
)
resp.raise_for_status()
Idempotency
Tex computes a stable hash per turn fromrole, 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.