# Memories

## 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 Parameters

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

  - `"force"`

- `infer: optional boolean`

- `metadata: optional unknown`

- `mode: optional "chat" or "import"`

  - `"chat"`

  - `"import"`

- `user_id: optional string`

### Returns

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

  - `"chat"`

  - `"import"`

- `results: optional array of MemoryItem`

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

### Example

```http
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"
            }
          ]
        }'
```

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

## Search Memory

**post** `/v1/memories/search/`

Search memories. `mode=flat` returns flat results; `mode=context`
runs the full retrieval agent and returns assembled context.

### Body Parameters

- `filters: unknown`

- `query: string`

- `char_budget: optional number`

- `conv_history: optional array of unknown`

- `conv_id: optional string`

- `exclude_artifact_ids: optional array of string`

- `mode: optional "flat" or "context"`

  - `"flat"`

  - `"context"`

- `rerank: optional boolean`

- `threshold: optional number`

- `top_k: optional number`

### Returns

- `all_retrieved_artifacts: optional array of Artifact`

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

- `artifacts: optional array of Artifact`

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

- `context: optional string`

- `episodes: optional array of Episode`

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

- `facts: optional array of Fact`

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

- `mode: optional "flat" or "context"`

  - `"flat"`

  - `"context"`

- `results: optional array of MemoryItem`

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

### Example

```http
curl https://api.example.com/v1/memories/search/ \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $XTRACE_MEMORY_MANAGER_API_KEY" \
    -H "X-Org-Id: $XTRACE_MEMORY_MANAGER_ORG_ID" \
    -d '{
          "filters": {},
          "query": "x"
        }'
```

#### Response

```json
{
  "all_retrieved_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
    }
  ],
  "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
    }
  ],
  "context": "context",
  "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"
    }
  ],
  "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"
    }
  ],
  "mode": "flat",
  "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
  }
}
```

## List Memories

**post** `/v1/memories/`

List active memories matching `filters`. Paginated.

### Query Parameters

- `page: optional number`

- `page_size: optional number`

### Body Parameters

- `filters: unknown`

### Returns

- `count: number`

- `next: optional string`

- `previous: optional string`

- `results: optional array of MemoryItem`

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

### Example

```http
curl https://api.example.com/v1/memories/ \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $XTRACE_MEMORY_MANAGER_API_KEY" \
    -H "X-Org-Id: $XTRACE_MEMORY_MANAGER_ORG_ID" \
    -d '{
          "filters": {}
        }'
```

#### Response

```json
{
  "count": 0,
  "next": "next",
  "previous": "previous",
  "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"
    }
  ]
}
```

## Get Memory By Id

**get** `/v1/memories/{memory_id}/`

Get one memory by id. Scope resolved from the row itself.

### Path Parameters

- `memory_id: string`

### Returns

- `MemoryItem object { id, memory, agent_id, 7 more }`

  One result item — used in flat search `results` and listings.

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

### Example

```http
curl https://api.example.com/v1/memories/$MEMORY_ID/ \
    -H "x-api-key: $XTRACE_MEMORY_MANAGER_API_KEY" \
    -H "X-Org-Id: $XTRACE_MEMORY_MANAGER_ORG_ID"
```

#### Response

```json
{
  "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"
}
```

## Patch Memory

**patch** `/v1/memories/{memory_id}/`

Update memory text — supersedes old + creates new.

Metadata-only patches (no `text`) are rejected with 400; the
row's metadata is derived from extraction and isn't editable from
the API yet.

### Path Parameters

- `memory_id: string`

### Body Parameters

- `metadata: optional unknown`

- `text: optional string`

### Returns

- `MemoryItem object { id, memory, agent_id, 7 more }`

  One result item — used in flat search `results` and listings.

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

### Example

```http
curl https://api.example.com/v1/memories/$MEMORY_ID/ \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $XTRACE_MEMORY_MANAGER_API_KEY" \
    -H "X-Org-Id: $XTRACE_MEMORY_MANAGER_ORG_ID" \
    -d '{}'
```

#### Response

```json
{
  "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"
}
```

## Delete Memory

**delete** `/v1/memories/{memory_id}/`

Delete Memory

### Path Parameters

- `memory_id: string`

### Example

```http
curl https://api.example.com/v1/memories/$MEMORY_ID/ \
    -X DELETE \
    -H "x-api-key: $XTRACE_MEMORY_MANAGER_API_KEY" \
    -H "X-Org-Id: $XTRACE_MEMORY_MANAGER_ORG_ID"
```

#### Response

```json
{}
```

## Domain Types

### Artifact

- `Artifact object { 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`

### Episode

- `Episode object { 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`

### Fact

- `Fact object { 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`

### Memory Item

- `MemoryItem object { id, memory, agent_id, 7 more }`

  One result item — used in flat search `results` and listings.

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

### Memory Add Response

- `MemoryAddResponse object { 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: 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: 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"`

    - `"chat"`

    - `"import"`

  - `results: optional array of MemoryItem`

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

### Memory Search Response

- `MemorySearchResponse object { all_retrieved_artifacts, artifacts, context, 5 more }`

  Returned by POST /v1/memories/search/.

  `results` is the flat list (always populated when matches exist).
  In `mode=context` the additional fields (`context`,
  `artifacts`, `episodes`) are filled in too. In `mode=flat`
  they're empty.

  - `all_retrieved_artifacts: optional array of Artifact`

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

  - `artifacts: optional array of Artifact`

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

  - `context: optional string`

  - `episodes: optional array of Episode`

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

  - `facts: optional array of Fact`

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

  - `mode: optional "flat" or "context"`

    - `"flat"`

    - `"context"`

  - `results: optional array of MemoryItem`

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

### Memory List Response

- `MemoryListResponse object { count, next, previous, results }`

  Paginated list envelope.

  - `count: number`

  - `next: optional string`

  - `previous: optional string`

  - `results: optional array of MemoryItem`

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

### Memory Delete Response

- `MemoryDeleteResponse = unknown`