@pyxmate/memory 1.32.1 → 1.33.0

package/dist/{chunk-MD5RCZCA.mjs → chunk-DV4IQOVD.mjs}

@@ -612,6 +612,13 @@ function normalizeExpand(input) {
   return { baseEntryIds, anchorEntryIds };
 }
 var CALLER_ENTRY_ID_RESERVED_PREFIXES = ["synthesis:", "user-profile:", "correction:"];
+function optionalExplainEntryId(value, strategy) {
+  if (value === void 0) return void 0;
+  if (strategy !== "hybrid") throw new Error("input.explainEntryId requires the hybrid strategy");
+  return requireString(value, "input.explainEntryId", {
+    maxBytes: DATA_PLANE_COMPILER_LIMITS.identityBytes
+  });
+}
 function optionalCallerEntryId(value, field) {
   if (value === void 0) return void 0;
   const id = requireString(value, field, { maxBytes: DATA_PLANE_COMPILER_LIMITS.identityBytes });
@@ -1131,7 +1138,8 @@ function normalizeSearch(input, mcp) {
     "asOf",
     "anchorTime",
     "enumerationConcept",
-    "enableRerank"
+    "enableRerank",
+    "explainEntryId"
   ];
   requireExactKeys(value, keys, "input");
   if (value.enumerationConcept !== void 0) {
@@ -1172,6 +1180,11 @@ function normalizeSearch(input, mcp) {
   if (value.enableRerank !== void 0) {
     normalized.enableRerank = requireBoolean(value.enableRerank, "input.enableRerank");
   }
+  withOptional(
+    normalized,
+    "explainEntryId",
+    optionalExplainEntryId(value.explainEntryId, normalized.strategy)
+  );
   return normalized;
 }
 function normalizeLineage(input, mcp) {

package/dist/{chunk-F2G2TBLW.mjs → chunk-UWGKWV44.mjs}

@@ -2,7 +2,7 @@ import {
   RAGStrategy,
   assertGraphExtractionPayload,
   mergeExtractedEntities
-} from "./chunk-MD5RCZCA.mjs";
+} from "./chunk-DV4IQOVD.mjs";
 
 // ../client/src/disabled-memory.ts
 var DEFAULT_PAGE_LIMIT = 20;
@@ -292,6 +292,9 @@ var MemoryClient = class {
     if (enumerationConcept) searchParams.set("enumerationConcept", enumerationConcept);
     if (params.abstentionThreshold != null)
       searchParams.set("abstentionThreshold", String(params.abstentionThreshold));
+    if (params.explainEntryId !== void 0) {
+      searchParams.set("explainEntryId", params.explainEntryId);
+    }
     return this.fetchApi(`/api/memory/search?${searchParams}`, {
       headers: this.authorityHeaders(this.exactReadAuthority(params.namespaceId, authority))
     });

package/dist/{chunk-UIR5VDPF.mjs → chunk-XQIJM5PD.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-F2G2TBLW.mjs";
+} from "./chunk-UWGKWV44.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {

package/dist/cli/pyx-mem.mjs

@@ -144,7 +144,7 @@ async function runMcpInstall(target, scope, remote, noRules) {
 }
 async function runMcpCommand(parsed) {
   if (parsed.subcommand === void 0) {
-    const { mcpCommand, resolveMcpMode } = await import("../mcp-GGI7LUYO.mjs");
+    const { mcpCommand, resolveMcpMode } = await import("../mcp-BAFJVW6C.mjs");
     const resolved = resolveMcpMode({
       remote: parsed.flags.remote === true,
       bundled: parsed.flags.bundled === true
@@ -249,7 +249,7 @@ async function main() {
         process.stderr.write("Error: `pyx-mem insights` requires --json.\n");
         return EXIT.USAGE;
       }
-      const { insightsCommand } = await import("../insights-E7USP2C5.mjs");
+      const { insightsCommand } = await import("../insights-KPANMV7T.mjs");
       return insightsCommand({
         withIdentity: parsed.flags["with-identity"] === true,
         withProvenance: parsed.flags["with-provenance"] === true
@@ -260,7 +260,7 @@ async function main() {
         process.stderr.write("Error: `pyx-mem taxonomy` requires --json.\n");
         return EXIT.USAGE;
       }
-      const { taxonomyCommand } = await import("../taxonomy-65DFVGRY.mjs");
+      const { taxonomyCommand } = await import("../taxonomy-3N4EUGDX.mjs");
       return taxonomyCommand({ withIdentity: parsed.flags["with-identity"] === true });
     }
     case "logout": {

package/dist/dashboard.mjs

@@ -11,10 +11,10 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-UIR5VDPF.mjs";
-import "./chunk-F2G2TBLW.mjs";
+} from "./chunk-XQIJM5PD.mjs";
+import "./chunk-UWGKWV44.mjs";
 import "./chunk-RWQTBXUC.mjs";
-import "./chunk-MD5RCZCA.mjs";
+import "./chunk-DV4IQOVD.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/data-plane-contract.mjs

@@ -27,7 +27,7 @@ import {
   parseHostedFileIngestJobView,
   parseHostedFileIngestPublishResult,
   requireHostedFileIngestFilename
-} from "./chunk-MD5RCZCA.mjs";
+} from "./chunk-DV4IQOVD.mjs";
 export {
   DATA_PLANE_CATALOG_VERSION,
   DATA_PLANE_COMPILER_LIMITS,

package/dist/index.d.ts

@@ -292,6 +292,12 @@ interface MemorySearchParams {
      * index drift. Default true (access tracking is the product's usage signal).
      */
     trackAccess?: boolean;
+    /**
+     * Explain one entry: the result gains `explanation`, saying where this
+     * search kept or dropped it. Hybrid strategy only. Such a search tracks no
+     * access, so explaining a result does not change how it ranks.
+     */
+    explainEntryId?: string;
     /**
      * Retrieval EFFORT tier (H8 slice 1b) — admits candidates by activation
      * strength BEFORE RRF fusion (like LLM thinking-mode depth): `quick` = the
@@ -339,6 +345,84 @@ interface MemorySearchParams {
      */
     forbiddenStrictNamespaceIds?: string[];
 }
+/** The first hybrid-search stage that did not keep an explained entry. */
+type SearchExplanationStage = 
+/** A filter of the search excludes the entry; `filter` names which. */
+'filtered'
+/** No candidate source of the search returned the entry. */
+ | 'not_retrieved'
+/** A higher-scored candidate has the same content. */
+ | 'duplicate'
+/** The entry scored below the last returned result. */
+ | 'below_limit'
+/** The entry was within the limit after scoring; reranking or a later ordering pass moved it out. */
+ | 'reordered_out';
+/** A candidate list of a hybrid search. */
+type SearchCandidateSource = 'vector' | 'keyword' | 'graph' | 'community';
+/**
+ * One candidate's hybrid score: the weighted parts are summed, then
+ * multiplied by `sourceTrust` and `entityBoost` into `total`.
+ */
+interface SearchScoreParts {
+    /** 1-based position among the scored candidates the caller may read. */
+    rank: number;
+    total: number;
+    relevance: number;
+    recency: number;
+    importance: number;
+    access: number;
+    metadata: number;
+    sourceTrust: number;
+    entityBoost: number;
+}
+/**
+ * Where one search kept or dropped one entry. It replays this search now: it
+ * is not a record of an earlier search, and it says nothing about whether a
+ * model used a result. Ranks and sizes count only candidates the caller may
+ * read.
+ */
+interface SearchExplanation {
+    entryId: string;
+    /** False when no entry with this id is readable here; nothing else is reported then. */
+    found: boolean;
+    /** 1-based position in the results; null when the entry was not returned. */
+    rank: number | null;
+    /** The first stage that did not keep the entry; null when it was returned or not found. */
+    stage: SearchExplanationStage | null;
+    /**
+     * The filter that excluded the entry, for stage `filtered`: `effort` (deep
+     * effort would admit it: its activation is below this tier, or it is
+     * superseded or archived), `scope` (no effort would: the search's type,
+     * agentId or namespace, or an on-demand entry), or `time` (`eventTimeRange`
+     * or `asOf`).
+     */
+    filter?: 'effort' | 'scope' | 'time';
+    /** The entry's activation, when the search set `effort`. */
+    activation?: {
+        strength: number;
+        tier: 'quick' | 'medium' | 'deep';
+        grace: boolean;
+    };
+    /**
+     * The search's candidate lists in retrieval order (a source repeats per
+     * sub-query): the entry's 1-based rank in each, or null, and the list's
+     * size. A list with no candidate the caller may read is left out.
+     */
+    sources?: Array<{
+        source: SearchCandidateSource;
+        rank: number | null;
+        size: number;
+    }>;
+    /**
+     * Dense similarity to the query under the search's filters; null when the
+     * vector source cannot see the entry, absent when that source failed.
+     */
+    vectorSimilarity?: number | null;
+    /** The entry's score, when it was scored. */
+    score?: SearchScoreParts;
+    /** The last returned result's score, when the entry was scored but not returned. */
+    cutoff?: SearchScoreParts;
+}
 interface MemorySearchResult {
     entries: MemoryEntry[];
     totalCount: number;
@@ -373,6 +457,8 @@ interface MemorySearchResult {
             scoreSeparation: number;
         };
     };
+    /** Present when the search set `explainEntryId`. */
+    explanation?: SearchExplanation;
 }
 /** One version in a fact's history, as returned by {@link LineageResult}. */
 interface LineageVersion {
@@ -2018,4 +2104,4 @@ interface CreatePyxMemoryOptions {
 }
 declare function createPyxMemory(opts?: CreatePyxMemoryOptions): MemoryClient;
 
-export { type AgentId, type ApiResponse, type ConsolidationJudgementsResult, type ConsolidationMerge, type ConsolidationPair, type ConsolidationPairSide, 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 ExpandAnchorStatus, type ExpandParams, type ExpandResult, 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, MCP_ACTOR_META_KEY, MEMORY_ACTOR_LABEL_MAX_CHARS, MEMORY_PROJECT_LABEL_MAX_CHARS, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInsightMetrics, type MemoryInsights, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemoryProjectInsight, 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, SESSION_ORDINAL_MAX, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, TAXONOMY_MAX_PROJECTS, TAXONOMY_MAX_SAMPLE_TOPICS, TAXONOMY_MAX_TOP_ENTITIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, isSessionOrdinal, mergeExtractedEntities, normalizeGraphLabel, normalizeMemoryActorLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };
+export { type AgentId, type ApiResponse, type ConsolidationJudgementsResult, type ConsolidationMerge, type ConsolidationPair, type ConsolidationPairSide, 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 ExpandAnchorStatus, type ExpandParams, type ExpandResult, 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, MCP_ACTOR_META_KEY, MEMORY_ACTOR_LABEL_MAX_CHARS, MEMORY_PROJECT_LABEL_MAX_CHARS, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInsightMetrics, type MemoryInsights, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemoryProjectInsight, 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, SESSION_ORDINAL_MAX, SINGLE_TENANT_ID, type SearchCandidateSource, type SearchExplanation, type SearchExplanationStage, type SearchScoreParts, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, TAXONOMY_MAX_PROJECTS, TAXONOMY_MAX_SAMPLE_TOPICS, TAXONOMY_MAX_TOP_ENTITIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, isSessionOrdinal, mergeExtractedEntities, normalizeGraphLabel, normalizeMemoryActorLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   DisabledMemory,
   MemoryClient,
   MemoryServerError
-} from "./chunk-F2G2TBLW.mjs";
+} from "./chunk-UWGKWV44.mjs";
 import {
   DEFAULTS,
   MCP_ACTOR_META_KEY,
@@ -40,7 +40,7 @@ import {
   normalizeGraphLabel,
   normalizeNameKey,
   parseListCursorToken
-} from "./chunk-MD5RCZCA.mjs";
+} from "./chunk-DV4IQOVD.mjs";
 
 // src/preset.ts
 var DEFAULT_MEMORY_URL = `http://localhost:${DEFAULTS.MEMORY_SERVER_PORT}`;

package/dist/{insights-E7USP2C5.mjs → insights-KPANMV7T.mjs}

@@ -8,7 +8,7 @@ import {
   TAXONOMY_MAX_PROJECTS,
   normalizeMemoryActorLabel
 } from "./chunk-RWQTBXUC.mjs";
-import "./chunk-MD5RCZCA.mjs";
+import "./chunk-DV4IQOVD.mjs";
 import {
   EXIT
 } from "./chunk-4DXEQC6X.mjs";

package/dist/{mcp-GGI7LUYO.mjs → mcp-BAFJVW6C.mjs}

@@ -25,7 +25,7 @@ import {
   parseHostedFileIngestJobView,
   parseHostedFileIngestPublishResult,
   requireHostedFileIngestFilename
-} from "./chunk-MD5RCZCA.mjs";
+} from "./chunk-DV4IQOVD.mjs";
 import {
   syncMemoryRulesFromServer
 } from "./chunk-QR5K7ETI.mjs";
@@ -901,7 +901,7 @@ function createProxyServer(client, version, uploadLocalFile, hostedFileIngest) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.32.1" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.33.0" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     throw new Error(

package/dist/react.mjs

@@ -11,10 +11,10 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-UIR5VDPF.mjs";
-import "./chunk-F2G2TBLW.mjs";
+} from "./chunk-XQIJM5PD.mjs";
+import "./chunk-UWGKWV44.mjs";
 import "./chunk-RWQTBXUC.mjs";
-import "./chunk-MD5RCZCA.mjs";
+import "./chunk-DV4IQOVD.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts
 import { useCallback as useCallback2, useMemo } from "react";

package/dist/{taxonomy-65DFVGRY.mjs → taxonomy-3N4EUGDX.mjs}

@@ -10,7 +10,7 @@ import {
   TAXONOMY_MAX_SAMPLE_TOPICS,
   TAXONOMY_MAX_TOP_ENTITIES
 } from "./chunk-RWQTBXUC.mjs";
-import "./chunk-MD5RCZCA.mjs";
+import "./chunk-DV4IQOVD.mjs";
 import {
   EXIT
 } from "./chunk-4DXEQC6X.mjs";

package/package.json

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