Add Memory

POST/v1/memories/add/

Ingest memories. mode=chat pairs messages; mode=import is bulk.

Workspace/CB write target lives in metadata.workspace_id / metadata.cb_id (absent → hosted single-tenant).

Body ParametersJSONExpand Collapse

messages: array of object { content, role, date, dia_id }

content: string

role: string

date: optional string

dia_id: optional string

agent_id: optional string

config_overrides: optional unknown

conv_id: optional string

custom_instructions: optional string

flush_after: optional boolean

flush_hint: optional "force"

infer: optional boolean

metadata: optional unknown

mode: optional "chat" or "import"

One of the following:

"chat"

"import"

user_id: optional string

ReturnsExpand Collapse

consolidation_id_mapping: optional map[string]

flush_result: optional object { episodes, stage_timings }

Returned inside AddResponse.flush_result when an auto-flush fires. Carries the freshly-minted episode ids — what a chat orchestrator passes to mark_completed (or equivalent).

episodes: optional array of Episode { episode_id, artifact_ids, conv_id, 5 more }

episode_id: string

artifact_ids: optional array of string

conv_id: optional string

ended_at: optional string

fact_ids: optional array of string

started_at: optional string

summary: optional string

title: optional string

stage_timings: optional map[number]

message: optional string

mode: optional "chat" or "import"

One of the following:

"chat"

"import"

results: optional array of MemoryItem { id, memory, agent_id, 7 more }

id: string

memory: string

agent_id: optional string

categories: optional array of string

conv_id: optional string

created_at: optional string

metadata: optional unknown

score: optional number

updated_at: optional string

user_id: optional string

stage_timings: optional map[number]

status: optional string

stored_artifacts: optional array of Artifact { artifact_id, artifact_type, content, 12 more }

artifact_id: string

artifact_type: optional string

content: optional string

conv_id: optional string

created_at: optional string

descriptor_fact_ids: optional array of string

episode_id: optional string

is_latest: optional boolean

name: optional string

parent_artifact_id: optional string

rationale: optional string

root_artifact_id: optional string

score: optional number

summary: optional string

version: optional number

stored_facts: optional array of Fact { fact_id, text, change_reason, 17 more }

fact_id: string

text: string

change_reason: optional string

change_type: optional string

consolidated_at: optional string

conv_id: optional string

created_at: optional string

episode_id: optional string

event_date: optional string

fact_type: optional string

metadata: optional unknown

origin: optional string

root_artifact_id: optional string

score: optional number

source_artifact_id: optional string

source_dia_ids: optional array of string

source_event_ids: optional array of string

source_role: optional string

status: optional string

supersedes: optional string

superseded_fact_ids: optional array of array of unknown

Add Memory

curl https://api.example.com/v1/memories/add/ \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $XTRACE_MEMORY_MANAGER_API_KEY" \
    -H "X-Org-Id: $XTRACE_MEMORY_MANAGER_ORG_ID" \
    -d '{
          "messages": [
            {
              "content": "content",
              "role": "role"
            }
          ]
        }'

{
  "consolidation_id_mapping": {
    "foo": "string"
  },
  "flush_result": {
    "episodes": [
      {
        "episode_id": "episode_id",
        "artifact_ids": [
          "string"
        ],
        "conv_id": "conv_id",
        "ended_at": "ended_at",
        "fact_ids": [
          "string"
        ],
        "started_at": "started_at",
        "summary": "summary",
        "title": "title"
      }
    ],
    "stage_timings": {
      "foo": 0
    }
  },
  "message": "message",
  "mode": "chat",
  "results": [
    {
      "id": "id",
      "memory": "memory",
      "agent_id": "agent_id",
      "categories": [
        "string"
      ],
      "conv_id": "conv_id",
      "created_at": "created_at",
      "metadata": {},
      "score": 0,
      "updated_at": "updated_at",
      "user_id": "user_id"
    }
  ],
  "stage_timings": {
    "foo": 0
  },
  "status": "status",
  "stored_artifacts": [
    {
      "artifact_id": "artifact_id",
      "artifact_type": "artifact_type",
      "content": "content",
      "conv_id": "conv_id",
      "created_at": "created_at",
      "descriptor_fact_ids": [
        "string"
      ],
      "episode_id": "episode_id",
      "is_latest": true,
      "name": "name",
      "parent_artifact_id": "parent_artifact_id",
      "rationale": "rationale",
      "root_artifact_id": "root_artifact_id",
      "score": 0,
      "summary": "summary",
      "version": 0
    }
  ],
  "stored_facts": [
    {
      "fact_id": "fact_id",
      "text": "text",
      "change_reason": "change_reason",
      "change_type": "change_type",
      "consolidated_at": "consolidated_at",
      "conv_id": "conv_id",
      "created_at": "created_at",
      "episode_id": "episode_id",
      "event_date": "event_date",
      "fact_type": "fact_type",
      "metadata": {},
      "origin": "origin",
      "root_artifact_id": "root_artifact_id",
      "score": 0,
      "source_artifact_id": "source_artifact_id",
      "source_dia_ids": [
        "string"
      ],
      "source_event_ids": [
        "string"
      ],
      "source_role": "source_role",
      "status": "status",
      "supersedes": "supersedes"
    }
  ],
  "superseded_fact_ids": [
    [
      {},
      {}
    ]
  ]
}

Returns Examples

{
  "consolidation_id_mapping": {
    "foo": "string"
  },
  "flush_result": {
    "episodes": [
      {
        "episode_id": "episode_id",
        "artifact_ids": [
          "string"
        ],
        "conv_id": "conv_id",
        "ended_at": "ended_at",
        "fact_ids": [
          "string"
        ],
        "started_at": "started_at",
        "summary": "summary",
        "title": "title"
      }
    ],
    "stage_timings": {
      "foo": 0
    }
  },
  "message": "message",
  "mode": "chat",
  "results": [
    {
      "id": "id",
      "memory": "memory",
      "agent_id": "agent_id",
      "categories": [
        "string"
      ],
      "conv_id": "conv_id",
      "created_at": "created_at",
      "metadata": {},
      "score": 0,
      "updated_at": "updated_at",
      "user_id": "user_id"
    }
  ],
  "stage_timings": {
    "foo": 0
  },
  "status": "status",
  "stored_artifacts": [
    {
      "artifact_id": "artifact_id",
      "artifact_type": "artifact_type",
      "content": "content",
      "conv_id": "conv_id",
      "created_at": "created_at",
      "descriptor_fact_ids": [
        "string"
      ],
      "episode_id": "episode_id",
      "is_latest": true,
      "name": "name",
      "parent_artifact_id": "parent_artifact_id",
      "rationale": "rationale",
      "root_artifact_id": "root_artifact_id",
      "score": 0,
      "summary": "summary",
      "version": 0
    }
  ],
  "stored_facts": [
    {
      "fact_id": "fact_id",
      "text": "text",
      "change_reason": "change_reason",
      "change_type": "change_type",
      "consolidated_at": "consolidated_at",
      "conv_id": "conv_id",
      "created_at": "created_at",
      "episode_id": "episode_id",
      "event_date": "event_date",
      "fact_type": "fact_type",
      "metadata": {},
      "origin": "origin",
      "root_artifact_id": "root_artifact_id",
      "score": 0,
      "source_artifact_id": "source_artifact_id",
      "source_dia_ids": [
        "string"
      ],
      "source_event_ids": [
        "string"
      ],
      "source_role": "source_role",
      "status": "status",
      "supersedes": "supersedes"
    }
  ],
  "superseded_fact_ids": [
    [
      {},
      {}
    ]
  ]
}