API Reference

Memories

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Search Memory

client.memories.search(MemorySearchParams { filters, query, char_budget, 7 more } body, RequestOptionsoptions?): MemorySearchResponse { all_retrieved_artifacts, artifacts, context, 5 more }

POST/v1/memories/search/

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

ParametersExpand Collapse

body: MemorySearchParams { filters, query, char_budget, 7 more }

filters: unknown

query: string

minLength1

char_budget?: number | null

conv_history?: Array<unknown> | null

conv_id?: string | null

exclude_artifact_ids?: Array<string> | null

mode?: "flat" | "context"

One of the following:

"flat"

"context"

rerank?: boolean

threshold?: number

maximum1

minimum0

top_k?: number

maximum1000

minimum1

ReturnsExpand Collapse

MemorySearchResponse { 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?: 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

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

context?: string

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

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

mode?: "flat" | "context"

One of the following:

"flat"

"context"

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>

Search Memory

TypeScript

HTTP

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.search({
  filters: {},
  query: 'x',
});

console.log(response.all_retrieved_artifacts);

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