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