@pyxmate/memory 0.13.0 → 0.14.0

package/dist/{chunk-DZZHJ66P.mjs → chunk-JBKJDTFO.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-4YIKI2BA.mjs";
+} from "./chunk-QNRIO462.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {

package/dist/chunk-QNRIO462.mjs

@@ -0,0 +1,658 @@
+// ../client/src/memory-client.ts
+var MemoryServerError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "MemoryServerError";
+    this.status = status;
+  }
+  /** True when the server returned HTTP 404 (not found). */
+  get isNotFound() {
+    return this.status === 404;
+  }
+};
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var INGEST_EVENT_HEARTBEAT_MS = 2e4;
+var MemoryClient = class {
+  baseUrl;
+  _authHeaders;
+  _requestTimeoutMs;
+  constructor(memoryUrl, apiKeyOrOptions) {
+    this.baseUrl = memoryUrl.replace(/\/$/, "");
+    let apiKey;
+    let defaultHeaders = {};
+    let requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
+    if (typeof apiKeyOrOptions === "string") {
+      apiKey = apiKeyOrOptions;
+    } else if (apiKeyOrOptions) {
+      apiKey = apiKeyOrOptions.apiKey;
+      defaultHeaders = apiKeyOrOptions.defaultHeaders ?? {};
+      if (apiKeyOrOptions.requestTimeoutMs !== void 0) {
+        requestTimeoutMs = apiKeyOrOptions.requestTimeoutMs;
+      }
+    }
+    const trimmed = apiKey?.trim();
+    this._authHeaders = {
+      ...trimmed ? { Authorization: `Bearer ${trimmed}` } : {},
+      ...defaultHeaders
+    };
+    this._requestTimeoutMs = requestTimeoutMs;
+  }
+  /** Encode a path segment to prevent URL injection */
+  encodePathSegment(segment) {
+    return encodeURIComponent(segment);
+  }
+  async initialize() {
+    const response = await fetch(`${this.baseUrl}/health`, {
+      headers: this._authHeaders
+    });
+    if (!response.ok) {
+      throw new Error(`Memory server not reachable at ${this.baseUrl}: ${response.status}`);
+    }
+  }
+  async store(entry) {
+    return this.fetchApi("/api/memory/ingest", {
+      method: "POST",
+      body: JSON.stringify(entry)
+    });
+  }
+  async search(params) {
+    const searchParams = new URLSearchParams({ query: params.query });
+    if (params.limit) searchParams.set("limit", String(params.limit));
+    if (params.type) searchParams.set("type", params.type);
+    if (params.agentId) searchParams.set("agentId", params.agentId);
+    if (params.strategy) searchParams.set("strategy", params.strategy);
+    if (params.eventTimeRange) {
+      searchParams.set("eventTimeStart", params.eventTimeRange[0]);
+      searchParams.set("eventTimeEnd", params.eventTimeRange[1]);
+    }
+    if (params.asOf) searchParams.set("asOf", params.asOf);
+    if (params.abstentionThreshold != null)
+      searchParams.set("abstentionThreshold", String(params.abstentionThreshold));
+    return this.fetchApi(`/api/memory/search?${searchParams}`);
+  }
+  async get(id) {
+    try {
+      return await this.fetchApi(`/api/memory/entries/${this.encodePathSegment(id)}`);
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return null;
+      throw error;
+    }
+  }
+  async delete(id) {
+    try {
+      await this.fetchApi(`/api/memory/entries/${this.encodePathSegment(id)}`, {
+        method: "DELETE"
+      });
+      return true;
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return false;
+      throw error;
+    }
+  }
+  async clearSession(sessionId) {
+    const result = await this.fetchApi(
+      `/api/memory/sessions/${this.encodePathSegment(sessionId)}`,
+      { method: "DELETE" }
+    );
+    return result.cleared;
+  }
+  async stats() {
+    const stats = await this.fetchApi("/api/memory/stats");
+    return { ...stats, connected: true };
+  }
+  async shutdown() {
+  }
+  async list(params = {}) {
+    const searchParams = new URLSearchParams();
+    if (params.page != null) searchParams.set("page", String(params.page));
+    if (params.limit != null) searchParams.set("limit", String(params.limit));
+    if (params.type) searchParams.set("type", params.type);
+    if (params.agentId) searchParams.set("agentId", params.agentId);
+    const qs = searchParams.toString();
+    return this.fetchApi(`/api/memory/entries${qs ? `?${qs}` : ""}`);
+  }
+  // --- Additional endpoints ---
+  /**
+   * Ingest a file with optional two-phase enrichment.
+   *
+   * Without enrichment callbacks: standard single-phase ingest (backwards compatible).
+   * With enrichment callbacks: fetches extracted images, calls describeImage for each,
+   * optionally extracts entities, then submits enrichment data back to the server.
+   */
+  /**
+   * Ingest a file end-to-end: server upload + (optionally) SDK-side LLM
+   * enrichment + graph write. Returns the final {@link FileIngestResult}.
+   *
+   * This is the Promise-shaped convenience that consumes
+   * {@link MemoryClient.ingestFileEvents} internally — every consumer that
+   * doesn't need progress observability stays on this exact signature.
+   * Throws {@link MemoryServerError} on terminal error events.
+   */
+  async ingestFile(file, options) {
+    for await (const event of this.ingestFileEvents(file, options)) {
+      if (event.type === "result") return this.fileIngestResultFromEvent(event);
+      if (event.type === "error") {
+        throw new MemoryServerError(event.error, event.status ?? 500);
+      }
+    }
+    throw new MemoryServerError("File ingest stream ended without a terminal event", 0);
+  }
+  /**
+   * Native streaming ingest. Yields typed {@link IngestEvent}s as the server
+   * (parsing/storing) and the SDK (enrichment/result) make progress.
+   *
+   * Wire layout: SDK POSTs with `Accept: application/x-ndjson`; the server
+   * returns NDJSON `progress`/`heartbeat`/`result` events. After the server's
+   * terminal event, the SDK runs its own enrichment phase (image-describe,
+   * entity-extract, `/enrich` POST), emitting its own progress + heartbeat
+   * events around each step, then yields the single terminal `result` event.
+   *
+   * On older servers that don't honor `Accept: application/x-ndjson`, the
+   * SDK falls back to JSON parsing and synthesizes the SDK-side events as
+   * if it had streamed — same observable contract for callers either way.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: NDJSON dispatch + JSON fallback + SDK enrichment fan-out is genuinely 3 cooperating paths; each is documented inline and tested in memory-client-events.test.ts.
+  async *ingestFileEvents(file, options) {
+    const controller = new AbortController();
+    const relayAbort = () => controller.abort(options?.signal?.reason);
+    if (options?.signal?.aborted) relayAbort();
+    options?.signal?.addEventListener("abort", relayAbort, { once: true });
+    try {
+      const formData = new FormData();
+      formData.append("file", file);
+      if (options?.description) formData.append("description", options.description);
+      const wantsTextWindows = Boolean(
+        options?.enrichment?.extractEntities || options?.enrichment?.extractEntitiesV2
+      );
+      const headers = {
+        Accept: "application/x-ndjson",
+        ...this._authHeaders
+      };
+      if (wantsTextWindows) headers["X-Pyx-Enrichment-Capabilities"] = "text_windows_v1";
+      let res;
+      try {
+        res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
+          method: "POST",
+          body: formData,
+          headers,
+          signal: controller.signal
+        });
+      } catch (err) {
+        yield this.ingestErrorEvent(
+          this.translateFetchError(err, "/api/memory/ingest/file"),
+          "parsing"
+        );
+        return;
+      }
+      const contentType = res.headers.get("content-type") ?? "";
+      if (!contentType.includes("application/x-ndjson")) {
+        try {
+          const result = await this.parseApiResponse(res);
+          yield* this.completeIngestFileEvents(file, result, options, controller.signal);
+        } catch (err) {
+          yield this.ingestErrorEvent(err, "parsing");
+        }
+        return;
+      }
+      if (!res.body) {
+        yield this.ingestErrorEvent(
+          new MemoryServerError("Memory server returned an empty stream", res.status),
+          "parsing"
+        );
+        return;
+      }
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let currentStage = "parsing";
+      let serverResult = null;
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            const raw = JSON.parse(line);
+            const type = raw.type;
+            if (type === "progress" || type === "heartbeat") {
+              const stage = this.normalizeActiveIngestStage(raw.stage);
+              if (!stage) continue;
+              currentStage = stage;
+              yield { ...raw, schemaVersion: 1, type, stage };
+              continue;
+            }
+            if (type === "result") {
+              serverResult = this.fileIngestResultFromEvent({
+                ...raw,
+                schemaVersion: 1,
+                type: "result",
+                stage: "complete"
+              });
+              break;
+            }
+            if (type === "error") {
+              yield {
+                schemaVersion: 1,
+                type: "error",
+                stage: this.normalizeActiveIngestStage(raw.stage) ?? currentStage,
+                error: typeof raw.error === "string" ? raw.error : "File ingest failed",
+                message: typeof raw.message === "string" ? raw.message : void 0,
+                code: typeof raw.code === "string" || typeof raw.code === "number" ? raw.code : void 0,
+                status: typeof raw.status === "number" ? raw.status : void 0
+              };
+              return;
+            }
+          }
+          if (serverResult) break;
+        }
+      } catch (err) {
+        yield this.ingestErrorEvent(err, currentStage);
+        return;
+      } finally {
+        reader.releaseLock();
+      }
+      if (!serverResult) {
+        yield this.ingestErrorEvent(
+          new MemoryServerError("File ingest stream ended without a server result", 0),
+          currentStage
+        );
+        return;
+      }
+      yield* this.completeIngestFileEvents(file, serverResult, options, controller.signal);
+    } finally {
+      options?.signal?.removeEventListener("abort", relayAbort);
+      controller.abort();
+    }
+  }
+  /**
+   * Run the SDK-side enrichment phase (image-describe → entity-extract →
+   * `/enrich` POST) for a server result, emitting progress + heartbeat
+   * events around the slow steps and yielding the single terminal
+   * {@link IngestResultEvent} at the end. Skips work cleanly when the
+   * server emitted no enrichment block or the caller wired no callbacks.
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: image-describe / extract-entities-v2 / extract-entities-v1 / no-op are documented decision branches; this is the same fan-out the original ingestFile() had, plus heartbeat plumbing.
+  async *completeIngestFileEvents(file, result, options, signal) {
+    try {
+      if (!result.enrichment || !options?.enrichment) {
+        yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
+        return;
+      }
+      const enrichment = result.enrichment;
+      const { fileId, token, expiresAt, images } = enrichment;
+      const isV2 = "version" in enrichment;
+      const textWindows = isV2 ? enrichment.textWindows : [];
+      const descriptions = [];
+      const describeImage = options.enrichment.describeImage;
+      if (describeImage && images.length > 0) {
+        yield {
+          schemaVersion: 1,
+          type: "progress",
+          stage: "enrichment",
+          filename: file.name,
+          message: "Describing extracted images"
+        };
+        const CONCURRENCY = 5;
+        for (let i = 0; i < images.length; i += CONCURRENCY) {
+          const batch = images.slice(i, i + CONCURRENCY);
+          const batchResults = yield* this.withSdkHeartbeats(
+            "enrichment",
+            Promise.all(
+              batch.map(async (imageMeta) => {
+                const imageRes = await fetch(
+                  `${this.baseUrl}/api/memory/files/${fileId}/images/${imageMeta.imageId}?token=${encodeURIComponent(token)}`,
+                  { headers: this._authHeaders, signal }
+                );
+                if (!imageRes.ok) {
+                  throw new MemoryServerError(
+                    `Failed to fetch image ${imageMeta.imageId}: ${imageRes.status}`,
+                    imageRes.status
+                  );
+                }
+                const imageBuffer = await imageRes.arrayBuffer();
+                const description = await describeImage(imageBuffer, imageMeta);
+                return { imageId: imageMeta.imageId, description };
+              })
+            ),
+            signal
+          );
+          descriptions.push(...batchResults);
+        }
+      }
+      let entities;
+      let relationships;
+      const imageDescriptionTexts = descriptions.map((d) => d.description);
+      if (options.enrichment.extractEntitiesV2 && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
+        yield {
+          schemaVersion: 1,
+          type: "progress",
+          stage: "enrichment",
+          filename: file.name,
+          message: "Extracting entities"
+        };
+        const extracted = yield* this.withSdkHeartbeats(
+          "enrichment",
+          options.enrichment.extractEntitiesV2({
+            textWindows,
+            imageDescriptions: imageDescriptionTexts,
+            mimeType: file.type,
+            filename: file.name
+          }),
+          signal
+        );
+        entities = extracted.entities;
+        relationships = extracted.relationships;
+      } else if (options.enrichment.extractEntities) {
+        const allInputs = [...textWindows, ...imageDescriptionTexts];
+        if (allInputs.length > 0) {
+          yield {
+            schemaVersion: 1,
+            type: "progress",
+            stage: "enrichment",
+            filename: file.name,
+            message: "Extracting entities"
+          };
+          const extracted = yield* this.withSdkHeartbeats(
+            "enrichment",
+            options.enrichment.extractEntities(allInputs),
+            signal
+          );
+          entities = extracted.entities;
+          relationships = extracted.relationships;
+        }
+      }
+      const hasGraph = (entities?.length ?? 0) > 0;
+      const hasImages = descriptions.length > 0;
+      if (!hasGraph && !hasImages) {
+        yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
+        return;
+      }
+      yield {
+        schemaVersion: 1,
+        type: "progress",
+        stage: "enrichment",
+        filename: file.name,
+        message: "Persisting enrichment"
+      };
+      const enrichRes = yield* this.withSdkHeartbeats(
+        "enrichment",
+        fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Enrichment-Token": `${token}:${expiresAt}`,
+            ...this._authHeaders
+          },
+          signal,
+          body: JSON.stringify({ imageDescriptions: descriptions, entities, relationships })
+        }),
+        signal
+      );
+      if (!enrichRes.ok) {
+        const body = await enrichRes.json().catch(() => ({}));
+        throw new MemoryServerError(
+          body.error ?? `Enrichment failed: ${enrichRes.status}`,
+          enrichRes.status
+        );
+      }
+      const enrichData = await this.parseApiResponse(enrichRes);
+      result.entryIds.push(...enrichData.entryIds);
+      result.chunks += descriptions.length;
+      result.totalCharacters += descriptions.reduce((sum, d) => sum + d.description.length, 0);
+      yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
+    } catch (err) {
+      yield this.ingestErrorEvent(err, "enrichment");
+    }
+  }
+  /**
+   * Race a Promise against a periodic heartbeat tick. Yields a heartbeat
+   * IngestEvent every {@link INGEST_EVENT_HEARTBEAT_MS} until the promise
+   * settles, then returns the resolved value (or rethrows). Lets callers
+   * keep upstream sockets alive through long LLM/HTTP work without
+   * coupling the heartbeat cadence to the work itself.
+   */
+  async *withSdkHeartbeats(stage, work, signal) {
+    let settled = false;
+    let value;
+    let thrown;
+    const done = work.then(
+      (v) => {
+        settled = true;
+        value = v;
+      },
+      (err) => {
+        settled = true;
+        thrown = err;
+      }
+    );
+    while (!settled) {
+      let timer;
+      const tick = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("tick"), INGEST_EVENT_HEARTBEAT_MS);
+      });
+      let cleanupAbort = () => {
+      };
+      const abort = new Promise((resolve) => {
+        if (!signal) return;
+        if (signal.aborted) return resolve("abort");
+        const onAbort = () => resolve("abort");
+        signal.addEventListener("abort", onAbort, { once: true });
+        cleanupAbort = () => signal.removeEventListener("abort", onAbort);
+      });
+      const winner = await Promise.race([done.then(() => "done"), tick, abort]);
+      if (timer) clearTimeout(timer);
+      cleanupAbort();
+      if (winner === "abort") throw new DOMException("File ingest aborted", "AbortError");
+      if (winner === "tick" && !settled) {
+        yield {
+          schemaVersion: 1,
+          type: "heartbeat",
+          stage,
+          message: "SDK enrichment still running"
+        };
+      }
+    }
+    await done;
+    if (thrown) throw thrown;
+    return value;
+  }
+  normalizeActiveIngestStage(stage) {
+    if (stage === "parsing" || stage === "storing" || stage === "enrichment") return stage;
+    if (stage === "chunking") return "storing";
+    return null;
+  }
+  fileIngestResultFromEvent(event) {
+    const { schemaVersion: _v, type: _t, stage: _s, message: _m, ...result } = event;
+    return result;
+  }
+  ingestErrorEvent(error, stage) {
+    const status = error instanceof MemoryServerError ? error.status : error instanceof Error && error.name === "AbortError" ? 499 : void 0;
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      schemaVersion: 1,
+      type: "error",
+      stage,
+      error: message,
+      message,
+      ...status != null ? { status, code: status } : {}
+    };
+  }
+  /**
+   * Get the download URL for an uploaded file.
+   * Returns a URL that serves the original file binary with proper Content-Type.
+   */
+  getFileDownloadUrl(filename) {
+    return `${this.baseUrl}/api/memory/files/download/${encodeURIComponent(filename)}`;
+  }
+  /**
+   * Download an uploaded file by filename.
+   * Returns the raw Response (caller handles the body — arrayBuffer, blob, stream, etc.).
+   */
+  async downloadFile(filename) {
+    const url = this.getFileDownloadUrl(filename);
+    const res = await fetch(url, { headers: this._authHeaders });
+    if (!res.ok) {
+      throw new MemoryServerError(`File download failed: ${res.status}`, res.status);
+    }
+    return res;
+  }
+  /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
+  async listEntries(params) {
+    const result = await this.list(params);
+    return result.entries;
+  }
+  async graphNodes() {
+    const result = await this.fetchApi(
+      "/api/memory/graph/nodes"
+    );
+    return result.nodes;
+  }
+  async graphEdges() {
+    return this.fetchApi(
+      "/api/memory/graph/edges"
+    );
+  }
+  async graphQuery(query) {
+    return this.fetchApi("/api/memory/graph/query", {
+      method: "POST",
+      body: JSON.stringify(query)
+    });
+  }
+  // --- ExtendedMemoryInterface methods ---
+  async consolidate() {
+    return this.fetchApi("/api/memory/consolidate", {
+      method: "POST"
+    });
+  }
+  async forget(id, reason) {
+    try {
+      await this.fetchApi(`/api/memory/forget/${this.encodePathSegment(id)}`, {
+        method: "POST",
+        body: JSON.stringify({ reason })
+      });
+      return true;
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return false;
+      throw error;
+    }
+  }
+  async summarizeSession(sessionId) {
+    try {
+      return await this.fetchApi(
+        `/api/memory/sessions/${this.encodePathSegment(sessionId)}/summarize`,
+        { method: "POST" }
+      );
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return null;
+      throw error;
+    }
+  }
+  async runDecay() {
+    const result = await this.fetchApi("/api/memory/decay", {
+      method: "POST"
+    });
+    return result.archived;
+  }
+  async reindex() {
+    await this.fetchApi("/api/memory/reindex", { method: "POST" });
+  }
+  async clearGraph() {
+    const result = await this.fetchApi("/api/memory/graph/clear", {
+      method: "POST"
+    });
+    return result.deleted;
+  }
+  async deleteBySource(source) {
+    const result = await this.fetchApi(
+      `/api/memory/source/${this.encodePathSegment(source)}`,
+      { method: "DELETE" }
+    );
+    return result.deleted;
+  }
+  async queryAsOf(asOfDate, filters = {}) {
+    const params = new URLSearchParams({ asOf: asOfDate });
+    if (filters.type) params.set("type", filters.type);
+    if (filters.agentId) params.set("agentId", filters.agentId);
+    if (filters.source) params.set("source", filters.source);
+    if (filters.limit) params.set("limit", String(filters.limit));
+    const result = await this.fetchApi(
+      `/api/memory/query-as-of?${params}`
+    );
+    return result.entries;
+  }
+  async queryByEventTime(startTime, endTime, filters = {}) {
+    const params = new URLSearchParams({ startTime, endTime });
+    if (filters.type) params.set("type", filters.type);
+    if (filters.agentId) params.set("agentId", filters.agentId);
+    if (filters.source) params.set("source", filters.source);
+    if (filters.limit) params.set("limit", String(filters.limit));
+    const result = await this.fetchApi(
+      `/api/memory/query-by-event-time?${params}`
+    );
+    return result.entries;
+  }
+  async fetchApi(path, options) {
+    const signal = options?.signal ?? AbortSignal.timeout(this._requestTimeoutMs);
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          ...options?.headers,
+          ...this._authHeaders
+        },
+        signal
+      });
+    } catch (err) {
+      throw this.translateFetchError(err, path);
+    }
+    return this.parseApiResponse(res);
+  }
+  /**
+   * Map fetch-layer rejections into a typed `MemoryServerError` so callers
+   * can react uniformly. AbortSignal.timeout fires a `TimeoutError`; the
+   * caller's signal generally fires an `AbortError`. Anything else (DNS,
+   * TCP reset, TLS) becomes a wrapped error with status 0.
+   */
+  translateFetchError(err, path) {
+    if (err instanceof Error) {
+      if (err.name === "TimeoutError") {
+        return new MemoryServerError(
+          `Memory server request timed out after ${this._requestTimeoutMs}ms (${path})`,
+          504
+        );
+      }
+      if (err.name === "AbortError") {
+        return new MemoryServerError(`Memory server request aborted (${path})`, 499);
+      }
+      return new MemoryServerError(`Memory server request failed: ${err.message} (${path})`, 0);
+    }
+    return new MemoryServerError(`Memory server request failed: ${String(err)} (${path})`, 0);
+  }
+  /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
+  async parseApiResponse(res) {
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      throw new MemoryServerError(
+        `Memory server error: invalid JSON response (${res.status})`,
+        res.status
+      );
+    }
+    if (!body?.success || body.data == null) {
+      throw new MemoryServerError(body?.error ?? `Memory server error: ${res.status}`, res.status);
+    }
+    return body.data;
+  }
+};
+
+export {
+  MemoryServerError,
+  MemoryClient
+};

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-DZZHJ66P.mjs";
-import "./chunk-4YIKI2BA.mjs";
+} from "./chunk-JBKJDTFO.mjs";
+import "./chunk-QNRIO462.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, MemoryStats as MemoryStats$1, ExtractedImageMeta, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, FileIngestResult, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
+import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, MemoryStats as MemoryStats$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, FileIngestResult as FileIngestResult$1, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -88,7 +88,7 @@ interface EnrichmentCallbacks {
      * metadata. Required for image-bearing files; safe to omit for text-only
      * uploads where the server emits zero images.
      */
-    describeImage?: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta) => Promise<string>;
+    describeImage?: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta$1) => Promise<string>;
     /**
      * Legacy entity-extraction callback. Receives a flat string array which
      * the SDK constructs as `[...textWindows, ...imageDescriptions]` — callers
@@ -116,6 +116,16 @@ interface EnrichmentCallbacks {
         relationships: IngestRelationship$1[];
     }>;
 }
+/**
+ * Options for {@link MemoryClient.ingestFile} and
+ * {@link MemoryClient.ingestFileEvents}. `signal` lets long-running ingests
+ * (LLM enrichment + graph writes) be cancelled cleanly.
+ */
+interface IngestFileOptions {
+    description?: string;
+    enrichment?: EnrichmentCallbacks;
+    signal?: AbortSignal;
+}
 /** Error thrown by MemoryClient when the server returns a non-success response. */
 declare class MemoryServerError extends Error {
     readonly status: number;
@@ -167,10 +177,50 @@ declare class MemoryClient implements ExtendedMemoryInterface {
      * With enrichment callbacks: fetches extracted images, calls describeImage for each,
      * optionally extracts entities, then submits enrichment data back to the server.
      */
-    ingestFile(file: File, options?: {
-        description?: string;
-        enrichment?: EnrichmentCallbacks;
-    }): Promise<FileIngestResult>;
+    /**
+     * Ingest a file end-to-end: server upload + (optionally) SDK-side LLM
+     * enrichment + graph write. Returns the final {@link FileIngestResult}.
+     *
+     * This is the Promise-shaped convenience that consumes
+     * {@link MemoryClient.ingestFileEvents} internally — every consumer that
+     * doesn't need progress observability stays on this exact signature.
+     * Throws {@link MemoryServerError} on terminal error events.
+     */
+    ingestFile(file: File, options?: IngestFileOptions): Promise<FileIngestResult$1>;
+    /**
+     * Native streaming ingest. Yields typed {@link IngestEvent}s as the server
+     * (parsing/storing) and the SDK (enrichment/result) make progress.
+     *
+     * Wire layout: SDK POSTs with `Accept: application/x-ndjson`; the server
+     * returns NDJSON `progress`/`heartbeat`/`result` events. After the server's
+     * terminal event, the SDK runs its own enrichment phase (image-describe,
+     * entity-extract, `/enrich` POST), emitting its own progress + heartbeat
+     * events around each step, then yields the single terminal `result` event.
+     *
+     * On older servers that don't honor `Accept: application/x-ndjson`, the
+     * SDK falls back to JSON parsing and synthesizes the SDK-side events as
+     * if it had streamed — same observable contract for callers either way.
+     */
+    ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent$1>;
+    /**
+     * Run the SDK-side enrichment phase (image-describe → entity-extract →
+     * `/enrich` POST) for a server result, emitting progress + heartbeat
+     * events around the slow steps and yielding the single terminal
+     * {@link IngestResultEvent} at the end. Skips work cleanly when the
+     * server emitted no enrichment block or the caller wired no callbacks.
+     */
+    private completeIngestFileEvents;
+    /**
+     * Race a Promise against a periodic heartbeat tick. Yields a heartbeat
+     * IngestEvent every {@link INGEST_EVENT_HEARTBEAT_MS} until the promise
+     * settles, then returns the resolved value (or rethrows). Lets callers
+     * keep upstream sockets alive through long LLM/HTTP work without
+     * coupling the heartbeat cadence to the work itself.
+     */
+    private withSdkHeartbeats;
+    private normalizeActiveIngestStage;
+    private fileIngestResultFromEvent;
+    private ingestErrorEvent;
     /**
      * Get the download URL for an uploaded file.
      * Returns a URL that serves the original file binary with proper Content-Type.
@@ -492,4 +542,105 @@ interface GraphTraversalResult {
     }>;
 }
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type ExtendedMemoryInterface, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestRelationship, type IngestionResult, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, RAGStrategy, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, VectorProvider };
+/** Metadata for a single image extracted from a PDF. */
+interface ExtractedImageMeta {
+    imageId: string;
+    pageNumber: number;
+    width: number;
+    height: number;
+    mimeType: 'image/png' | 'image/jpeg';
+}
+/**
+ * Legacy Phase 1 enrichment block (v1). Returned by servers running the
+ * pre-Patch-#2 pipeline OR by Patch-#2+ servers when the client does NOT
+ * signal `text_windows_v1` capability via the
+ * `X-Pyx-Enrichment-Capabilities` request header.
+ */
+interface EnrichmentPendingV1 {
+    fileId: string;
+    token: string;
+    expiresAt: string;
+    images: ExtractedImageMeta[];
+}
+/** Truncation report for v2 text-window emission. Always present in v2. */
+interface EnrichmentTextWindowsTruncation {
+    /** Total characters seen by the parser, including content beyond the cap. */
+    originalChars: number;
+    /** Sum of emitted window lengths. <= originalChars. */
+    includedChars: number;
+    windowCount: number;
+    truncated: boolean;
+    reason: 'maxWindows' | 'maxTotalChars' | null;
+}
+/**
+ * v2 enrichment block. Returned by Patch-#2+ servers when the client signals
+ * `text_windows_v1` capability. Adds `textWindows` so SDK callers that bring
+ * their own LLM can extract entities from any text-bearing file (text PDFs,
+ * .txt, .md, .docx, .pptx, .xlsx, …) — closing the structural gap that left
+ * Knowledge Graph + Vector Map blank for text-only uploads.
+ */
+interface EnrichmentPendingV2 {
+    /** Discriminator. v1 omits this field. */
+    version: 2;
+    fileId: string;
+    token: string;
+    expiresAt: string;
+    images: ExtractedImageMeta[];
+    /** UTF-16 text windows for entity extraction. Empty when no text content. */
+    textWindows: string[];
+    textWindowsTruncation: EnrichmentTextWindowsTruncation;
+}
+/**
+ * Discriminated union over enrichment shapes. Narrow with `'version' in prep`
+ * before accessing v2-only fields.
+ */
+type EnrichmentPending = EnrichmentPendingV1 | EnrichmentPendingV2;
+/** Extended ingestion result when PDF contains images or v2 text windows. */
+interface FileIngestResult {
+    filename: string;
+    fileType: string;
+    chunks: number;
+    entryIds: string[];
+    totalCharacters: number;
+    /** Present when images were extracted (v1) OR text windows / images were emitted (v2). */
+    enrichment?: EnrichmentPending;
+}
+/** Coarse pipeline stages. Stable vocabulary — finer detail goes in counters/message. */
+type IngestStage = 'parsing' | 'storing' | 'enrichment' | 'complete';
+/** Mid-stream progress notification — never carries the terminal result. */
+interface IngestProgressEvent {
+    schemaVersion: 1;
+    type: 'progress';
+    stage: Exclude<IngestStage, 'complete'>;
+    filename?: string;
+    chunksStored?: number;
+    totalCharacters?: number;
+    message?: string;
+}
+/** Keepalive emitted while a stage is doing slow work (LLM, graph batch, etc). */
+interface IngestHeartbeatEvent {
+    schemaVersion: 1;
+    type: 'heartbeat';
+    stage: Exclude<IngestStage, 'complete'>;
+    message?: string;
+}
+/** Terminal success — exactly one per stream, carries the full FileIngestResult. */
+interface IngestResultEvent extends FileIngestResult {
+    schemaVersion: 1;
+    type: 'result';
+    stage: 'complete';
+    message?: string;
+}
+/** Terminal failure — exactly one per stream, mutually exclusive with result. */
+interface IngestErrorEvent {
+    schemaVersion: 1;
+    type: 'error';
+    stage: IngestStage;
+    error: string;
+    message?: string;
+    code?: string | number;
+    status?: number;
+}
+type IngestEvent = IngestProgressEvent | IngestHeartbeatEvent | IngestResultEvent | IngestErrorEvent;
+
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type ExtendedMemoryInterface, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, RAGStrategy, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, VectorProvider };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-4YIKI2BA.mjs";
+} from "./chunk-QNRIO462.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-DZZHJ66P.mjs";
-import "./chunk-4YIKI2BA.mjs";
+} from "./chunk-JBKJDTFO.mjs";
+import "./chunk-QNRIO462.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts
 import { useCallback as useCallback2, useMemo } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/dist/chunk-4YIKI2BA.mjs

@@ -1,404 +0,0 @@
-// ../client/src/memory-client.ts
-var MemoryServerError = class extends Error {
-  status;
-  constructor(message, status) {
-    super(message);
-    this.name = "MemoryServerError";
-    this.status = status;
-  }
-  /** True when the server returned HTTP 404 (not found). */
-  get isNotFound() {
-    return this.status === 404;
-  }
-};
-var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
-var MemoryClient = class {
-  baseUrl;
-  _authHeaders;
-  _requestTimeoutMs;
-  constructor(memoryUrl, apiKeyOrOptions) {
-    this.baseUrl = memoryUrl.replace(/\/$/, "");
-    let apiKey;
-    let defaultHeaders = {};
-    let requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
-    if (typeof apiKeyOrOptions === "string") {
-      apiKey = apiKeyOrOptions;
-    } else if (apiKeyOrOptions) {
-      apiKey = apiKeyOrOptions.apiKey;
-      defaultHeaders = apiKeyOrOptions.defaultHeaders ?? {};
-      if (apiKeyOrOptions.requestTimeoutMs !== void 0) {
-        requestTimeoutMs = apiKeyOrOptions.requestTimeoutMs;
-      }
-    }
-    const trimmed = apiKey?.trim();
-    this._authHeaders = {
-      ...trimmed ? { Authorization: `Bearer ${trimmed}` } : {},
-      ...defaultHeaders
-    };
-    this._requestTimeoutMs = requestTimeoutMs;
-  }
-  /** Encode a path segment to prevent URL injection */
-  encodePathSegment(segment) {
-    return encodeURIComponent(segment);
-  }
-  async initialize() {
-    const response = await fetch(`${this.baseUrl}/health`, {
-      headers: this._authHeaders
-    });
-    if (!response.ok) {
-      throw new Error(`Memory server not reachable at ${this.baseUrl}: ${response.status}`);
-    }
-  }
-  async store(entry) {
-    return this.fetchApi("/api/memory/ingest", {
-      method: "POST",
-      body: JSON.stringify(entry)
-    });
-  }
-  async search(params) {
-    const searchParams = new URLSearchParams({ query: params.query });
-    if (params.limit) searchParams.set("limit", String(params.limit));
-    if (params.type) searchParams.set("type", params.type);
-    if (params.agentId) searchParams.set("agentId", params.agentId);
-    if (params.strategy) searchParams.set("strategy", params.strategy);
-    if (params.eventTimeRange) {
-      searchParams.set("eventTimeStart", params.eventTimeRange[0]);
-      searchParams.set("eventTimeEnd", params.eventTimeRange[1]);
-    }
-    if (params.asOf) searchParams.set("asOf", params.asOf);
-    if (params.abstentionThreshold != null)
-      searchParams.set("abstentionThreshold", String(params.abstentionThreshold));
-    return this.fetchApi(`/api/memory/search?${searchParams}`);
-  }
-  async get(id) {
-    try {
-      return await this.fetchApi(`/api/memory/entries/${this.encodePathSegment(id)}`);
-    } catch (error) {
-      if (error instanceof MemoryServerError && error.isNotFound) return null;
-      throw error;
-    }
-  }
-  async delete(id) {
-    try {
-      await this.fetchApi(`/api/memory/entries/${this.encodePathSegment(id)}`, {
-        method: "DELETE"
-      });
-      return true;
-    } catch (error) {
-      if (error instanceof MemoryServerError && error.isNotFound) return false;
-      throw error;
-    }
-  }
-  async clearSession(sessionId) {
-    const result = await this.fetchApi(
-      `/api/memory/sessions/${this.encodePathSegment(sessionId)}`,
-      { method: "DELETE" }
-    );
-    return result.cleared;
-  }
-  async stats() {
-    const stats = await this.fetchApi("/api/memory/stats");
-    return { ...stats, connected: true };
-  }
-  async shutdown() {
-  }
-  async list(params = {}) {
-    const searchParams = new URLSearchParams();
-    if (params.page != null) searchParams.set("page", String(params.page));
-    if (params.limit != null) searchParams.set("limit", String(params.limit));
-    if (params.type) searchParams.set("type", params.type);
-    if (params.agentId) searchParams.set("agentId", params.agentId);
-    const qs = searchParams.toString();
-    return this.fetchApi(`/api/memory/entries${qs ? `?${qs}` : ""}`);
-  }
-  // --- Additional endpoints ---
-  /**
-   * Ingest a file with optional two-phase enrichment.
-   *
-   * Without enrichment callbacks: standard single-phase ingest (backwards compatible).
-   * With enrichment callbacks: fetches extracted images, calls describeImage for each,
-   * optionally extracts entities, then submits enrichment data back to the server.
-   */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: two-phase enrichment fans out across image-describe + entity-extract + v1/v2 negotiation; each branch maps to a documented case in memory-client-enrichment.test.ts
-  async ingestFile(file, options) {
-    const formData = new FormData();
-    formData.append("file", file);
-    if (options?.description) {
-      formData.append("description", options.description);
-    }
-    const wantsTextWindows = Boolean(
-      options?.enrichment?.extractEntities || options?.enrichment?.extractEntitiesV2
-    );
-    const headers = { ...this._authHeaders };
-    if (wantsTextWindows) {
-      headers["X-Pyx-Enrichment-Capabilities"] = "text_windows_v1";
-    }
-    const res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
-      method: "POST",
-      body: formData,
-      headers
-    });
-    const result = await this.parseApiResponse(res);
-    if (!result.enrichment || !options?.enrichment) {
-      return result;
-    }
-    const enrichment = result.enrichment;
-    const { fileId, token, expiresAt, images } = enrichment;
-    const isV2 = "version" in enrichment;
-    const textWindows = isV2 ? enrichment.textWindows : [];
-    const descriptions = [];
-    const describeImage = options.enrichment.describeImage;
-    if (describeImage && images.length > 0) {
-      const CONCURRENCY = 5;
-      for (let i = 0; i < images.length; i += CONCURRENCY) {
-        const batch = images.slice(i, i + CONCURRENCY);
-        const batchResults = await Promise.all(
-          batch.map(async (imageMeta) => {
-            const imageRes = await fetch(
-              `${this.baseUrl}/api/memory/files/${fileId}/images/${imageMeta.imageId}?token=${encodeURIComponent(token)}`,
-              { headers: this._authHeaders }
-            );
-            if (!imageRes.ok) {
-              throw new MemoryServerError(
-                `Failed to fetch image ${imageMeta.imageId}: ${imageRes.status}`,
-                imageRes.status
-              );
-            }
-            const imageBuffer = await imageRes.arrayBuffer();
-            const description = await describeImage(imageBuffer, imageMeta);
-            return { imageId: imageMeta.imageId, description };
-          })
-        );
-        descriptions.push(...batchResults);
-      }
-    }
-    let entities;
-    let relationships;
-    const v2Callback = options.enrichment.extractEntitiesV2;
-    const legacyCallback = options.enrichment.extractEntities;
-    const imageDescriptionTexts = descriptions.map((d) => d.description);
-    if (v2Callback && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
-      const extracted = await v2Callback({
-        textWindows,
-        imageDescriptions: imageDescriptionTexts,
-        mimeType: file.type,
-        filename: file.name
-      });
-      entities = extracted.entities;
-      relationships = extracted.relationships;
-    } else if (legacyCallback) {
-      const allInputs = [...textWindows, ...imageDescriptionTexts];
-      if (allInputs.length > 0) {
-        const extracted = await legacyCallback(allInputs);
-        entities = extracted.entities;
-        relationships = extracted.relationships;
-      }
-    }
-    const hasGraph = (entities?.length ?? 0) > 0;
-    const hasImages = descriptions.length > 0;
-    if (!hasGraph && !hasImages) {
-      return result;
-    }
-    const enrichTokenHeader = `${token}:${expiresAt}`;
-    const enrichRes = await fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-Enrichment-Token": enrichTokenHeader,
-        ...this._authHeaders
-      },
-      body: JSON.stringify({
-        imageDescriptions: descriptions,
-        entities,
-        relationships
-      })
-    });
-    if (!enrichRes.ok) {
-      const body = await enrichRes.json().catch(() => ({}));
-      throw new MemoryServerError(
-        body.error ?? `Enrichment failed: ${enrichRes.status}`,
-        enrichRes.status
-      );
-    }
-    const enrichData = await this.parseApiResponse(enrichRes);
-    const enrichCharacters = descriptions.reduce((sum, d) => sum + d.description.length, 0);
-    result.entryIds.push(...enrichData.entryIds);
-    result.chunks += descriptions.length;
-    result.totalCharacters += enrichCharacters;
-    return result;
-  }
-  /**
-   * Get the download URL for an uploaded file.
-   * Returns a URL that serves the original file binary with proper Content-Type.
-   */
-  getFileDownloadUrl(filename) {
-    return `${this.baseUrl}/api/memory/files/download/${encodeURIComponent(filename)}`;
-  }
-  /**
-   * Download an uploaded file by filename.
-   * Returns the raw Response (caller handles the body — arrayBuffer, blob, stream, etc.).
-   */
-  async downloadFile(filename) {
-    const url = this.getFileDownloadUrl(filename);
-    const res = await fetch(url, { headers: this._authHeaders });
-    if (!res.ok) {
-      throw new MemoryServerError(`File download failed: ${res.status}`, res.status);
-    }
-    return res;
-  }
-  /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
-  async listEntries(params) {
-    const result = await this.list(params);
-    return result.entries;
-  }
-  async graphNodes() {
-    const result = await this.fetchApi(
-      "/api/memory/graph/nodes"
-    );
-    return result.nodes;
-  }
-  async graphEdges() {
-    return this.fetchApi(
-      "/api/memory/graph/edges"
-    );
-  }
-  async graphQuery(query) {
-    return this.fetchApi("/api/memory/graph/query", {
-      method: "POST",
-      body: JSON.stringify(query)
-    });
-  }
-  // --- ExtendedMemoryInterface methods ---
-  async consolidate() {
-    return this.fetchApi("/api/memory/consolidate", {
-      method: "POST"
-    });
-  }
-  async forget(id, reason) {
-    try {
-      await this.fetchApi(`/api/memory/forget/${this.encodePathSegment(id)}`, {
-        method: "POST",
-        body: JSON.stringify({ reason })
-      });
-      return true;
-    } catch (error) {
-      if (error instanceof MemoryServerError && error.isNotFound) return false;
-      throw error;
-    }
-  }
-  async summarizeSession(sessionId) {
-    try {
-      return await this.fetchApi(
-        `/api/memory/sessions/${this.encodePathSegment(sessionId)}/summarize`,
-        { method: "POST" }
-      );
-    } catch (error) {
-      if (error instanceof MemoryServerError && error.isNotFound) return null;
-      throw error;
-    }
-  }
-  async runDecay() {
-    const result = await this.fetchApi("/api/memory/decay", {
-      method: "POST"
-    });
-    return result.archived;
-  }
-  async reindex() {
-    await this.fetchApi("/api/memory/reindex", { method: "POST" });
-  }
-  async clearGraph() {
-    const result = await this.fetchApi("/api/memory/graph/clear", {
-      method: "POST"
-    });
-    return result.deleted;
-  }
-  async deleteBySource(source) {
-    const result = await this.fetchApi(
-      `/api/memory/source/${this.encodePathSegment(source)}`,
-      { method: "DELETE" }
-    );
-    return result.deleted;
-  }
-  async queryAsOf(asOfDate, filters = {}) {
-    const params = new URLSearchParams({ asOf: asOfDate });
-    if (filters.type) params.set("type", filters.type);
-    if (filters.agentId) params.set("agentId", filters.agentId);
-    if (filters.source) params.set("source", filters.source);
-    if (filters.limit) params.set("limit", String(filters.limit));
-    const result = await this.fetchApi(
-      `/api/memory/query-as-of?${params}`
-    );
-    return result.entries;
-  }
-  async queryByEventTime(startTime, endTime, filters = {}) {
-    const params = new URLSearchParams({ startTime, endTime });
-    if (filters.type) params.set("type", filters.type);
-    if (filters.agentId) params.set("agentId", filters.agentId);
-    if (filters.source) params.set("source", filters.source);
-    if (filters.limit) params.set("limit", String(filters.limit));
-    const result = await this.fetchApi(
-      `/api/memory/query-by-event-time?${params}`
-    );
-    return result.entries;
-  }
-  async fetchApi(path, options) {
-    const signal = options?.signal ?? AbortSignal.timeout(this._requestTimeoutMs);
-    let res;
-    try {
-      res = await fetch(`${this.baseUrl}${path}`, {
-        ...options,
-        headers: {
-          "Content-Type": "application/json",
-          ...options?.headers,
-          ...this._authHeaders
-        },
-        signal
-      });
-    } catch (err) {
-      throw this.translateFetchError(err, path);
-    }
-    return this.parseApiResponse(res);
-  }
-  /**
-   * Map fetch-layer rejections into a typed `MemoryServerError` so callers
-   * can react uniformly. AbortSignal.timeout fires a `TimeoutError`; the
-   * caller's signal generally fires an `AbortError`. Anything else (DNS,
-   * TCP reset, TLS) becomes a wrapped error with status 0.
-   */
-  translateFetchError(err, path) {
-    if (err instanceof Error) {
-      if (err.name === "TimeoutError") {
-        return new MemoryServerError(
-          `Memory server request timed out after ${this._requestTimeoutMs}ms (${path})`,
-          504
-        );
-      }
-      if (err.name === "AbortError") {
-        return new MemoryServerError(`Memory server request aborted (${path})`, 499);
-      }
-      return new MemoryServerError(`Memory server request failed: ${err.message} (${path})`, 0);
-    }
-    return new MemoryServerError(`Memory server request failed: ${String(err)} (${path})`, 0);
-  }
-  /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
-  async parseApiResponse(res) {
-    let body;
-    try {
-      body = await res.json();
-    } catch {
-      throw new MemoryServerError(
-        `Memory server error: invalid JSON response (${res.status})`,
-        res.status
-      );
-    }
-    if (!body?.success || body.data == null) {
-      throw new MemoryServerError(body?.error ?? `Memory server error: ${res.status}`, res.status);
-    }
-    return body.data;
-  }
-};
-
-export {
-  MemoryServerError,
-  MemoryClient
-};