Add Memory

client.memories.add(, ?): MemoryAddResponse { consolidation_id_mapping, flush_result, message, 7 more }

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

ParametersExpand Collapse

body: MemoryAddParams { messages, agent_id, config_overrides, 8 more }

messages: Array<Message>

content: string

role: string

date?: string | null

dia_id?: string | null

agent_id?: string | null

config_overrides?: unknown

conv_id?: string | null

custom_instructions?: string | null

flush_after?: boolean

flush_hint?: "force" | null

infer?: boolean

metadata?: unknown

mode?: "chat" | "import"

One of the following:

"chat"

"import"

user_id?: string | null

ReturnsExpand Collapse

MemoryAddResponse { consolidation_id_mapping, flush_result, message, 7 more }

Returned by POST /v1/memories/add/.

Sync inline result — the full extracted set is in the response; no event_id / async polling. results mirrors the flat-list shape that search returns, so clients can read just-stored memories with one consistent shape.

consolidation_id_mapping?: Record<string, string>

flush_result?: FlushResult | null

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?: Array<Episode { episode_id, artifact_ids, conv_id, 5 more } >

episode_id: string

artifact_ids?: Array<string>

conv_id?: string | null

ended_at?: string | null

fact_ids?: Array<string>

started_at?: string | null

summary?: string | null

title?: string | null

stage_timings?: Record<string, number>

message?: string

mode?: "chat" | "import"

One of the following:

"chat"

"import"

results?: Array<MemoryItem { id, memory, agent_id, 7 more } >

id: string

memory: string

agent_id?: string | null

categories?: Array<string>

conv_id?: string | null

created_at?: string | null

metadata?: unknown

score?: number | null

updated_at?: string | null

user_id?: string | null

stage_timings?: Record<string, number>

status?: string

stored_artifacts?: Array<Artifact { artifact_id, artifact_type, content, 12 more } >

artifact_id: string

artifact_type?: string | null

content?: string | null

conv_id?: string | null

created_at?: string | null

descriptor_fact_ids?: Array<string>

episode_id?: string | null

is_latest?: boolean | null

name?: string | null

parent_artifact_id?: string | null

rationale?: string | null

root_artifact_id?: string | null

score?: number | null

summary?: string | null

version?: number | null

stored_facts?: Array<Fact { fact_id, text, change_reason, 17 more } >

fact_id: string

text: string

change_reason?: string | null

change_type?: string | null

consolidated_at?: string | null

conv_id?: string | null

created_at?: string | null

episode_id?: string | null

event_date?: string | null

fact_type?: string | null

metadata?: unknown

origin?: string | null

root_artifact_id?: string | null

score?: number | null

source_artifact_id?: string | null

source_dia_ids?: Array<string>

source_event_ids?: Array<string>

source_role?: string | null

status?: string | null

supersedes?: string | null

superseded_fact_ids?: Array<Array<unknown>>

Add Memory

import XtraceMemoryManager from 'xtrace-memory-manager';

const client = new XtraceMemoryManager({
  apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted
  orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted
});

const response = await client.memories.add({ messages: [{ content: 'content', role: 'role' }] });

console.log(response.consolidation_id_mapping);

{
  "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": [
    [
      {},
      {}
    ]
  ]
}