@acidkill/surreal-memory-client 2.6.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Surreal-Memory Contributors
+Copyright (c) 2026 Toni Nowak / AI-Flow NOWAK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @acidkill/surreal-memory-client
+
+TypeScript client for the [Surreal-Memory](https://github.com/acidkill/surreal-memory) REST API.
+
+```bash
+npm install @acidkill/surreal-memory-client
+```
+
+## Quick start
+
+```ts
+import { SurrealMemoryClient } from "@acidkill/surreal-memory-client"
+
+const client = new SurrealMemoryClient({
+  baseUrl: "http://localhost:8000",
+  brain: "myproject",
+})
+
+// Save a memory
+const { fiber_id } = await client.remember({
+  content: "Fixed auth bug with null check in login.py:42",
+  type: "fix",
+  priority: 7,
+  tags: ["auth"],
+})
+
+// Recall related memories
+const { results } = await client.recall({ query: "auth bug", limit: 5 })
+
+for (const { fiber, score } of results) {
+  console.log(score, fiber.content)
+}
+
+// Pull recent context
+const { fibers } = await client.context({ limit: 20 })
+```
+
+## API
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `remember(req)` | `POST /api/remember` | Save a memory. |
+| `recall(req)` | `POST /api/recall` | Recall by query (spreading activation + optional vector). |
+| `context(req?)` | `GET /api/context` | Recent fibers in the current brain. |
+| `getFiber(id)` | `GET /api/fibers/:id` | Fetch one fiber. |
+| `forget(id)` | `DELETE /api/fibers/:id` | Hard-delete a fiber. |
+| `listBrains()` | `GET /api/brains` | List all brains. |
+| `getBrainStats()` | `GET /api/stats` | Neuron / synapse / fiber counts. |
+| `health()` | `GET /api/health` | Health probe. |
+
+Every method accepts an optional `RequestOptions` argument (`brain` override, `timeoutMs`, `AbortSignal`, extra `headers`).
+
+## Configuration
+
+```ts
+new SurrealMemoryClient({
+  baseUrl: "https://memory.example.com",   // required, no trailing slash
+  brain: "default",                         // optional default brain
+  apiKey: process.env.SURREAL_MEMORY_API_KEY, // optional bearer token
+  timeoutMs: 30_000,                        // default 30s
+  fetch: customFetch,                       // optional fetch impl
+  headers: { "X-Tenant": "acme" },          // optional default headers
+})
+```
+
+## Error handling
+
+```ts
+import { ApiError, SurrealMemoryClient } from "@acidkill/surreal-memory-client"
+
+try {
+  await client.recall({ query: "..." })
+} catch (err: unknown) {
+  if (err instanceof ApiError) {
+    console.error(err.status, err.message, err.payload)
+  } else {
+    throw err
+  }
+}
+```
+
+## Server compatibility
+
+| Client | Server |
+|---|---|
+| `2.x` | Surreal-Memory `2.x` (REST API at `/api/*`) |
+
+## License
+
+MIT — see [LICENSE](https://github.com/acidkill/surreal-memory/blob/main/LICENSE).

package/dist/index.cjs

@@ -0,0 +1,171 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  SurrealMemoryClient: () => SurrealMemoryClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var ApiError = class extends Error {
+  status;
+  payload;
+  constructor(status, message, payload) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.payload = payload;
+  }
+};
+var SurrealMemoryClient = class {
+  baseUrl;
+  defaultBrain;
+  apiKey;
+  fetchImpl;
+  defaultTimeoutMs;
+  defaultHeaders;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error("SurrealMemoryClient: baseUrl is required");
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.defaultBrain = options.brain;
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.defaultTimeoutMs = options.timeoutMs ?? 3e4;
+    this.defaultHeaders = options.headers ?? {};
+  }
+  // ── Memory operations ─────────────────────────────────────
+  async remember(req, options) {
+    return this.request("POST", "/api/remember", req, options);
+  }
+  async recall(req, options) {
+    return this.request("POST", "/api/recall", req, options);
+  }
+  async context(req, options) {
+    const query = req ? this.buildQuery(req) : "";
+    return this.request("GET", `/api/context${query}`, void 0, options);
+  }
+  async getFiber(fiberId, options) {
+    return this.request("GET", `/api/fibers/${encodeURIComponent(fiberId)}`, void 0, options);
+  }
+  async forget(fiberId, options) {
+    return this.request("DELETE", `/api/fibers/${encodeURIComponent(fiberId)}`, void 0, options);
+  }
+  // ── Brain operations ──────────────────────────────────────
+  async listBrains(options) {
+    return this.request("GET", "/api/brains", void 0, options);
+  }
+  async getBrainStats(options) {
+    return this.request("GET", "/api/stats", void 0, options);
+  }
+  // ── Health / diagnostics ─────────────────────────────────
+  async health(options) {
+    return this.request("GET", "/api/health", void 0, options);
+  }
+  // ── Internal request plumbing ────────────────────────────
+  async request(method, path, body, options) {
+    const brain = options?.brain ?? this.defaultBrain;
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const headers = new Headers(this.defaultHeaders);
+    for (const [k, v] of Object.entries(options?.headers ?? {})) {
+      headers.set(k, v);
+    }
+    if (brain) {
+      headers.set("X-Brain-ID", brain);
+    }
+    if (this.apiKey) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`);
+    }
+    if (body !== void 0 && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    if (!headers.has("Accept")) {
+      headers.set("Accept", "application/json");
+    }
+    const controller = new AbortController();
+    const timeoutHandle = timeoutMs > 0 ? setTimeout(() => controller.abort(new Error("Request timeout")), timeoutMs) : void 0;
+    const externalSignal = options?.signal;
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort(externalSignal.reason);
+      } else {
+        externalSignal.addEventListener("abort", () => controller.abort(externalSignal.reason), {
+          once: true
+        });
+      }
+    }
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const payload = await this.safeReadErrorPayload(response);
+        const message = payload?.detail ?? payload?.error ?? `HTTP ${response.status}`;
+        throw new ApiError(response.status, message, payload);
+      }
+      if (response.status === 204) {
+        return void 0;
+      }
+      return await response.json();
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+  }
+  async safeReadErrorPayload(response) {
+    try {
+      const contentType = response.headers.get("Content-Type") ?? "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      }
+      const text = await response.text();
+      return { detail: text || void 0 };
+    } catch {
+      return void 0;
+    }
+  }
+  buildQuery(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          search.append(key, String(v));
+        }
+      } else {
+        search.set(key, String(value));
+      }
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  SurrealMemoryClient
+});

package/dist/index.d.cts

@@ -0,0 +1,177 @@
+/**
+ * Type definitions for the Surreal-Memory REST API.
+ *
+ * Mirrors the server response shapes from `src/surreal_memory/server/`.
+ * Only public-API fields are typed here; internal fields are passed through
+ * as `unknown` so the SDK does not break when the server adds new fields.
+ */
+type MemoryType = "fact" | "decision" | "error" | "insight" | "preference" | "workflow" | "instruction" | "concept" | "context" | "todo";
+type SynapseType = "CAUSED_BY" | "LEADS_TO" | "CONTRADICTS" | "SIMILAR_TO" | "PART_OF" | "USED_BY" | "DEPENDS_ON" | string;
+type NeuronType = "entity" | "concept" | "time" | "action" | "intent" | "state";
+type LifecycleStage = "full" | "summary" | "essence" | "ghost" | "metadata";
+interface Neuron {
+    id: string;
+    type: NeuronType;
+    content: string;
+    content_hash?: number;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+interface Synapse {
+    id: string;
+    type: SynapseType;
+    source_id: string;
+    target_id: string;
+    weight?: number;
+    created_at: string;
+}
+interface Fiber {
+    id: string;
+    content: string;
+    type?: MemoryType;
+    priority?: number;
+    tags?: string[];
+    stage?: LifecycleStage;
+    created_at: string;
+    updated_at?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Brain {
+    id: string;
+    name: string;
+    created_at: string;
+    stats?: BrainStats;
+}
+interface BrainStats {
+    neurons: number;
+    synapses: number;
+    fibers: number;
+    active_neurons?: number;
+}
+interface RememberRequest {
+    content: string;
+    type?: MemoryType;
+    priority?: number;
+    tags?: string[];
+    ephemeral?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RememberResponse {
+    fiber_id: string;
+    type: MemoryType;
+    saved: true;
+}
+interface RecallRequest {
+    query: string;
+    limit?: number;
+    type?: MemoryType;
+    tags?: string[];
+    min_priority?: number;
+}
+interface RecallResult {
+    fiber: Fiber;
+    score: number;
+    activation?: number;
+}
+interface RecallResponse {
+    results: RecallResult[];
+    query: string;
+    brain: string;
+}
+interface ContextRequest {
+    limit?: number;
+    since?: string;
+}
+interface ContextResponse {
+    fibers: Fiber[];
+    brain: string;
+    count: number;
+}
+interface HealthResponse {
+    status: "ok" | "degraded" | "down";
+    version: string;
+    storage: string;
+    brain?: string;
+}
+interface ApiErrorPayload {
+    detail?: string;
+    error?: string;
+    status?: number;
+}
+
+/**
+ * SurrealMemoryClient — typed REST client for a running Surreal-Memory server.
+ *
+ * @example
+ * ```ts
+ * import { SurrealMemoryClient } from "@acidkill/surreal-memory-client"
+ *
+ * const client = new SurrealMemoryClient({
+ *   baseUrl: "http://localhost:8000",
+ *   brain: "myproject",
+ * })
+ *
+ * const { fiber_id } = await client.remember({
+ *   content: "Fixed auth bug with null check in login.py:42",
+ *   type: "fix",
+ *   priority: 7,
+ *   tags: ["auth"],
+ * })
+ *
+ * const { results } = await client.recall({ query: "auth bug", limit: 5 })
+ * ```
+ */
+
+interface ClientOptions {
+    /** REST server URL, e.g. `http://localhost:8000`. No trailing slash. */
+    baseUrl: string;
+    /** Default brain name. Can be overridden per-request. Optional. */
+    brain?: string;
+    /** Optional bearer token sent as `Authorization: Bearer <token>`. */
+    apiKey?: string;
+    /** Custom `fetch` implementation (defaults to global `fetch`). */
+    fetch?: typeof fetch;
+    /** Default timeout in ms (defaults to 30000). */
+    timeoutMs?: number;
+    /** Extra headers attached to every request. */
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    /** Override the brain for this single call. */
+    brain?: string;
+    /** Override the timeout for this single call. */
+    timeoutMs?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+    /** Additional headers merged on top of client defaults. */
+    headers?: Record<string, string>;
+}
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly payload: ApiErrorPayload | undefined;
+    constructor(status: number, message: string, payload?: ApiErrorPayload);
+}
+declare class SurrealMemoryClient {
+    private readonly baseUrl;
+    private readonly defaultBrain;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly defaultTimeoutMs;
+    private readonly defaultHeaders;
+    constructor(options: ClientOptions);
+    remember(req: RememberRequest, options?: RequestOptions): Promise<RememberResponse>;
+    recall(req: RecallRequest, options?: RequestOptions): Promise<RecallResponse>;
+    context(req?: ContextRequest, options?: RequestOptions): Promise<ContextResponse>;
+    getFiber(fiberId: string, options?: RequestOptions): Promise<Fiber>;
+    forget(fiberId: string, options?: RequestOptions): Promise<{
+        deleted: true;
+    }>;
+    listBrains(options?: RequestOptions): Promise<Brain[]>;
+    getBrainStats(options?: RequestOptions): Promise<BrainStats>;
+    health(options?: RequestOptions): Promise<HealthResponse>;
+    private request;
+    private safeReadErrorPayload;
+    private buildQuery;
+}
+
+export { ApiError, type ApiErrorPayload, type Brain, type BrainStats, type ClientOptions, type ContextRequest, type ContextResponse, type Fiber, type HealthResponse, type LifecycleStage, type MemoryType, type Neuron, type NeuronType, type RecallRequest, type RecallResponse, type RecallResult, type RememberRequest, type RememberResponse, type RequestOptions, SurrealMemoryClient, type Synapse, type SynapseType };

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Type definitions for the Surreal-Memory REST API.
+ *
+ * Mirrors the server response shapes from `src/surreal_memory/server/`.
+ * Only public-API fields are typed here; internal fields are passed through
+ * as `unknown` so the SDK does not break when the server adds new fields.
+ */
+type MemoryType = "fact" | "decision" | "error" | "insight" | "preference" | "workflow" | "instruction" | "concept" | "context" | "todo";
+type SynapseType = "CAUSED_BY" | "LEADS_TO" | "CONTRADICTS" | "SIMILAR_TO" | "PART_OF" | "USED_BY" | "DEPENDS_ON" | string;
+type NeuronType = "entity" | "concept" | "time" | "action" | "intent" | "state";
+type LifecycleStage = "full" | "summary" | "essence" | "ghost" | "metadata";
+interface Neuron {
+    id: string;
+    type: NeuronType;
+    content: string;
+    content_hash?: number;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+interface Synapse {
+    id: string;
+    type: SynapseType;
+    source_id: string;
+    target_id: string;
+    weight?: number;
+    created_at: string;
+}
+interface Fiber {
+    id: string;
+    content: string;
+    type?: MemoryType;
+    priority?: number;
+    tags?: string[];
+    stage?: LifecycleStage;
+    created_at: string;
+    updated_at?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Brain {
+    id: string;
+    name: string;
+    created_at: string;
+    stats?: BrainStats;
+}
+interface BrainStats {
+    neurons: number;
+    synapses: number;
+    fibers: number;
+    active_neurons?: number;
+}
+interface RememberRequest {
+    content: string;
+    type?: MemoryType;
+    priority?: number;
+    tags?: string[];
+    ephemeral?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RememberResponse {
+    fiber_id: string;
+    type: MemoryType;
+    saved: true;
+}
+interface RecallRequest {
+    query: string;
+    limit?: number;
+    type?: MemoryType;
+    tags?: string[];
+    min_priority?: number;
+}
+interface RecallResult {
+    fiber: Fiber;
+    score: number;
+    activation?: number;
+}
+interface RecallResponse {
+    results: RecallResult[];
+    query: string;
+    brain: string;
+}
+interface ContextRequest {
+    limit?: number;
+    since?: string;
+}
+interface ContextResponse {
+    fibers: Fiber[];
+    brain: string;
+    count: number;
+}
+interface HealthResponse {
+    status: "ok" | "degraded" | "down";
+    version: string;
+    storage: string;
+    brain?: string;
+}
+interface ApiErrorPayload {
+    detail?: string;
+    error?: string;
+    status?: number;
+}
+
+/**
+ * SurrealMemoryClient — typed REST client for a running Surreal-Memory server.
+ *
+ * @example
+ * ```ts
+ * import { SurrealMemoryClient } from "@acidkill/surreal-memory-client"
+ *
+ * const client = new SurrealMemoryClient({
+ *   baseUrl: "http://localhost:8000",
+ *   brain: "myproject",
+ * })
+ *
+ * const { fiber_id } = await client.remember({
+ *   content: "Fixed auth bug with null check in login.py:42",
+ *   type: "fix",
+ *   priority: 7,
+ *   tags: ["auth"],
+ * })
+ *
+ * const { results } = await client.recall({ query: "auth bug", limit: 5 })
+ * ```
+ */
+
+interface ClientOptions {
+    /** REST server URL, e.g. `http://localhost:8000`. No trailing slash. */
+    baseUrl: string;
+    /** Default brain name. Can be overridden per-request. Optional. */
+    brain?: string;
+    /** Optional bearer token sent as `Authorization: Bearer <token>`. */
+    apiKey?: string;
+    /** Custom `fetch` implementation (defaults to global `fetch`). */
+    fetch?: typeof fetch;
+    /** Default timeout in ms (defaults to 30000). */
+    timeoutMs?: number;
+    /** Extra headers attached to every request. */
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    /** Override the brain for this single call. */
+    brain?: string;
+    /** Override the timeout for this single call. */
+    timeoutMs?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+    /** Additional headers merged on top of client defaults. */
+    headers?: Record<string, string>;
+}
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly payload: ApiErrorPayload | undefined;
+    constructor(status: number, message: string, payload?: ApiErrorPayload);
+}
+declare class SurrealMemoryClient {
+    private readonly baseUrl;
+    private readonly defaultBrain;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly defaultTimeoutMs;
+    private readonly defaultHeaders;
+    constructor(options: ClientOptions);
+    remember(req: RememberRequest, options?: RequestOptions): Promise<RememberResponse>;
+    recall(req: RecallRequest, options?: RequestOptions): Promise<RecallResponse>;
+    context(req?: ContextRequest, options?: RequestOptions): Promise<ContextResponse>;
+    getFiber(fiberId: string, options?: RequestOptions): Promise<Fiber>;
+    forget(fiberId: string, options?: RequestOptions): Promise<{
+        deleted: true;
+    }>;
+    listBrains(options?: RequestOptions): Promise<Brain[]>;
+    getBrainStats(options?: RequestOptions): Promise<BrainStats>;
+    health(options?: RequestOptions): Promise<HealthResponse>;
+    private request;
+    private safeReadErrorPayload;
+    private buildQuery;
+}
+
+export { ApiError, type ApiErrorPayload, type Brain, type BrainStats, type ClientOptions, type ContextRequest, type ContextResponse, type Fiber, type HealthResponse, type LifecycleStage, type MemoryType, type Neuron, type NeuronType, type RecallRequest, type RecallResponse, type RecallResult, type RememberRequest, type RememberResponse, type RequestOptions, SurrealMemoryClient, type Synapse, type SynapseType };

package/dist/index.js

@@ -0,0 +1,143 @@
+// src/client.ts
+var ApiError = class extends Error {
+  status;
+  payload;
+  constructor(status, message, payload) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.payload = payload;
+  }
+};
+var SurrealMemoryClient = class {
+  baseUrl;
+  defaultBrain;
+  apiKey;
+  fetchImpl;
+  defaultTimeoutMs;
+  defaultHeaders;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error("SurrealMemoryClient: baseUrl is required");
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.defaultBrain = options.brain;
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.defaultTimeoutMs = options.timeoutMs ?? 3e4;
+    this.defaultHeaders = options.headers ?? {};
+  }
+  // ── Memory operations ─────────────────────────────────────
+  async remember(req, options) {
+    return this.request("POST", "/api/remember", req, options);
+  }
+  async recall(req, options) {
+    return this.request("POST", "/api/recall", req, options);
+  }
+  async context(req, options) {
+    const query = req ? this.buildQuery(req) : "";
+    return this.request("GET", `/api/context${query}`, void 0, options);
+  }
+  async getFiber(fiberId, options) {
+    return this.request("GET", `/api/fibers/${encodeURIComponent(fiberId)}`, void 0, options);
+  }
+  async forget(fiberId, options) {
+    return this.request("DELETE", `/api/fibers/${encodeURIComponent(fiberId)}`, void 0, options);
+  }
+  // ── Brain operations ──────────────────────────────────────
+  async listBrains(options) {
+    return this.request("GET", "/api/brains", void 0, options);
+  }
+  async getBrainStats(options) {
+    return this.request("GET", "/api/stats", void 0, options);
+  }
+  // ── Health / diagnostics ─────────────────────────────────
+  async health(options) {
+    return this.request("GET", "/api/health", void 0, options);
+  }
+  // ── Internal request plumbing ────────────────────────────
+  async request(method, path, body, options) {
+    const brain = options?.brain ?? this.defaultBrain;
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const headers = new Headers(this.defaultHeaders);
+    for (const [k, v] of Object.entries(options?.headers ?? {})) {
+      headers.set(k, v);
+    }
+    if (brain) {
+      headers.set("X-Brain-ID", brain);
+    }
+    if (this.apiKey) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`);
+    }
+    if (body !== void 0 && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    if (!headers.has("Accept")) {
+      headers.set("Accept", "application/json");
+    }
+    const controller = new AbortController();
+    const timeoutHandle = timeoutMs > 0 ? setTimeout(() => controller.abort(new Error("Request timeout")), timeoutMs) : void 0;
+    const externalSignal = options?.signal;
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort(externalSignal.reason);
+      } else {
+        externalSignal.addEventListener("abort", () => controller.abort(externalSignal.reason), {
+          once: true
+        });
+      }
+    }
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const payload = await this.safeReadErrorPayload(response);
+        const message = payload?.detail ?? payload?.error ?? `HTTP ${response.status}`;
+        throw new ApiError(response.status, message, payload);
+      }
+      if (response.status === 204) {
+        return void 0;
+      }
+      return await response.json();
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+  }
+  async safeReadErrorPayload(response) {
+    try {
+      const contentType = response.headers.get("Content-Type") ?? "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      }
+      const text = await response.text();
+      return { detail: text || void 0 };
+    } catch {
+      return void 0;
+    }
+  }
+  buildQuery(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          search.append(key, String(v));
+        }
+      } else {
+        search.set(key, String(value));
+      }
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+  }
+};
+export {
+  ApiError,
+  SurrealMemoryClient
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@acidkill/surreal-memory-client",
+  "version": "2.6.0",
+  "description": "TypeScript client for the Surreal-Memory REST API — typed access to brains, neurons, synapses, fibers, recall, and sync.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "surreal-memory",
+    "surrealmemory",
+    "surrealdb",
+    "memory",
+    "ai-agent",
+    "client",
+    "sdk",
+    "rest"
+  ],
+  "author": "Toni Nowak / AI-Flow NOWAK",
+  "license": "MIT",
+  "homepage": "https://github.com/acidkill/surreal-memory#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acidkill/surreal-memory.git",
+    "directory": "integrations/surreal-memory-client"
+  },
+  "bugs": {
+    "url": "https://github.com/acidkill/surreal-memory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,234 @@
+/**
+ * SurrealMemoryClient — typed REST client for a running Surreal-Memory server.
+ *
+ * @example
+ * ```ts
+ * import { SurrealMemoryClient } from "@acidkill/surreal-memory-client"
+ *
+ * const client = new SurrealMemoryClient({
+ *   baseUrl: "http://localhost:8000",
+ *   brain: "myproject",
+ * })
+ *
+ * const { fiber_id } = await client.remember({
+ *   content: "Fixed auth bug with null check in login.py:42",
+ *   type: "fix",
+ *   priority: 7,
+ *   tags: ["auth"],
+ * })
+ *
+ * const { results } = await client.recall({ query: "auth bug", limit: 5 })
+ * ```
+ */
+
+import type {
+  ApiErrorPayload,
+  Brain,
+  BrainStats,
+  ContextRequest,
+  ContextResponse,
+  Fiber,
+  HealthResponse,
+  RecallRequest,
+  RecallResponse,
+  RememberRequest,
+  RememberResponse,
+} from "./types"
+
+export interface ClientOptions {
+  /** REST server URL, e.g. `http://localhost:8000`. No trailing slash. */
+  baseUrl: string
+  /** Default brain name. Can be overridden per-request. Optional. */
+  brain?: string
+  /** Optional bearer token sent as `Authorization: Bearer <token>`. */
+  apiKey?: string
+  /** Custom `fetch` implementation (defaults to global `fetch`). */
+  fetch?: typeof fetch
+  /** Default timeout in ms (defaults to 30000). */
+  timeoutMs?: number
+  /** Extra headers attached to every request. */
+  headers?: Record<string, string>
+}
+
+export interface RequestOptions {
+  /** Override the brain for this single call. */
+  brain?: string
+  /** Override the timeout for this single call. */
+  timeoutMs?: number
+  /** AbortSignal for cancellation. */
+  signal?: AbortSignal
+  /** Additional headers merged on top of client defaults. */
+  headers?: Record<string, string>
+}
+
+export class ApiError extends Error {
+  public readonly status: number
+  public readonly payload: ApiErrorPayload | undefined
+
+  constructor(status: number, message: string, payload?: ApiErrorPayload) {
+    super(message)
+    this.name = "ApiError"
+    this.status = status
+    this.payload = payload
+  }
+}
+
+export class SurrealMemoryClient {
+  private readonly baseUrl: string
+  private readonly defaultBrain: string | undefined
+  private readonly apiKey: string | undefined
+  private readonly fetchImpl: typeof fetch
+  private readonly defaultTimeoutMs: number
+  private readonly defaultHeaders: Record<string, string>
+
+  constructor(options: ClientOptions) {
+    if (!options.baseUrl) {
+      throw new Error("SurrealMemoryClient: baseUrl is required")
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "")
+    this.defaultBrain = options.brain
+    this.apiKey = options.apiKey
+    this.fetchImpl = options.fetch ?? globalThis.fetch
+    this.defaultTimeoutMs = options.timeoutMs ?? 30_000
+    this.defaultHeaders = options.headers ?? {}
+  }
+
+  // ── Memory operations ─────────────────────────────────────
+
+  async remember(req: RememberRequest, options?: RequestOptions): Promise<RememberResponse> {
+    return this.request<RememberResponse>("POST", "/api/remember", req, options)
+  }
+
+  async recall(req: RecallRequest, options?: RequestOptions): Promise<RecallResponse> {
+    return this.request<RecallResponse>("POST", "/api/recall", req, options)
+  }
+
+  async context(req?: ContextRequest, options?: RequestOptions): Promise<ContextResponse> {
+    const query = req ? this.buildQuery(req as Record<string, unknown>) : ""
+    return this.request<ContextResponse>("GET", `/api/context${query}`, undefined, options)
+  }
+
+  async getFiber(fiberId: string, options?: RequestOptions): Promise<Fiber> {
+    return this.request<Fiber>("GET", `/api/fibers/${encodeURIComponent(fiberId)}`, undefined, options)
+  }
+
+  async forget(fiberId: string, options?: RequestOptions): Promise<{ deleted: true }> {
+    return this.request("DELETE", `/api/fibers/${encodeURIComponent(fiberId)}`, undefined, options)
+  }
+
+  // ── Brain operations ──────────────────────────────────────
+
+  async listBrains(options?: RequestOptions): Promise<Brain[]> {
+    return this.request<Brain[]>("GET", "/api/brains", undefined, options)
+  }
+
+  async getBrainStats(options?: RequestOptions): Promise<BrainStats> {
+    return this.request<BrainStats>("GET", "/api/stats", undefined, options)
+  }
+
+  // ── Health / diagnostics ─────────────────────────────────
+
+  async health(options?: RequestOptions): Promise<HealthResponse> {
+    return this.request<HealthResponse>("GET", "/api/health", undefined, options)
+  }
+
+  // ── Internal request plumbing ────────────────────────────
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    options?: RequestOptions,
+  ): Promise<T> {
+    const brain = options?.brain ?? this.defaultBrain
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs
+
+    const headers = new Headers(this.defaultHeaders)
+    for (const [k, v] of Object.entries(options?.headers ?? {})) {
+      headers.set(k, v)
+    }
+    if (brain) {
+      headers.set("X-Brain-ID", brain)
+    }
+    if (this.apiKey) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`)
+    }
+    if (body !== undefined && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json")
+    }
+    if (!headers.has("Accept")) {
+      headers.set("Accept", "application/json")
+    }
+
+    const controller = new AbortController()
+    const timeoutHandle =
+      timeoutMs > 0
+        ? setTimeout(() => controller.abort(new Error("Request timeout")), timeoutMs)
+        : undefined
+
+    const externalSignal = options?.signal
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort(externalSignal.reason)
+      } else {
+        externalSignal.addEventListener("abort", () => controller.abort(externalSignal.reason), {
+          once: true,
+        })
+      }
+    }
+
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      })
+
+      if (!response.ok) {
+        const payload = await this.safeReadErrorPayload(response)
+        const message = payload?.detail ?? payload?.error ?? `HTTP ${response.status}`
+        throw new ApiError(response.status, message, payload)
+      }
+
+      if (response.status === 204) {
+        return undefined as T
+      }
+
+      return (await response.json()) as T
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle)
+      }
+    }
+  }
+
+  private async safeReadErrorPayload(response: Response): Promise<ApiErrorPayload | undefined> {
+    try {
+      const contentType = response.headers.get("Content-Type") ?? ""
+      if (contentType.includes("application/json")) {
+        return (await response.json()) as ApiErrorPayload
+      }
+      const text = await response.text()
+      return { detail: text || undefined }
+    } catch {
+      return undefined
+    }
+  }
+
+  private buildQuery(params: Record<string, unknown>): string {
+    const search = new URLSearchParams()
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null) continue
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          search.append(key, String(v))
+        }
+      } else {
+        search.set(key, String(value))
+      }
+    }
+    const qs = search.toString()
+    return qs ? `?${qs}` : ""
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @acidkill/surreal-memory-client
+ *
+ * Typed REST client for Surreal-Memory. See README.md for usage examples.
+ */
+
+export { SurrealMemoryClient, ApiError } from "./client"
+export type { ClientOptions, RequestOptions } from "./client"
+export type {
+  ApiErrorPayload,
+  Brain,
+  BrainStats,
+  ContextRequest,
+  ContextResponse,
+  Fiber,
+  HealthResponse,
+  LifecycleStage,
+  MemoryType,
+  Neuron,
+  NeuronType,
+  RecallRequest,
+  RecallResponse,
+  RecallResult,
+  RememberRequest,
+  RememberResponse,
+  Synapse,
+  SynapseType,
+} from "./types"

package/src/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Type definitions for the Surreal-Memory REST API.
+ *
+ * Mirrors the server response shapes from `src/surreal_memory/server/`.
+ * Only public-API fields are typed here; internal fields are passed through
+ * as `unknown` so the SDK does not break when the server adds new fields.
+ */
+
+export type MemoryType =
+  | "fact"
+  | "decision"
+  | "error"
+  | "insight"
+  | "preference"
+  | "workflow"
+  | "instruction"
+  | "concept"
+  | "context"
+  | "todo"
+
+export type SynapseType =
+  | "CAUSED_BY"
+  | "LEADS_TO"
+  | "CONTRADICTS"
+  | "SIMILAR_TO"
+  | "PART_OF"
+  | "USED_BY"
+  | "DEPENDS_ON"
+  | string
+
+export type NeuronType = "entity" | "concept" | "time" | "action" | "intent" | "state"
+
+export type LifecycleStage = "full" | "summary" | "essence" | "ghost" | "metadata"
+
+export interface Neuron {
+  id: string
+  type: NeuronType
+  content: string
+  content_hash?: number
+  created_at: string
+  metadata?: Record<string, unknown>
+}
+
+export interface Synapse {
+  id: string
+  type: SynapseType
+  source_id: string
+  target_id: string
+  weight?: number
+  created_at: string
+}
+
+export interface Fiber {
+  id: string
+  content: string
+  type?: MemoryType
+  priority?: number
+  tags?: string[]
+  stage?: LifecycleStage
+  created_at: string
+  updated_at?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface Brain {
+  id: string
+  name: string
+  created_at: string
+  stats?: BrainStats
+}
+
+export interface BrainStats {
+  neurons: number
+  synapses: number
+  fibers: number
+  active_neurons?: number
+}
+
+export interface RememberRequest {
+  content: string
+  type?: MemoryType
+  priority?: number
+  tags?: string[]
+  ephemeral?: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface RememberResponse {
+  fiber_id: string
+  type: MemoryType
+  saved: true
+}
+
+export interface RecallRequest {
+  query: string
+  limit?: number
+  type?: MemoryType
+  tags?: string[]
+  min_priority?: number
+}
+
+export interface RecallResult {
+  fiber: Fiber
+  score: number
+  activation?: number
+}
+
+export interface RecallResponse {
+  results: RecallResult[]
+  query: string
+  brain: string
+}
+
+export interface ContextRequest {
+  limit?: number
+  since?: string
+}
+
+export interface ContextResponse {
+  fibers: Fiber[]
+  brain: string
+  count: number
+}
+
+export interface HealthResponse {
+  status: "ok" | "degraded" | "down"
+  version: string
+  storage: string
+  brain?: string
+}
+
+export interface ApiErrorPayload {
+  detail?: string
+  error?: string
+  status?: number
+}