xmemory 2.0.0 → 2.1.1

package/README.md

@@ -15,7 +15,7 @@ import { XmemoryClient } from "xmemory";
 
 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
+  apiKey: "<your-api-key>",       // or set XMEM_API_KEY env var
 });
 
 // Write and read from an existing instance
@@ -28,11 +28,13 @@ console.log(result.reader_result);
 
 ## Configuration
 
-| 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 |
+| Parameter   | Env var          | Default                   | Description                             |
+|-------------|------------------|---------------------------|-----------------------------------------|
+| `url`       | `XMEM_API_URL`   | `https://api.xmemory.ai`  | Base URL of the Xmemory API             |
+| `apiKey`    | `XMEM_API_KEY`   | `undefined`               | Bearer API key for authentication       |
+| `timeoutMs` | —                | `60000`                   | Default request timeout in milliseconds |
+
+The legacy `token` option and `XMEM_AUTH_TOKEN` env var are still accepted for backwards compatibility but are deprecated and will be removed in a future release. Using them prints a deprecation warning. If both the new and legacy values are set, the new ones win.
 
 ## Creating a client
 
@@ -40,13 +42,13 @@ console.log(result.reader_result);
 import { XmemoryClient, xmemoryInstance } from "xmemory";
 
 // Option 1: constructor (no health check)
-const xm1 = new XmemoryClient({ token: "..." });
+const xm1 = new XmemoryClient({ apiKey: "..." });
 
 // Option 2: factory with health check
-const xm2 = await XmemoryClient.create({ token: "..." });
+const xm2 = await XmemoryClient.create({ apiKey: "..." });
 
 // Option 3: convenience function (same as Option 2)
-const xm3 = await xmemoryInstance({ token: "..." });
+const xm3 = await xmemoryInstance({ apiKey: "..." });
 ```
 
 ## Admin operations
@@ -168,6 +170,19 @@ 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 throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
@@ -176,7 +191,7 @@ All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCh
 import { XmemoryClient, XmemoryAPIError, XmemoryHealthCheckError } from "xmemory";
 
 try {
-  const xm = await XmemoryClient.create({ token: "..." });
+  const xm = await XmemoryClient.create({ apiKey: "..." });
 } catch (e) {
   if (e instanceof XmemoryHealthCheckError) {
     console.error("Server unreachable:", e.message);

package/dist/client.d.ts

@@ -22,9 +22,10 @@ export interface AdminNamespace {
 export declare class XmemoryClient {
     private readonly _baseUrl;
     private readonly _timeoutMs;
-    private readonly _token;
+    private readonly _apiKey;
     readonly admin: AdminNamespace;
     constructor(options?: XmemoryClientOptions);
+    private static _resolveApiKey;
     /** 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. */

package/dist/client.js

@@ -5,21 +5,41 @@ 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;
+const ORANGE = "\x1b[38;5;208m";
+const RESET = "\x1b[0m";
+function deprecationWarning(message) {
+    console.warn(`${ORANGE}[xmemory] DEPRECATION: ${message}${RESET}`);
+}
 // ---------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------
 export class XmemoryClient {
     _baseUrl;
     _timeoutMs;
-    _token;
+    _apiKey;
     admin;
     constructor(options = {}) {
         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._apiKey = XmemoryClient._resolveApiKey(options, env);
         this._timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.admin = this._buildAdmin();
     }
+    static _resolveApiKey(options, env) {
+        if (options.apiKey != null)
+            return options.apiKey;
+        if (options.token != null) {
+            deprecationWarning("The `token` constructor option is deprecated and will be removed soon. Use `apiKey` instead.");
+            return options.token;
+        }
+        if (env?.XMEM_API_KEY)
+            return env.XMEM_API_KEY;
+        if (env?.XMEM_AUTH_TOKEN) {
+            deprecationWarning("The `XMEM_AUTH_TOKEN` environment variable is deprecated and will be removed soon. Use `XMEM_API_KEY` instead.");
+            return env.XMEM_AUTH_TOKEN;
+        }
+        return undefined;
+    }
     /** Factory that performs a health check before returning the client. */
     static async create(options = {}) {
         const client = new XmemoryClient(options);
@@ -64,8 +84,8 @@ export class XmemoryClient {
         };
         if (hasBody)
             h["Content-Type"] = "application/json";
-        if (this._token)
-            h["Authorization"] = `Bearer ${this._token}`;
+        if (this._apiKey)
+            h["Authorization"] = `Bearer ${this._apiKey}`;
         return h;
     }
     /** Core request — returns the raw API wrapper `{ids, items, errors}`. */

package/dist/index.d.ts

@@ -3,9 +3,9 @@
  */
 export { XmemoryClient, xmemoryInstance } from "./client.js";
 export type { AdminNamespace } from "./client.js";
-export { InstanceHandle } from "./instance.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, } from "./types.js";
+export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";

package/dist/index.js

@@ -4,7 +4,7 @@
 // Client
 export { XmemoryClient, xmemoryInstance } from "./client.js";
 // Instance handle
-export { InstanceHandle } from "./instance.js";
+export { DescribeResult, InstanceHandle } from "./instance.js";
 // Error classes
 export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
 // Enums

package/dist/instance.d.ts

@@ -1,10 +1,34 @@
 /**
  * InstanceHandle — scoped data operations on a single xmemory instance.
  */
-import type { AsyncWriteResult, ExtractOptions, ExtractResult, InstanceSchemaInfo, ReadOptions, ReadResult, RequestOneFn, RequestOptions, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
+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>;
@@ -12,4 +36,13 @@ export declare class InstanceHandle {
     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

@@ -1,9 +1,105 @@
 /**
  * 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;
@@ -65,4 +161,28 @@ export class InstanceHandle {
             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

@@ -58,8 +58,32 @@ export interface ExtractResult {
 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;
+    apiKey?: string;
+    /** @deprecated Use `apiKey` instead. Will be removed in a future release. */
     token?: string;
     timeoutMs?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "xmemory",
   "keywords": [
     "xmemory"