@pyxmate/memory 0.12.1 → 0.13.0

package/dist/index.d.ts

@@ -394,6 +394,17 @@ interface IngestRelationship {
     /** Optional properties to attach to the graph edge. */
     properties?: Record<string, unknown>;
 }
+/**
+ * How `Memory.store()` should react when the graph write fails.
+ * - `throw` (default, since v0.13.0): propagate the failure so the caller
+ *   knows the graph is incomplete. Honest contract: a graph write either
+ *   commits or fails loudly. Silent partial-loss was the v0.12.2 bug that
+ *   masked 91/92 dropped entities.
+ * - `best-effort`: swallow the error and log a warning; the entry is still
+ *   considered ingested in SQLite/vector. Use only when you genuinely don't
+ *   need the graph slice and a transient neo4j blip shouldn't fail ingest.
+ */
+type GraphFailureMode = 'throw' | 'best-effort';
 /** Store input: what the agent sends to Memory.store(). */
 type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
     id?: string;
@@ -404,6 +415,8 @@ type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
     entities?: IngestEntity[];
     /** Agent-provided relationships for graph storage. */
     relationships?: IngestRelationship[];
+    /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
+    graphFailureMode?: GraphFailureMode;
 };
 interface MemoryIngestRequest {
     content?: string;
@@ -417,6 +430,8 @@ interface MemoryIngestRequest {
     entities?: IngestEntity[];
     /** Agent-provided relationships for graph storage. */
     relationships?: IngestRelationship[];
+    /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
+    graphFailureMode?: GraphFailureMode;
     /** Importance score (1-10). */
     importance?: number;
     /** Source identifier (e.g., filename, URL). */
@@ -477,4 +492,4 @@ interface GraphTraversalResult {
     }>;
 }
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type ExtendedMemoryInterface, 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 };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/skills/pyx-memory/SKILL.md

@@ -93,7 +93,16 @@ curl -s -X POST {{ENDPOINT}}/api/memory/ingest/file \
 
 Supported formats: txt, md, csv, tsv, log, pdf, docx, xlsx, pptx, json, jsonl, html, htm, png, jpg, jpeg, webp, gif, bmp, tiff, svg (100MB limit).
 
-Ingestion streams from disk — parsers read row-by-row (csv/xlsx), line-by-line (txt/jsonl), page-by-page (pdf), or slide-by-slide (pptx) so peak memory is bounded regardless of file size. The only exception is `.docx`, which is hard-capped at 10MB because the underlying library (mammoth) loads the whole document into memory; above 10MB the server returns an error asking you to pre-extract the text upstream and re-upload as `.txt` or `.md`.
+Ingestion memory profile, by format:
+
+- **Plain-text + structured-text** (`csv`, `tsv`, `txt`, `log`, `json`, `jsonl`, `html`, `htm`, `md`): truly streaming — peak memory ≈ a few MB regardless of file size, up to the 100 MB file cap.
+- **`pdf`**: streaming via the poppler `pdftotext` first-class path — peak memory ≈ a few MB. The `pdf-parse` fallback (when poppler is absent) loads the whole buffer; install poppler-utils for streaming.
+- **`xlsx`**: row-by-row streaming via `ExcelJS.stream.xlsx.WorkbookReader`, but **shared strings are cached for the whole workbook** (`sharedStrings: 'cache'`). Peak memory grows with shared-string count, not just file size — workbooks with dense, repeated cell strings can use significantly more memory than the file cap suggests.
+- **`pptx`**: the full ZIP is decompressed in memory (same shape as docx); only one slide's XML is decoded at a time. For a typical 30 MB presentation, peak memory is ~90 MB. Capped at 100 MB file / 200 MB decompressed.
+- **`docx`**: hard-capped at 10 MB. The underlying library (mammoth) has no streaming API and loads the whole document into memory; above 10 MB the server returns a `MemoryError` asking you to pre-extract the text upstream and re-upload as `.txt` or `.md`.
+- **Images** (`png`, `jpg`, `jpeg`, `webp`, `gif`, `bmp`, `tiff`, `svg`): the file is held in memory once for embedding/storage; size scales with the file, not with content complexity.
+
+If you need deterministic memory or timing for production UX (e.g. RAG over large user-supplied workbooks), prefer pre-extracting `.pptx` and large `.xlsx` upstream and uploading the text as `.txt`. See `patterns/file-uploads.md` for the consumer-side pattern.
 
 **Images require a `description`** — this is how the content gets embedded and becomes searchable. Without it, the image is stored but not findable. Use your vision capabilities to generate the description when the user doesn't provide one.
 

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

@@ -0,0 +1,78 @@
+# 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.
+
+## TL;DR
+
+| Format | Default action |
+|---|---|
+| `txt`, `md`, `csv`, `tsv`, `log`, `json`, `jsonl`, `html`, `htm` | Forward raw — pyx-memory streams. |
+| `pdf` | Forward raw — pyx-memory streams via poppler. Install `poppler-utils` on the server image. |
+| Images (`png`, `jpg`, `jpeg`, `webp`, `gif`, `bmp`, `tiff`, `svg`) | Forward raw with a `description` (use vision capability). |
+| `docx` ≤ 10 MB | Forward raw. |
+| `docx` > 10 MB | **Pre-extract upstream** as `.txt` or `.md`. The server returns a `MemoryError` if you don't. |
+| `xlsx` (large or shared-string-heavy) | **Pre-extract upstream** as `.xxx.xlsx.txt` for deterministic UX. |
+| `pptx` (production UX) | **Pre-extract upstream** as `.xxx.pptx.txt` for deterministic UX. |
+
+"Production UX" here means: you can't afford a single hung upload to wedge
+the user-facing layer for 30+ seconds, you need actionable error messages
+on every failure, and you have your own copy of the original file
+(separate from pyx-memory's internal storage).
+
+## Why pre-extract pptx and large xlsx
+
+The server's pptx parser decompresses the full ZIP in memory (~3× file
+size peak). The xlsx parser streams rows but caches shared strings for
+the entire workbook (`ExcelJS.WorkbookReader { sharedStrings: 'cache' }`).
+Both are bounded by the 100 MB file / 200 MB decompressed caps, but
+"bounded" is not "constant" — pathological files (huge shared-string
+tables, dense cell formulas, embedded media) can push peak memory and
+parse time well past what naive callers expect.
+
+If you control the upload boundary (e.g. you operate a runtime/proxy
+service that fronts pyx-memory), upstream pre-extraction lets you:
+
+1. **Catch parse failures at your boundary**, where you can return an
+   actionable error to the user (`"Excel formula evaluation failed at
+   sheet 'Q3 Revenue', row 412"`) instead of a generic upstream 5xx.
+2. **Bound the wire payload to pyx-memory** — text/plain only — so the
+   memory server's parser is never the bottleneck.
+3. **Keep the original binary in your own storage**, so users can still
+   download the file. pyx-memory's catalog only holds the indexed text.
+
+## Reference implementation
+
+[ai-rag-hub](https://github.com/fysoul17/one-query-v1) (a consumer of
+pyx-memory) implements this pattern in its runtime:
+
+- `packages/server/src/text-extractors.ts` — local extractors for `pptx`
+  and `xlsx`, both wrapped in the same OOXML safety envelope (zip-bomb
+  defense, path-traversal check, macro reject, decompressed-size cap,
+  char limit).
+- `packages/server/src/routes/memory.ts` — `prepareFileForIngest`
+  dispatches via `getTextExtractor(mimeType)`; matched formats are
+  re-uploaded as `<original>.txt` with `text/plain`. Catalog metadata
+  flags `downloadableFromMemory: false` so the consumer's own
+  `/api/team/documents/[id]/download` route serves the original
+  binary instead.
+
+## When NOT to pre-extract
+
+Single-tenant lab usage, internal tools, batch jobs where a 30-second
+parse latency is acceptable, or any case where you don't have your own
+copy of the file and need pyx-memory's `GET /api/memory/files/download/:filename`
+to return the original binary. In those cases, the native pyx-memory
+parsers are exactly what you want.
+
+## What about other formats
+
+- **HTML**: pyx-memory strips `<script>` and `<style>` during parse
+  (`parsers/html.ts`). No upstream sanitizer needed for indexing.
+- **PDF with images**: use the SDK's two-phase enrichment via
+  `EnrichmentCallbacks` — see `reference/sdk-guide.md`. Don't pre-extract
+  the PDF as text and lose image enrichment.
+- **SVG**: currently classified as an image but pyx-memory's image
+  parser only stores it as a placeholder; if you need SVG text indexed,
+  pre-extract the `<text>` and `<desc>` content yourself or convert to
+  raster + describeImage.

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

@@ -71,7 +71,15 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 
 **Supported formats**: `.txt`, `.md`, `.csv`, `.tsv`, `.log`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.json`, `.jsonl`, `.html`, `.htm`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.svg`
 
-**Memory behavior**: All text parsers (csv, tsv, txt, log, pdf, json, jsonl, html, xlsx, pptx) stream from disk during ingestion — peak server memory is bounded to a few MB regardless of file size, up to the 100MB file limit. `.docx` is the exception: mammoth (the parser) has no streaming API, so `.docx` is hard-capped at 10MB on the server. Above 10MB the server returns a `MemoryError` asking you to pre-extract the text upstream and re-upload as `.txt` or `.md`.
+**Memory behavior, by format**:
+
+- **Plain-text + structured-text** (`csv`, `tsv`, `txt`, `log`, `json`, `jsonl`, `html`, `htm`, `md`) — fully streaming; peak server memory ≈ a few MB regardless of file size up to the 100 MB cap.
+- **`pdf`** — streaming via `pdftotext` (poppler-utils); fall-back path (`pdf-parse`) buffers the file, so install poppler-utils on the server for streaming behavior.
+- **`xlsx`** — `ExcelJS.stream.xlsx.WorkbookReader` yields rows as it parses, but the shared-string table is cached for the whole workbook. Peak memory grows with shared-string count; dense workbooks can exceed "a few MB" significantly.
+- **`pptx`** — the full ZIP is decompressed in memory (~3× file size peak for typical decks). One slide's XML is decoded at a time. Bounded by the 100 MB file cap and a 200 MB decompressed cap.
+- **`docx`** — hard-capped at 10 MB. mammoth has no streaming API; above 10 MB the server returns a `MemoryError` asking you to pre-extract the text upstream and re-upload as `.txt` or `.md`.
+
+For deterministic peak memory or timing (production UX), consumers should pre-extract `.pptx` and large `.xlsx` upstream and upload the text as `.txt` — see `patterns/file-uploads.md`.
 
 **What happens on upload**:
 1. Original file is saved to `{DATA_DIR}/files/{filename}` (persistent across restarts)