API Reference

Memories

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

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 ParametersJSONExpand Collapse

filters: unknown

query: string

minLength1

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"

One of the following:

"flat"

"context"

rerank: optional boolean

threshold: optional number

maximum1

minimum0

top_k: optional number

maximum1000

minimum1

ReturnsExpand Collapse

all_retrieved_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

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

context: optional string

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

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

mode: optional "flat" or "context"

One of the following:

"flat"

"context"

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]

Search Memory

HTTP

HTTP

TypeScript

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"
        }'

200 example

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

Returns Examples

200 example

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