@pyxmate/memory 0.14.0 → 0.15.0

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

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

package/dist/{chunk-QNRIO462.mjs → chunk-W4LB326D.mjs}

@@ -112,47 +112,26 @@ var MemoryClient = class {
     const qs = searchParams.toString();
     return this.fetchApi(`/api/memory/entries${qs ? `?${qs}` : ""}`);
   }
-  // --- Additional endpoints ---
+  // --- File ingest ---
   /**
-   * Ingest a file with optional two-phase enrichment.
+   * Native streaming file ingest. Yields typed {@link IngestEvent}s as the
+   * server (parsing/storing) and the SDK (enrichment/result) make progress.
    *
-   * 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}.
+   * 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.
    *
-   * 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.
+   * 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.
    *
-   * 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.
+   * 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 + JSON fallback + SDK enrichment fan-out is genuinely 3 cooperating paths; each is documented inline and tested in memory-client-events.test.ts.
+  // 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);
@@ -162,9 +141,7 @@ var MemoryClient = class {
       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 wantsTextWindows = Boolean(options?.enrichment?.extractEntitiesV2);
       const headers = {
         Accept: "application/x-ndjson",
         ...this._authHeaders
@@ -187,12 +164,13 @@ var MemoryClient = class {
       }
       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");
-        }
+        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) {
@@ -275,7 +253,7 @@ var MemoryClient = class {
    * {@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.
+  // 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) {
@@ -346,24 +324,6 @@ var MemoryClient = class {
         );
         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;

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-JBKJDTFO.mjs";
-import "./chunk-QNRIO462.mjs";
+} from "./chunk-K7JZXUBN.mjs";
+import "./chunk-W4LB326D.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 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';
+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, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -72,15 +72,14 @@ interface ExtendedMemoryInterface extends MemoryInterface {
 }
 
 /**
- * Callbacks for two-phase file enrichment. All callbacks are optional so the
- * SDK can support every combination of the v2 flow:
+ * Callbacks for two-phase file enrichment. All callbacks are optional:
  *   - Image-rich PDF + describeImage only → describes images, no entity extraction
- *   - Image-rich PDF + describeImage + extractEntities[V2] → describes + extracts
- *   - Text-only file + extractEntities[V2] only → extracts from textWindows
- *   - Mixed file + all three → describes + extracts from both sources
+ *   - Image-rich PDF + describeImage + extractEntitiesV2 → describes + extracts
+ *   - Text-only file + extractEntitiesV2 only → extracts from textWindows
+ *   - Mixed file + both → describes images + extracts from both sources
  *
- * Without ANY callback, ingestFile returns the parsed result without running
- * Phase 2/3 — caller opted out of enrichment entirely.
+ * Without any callback, the ingest stream emits the server result with no
+ * SDK-side enrichment — caller opted out entirely.
  */
 interface EnrichmentCallbacks {
     /**
@@ -90,21 +89,10 @@ interface EnrichmentCallbacks {
      */
     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
-     * cannot distinguish the two sources. Kept for backwards compatibility;
-     * new code should prefer {@link extractEntitiesV2}.
-     */
-    extractEntities?: (descriptions: string[]) => Promise<{
-        entities: IngestEntity$1[];
-        relationships: IngestRelationship$1[];
-    }>;
-    /**
-     * v2 entity-extraction callback. Receives text windows and image
-     * descriptions separately so callers can apply different prompts per
-     * source. Takes precedence over {@link extractEntities} when both are
-     * defined. Triggers the `X-Pyx-Enrichment-Capabilities: text_windows_v1`
-     * negotiation header on ingest.
+     * Entity-extraction callback. Receives text windows and image descriptions
+     * separately so callers can apply different prompts per source. Triggers
+     * the `X-Pyx-Enrichment-Capabilities: text_windows_v1` negotiation header
+     * on ingest.
      */
     extractEntitiesV2?: (input: {
         textWindows: string[];
@@ -117,9 +105,8 @@ interface EnrichmentCallbacks {
     }>;
 }
 /**
- * Options for {@link MemoryClient.ingestFile} and
- * {@link MemoryClient.ingestFileEvents}. `signal` lets long-running ingests
- * (LLM enrichment + graph writes) be cancelled cleanly.
+ * Options for {@link MemoryClient.ingestFileEvents}. `signal` lets
+ * long-running ingests (LLM enrichment + graph writes) be cancelled cleanly.
  */
 interface IngestFileOptions {
     description?: string;
@@ -171,35 +158,22 @@ declare class MemoryClient implements ExtendedMemoryInterface {
     shutdown(): Promise<void>;
     list(params?: MemoryListParams): Promise<MemoryListResult>;
     /**
-     * Ingest a file with optional two-phase enrichment.
+     * Native streaming file ingest. Yields typed {@link IngestEvent}s as the
+     * server (parsing/storing) and the SDK (enrichment/result) make progress.
      *
-     * 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.
-     */
-    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 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.
      *
-     * 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.
+     * 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.
      *
-     * 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.
+     * 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).
      */
     ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent$1>;
     /**

package/dist/index.mjs

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

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-JBKJDTFO.mjs";
-import "./chunk-QNRIO462.mjs";
+} from "./chunk-K7JZXUBN.mjs";
+import "./chunk-W4LB326D.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.14.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/skills/pyx-memory/patterns/access-control.md

@@ -207,7 +207,7 @@ pyx-memory has two auth tiers: `API_KEY` (read + write) and `ADMIN_API_KEY` (des
 
 | Key | Allowed operations |
 |-----|-------------------|
-| `API_KEY` | All read operations (search, get, list, stats) + write operations (store, ingestFile) |
+| `API_KEY` | All read operations (search, get, list, stats) + write operations (store, ingestFileEvents) |
 | `ADMIN_API_KEY` | Destructive operations: DELETE, forget, decay, consolidate, reindex, deleteBySource |
 
 ```bash

package/skills/pyx-memory/patterns/consumer.md

@@ -42,18 +42,24 @@ if (memory) {
   const nodes = await memory.graphNodes();
   const traversal = await memory.graphQuery({ nodeId: 'node-1', depth: 2 });
 
-  // File ingestion — also available on MemoryClient
+  // File ingestion — native NDJSON streaming via ingestFileEvents()
   const file = new File([buffer], 'report.pdf', { type: 'application/pdf' });
-  const result = await memory.ingestFile(file);
+  for await (const event of memory.ingestFileEvents(file)) {
+    if (event.type === 'progress') console.log(`[${event.stage}] ${event.message ?? ''}`);
+    if (event.type === 'error') throw new Error(event.message ?? event.error);
+    // event.type === 'result' carries the terminal { filename, chunks, entryIds, ... }
+  }
 
   // Image ingestion with AI description
   // pyx-memory saves the original image to {DATA_DIR}/files/ and indexes the
   // description in vector + SQLite for semantic search. Without a description,
   // images get a minimal placeholder ("[Image] filename (size KB)").
   const image = new File([imgBuffer], 'photo.png', { type: 'image/png' });
-  const imgResult = await memory.ingestFile(image, {
+  for await (const _ of memory.ingestFileEvents(image, {
     description: 'A screenshot of the login page showing an error dialog',
-  });
+  })) {
+    /* drain to terminal */
+  }
 
   // Lifecycle
   await memory.consolidate();

package/skills/pyx-memory/patterns/file-uploads.md

@@ -1,7 +1,7 @@
 # Pattern: File Uploads
 
 This is consumer-side guidance: how to decide whether to forward a file
-straight to `ingestFile()` or to pre-extract its text upstream first.
+straight to `ingestFileEvents()` or to pre-extract its text upstream first.
 
 ## TL;DR
 

package/skills/pyx-memory/reference/http-api.md

@@ -90,53 +90,42 @@ For deterministic peak memory or timing (production UX), consumers should pre-ex
 
 **Image ingestion**: Images cannot have text extracted. Pass a `description` field with a natural-language description (e.g., from an LLM with vision). Without a description, images get a minimal placeholder (`[Image] filename (size KB)`).
 
-**PDF enrichment**: When a PDF contains images (≥50x50px), the response includes an `enrichment` block. The SDK's `ingestFile()` with `EnrichmentCallbacks` handles the full flow automatically — see [sdk-guide.md](sdk-guide.md#two-phase-pdf-enrichment).
+**PDF enrichment**: When a PDF contains images (≥50x50px), the server emits an `enrichment` block on the terminal `result` event. The SDK's `ingestFileEvents()` with `EnrichmentCallbacks` handles the full flow automatically — see [sdk-guide.md](sdk-guide.md#two-phase-pdf-enrichment).
 
-### Streaming Progress (NDJSON)
+### NDJSON Wire Format (the only response shape)
 
-For real-time ingestion progress, request NDJSON streaming by setting the `Accept` header or a query parameter:
-
-```bash
-# Via Accept header
-curl -X POST {{ENDPOINT}}/api/memory/ingest/file \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -H "Accept: application/x-ndjson" \
-  -F "file=@large-report.pdf"
-
-# Via query parameter
-curl -X POST "{{ENDPOINT}}/api/memory/ingest/file?stream=true" \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -F "file=@large-report.pdf"
-```
-
-The response is streamed as newline-delimited JSON (`Content-Type: application/x-ndjson`). Each line is a JSON object:
+`POST /api/memory/ingest/file` always streams `Content-Type: application/x-ndjson`. Each line is one typed event with `schemaVersion: 1`. The terminal event is exactly one of `result` (success) or `error` (failure):
 
 ```
-{"type":"progress","stage":"parsing","filename":"large-report.pdf","message":"Extracting text..."}
-{"type":"progress","stage":"storing","filename":"large-report.pdf","chunksStored":10,"totalCharacters":4800,"message":"Storing chunk 10..."}
-{"type":"progress","stage":"storing","filename":"large-report.pdf","chunksStored":20,"totalCharacters":9600,"message":"Storing chunk 20..."}
-{"type":"progress","stage":"complete","filename":"large-report.pdf","chunksStored":24,"totalCharacters":11520,"message":"Ingestion complete"}
-{"type":"result","filename":"large-report.pdf","fileType":".pdf","chunks":24,"entryIds":[...],"totalCharacters":11520}
+{"schemaVersion":1,"type":"progress","stage":"parsing","filename":"large-report.pdf","message":"Extracting text..."}
+{"schemaVersion":1,"type":"progress","stage":"storing","filename":"large-report.pdf","chunksStored":10,"totalCharacters":4800}
+{"schemaVersion":1,"type":"heartbeat","stage":"storing","message":"File ingest still running"}
+{"schemaVersion":1,"type":"progress","stage":"enrichment","filename":"large-report.pdf"}
+{"schemaVersion":1,"type":"result","stage":"complete","filename":"large-report.pdf","fileType":".pdf","chunks":24,"entryIds":["…"],"totalCharacters":11520}
 ```
 
-**Progress stages**: `parsing` (text extraction), `storing` (chunk storage — emitted every batch), `enrichment` (PDF image extraction), `complete` (done).
+**Stable stages**: `parsing` (text/image extraction), `storing` (chunk + vector writes), `enrichment` (LLM image-describe + entity-extract + `/enrich` POST), `complete` (terminal result only). Finer detail goes in optional counters (`chunksStored`, `totalCharacters`) and `message`, not in new stage names.
+
+**Heartbeat**: emitted every 20s while the pipeline is doing slow work. Sized below undici's default 300s `headersTimeout` and Envoy's default 5m stream-idle so an LLM call or graph batch never trips an upstream socket timeout.
 
-The last line always has `"type":"result"` and contains the full `IngestionResult` (same shape as the non-streaming JSON response). On error, the last line has `"type":"error"` with an `error` message string.
+**Errors before the stream starts** (multipart parse, file size cap, validation) come back as a single-line NDJSON `error` event with the appropriate HTTP status code on the response.
 
-Without the `Accept: application/x-ndjson` header (or `?stream=true`), the endpoint behaves exactly as before — returning a single JSON response after ingestion completes.
+Pre-v0.15.0 servers returned `application/json` for this endpoint. v0.15.0 SDK consumers will see a terminal `error` event with the message `Memory server returned application/json instead of application/x-ndjson — server is older than v0.15.0` if they hit such a server; upgrade the server.
 
 ### Example: ingest a document
 
 ```bash
-curl -X POST {{ENDPOINT}}/api/memory/ingest/file \
+curl -N -X POST {{ENDPOINT}}/api/memory/ingest/file \
   -H "Authorization: Bearer {{API_KEY}}" \
   -F "file=@report.pdf"
 ```
 
+`-N` disables curl buffering so events appear as the server emits them.
+
 ### Example: ingest an image with description
 
 ```bash
-curl -X POST {{ENDPOINT}}/api/memory/ingest/file \
+curl -N -X POST {{ENDPOINT}}/api/memory/ingest/file \
   -H "Authorization: Bearer {{API_KEY}}" \
   -F "file=@screenshot.png" \
   -F "description=A screenshot of the dashboard showing memory usage at 85%"
@@ -145,29 +134,45 @@ curl -X POST {{ENDPOINT}}/api/memory/ingest/file \
 ### SDK usage
 
 ```typescript
+import { MemoryClient, type FileIngestResult } from '@pyxmate/memory';
+
+// Iterate the AsyncIterable. The terminal event is `result` (success) or `error` (failure).
+async function ingestAndCollect(memory: MemoryClient, file: File): Promise<FileIngestResult> {
+  for await (const event of memory.ingestFileEvents(file)) {
+    if (event.type === 'progress' || event.type === 'heartbeat') continue;
+    if (event.type === 'error') throw new Error(event.message ?? event.error);
+    // event.type === 'result'
+    const { schemaVersion: _v, type: _t, stage: _s, message: _m, ...result } = event;
+    return result;
+  }
+  throw new Error('memory ingest stream ended without a terminal event');
+}
+
 // Document (text-only)
 const doc = new File([buffer], 'report.pdf', { type: 'application/pdf' });
-await memory.ingestFile(doc);
+await ingestAndCollect(memory, doc);
 
 // Image with description
 const img = new File([imgBuffer], 'photo.png', { type: 'image/png' });
-await memory.ingestFile(img, {
+await ingestAndCollect(memory, img); // pass via options when needed
+for await (const _ of memory.ingestFileEvents(img, {
   description: 'A photo of the whiteboard from the architecture meeting',
-});
+})) { /* drain */ }
 
 // PDF with two-phase enrichment (images described via LLM vision)
-await memory.ingestFile(pdfFile, {
+for await (const event of memory.ingestFileEvents(pdfFile, {
   enrichment: {
-    describeImage: async (buffer, meta) => {
-      // Call your LLM vision model to describe the image
-      return 'A bar chart showing Q4 revenue growth of 23%';
-    },
-    extractEntities: async (descriptions) => ({
+    describeImage: async (buffer, meta) => 'A bar chart showing Q4 revenue growth of 23%',
+    extractEntitiesV2: async ({ textWindows, imageDescriptions, filename, mimeType }) => ({
       entities: [{ name: 'Q4 Revenue', type: 'METRIC' }],
       relationships: [],
     }),
   },
-});
+})) {
+  if (event.type === 'progress') {
+    console.log(`[${event.stage}] ${event.message ?? ''}`);
+  }
+}
 ```
 
 ## File Downloads
@@ -201,13 +206,13 @@ const buffer = await response.arrayBuffer();
 
 ## Two-Phase PDF Enrichment
 
-When a PDF contains extractable images, the server returns an `enrichment` block from `POST /api/memory/ingest/file`. The SDK wraps the full three-phase flow into a single `ingestFile()` call with `EnrichmentCallbacks`.
+When a PDF contains extractable images, the server's terminal `result` event carries an `enrichment` block. The SDK's `ingestFileEvents()` with `EnrichmentCallbacks` runs the full three-phase flow automatically, emitting its own `enrichment` progress + heartbeat events while it works.
 
 ### Flow
 
 ```
-Phase 1: POST /api/memory/ingest/file → text stored immediately
-  Response: { ...result, enrichment: { fileId, token, expiresAt, images: [...] } }
+Phase 1: POST /api/memory/ingest/file → text stored immediately, enrichment block emitted on terminal `result`
+  Result event: { schemaVersion: 1, type: 'result', stage: 'complete', ...ingestResult, enrichment: { fileId, token, expiresAt, images: [...] } }
 
 Phase 2: GET /api/memory/files/{fileId}/images/{imageId}?token=... → binary image
   (SDK fetches each image, calls describeImage callback)

package/skills/pyx-memory/reference/sdk-guide.md

@@ -179,36 +179,44 @@ All from `@pyx-memory/core` except `MemoryServerError` from `@pyx-memory/client`
 
 ## Two-Phase PDF Enrichment
 
-When ingesting PDFs that contain images, `ingestFile()` supports a two-phase enrichment flow via `EnrichmentCallbacks`. The SDK handles all three phases automatically:
+When ingesting PDFs that contain images, `ingestFileEvents()` runs a three-phase enrichment flow via `EnrichmentCallbacks`. The SDK handles all phases automatically and emits typed `IngestEvent`s as it goes:
 
-1. **Upload** — text extracted and stored immediately
-2. **Image description** — each extracted image is fetched and described via your LLM vision callback (batched, 5 concurrent)
-3. **Enrichment** — descriptions + entities submitted back to the server
+1. **Server upload** — text extracted and stored immediately; server emits `progress` events with stage `parsing` then `storing`
+2. **Image description** — each extracted image is fetched and described via your LLM vision callback (batched, 5 concurrent); SDK emits `progress`/`heartbeat` events with stage `enrichment`
+3. **Enrichment write** — descriptions + entities POSTed back to the server's `/enrich` endpoint; SDK emits the terminal `result` event
 
 ```typescript
-import { MemoryClient, type EnrichmentCallbacks } from '@pyx-memory/client';
+import { MemoryClient, type EnrichmentCallbacks, type FileIngestResult } from '@pyxmate/memory';
 
 const memory = new MemoryClient('http://localhost:7822', apiKey);
 
 const enrichment: EnrichmentCallbacks = {
-  // Required: describe each image using LLM vision
+  // Optional: describe each image using LLM vision
   describeImage: async (imageBuffer, meta) => {
     // imageBuffer is ArrayBuffer of the extracted PNG/JPEG
     // meta has: imageId, pageNumber, width, height, mimeType
-    const description = await myVisionModel.describe(imageBuffer);
-    return description;
+    return await myVisionModel.describe(imageBuffer);
   },
-  // Optional: extract entities from all descriptions at once
-  extractEntities: async (descriptions) => ({
+  // Optional: extract entities from text windows + image descriptions
+  extractEntitiesV2: async ({ textWindows, imageDescriptions, filename, mimeType }) => ({
     entities: [{ name: 'Revenue', type: 'METRIC' }],
     relationships: [{ source: 'Revenue', target: 'Q4', type: 'RELATED_TO' }],
   }),
 };
 
-const result = await memory.ingestFile(pdfFile, { enrichment });
-// result.enrichment is defined when PDF had images
-// Text chunks are already stored from Phase 1
-// Image descriptions are stored from Phase 3
+let result: FileIngestResult | null = null;
+for await (const event of memory.ingestFileEvents(pdfFile, { enrichment })) {
+  if (event.type === 'progress') {
+    console.log(`[${event.stage}] ${event.message ?? ''}`);
+    continue;
+  }
+  if (event.type === 'error') throw new Error(event.message ?? event.error);
+  if (event.type === 'result') {
+    const { schemaVersion: _v, type: _t, stage: _s, message: _m, ...payload } = event;
+    result = payload;
+  }
+}
+if (!result) throw new Error('memory ingest stream ended without a result');
 ```
 
-Without `enrichment` callbacks, `ingestFile()` behaves identically to before — fully backwards compatible.
+Without `enrichment` callbacks, the stream still emits `parsing` → `storing` progress events and a terminal `result` — the SDK just skips Phase 2/3.

package/skills/pyx-memory/reference/types.md

@@ -107,13 +107,11 @@ class MemoryClient implements ExtendedMemoryInterface {
   graphEdges(): Promise<{ stats: { nodeCount: number; edgeCount: number } }>;
   graphQuery(query: { nodeId: string; depth?: number }): Promise<GraphTraversalResult>;
 
-  // File ingestion with optional two-phase enrichment
-  // Without callbacks: standard single-phase ingest (backwards compatible)
-  // With callbacks: fetches extracted images, calls describeImage, submits enrichment
-  ingestFile(file: File, options?: {
-    description?: string;
-    enrichment?: EnrichmentCallbacks;
-  }): Promise<FileIngestResult>;
+  // File ingestion — native NDJSON streaming (v0.15.0+)
+  // Yields typed IngestEvents (progress / heartbeat / result / error).
+  // With enrichment callbacks: fetches extracted images, calls describeImage,
+  // calls extractEntitiesV2, posts /enrich, then yields the terminal `result`.
+  ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent>;
 
   // Bi-temporal queries
   queryAsOf(asOf: string, filters?: TemporalQueryFilters): Promise<MemoryEntry[]>;