@voltmem/client 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# `@voltmem/client`
+
+Workers-safe TypeScript client for the [VoltMem HTTP sidecar](../../sidecar/README.md).
+Zero runtime dependencies — uses global `fetch`.
+
+## Install
+
+From this repo (path / file dependency):
+
+```bash
+# in your TS app
+npm install ../path/to/voltmem/clients/typescript
+# or after build:
+# "dependencies": { "@voltmem/client": "file:../voltmem/clients/typescript" }
+```
+
+```bash
+cd clients/typescript && npm install && npm run build
+```
+
+Not published to npm yet — use a local `file:` / workspace path.
+
+## Usage
+
+```ts
+import { VoltMemClient } from "@voltmem/client";
+
+const mem = new VoltMemClient({
+  baseUrl: env.VOLTMEM_URL,   // e.g. https://voltmem.example.com
+  apiKey: env.VOLTMEM_API_KEY,
+  userId: user.id,
+});
+
+await mem.add("I prefer darker colors and minimal fits");
+const hits = await mem.search("what colors does this user like?", { limit: 5 });
+const stats = await mem.domainStats(); // prior calibration telemetry
+```
+
+### Cloudflare Worker
+
+```ts
+import { VoltMemClient } from "@voltmem/client";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const mem = new VoltMemClient({
+      baseUrl: env.VOLTMEM_URL,
+      apiKey: env.VOLTMEM_API_KEY,
+      userId: "alice",
+    });
+    const hits = await mem.search("style preferences");
+    return Response.json(hits);
+  },
+};
+```
+
+Keep `VOLTMEM_API_KEY` in Worker secrets — never ship it to the browser.
+
+### Multi-tenant
+
+```ts
+const bob = mem.forUser("bob");
+await bob.add("I prefer neon colors");
+```
+
+## API
+
+| Method | Sidecar |
+|---|---|
+| `health()` | `GET /health` |
+| `add(data, opts?)` | `POST /v1/users/{userId}/memories` |
+| `search(q, opts?)` | `GET .../memories/search` |
+| `getAll()` | `GET .../memories` |
+| `get(id)` | `GET .../memories/{id}` |
+| `delete(id)` | `DELETE .../memories/{id}` |
+| `clear()` | `DELETE .../memories` |
+| `summary()` | `GET .../summary` |
+| `domainStats()` | `GET .../domain_stats` |
+
+Errors throw `VoltMemError` with `.status` and `.body`.
+
+## Develop
+
+```bash
+npm install
+npm test    # tsc + node:test against mocked fetch
+```

package/dist/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../src/client.test.ts"],"names":[],"mappings":""}

package/dist/client.test.js

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { mock, test } from "node:test";
+import { VoltMemClient, VoltMemError } from "./index.js";
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+test("add / search / domainStats hit expected paths and headers", async () => {
+    const calls = [];
+    const fetchMock = mock.fn(async (input, init) => {
+        const url = String(input);
+        calls.push({ url, init });
+        if (url.endsWith("/memories") && init?.method === "POST") {
+            return jsonResponse(200, {
+                id: "m1",
+                memory: "I prefer darker colors",
+                action: "inserted",
+                domain: "style_preference",
+                detail: "",
+            });
+        }
+        if (url.includes("/memories/search")) {
+            return jsonResponse(200, [
+                {
+                    id: "m1",
+                    memory: "I prefer darker colors",
+                    domain: "style_preference",
+                    source: "explicit_statement",
+                    created_at: 1,
+                    last_confirmed_at: 1,
+                    score: 0.9,
+                },
+            ]);
+        }
+        if (url.endsWith("/domain_stats")) {
+            return jsonResponse(200, {
+                style_preference: { prior: 0.08, inserted: 1, audit_rate: 0 },
+            });
+        }
+        return jsonResponse(404, { detail: "unexpected" });
+    });
+    const client = new VoltMemClient({
+        baseUrl: "https://voltmem.example.com/",
+        apiKey: "secret",
+        userId: "alice",
+        fetch: fetchMock,
+    });
+    const added = await client.add("I prefer darker colors");
+    assert.equal(added.id, "m1");
+    const hits = await client.search("style preferences", { limit: 3 });
+    assert.equal(hits[0]?.domain, "style_preference");
+    const stats = await client.domainStats();
+    assert.equal(stats.style_preference?.prior, 0.08);
+    assert.equal(calls.length, 3);
+    assert.match(calls[0].url, /\/v1\/users\/alice\/memories$/);
+    assert.equal(calls[0].init?.method, "POST");
+    assert.equal((calls[0].init?.headers)["X-API-Key"], "secret");
+    assert.match(calls[1].url, /q=style\+preferences/);
+    assert.match(calls[1].url, /limit=3/);
+    assert.match(calls[2].url, /\/domain_stats$/);
+});
+test("health skips API key", async () => {
+    const fetchMock = mock.fn(async (_input, init) => {
+        const headers = init?.headers;
+        assert.equal(headers["X-API-Key"], undefined);
+        return jsonResponse(200, { status: "ok" });
+    });
+    const client = new VoltMemClient({
+        baseUrl: "https://voltmem.example.com",
+        apiKey: "secret",
+        fetch: fetchMock,
+    });
+    const health = await client.health();
+    assert.deepEqual(health, { status: "ok" });
+});
+test("throws VoltMemError on non-2xx", async () => {
+    const client = new VoltMemClient({
+        baseUrl: "https://voltmem.example.com",
+        userId: "alice",
+        fetch: (async () => jsonResponse(401, { detail: "invalid or missing X-API-Key" })),
+    });
+    await assert.rejects(() => client.getAll(), (err) => {
+        assert.ok(err instanceof VoltMemError);
+        assert.equal(err.status, 401);
+        return true;
+    });
+});
+test("forUser overrides tenant", async () => {
+    let seen = "";
+    const client = new VoltMemClient({
+        baseUrl: "https://voltmem.example.com",
+        userId: "alice",
+        fetch: (async (input) => {
+            seen = String(input);
+            return jsonResponse(200, []);
+        }),
+    });
+    await client.forUser("bob").getAll();
+    assert.match(seen, /\/v1\/users\/bob\/memories$/);
+});
+test("requires userId", async () => {
+    const client = new VoltMemClient({
+        baseUrl: "https://voltmem.example.com",
+        fetch: (async () => jsonResponse(200, [])),
+    });
+    await assert.rejects(() => client.getAll(), /userId is required/);
+});
+//# sourceMappingURL=client.test.js.map

package/dist/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../src/client.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import type { AddData, AddOptions, DomainStats, MemoryHit, MemoryItem, SearchOptions, UserOptions, VoltMemClientOptions, WriteResult } from "./types.js";
+export type { AddData, AddOptions, DomainStat, DomainStats, MemoryHit, MemoryItem, Message, SearchOptions, UserOptions, VoltMemClientOptions, WriteResult, } from "./types.js";
+export declare class VoltMemError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * Thin fetch client for the VoltMem HTTP sidecar.
+ * Safe for Cloudflare Workers, Node 18+, Bun, and browsers (server-side preferred for API keys).
+ */
+export declare class VoltMemClient {
+    readonly baseUrl: string;
+    readonly apiKey: string | undefined;
+    readonly userId: string | undefined;
+    private readonly fetchImpl;
+    constructor(options: VoltMemClientOptions);
+    /** Bound client for another tenant (shares baseUrl / apiKey / fetch). */
+    forUser(userId: string): VoltMemClient;
+    health(): Promise<{
+        status: string;
+    }>;
+    add(data: AddData, options?: AddOptions): Promise<WriteResult | WriteResult[]>;
+    search(query: string, options?: SearchOptions): Promise<MemoryHit[]>;
+    getAll(options?: UserOptions): Promise<MemoryItem[]>;
+    get(memoryId: string, options?: UserOptions): Promise<MemoryItem>;
+    delete(memoryId: string, options?: UserOptions): Promise<{
+        deleted: boolean;
+    }>;
+    clear(options?: UserOptions): Promise<{
+        cleared: boolean;
+    }>;
+    summary(options?: UserOptions): Promise<Record<string, unknown>>;
+    domainStats(options?: UserOptions): Promise<DomainStats>;
+    private requireUserId;
+    private request;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,OAAO,EACP,UAAU,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,OAAO,EACP,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,oBAAoB;IAOzC,yEAAyE;IACzE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAUhC,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAIrC,GAAG,CACP,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC;IAYjC,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,SAAS,EAAE,CAAC;IAajB,MAAM,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAQxD,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC;IAQhB,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAQ1B,KAAK,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAQ/D,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAQpE,WAAW,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IAQlE,OAAO,CAAC,aAAa;YAUP,OAAO;CAuCtB"}

package/dist/index.js

@@ -0,0 +1,119 @@
+export class VoltMemError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "VoltMemError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Thin fetch client for the VoltMem HTTP sidecar.
+ * Safe for Cloudflare Workers, Node 18+, Bun, and browsers (server-side preferred for API keys).
+ */
+export class VoltMemClient {
+    baseUrl;
+    apiKey;
+    userId;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.userId = options.userId;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** Bound client for another tenant (shares baseUrl / apiKey / fetch). */
+    forUser(userId) {
+        const options = {
+            baseUrl: this.baseUrl,
+            userId,
+            fetch: this.fetchImpl,
+        };
+        if (this.apiKey !== undefined)
+            options.apiKey = this.apiKey;
+        return new VoltMemClient(options);
+    }
+    async health() {
+        return this.request("GET", "/health", { auth: false });
+    }
+    async add(data, options = {}) {
+        const userId = this.requireUserId(options.userId);
+        const body = { data };
+        if (options.source !== undefined)
+            body.source = options.source;
+        if (options.extract !== undefined)
+            body.extract = options.extract;
+        return this.request("POST", `/v1/users/${encodeURIComponent(userId)}/memories`, { body });
+    }
+    async search(query, options = {}) {
+        const userId = this.requireUserId(options.userId);
+        const params = new URLSearchParams({ q: query });
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.minScore !== undefined) {
+            params.set("min_score", String(options.minScore));
+        }
+        return this.request("GET", `/v1/users/${encodeURIComponent(userId)}/memories/search?${params}`);
+    }
+    async getAll(options = {}) {
+        const userId = this.requireUserId(options.userId);
+        return this.request("GET", `/v1/users/${encodeURIComponent(userId)}/memories`);
+    }
+    async get(memoryId, options = {}) {
+        const userId = this.requireUserId(options.userId);
+        return this.request("GET", `/v1/users/${encodeURIComponent(userId)}/memories/${encodeURIComponent(memoryId)}`);
+    }
+    async delete(memoryId, options = {}) {
+        const userId = this.requireUserId(options.userId);
+        return this.request("DELETE", `/v1/users/${encodeURIComponent(userId)}/memories/${encodeURIComponent(memoryId)}`);
+    }
+    async clear(options = {}) {
+        const userId = this.requireUserId(options.userId);
+        return this.request("DELETE", `/v1/users/${encodeURIComponent(userId)}/memories`);
+    }
+    async summary(options = {}) {
+        const userId = this.requireUserId(options.userId);
+        return this.request("GET", `/v1/users/${encodeURIComponent(userId)}/summary`);
+    }
+    async domainStats(options = {}) {
+        const userId = this.requireUserId(options.userId);
+        return this.request("GET", `/v1/users/${encodeURIComponent(userId)}/domain_stats`);
+    }
+    requireUserId(override) {
+        const userId = override ?? this.userId;
+        if (!userId) {
+            throw new Error("userId is required (pass VoltMemClientOptions.userId or per-call userId)");
+        }
+        return userId;
+    }
+    async request(method, path, opts = {}) {
+        const headers = {
+            Accept: "application/json",
+        };
+        if (opts.auth !== false && this.apiKey) {
+            headers["X-API-Key"] = this.apiKey;
+        }
+        const init = { method, headers };
+        if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(opts.body);
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+        const text = await res.text();
+        let parsed = undefined;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            throw new VoltMemError(`VoltMem ${method} ${path} failed (${res.status})`, res.status, parsed);
+        }
+        return parsed;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/** Types mirrored from the VoltMem Python sidecar JSON responses. */
+export type Message = {
+    role: string;
+    content: string;
+};
+/** String fact, one chat message, or a list of messages (extractable). */
+export type AddData = string | Message | Message[];
+export type WriteResult = {
+    id: string;
+    memory: string;
+    action: string;
+    domain: string;
+    detail: string;
+};
+export type MemoryItem = {
+    id: string;
+    memory: string;
+    domain: string;
+    source: string;
+    created_at: number;
+    last_confirmed_at: number;
+};
+export type MemoryHit = MemoryItem & {
+    score: number;
+};
+export type DomainStat = {
+    prior?: number;
+    inserted?: number;
+    confirmed?: number;
+    logged_mismatch?: number;
+    audited?: number;
+    audit_rate?: number;
+    mismatch_rate?: number;
+    [key: string]: number | undefined;
+};
+export type DomainStats = Record<string, DomainStat>;
+export type VoltMemClientOptions = {
+    /** Sidecar base URL, e.g. `https://voltmem.example.com` (no trailing slash required). */
+    baseUrl: string;
+    /** Sent as `X-API-Key` when the sidecar has `VOLTMEM_API_KEY` set. */
+    apiKey?: string;
+    /** Default tenant for convenience methods. */
+    userId?: string;
+    /** Override `globalThis.fetch` (tests / custom runtimes). */
+    fetch?: typeof fetch;
+};
+export type AddOptions = {
+    source?: string;
+    extract?: boolean;
+    userId?: string;
+};
+export type SearchOptions = {
+    limit?: number;
+    minScore?: number;
+    userId?: string;
+};
+export type UserOptions = {
+    userId?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAErD,MAAM,MAAM,oBAAoB,GAAG;IACjC,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Types mirrored from the VoltMem Python sidecar JSON responses. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qEAAqE"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@voltmem/client",
+  "version": "0.1.0",
+  "description": "Workers-safe TypeScript client for the VoltMem HTTP sidecar",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test dist/client.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "voltmem",
+    "memory",
+    "llm",
+    "cloudflare-workers",
+    "typescript"
+  ]
+}

package/src/client.test.ts

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import { mock, test } from "node:test";
+
+import { VoltMemClient, VoltMemError } from "./index.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+test("add / search / domainStats hit expected paths and headers", async () => {
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+  const fetchMock = mock.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, init });
+    if (url.endsWith("/memories") && init?.method === "POST") {
+      return jsonResponse(200, {
+        id: "m1",
+        memory: "I prefer darker colors",
+        action: "inserted",
+        domain: "style_preference",
+        detail: "",
+      });
+    }
+    if (url.includes("/memories/search")) {
+      return jsonResponse(200, [
+        {
+          id: "m1",
+          memory: "I prefer darker colors",
+          domain: "style_preference",
+          source: "explicit_statement",
+          created_at: 1,
+          last_confirmed_at: 1,
+          score: 0.9,
+        },
+      ]);
+    }
+    if (url.endsWith("/domain_stats")) {
+      return jsonResponse(200, {
+        style_preference: { prior: 0.08, inserted: 1, audit_rate: 0 },
+      });
+    }
+    return jsonResponse(404, { detail: "unexpected" });
+  });
+
+  const client = new VoltMemClient({
+    baseUrl: "https://voltmem.example.com/",
+    apiKey: "secret",
+    userId: "alice",
+    fetch: fetchMock as unknown as typeof fetch,
+  });
+
+  const added = await client.add("I prefer darker colors");
+  assert.equal((added as { id: string }).id, "m1");
+
+  const hits = await client.search("style preferences", { limit: 3 });
+  assert.equal(hits[0]?.domain, "style_preference");
+
+  const stats = await client.domainStats();
+  assert.equal(stats.style_preference?.prior, 0.08);
+
+  assert.equal(calls.length, 3);
+  assert.match(calls[0]!.url, /\/v1\/users\/alice\/memories$/);
+  assert.equal(calls[0]!.init?.method, "POST");
+  assert.equal(
+    (calls[0]!.init?.headers as Record<string, string>)["X-API-Key"],
+    "secret",
+  );
+  assert.match(calls[1]!.url, /q=style\+preferences/);
+  assert.match(calls[1]!.url, /limit=3/);
+  assert.match(calls[2]!.url, /\/domain_stats$/);
+});
+
+test("health skips API key", async () => {
+  const fetchMock = mock.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string>;
+    assert.equal(headers["X-API-Key"], undefined);
+    return jsonResponse(200, { status: "ok" });
+  });
+
+  const client = new VoltMemClient({
+    baseUrl: "https://voltmem.example.com",
+    apiKey: "secret",
+    fetch: fetchMock as unknown as typeof fetch,
+  });
+  const health = await client.health();
+  assert.deepEqual(health, { status: "ok" });
+});
+
+test("throws VoltMemError on non-2xx", async () => {
+  const client = new VoltMemClient({
+    baseUrl: "https://voltmem.example.com",
+    userId: "alice",
+    fetch: (async () =>
+      jsonResponse(401, { detail: "invalid or missing X-API-Key" })) as typeof fetch,
+  });
+
+  await assert.rejects(
+    () => client.getAll(),
+    (err: unknown) => {
+      assert.ok(err instanceof VoltMemError);
+      assert.equal((err as VoltMemError).status, 401);
+      return true;
+    },
+  );
+});
+
+test("forUser overrides tenant", async () => {
+  let seen = "";
+  const client = new VoltMemClient({
+    baseUrl: "https://voltmem.example.com",
+    userId: "alice",
+    fetch: (async (input) => {
+      seen = String(input);
+      return jsonResponse(200, []);
+    }) as typeof fetch,
+  });
+
+  await client.forUser("bob").getAll();
+  assert.match(seen, /\/v1\/users\/bob\/memories$/);
+});
+
+test("requires userId", async () => {
+  const client = new VoltMemClient({
+    baseUrl: "https://voltmem.example.com",
+    fetch: (async () => jsonResponse(200, [])) as typeof fetch,
+  });
+  await assert.rejects(() => client.getAll(), /userId is required/);
+});

package/src/index.ts

@@ -0,0 +1,205 @@
+import type {
+  AddData,
+  AddOptions,
+  DomainStats,
+  MemoryHit,
+  MemoryItem,
+  SearchOptions,
+  UserOptions,
+  VoltMemClientOptions,
+  WriteResult,
+} from "./types.js";
+
+export type {
+  AddData,
+  AddOptions,
+  DomainStat,
+  DomainStats,
+  MemoryHit,
+  MemoryItem,
+  Message,
+  SearchOptions,
+  UserOptions,
+  VoltMemClientOptions,
+  WriteResult,
+} from "./types.js";
+
+export class VoltMemError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(message: string, status: number, body: unknown) {
+    super(message);
+    this.name = "VoltMemError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * Thin fetch client for the VoltMem HTTP sidecar.
+ * Safe for Cloudflare Workers, Node 18+, Bun, and browsers (server-side preferred for API keys).
+ */
+export class VoltMemClient {
+  readonly baseUrl: string;
+  readonly apiKey: string | undefined;
+  readonly userId: string | undefined;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: VoltMemClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.userId = options.userId;
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  /** Bound client for another tenant (shares baseUrl / apiKey / fetch). */
+  forUser(userId: string): VoltMemClient {
+    const options: VoltMemClientOptions = {
+      baseUrl: this.baseUrl,
+      userId,
+      fetch: this.fetchImpl,
+    };
+    if (this.apiKey !== undefined) options.apiKey = this.apiKey;
+    return new VoltMemClient(options);
+  }
+
+  async health(): Promise<{ status: string }> {
+    return this.request<{ status: string }>("GET", "/health", { auth: false });
+  }
+
+  async add(
+    data: AddData,
+    options: AddOptions = {},
+  ): Promise<WriteResult | WriteResult[]> {
+    const userId = this.requireUserId(options.userId);
+    const body: Record<string, unknown> = { data };
+    if (options.source !== undefined) body.source = options.source;
+    if (options.extract !== undefined) body.extract = options.extract;
+    return this.request<WriteResult | WriteResult[]>(
+      "POST",
+      `/v1/users/${encodeURIComponent(userId)}/memories`,
+      { body },
+    );
+  }
+
+  async search(
+    query: string,
+    options: SearchOptions = {},
+  ): Promise<MemoryHit[]> {
+    const userId = this.requireUserId(options.userId);
+    const params = new URLSearchParams({ q: query });
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.minScore !== undefined) {
+      params.set("min_score", String(options.minScore));
+    }
+    return this.request<MemoryHit[]>(
+      "GET",
+      `/v1/users/${encodeURIComponent(userId)}/memories/search?${params}`,
+    );
+  }
+
+  async getAll(options: UserOptions = {}): Promise<MemoryItem[]> {
+    const userId = this.requireUserId(options.userId);
+    return this.request<MemoryItem[]>(
+      "GET",
+      `/v1/users/${encodeURIComponent(userId)}/memories`,
+    );
+  }
+
+  async get(
+    memoryId: string,
+    options: UserOptions = {},
+  ): Promise<MemoryItem> {
+    const userId = this.requireUserId(options.userId);
+    return this.request<MemoryItem>(
+      "GET",
+      `/v1/users/${encodeURIComponent(userId)}/memories/${encodeURIComponent(memoryId)}`,
+    );
+  }
+
+  async delete(
+    memoryId: string,
+    options: UserOptions = {},
+  ): Promise<{ deleted: boolean }> {
+    const userId = this.requireUserId(options.userId);
+    return this.request<{ deleted: boolean }>(
+      "DELETE",
+      `/v1/users/${encodeURIComponent(userId)}/memories/${encodeURIComponent(memoryId)}`,
+    );
+  }
+
+  async clear(options: UserOptions = {}): Promise<{ cleared: boolean }> {
+    const userId = this.requireUserId(options.userId);
+    return this.request<{ cleared: boolean }>(
+      "DELETE",
+      `/v1/users/${encodeURIComponent(userId)}/memories`,
+    );
+  }
+
+  async summary(options: UserOptions = {}): Promise<Record<string, unknown>> {
+    const userId = this.requireUserId(options.userId);
+    return this.request<Record<string, unknown>>(
+      "GET",
+      `/v1/users/${encodeURIComponent(userId)}/summary`,
+    );
+  }
+
+  async domainStats(options: UserOptions = {}): Promise<DomainStats> {
+    const userId = this.requireUserId(options.userId);
+    return this.request<DomainStats>(
+      "GET",
+      `/v1/users/${encodeURIComponent(userId)}/domain_stats`,
+    );
+  }
+
+  private requireUserId(override?: string): string {
+    const userId = override ?? this.userId;
+    if (!userId) {
+      throw new Error(
+        "userId is required (pass VoltMemClientOptions.userId or per-call userId)",
+      );
+    }
+    return userId;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    opts: { body?: unknown; auth?: boolean } = {},
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+    };
+    if (opts.auth !== false && this.apiKey) {
+      headers["X-API-Key"] = this.apiKey;
+    }
+
+    const init: RequestInit = { method, headers };
+    if (opts.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(opts.body);
+    }
+
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+
+    const text = await res.text();
+    let parsed: unknown = undefined;
+    if (text) {
+      try {
+        parsed = JSON.parse(text) as unknown;
+      } catch {
+        parsed = text;
+      }
+    }
+
+    if (!res.ok) {
+      throw new VoltMemError(
+        `VoltMem ${method} ${path} failed (${res.status})`,
+        res.status,
+        parsed,
+      );
+    }
+    return parsed as T;
+  }
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+/** Types mirrored from the VoltMem Python sidecar JSON responses. */
+
+export type Message = {
+  role: string;
+  content: string;
+};
+
+/** String fact, one chat message, or a list of messages (extractable). */
+export type AddData = string | Message | Message[];
+
+export type WriteResult = {
+  id: string;
+  memory: string;
+  action: string;
+  domain: string;
+  detail: string;
+};
+
+export type MemoryItem = {
+  id: string;
+  memory: string;
+  domain: string;
+  source: string;
+  created_at: number;
+  last_confirmed_at: number;
+};
+
+export type MemoryHit = MemoryItem & {
+  score: number;
+};
+
+export type DomainStat = {
+  prior?: number;
+  inserted?: number;
+  confirmed?: number;
+  logged_mismatch?: number;
+  audited?: number;
+  audit_rate?: number;
+  mismatch_rate?: number;
+  [key: string]: number | undefined;
+};
+
+export type DomainStats = Record<string, DomainStat>;
+
+export type VoltMemClientOptions = {
+  /** Sidecar base URL, e.g. `https://voltmem.example.com` (no trailing slash required). */
+  baseUrl: string;
+  /** Sent as `X-API-Key` when the sidecar has `VOLTMEM_API_KEY` set. */
+  apiKey?: string;
+  /** Default tenant for convenience methods. */
+  userId?: string;
+  /** Override `globalThis.fetch` (tests / custom runtimes). */
+  fetch?: typeof fetch;
+};
+
+export type AddOptions = {
+  source?: string;
+  extract?: boolean;
+  userId?: string;
+};
+
+export type SearchOptions = {
+  limit?: number;
+  minScore?: number;
+  userId?: string;
+};
+
+export type UserOptions = {
+  userId?: string;
+};