@pyxmate/memory 0.45.1 → 1.0.1

package/dist/dashboard.mjs

@@ -11,9 +11,9 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-DKNGLNN4.mjs";
-import "./chunk-UV2DFSKR.mjs";
-import "./chunk-KSTI4M52.mjs";
+} from "./chunk-ZILXBWWH.mjs";
+import "./chunk-U3U4MHWS.mjs";
+import "./chunk-X6AYWXW7.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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, 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, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
+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, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -19,6 +19,8 @@ interface MemoryListParams {
      * and get the legacy tenant-only scope.
      */
     principal?: PrincipalContext$1;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
     /**
      * R1/R2 — opt-in list of `metadata._kind` values to include in the
      * response. When omitted or empty, the default-set returns only entries
@@ -42,6 +44,8 @@ interface TemporalQueryFilters {
     agentId?: string;
     source?: string;
     limit?: number;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
 }
 /** Filters for the chronological feed (`log`, Karpathy `log.md` primitive). */
 interface MemoryLogFilters {
@@ -52,6 +56,8 @@ interface MemoryLogFilters {
     type?: MemoryType$1;
     agentId?: string;
     source?: string;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
 }
 /** Options for scoping operations to a specific tenant. */
 interface TenantScopeOptions {
@@ -69,6 +75,8 @@ interface TenantScopeOptions {
      * legacy tenant-only scope.
      */
     principal?: PrincipalContext$1;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
 }
 /** Abstract interface for memory systems (local or remote). */
 interface MemoryInterface {
@@ -141,6 +149,37 @@ interface ExtendedMemoryInterface extends MemoryInterface {
     getEntitySynthesis(name: string): Promise<MemoryEntry$1 | null>;
 }
 
+/**
+ * No-op {@link MemoryInterface} for hosts that run without a memory backend
+ * (e.g. `MEMORY_URL` is unset). Every method returns a safe default, so the
+ * rest of the system functions without branching on `memory == null`.
+ *
+ * Canonical single source: this lives in the SAME package as `MemoryInterface`,
+ * so any method added to the interface fails THIS class's compile in the same
+ * build. The null-object can never silently drift behind the contract — the
+ * failure mode that left hand-rolled copies in downstream repos missing
+ * `lineage`/`reinforce` after the interface grew them.
+ *
+ * `initialize()` emits a single `console.warn`; pass nothing else — it is a
+ * pure null-object. Hosts wanting structured logging should log at the wiring
+ * site where they choose `DisabledMemory` over a real client.
+ */
+declare class DisabledMemory implements MemoryInterface {
+    initialize(): Promise<void>;
+    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
+    search(): Promise<MemorySearchResult$1>;
+    list(params?: MemoryListParams): Promise<MemoryListResult>;
+    get(): Promise<MemoryEntry$1 | null>;
+    delete(): Promise<boolean>;
+    clearSession(): Promise<number>;
+    stats(): Promise<MemoryStats$1>;
+    queryAsOf(): Promise<MemoryEntry$1[]>;
+    lineage(): Promise<LineageResult$1>;
+    reinforce(): Promise<ReinforceResult$1>;
+    queryByEventTime(): Promise<MemoryEntry$1[]>;
+    shutdown(): Promise<void>;
+}
+
 /**
  * Callbacks for two-phase file enrichment. All callbacks are optional:
  *   - Image-rich PDF + describeImage only → describes images, no entity extraction
@@ -149,7 +188,9 @@ interface ExtendedMemoryInterface extends MemoryInterface {
  *   - Mixed file + both → describes images + extracts from both sources
  *
  * Without any callback, the ingest stream emits the server result with no
- * SDK-side enrichment — caller opted out entirely.
+ * SDK-side enrichment. Server-side text/entity extraction may still run when
+ * configured; image understanding still requires caller-provided
+ * descriptions/hooks.
  */
 interface EnrichmentCallbacks {
     /**
@@ -191,9 +232,12 @@ interface IngestFileOptions {
 }
 /**
  * Caller-supplied enrichment for the per-call store path. Mirrors
- * {@link EnrichmentCallbacks} for file ingest — the SDK invokes the callback
- * (against the caller's own LLM credentials) and merges the result into the
- * ingest payload before POSTing, so the server holds no LLM keys.
+ * {@link EnrichmentCallbacks} for file ingest. When supplied, the SDK invokes
+ * the callback and merges the result into the payload before POSTing. Without
+ * a callback, server-side text/entity extraction can run only when the server
+ * has an extraction brain configured; otherwise callers must pass graph data
+ * or use caller-side hooks. Images always require caller-provided
+ * descriptions/hooks.
  */
 interface StoreEnrichmentCallbacks {
     /**
@@ -203,8 +247,8 @@ interface StoreEnrichmentCallbacks {
      *
      * Skipped when `entry.extractEntities === false`. When
      * `entry.extractEntities === true` but this callback is not supplied,
-     * `MemoryClient.store()` throws a loud error rather than silently no-op'ing
-     * (same shape as the in-process Memory.store() guard).
+     * `MemoryClient.store()` forwards the hint so the server-side extraction
+     * brain can run and loud-fail if it is not configured.
      */
     extractEntities?: (input: {
         content: string;
@@ -495,6 +539,24 @@ declare const EmbeddingProviderName: {
     readonly HTTP: "http";
 };
 type EmbeddingProviderName = (typeof EmbeddingProviderName)[keyof typeof EmbeddingProviderName];
+type GraphEnrichmentStatus = 'caller-provided' | 'extracted' | 'merged' | 'opted-out' | 'skipped-duplicate' | 'skipped-sensitive' | 'skipped-unprovisioned' | 'extracted-empty' | 'failed-graph-write' | 'failed-best-effort';
+interface GraphEnrichment {
+    status: GraphEnrichmentStatus;
+    provider?: 'http' | 'local' | 'none';
+    reason?: string;
+    action?: string;
+}
+/**
+ * A caller-supplied relationship whose source or target name did not resolve to
+ * any entity in the same store call (after name normalization), so the edge was
+ * not written. Surfaced on the store response so the agent — not just the server
+ * log — can see which edges to re-send.
+ */
+interface DroppedGraphRelationship {
+    source: string;
+    target: string;
+    type: string;
+}
 interface MemoryEntry {
     id: string;
     content: string;
@@ -529,6 +591,12 @@ interface MemoryEntry {
     graphEntitiesWritten?: number;
     /** Number of graph relationships written by this store call. Present on store responses. */
     graphRelationshipsWritten?: number;
+    /** Count of caller relationships dropped because an endpoint name did not match any entity in the call. Present (and >0) only when edges were dropped. */
+    graphRelationshipsDropped?: number;
+    /** Up to 20 of the dropped relationships (source/target/type), so the agent can re-send them. Present only when edges were dropped. */
+    graphRelationshipsDroppedDetail?: DroppedGraphRelationship[];
+    /** Graph extraction/enrichment outcome for this store call. Present on graph-targeted store responses. */
+    graphEnrichment?: GraphEnrichment;
     /** Tenant ID for multi-tenant isolation. */
     tenantId?: string;
     /** User ID within the tenant. */
@@ -602,8 +670,8 @@ interface MemorySearchParams {
      * only). The pipeline retrieves and dedups a deeper candidate pool (≥50),
      * scores it through the cross-encoder, then truncates to `limit` —
      * reranking after truncation cannot change top-`limit` set membership.
-     * EMBEDDED ONLY: `MemoryClient.search` rejects it (HTTP API does not
-     * forward it).
+     * Forwarded by `MemoryClient.search` and the HTTP route; core enforces
+     * hybrid-only usage.
      */
     enableRerank?: boolean;
     /**
@@ -643,7 +711,7 @@ interface MemorySearchParams {
      * reinforces); idle alone never revives. See `docs/H8-MEMORY-MODEL-DESIGN.md`.
      */
     effort?: 'quick' | 'medium' | 'deep';
-    /** Maximum sensitivity level to include in results. Entries above this level are excluded or redacted. */
+    /** Maximum sensitivity level to include in results. Entries above this level are excluded. */
     maxSensitivity?: SensitivityLevel;
     /** Tenant ID for multi-tenant isolation. */
     tenantId?: string;
@@ -683,10 +751,17 @@ interface MemorySearchResult {
     strategy: RAGStrategy;
     /** Visible graph slice that supported the returned entries, when graph traversal contributed. */
     graph?: GraphTraversalResult;
-    /** Optional scored entries with relevance scores for ranked results. */
+    /**
+     * Optional scored entries for ranked results. `score` is the fused RANK score
+     * (RRF + recency/importance/access priors) — good for ordering, NOT a relevance
+     * magnitude. `vectorSimilarity` is the raw dense query-similarity (LanceDB
+     * transformed-L2, 1/(1+distance)); null when the entry has no dense signal
+     * (FTS/graph-only). Surface vectorSimilarity, not score, as a "% match".
+     */
     scoredEntries?: Array<{
         entry: MemoryEntry;
         score: number;
+        vectorSimilarity?: number | null;
     }>;
     /** Confidence assessment for abstention. Present when search produces scored entries. */
     confidence?: {
@@ -918,6 +993,8 @@ interface FetchCorrectionsInput {
     project?: string;
     /** Max corrections to return. Default 5, hard cap 5. */
     limit?: number;
+    /** Optional sensitivity cap for hosted/HTTP callers. Omitted preserves trusted in-process behavior. */
+    maxSensitivity?: SensitivityLevel;
 }
 /** One applicable correction returned by `fetchApplicableCorrections`. */
 interface CorrectionRecord {
@@ -1005,11 +1082,10 @@ interface WikiLintReport {
 /**
  * Result shape returned by an LLM entity extractor — entities + relations.
  *
- * Lives in shared so both the server-side Memory.store() merge and any
- * client-side enrichment path (`MemoryClient.store(..., { enrichment })`,
- * the MCP `store_memory` tool that goes through MCP sampling) can speak the
- * exact same structural type without crossing the core→client circular
- * dependency.
+ * Lives in shared so server-side Memory.store(), client-side enrichment
+ * (`MemoryClient.store(..., { enrichment })`), and MCP store forwarding can
+ * speak the exact same structural type without crossing the core→client
+ * circular dependency.
  */
 interface EntityExtractionResult {
     entities: Array<{
@@ -1023,6 +1099,18 @@ interface EntityExtractionResult {
     }>;
 }
 declare function normalizeGraphLabel(value: string, fallback: string): string;
+/**
+ * Identity key for a graph node: the normalized name alone. `type` is a node
+ * ATTRIBUTE, never part of identity — it is a noisy, role-dependent, LLM-guessed
+ * label that the relationship contract cannot even address (edges reference
+ * names only), so using it as a primary key fractures one real-world entity
+ * into disconnected nodes and severs multi-hop chains.
+ *
+ * The single source of truth for name identity: the SQLite/Neo4j upserts and
+ * the core relationship resolver match by this, and the MCP store guard predicts
+ * edge resolvability with it — all three MUST agree, so they import this one fn.
+ */
+declare function normalizeNameKey(name: string): string;
 /**
  * Merge caller-provided entities/relationships with LLM-extracted ones.
  *
@@ -1061,6 +1149,8 @@ type TopologyServiceVariant = 'cloud' | 'full';
  * is internal infrastructure and is intentionally NOT exposed here.
  */
 type TopologyEmbeddingLocation = 'inline' | 'remote';
+/** Server-side graph extraction provider resolved at boot. */
+type TopologyExtractionProvider = 'http' | 'local' | 'none';
 /**
  * Public topology snapshot returned by `GET /status`. Reflects actual runtime
  * capability (variant detected from import probe, embedding location derived
@@ -1084,6 +1174,9 @@ interface Topology {
         modelId: string;
         dimensions: number;
     };
+    extraction: {
+        provider: TopologyExtractionProvider;
+    };
 }
 
 /** Metadata for a single image extracted from a PDF. */
@@ -1361,4 +1454,12 @@ interface PrincipalContext {
 /** Sentinel tenant ID used in single-tenant deployments. */
 declare const SINGLE_TENANT_ID = "_single";
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, DEFAULTS, DEPRECATED_RAG_STRATEGIES, EmbeddingProviderName, type EnrichmentCallbacks, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, 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, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyServiceVariant, VectorProvider, type WikiLintReport, mergeExtractedEntities, normalizeGraphLabel };
+interface CreatePyxMemoryOptions {
+    url?: string;
+    apiKey?: string;
+    requestTimeoutMs?: number;
+    defaultHeaders?: Record<string, string>;
+}
+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, EmbeddingProviderName, type EnrichmentCallbacks, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphEnrichment, type GraphEnrichmentStatus, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, 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, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, VectorProvider, type WikiLintReport, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey };

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import {
+  DisabledMemory,
   MemoryClient,
   MemoryServerError
-} from "./chunk-UV2DFSKR.mjs";
+} from "./chunk-U3U4MHWS.mjs";
 import {
   DEFAULTS,
   DEPRECATED_RAG_STRATEGIES,
@@ -15,11 +16,27 @@ import {
   StoreTarget,
   VectorProvider,
   mergeExtractedEntities,
-  normalizeGraphLabel
-} from "./chunk-KSTI4M52.mjs";
+  normalizeGraphLabel,
+  normalizeNameKey
+} from "./chunk-X6AYWXW7.mjs";
+
+// src/preset.ts
+var DEFAULT_MEMORY_URL = `http://localhost:${DEFAULTS.MEMORY_SERVER_PORT}`;
+function createPyxMemory(opts = {}) {
+  const env = typeof process !== "undefined" ? process.env : {};
+  const url = opts.url ?? env.PYX_MEMORY_URL ?? DEFAULT_MEMORY_URL;
+  const apiKey = opts.apiKey ?? env.PYX_MEMORY_API_KEY;
+  const clientOptions = {
+    ...apiKey !== void 0 ? { apiKey } : {},
+    ...opts.defaultHeaders !== void 0 ? { defaultHeaders: opts.defaultHeaders } : {},
+    ...opts.requestTimeoutMs !== void 0 ? { requestTimeoutMs: opts.requestTimeoutMs } : {}
+  };
+  return new MemoryClient(url, clientOptions);
+}
 export {
   DEFAULTS,
   DEPRECATED_RAG_STRATEGIES,
+  DisabledMemory,
   EmbeddingProviderName,
   MemoryClient,
   MemoryServerError,
@@ -31,6 +48,8 @@ export {
   SensitivityLevel,
   StoreTarget,
   VectorProvider,
+  createPyxMemory,
   mergeExtractedEntities,
-  normalizeGraphLabel
+  normalizeGraphLabel,
+  normalizeNameKey
 };

package/dist/react.mjs

@@ -11,9 +11,9 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-DKNGLNN4.mjs";
-import "./chunk-UV2DFSKR.mjs";
-import "./chunk-KSTI4M52.mjs";
+} from "./chunk-ZILXBWWH.mjs";
+import "./chunk-U3U4MHWS.mjs";
+import "./chunk-X6AYWXW7.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.45.1",
+  "version": "1.0.1",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",
@@ -28,6 +28,10 @@
       "import": "./dist/dashboard.mjs",
       "types": "./dist/dashboard.d.ts"
     },
+    "./agent-contract": {
+      "import": "./dist/agent-contract.mjs",
+      "types": "./dist/agent-contract.d.ts"
+    },
     "./react": {
       "import": "./dist/react.mjs",
       "types": "./dist/react.d.ts"
@@ -43,6 +47,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "generate:agent-template": "bun run scripts/generate-agent-template.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist skills node_modules .turbo"