xmemory 1.0.0 → 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

@@ -0,0 +1,46 @@
+/**
+ * xmemory HTTP client for Node.js.
+ */
+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;
+}
+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;
+}
+/**
+ * Create an xmemory client.
+ */
+export declare function xmemoryInstance(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;

package/dist/client.js

@@ -0,0 +1,156 @@
+/**
+ * xmemory HTTP client for Node.js.
+ */
+export { SchemaType } from "./types.js";
+const DEFAULT_BASE_URL = "http://0.0.0.0:8000";
+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;
+}
+export class XmemoryClient {
+    baseUrl;
+    timeoutMs;
+    token;
+    instanceId = null;
+    constructor(options = {}) {
+        this.baseUrl = options.url ?? "";
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.token = options.token;
+    }
+    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 });
+        await client.checkHealth();
+        return client;
+    }
+    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);
+        }
+    }
+    requireInstanceId(op) {
+        if (!this.instanceId) {
+            throw new XmemoryAPIError(`instance_id is required for ${op}() but none was provided or saved.`);
+        }
+        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;
+        }
+        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",
+        };
+        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?.timeoutMs ?? this.timeoutMs;
+        return postJson(this.baseUrl, "/read", {
+            instance_id: iid,
+            query,
+            mode: "single-answer",
+        }, this.token, timeoutMs);
+    }
+    get instance_id() {
+        return this.instanceId;
+    }
+}
+/**
+ * Create an xmemory client.
+ */
+export async function xmemoryInstance(options = {}) {
+    return XmemoryClient.create(options);
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Types 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 interface CreateInstanceResponse {
+    status: "ok" | "error";
+    instance_id?: string | null;
+    error_message?: string | null;
+}
+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 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/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the xmemory API.
+ */
+export const SchemaType = {
+    YML: 0,
+    JSON: 1,
+};

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "xmemory",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "xmemory",
-  "keywords": [ "xmemory" ],
+  "keywords": [
+    "xmemory"
+  ],
   "homepage": "https://github.com/xmemory-ai/xmemory-npm",
   "bugs": {
     "url": "https://github.com/xmemory-ai/xmemory-npm/issues"
@@ -13,12 +15,20 @@
   },
   "license": "MIT",
   "author": "Dima Korolev",
-  "type": "commonjs",
-  "main": "index.js",
-  "bin": {
-    "xmemory": "cli.js"
-  },
+  "type": "module",
+  "main": "dist/client.js",
+  "types": "dist/client.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc",
+    "test": "tsc --noEmit && node --import tsx test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
   }
 }

package/cli.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-
-const greet = require("./index");
-
-const name = process.argv[2];
-console.log(greet(name));

package/index.js

@@ -1,11 +0,0 @@
-// NOTE(dkorolev): There will be more to this module.
-// For now it's just the prompt to connect `xmemory` to Mastra.
-
-function greet(name) {
-  if (name) {
-    return `Hello, ${name}!`;
-  }
-  return "Hello, xmemory!";
-}
-
-module.exports = greet;