@pyxmate/memory 0.9.3 → 0.10.0

package/dist/index.d.ts

@@ -255,6 +255,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 +377,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.9.3",
+  "version": "0.10.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)
 }
 ```