xmem-ai 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { XMemClient } from "./src/client";
+export type { APIEnvelope, DomainResult, HealthStatus, IngestParams, IngestResult, OperationDetail, RetrieveParams, RetrieveResult, SearchParams, SearchResult, SourceRecord, WeaverSummary, } from "./src/types";
+export { XMemSDKError, AuthenticationError, ConnectionError, NotReadyError, RateLimitError, ServerError, ValidationError, } from "./src/error";

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.ServerError = exports.RateLimitError = exports.NotReadyError = exports.ConnectionError = exports.AuthenticationError = exports.XMemSDKError = exports.XMemClient = void 0;
+var client_1 = require("./src/client");
+Object.defineProperty(exports, "XMemClient", { enumerable: true, get: function () { return client_1.XMemClient; } });
+var error_1 = require("./src/error");
+Object.defineProperty(exports, "XMemSDKError", { enumerable: true, get: function () { return error_1.XMemSDKError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return error_1.AuthenticationError; } });
+Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return error_1.ConnectionError; } });
+Object.defineProperty(exports, "NotReadyError", { enumerable: true, get: function () { return error_1.NotReadyError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_1.RateLimitError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return error_1.ServerError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return error_1.ValidationError; } });

package/dist/src/client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * XMem TypeScript client.
+ *
+ * ```ts
+ * import { XMemClient } from "@xmem/sdk";
+ *
+ * const client = new XMemClient("http://localhost:8000", "sk-...");
+ * const result = await client.ingest({ user_query: "I love hiking", user_id: "u1" });
+ * const answer = await client.retrieve({ query: "hobbies", user_id: "u1" });
+ * console.log(answer.answer);
+ * ```
+ */
+import type { HealthStatus, IngestParams, IngestResult, RetrieveParams, RetrieveResult, SearchParams, SearchResult } from "./types";
+export declare class XMemClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(apiUrl?: string, apiKey?: string);
+    private req;
+    ping(): Promise<HealthStatus>;
+    isReady(): Promise<boolean>;
+    ingest(params: IngestParams): Promise<IngestResult>;
+    retrieve(params: RetrieveParams): Promise<RetrieveResult>;
+    search(params: SearchParams): Promise<SearchResult>;
+}

package/dist/src/client.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * XMem TypeScript client.
+ *
+ * ```ts
+ * import { XMemClient } from "@xmem/sdk";
+ *
+ * const client = new XMemClient("http://localhost:8000", "sk-...");
+ * const result = await client.ingest({ user_query: "I love hiking", user_id: "u1" });
+ * const answer = await client.retrieve({ query: "hobbies", user_id: "u1" });
+ * console.log(answer.answer);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XMemClient = void 0;
+const network_1 = require("./network");
+class XMemClient {
+    constructor(apiUrl, apiKey) {
+        this.baseUrl = (apiUrl || process.env.XMEM_API_URL || "http://localhost:8000").replace(/\/$/, "");
+        const key = apiKey || process.env.XMEM_API_KEY || "";
+        this.headers = {
+            "Content-Type": "application/json",
+            ...(key ? { Authorization: `Bearer ${key}` } : {}),
+        };
+    }
+    async req(method, path, body) {
+        return (0, network_1.request)(this.baseUrl, path, {
+            method,
+            headers: this.headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    // ── Health ───────────────────────────────────────────────────────
+    async ping() {
+        try {
+            const env = await this.req("GET", "/health");
+            return env.data;
+        }
+        catch {
+            return { status: "unreachable", pipelines_ready: false, version: "" };
+        }
+    }
+    async isReady() {
+        return (await this.ping()).pipelines_ready;
+    }
+    // ── Ingest ───────────────────────────────────────────────────────
+    async ingest(params) {
+        const env = await this.req("POST", "/v1/memory/ingest", params);
+        return { ...env.data, request_id: env.request_id, elapsed_ms: env.elapsed_ms };
+    }
+    // ── Retrieve ─────────────────────────────────────────────────────
+    async retrieve(params) {
+        const env = await this.req("POST", "/v1/memory/retrieve", params);
+        return { ...env.data, request_id: env.request_id, elapsed_ms: env.elapsed_ms };
+    }
+    // ── Search ───────────────────────────────────────────────────────
+    async search(params) {
+        const env = await this.req("POST", "/v1/memory/search", params);
+        return { ...env.data, request_id: env.request_id, elapsed_ms: env.elapsed_ms };
+    }
+}
+exports.XMemClient = XMemClient;

package/dist/src/error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Error hierarchy for the XMem TypeScript SDK.
+ */
+export declare class XMemSDKError extends Error {
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    constructor(message: string, statusCode?: number, requestId?: string);
+}
+export declare class AuthenticationError extends XMemSDKError {
+    constructor(message: string, statusCode?: number, requestId?: string);
+}
+export declare class RateLimitError extends XMemSDKError {
+    readonly retryAfter?: number;
+    constructor(message: string, statusCode?: number, requestId?: string, retryAfter?: number);
+}
+export declare class ServerError extends XMemSDKError {
+    constructor(message: string, statusCode?: number, requestId?: string);
+}
+export declare class ValidationError extends XMemSDKError {
+    constructor(message: string, statusCode?: number, requestId?: string);
+}
+export declare class NotReadyError extends XMemSDKError {
+    constructor(message: string, statusCode?: number, requestId?: string);
+}
+export declare class ConnectionError extends XMemSDKError {
+    constructor(message: string);
+}

package/dist/src/error.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Error hierarchy for the XMem TypeScript SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionError = exports.NotReadyError = exports.ValidationError = exports.ServerError = exports.RateLimitError = exports.AuthenticationError = exports.XMemSDKError = void 0;
+class XMemSDKError extends Error {
+    constructor(message, statusCode, requestId) {
+        super(message);
+        this.name = "XMemSDKError";
+        this.statusCode = statusCode;
+        this.requestId = requestId;
+    }
+}
+exports.XMemSDKError = XMemSDKError;
+class AuthenticationError extends XMemSDKError {
+    constructor(message, statusCode, requestId) {
+        super(message, statusCode, requestId);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class RateLimitError extends XMemSDKError {
+    constructor(message, statusCode, requestId, retryAfter) {
+        super(message, statusCode, requestId);
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+class ServerError extends XMemSDKError {
+    constructor(message, statusCode, requestId) {
+        super(message, statusCode, requestId);
+        this.name = "ServerError";
+    }
+}
+exports.ServerError = ServerError;
+class ValidationError extends XMemSDKError {
+    constructor(message, statusCode, requestId) {
+        super(message, statusCode, requestId);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+class NotReadyError extends XMemSDKError {
+    constructor(message, statusCode, requestId) {
+        super(message, statusCode, requestId);
+        this.name = "NotReadyError";
+    }
+}
+exports.NotReadyError = NotReadyError;
+class ConnectionError extends XMemSDKError {
+    constructor(message) {
+        super(message);
+        this.name = "ConnectionError";
+    }
+}
+exports.ConnectionError = ConnectionError;

package/dist/src/network.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Internal HTTP transport for the XMem TypeScript SDK.
+ */
+import type { APIEnvelope } from "./types";
+export declare function request<T = Record<string, unknown>>(baseUrl: string, path: string, init: RequestInit): Promise<APIEnvelope<T>>;

package/dist/src/network.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Internal HTTP transport for the XMem TypeScript SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = request;
+const error_1 = require("./error");
+function mapError(status, body) {
+    const msg = body.error || body.detail || `HTTP ${status}`;
+    const rid = body.request_id;
+    if (status === 401 || status === 403)
+        return new error_1.AuthenticationError(msg, status, rid);
+    if (status === 422)
+        return new error_1.ValidationError(msg, status, rid);
+    if (status === 429)
+        return new error_1.RateLimitError(msg, status, rid, Number(body.retry_after ?? 60));
+    if (status === 503)
+        return new error_1.NotReadyError(msg, status, rid);
+    if (status >= 500)
+        return new error_1.ServerError(msg, status, rid);
+    return new error_1.XMemSDKError(msg, status, rid);
+}
+async function request(baseUrl, path, init) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl}${path}`, init);
+    }
+    catch (err) {
+        throw new error_1.ConnectionError(`Connection failed: ${err}`);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        if (response.status >= 400) {
+            throw mapError(response.status, { error: await response.text().catch(() => "") });
+        }
+        throw new error_1.XMemSDKError(`Unparseable response (HTTP ${response.status})`);
+    }
+    if (response.status >= 400) {
+        throw mapError(response.status, body);
+    }
+    if (body.status === "error") {
+        throw mapError(response.status || 500, body);
+    }
+    return {
+        status: "ok",
+        data: body.data,
+        error: body.error,
+        request_id: body.request_id,
+        elapsed_ms: body.elapsed_ms,
+    };
+}

package/dist/src/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Public types for the XMem TypeScript SDK.
+ */
+export interface APIEnvelope<T = Record<string, unknown>> {
+    status: "ok" | "error";
+    data?: T;
+    error?: string;
+    request_id?: string;
+    elapsed_ms?: number;
+}
+export interface HealthStatus {
+    status: string;
+    pipelines_ready: boolean;
+    version: string;
+    uptime_seconds?: number;
+    error?: string;
+}
+export interface IngestParams {
+    user_query: string;
+    user_id: string;
+    agent_response?: string;
+    session_datetime?: string;
+    image_url?: string;
+}
+export interface OperationDetail {
+    type: string;
+    content: string;
+    reason: string;
+}
+export interface WeaverSummary {
+    succeeded: number;
+    skipped: number;
+    failed: number;
+}
+export interface DomainResult {
+    confidence: number;
+    operations: OperationDetail[];
+    weaver?: WeaverSummary;
+}
+export interface IngestResult {
+    model: string;
+    classification: unknown[];
+    profile?: DomainResult;
+    temporal?: DomainResult;
+    summary?: DomainResult;
+    image?: DomainResult;
+    request_id?: string;
+    elapsed_ms?: number;
+}
+export interface RetrieveParams {
+    query: string;
+    user_id: string;
+    top_k?: number;
+}
+export interface SourceRecord {
+    domain: string;
+    content: string;
+    score: number;
+    metadata: Record<string, unknown>;
+}
+export interface RetrieveResult {
+    model: string;
+    answer: string;
+    sources: SourceRecord[];
+    confidence: number;
+    request_id?: string;
+    elapsed_ms?: number;
+}
+export interface SearchParams {
+    query: string;
+    user_id: string;
+    domains?: string[];
+    top_k?: number;
+}
+export interface SearchResult {
+    results: SourceRecord[];
+    total: number;
+    request_id?: string;
+    elapsed_ms?: number;
+}

package/dist/src/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Public types for the XMem TypeScript SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "xmem-ai",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "xmem",
+    "memory",
+    "long-term-memory",
+    "llm",
+    "rag",
+    "ai-agent"
+  ],
+  "author": "Ishaan Gupta",
+  "license": "Apache-2.0",
+  "description": "TypeScript SDK for the XMem long-term memory API",
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.8.0"
+  }
+}