xmemory 2.0.0 → 2.1.0

package/README.md

@@ -168,6 +168,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).

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,6 +58,28 @@ 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;
     token?: string;

package/package.json

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