TypeScript SDK

npm install @xtraceai/memory

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

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

const job = await client.memories.ingest({
  messages: [
    { role: 'user', content: 'My favorite food is pad see ew.' },
    { role: 'assistant', content: 'Noted.' },
  ],
  user_id: 'alice',
  conv_id: 'conv_2026_05_16',
});

for await (const memory of client.memories.list({ user_id: 'alice' })) {
  console.log(memory.text);
}

const page = await client.memories.listPage({ user_id: 'alice', limit: 50, cursor });
// page.data, page.has_more, page.next_cursor

const memory = await client.memories.get('5b0d0f7d-d502-...');

await client.memories.delete('5b0d0f7d-d502-...');

const results = await client.memories.search({
  query: 'what does the user like to eat?',
  user_id: 'alice',
  limit: 10,
});
// results.data — ranked rows;  results.context — assembled prompt when mode==='compose'

const { prompt, memories, scopes } = await client.memories.recall({
  query: 'what should we plan for dinner on the trip?',
  pools: [
    { user_id: 'alice' },             // personal scope
    { group_ids: ['grp_tokyo2026'] }, // shared scope (any-of)
  ],
});
// inject `prompt`; `memories` is the deduped, score-ranked union; `scopes` is per-pool counts

const done = await client.memories.jobs.pollUntilDone(job.id);
if (done.status === 'failed') throw new Error(done.error?.message);
console.log(done.result?.memories_created);

const trip = await client.groups.create({
  name: 'Tokyo trip 2026',
  prompt: 'Facts about the Tokyo trip: hotels, restaurants, dates, dietary needs.',
});
// trip.id === "grp_…"

import { MemoryNotFound, RateLimited, MemoryError } from '@xtraceai/memory';

try {
  await client.memories.get('does-not-exist');
} catch (err) {
  if (err instanceof MemoryNotFound) {
    // 404
  } else if (err instanceof RateLimited) {
    console.log('retry after', err.retryAfter, 'seconds');
  } else if (err instanceof MemoryError) {
    console.log(err.status, err.code, err.message);
  }
}

import type {
  // Resources
  Memory,
  FactMemory,
  ArtifactMemory,
  EpisodeMemory,
  FactDetails,
  ArtifactDetails,
  EpisodeDetails,
  MemoryRef,
  MemoryType,
  MemoryStatus,

  // Ingest
  Message,
  Role,
  IngestRequest,
  IngestJob,
  IngestJobResult,
  JobStatus,

  // Read
  ListQuery,
  ListEnvelope,
  SearchRequest,
  SearchListEnvelope,
  SearchMode,

  // Recall + prompt rendering
  RecallParams,
  RecallResult,
  RecallScopeStat,
  ScopePool,
  PromptTemplate,

  // Groups
  Group,
  GroupStatus,
  GroupCreateRequest,
  GroupUpdateRequest,
  GroupListEnvelope,

  // Errors
  ApiErrorBody,
} from '@xtraceai/memory';

import { renderMemoriesPrompt, DEFAULT_PROMPT_TEMPLATE } from '@xtraceai/memory';