@pyxmate/memory 0.13.0 → 0.15.0

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, 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 {
     /**
@@ -88,23 +87,12 @@ 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
-     * 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[];
@@ -116,6 +104,15 @@ interface EnrichmentCallbacks {
         relationships: IngestRelationship$1[];
     }>;
 }
+/**
+ * Options for {@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;
@@ -161,16 +158,43 @@ 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.
+     *
+     * 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.
      *
-     * 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.
+     * 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).
+     */
+    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.
      */
-    ingestFile(file: File, options?: {
-        description?: string;
-        enrichment?: EnrichmentCallbacks;
-    }): Promise<FileIngestResult>;
+    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 +516,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-W4LB326D.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-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.13.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[]>;