@pyxmate/memory 1.17.16 → 1.17.17

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, SensitivityLevel as SensitivityLevel$1, MemoryStats as MemoryStats$1, LineageParams as LineageParams$1, LineageResult as LineageResult$1, ReinforceParams as ReinforceParams$1, ReinforceResult as ReinforceResult$1, WikiLintReport as WikiLintReport$1, GraphRepairResult as GraphRepairResult$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, EntityExtractionResult as EntityExtractionResult$1, Topology as Topology$1, IngestEvent as IngestEvent$1, GraphEnrichEvent as GraphEnrichEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
+export { documentContentSource, documentGraphSource, documentImageSource } from '@pyx-memory/shared';
+export { e as encodeListCursorToken, p as parseListCursorToken } from './data-plane-contract-fDvTm9bF.js';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -61,6 +63,17 @@ interface TemporalQueryFilters {
     agentId?: string;
     source?: string;
     limit?: number;
+    /**
+     * Number of matching rows to skip. Offset pages can shift under concurrent
+     * deletion; use cursor for a deletion-stable queryAsOf walk.
+     */
+    offset?: number;
+    /**
+     * Opaque keyset token for a deletion-stable queryAsOf walk. Derive it from
+     * the last returned entry with `encodeListCursorToken`; mutually exclusive
+     * with offset.
+     */
+    cursor?: string;
     /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
     maxSensitivity?: SensitivityLevel$1;
 }
@@ -79,6 +92,8 @@ interface MemoryLogFilters {
 /** Options for scoping operations to a specific tenant. */
 interface TenantScopeOptions {
     tenantId?: string;
+    /** Optional strict namespace coordinate for exact get/delete operations. */
+    namespaceId?: string;
     /**
      * Graph count mode for stats(). Use raw on admin-health paths
      * that should avoid the visible graph projection.
@@ -107,7 +122,7 @@ interface MemoryInterface {
     clearSession(sessionId: string, options?: TenantScopeOptions): Promise<number>;
     stats(options?: TenantScopeOptions): Promise<MemoryStats$1>;
     /** Query entries as they existed at a point in time (by ingest time). */
-    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters, options?: TenantScopeOptions): Promise<MemoryEntry$1[]>;
     /** Read the time-ordered lineage of a graph fact or superseded entry chain. */
     lineage(params: LineageParams$1): Promise<LineageResult$1>;
     /** Reinforce memories that were actually used by the caller. */
@@ -144,7 +159,7 @@ interface ExtendedMemoryInterface extends MemoryInterface {
     /** Reindex the FTS5 full-text search index. */
     reindex(): Promise<void>;
     /** Delete all entries matching a source, cleaning up all stores. */
-    deleteBySource(source: string): Promise<number>;
+    deleteBySource(source: string, options?: TenantScopeOptions): Promise<number>;
     /** Repair stale graph references left by older delete paths or crashed cleanup. */
     repairGraph(): Promise<GraphRepairResult$1>;
     /**
@@ -246,6 +261,20 @@ interface IngestFileOptions {
     enrichment?: EnrichmentCallbacks;
     signal?: AbortSignal;
     namespaceId?: string;
+    /**
+     * Stable logical document identity used for replaceable content, image,
+     * and graph projections. Requires `enrichment.extractEntitiesV2` so the
+     * client can negotiate text windows and complete the stable replacement.
+     */
+    documentKey?: string;
+    /**
+     * Migration-only pinned file-ingestion catalog for this document's first
+     * stable replacement. The server validates its exact scope and uses its
+     * bounded provenance to detach legacy graph references. Omit this after the
+     * stable anchor is established: the first pass may retire catalog-owned
+     * projections, so later revisions should use `documentKey` alone.
+     */
+    catalogEntryId?: string;
 }
 /**
  * Options for {@link MemoryClient.graphEnrichFileEvents}. `documentKey` is the
@@ -259,10 +288,23 @@ interface IngestFileOptions {
  */
 interface GraphEnrichFileOptions {
     documentKey: string;
+    /**
+     * Migration-only pinned file-ingestion catalog for the first stable graph
+     * replacement. The server resolves it in the current tenant/namespace and
+     * detaches its bounded graph references. Omit it on later revisions once
+     * the `documentKey` anchor exists.
+     */
+    catalogEntryId?: string;
     namespaceId?: string;
     signal?: AbortSignal;
     enrichment: EnrichmentCallbacks;
 }
+interface FileDownloadOptions {
+    /** Stable logical document identity used by documentKey-aware ingest. */
+    documentKey?: string;
+    /** Exact namespace containing the uploaded document. */
+    namespaceId?: string;
+}
 /**
  * Caller-supplied enrichment for the per-call store path. Mirrors
  * {@link EnrichmentCallbacks} for file ingest. When supplied, the SDK invokes
@@ -304,7 +346,13 @@ interface RequestAuthorityOptions {
 /** Error thrown by MemoryClient when the server returns a non-success response. */
 declare class MemoryServerError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    /** Stable machine-readable discriminator returned by the memory server. */
+    readonly code?: string;
+    /** Exact HTTP Retry-After value returned by the memory server. */
+    readonly retryAfter?: string;
+    /** Retry delay normalized to seconds when Retry-After is parseable. */
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, status: number, code?: string, retryAfter?: string);
     /** True when the server returned HTTP 404 (not found). */
     get isNotFound(): boolean;
 }
@@ -414,10 +462,10 @@ declare class MemoryClient implements ExtendedMemoryInterface {
      * heartbeat events around each slow step. Throws on any failure; the
      * purpose-specific wrappers translate that into their terminal error.
      *
-     * The purpose controls empty-output semantics: ingest skips an optional
-     * empty add-on; graph-only finalizes an extractor that ran and found zero
-     * entities, but refuses to erase prior graph state when no extractable input
-     * reached the callback at all.
+     * Legacy ingest keeps its existing partial add-on behavior. Graph-only and
+     * documentKey-aware full ingest may replace a prior graph only from a
+     * complete input set (no truncated text windows or undescribed images). A
+     * complete extractor result containing zero entities remains a valid clear.
      */
     private runEnrichmentCallbacks;
     /**
@@ -435,12 +483,12 @@ declare class MemoryClient implements ExtendedMemoryInterface {
      * Get the download URL for an uploaded file.
      * Returns a URL that serves the original file binary with proper Content-Type.
      */
-    getFileDownloadUrl(filename: string): string;
+    getFileDownloadUrl(filename: string, options?: FileDownloadOptions): string;
     /**
      * Download an uploaded file by filename.
      * Returns the raw Response (caller handles the body — arrayBuffer, blob, stream, etc.).
      */
-    downloadFile(filename: string): Promise<Response>;
+    downloadFile(filename: string, options?: FileDownloadOptions): Promise<Response>;
     /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
     listEntries(params?: {
         page?: number;
@@ -469,7 +517,7 @@ declare class MemoryClient implements ExtendedMemoryInterface {
     reindex(): Promise<void>;
     clearGraph(): Promise<number>;
     repairGraph(): Promise<GraphRepairResult$1>;
-    deleteBySource(source: string): Promise<number>;
+    deleteBySource(source: string, authority?: TenantScopeOptions): Promise<number>;
     setFolder(from: string, to: string, options?: {
         dryRun?: boolean;
     }): Promise<{
@@ -478,7 +526,7 @@ declare class MemoryClient implements ExtendedMemoryInterface {
         updated: number;
         dryRun: boolean;
     }>;
-    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters, authority?: TenantScopeOptions): Promise<MemoryEntry$1[]>;
     lineage(params: LineageParams$1, authority?: RequestAuthorityOptions): Promise<LineageResult$1>;
     reinforce(params: ReinforceParams$1, authority?: RequestAuthorityOptions): Promise<ReinforceResult$1>;
     log(filters?: MemoryLogFilters): Promise<MemoryEntry$1[]>;
@@ -996,6 +1044,8 @@ interface ReinforceResult {
 interface SourceEvidence {
     /** Memory entry that produced this graph fact. */
     memoryEntryId: string;
+    /** Data tenant of the source entry. `null` = single-tenant / legacy data. */
+    tenantId?: string | null;
     /** Namespace of the source memory entry. `null` = legacy / tenant-root. */
     namespaceId?: string | null;
     /** Optional source identifier copied from the memory entry or caller. */
@@ -1419,6 +1469,8 @@ interface ApiResponse<T> {
     success: boolean;
     data?: T;
     error?: string;
+    /** Stable machine-readable discriminator for error responses. */
+    code?: string;
 }
 /**
  * Build variant of the running pyx-memory image. Detected from the actual
@@ -1524,11 +1576,21 @@ interface FileIngestResult {
     fileType: string;
     chunks: number;
     entryIds: string[];
+    /**
+     * Stable document graph anchor written during enrichment when the ingest
+     * supplied a documentKey. This anchor is not included in entryIds; that
+     * array remains limited to chunks and image-description rows.
+     */
+    graphAnchorEntryId?: string;
     totalCharacters: number;
     /** Present when images were extracted (v1) OR text windows / images were emitted (v2). */
     enrichment?: EnrichmentPending;
     /** Present only when ≥1 stored chunk was auto-classified secret by credential detection. */
     secretElevation?: SecretElevationAggregate;
+    /** Relationships dropped because an endpoint matched no submitted entity. */
+    relationshipsDropped?: number;
+    /** Up to 20 dropped relationships, retained from the enrichment response. */
+    droppedRelationships?: DroppedGraphRelationship[];
 }
 /** Coarse pipeline stages. Stable vocabulary — finer detail goes in counters/message. */
 type IngestStage = 'parsing' | 'storing' | 'enrichment' | 'complete';
@@ -1575,16 +1637,20 @@ interface IngestErrorEvent {
     message?: string;
     code?: string | number;
     status?: number;
+    /** Exact HTTP Retry-After value when the failure came from an HTTP response. */
+    retryAfter?: string;
+    /** Retry delay normalized to seconds when Retry-After was parseable. */
+    retryAfterSeconds?: number;
     /**
-     * Server's pre-enrichment {@link FileIngestResult}, present when the error
-     * fired during the SDK's enrichment phase (after the server already emitted
-     * a successful result and the file's chunks/entryIds are durably stored).
+     * Durably committed {@link FileIngestResult}, present when either the server
+     * committed a stable replacement but its secondary-projection cleanup is
+     * still pending, or the SDK's later enrichment phase failed.
      *
      * Lets consumers persist the catalog entry id, per-chunk entry ids, and
      * character/chunk counts before surfacing the error — so a 401 storm during
      * entity extraction no longer loses the search-ready chunks. Absent for
-     * errors that happen before the server's terminal result (parsing/storing
-     * stage failures, transport errors, abort).
+     * errors where the attempted revision did not commit (parsing/storing
+     * failures and rollback cleanup debt), transport errors, and aborts.
      */
     partialResult?: FileIngestResult;
 }
@@ -1618,8 +1684,10 @@ interface GraphEnrichResult {
     purpose: 'graph-only';
     filename: string;
     fileType: string;
-    /** The single stable anchor entry id, including a successful zero-entity replacement. */
-    entryIds: string[];
+    /** The single persisted graph projection row, including a successful zero-entity replacement. */
+    entryIds: [string];
+    /** Stable logical document identity whose graph projection was replaced. */
+    graphAnchorEntryId: string;
     entitiesStored: number;
     relationshipsStored: number;
     /** Present (and >0) only when edges were dropped — see {@link EnrichResult}. */
@@ -1753,4 +1821,4 @@ interface CreatePyxMemoryOptions {
 }
 declare function createPyxMemory(opts?: CreatePyxMemoryOptions): MemoryClient;
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, type DueScanInput, EmbeddingProviderName, type EnrichmentCallbacks, type EnrichmentPurpose, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphEnrichEvent, type GraphEnrichFileOptions, type GraphEnrichPreparedEvent, type GraphEnrichResult, type GraphEnrichResultEvent, type GraphEnrichment, type GraphEnrichmentStatus, type GraphExtractionPayload, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, type DueScanInput, EmbeddingProviderName, type EnrichmentCallbacks, type EnrichmentPurpose, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type FileDownloadOptions, type GraphEnrichEvent, type GraphEnrichFileOptions, type GraphEnrichPreparedEvent, type GraphEnrichResult, type GraphEnrichResultEvent, type GraphEnrichment, type GraphEnrichmentStatus, type GraphExtractionPayload, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };

package/dist/index.mjs

@@ -14,17 +14,22 @@ import {
   StoreTarget,
   TAXONOMY_MAX_CATEGORIES,
   VectorProvider,
+  documentContentSource,
+  documentGraphSource,
+  documentImageSource,
   projectSearchResponseForMcp,
   secretElevationAggregate,
   secretElevationNoticeFor,
   withSecretElevationNotice
-} from "./chunk-MDFUZ3V2.mjs";
+} from "./chunk-JGFDID3B.mjs";
 import {
   assertGraphExtractionPayload,
+  encodeListCursorToken,
   mergeExtractedEntities,
   normalizeGraphLabel,
-  normalizeNameKey
-} from "./chunk-34MTVIYK.mjs";
+  normalizeNameKey,
+  parseListCursorToken
+} from "./chunk-3OLH3HYR.mjs";
 
 // src/preset.ts
 var DEFAULT_MEMORY_URL = `http://localhost:${DEFAULTS.MEMORY_SERVER_PORT}`;
@@ -57,9 +62,14 @@ export {
   VectorProvider,
   assertGraphExtractionPayload,
   createPyxMemory,
+  documentContentSource,
+  documentGraphSource,
+  documentImageSource,
+  encodeListCursorToken,
   mergeExtractedEntities,
   normalizeGraphLabel,
   normalizeNameKey,
+  parseListCursorToken,
   projectSearchResponseForMcp,
   secretElevationAggregate,
   secretElevationNoticeFor,

package/dist/react.mjs

@@ -11,9 +11,9 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-ZVI7DCB4.mjs";
-import "./chunk-MDFUZ3V2.mjs";
-import "./chunk-34MTVIYK.mjs";
+} from "./chunk-AMKPOPH6.mjs";
+import "./chunk-JGFDID3B.mjs";
+import "./chunk-3OLH3HYR.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": "1.17.16",
+  "version": "1.17.17",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/dist/chunk-34MTVIYK.mjs

@@ -1,109 +0,0 @@
-// ../shared/src/graph/extraction.ts
-function normalizeGraphLabel(value, fallback) {
-  const normalized = value.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  return normalized.length > 0 ? normalized : fallback;
-}
-function normalizeNameKey(name) {
-  return name.trim().toLowerCase().replace(/\s+/g, " ");
-}
-function requireGraphRecord(value, field) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${field} must be an object`);
-  }
-  return value;
-}
-function requireNonemptyGraphString(value, field) {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`${field} must be a non-empty string`);
-  }
-  return value;
-}
-function assertGraphExtractionPayload(value, field = "graph extraction payload") {
-  const record = requireGraphRecord(value, field);
-  if (!Array.isArray(record.entities)) throw new Error(`${field}.entities must be an array`);
-  if (!Array.isArray(record.relationships)) {
-    throw new Error(`${field}.relationships must be an array`);
-  }
-  const entities = record.entities.map((item, index) => {
-    const entity = requireGraphRecord(item, `${field}.entities[${index}]`);
-    requireNonemptyGraphString(entity.name, `${field}.entities[${index}].name`);
-    requireNonemptyGraphString(entity.type, `${field}.entities[${index}].type`);
-    if (entity.properties !== void 0 && (!entity.properties || typeof entity.properties !== "object" || Array.isArray(entity.properties))) {
-      throw new Error(`${field}.entities[${index}].properties must be an object`);
-    }
-    return item;
-  });
-  const entityNames = new Set(entities.map((entity) => normalizeNameKey(entity.name)));
-  const relationships = record.relationships.map((item, index) => {
-    const relationship = requireGraphRecord(item, `${field}.relationships[${index}]`);
-    const source = requireNonemptyGraphString(
-      relationship.source,
-      `${field}.relationships[${index}].source`
-    );
-    const target = requireNonemptyGraphString(
-      relationship.target,
-      `${field}.relationships[${index}].target`
-    );
-    requireNonemptyGraphString(relationship.type, `${field}.relationships[${index}].type`);
-    if (!entityNames.has(normalizeNameKey(source)) || !entityNames.has(normalizeNameKey(target))) {
-      throw new Error(
-        `${field}.relationships[${index}] endpoints must reference declared entity names`
-      );
-    }
-    if (relationship.properties !== void 0 && (!relationship.properties || typeof relationship.properties !== "object" || Array.isArray(relationship.properties))) {
-      throw new Error(`${field}.relationships[${index}].properties must be an object`);
-    }
-    return item;
-  });
-  return { entities, relationships };
-}
-function relationshipKey(relationship) {
-  return [
-    relationship.source.trim().toLowerCase(),
-    relationship.target.trim().toLowerCase(),
-    normalizeGraphLabel(relationship.type, "RELATED_TO")
-  ].join("\0");
-}
-function mergeExtractedEntities(callerEntities, callerRelationships, extracted) {
-  const entities = [...callerEntities ?? []];
-  const relationships = [...callerRelationships ?? []];
-  const nameByLowercase = /* @__PURE__ */ new Map();
-  for (const entity of entities) {
-    const key = entity.name.toLowerCase();
-    if (!nameByLowercase.has(key)) nameByLowercase.set(key, entity.name);
-  }
-  for (const entity of extracted.entities) {
-    const key = entity.name.toLowerCase();
-    if (nameByLowercase.has(key)) continue;
-    entities.push({ ...entity, type: normalizeGraphLabel(entity.type, "CONCEPT") });
-    nameByLowercase.set(key, entity.name);
-  }
-  for (const relationship of extracted.relations) {
-    const source = nameByLowercase.get(relationship.source.toLowerCase());
-    const target = nameByLowercase.get(relationship.target.toLowerCase());
-    if (source && target) {
-      relationships.push({
-        ...relationship,
-        source,
-        target,
-        type: normalizeGraphLabel(relationship.type, "RELATED_TO")
-      });
-    }
-  }
-  const seenRelationships = /* @__PURE__ */ new Set();
-  const dedupedRelationships = [];
-  for (const relationship of relationships) {
-    const key = relationshipKey(relationship);
-    if (seenRelationships.has(key)) continue;
-    seenRelationships.add(key);
-    dedupedRelationships.push(relationship);
-  }
-  return { entities, relationships: dedupedRelationships };
-}
-
-export {
-  normalizeGraphLabel,
-  normalizeNameKey,
-  assertGraphExtractionPayload,
-  mergeExtractedEntities
-};