@pyxmate/memory 1.17.16 → 1.17.17

package/dist/{chunk-ZVI7DCB4.mjs → chunk-AMKPOPH6.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-MDFUZ3V2.mjs";
+} from "./chunk-JGFDID3B.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {
@@ -178,8 +178,10 @@ var DashboardClient = class extends MemoryClient {
    * arbitrary N-node sample were silently dropped, collapsing dense graphs to
    * a handful of rendered links.
    */
-  async graphSubgraph(edges = 2e3) {
-    return this.fetchApi(`/api/memory/graph/subgraph?edges=${edges}`);
+  async graphSubgraph(edges = 2e3, nodes = 2e3) {
+    return this.fetchApi(
+      `/api/memory/graph/subgraph?edges=${edges}&nodes=${nodes}`
+    );
   }
   async fetchHealthRaw() {
     return this.fetchApi("/health");

package/dist/{chunk-MDFUZ3V2.mjs → chunk-JGFDID3B.mjs}

@@ -1,7 +1,7 @@
 import {
   assertGraphExtractionPayload,
   mergeExtractedEntities
-} from "./chunk-34MTVIYK.mjs";
+} from "./chunk-3OLH3HYR.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {
@@ -11,6 +11,21 @@ var DEFAULTS = {
 };
 var TAXONOMY_MAX_CATEGORIES = 10;
 
+// ../shared/src/document-source.ts
+import { createHash } from "crypto";
+function documentSource(prefix, documentKey) {
+  return `${prefix}:${createHash("sha256").update(documentKey).digest("hex")}`;
+}
+function documentGraphSource(documentKey) {
+  return documentSource("document-graph", documentKey);
+}
+function documentContentSource(documentKey) {
+  return documentSource("document-content", documentKey);
+}
+function documentImageSource(documentKey) {
+  return documentSource("document-image", documentKey);
+}
+
 // ../shared/src/mcp/search-response.ts
 var STRIPPED_ENTRY_FIELDS = /* @__PURE__ */ new Set(["contentHash", "embedding", "tenantId", "userId", "teamId"]);
 function isRecord(value) {
@@ -228,12 +243,54 @@ var DisabledMemory = class {
 };
 
 // ../client/src/memory-client.ts
+function isRecord3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeRetryAfter(retryAfter, retryAfterSeconds) {
+  const exact = typeof retryAfter === "string" ? retryAfter.trim() : "";
+  if (exact) {
+    const parsed = /^\d+$/.test(exact) ? Number(exact) : Math.ceil((Date.parse(exact) - Date.now()) / 1e3);
+    return {
+      retryAfter: exact,
+      ...Number.isSafeInteger(parsed) && parsed >= 0 ? { retryAfterSeconds: parsed } : {}
+    };
+  }
+  return Number.isSafeInteger(retryAfterSeconds) && retryAfterSeconds >= 0 ? { retryAfterSeconds } : {};
+}
+function structuralHttpStatus(error) {
+  if (!isRecord3(error) || typeof error.status !== "number") return void 0;
+  return Number.isSafeInteger(error.status) && error.status >= 400 && error.status < 600 ? error.status : void 0;
+}
+function isFileIngestResult(value) {
+  if (!isRecord3(value)) return false;
+  if (typeof value.filename !== "string" || typeof value.fileType !== "string" || typeof value.chunks !== "number" || !Number.isSafeInteger(value.chunks) || value.chunks < 0 || !Array.isArray(value.entryIds) || !value.entryIds.every((id) => typeof id === "string") || typeof value.totalCharacters !== "number" || !Number.isSafeInteger(value.totalCharacters) || value.totalCharacters < 0) {
+    return false;
+  }
+  if (value.graphAnchorEntryId !== void 0 && typeof value.graphAnchorEntryId !== "string") {
+    return false;
+  }
+  if (value.enrichment !== void 0 && !isRecord3(value.enrichment)) return false;
+  return true;
+}
+function hasEnrichmentCallback(callbacks) {
+  return Boolean(callbacks?.describeImage || callbacks?.extractEntitiesV2);
+}
 var MemoryServerError = class extends Error {
   status;
-  constructor(message, status) {
+  /** Stable machine-readable discriminator returned by the memory server. */
+  code;
+  /** Exact HTTP Retry-After value returned by the memory server. */
+  retryAfter;
+  /** Retry delay normalized to seconds when Retry-After is parseable. */
+  retryAfterSeconds;
+  constructor(message, status, code, retryAfter) {
     super(message);
     this.name = "MemoryServerError";
     this.status = status;
+    this.code = code;
+    const retry = normalizeRetryAfter(retryAfter);
+    this.retryAfter = retry.retryAfter;
+    this.retryAfterSeconds = retry.retryAfterSeconds;
   }
   /** True when the server returned HTTP 404 (not found). */
   get isNotFound() {
@@ -273,12 +330,33 @@ var MemoryClient = class {
   }
   authorityHeaders(options) {
     if (!options) return {};
+    const headers = {};
     const key = options.idempotencyKey;
-    if (key === void 0) return {};
-    if (typeof key !== "string" || key.length === 0 || !key.isWellFormed() || new TextEncoder().encode(key).byteLength > 256) {
-      throw new Error("idempotencyKey must be 1-256 well-formed UTF-8 bytes");
+    if (key !== void 0) {
+      if (typeof key !== "string" || key.length === 0 || !key.isWellFormed() || new TextEncoder().encode(key).byteLength > 256) {
+        throw new Error("idempotencyKey must be 1-256 well-formed UTF-8 bytes");
+      }
+      headers["Idempotency-Key"] = key;
+    }
+    for (const [headerName, value] of [
+      ["X-Tenant-Id", options.tenantId],
+      ["X-Namespace-Id", options.namespaceId]
+    ]) {
+      if (value === void 0) continue;
+      const configured = Object.entries(this._authHeaders).find(
+        ([name]) => name.toLowerCase() === headerName.toLowerCase()
+      )?.[1];
+      if (configured !== void 0) {
+        if (configured !== value) {
+          throw new Error(
+            `${headerName} conflicts with the MemoryClient default scope; create a client for the requested scope`
+          );
+        }
+        continue;
+      }
+      headers[headerName] = value;
     }
-    return { "Idempotency-Key": key };
+    return headers;
   }
   async initialize() {
     const response = await fetch(`${this.baseUrl}/health`, {
@@ -426,6 +504,16 @@ var MemoryClient = class {
    * method by design (one wire format, one SDK method).
    */
   async *ingestFileEvents(file, options) {
+    if (options?.documentKey !== void 0) {
+      if (typeof options.documentKey !== "string" || options.documentKey.trim().length === 0) {
+        throw new Error("ingestFileEvents requires a non-empty documentKey when provided");
+      }
+      if (!options.enrichment?.extractEntitiesV2) {
+        throw new Error(
+          "ingestFileEvents with documentKey requires enrichment.extractEntitiesV2 so the stable graph replacement can be finalized"
+        );
+      }
+    }
     const controller = new AbortController();
     const relayAbort = () => controller.abort(options?.signal?.reason);
     if (options?.signal?.aborted) relayAbort();
@@ -435,6 +523,12 @@ var MemoryClient = class {
       formData.append("file", file);
       if (options?.description) formData.append("description", options.description);
       if (options?.namespaceId) formData.append("namespaceId", options.namespaceId);
+      if (options?.documentKey !== void 0) {
+        formData.append("documentKey", options.documentKey);
+      }
+      if (options?.catalogEntryId !== void 0) {
+        formData.append("catalogEntryId", options.catalogEntryId);
+      }
       const wantsTextWindows = Boolean(options?.enrichment?.extractEntitiesV2);
       const headers = {
         Accept: "application/x-ndjson",
@@ -490,6 +584,9 @@ var MemoryClient = class {
       const formData = new FormData();
       formData.append("file", file);
       formData.append("documentKey", options.documentKey);
+      if (options.catalogEntryId !== void 0) {
+        formData.append("catalogEntryId", options.catalogEntryId);
+      }
       if (options.namespaceId) formData.append("namespaceId", options.namespaceId);
       const headers = {
         Accept: "application/x-ndjson",
@@ -519,7 +616,7 @@ var MemoryClient = class {
           "graph-only"
         );
         const data = outcome.data;
-        if (data?.purpose !== "graph-only" || !Array.isArray(data.entryIds)) {
+        if (data?.purpose !== "graph-only" || !Array.isArray(data.entryIds) || data.entryIds.length !== 1 || typeof data.entryIds[0] !== "string" || data.entryIds[0].length === 0 || typeof data.graphAnchorEntryId !== "string" || data.graphAnchorEntryId.length === 0) {
           throw new MemoryServerError(
             "Graph enrichment finalization returned an unexpected result",
             0
@@ -557,6 +654,17 @@ var MemoryClient = class {
       return null;
     }
     const contentType = res.headers.get("content-type") ?? "";
+    if (!res.ok) {
+      let error;
+      try {
+        await this.parseApiResponse(res);
+        error = new MemoryServerError(`Memory server error: ${res.status}`, res.status);
+      } catch (cause) {
+        error = cause;
+      }
+      yield this.ingestErrorEvent(error, "parsing");
+      return null;
+    }
     if (!contentType.includes("application/x-ndjson")) {
       yield this.ingestErrorEvent(
         new MemoryServerError(
@@ -602,6 +710,8 @@ var MemoryClient = class {
             break;
           }
           if (type === "error") {
+            const partialResult = isFileIngestResult(raw.partialResult) ? raw.partialResult : void 0;
+            const retry = normalizeRetryAfter(raw.retryAfter, raw.retryAfterSeconds);
             yield {
               schemaVersion: 1,
               type: "error",
@@ -609,7 +719,9 @@ var MemoryClient = class {
               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
+              status: typeof raw.status === "number" ? raw.status : void 0,
+              ...retry,
+              ...partialResult ? { partialResult } : {}
             };
             return null;
           }
@@ -640,26 +752,48 @@ var MemoryClient = class {
    */
   async *completeIngestFileEvents(file, result, options, signal) {
     try {
-      if (!result.enrichment || !options?.enrichment) {
+      const callbacks = options?.enrichment;
+      if (options?.documentKey !== void 0 && !result.enrichment) {
+        throw new MemoryServerError(
+          "documentKey-aware ingest response omitted required enrichment preparation; stable graph finalization did not run",
+          502
+        );
+      }
+      if (!result.enrichment || !hasEnrichmentCallback(callbacks)) {
         yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
         return;
       }
       const outcome = yield* this.runEnrichmentCallbacks(
         file,
         result.enrichment,
-        options.enrichment,
+        callbacks,
         signal,
-        "ingest"
+        "ingest",
+        options?.documentKey !== void 0
       );
       if (outcome.posted) {
         const enrichData = outcome.data;
+        if (options?.documentKey !== void 0 && !enrichData.graphAnchorEntryId) {
+          throw new MemoryServerError(
+            "documentKey-aware enrichment response omitted graphAnchorEntryId; server does not support stable document replacement",
+            502
+          );
+        }
         result.entryIds.push(...enrichData.entryIds);
+        if (enrichData.graphAnchorEntryId) {
+          result.graphAnchorEntryId = enrichData.graphAnchorEntryId;
+        }
+        if ((enrichData.relationshipsDropped ?? 0) > 0) {
+          result.relationshipsDropped = enrichData.relationshipsDropped;
+          result.droppedRelationships = enrichData.droppedRelationships;
+        }
         result.chunks += outcome.descriptions.length;
         result.totalCharacters += outcome.descriptions.reduce(
           (sum, d) => sum + d.description.length,
           0
         );
       }
+      delete result.enrichment;
       yield { schemaVersion: 1, type: "result", stage: "complete", ...result };
     } catch (err) {
       yield this.ingestErrorEvent(err, "enrichment", result);
@@ -673,16 +807,24 @@ var MemoryClient = class {
    * heartbeat events around each slow step. Throws on any failure; the
    * purpose-specific wrappers translate that into their terminal error.
    *
-   * The purpose controls empty-output semantics: ingest skips an optional
-   * empty add-on; graph-only finalizes an extractor that ran and found zero
-   * entities, but refuses to erase prior graph state when no extractable input
-   * reached the callback at all.
+   * Legacy ingest keeps its existing partial add-on behavior. Graph-only and
+   * documentKey-aware full ingest may replace a prior graph only from a
+   * complete input set (no truncated text windows or undescribed images). A
+   * complete extractor result containing zero entities remains a valid clear.
    */
   // 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 *runEnrichmentCallbacks(file, enrichment, callbacks, signal, purpose) {
+  async *runEnrichmentCallbacks(file, enrichment, callbacks, signal, purpose, replaceEmptyGraph = false) {
     const { fileId, token, expiresAt, images } = enrichment;
     const isV2 = "version" in enrichment;
     const textWindows = isV2 ? enrichment.textWindows : [];
+    const textWindowsTruncation = isV2 ? enrichment.textWindowsTruncation : void 0;
+    const requiresCompleteGraphReplacement = purpose === "graph-only" || replaceEmptyGraph;
+    if (requiresCompleteGraphReplacement && textWindowsTruncation?.truncated) {
+      throw new MemoryServerError(
+        `Graph enrichment input was truncated (${textWindowsTruncation.reason ?? "unknown limit"}); prior graph state was preserved and the pending session remains retryable`,
+        422
+      );
+    }
     const descriptions = [];
     const describeImage = callbacks.describeImage;
     if (describeImage && images.length > 0) {
@@ -731,6 +873,12 @@ var MemoryClient = class {
         };
       }
     }
+    if (requiresCompleteGraphReplacement && descriptions.length < images.length) {
+      throw new MemoryServerError(
+        `Graph enrichment described only ${descriptions.length}/${images.length} images; prior graph state was preserved and the pending session remains retryable`,
+        422
+      );
+    }
     let entities;
     let relationships;
     const imageDescriptionTexts = descriptions.map((d) => d.description);
@@ -773,7 +921,7 @@ var MemoryClient = class {
     }
     const hasGraph = (entities?.length ?? 0) > 0;
     const hasImages = descriptions.length > 0;
-    if (!hasGraph && !hasImages && purpose === "ingest") {
+    if (!hasGraph && !hasImages && purpose === "ingest" && !replaceEmptyGraph) {
       return { posted: false, data: null, descriptions };
     }
     yield {
@@ -793,17 +941,14 @@ var MemoryClient = class {
           ...this._authHeaders
         },
         signal,
-        body: JSON.stringify({ imageDescriptions: descriptions, entities, relationships })
+        body: JSON.stringify({
+          imageDescriptions: descriptions,
+          entities: entities ?? [],
+          relationships: relationships ?? []
+        })
       }),
       signal
     );
-    if (!enrichRes.ok) {
-      const body = await enrichRes.json().catch(() => ({}));
-      throw new MemoryServerError(
-        body.error ?? `Enrichment failed: ${enrichRes.status}`,
-        enrichRes.status
-      );
-    }
     const data = await this.parseApiResponse(enrichRes);
     return { posted: true, data, descriptions };
   }
@@ -869,15 +1014,20 @@ var MemoryClient = class {
     return result;
   }
   ingestErrorEvent(error, stage, partialResult) {
-    const status = error instanceof MemoryServerError ? error.status : error instanceof Error && error.name === "AbortError" ? 499 : void 0;
+    const structuralError = isRecord3(error) ? error : void 0;
+    const status = error instanceof MemoryServerError ? error.status : error instanceof Error && error.name === "AbortError" ? 499 : structuralHttpStatus(error);
     const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof MemoryServerError ? error.code : void 0;
+    const retry = error instanceof MemoryServerError ? { retryAfter: error.retryAfter, retryAfterSeconds: error.retryAfterSeconds } : normalizeRetryAfter(structuralError?.retryAfter, structuralError?.retryAfterSeconds);
     return {
       schemaVersion: 1,
       type: "error",
       stage,
       error: message,
       message,
-      ...status != null ? { status, code: status } : {},
+      ...status != null ? { status, code: code ?? status } : {},
+      ...retry.retryAfter !== void 0 ? { retryAfter: retry.retryAfter } : {},
+      ...retry.retryAfterSeconds !== void 0 ? { retryAfterSeconds: retry.retryAfterSeconds } : {},
       ...partialResult ? { partialResult } : {}
     };
   }
@@ -885,15 +1035,24 @@ var MemoryClient = class {
    * 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)}`;
+  getFileDownloadUrl(filename, options) {
+    const url = new URL(
+      `${this.baseUrl}/api/memory/files/download/${encodeURIComponent(filename)}`
+    );
+    if (options?.documentKey !== void 0) {
+      url.searchParams.set("documentKey", options.documentKey);
+    }
+    if (options?.namespaceId !== void 0) {
+      url.searchParams.set("namespaceId", options.namespaceId);
+    }
+    return url.toString();
   }
   /**
    * 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);
+  async downloadFile(filename, options) {
+    const url = this.getFileDownloadUrl(filename, options);
     const res = await fetch(url, { headers: this._authHeaders });
     if (!res.ok) {
       throw new MemoryServerError(`File download failed: ${res.status}`, res.status);
@@ -971,10 +1130,10 @@ var MemoryClient = class {
   async repairGraph() {
     return this.fetchApi("/api/memory/graph/repair", { method: "POST" });
   }
-  async deleteBySource(source) {
+  async deleteBySource(source, authority) {
     const result = await this.fetchApi(
       `/api/memory/source/${this.encodePathSegment(source)}`,
-      { method: "DELETE" }
+      { method: "DELETE", headers: this.authorityHeaders(authority) }
     );
     return result.deleted;
   }
@@ -987,14 +1146,20 @@ var MemoryClient = class {
       }
     );
   }
-  async queryAsOf(asOfDate, filters = {}) {
+  async queryAsOf(asOfDate, filters = {}, authority) {
+    if (filters.cursor !== void 0 && filters.offset !== void 0) {
+      throw new Error("queryAsOf cursor and offset are mutually exclusive");
+    }
     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));
+    if (filters.offset !== void 0) params.set("offset", String(filters.offset));
+    if (filters.cursor !== void 0) params.set("cursor", filters.cursor);
     const result = await this.fetchApi(
-      `/api/memory/query-as-of?${params}`
+      `/api/memory/query-as-of?${params}`,
+      { headers: this.authorityHeaders(authority) }
     );
     return result.entries;
   }
@@ -1036,11 +1201,15 @@ var MemoryClient = class {
     return result.entries;
   }
   async queryByEventTime(startTime, endTime, filters = {}) {
+    if (filters.cursor !== void 0) {
+      throw new Error("queryByEventTime does not support a createdAt cursor; use offset");
+    }
     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));
+    if (filters.offset !== void 0) params.set("offset", String(filters.offset));
     const result = await this.fetchApi(
       `/api/memory/query-by-event-time?${params}`
     );
@@ -1164,23 +1333,33 @@ var MemoryClient = class {
   }
   /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
   async parseApiResponse(res) {
+    const retryAfter = res.headers.get("Retry-After") ?? void 0;
     let body;
     try {
       body = await res.json();
     } catch {
       throw new MemoryServerError(
         `Memory server error: invalid JSON response (${res.status})`,
-        res.status
+        res.status,
+        void 0,
+        retryAfter
       );
     }
-    if (!body?.success || body.data == null) {
+    if (!res.ok || !body?.success || body.data == null) {
       if (res.ok && body?.error === void 0) {
         throw new MemoryServerError(
           `Memory server returned HTTP ${res.status} without the expected { success, data } API envelope. Check that the base URL points to a pyx-memory instance server; hosted pyx-memory access uses MCP.`,
-          res.status
+          res.status,
+          void 0,
+          retryAfter
         );
       }
-      throw new MemoryServerError(body?.error ?? `Memory server error: ${res.status}`, res.status);
+      throw new MemoryServerError(
+        body?.error ?? `Memory server error: ${res.status}`,
+        res.status,
+        body?.code,
+        retryAfter
+      );
     }
     return body.data;
   }
@@ -1189,6 +1368,9 @@ var MemoryClient = class {
 export {
   DEFAULTS,
   TAXONOMY_MAX_CATEGORIES,
+  documentGraphSource,
+  documentContentSource,
+  documentImageSource,
   projectSearchResponseForMcp,
   secretElevationNoticeFor,
   withSecretElevationNotice,

package/dist/cli/pyx-mem.mjs

@@ -597,6 +597,7 @@ function createHttpClient(credentials, fetchImpl = fetch) {
     headers.set("Accept", "application/json");
     if (contentType) headers.set("Content-Type", contentType);
     if (scope?.tenantId) headers.set("X-Tenant-Id", scope.tenantId);
+    if (scope?.namespaceId) headers.set("X-Namespace-Id", scope.namespaceId);
     if (scope?.userId) headers.set("X-User-Id", scope.userId);
     if (scope?.teamId) headers.set("X-Team-Id", scope.teamId);
     if (scope?.callerAccessLevel) headers.set("X-Caller-Access-Level", scope.callerAccessLevel);
@@ -835,7 +836,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.17.16" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.17.17" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     const text = read.result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();

package/dist/dashboard.d.ts

@@ -21,6 +21,8 @@ interface SubgraphResponse {
     totalNodes: number;
     totalEdges: number;
     truncated: boolean;
+    nodesTruncated?: boolean;
+    edgesTruncated?: boolean;
 }
 interface HealthData {
     status: 'ok' | 'degraded' | 'unreachable';
@@ -191,7 +193,7 @@ declare class DashboardClient extends MemoryClient {
      * arbitrary N-node sample were silently dropped, collapsing dense graphs to
      * a handful of rendered links.
      */
-    graphSubgraph(edges?: number): Promise<SubgraphResponse>;
+    graphSubgraph(edges?: number, nodes?: number): Promise<SubgraphResponse>;
     fetchHealthRaw(): Promise<RawHealthResponse>;
 }
 

package/dist/dashboard.mjs

@@ -11,9 +11,9 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-ZVI7DCB4.mjs";
-import "./chunk-MDFUZ3V2.mjs";
-import "./chunk-34MTVIYK.mjs";
+} from "./chunk-AMKPOPH6.mjs";
+import "./chunk-JGFDID3B.mjs";
+import "./chunk-3OLH3HYR.mjs";
 export {
   DashboardClient,
   Poller,