@pyxmate/memory 0.3.0-beta → 0.3.1-beta

package/package.json

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

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

@@ -38,6 +38,15 @@ if (memory) {
   const file = new File([buffer], 'report.pdf', { type: 'application/pdf' });
   const result = await memory.ingestFile(file);
 
+  // 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, {
+    description: 'A screenshot of the login page showing an error dialog',
+  });
+
   // Lifecycle
   await memory.consolidate();
   await memory.runDecay();

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

@@ -54,6 +54,58 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | GET | `/api/memory/query-as-of?asOf=...` | Bi-temporal point-in-time query (asOf, type, agentId, source, limit) |
 | GET | `/api/memory/query-by-event-time?startTime=...&endTime=...` | Bi-temporal event time range query (startTime, endTime, type, agentId, source, limit) |
 
+## File Ingestion (Images + Documents)
+
+`POST /api/memory/ingest/file` accepts multipart/form-data with:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | File | Yes | The file to ingest (max 50MB) |
+| `description` | string | No | Agent-provided description (e.g., from LLM vision). Used instead of parser output for images. |
+
+**Supported formats**: `.txt`, `.md`, `.csv`, `.pdf`, `.docx`, `.json`, `.jsonl`, `.html`, `.htm`, `.log`, `.tsv`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.svg`
+
+**What happens on upload**:
+1. Original file is saved to `{DATA_DIR}/files/{filename}` (persistent across restarts)
+2. Text is extracted (documents) or description is used (images)
+3. Content is chunked and stored in SQLite + vector for semantic search
+4. Source-aware dedup: re-uploading the same filename replaces the previous version
+
+**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)`).
+
+### Example: ingest a document
+
+```bash
+curl -X POST {{ENDPOINT}}/api/memory/ingest/file \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -F "file=@report.pdf"
+```
+
+### Example: ingest an image with description
+
+```bash
+curl -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%"
+```
+
+### SDK usage
+
+```typescript
+// Document
+const doc = new File([buffer], 'report.pdf', { type: 'application/pdf' });
+await memory.ingestFile(doc);
+
+// Image with description
+const img = new File([imgBuffer], 'photo.png', { type: 'image/png' });
+await memory.ingestFile(img, {
+  description: 'A photo of the whiteboard from the architecture meeting',
+});
+```
+
+---
+
 ## Entity Extraction (Knowledge Graph)
 
 When storing memories that mention named subjects, include `entities` and `relationships` in the ingest request to populate the knowledge graph. This enables graph-based RAG and dashboard visualization.

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

@@ -87,7 +87,8 @@ class MemoryClient implements ExtendedMemoryInterface {
   graphQuery(query: { nodeId: string; depth?: number }): Promise<GraphTraversalResult>;
 
   // File ingestion (multipart upload to server)
-  ingestFile(file: File): Promise<IngestionResult>;
+  // For images: pass { description } from LLM vision to enable semantic search
+  ingestFile(file: File, options?: { description?: string }): Promise<IngestionResult>;
 
   // Bi-temporal queries
   queryAsOf(asOf: string, filters?: TemporalQueryFilters): Promise<MemoryEntry[]>;