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

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

// Auto-paginating async iterator
for await (const memory of client.memories.list({ user_id: 'alice' })) {
  console.log(memory.text);
}

// Or single-page access
const page = await client.memories.listPage({ user_id: 'alice', limit: 50 });
{
  "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>"
}

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

Query Parameters

user_id
string | null

Filter by user_id (exact match). Combine with other entity params for AND.

agent_id
string | null

Filter by agent_id (exact match).

conv_id
string | null

Filter by conv_id (exact match).

app_id
string | null

Filter by app_id (exact match).

type
enum<string> | null

Restrict results to one memory subtype. Default: all three.

Available options:
fact,
artifact,
episode
cursor
string | null

Opaque pagination cursor from a previous response's next_cursor. Must match this request's order and the issuing org (mismatch → 422 cursor_mismatch).

limit
integer
default:50

Maximum rows per page. 1–100, default 50.

Required range: 1 <= x <= 100
order
enum<string>
default:created_at_desc

Sort order on (created_at, id).

Available options:
created_at_desc,
created_at_asc
include
string | null

Comma-separated opt-in extras. Currently only full_content is supported (populates details.full_content on artifact rows).

Response

Successful Response

Stripe-style list envelope used by GET /v1/memories, GET /v1/memories/{id}/revisions, and the default search response.

object
string
default:list

Constant discriminator for the resource type.

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

Page of memory rows.

has_more
boolean
default:false

True if more rows exist beyond this page; use next_cursor to fetch them.

next_cursor
string | null

Opaque cursor for the next page. Null on the final page. Tenant-scoped: only usable with the same (org, key) that produced it.