Quickstart - XTrace Memory

End-to-end in 5 minutes. By the end you’ll have a memory ingested and retrieved via vector search.

1. Install

npm install @xtraceai/memory

Node 18 or newer. Works in the browser too.

2. Get credentials

Sign in at app.xtrace.ai and grab your API key (xtk_…) from Settings → API Keys. The key is the sole identity — your org is derived server-side from it. See Authentication for the full credential setup, including storage best practices.

3. Ingest a memory

import { MemoryClient } from '@xtraceai/memory';

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

const job = await client.memories.ingest({
  messages: [
    { role: 'user', content: 'My favorite food is pad see ew. I love Thai cuisine.' },
    { role: 'assistant', content: 'Got it — pad see ew noted.' },
  ],
  user_id: 'alice',
  conv_id: 'conv_2026_05_16',
});

console.log('Ingest job:', job.id, 'status:', job.status);

The call returns immediately with a job in status: "pending" or "running". Extraction runs server-side (3–10 seconds typical).

4. Wait for extraction to finish

const done = await client.memories.jobs.pollUntilDone(job.id);
console.log('Memories created:', done.result?.memories_created);

The SDK’s pollUntilDone helper handles exponential backoff (500ms → 5s) and a configurable timeout. You can also opt into synchronous mode by passing { wait: true } on ingest — the server holds the connection up to 30 seconds. See Ingesting memories for the full pattern.

5. Search the memory back

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

for (const m of results.data) {
  console.log(m.score?.toFixed(2), '·', m.text);
}
// 0.87 · User loves Thai cuisine.
// 0.82 · User's favorite food is pad see ew.

What’s next

Authentication — get the credentials and use them
Ingesting memories — async/sync trade-offs, polling, what gets extracted
Searching memories — scoping, search modes, recall
Groups — share memory across users
API Reference tab — every endpoint, every response shape