xmemory 1.0.1 → 1.2.0

package/README.md

@@ -1,8 +1,134 @@
-# `xmemory`
+# xmemory
 
-Integration code with `xmemory`.
+TypeScript/JavaScript client library for the [Xmemory](https://xmemory.ai) API.
 
-For now just the Mastra prompt.
+## Quick start
+
+```typescript
+import { xmemoryInstance } 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
+});
+
+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
+
+```bash
+npm install xmemory
+```
+
+## 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 |
+
+## 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 2: static create method (also runs a health check)
+const mem = await XmemoryClient.create({ url: "https://api.xmemory.ai", token: "..." });
+
+// Option 3: constructor (no health check)
+const mem = new XmemoryClient({ url: "https://api.xmemory.ai", token: "..." });
+```
+
+## Methods
+
+### `createInstance(schemaText, schemaType, timeoutMs?) → Promise<boolean>`
+
+Create a new instance with the given schema. On success the new `instanceId`
+is saved automatically and used for subsequent calls.
+
+```typescript
+import { SchemaType } from "xmemory";
+
+const ok = await mem.createInstance(schemaYml, SchemaType.YML);
+const ok = await mem.createInstance(schemaJson, SchemaType.JSON);
+```
+
+### `write(text, options?) → Promise<WriteResponse>`
+
+Extract structured objects from `text` and store them in the instance.
+
+```typescript
+const resp = await mem.write("Bob joined the team on Monday as a designer.");
+console.log(resp.status); // "ok" or "error"
+```
+
+Options: `{ timeoutMs?, extractionLogic? }` where `extractionLogic` is `"fast"`, `"regular"`, or `"deep"` (default: `"deep"`).
+
+### `writeAsync(text, options?) → Promise<AsyncWriteResponse>`
+
+Start an asynchronous write and return immediately with a `write_id` for tracking.
+
+```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
+```
+
+Options: `{ timeoutMs?, extractionLogic?, extractWriteId? }`.
+
+### `writeStatus(writeId, options?) → Promise<WriteStatusResponse>`
+
+Check the status of an async write operation.
+
+```typescript
+const status = await mem.writeStatus(resp.write_id);
+console.log(status.write_status); // "queued" | "processing" | "completed" | "failed" | "not_found"
+```
+
+### `read(query, options?) → Promise<ReadResponse>`
+
+Query the instance and get a natural-language answer.
+
+```typescript
+const resp = await mem.read("Who is on the team?");
+console.log(resp.reader_result?.answer);
+```
+
+Options: `{ timeoutMs? }`.
+
+## Error handling
+
+All errors raise `XmemoryAPIError`.
+
+```typescript
+import { XmemoryAPIError, xmemoryInstance } from "xmemory";
+
+const mem = await xmemoryInstance({ url: "https://api.xmemory.ai", token: "..." });
+
+try {
+  const resp = await mem.read("something");
+} catch (e) {
+  if (e instanceof XmemoryAPIError) {
+    console.error(`API error (HTTP ${e.status}): ${e.message}`);
+  }
+}
+```
+
+---
+
+## Mastra integration
+
+You can also use `xmemory` as an MCP server within [Mastra.ai](https://mastra.ai).
 
 First, create a local Mastra instance:
 

package/dist/client.d.ts

@@ -1,9 +1,9 @@
 /**
  * xmemory HTTP client for Node.js.
  */
-import type { ReadResponse, SchemaTypeValue, WriteResponse } from "./types.js";
+import type { AsyncWriteResponse, ExtractionLogic, ReadResponse, SchemaTypeValue, WriteResponse, WriteStatusResponse } from "./types.js";
 export { SchemaType } from "./types.js";
-export type { SchemaTypeValue, CreateInstanceResponse, WriteResponse, ReadResponse, ReaderResult } 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);
@@ -11,7 +11,7 @@ export declare class XmemoryAPIError extends Error {
 export interface XmemoryInstanceOptions {
     url?: string;
     token?: string;
-    timeout?: number;
+    timeoutMs?: number;
 }
 export declare class XmemoryClient {
     readonly baseUrl: string;
@@ -22,12 +22,21 @@ export declare class XmemoryClient {
     static create(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;
     private checkHealth;
     private requireInstanceId;
-    createInstance(schemaText: string, schemaType: SchemaTypeValue, timeout?: number): Promise<boolean>;
+    createInstance(schemaText: string, schemaType: SchemaTypeValue, timeoutMs?: number): Promise<boolean>;
     write(text: string, options?: {
-        timeout?: number;
+        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?: {
-        timeout?: number;
+        timeoutMs?: number;
     }): Promise<ReadResponse>;
     get instance_id(): string | null;
 }

package/dist/client.js

@@ -73,7 +73,7 @@ export class XmemoryClient {
     instanceId = null;
     constructor(options = {}) {
         this.baseUrl = options.url ?? "";
-        this.timeoutMs = (options.timeout ?? 60) * 1000;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.token = options.token;
     }
     static async create(options = {}) {
@@ -100,11 +100,10 @@ export class XmemoryClient {
         }
         return this.instanceId;
     }
-    async createInstance(schemaText, schemaType, timeout) {
+    async createInstance(schemaText, schemaType, timeoutMs) {
         const path = "/instance/create";
         const body = schemaType === 0 ? { yml_schema: schemaText } : { json_schema: schemaText };
-        const timeoutMs = timeout != null ? timeout * 1000 : this.timeoutMs;
-        const response = await postJson(this.baseUrl, path, body, this.token, timeoutMs);
+        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;
         }
@@ -112,16 +111,33 @@ export class XmemoryClient {
     }
     async write(text, options) {
         const iid = this.requireInstanceId("write");
-        const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.timeoutMs;
+        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
         return postJson(this.baseUrl, "/write", {
             instance_id: iid,
             text,
-            extraction_logic: "deep",
+            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",
+        };
+        if (options?.extractWriteId != null) {
+            body["extract_write_id"] = options.extractWriteId;
+        }
+        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?.timeout != null ? options.timeout * 1000 : this.timeoutMs;
+        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
         return postJson(this.baseUrl, "/read", {
             instance_id: iid,
             query,

package/dist/types.d.ts

@@ -14,10 +14,11 @@ export interface CreateInstanceResponse {
     instance_id?: string | null;
     error_message?: string | null;
 }
+export type ExtractionLogic = "fast" | "regular" | "deep";
 export interface WriteRequest {
     instance_id: string;
     text: string;
-    extraction_logic?: "fast" | "regular" | "deep";
+    extraction_logic?: ExtractionLogic;
 }
 export interface WriteResponse {
     status: "ok" | "error";
@@ -37,3 +38,20 @@ export interface ReadResponse {
     reader_result?: ReaderResult | null;
     error_message?: string | null;
 }
+export interface AsyncWriteResponse {
+    status: "ok" | "error";
+    write_id?: string | null;
+    error_message?: string | null;
+}
+export type WriteQueueStatus = "queued" | "processing" | "completed" | "failed" | "not_found";
+export interface WriteStatusRequest {
+    write_id: string;
+}
+export interface WriteStatusResponse {
+    status: "ok" | "error";
+    write_id: string;
+    write_status: WriteQueueStatus;
+    error_detail?: string | null;
+    completed_at?: string | null;
+    error_message?: string | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "xmemory",
   "keywords": [
     "xmemory"