@pyxmate/memory 0.37.0 → 0.38.0

package/dist/{chunk-EXUSQ2GR.mjs → chunk-CK7VUON3.mjs}

@@ -100,6 +100,7 @@ var MemoryClient = class {
     if (params.type) searchParams.set("type", params.type);
     if (params.agentId) searchParams.set("agentId", params.agentId);
     if (params.strategy) searchParams.set("strategy", params.strategy);
+    if (params.effort) searchParams.set("effort", params.effort);
     if (params.eventTimeRange) {
       searchParams.set("eventTimeStart", params.eventTimeRange[0]);
       searchParams.set("eventTimeEnd", params.eventTimeRange[1]);
@@ -628,6 +629,27 @@ var MemoryClient = class {
     );
     return result.entries;
   }
+  async lineage(params) {
+    const searchParams = new URLSearchParams();
+    if (params.subject) searchParams.set("subject", params.subject);
+    if (params.relation) searchParams.set("relation", params.relation);
+    if (params.entryId) searchParams.set("entryId", params.entryId);
+    if (params.asOf) searchParams.set("asOf", params.asOf);
+    if (params.beforeValue) searchParams.set("beforeValue", params.beforeValue);
+    if (params.limit !== void 0) searchParams.set("limit", String(params.limit));
+    if (params.eventTimeRange) {
+      searchParams.set("eventTimeStart", params.eventTimeRange[0]);
+      searchParams.set("eventTimeEnd", params.eventTimeRange[1]);
+    }
+    const qs = searchParams.toString();
+    return this.fetchApi(`/api/memory/lineage${qs ? `?${qs}` : ""}`);
+  }
+  async reinforce(params) {
+    return this.fetchApi("/api/memory/reinforce", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
   async log(filters = {}) {
     const params = new URLSearchParams();
     if (filters.since) params.set("since", filters.since);

package/dist/{chunk-DEMDFWI4.mjs → chunk-TDPGRIJW.mjs}

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

package/dist/cli/pyx-mem.mjs

@@ -555,7 +555,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/mcp/instructions.ts
-var PYX_MEMORY_INSTRUCTIONS = `Use pyx-memory to search durable project/user memory before assuming prior decisions, and to store concise facts after corrections, bug fixes, design decisions, integration discoveries, gotchas, explicit preferences, or "remember this" requests. Store decisions, not deliberation. Include topic and project. Pass eventTime (ISO-8601, when the fact happened or took effect) for any fact that can change or go stale \u2014 job/status changes, decisions that supersede earlier ones, dated events; recency ordering, dated ("as of") queries, and stale-vs-current conflict resolution all key off it. When a question names a time \u2014 explicit or relative ("last year", "\uB450 \uB2EC \uC804") \u2014 resolve it to an absolute ISO-8601 timestamp yourself and pass it as search anchorTime: results then rank by proximity to that time instead of now, without excluding anything. When content names people, organizations, tools, places, events, or key concepts, you (the caller) must extract and pass both entities and relationships \u2014 the server does not auto-extract them. Edges matter as much as nodes: without relationships the graph cannot connect related memories. Use file ingest for documents/images worth persisting; images require a description.`;
+var PYX_MEMORY_INSTRUCTIONS = `Use pyx-memory to search durable project/user memory before assuming prior decisions, and to store concise facts after corrections, bug fixes, design decisions, integration discoveries, gotchas, explicit preferences, or "remember this" requests. Store decisions, not deliberation. Include topic and project. Pass eventTime (ISO-8601, when the fact happened or took effect) for any fact that can change or go stale \u2014 job/status changes, decisions that supersede earlier ones, dated events; recency ordering, dated ("as of") queries, and stale-vs-current conflict resolution all key off it. Search effort is retrieval depth: quick=strongest, deep=everything including archived/superseded. Use reinforce after memories were actually used, so they surface in quick/medium effort tiers. Use lineage for the history of how a fact changed; pass subject+relation for graph lineage or entryId for a superseded chain. When a question names a time \u2014 explicit or relative ("last year", "\uB450 \uB2EC \uC804") \u2014 resolve it to an absolute ISO-8601 timestamp yourself and pass it as search anchorTime: results then rank by proximity to this time instead of now, without excluding anything. When content names people, organizations, tools, places, events, or key concepts, you (the caller) must extract and pass both entities and relationships \u2014 the server does not auto-extract them. Edges matter as much as nodes: without relationships the graph cannot connect related memories. Use file ingest for documents/images worth persisting; images require a description.`;
 
 // src/mcp/sampling.ts
 function createSamplingClient(server) {
@@ -910,17 +910,62 @@ var ingestMemoryFileTool = {
   }
 };
 
-// src/mcp/tools/list.ts
+// src/mcp/tools/lineage.ts
 import { z as z6 } from "zod";
 var inputShape4 = {
-  mode: z6.enum(["entries", "log"]).optional().describe(
+  subject: z6.string().optional().describe("Graph subject to trace, used with relation for graph lineage."),
+  relation: z6.string().optional().describe("Graph relation to trace for the subject."),
+  entryId: z6.string().optional().describe("Memory entry id to trace through its supersededBy chain."),
+  asOf: z6.string().optional().describe("Only include lineage versions ingested by this ISO-8601 time."),
+  eventTimeStart: z6.string().optional().describe("Inclusive event-time start (ISO-8601)."),
+  eventTimeEnd: z6.string().optional().describe("Inclusive event-time end (ISO-8601)."),
+  beforeValue: z6.string().optional().describe("Stop before the lineage version with this value."),
+  limit: z6.number().int().positive().optional().describe("Maximum lineage versions to return."),
+  ...scopeShape
+};
+var lineageTool = {
+  name: "lineage",
+  config: {
+    title: "Trace pyx-memory fact lineage",
+    description: "Return the time-ordered history of how a fact evolved: subject+relation traces graph lineage, entryId traces a supersededBy chain. Use for questions like what did X use before Y or how did this fact evolve.",
+    inputSchema: inputShape4,
+    annotations: { readOnlyHint: true, openWorldHint: true }
+  },
+  handler: (deps) => async (raw) => {
+    const args = raw;
+    const creds = await deps.readCredentials();
+    if (!creds.ok) return creds.result;
+    const http = createHttpClient(creds.credentials, deps.fetchImpl);
+    const res = await http.requestJson({
+      method: "GET",
+      path: "/api/memory/lineage",
+      query: {
+        subject: args.subject,
+        relation: args.relation,
+        entryId: args.entryId,
+        asOf: args.asOf,
+        eventTimeStart: args.eventTimeStart,
+        eventTimeEnd: args.eventTimeEnd,
+        beforeValue: args.beforeValue,
+        limit: args.limit
+      },
+      scope: args
+    });
+    return res.ok ? mcpJson(res.data) : res.result;
+  }
+};
+
+// src/mcp/tools/list.ts
+import { z as z7 } from "zod";
+var inputShape5 = {
+  mode: z7.enum(["entries", "log"]).optional().describe(
     "Listing mode. `entries` (default) returns paginated entries by filter; `log` returns the chronological memory log."
   ),
-  page: z6.number().int().min(1).optional().describe("1-based page index for entries mode."),
-  limit: z6.number().int().min(1).max(200).optional().describe("Page size; server clamps."),
-  type: z6.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
-  agentId: z6.string().optional().describe("Filter to memories from this agentId."),
-  since: z6.string().optional().describe("ISO-8601 lower bound for log mode."),
+  page: z7.number().int().min(1).optional().describe("1-based page index for entries mode."),
+  limit: z7.number().int().min(1).max(200).optional().describe("Page size; server clamps."),
+  type: z7.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
+  agentId: z7.string().optional().describe("Filter to memories from this agentId."),
+  since: z7.string().optional().describe("ISO-8601 lower bound for log mode."),
   ...scopeShape
 };
 var listMemoriesTool = {
@@ -928,7 +973,7 @@ var listMemoriesTool = {
   config: {
     title: "List pyx-memory",
     description: "List recent memory entries or a chronological memory log. Same tool for both reads \u2014 `mode` controls which.",
-    inputSchema: inputShape4,
+    inputSchema: inputShape5,
     annotations: { readOnlyHint: true, openWorldHint: true }
   },
   handler: (deps) => async (raw) => {
@@ -955,9 +1000,9 @@ var listMemoriesTool = {
 };
 
 // src/mcp/tools/profile.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var getInputShape = {
-  namespaceId: z7.string().min(1).describe("Namespace id whose user-profile to fetch."),
+  namespaceId: z8.string().min(1).describe("Namespace id whose user-profile to fetch."),
   ...scopeShape
 };
 var getUserProfileTool = {
@@ -983,8 +1028,8 @@ var getUserProfileTool = {
   }
 };
 var upsertInputShape = {
-  namespaceId: z7.string().min(1).describe("Namespace id to upsert the user-profile into."),
-  content: z7.string().min(1).describe("Full freeform profile content (UTF-8, \u22648192 bytes; server enforces the cap)."),
+  namespaceId: z8.string().min(1).describe("Namespace id to upsert the user-profile into."),
+  content: z8.string().min(1).describe("Full freeform profile content (UTF-8, \u22648192 bytes; server enforces the cap)."),
   ...scopeShape
 };
 var upsertUserProfileTool = {
@@ -1010,21 +1055,57 @@ var upsertUserProfileTool = {
   }
 };
 
+// src/mcp/tools/reinforce.ts
+import { z as z9 } from "zod";
+var inputShape6 = {
+  entryIds: z9.array(z9.string().min(1)).min(1).describe("Memory entry ids that were actually used."),
+  signal: z9.enum(["context_included", "cited", "explicit_positive"]).describe("Reinforcement signal: context_included < cited < explicit_positive."),
+  at: z9.union([z9.string(), z9.number()]).optional().describe("Recall time as epoch-ms or full ISO-8601 timestamp with timezone."),
+  ...scopeShape
+};
+var reinforceTool = {
+  name: "reinforce",
+  config: {
+    title: "Reinforce used pyx-memory entries",
+    description: "Reinforce memories the agent actually USED (recall reinforces \u2014 raises strength so they surface in quick/medium effort tiers). signal: context_included < cited < explicit_positive.",
+    inputSchema: inputShape6,
+    annotations: { readOnlyHint: false, openWorldHint: true }
+  },
+  handler: (deps) => async (raw) => {
+    const args = raw;
+    const creds = await deps.readCredentials();
+    if (!creds.ok) return creds.result;
+    const http = createHttpClient(creds.credentials, deps.fetchImpl);
+    const res = await http.requestJson({
+      method: "POST",
+      path: "/api/memory/reinforce",
+      body: { entryIds: args.entryIds, signal: args.signal, at: args.at },
+      scope: args
+    });
+    return res.ok ? mcpJson(res.data) : res.result;
+  }
+};
+
 // src/mcp/tools/search.ts
-import { z as z8 } from "zod";
-var inputShape5 = {
-  query: z8.string().min(1).describe("Required natural-language search text."),
-  limit: z8.number().int().min(1).max(100).optional().describe("Maximum results; server clamps to 1\u2013100. Default 10."),
-  strategy: z8.enum(["naive", "graph", "hybrid"]).optional().describe(
+import { z as z10 } from "zod";
+var inputShape7 = {
+  query: z10.string().min(1).describe("Required natural-language search text."),
+  limit: z10.number().int().min(1).max(100).optional().describe(
+    'Target result count; server clamps to 1\u2013100. Default 10. The hybrid strategy may widen enumeration/count queries ("how many \u2026", "list all/every \u2026") up to 30 for set-completeness recall.'
+  ),
+  strategy: z10.enum(["naive", "graph", "hybrid"]).optional().describe(
     "RAG strategy. Defaults to `hybrid` (cross-encoder reranking, multi-entity decomposition, confidence scoring) and is sent explicitly when omitted; pass `naive` for a lighter vector-only search or `graph` for graph-augmented retrieval."
   ),
-  type: z8.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
-  agentId: z8.string().optional().describe("Filter to memories stored for this agentId."),
-  abstentionThreshold: z8.number().min(0).max(1).optional().describe("Enable confidence scoring; abstain when confidence falls below this value (0\u20131)."),
-  eventTimeStart: z8.string().optional().describe("Inclusive event-time start (ISO-8601); must be paired with eventTimeEnd."),
-  eventTimeEnd: z8.string().optional().describe("Inclusive event-time end (ISO-8601); must be paired with eventTimeStart."),
-  asOf: z8.string().optional().describe("Only include memories ingested before this ISO-8601 timestamp."),
-  anchorTime: z8.string().optional().describe(
+  effort: z10.enum(["quick", "medium", "deep"]).optional().describe(
+    "Retrieval depth: quick=strongest, medium=default-depth, deep=everything including archived/superseded."
+  ),
+  type: z10.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
+  agentId: z10.string().optional().describe("Filter to memories stored for this agentId."),
+  abstentionThreshold: z10.number().min(0).max(1).optional().describe("Enable confidence scoring; abstain when confidence falls below this value (0\u20131)."),
+  eventTimeStart: z10.string().optional().describe("Inclusive event-time start (ISO-8601); must be paired with eventTimeEnd."),
+  eventTimeEnd: z10.string().optional().describe("Inclusive event-time end (ISO-8601); must be paired with eventTimeStart."),
+  asOf: z10.string().optional().describe("Only include memories ingested before this ISO-8601 timestamp."),
+  anchorTime: z10.string().optional().describe(
     'Soft recency ANCHOR (ISO-8601) \u2014 ranks results by proximity to this time instead of now; never excludes anything. When the question names a relative time ("two months ago", "last year", "3\uB144 \uC804"), resolve it against the current date yourself and pass the absolute timestamp here; prefer this over eventTimeStart/End unless a strict window is required, because hard filters drop last-known-before facts.'
   ),
   ...scopeShape
@@ -1034,7 +1115,7 @@ var searchMemoriesTool = {
   config: {
     title: "Search pyx-memory",
     description: "Search durable pyx-memory entries with hybrid/vector/keyword/graph strategy, tenant scope, sensitivity access, and optional confidence/abstention.",
-    inputSchema: inputShape5,
+    inputSchema: inputShape7,
     annotations: { readOnlyHint: true, openWorldHint: true }
   },
   handler: (deps) => async (raw) => {
@@ -1053,6 +1134,7 @@ var searchMemoriesTool = {
         // `naive` (1–2 results vs hybrid's 15–20) — sending it explicitly makes
         // recall deterministic regardless of the instance version.
         strategy: args.strategy ?? "hybrid",
+        effort: args.effort,
         type: args.type,
         agentId: args.agentId,
         abstentionThreshold: args.abstentionThreshold,
@@ -1068,13 +1150,13 @@ var searchMemoriesTool = {
 };
 
 // src/mcp/tools/status.ts
-var inputShape6 = {};
+var inputShape8 = {};
 var statusTool = {
   name: "status",
   config: {
     title: "Get pyx-memory topology",
     description: "Fetch the running pyx-memory server topology from GET /status when available. Hosted gateways that expose /health but not /status return an explicit topologyUnavailable result with the health payload.",
-    inputSchema: inputShape6,
+    inputSchema: inputShape8,
     annotations: { readOnlyHint: true, openWorldHint: true }
   },
   handler: (deps) => async () => {
@@ -1097,10 +1179,10 @@ var statusTool = {
 };
 
 // src/mcp/tools/store.ts
-import { z as z10 } from "zod";
+import { z as z12 } from "zod";
 
 // src/mcp/extraction-prompt.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 var ENTITY_TYPES = ["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"];
 var RELATION_TYPES = [
   "USES",
@@ -1113,18 +1195,18 @@ var RELATION_TYPES = [
   "WORKS_AT",
   "LOCATED_IN"
 ];
-var ExtractionSchema = z9.object({
-  entities: z9.array(
-    z9.object({
-      name: z9.string().min(1),
-      type: z9.string().min(1).transform((value) => normalizeGraphLabel(value, "CONCEPT"))
+var ExtractionSchema = z11.object({
+  entities: z11.array(
+    z11.object({
+      name: z11.string().min(1),
+      type: z11.string().min(1).transform((value) => normalizeGraphLabel(value, "CONCEPT"))
     })
   ),
-  relations: z9.array(
-    z9.object({
-      source: z9.string().min(1),
-      target: z9.string().min(1),
-      type: z9.string().min(1).transform((value) => normalizeGraphLabel(value, "RELATED_TO"))
+  relations: z11.array(
+    z11.object({
+      source: z11.string().min(1),
+      target: z11.string().min(1),
+      type: z11.string().min(1).transform((value) => normalizeGraphLabel(value, "RELATED_TO"))
     })
   )
 });
@@ -1170,40 +1252,40 @@ var relationshipTypes = [
   "LOCATED_IN"
 ];
 var storeTargets = ["sqlite", "vector", "graph"];
-var inputShape7 = {
-  content: z10.string().min(1).describe("Concise factual statement to persist; decision, not deliberation."),
-  topic: z10.string().min(1).describe("Required metadata.topic for retrieval grouping."),
-  project: z10.string().min(1).describe("Required metadata.project namespace."),
-  type: z10.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Memory type. Default long-term."),
-  targets: z10.array(z10.enum(storeTargets)).optional().describe(
+var inputShape9 = {
+  content: z12.string().min(1).describe("Concise factual statement to persist; decision, not deliberation."),
+  topic: z12.string().min(1).describe("Required metadata.topic for retrieval grouping."),
+  project: z12.string().min(1).describe("Required metadata.project namespace."),
+  type: z12.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Memory type. Default long-term."),
+  targets: z12.array(z12.enum(storeTargets)).optional().describe(
     "Storage targets. Include 'graph' when you provide entities/relationships or want zero graph write counts reported."
   ),
-  importance: z10.number().int().min(1).max(10).optional().describe("Importance 1\u201310."),
-  eventTime: z10.string().optional().describe(
+  importance: z12.number().int().min(1).max(10).optional().describe("Importance 1\u201310."),
+  eventTime: z12.string().optional().describe(
     'ISO-8601 time the fact happened or took effect (bi-temporal). Pass for any fact that can change or go stale \u2014 recency ordering, dated ("as of") queries, and stale-vs-current conflict resolution key off it.'
   ),
-  source: z10.string().optional().describe("Free-form origin (filename, URL, conversation id)."),
-  agentId: z10.string().optional().describe("Agent identifier stored alongside the entry."),
-  sessionId: z10.string().optional().describe("Session identifier for grouping."),
-  parentId: z10.string().optional().describe("Parent memory entry id (hierarchical)."),
-  entities: z10.array(
-    z10.object({
-      name: z10.string().min(1).describe("Entity name as referenced in content."),
-      type: z10.enum(entityTypes).describe("Entity type.")
+  source: z12.string().optional().describe("Free-form origin (filename, URL, conversation id)."),
+  agentId: z12.string().optional().describe("Agent identifier stored alongside the entry."),
+  sessionId: z12.string().optional().describe("Session identifier for grouping."),
+  parentId: z12.string().optional().describe("Parent memory entry id (hierarchical)."),
+  entities: z12.array(
+    z12.object({
+      name: z12.string().min(1).describe("Entity name as referenced in content."),
+      type: z12.enum(entityTypes).describe("Entity type.")
     })
   ).optional().describe(
     "Named entities mentioned by the content. The caller LLM must extract and pass these when the content names people, organizations, tools, places, events, or key concepts; the server does not auto-extract them."
   ),
-  relationships: z10.array(
-    z10.object({
-      source: z10.string().min(1).describe("Source entity name (must appear in entities array)."),
-      target: z10.string().min(1).describe("Target entity name (must appear in entities array)."),
-      type: z10.enum(relationshipTypes).describe("Relationship type.")
+  relationships: z12.array(
+    z12.object({
+      source: z12.string().min(1).describe("Source entity name (must appear in entities array)."),
+      target: z12.string().min(1).describe("Target entity name (must appear in entities array)."),
+      type: z12.enum(relationshipTypes).describe("Relationship type.")
     })
   ).optional().describe(
     "Edges between entities; source and target must be entity names from this request. Relationships matter as much as entities because graph traversal needs edges to connect related memories."
   ),
-  extractEntities: z10.boolean().optional().describe(
+  extractEntities: z12.boolean().optional().describe(
     "Override extraction: false skips caller-side extraction; true requires caller entities or MCP sampling and errors loudly if neither is available."
   ),
   ...scopeShape
@@ -1213,7 +1295,7 @@ var storeMemoryTool = {
   config: {
     title: "Store pyx-memory entry",
     description: "Store one concise factual memory with required topic and project metadata. When content names people, organizations, tools, places, events, or key concepts, the caller LLM must extract and pass entities and relationships; the server does not auto-extract them. Relationships (edges) matter as much as entities because graph traversal needs edges to connect related memories. Entity-free memories are valid; omit graph data or set extractEntities:false when there are no graph facts.",
-    inputSchema: inputShape7,
+    inputSchema: inputShape9,
     annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
   },
   handler: (deps) => async (raw, ctx) => {
@@ -1273,13 +1355,13 @@ var storeMemoryTool = {
 };
 
 // src/mcp/tools/summarize.ts
-import { z as z11 } from "zod";
-var inputShape8 = {
-  entityName: z11.string().min(1).describe(
+import { z as z13 } from "zod";
+var inputShape10 = {
+  entityName: z13.string().min(1).describe(
     "Entity name to synthesize a profile for (PERSON, ORG, CONCEPT, TOOL, LOCATION, EVENT)."
   ),
-  entityType: z11.enum(["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"]).optional().describe("Optional explicit entity type when the same name spans multiple categories."),
-  refresh: z11.boolean().optional().describe(
+  entityType: z13.enum(["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"]).optional().describe("Optional explicit entity type when the same name spans multiple categories."),
+  refresh: z13.boolean().optional().describe(
     "Default false: fetch the existing synthesis. true: rebuild the synthesis from current memory (POST)."
   ),
   ...scopeShape
@@ -1289,7 +1371,7 @@ var summarizeMemoryEntityTool = {
   config: {
     title: "Synthesize pyx-memory entity",
     description: "Fetch or refresh a reusable synthesis/profile for an entity (person, customer, project, tool, organization). Default fetches existing; set refresh:true to rebuild.",
-    inputSchema: inputShape8,
+    inputSchema: inputShape10,
     annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true }
   },
   handler: (deps) => async (raw) => {
@@ -1321,6 +1403,8 @@ var ALL_TOOLS = [
   searchMemoriesTool,
   storeMemoryTool,
   getMemoryTool,
+  lineageTool,
+  reinforceTool,
   listMemoriesTool,
   deleteMemoryTool,
   ingestMemoryFileTool,
@@ -1336,7 +1420,7 @@ var ALL_TOOL_NAMES = ALL_TOOLS.map((t) => t.name);
 // src/mcp/server.ts
 async function runMcpServer(opts) {
   const fetchImpl = opts.fetchImpl ?? fetch;
-  const version = opts.version ?? (true ? "0.37.0" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "0.38.0" : "0.0.0-dev");
   const server = new McpServer(
     { name: "pyx-memory", version },
     { instructions: PYX_MEMORY_INSTRUCTIONS, capabilities: { tools: {} } }

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-DEMDFWI4.mjs";
-import "./chunk-EXUSQ2GR.mjs";
+} from "./chunk-TDPGRIJW.mjs";
+import "./chunk-CK7VUON3.mjs";
 import "./chunk-KSTI4M52.mjs";
 export {
   DashboardClient,

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, 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, 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 {
@@ -83,6 +83,10 @@ interface MemoryInterface {
     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[]>;
+    /** 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. */
+    reinforce(params: ReinforceParams$1): Promise<ReinforceResult$1>;
     /** Query entries by event time range (when things actually happened). */
     queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
     shutdown(): Promise<void>;
@@ -354,6 +358,8 @@ declare class MemoryClient implements ExtendedMemoryInterface {
         dryRun: boolean;
     }>;
     queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    lineage(params: LineageParams$1): Promise<LineageResult$1>;
+    reinforce(params: ReinforceParams$1): Promise<ReinforceResult$1>;
     log(filters?: MemoryLogFilters): Promise<MemoryEntry$1[]>;
     queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
     summarizeEntity(name: string): Promise<MemoryEntry$1>;
@@ -543,6 +549,22 @@ interface MemoryEntry {
      * file-catalog row pointed at by another service's foreign key).
      */
     pinned?: boolean;
+    /**
+     * Lifecycle status (H8). `'active'` (or absent — back-compat default) is a
+     * normal retrievable entry. `'superseded'` means a newer near-duplicate
+     * UPDATE replaced this one during consolidation. `'archived'` (1b) means decay
+     * retired it (no successor) — kept, strength 0, `deep`-tier only. All three
+     * are kept (history / lineage / deep recall) but `superseded`/`archived` are
+     * excluded from default/quick/medium search. Only `forget()` and exact-byte-
+     * duplicate collapse hard-delete. See `docs/H8-MEMORY-MODEL-DESIGN.md`.
+     */
+    status?: 'active' | 'superseded' | 'archived';
+    /**
+     * When `status==='superseded'`, the id of the newer entry that replaced this
+     * one — the backward link used by `Memory.lineage()` chain traversal. Cleared
+     * to NULL (never resurrected to active) if the successor is later forgotten.
+     */
+    supersededByEntryId?: string;
 }
 interface MemorySearchParams {
     query: string;
@@ -601,6 +623,16 @@ interface MemorySearchParams {
      * index drift. Default true (access tracking is the product's usage signal).
      */
     trackAccess?: boolean;
+    /**
+     * Retrieval EFFORT tier (H8 slice 1b) — admits candidates by activation
+     * strength BEFORE RRF fusion (like LLM thinking-mode depth): `quick` = the
+     * strongest (sharpest top), `medium` = strong+mid, `deep` = everything
+     * including cold + superseded + archived rows. **Omitted ⇒ byte-identical to
+     * pre-1b behavior** (no activation lookup; all rows admitted, superseded/
+     * archived hidden as in 1a). Strength rises only via `Memory.reinforce` (recall
+     * 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. */
     maxSensitivity?: SensitivityLevel;
     /** Tenant ID for multi-tenant isolation. */
@@ -663,6 +695,65 @@ interface MemorySearchResult {
         };
     };
 }
+/** One version in a fact's history, as returned by {@link LineageResult}. */
+interface LineageVersion {
+    entryId: string;
+    /** The entry content carrying this version's value. */
+    value: string;
+    eventTime?: string;
+    ingestTime?: string;
+    status: 'active' | 'superseded' | 'archived';
+    /** Set when this version was superseded by a newer entry. */
+    supersededByEntryId?: string;
+}
+/**
+ * Query for the evolution of a fact (H8 `Memory.lineage`). Provide either a
+ * `subject` (+ optional `relation`) for graph-backed subject/relation lineage,
+ * OR an `entryId` to walk the `supersededBy` chain (the only mode available
+ * without a graph store).
+ */
+interface LineageParams {
+    subject?: string;
+    relation?: string;
+    entryId?: string;
+    /** Current version as of this time (newest version with eventTime ≤ asOf). */
+    asOf?: string;
+    eventTimeRange?: [string, string];
+    /** Return only versions strictly older than the version holding this value. */
+    beforeValue?: string;
+    limit?: number;
+}
+interface LineageResult {
+    subject?: string;
+    relation?: string;
+    /** Event-time ascending (oldest → newest). */
+    versions: LineageVersion[];
+    /** Which path answered — honest provenance (graph conflict-group vs supersededBy chain). */
+    source: 'graph' | 'chain';
+}
+/**
+ * Explicit recall-usefulness signal for {@link MemorySearchParams} `reinforce`.
+ * `context_included` = surfaced into the working context (small η); `cited` =
+ * the agent actually used it in its answer (medium η); `explicit_positive` =
+ * user/agent marked it useful (large η). Mere top-k return is NOT a signal
+ * (determinism + "returned ≠ used") — only an explicit `reinforce()` call moves
+ * strength.
+ */
+type ReinforceSignal = 'context_included' | 'cited' | 'explicit_positive';
+interface ReinforceParams {
+    entryIds: string[];
+    signal: ReinforceSignal;
+    /** When the recall happened — epoch-ms, or full ISO-8601 WITH timezone. Date-only / tz-free is rejected. Defaults to the activation clock. */
+    at?: string | number;
+}
+interface ReinforceResult {
+    /** Per-entry post-reinforce activation. Entries absent from the store are omitted. */
+    updated: Array<{
+        entryId: string;
+        strength: number;
+        tier: 'quick' | 'medium' | 'deep';
+    }>;
+}
 interface SourceEvidence {
     /** Memory entry that produced this graph fact. */
     memoryEntryId: string;
@@ -1254,4 +1345,4 @@ 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, 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, SINGLE_TENANT_ID, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyServiceVariant, VectorProvider, type WikiLintReport, mergeExtractedEntities, normalizeGraphLabel };
+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 };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-EXUSQ2GR.mjs";
+} from "./chunk-CK7VUON3.mjs";
 import {
   DEFAULTS,
   DEPRECATED_RAG_STRATEGIES,

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-DEMDFWI4.mjs";
-import "./chunk-EXUSQ2GR.mjs";
+} from "./chunk-TDPGRIJW.mjs";
+import "./chunk-CK7VUON3.mjs";
 import "./chunk-KSTI4M52.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts

package/package.json

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