xmemory 1.2.0 → 2.1.0

package/README.md

@@ -2,121 +2,202 @@
 
 TypeScript/JavaScript client library for the [Xmemory](https://xmemory.ai) API.
 
+## Installation
+
+```bash
+npm install xmemory
+```
+
 ## Quick start
 
 ```typescript
-import { xmemoryInstance } from "xmemory";
+import { XmemoryClient } from "xmemory";
 
-const mem = await xmemoryInstance({
-  url: "https://api.xmemory.ai",    // or set XMEM_API_URL env var
-  token: "<your-token>",            // or set XMEM_AUTH_TOKEN env var
+const xm = new XmemoryClient({
+  url: "https://api.xmemory.ai",  // or set XMEM_API_URL env var
+  token: "<your-token>",          // or set XMEM_AUTH_TOKEN env var
 });
 
-mem.instanceId = "<your-instance-id>";
-
-await mem.write("Alice is a software engineer who loves TypeScript.");
-const result = await mem.read("What does Alice do?");
-console.log(result.reader_result?.answer);
-```
-
-## Installation
+// Write and read from an existing instance
+const inst = xm.instance("<your-instance-id>");
 
-```bash
-npm install xmemory
+await inst.write("Alice is a software engineer who loves TypeScript.");
+const result = await inst.read("What does Alice do?");
+console.log(result.reader_result);
 ```
 
 ## Configuration
 
-| Parameter   | Env var           | Default                   | Description                           |
-|-------------|-------------------|---------------------------|---------------------------------------|
-| `url`       | `XMEM_API_URL`    | `http://0.0.0.0:8000`    | Base URL of the Xmemory API           |
-| `token`     | `XMEM_AUTH_TOKEN` | `undefined`               | Bearer token for authentication       |
-| `timeoutMs` | —                 | `60000`                   | Default request timeout in milliseconds |
+| Parameter   | Env var           | Default                    | Description                            |
+|-------------|-------------------|----------------------------|----------------------------------------|
+| `url`       | `XMEM_API_URL`    | `https://api.xmemory.ai`  | Base URL of the Xmemory API            |
+| `token`     | `XMEM_AUTH_TOKEN` | `undefined`                | Bearer token for authentication        |
+| `timeoutMs` | —                 | `60000`                    | Default request timeout in milliseconds |
 
 ## Creating a client
 
 ```typescript
 import { XmemoryClient, xmemoryInstance } from "xmemory";
 
-// Option 1: factory function (runs a health check automatically)
-const mem = await xmemoryInstance({ url: "https://api.xmemory.ai", token: "..." });
+// Option 1: constructor (no health check)
+const xm1 = new XmemoryClient({ token: "..." });
 
-// Option 2: static create method (also runs a health check)
-const mem = await XmemoryClient.create({ url: "https://api.xmemory.ai", token: "..." });
+// Option 2: factory with health check
+const xm2 = await XmemoryClient.create({ token: "..." });
 
-// Option 3: constructor (no health check)
-const mem = new XmemoryClient({ url: "https://api.xmemory.ai", token: "..." });
+// Option 3: convenience function (same as Option 2)
+const xm3 = await xmemoryInstance({ token: "..." });
 ```
 
-## Methods
+## Admin operations
 
-### `createInstance(schemaText, schemaType, timeoutMs?) → Promise<boolean>`
+All cluster and instance management lives under `client.admin`.
+
+### Clusters
+
+```typescript
+const clusters = await xm.admin.listClusters();
+const cluster = await xm.admin.getCluster(clusterId);
+```
 
-Create a new instance with the given schema. On success the new `instanceId`
-is saved automatically and used for subsequent calls.
+### Create an instance
 
 ```typescript
 import { SchemaType } from "xmemory";
 
-const ok = await mem.createInstance(schemaYml, SchemaType.YML);
-const ok = await mem.createInstance(schemaJson, SchemaType.JSON);
+const inst = await xm.admin.createInstance(
+  clusterId,
+  "my-instance",
+  schemaYml,
+  SchemaType.YML,
+  { description: "User profiles" },
+);
+
+// inst is an InstanceHandle — use it directly for data operations
+await inst.write("Alice joined the team.");
 ```
 
-### `write(text, options?) → Promise<WriteResponse>`
+### List and get instances
+
+```typescript
+const instances = await xm.admin.listInstances();
+const info = await xm.admin.getInstance(instanceId);
+```
 
-Extract structured objects from `text` and store them in the instance.
+### Schema operations
 
 ```typescript
-const resp = await mem.write("Bob joined the team on Monday as a designer.");
-console.log(resp.status); // "ok" or "error"
+const schema = await xm.admin.getInstanceSchema(instanceId);
+await xm.admin.updateInstanceSchema(instanceId, newYml, SchemaType.YML);
 ```
 
-Options: `{ timeoutMs?, extractionLogic? }` where `extractionLogic` is `"fast"`, `"regular"`, or `"deep"` (default: `"deep"`).
+### Generate schema
 
-### `writeAsync(text, options?) → Promise<AsyncWriteResponse>`
+```typescript
+const result = await xm.admin.generateSchema(clusterId, "Track user profiles and preferences");
+console.log(result.data_schema);
+```
 
-Start an asynchronous write and return immediately with a `write_id` for tracking.
+### Update metadata and delete
 
 ```typescript
-const resp = await mem.writeAsync("Carol is a manager based in Berlin.", {
-  extractionLogic: "deep",
-});
-console.log(resp.write_id); // use this to check status
+await xm.admin.updateInstanceMetadata(instanceId, "new-name", "new description");
+const deletedIds = await xm.admin.deleteInstance(instanceId);
+```
+
+## Instance data operations
+
+Get a handle to an instance and use it for reads, writes, and extractions.
+
+```typescript
+const inst = xm.instance("<instance-id>");
+```
+
+### `inst.write(text, options?)` → `WriteResult`
+
+Extract and store structured objects from text.
+
+```typescript
+const result = await inst.write("Bob is a designer based in Berlin.");
+console.log(result.write_id, result.trace_id);
 ```
 
-Options: `{ timeoutMs?, extractionLogic?, extractWriteId? }`.
+Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"deep"`.
+
+### `inst.writeAsync(text, options?)` → `AsyncWriteResult`
+
+Start an asynchronous write. Returns a `write_id` for tracking.
 
-### `writeStatus(writeId, options?) → Promise<WriteStatusResponse>`
+```typescript
+const { write_id } = await inst.writeAsync("Carol manages the London office.");
+```
 
-Check the status of an async write operation.
+### `inst.writeStatus(writeId, options?)` → `WriteStatusResult`
+
+Poll the status of an async write.
 
 ```typescript
-const status = await mem.writeStatus(resp.write_id);
+const status = await inst.writeStatus(write_id);
 console.log(status.write_status); // "queued" | "processing" | "completed" | "failed" | "not_found"
 ```
 
-### `read(query, options?) → Promise<ReadResponse>`
+### `inst.read(query, options?)` → `ReadResult`
+
+Query the instance.
+
+```typescript
+const result = await inst.read("Who is on the team?");
+console.log(result.reader_result);
+```
+
+Options: `{ readMode?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
 
-Query the instance and get a natural-language answer.
+### `inst.extract(text, options?)` → `ExtractResult`
+
+Extract objects from text without storing them.
 
 ```typescript
-const resp = await mem.read("Who is on the team?");
-console.log(resp.reader_result?.answer);
+const result = await inst.extract("Dave is an engineer in Tokyo.");
+console.log(result.objects_extracted);
 ```
 
-Options: `{ timeoutMs? }`.
+### `inst.getSchema(options?)` → `InstanceSchemaInfo`
+
+```typescript
+const schema = await inst.getSchema();
+console.log(schema.data_schema);
+```
+
+### `inst.describe(options?)` → `DescribeResult`
+
+Get agent-facing tool descriptions enriched with the instance's schema.
+
+```typescript
+const desc = await inst.describe();
+console.log(desc.asText());              // plain text for system prompts
+const tools = desc.asAnthropicTools();   // Anthropic tool-use format
+const tools = desc.asOpenaiTools();      // OpenAI function-calling format
+```
+
+Results are cached for 5 minutes. Call `inst.clearDescribeCache()` to force a refresh.
 
 ## Error handling
 
-All errors raise `XmemoryAPIError`.
+All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
 
 ```typescript
-import { XmemoryAPIError, xmemoryInstance } from "xmemory";
+import { XmemoryClient, XmemoryAPIError, XmemoryHealthCheckError } from "xmemory";
 
-const mem = await xmemoryInstance({ url: "https://api.xmemory.ai", token: "..." });
+try {
+  const xm = await XmemoryClient.create({ token: "..." });
+} catch (e) {
+  if (e instanceof XmemoryHealthCheckError) {
+    console.error("Server unreachable:", e.message);
+  }
+}
 
 try {
-  const resp = await mem.read("something");
+  await inst.read("query");
 } catch (e) {
   if (e instanceof XmemoryAPIError) {
     console.error(`API error (HTTP ${e.status}): ${e.message}`);
@@ -124,6 +205,14 @@ try {
 }
 ```
 
+## All timeouts are per-request
+
+Every method accepts an optional `timeoutMs` in its options bag, overriding the client default.
+
+```typescript
+const result = await inst.read("query", { timeoutMs: 120_000 });
+```
+
 ---
 
 ## Mastra integration

package/dist/client.d.ts

@@ -1,46 +1,44 @@
 /**
- * xmemory HTTP client for Node.js.
+ * XmemoryClient — main entry point for the xmemory API.
  */
-import type { AsyncWriteResponse, ExtractionLogic, ReadResponse, SchemaTypeValue, WriteResponse, WriteStatusResponse } from "./types.js";
-export { SchemaType } from "./types.js";
-export type { AsyncWriteResponse, CreateInstanceResponse, ExtractionLogic, ReadResponse, ReaderResult, SchemaTypeValue, WriteQueueStatus, WriteResponse, WriteStatusResponse, } from "./types.js";
-export declare class XmemoryAPIError extends Error {
-    readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
-}
-export interface XmemoryInstanceOptions {
-    url?: string;
-    token?: string;
-    timeoutMs?: number;
+import { InstanceHandle } from "./instance.js";
+import { type ClusterInfo, type CreateInstanceOptions, type GenerateSchemaOptions, type GenerateSchemaResult, type InstanceInfo, type InstanceSchemaInfo, type RequestOptions, type SchemaTypeValue, type XmemoryClientOptions } from "./types.js";
+export interface AdminNamespace {
+    listClusters(options?: RequestOptions & {
+        ids?: string[];
+    }): Promise<ClusterInfo[]>;
+    getCluster(clusterId: string, options?: RequestOptions): Promise<ClusterInfo>;
+    createInstance(clusterId: string, name: string, schemaText: string, schemaType: SchemaTypeValue, options?: CreateInstanceOptions): Promise<InstanceHandle>;
+    listInstances(options?: RequestOptions & {
+        ids?: string[];
+    }): Promise<InstanceInfo[]>;
+    getInstance(instanceId: string, options?: RequestOptions): Promise<InstanceInfo>;
+    deleteInstance(instanceId: string, options?: RequestOptions): Promise<string[]>;
+    getInstanceSchema(instanceId: string, options?: RequestOptions): Promise<InstanceSchemaInfo>;
+    updateInstanceSchema(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: RequestOptions): Promise<InstanceInfo>;
+    updateInstanceMetadata(instanceId: string, name: string, description: string, options?: RequestOptions): Promise<InstanceInfo>;
+    generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
 }
 export declare class XmemoryClient {
-    readonly baseUrl: string;
-    readonly timeoutMs: number;
-    readonly token: string | undefined;
-    instanceId: string | null;
-    constructor(options?: XmemoryInstanceOptions);
-    static create(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;
-    private checkHealth;
-    private requireInstanceId;
-    createInstance(schemaText: string, schemaType: SchemaTypeValue, timeoutMs?: number): Promise<boolean>;
-    write(text: string, options?: {
-        timeoutMs?: number;
-        extractionLogic?: ExtractionLogic;
-    }): Promise<WriteResponse>;
-    writeAsync(text: string, options?: {
-        timeoutMs?: number;
-        extractionLogic?: ExtractionLogic;
-        extractWriteId?: string;
-    }): Promise<AsyncWriteResponse>;
-    writeStatus(writeId: string, options?: {
-        timeoutMs?: number;
-    }): Promise<WriteStatusResponse>;
-    read(query: string, options?: {
-        timeoutMs?: number;
-    }): Promise<ReadResponse>;
-    get instance_id(): string | null;
+    private readonly _baseUrl;
+    private readonly _timeoutMs;
+    private readonly _token;
+    readonly admin: AdminNamespace;
+    constructor(options?: XmemoryClientOptions);
+    /** Factory that performs a health check before returning the client. */
+    static create(options?: XmemoryClientOptions): Promise<XmemoryClient>;
+    /** Return an InstanceHandle scoped to the given instance ID. */
+    instance(instanceId: string): InstanceHandle;
+    /** GET /healthz — throws XmemoryHealthCheckError on failure. */
+    checkHealth(): Promise<void>;
+    private _fetch;
+    private _headers;
+    /** Core request — returns the raw API wrapper `{ids, items, errors}`. */
+    private _request;
+    private _requestOne;
+    private _requestList;
+    private _requestIds;
+    private _buildAdmin;
 }
-/**
- * Create an xmemory client.
- */
-export declare function xmemoryInstance(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;
+/** Convenience factory — creates a client with a health check. */
+export declare function xmemoryInstance(options?: XmemoryClientOptions): Promise<XmemoryClient>;

package/dist/client.js

@@ -1,156 +1,208 @@
 /**
- * xmemory HTTP client for Node.js.
+ * XmemoryClient — main entry point for the xmemory API.
  */
-export { SchemaType } from "./types.js";
-const DEFAULT_BASE_URL = "http://0.0.0.0:8000";
+import { InstanceHandle } from "./instance.js";
+import { XmemoryAPIError, XmemoryHealthCheckError, buildInstanceSchema, } from "./types.js";
+const DEFAULT_BASE_URL = "https://api.xmemory.ai";
 const DEFAULT_TIMEOUT_MS = 60_000;
-export class XmemoryAPIError extends Error {
-    status;
-    constructor(message, status) {
-        super(message);
-        this.status = status;
-        this.name = "XmemoryAPIError";
-    }
-}
-async function getEnv(name) {
-    if (typeof process !== "undefined" && process.env) {
-        return process.env[name];
-    }
-    return undefined;
-}
-async function fetchWithTimeout(url, options) {
-    const { timeoutMs = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options;
-    const controller = new AbortController();
-    const id = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetch(url, {
-            ...fetchOptions,
-            signal: controller.signal,
-        });
-        return res;
-    }
-    finally {
-        clearTimeout(id);
-    }
-}
-async function postJson(baseUrl, path, body, token, timeoutMs) {
-    const url = `${baseUrl.replace(/\/$/, "")}${path}`;
-    const headers = {
-        Accept: "application/json",
-        "Content-Type": "application/json",
-    };
-    if (token) {
-        headers["Authorization"] = `Bearer ${token}`;
-    }
-    const res = await fetchWithTimeout(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        timeoutMs,
-    });
-    const raw = await res.text();
-    let payload;
-    try {
-        payload = raw ? JSON.parse(raw) : {};
-    }
-    catch {
-        throw new XmemoryAPIError(`Invalid JSON from server (${res.status})`, res.status);
-    }
-    if (typeof payload === "object" && payload !== null && payload.status === "error") {
-        const err = payload;
-        const msg = err.error_message || err.error || String(payload);
-        throw new XmemoryAPIError(`${path} failed: ${msg}`, res.status);
-    }
-    if (!res.ok) {
-        throw new XmemoryAPIError(`HTTP ${res.status}: ${raw.slice(0, 200)}`, res.status);
-    }
-    return payload;
-}
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
 export class XmemoryClient {
-    baseUrl;
-    timeoutMs;
-    token;
-    instanceId = null;
+    _baseUrl;
+    _timeoutMs;
+    _token;
+    admin;
     constructor(options = {}) {
-        this.baseUrl = options.url ?? "";
-        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-        this.token = options.token;
+        const env = typeof process !== "undefined" ? process.env : undefined;
+        this._baseUrl = (options.url ?? env?.XMEM_API_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this._token = options.token ?? env?.XMEM_AUTH_TOKEN;
+        this._timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.admin = this._buildAdmin();
     }
+    /** Factory that performs a health check before returning the client. */
     static async create(options = {}) {
-        const url = options.url ?? (await getEnv("XMEM_API_URL")) ?? DEFAULT_BASE_URL;
-        const token = options.token ?? (await getEnv("XMEM_AUTH_TOKEN"));
-        const client = new XmemoryClient({ ...options, url, token });
+        const client = new XmemoryClient(options);
         await client.checkHealth();
         return client;
     }
+    /** Return an InstanceHandle scoped to the given instance ID. */
+    instance(instanceId) {
+        return new InstanceHandle(instanceId, this._requestOne.bind(this));
+    }
+    /** GET /healthz — throws XmemoryHealthCheckError on failure. */
     async checkHealth() {
-        const url = `${this.baseUrl.replace(/\/$/, "")}/api/healthz`;
-        const res = await fetchWithTimeout(url, {
-            method: "GET",
-            headers: { Accept: "application/json" },
-            timeoutMs: this.timeoutMs,
-        });
-        if (!res.ok) {
-            throw new XmemoryAPIError(`Health check failed: ${res.status} at ${url}`, res.status);
+        const url = `${this._baseUrl}/healthz`;
+        try {
+            const res = await this._fetch(url, { method: "GET" }, this._timeoutMs);
+            if (!res.ok) {
+                throw new XmemoryHealthCheckError(`Health check failed: HTTP ${res.status} at ${url}`, res.status);
+            }
         }
-    }
-    requireInstanceId(op) {
-        if (!this.instanceId) {
-            throw new XmemoryAPIError(`instance_id is required for ${op}() but none was provided or saved.`);
+        catch (err) {
+            if (err instanceof XmemoryHealthCheckError)
+                throw err;
+            throw new XmemoryHealthCheckError(`Health check failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        return this.instanceId;
     }
-    async createInstance(schemaText, schemaType, timeoutMs) {
-        const path = "/instance/create";
-        const body = schemaType === 0 ? { yml_schema: schemaText } : { json_schema: schemaText };
-        const response = await postJson(this.baseUrl, path, body, this.token, timeoutMs ?? this.timeoutMs);
-        if (response.status === "ok" && response.instance_id) {
-            this.instanceId = response.instance_id;
+    // -----------------------------------------------------------------------
+    // Private: HTTP layer
+    // -----------------------------------------------------------------------
+    async _fetch(url, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
         }
-        return response.status === "ok";
-    }
-    async write(text, options) {
-        const iid = this.requireInstanceId("write");
-        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
-        return postJson(this.baseUrl, "/write", {
-            instance_id: iid,
-            text,
-            extraction_logic: options?.extractionLogic ?? "deep",
-        }, this.token, timeoutMs);
     }
-    async writeAsync(text, options) {
-        const iid = this.requireInstanceId("writeAsync");
-        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
-        const body = {
-            instance_id: iid,
-            text,
-            extraction_logic: options?.extractionLogic ?? "deep",
+    _headers(hasBody = false) {
+        const h = {
+            Accept: "application/json",
         };
-        if (options?.extractWriteId != null) {
-            body["extract_write_id"] = options.extractWriteId;
+        if (hasBody)
+            h["Content-Type"] = "application/json";
+        if (this._token)
+            h["Authorization"] = `Bearer ${this._token}`;
+        return h;
+    }
+    /** Core request — returns the raw API wrapper `{ids, items, errors}`. */
+    async _request(method, path, options) {
+        let url = `${this._baseUrl}${path}`;
+        if (options?.params) {
+            const sp = new URLSearchParams();
+            for (const [key, val] of Object.entries(options.params)) {
+                if (Array.isArray(val)) {
+                    for (const v of val)
+                        sp.append(key, v);
+                }
+                else {
+                    sp.append(key, val);
+                }
+            }
+            const qs = sp.toString();
+            if (qs)
+                url += `?${qs}`;
         }
-        return postJson(this.baseUrl, "/write_async", body, this.token, timeoutMs);
-    }
-    async writeStatus(writeId, options) {
-        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
-        return postJson(this.baseUrl, "/write_status", { write_id: writeId }, this.token, timeoutMs);
-    }
-    async read(query, options) {
-        const iid = this.requireInstanceId("read");
-        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
-        return postJson(this.baseUrl, "/read", {
-            instance_id: iid,
-            query,
-            mode: "single-answer",
-        }, this.token, timeoutMs);
+        const timeoutMs = options?.timeoutMs ?? this._timeoutMs;
+        const hasBody = !!(options?.body && method !== "GET");
+        const init = { method, headers: this._headers(hasBody) };
+        if (hasBody) {
+            init.body = JSON.stringify(options.body);
+        }
+        const res = await this._fetch(url, init, timeoutMs);
+        const raw = await res.text();
+        let payload;
+        try {
+            payload = raw ? JSON.parse(raw) : {};
+        }
+        catch {
+            throw new XmemoryAPIError(`Invalid JSON from server (${res.status}): ${raw.slice(0, 200)}`, res.status);
+        }
+        if (!res.ok) {
+            const msg = typeof payload === "object" && payload !== null && "message" in payload
+                ? String(payload.message)
+                : raw.slice(0, 200);
+            throw new XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status);
+        }
+        const response = payload;
+        if (response.errors?.length) {
+            const first = response.errors[0];
+            throw new XmemoryAPIError(`API error: ${first.message} (${first.code})`, res.status);
+        }
+        return response;
     }
-    get instance_id() {
-        return this.instanceId;
+    async _requestOne(method, path, options) {
+        const response = await this._request(method, path, options);
+        const items = response.items ?? [];
+        if (items.length === 0) {
+            throw new XmemoryAPIError(`Expected one item from ${method} ${path}, got none`);
+        }
+        if (items.length > 1) {
+            throw new XmemoryAPIError(`Expected one item from ${method} ${path}, got ${items.length}`);
+        }
+        return items[0];
+    }
+    async _requestList(method, path, options) {
+        const response = await this._request(method, path, options);
+        return (response.items ?? []);
+    }
+    async _requestIds(method, path, options) {
+        const response = await this._request(method, path, options);
+        return response.ids ?? [];
+    }
+    // -----------------------------------------------------------------------
+    // Private: build admin namespace
+    // -----------------------------------------------------------------------
+    _buildAdmin() {
+        return {
+            listClusters: async (options) => {
+                const params = options?.ids ? { ids: options.ids } : undefined;
+                return this._requestList("GET", "/clusters", { params, timeoutMs: options?.timeoutMs });
+            },
+            getCluster: async (clusterId, options) => {
+                return this._requestOne("GET", `/clusters/${clusterId}`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            createInstance: async (clusterId, name, schemaText, schemaType, options) => {
+                const body = {
+                    name,
+                    instance_schema: buildInstanceSchema(schemaText, schemaType),
+                };
+                if (options?.description != null)
+                    body.description = options.description;
+                if (options?.schemaDescription != null)
+                    body.schema_description = options.schemaDescription;
+                const info = await this._requestOne("POST", `/clusters/${clusterId}/instances`, {
+                    body,
+                    timeoutMs: options?.timeoutMs,
+                });
+                return this.instance(info.id);
+            },
+            listInstances: async (options) => {
+                const params = options?.ids ? { ids: options.ids } : undefined;
+                return this._requestList("GET", "/instances", { params, timeoutMs: options?.timeoutMs });
+            },
+            getInstance: async (instanceId, options) => {
+                return this._requestOne("GET", `/instances/${instanceId}`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            deleteInstance: async (instanceId, options) => {
+                return this._requestIds("DELETE", `/instances/${instanceId}`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            getInstanceSchema: async (instanceId, options) => {
+                return this._requestOne("GET", `/instances/${instanceId}/schema`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            updateInstanceSchema: async (instanceId, schemaText, schemaType, options) => {
+                return this._requestOne("PUT", `/instances/${instanceId}/schema`, {
+                    body: { instance_schema: buildInstanceSchema(schemaText, schemaType) },
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            updateInstanceMetadata: async (instanceId, name, description, options) => {
+                return this._requestOne("PUT", `/instances/${instanceId}`, {
+                    body: { name, description },
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            generateSchema: async (clusterId, schemaDescription, options) => {
+                const body = { schema_description: schemaDescription };
+                if (options?.currentYmlSchema != null)
+                    body.current_yml_schema = options.currentYmlSchema;
+                return this._requestOne("POST", `/clusters/${clusterId}/instances/generate_schema`, { body, timeoutMs: options?.timeoutMs });
+            },
+        };
     }
 }
-/**
- * Create an xmemory client.
- */
+/** Convenience factory — creates a client with a health check. */
 export async function xmemoryInstance(options = {}) {
     return XmemoryClient.create(options);
 }

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * xmemory — TypeScript client for the xmemory API.
+ */
+export { XmemoryClient, xmemoryInstance } from "./client.js";
+export type { AdminNamespace } from "./client.js";
+export { DescribeResult, InstanceHandle } from "./instance.js";
+export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
+export { SchemaType } from "./types.js";
+export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus } from "./types.js";
+export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, } from "./types.js";
+export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * xmemory — TypeScript client for the xmemory API.
+ */
+// Client
+export { XmemoryClient, xmemoryInstance } from "./client.js";
+// Instance handle
+export { DescribeResult, InstanceHandle } from "./instance.js";
+// Error classes
+export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
+// Enums
+export { SchemaType } from "./types.js";

package/dist/instance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * InstanceHandle — scoped data operations on a single xmemory instance.
+ */
+import type { AsyncWriteResult, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ToolDescription, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
+export declare class DescribeResult {
+    readonly instanceId: string;
+    readonly instanceName: string;
+    readonly schemaSummary: string;
+    readonly tools: readonly ToolDescription[];
+    constructor(raw: RawDescribeResult);
+    /**
+     * Plain-text representation suitable for injecting into an LLM system prompt.
+     *
+     * By default, tools are presented as method calls (matching the SDK).
+     * Set `includeHttp` to `true` to also show HTTP method and path for
+     * raw REST callers.
+     */
+    asText(options?: {
+        includeHttp?: boolean;
+    }): string;
+    /** Tool definitions in the Anthropic tool-use format. */
+    asAnthropicTools(): Record<string, unknown>[];
+    /** Tool definitions in the OpenAI function-calling format. */
+    asOpenaiTools(): Record<string, unknown>[];
+}
+export declare class InstanceHandle {
+    readonly id: string;
+    private readonly _requestOne;
+    private _describeCache;
+    private _describeCacheAt;
+    private _describeTtlMs;
+    constructor(id: string, requestOne: RequestOneFn);
+    read(query: string, options?: ReadOptions): Promise<ReadResult>;
+    write(text: string, options?: WriteOptions): Promise<WriteResult>;
+    writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
+    writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
+    extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
+    getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
+    /**
+     * Return agent-facing tool descriptions enriched with the instance schema.
+     *
+     * Results are cached locally with a TTL (default 5 min).
+     * Call `clearDescribeCache()` to force a refresh.
+     */
+    describe(options?: RequestOptions): Promise<DescribeResult>;
+    /** Clear the cached describe result so the next `describe()` call fetches fresh data. */
+    clearDescribeCache(): void;
+}

package/dist/instance.js

@@ -0,0 +1,188 @@
+/**
+ * InstanceHandle — scoped data operations on a single xmemory instance.
+ */
+const DEFAULT_DESCRIBE_TTL_MS = 300_000; // 5 minutes
+export class DescribeResult {
+    instanceId;
+    instanceName;
+    schemaSummary;
+    tools;
+    constructor(raw) {
+        this.instanceId = raw.instance_id;
+        this.instanceName = raw.instance_name;
+        this.schemaSummary = raw.schema_summary;
+        this.tools = raw.tools;
+    }
+    /**
+     * Plain-text representation suitable for injecting into an LLM system prompt.
+     *
+     * By default, tools are presented as method calls (matching the SDK).
+     * Set `includeHttp` to `true` to also show HTTP method and path for
+     * raw REST callers.
+     */
+    asText(options) {
+        const includeHttp = options?.includeHttp ?? false;
+        const lines = [];
+        lines.push(`Instance: ${this.instanceName} (${this.instanceId})`);
+        if (this.schemaSummary) {
+            lines.push(`\n${this.schemaSummary}`);
+        }
+        lines.push("\nAvailable tools:\n");
+        for (const tool of this.tools) {
+            const paramsSig = tool.parameters
+                .map((p) => p.name + (p.required ? "" : "?"))
+                .join(", ");
+            lines.push(`## ${tool.name}(${paramsSig})`);
+            lines.push(tool.description);
+            lines.push(`When to use: ${tool.when_to_use}`);
+            if (includeHttp) {
+                lines.push(`HTTP: ${tool.http_method} ${tool.http_path}`);
+            }
+            if (tool.parameters.length > 0) {
+                lines.push("Parameters:");
+                for (const p of tool.parameters) {
+                    const req = p.required ? "required" : "optional";
+                    lines.push(`  - ${p.name} (${p.type}, ${req}): ${p.description}`);
+                    if (p.enum) {
+                        lines.push(`    Allowed values: ${p.enum.join(", ")}`);
+                    }
+                    if (p.default != null) {
+                        lines.push(`    Default: ${p.default}`);
+                    }
+                }
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /** Tool definitions in the Anthropic tool-use format. */
+    asAnthropicTools() {
+        return this.tools.map((tool) => {
+            const { properties, required } = buildJsonSchemaProps(tool.parameters);
+            return {
+                name: tool.name,
+                description: `${tool.description}\n\nWhen to use: ${tool.when_to_use}`,
+                input_schema: { type: "object", properties, required },
+            };
+        });
+    }
+    /** Tool definitions in the OpenAI function-calling format. */
+    asOpenaiTools() {
+        return this.tools.map((tool) => {
+            const { properties, required } = buildJsonSchemaProps(tool.parameters);
+            return {
+                type: "function",
+                function: {
+                    name: tool.name,
+                    description: `${tool.description}\n\nWhen to use: ${tool.when_to_use}`,
+                    parameters: { type: "object", properties, required },
+                },
+            };
+        });
+    }
+}
+function buildJsonSchemaProps(params) {
+    const properties = {};
+    const required = [];
+    for (const p of params) {
+        const prop = { type: p.type, description: p.description };
+        if (p.enum)
+            prop.enum = p.enum;
+        properties[p.name] = prop;
+        if (p.required)
+            required.push(p.name);
+    }
+    return { properties, required };
+}
+export class InstanceHandle {
+    id;
+    _requestOne;
+    _describeCache = null;
+    _describeCacheAt = 0;
+    _describeTtlMs = DEFAULT_DESCRIBE_TTL_MS;
+    constructor(id, requestOne) {
+        this.id = id;
+        this._requestOne = requestOne;
+    }
+    async read(query, options) {
+        const body = {
+            query,
+            mode: options?.readMode ?? "single-answer",
+        };
+        if (options?.traceId != null)
+            body.trace_id = options.traceId;
+        return this._requestOne("POST", `/instances/${this.id}/read`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async write(text, options) {
+        const body = {
+            text,
+            extraction_logic: options?.extractionLogic ?? "deep",
+        };
+        if (options?.diffEngine != null)
+            body.diff_engine = options.diffEngine;
+        return this._requestOne("POST", `/instances/${this.id}/write`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async writeAsync(text, options) {
+        const body = {
+            text,
+            extraction_logic: options?.extractionLogic ?? "deep",
+        };
+        if (options?.diffEngine != null)
+            body.diff_engine = options.diffEngine;
+        return this._requestOne("POST", `/instances/${this.id}/write_async`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async writeStatus(writeId, options) {
+        return this._requestOne("POST", `/instances/${this.id}/write_status`, {
+            body: { write_id: writeId },
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async extract(text, options) {
+        const body = {
+            text,
+            extraction_logic: options?.extractionLogic ?? "deep",
+        };
+        return this._requestOne("POST", `/instances/${this.id}/extract`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async getSchema(options) {
+        return this._requestOne("GET", `/instances/${this.id}/schema`, {
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    /**
+     * Return agent-facing tool descriptions enriched with the instance schema.
+     *
+     * Results are cached locally with a TTL (default 5 min).
+     * Call `clearDescribeCache()` to force a refresh.
+     */
+    async describe(options) {
+        const now = Date.now();
+        if (this._describeCache && now - this._describeCacheAt < this._describeTtlMs) {
+            return this._describeCache;
+        }
+        const raw = await this._requestOne("GET", `/instances/${this.id}/describe`, {
+            timeoutMs: options?.timeoutMs,
+        });
+        const result = new DescribeResult(raw);
+        this._describeCache = result;
+        this._describeCacheAt = now;
+        return result;
+    }
+    /** Clear the cached describe result so the next `describe()` call fetches fresh data. */
+    clearDescribeCache() {
+        this._describeCache = null;
+        this._describeCacheAt = 0;
+    }
+}

package/dist/types.d.ts

@@ -1,57 +1,133 @@
 /**
- * Types for the xmemory API.
+ * Types, enums, and error classes for the xmemory API.
  */
 export declare const SchemaType: {
     readonly YML: 0;
     readonly JSON: 1;
 };
 export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
-export interface CreateInstanceYMLRequest {
-    yml_schema: string;
+export type ExtractionLogic = "fast" | "regular" | "deep";
+export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
+export type WriteQueueStatus = "queued" | "processing" | "completed" | "failed" | "not_found";
+export declare class XmemoryAPIError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
 }
-export interface CreateInstanceResponse {
-    status: "ok" | "error";
-    instance_id?: string | null;
-    error_message?: string | null;
+export declare class XmemoryHealthCheckError extends XmemoryAPIError {
+    constructor(message: string, status?: number);
 }
-export type ExtractionLogic = "fast" | "regular" | "deep";
-export interface WriteRequest {
-    instance_id: string;
-    text: string;
-    extraction_logic?: ExtractionLogic;
-}
-export interface WriteResponse {
-    status: "ok" | "error";
-    error_message?: string | null;
-}
-export interface ReadRequest {
-    instance_id: string;
-    query: string;
-    mode?: "single-answer" | "raw-tables" | "xresponse";
-}
-export interface ReaderResult {
-    answer?: string;
-    [key: string]: unknown;
-}
-export interface ReadResponse {
-    status: "ok" | "error";
-    reader_result?: ReaderResult | null;
-    error_message?: string | null;
-}
-export interface AsyncWriteResponse {
-    status: "ok" | "error";
-    write_id?: string | null;
-    error_message?: string | null;
+export interface ClusterInfo {
+    readonly id: string;
+    readonly org_id: string;
+    readonly name: string;
+    readonly description: string | null;
 }
-export type WriteQueueStatus = "queued" | "processing" | "completed" | "failed" | "not_found";
-export interface WriteStatusRequest {
-    write_id: string;
+export interface InstanceInfo {
+    readonly id: string;
+    readonly cluster_id: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly data_schema: Record<string, unknown> | null;
+}
+export interface InstanceSchemaInfo {
+    readonly data_schema: Record<string, unknown>;
+}
+export interface ReadResult {
+    readonly trace_id: string | null;
+    readonly reader_result: unknown;
+}
+export interface WriteResult {
+    readonly write_id: string;
+    readonly trace_id: string | null;
+    readonly cleaned_objects: unknown;
+    readonly diff_plan: unknown;
+}
+export interface AsyncWriteResult {
+    readonly write_id: string;
+}
+export interface WriteStatusResult {
+    readonly write_id: string;
+    readonly write_status: WriteQueueStatus;
+    readonly error_detail: string | null;
+    readonly completed_at: string | null;
+}
+export interface ExtractResult {
+    readonly trace_id: string | null;
+    readonly objects_extracted: unknown;
+}
+export interface GenerateSchemaResult {
+    readonly data_schema: Record<string, unknown>;
+}
+export interface ToolParameterDescription {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+    readonly required: boolean;
+    readonly enum?: string[];
+    readonly default?: string;
+}
+export interface ToolDescription {
+    readonly name: string;
+    readonly description: string;
+    readonly when_to_use: string;
+    readonly parameters: ToolParameterDescription[];
+    readonly http_method: string;
+    readonly http_path: string;
+}
+export interface RawDescribeResult {
+    readonly instance_id: string;
+    readonly instance_name: string;
+    readonly schema_summary: string;
+    readonly tools: ToolDescription[];
+}
+export interface XmemoryClientOptions {
+    url?: string;
+    token?: string;
+    timeoutMs?: number;
+}
+export interface RequestOptions {
+    timeoutMs?: number;
+}
+export interface ReadOptions {
+    readMode?: ReadMode;
+    traceId?: string;
+    timeoutMs?: number;
+}
+export interface WriteOptions {
+    extractionLogic?: ExtractionLogic;
+    diffEngine?: boolean;
+    timeoutMs?: number;
+}
+export interface ExtractOptions {
+    extractionLogic?: ExtractionLogic;
+    timeoutMs?: number;
+}
+export interface CreateInstanceOptions {
+    description?: string;
+    schemaDescription?: string;
+    timeoutMs?: number;
+}
+export interface GenerateSchemaOptions {
+    currentYmlSchema?: string;
+    timeoutMs?: number;
+}
+export interface ApiError {
+    readonly code: string;
+    readonly message: string;
+    readonly field?: string;
+    readonly resource_id?: string;
+}
+export interface RawApiResponse {
+    readonly ids?: string[];
+    readonly items?: unknown[];
+    readonly errors?: ApiError[];
 }
-export interface WriteStatusResponse {
-    status: "ok" | "error";
-    write_id: string;
-    write_status: WriteQueueStatus;
-    error_detail?: string | null;
-    completed_at?: string | null;
-    error_message?: string | null;
+export interface InternalRequestOptions {
+    body?: Record<string, unknown>;
+    params?: Record<string, string | string[]>;
+    timeoutMs?: number;
 }
+export type RequestOneFn = <T>(method: string, path: string, options?: InternalRequestOptions) => Promise<T>;
+export type RequestListFn = <T>(method: string, path: string, options?: InternalRequestOptions) => Promise<T[]>;
+export type RequestIdsFn = (method: string, path: string, options?: InternalRequestOptions) => Promise<string[]>;
+export declare function buildInstanceSchema(schemaText: string, schemaType: SchemaTypeValue): Record<string, unknown>;

package/dist/types.js

@@ -1,7 +1,30 @@
 /**
- * Types for the xmemory API.
+ * Types, enums, and error classes for the xmemory API.
  */
-export const SchemaType = {
-    YML: 0,
-    JSON: 1,
-};
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+export const SchemaType = { YML: 0, JSON: 1 };
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+export class XmemoryAPIError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "XmemoryAPIError";
+    }
+}
+export class XmemoryHealthCheckError extends XmemoryAPIError {
+    constructor(message, status) {
+        super(message, status);
+        this.name = "XmemoryHealthCheckError";
+    }
+}
+export function buildInstanceSchema(schemaText, schemaType) {
+    if (schemaType === SchemaType.YML) {
+        return { yml: { value: schemaText } };
+    }
+    return { json_schema: { value: schemaText } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "xmemory",
   "keywords": [
     "xmemory"
@@ -16,14 +16,15 @@
   "license": "MIT",
   "author": "Dima Korolev",
   "type": "module",
-  "main": "dist/client.js",
-  "types": "dist/client.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsc",
     "test": "tsc --noEmit && node --import tsx test.ts",
+    "test:types": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {