Skip to main content
POST
/
v1
/
memories
/
search
TypeScript SDK
import { MemoryClient } from '@xtraceai/memory';

const client = new MemoryClient({
  apiKey: process.env.XTRACE_API_KEY!,
  orgId:  process.env.XTRACE_ORG_ID!,
});

const results = await client.memories.search({
  query: 'what does the user like to eat?',
  filters: { user_id: 'alice' },
  limit: 10,
});

for (const m of results.data) {
  console.log(m.score?.toFixed(2), '·', m.text);
}
{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "text": "<string>",
      "object": "memory",
      "user_id": "<string>",
      "agent_id": "<string>",
      "conv_id": "<string>",
      "app_id": "<string>",
      "metadata": {},
      "categories": [
        "<string>"
      ],
      "score": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "details": {
        "fact_type": "<string>",
        "status": "<string>",
        "supersedes": "<string>",
        "source_role": "<string>",
        "episode_id": "<string>",
        "artifact_id": "<string>",
        "artifact_ids": [
          "<string>"
        ],
        "source_event_ids": [
          "<string>"
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": "<string>",
  "extras": {
    "context_prompt": "<string>",
    "stage_timings": {}
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.mem.xtrace.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-api-key
string
header
required

Long-lived org API key. Alternative: Authorization: Bearer <key>.

​
X-Org-Id
string
header
required

Required alongside the API key (no key→org reverse index).

Headers

​
X-Service-Token
string | null

Body

application/json

POST /v1/memories/search — vector + filter search over the unified memory pool. No mode flag; opt into composed output via include.

filters is the full DSL (bare values, $in/$ne/$gte/ $lte, AND/OR/NOT). Empty/omitted filters mean "all memories in this org".

​
query
string
required

Natural-language query text. Embedded server-side; cosine-similarity-ranked.

Minimum string length: 1
Example:

"who likes thai food?"

​
filters
Filters · object

Filter DSL. Top-level keys are implicit-AND. Supported operators on per-field values: bare value, null, $eq, $ne, $in, $nin, $exists, $gt/$gte/$lt/$lte, $between. Boolean composition: AND / OR / NOT. type (string or $in list) restricts which kb_types are scanned (default = all three).

Examples:
{ "user_id": "alice" }
{
  "AND": [
    { "user_id": "alice" },
    { "agent_id": "bot-7" }
  ]
}
{
  "score_val": { "$gte": 0.5 },
  "type": "fact"
}
​
limit
integer
default:20

Maximum rows to return. 1–100, default 20.

Required range: 1 <= x <= 100
​
cursor
string | null

Opaque pagination cursor from a previous response's next_cursor. Tenant-scoped — using one from another org returns 422 cursor_mismatch.

​
include
enum<string>[]

Opt-in extras. full_content populates details.full_content on artifact rows (no-op for facts/episodes). context_prompt runs xmem's retrieval-agent pipeline; the assembled markdown lands under extras.context_prompt and requires both user_id and conv_id in filters.

Available options:
full_content,
context_prompt

Response

Successful Response

Search response — list envelope + optional extras block.

​
object
string
default:list

Constant discriminator for the resource type.

Allowed value: "list"
​
data
Memory · object[]

Ranked rows. Mixed kb_types are merged by raw cosine; score carries the similarity value.

​
has_more
boolean
default:false
​
next_cursor
string | null
​
extras
SearchExtras · object

Populated only when include opts in. null on a default search response.