@pyxmate/memory 0.13.0 → 0.15.0

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

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

package/dist/chunk-W4LB326D.mjs

@@ -0,0 +1,618 @@
+// ../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}` : ""}`);
+  }
+  // --- File ingest ---
+  /**
+   * Native streaming file ingest. Yields typed {@link IngestEvent}s as the
+   * server (parsing/storing) and the SDK (enrichment/result) make progress.
+   *
+   * Wire contract: SDK POSTs with `Accept: application/x-ndjson`; the server
+   * MUST respond with NDJSON. There is no JSON fallback — older servers
+   * that emit `application/json` for this endpoint are not supported, and
+   * the SDK yields a terminal `error` event in that case.
+   *
+   * After the server's terminal `result`, the SDK runs its own enrichment
+   * phase (image-describe → entity-extract → `/enrich` POST), emitting
+   * progress + heartbeat events around each step, then yields the single
+   * terminal `result` event with the merged SDK + server result.
+   *
+   * Promise-shaped consumers should iterate the returned AsyncIterable and
+   * collect the terminal event; there is no separate `ingestFile()` Promise
+   * method by design (one wire format, one SDK method).
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: NDJSON dispatch + SDK enrichment fan-out is two cooperating paths; 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?.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")) {
+        yield this.ingestErrorEvent(
+          new MemoryServerError(
+            `Memory server returned ${contentType || "unknown content-type"} instead of application/x-ndjson \u2014 server is older than v0.15.0`,
+            res.status
+          ),
+          "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 / no-op are documented decision branches; the fan-out covers the v0.15.0 enrichment phase + 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;
+      }
+      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-K7JZXUBN.mjs";
+import "./chunk-W4LB326D.mjs";
 export {
   DashboardClient,
   Poller,