@pyxmate/memory 0.9.3 → 0.11.0

package/dist/{chunk-KVRPHFDP.mjs → chunk-5IERAVVW.mjs}

@@ -112,21 +112,36 @@ var MemoryClient = class {
    * With enrichment callbacks: fetches extracted images, calls describeImage for each,
    * optionally extracts entities, then submits enrichment data back to the server.
    */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: two-phase enrichment fans out across image-describe + entity-extract + v1/v2 negotiation; each branch maps to a documented case in memory-client-enrichment.test.ts
   async ingestFile(file, options) {
     const formData = new FormData();
     formData.append("file", file);
     if (options?.description) {
       formData.append("description", options.description);
     }
+    const wantsTextWindows = Boolean(
+      options?.enrichment?.extractEntities || options?.enrichment?.extractEntitiesV2
+    );
+    const headers = { ...this._authHeaders };
+    if (wantsTextWindows) {
+      headers["X-Pyx-Enrichment-Capabilities"] = "text_windows_v1";
+    }
     const res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
       method: "POST",
       body: formData,
-      headers: this._authHeaders
+      headers
     });
     const result = await this.parseApiResponse(res);
-    if (result.enrichment && options?.enrichment?.describeImage) {
-      const { fileId, token, expiresAt, images } = result.enrichment;
-      const descriptions = [];
+    if (!result.enrichment || !options?.enrichment) {
+      return result;
+    }
+    const enrichment = result.enrichment;
+    const { fileId, token, expiresAt, images } = enrichment;
+    const isV2 = "version" in enrichment;
+    const textWindows = isV2 ? enrichment.textWindows : [];
+    const descriptions = [];
+    const describeImage = options.enrichment.describeImage;
+    if (describeImage && images.length > 0) {
       const CONCURRENCY = 5;
       for (let i = 0; i < images.length; i += CONCURRENCY) {
         const batch = images.slice(i, i + CONCURRENCY);
@@ -143,48 +158,66 @@ var MemoryClient = class {
               );
             }
             const imageBuffer = await imageRes.arrayBuffer();
-            const description = await options.enrichment.describeImage(imageBuffer, imageMeta);
+            const description = await describeImage(imageBuffer, imageMeta);
             return { imageId: imageMeta.imageId, description };
           })
         );
         descriptions.push(...batchResults);
       }
-      let entities;
-      let relationships;
-      if (options.enrichment.extractEntities && descriptions.length > 0) {
-        const extracted = await options.enrichment.extractEntities(
-          descriptions.map((d) => d.description)
-        );
+    }
+    let entities;
+    let relationships;
+    const v2Callback = options.enrichment.extractEntitiesV2;
+    const legacyCallback = options.enrichment.extractEntities;
+    const imageDescriptionTexts = descriptions.map((d) => d.description);
+    if (v2Callback && (textWindows.length > 0 || imageDescriptionTexts.length > 0)) {
+      const extracted = await v2Callback({
+        textWindows,
+        imageDescriptions: imageDescriptionTexts,
+        mimeType: file.type,
+        filename: file.name
+      });
+      entities = extracted.entities;
+      relationships = extracted.relationships;
+    } else if (legacyCallback) {
+      const allInputs = [...textWindows, ...imageDescriptionTexts];
+      if (allInputs.length > 0) {
+        const extracted = await legacyCallback(allInputs);
         entities = extracted.entities;
         relationships = extracted.relationships;
       }
-      const enrichTokenHeader = `${token}:${expiresAt}`;
-      const enrichRes = await fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "X-Enrichment-Token": enrichTokenHeader,
-          ...this._authHeaders
-        },
-        body: JSON.stringify({
-          imageDescriptions: descriptions,
-          entities,
-          relationships
-        })
-      });
-      if (!enrichRes.ok) {
-        const body = await enrichRes.json().catch(() => ({}));
-        throw new MemoryServerError(
-          body.error ?? `Enrichment failed: ${enrichRes.status}`,
-          enrichRes.status
-        );
-      }
-      const enrichData = await this.parseApiResponse(enrichRes);
-      const enrichCharacters = descriptions.reduce((sum, d) => sum + d.description.length, 0);
-      result.entryIds.push(...enrichData.entryIds);
-      result.chunks += descriptions.length;
-      result.totalCharacters += enrichCharacters;
     }
+    const hasGraph = (entities?.length ?? 0) > 0;
+    const hasImages = descriptions.length > 0;
+    if (!hasGraph && !hasImages) {
+      return result;
+    }
+    const enrichTokenHeader = `${token}:${expiresAt}`;
+    const enrichRes = await fetch(`${this.baseUrl}/api/memory/files/${fileId}/enrich`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Enrichment-Token": enrichTokenHeader,
+        ...this._authHeaders
+      },
+      body: JSON.stringify({
+        imageDescriptions: descriptions,
+        entities,
+        relationships
+      })
+    });
+    if (!enrichRes.ok) {
+      const body = await enrichRes.json().catch(() => ({}));
+      throw new MemoryServerError(
+        body.error ?? `Enrichment failed: ${enrichRes.status}`,
+        enrichRes.status
+      );
+    }
+    const enrichData = await this.parseApiResponse(enrichRes);
+    const enrichCharacters = descriptions.reduce((sum, d) => sum + d.description.length, 0);
+    result.entryIds.push(...enrichData.entryIds);
+    result.chunks += descriptions.length;
+    result.totalCharacters += enrichCharacters;
     return result;
   }
   /**

package/dist/{chunk-QFEFLBTN.mjs → chunk-DGVOXKYV.mjs}

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

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-QFEFLBTN.mjs";
-import "./chunk-KVRPHFDP.mjs";
+} from "./chunk-DGVOXKYV.mjs";
+import "./chunk-5IERAVVW.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/index.d.ts

@@ -71,15 +71,50 @@ interface ExtendedMemoryInterface extends MemoryInterface {
     deleteBySource(source: string): Promise<number>;
 }
 
-/** Callbacks for two-phase file enrichment. */
+/**
+ * Callbacks for two-phase file enrichment. All callbacks are optional so the
+ * SDK can support every combination of the v2 flow:
+ *   - 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
+ *
+ * Without ANY callback, ingestFile returns the parsed result without running
+ * Phase 2/3 — caller opted out of enrichment entirely.
+ */
 interface EnrichmentCallbacks {
-    /** Describe an image using LLM vision. Receives the raw image buffer and metadata. */
-    describeImage: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta) => Promise<string>;
-    /** Optionally extract entities/relationships from all image descriptions. */
+    /**
+     * Describe an image using LLM vision. Receives the raw image buffer and
+     * 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>;
+    /**
+     * 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.
+     */
+    extractEntitiesV2?: (input: {
+        textWindows: string[];
+        imageDescriptions: string[];
+        mimeType: string;
+        filename: string;
+    }) => Promise<{
+        entities: IngestEntity$1[];
+        relationships: IngestRelationship$1[];
+    }>;
 }
 /** Error thrown by MemoryClient when the server returns a non-success response. */
 declare class MemoryServerError extends Error {
@@ -255,6 +290,13 @@ interface MemoryEntry {
     userId?: string;
     /** Team/group ID within the tenant. */
     teamId?: string;
+    /**
+     * When true, consolidation leaves this entry alone — it is never archived by
+     * decay and never merged (nor merged-into) by semantic deduplication. Use for
+     * stable anchor entries whose ID is referenced by external systems (e.g. a
+     * file-catalog row pointed at by another service's foreign key).
+     */
+    pinned?: boolean;
 }
 interface MemorySearchParams {
     query: string;
@@ -370,6 +412,11 @@ interface MemoryIngestRequest {
     userId?: string;
     /** Team/group ID within the tenant. */
     teamId?: string;
+    /**
+     * Exclude this entry from consolidation (decay-archive and semantic dedup).
+     * See `MemoryEntry.pinned` for full semantics.
+     */
+    pinned?: boolean;
 }
 interface MemoryStats {
     totalEntries: number;

package/dist/index.mjs

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

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-QFEFLBTN.mjs";
-import "./chunk-KVRPHFDP.mjs";
+} from "./chunk-DGVOXKYV.mjs";
+import "./chunk-5IERAVVW.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.9.3",
+  "version": "0.11.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

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

@@ -86,6 +86,21 @@ When `consolidate()` runs, it executes a 7-step pipeline:
 
 All steps have **non-LLM fallbacks** — consolidation works without an LLM, just less intelligently.
 
+### Pinned entries (opt out of consolidation)
+
+Entries stored with `pinned: true` are exempt from both the dedup step and the decay-archive step. `Memory.runDecay()` skips them via the same filter. Use for anchor rows whose ID is referenced by external systems — e.g. a file-catalog entry whose ID is stored as a foreign key in a downstream service's database:
+
+```typescript
+await memory.store({
+  content: '[File: "report.pdf" (application/pdf)]',
+  type: MemoryType.LONG_TERM,
+  metadata: { source: 'file-ingestion', filename: 'report.pdf' },
+  pinned: true, // external FK points here — must not be merged or archived
+});
+```
+
+Without `pinned`, short near-duplicate anchor content can trip the 0.95 cosine dedup threshold and get hard-deleted, orphaning the external reference. Pinned entries' exemption is SQL-side (`WHERE pinned = 0` filter on consolidation's query) and backed by a partial index `idx_memory_pinned WHERE pinned = 1`. Callers can query with `QueryFilters.excludePinned: true` to reproduce the same exclusion.
+
 ---
 
 ## Community Detection

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

@@ -24,7 +24,7 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 |--------|----------|-------------|
 | GET | `/health` | Public health check (status only — no internals exposed) |
 | GET | `/admin/health` | Admin health check (version, uptime, embedding provider, memory stats) |
-| POST | `/api/memory/ingest` | Store a memory (JSON: `{ content, type, metadata, agentId?, sessionId?, targets?, entities?, relationships?, importance?, source?, eventTime?, id?, parentId?, ingestTime? }`) |
+| POST | `/api/memory/ingest` | Store a memory (JSON: `{ content, type, metadata, agentId?, sessionId?, targets?, entities?, relationships?, importance?, source?, eventTime?, id?, parentId?, ingestTime?, pinned? }`) |
 | POST | `/api/memory/ingest/file` | Upload file (multipart, 100MB limit). For PDFs with images, returns an `enrichment` block with HMAC token and image metadata for two-phase enrichment. |
 | GET | `/api/memory/files/download/:filename` | Download uploaded file binary by filename. Returns the original file with proper Content-Type. Images served inline, documents as attachment. |
 | GET | `/api/memory/files/:fileId/images/:imageId?token=...` | Fetch an extracted PDF image (binary). Requires HMAC token from ingest response. |

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

@@ -192,6 +192,7 @@ interface MemoryEntry {
   teamId?: string;             // team/group within tenant
   sensitivity?: SensitivityLevel; // auto-classified: 'public' | 'internal' | 'secret'
   encrypted?: boolean;         // true when content is encrypted at rest
+  pinned?: boolean;            // exempt from consolidation (decay-archive + dedup-merge); use for stable anchors referenced by external systems
 }
 ```
 
@@ -220,6 +221,7 @@ interface SearchFilters {
   eventTimeRange?: [string, string];  // [start, end] ISO timestamps
   parentId?: string;
   contentType?: string;
+  excludePinned?: boolean;             // SQL-side `pinned = 0` filter (used internally by consolidation/decay; available to callers too)
 }
 ```