## Add Memory

`client.memories.add(MemoryAddParamsbody, RequestOptionsoptions?): MemoryAddResponse`

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

### Parameters

- `body: MemoryAddParams`

  - `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`

    - `"force"`

  - `infer?: boolean`

  - `metadata?: unknown`

  - `mode?: "chat" | "import"`

    - `"chat"`

    - `"import"`

  - `user_id?: string | null`

### Returns

- `MemoryAddResponse`

  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: 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"`

    - `"chat"`

    - `"import"`

  - `results?: Array<MemoryItem>`

    - `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: 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: 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>>`

### Example

```typescript
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);
```

#### Response

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