xmem-ai

TypeScript SDK for the XMem long-term memory API.

Install

npm install xmem-ai

Usage

All constructor arguments are required: API base URL, API key, and username (sent on every request via the X-XMem-Username header).

import { XMemClient } from "xmem-ai";

const client = new XMemClient(
  "http://localhost:8000",
  process.env.XMEM_API_KEY!,
  "alice",
);

const ready = await client.isReady();

await client.ingest({
  user_query: "Hello",
  user_id: "user_42",
});

const answer = await client.retrieve({
  query: "What did we talk about?",
  user_id: "user_42",
});

Error handling

import {
  XMemClient,
  AuthenticationError,
  RateLimitError,
} from "xmem-ai";

try {
  await client.ingest({ user_query: "test", user_id: "u1" });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error(`Auth failed: ${e.message}`);
  } else if (e instanceof RateLimitError) {
    console.error(`Rate limited, retry after ${e.retryAfter}s`);
  }
}

Migrating from 1.x

Version 2.0.0 is a breaking release.

Constructor

Before (1.x):

new XMemClient(); // defaults: localhost, no API key
new XMemClient(apiUrl);
new XMemClient(apiUrl, apiKey);

Optional arguments fell back to process.env.XMEM_API_URL, process.env.XMEM_API_KEY, and defaults.

After (2.x):

new XMemClient(apiUrl, apiKey, username);

• apiUrl, apiKey, and username are required strings.
• Passing undefined, null, or whitespace-only values throws Error immediately (before any network call).
• Username is included on every request as the X-XMem-Username HTTP header.

Replace previous env-only setups by reading variables yourself and passing them explicitly:

const apiUrl = process.env.XMEM_API_URL ?? "http://localhost:8000";
const apiKey = process.env.XMEM_API_KEY!;
const username = process.env.XMEM_USERNAME!;

const client = new XMemClient(apiUrl, apiKey, username);

Apache-2.0 License