claude-memory-layer 1.0.46 → 1.0.48

package/dist/mcp/index.js

@@ -10410,6 +10410,11 @@ var tools = [
           enum: ["off", "safe", "aggressive"],
           description: "Optional context-pack compression mode. safe preserves source refs and high-signal errors/log lines; aggressive is more compact."
         },
+        retrievalMode: {
+          type: "string",
+          enum: ["session-event-hybrid", "event"],
+          description: "Optional production context-pack retrieval mode. Defaults to session-event-hybrid (session-event hybrid), which rescues query-relevant sibling events from sessions already hit by direct retrieval. Use event for exact event-only debugging."
+        },
         maxChars: {
           type: "number",
           minimum: 1e3,
@@ -10567,6 +10572,16 @@ var tools = [
           type: "number",
           description: "Maximum recent events to scan for ID resolution (default: 10000, max: 50000)"
         },
+        includeNeighbors: {
+          type: "boolean",
+          description: "When true, include privacy-safe neighbor events from the same session around each resolved source reference."
+        },
+        neighborWindow: {
+          type: "number",
+          minimum: 0,
+          maximum: 5,
+          description: "Number of before/after session neighbor events to include when includeNeighbors is true (default: 1, max: 5)."
+        },
         projectPath: projectPathProperty
       },
       required: ["ids"]
@@ -13647,6 +13662,7 @@ var VectorOutbox = class {
 // src/core/retrieval-debug-lanes.ts
 var RETRIEVAL_DEBUG_LANE_NAMES = [
   "raw_event",
+  "session_event",
   "session_summary",
   "graph_path",
   "facet_match"
@@ -21501,6 +21517,7 @@ var Retriever = class {
   }
   async retrieve(query, options = {}) {
     const opts = { ...DEFAULT_OPTIONS, ...options };
+    const retrievalMode = options.retrievalMode ?? ((options.strategy ?? DEFAULT_OPTIONS.strategy) === "auto" ? "session-event-hybrid" : "event");
     const sessionFilter = opts.scope?.sessionId ?? opts.sessionId;
     const fallbackTrace = [];
     const qualityQuery = buildRetrievalQualityQuery(query);
@@ -21531,6 +21548,7 @@ var Retriever = class {
       decayPolicy: opts.decayPolicy,
       intentRewrite: opts.intentRewrite === true,
       graphHop: opts.graphHop,
+      retrievalMode,
       projectScopeMode: opts.projectScopeMode,
       projectHash: opts.projectHash,
       allowedProjectHashes: opts.allowedProjectHashes,
@@ -21549,6 +21567,7 @@ var Retriever = class {
         rerankWeights: opts.rerankWeights,
         decayPolicy: opts.decayPolicy,
         graphHop: opts.graphHop,
+        retrievalMode,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
         allowedProjectHashes: opts.allowedProjectHashes,
@@ -21568,6 +21587,7 @@ var Retriever = class {
         rerankWeights: opts.rerankWeights,
         decayPolicy: opts.decayPolicy,
         graphHop: opts.graphHop,
+        retrievalMode,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
         allowedProjectHashes: opts.allowedProjectHashes,
@@ -21588,10 +21608,26 @@ var Retriever = class {
         query,
         minScore: opts.minScore
       });
+      const expandedSummary = retrievalMode === "session-event-hybrid" ? await this.expandSessionEventHybrid(filteredSummary, {
+        query: qualityQuery,
+        currentStateQuery: query,
+        limit: opts.topK * 4
+      }) : filteredSummary;
+      const scopedExpandedSummary = retrievalMode === "session-event-hybrid" ? await this.applyScopeFilters(expandedSummary, {
+        scope: opts.scope,
+        projectScopeMode: opts.projectScopeMode,
+        projectHash: opts.projectHash,
+        allowedProjectHashes: opts.allowedProjectHashes,
+        facets: opts.facets
+      }) : expandedSummary;
+      const finalSummary = retrievalMode === "session-event-hybrid" ? this.applyQualityFilters(scopedExpandedSummary, {
+        query,
+        minScore: opts.minScore
+      }) : scopedExpandedSummary;
       current = {
-        results: filteredSummary,
-        candidateResults: filteredSummary,
-        matchResult: this.matcher.matchSearchResults(filteredSummary, () => 0)
+        results: finalSummary,
+        candidateResults: finalSummary,
+        matchResult: this.matcher.matchSearchResults(finalSummary, () => 0)
       };
       fallbackTrace.push("fallback:summary");
     }
@@ -21677,13 +21713,18 @@ var Retriever = class {
         initialResults = this.mergeResults(initialResults, rewrittenResults, input.topK * 3);
       }
     }
-    const expandedResults = input.graphHop?.enabled === false ? initialResults : await this.expandGraphHops(initialResults, {
+    const graphExpandedResults = input.graphHop?.enabled === false ? initialResults : await this.expandGraphHops(initialResults, {
       query,
       queryGraphEnabled: this.queryGraphExpansionEnabled,
       maxHops: clampGraphHops(input.graphHop?.maxHops ?? 1),
       hopPenalty: Math.max(0, input.graphHop?.hopPenalty ?? 0.08),
       limit: input.topK * 4
     });
+    const expandedResults = input.retrievalMode === "session-event-hybrid" ? await this.expandSessionEventHybrid(graphExpandedResults, {
+      query: rerankQuery,
+      currentStateQuery: query,
+      limit: input.topK * 4
+    }) : graphExpandedResults;
     const rerankedResults = input.rerankWithKeyword ? this.rerankByKeywordOverlap(expandedResults, rerankQuery, input.rerankWeights, input.decayPolicy) : expandedResults;
     const filtered = await this.applyScopeFilters(rerankedResults, {
       scope: input.scope,
@@ -21731,6 +21772,47 @@ var Retriever = class {
     }
     return [...byId.values()].sort((a, b) => b.score - a.score).slice(0, limit);
   }
+  async expandSessionEventHybrid(seeds, opts) {
+    if (seeds.length === 0 || opts.limit <= seeds.length) return seeds;
+    const queryTokens = this.tokenize(opts.query);
+    if (queryTokens.length === 0) return seeds;
+    const byId = /* @__PURE__ */ new Map();
+    for (const seed of seeds) byId.set(seed.eventId, seed);
+    const bestSeedBySession = /* @__PURE__ */ new Map();
+    for (const seed of [...seeds].sort((a, b) => b.score - a.score || compareStable(a.eventId, b.eventId))) {
+      if (!seed.sessionId || bestSeedBySession.has(seed.sessionId)) continue;
+      bestSeedBySession.set(seed.sessionId, seed);
+    }
+    const suppressStaleState = isCurrentStateQuery(opts.currentStateQuery);
+    for (const [sessionId, seed] of bestSeedBySession) {
+      const sessionEvents = await this.eventStore.getSessionEvents(sessionId);
+      for (const event of [...sessionEvents].sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime())) {
+        if (byId.has(event.id)) continue;
+        if (isLowSignalContextContent(event.content)) continue;
+        if (suppressStaleState && isStaleOrSupersededContent(event.content)) continue;
+        const lexicalScore = this.keywordOverlap(queryTokens, this.tokenize(event.content));
+        if (lexicalScore <= 0) continue;
+        if (shouldApplyTechnicalGuard(opts.query) && !hasTechnicalTermOverlap(opts.query, event.content)) continue;
+        const score = Math.min(0.95, Math.max(0.35, seed.score * 0.72 + lexicalScore * 0.28));
+        const row = withRetrievalLane({
+          id: `session-event-${seed.eventId}-${event.id}`,
+          eventId: event.id,
+          content: event.content,
+          score,
+          sessionId: event.sessionId,
+          eventType: event.eventType,
+          timestamp: event.timestamp.toISOString(),
+          semanticScore: seed.semanticScore ?? seed.score,
+          lexicalScore,
+          recencyScore: seed.recencyScore
+        }, { lane: "session_event", reason: `same_session:${seed.eventId}`, score });
+        byId.set(row.eventId, row);
+        if (byId.size >= opts.limit) break;
+      }
+      if (byId.size >= opts.limit) break;
+    }
+    return [...byId.values()].sort((a, b) => b.score - a.score || compareStable(a.eventId, b.eventId)).slice(0, opts.limit);
+  }
   async expandGraphHops(seeds, opts) {
     const byId = /* @__PURE__ */ new Map();
     for (const s of seeds) byId.set(s.eventId, s);
@@ -27858,11 +27940,13 @@ var SEMANTIC_VECTOR_FALLBACK_FAILED_WARNING = "Warning: semantic/vector retrieva
 async function retrieveMcpMemories(memoryService, query, options) {
   const fetchTopK = Math.max(options.topK, options.fetchTopK ?? options.topK);
   try {
-    const result2 = await memoryService.retrieveMemories(query, {
+    const retrieveOptions = {
       topK: fetchTopK,
       sessionId: options.sessionId,
-      recordTrace: false
-    });
+      recordTrace: false,
+      ...options.retrievalMode ? { retrievalMode: options.retrievalMode } : {}
+    };
+    const result2 = await memoryService.retrieveMemories(query, retrieveOptions);
     return { memories: selectMcpMemoryResults(result2.memories, options.topK, options.eventType) };
   } catch (error) {
     if (!isVectorSchemaMismatchError(error)) {
@@ -27990,6 +28074,7 @@ async function handleMemContextPack(memoryService, args) {
   const projectPath = optionalString(args.projectPath);
   const maxContextChars = contextPackMaxCharsArg(args);
   const compression = contextCompressionModeArg(args.compression, maxContextChars !== void 0);
+  const retrievalMode = contextPackRetrievalModeArg(args.retrievalMode);
   const compressionTelemetry = [];
   const formatOptions = {
     compression,
@@ -28010,7 +28095,7 @@ async function handleMemContextPack(memoryService, args) {
     sessionsDir: optionalString(args.sessionsDir),
     stateDb: optionalString(args.stateDb)
   }) : void 0;
-  const search = await retrieveMcpMemories(memoryService, query, { topK: retrievalTopK, sessionId });
+  const search = await retrieveMcpMemories(memoryService, query, { topK: retrievalTopK, sessionId, retrievalMode });
   const recentEvents = await memoryService.getRecentEvents(recentLimit);
   const timelineEvents = selectContextPackTimelineEvents(
     recentEvents,
@@ -28234,7 +28319,10 @@ async function handleMemSourceRef(memoryService, args) {
   const ids = Array.isArray(args.ids) ? args.ids.map((id) => String(id)).filter((id) => id.trim().length > 0) : [];
   const maxContentChars = numberArg(args.maxContentChars, 500, 80, 2e3);
   const lookupLimit = numberArg(args.lookupLimit, 1e4, 1, 5e4);
+  const includeNeighbors = args.includeNeighbors === true;
+  const neighborWindow = includeNeighbors ? numberArg(args.neighborWindow, 1, 0, 5) : 0;
   const recentEvents = await memoryService.getRecentEvents(lookupLimit);
+  const sessionEventCache = /* @__PURE__ */ new Map();
   const lines = ["## Source References", ""];
   if (ids.length === 0) {
     lines.push("No IDs supplied.", "");
@@ -28262,6 +28350,19 @@ async function handleMemSourceRef(memoryService, args) {
     }
     lines.push("- Redacted Preview:");
     lines.push(`  > ${safeInline(event.content, maxContentChars)}`);
+    if (neighborWindow > 0) {
+      try {
+        let sessionEventsPromise = sessionEventCache.get(event.sessionId);
+        if (!sessionEventsPromise) {
+          sessionEventsPromise = memoryService.getSessionHistory(event.sessionId);
+          sessionEventCache.set(event.sessionId, sessionEventsPromise);
+        }
+        const sessionEvents = await sessionEventsPromise;
+        appendSourceRefNeighborContext(lines, event, sessionEvents, neighborWindow, maxContentChars);
+      } catch {
+        lines.push("- Neighbor Context: unavailable (details suppressed)");
+      }
+    }
     lines.push("");
   }
   return textResult(lines.join("\n"));
@@ -28491,6 +28592,31 @@ function sourceTypeForEvent(event) {
   if (typeof event.metadata?.transcriptPath === "string") return "transcript";
   return "raw_event";
 }
+function appendSourceRefNeighborContext(lines, event, sessionEvents, neighborWindow, maxContentChars) {
+  const sorted = sessionEvents.slice().sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime() || a.id.localeCompare(b.id));
+  const targetIndex = sorted.findIndex((candidate) => candidate.id === event.id);
+  lines.push("- Neighbor Context:");
+  if (targetIndex < 0) {
+    lines.push("  - unavailable (source event not found in session history)");
+    return;
+  }
+  const start = Math.max(0, targetIndex - neighborWindow);
+  const end = Math.min(sorted.length, targetIndex + neighborWindow + 1);
+  const neighbors = sorted.map((candidate, index) => ({ event: candidate, index })).slice(start, end).filter((candidate) => candidate.event.id !== event.id);
+  if (neighbors.length === 0) {
+    lines.push("  - none within requested window");
+    return;
+  }
+  const previewChars = Math.max(80, Math.min(maxContentChars, 300));
+  for (const neighbor of neighbors) {
+    const direction = neighbor.index < targetIndex ? "before" : "after";
+    const citationId = generateCitationId(neighbor.event.id);
+    lines.push(
+      `  - ${direction} [mem:${citationId}] sourceRef=event:${neighbor.event.id} type=${neighbor.event.eventType} timestamp=${neighbor.event.timestamp.toISOString()}`
+    );
+    lines.push(`    > ${safeInline(neighbor.event.content, previewChars)}`);
+  }
+}
 function formatRelevantMemoryLine(event, score, index, formatOptions = DEFAULT_CONTEXT_PACK_FORMAT_OPTIONS) {
   const citationId = generateCitationId(event.id);
   const previewBudget = formatOptions.compression === "off" ? 260 : 180;
@@ -28614,9 +28740,17 @@ function contextCompressionModeArg(value, hasBudget) {
   if (normalized === "off" || normalized === "safe" || normalized === "aggressive") return normalized;
   throw new Error("Invalid compression: expected off, safe, or aggressive");
 }
+function contextPackRetrievalModeArg(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === "session-event-hybrid") return "session-event-hybrid";
+  if (normalized === "event") return "event";
+  throw new Error("Invalid retrievalMode: expected session-event-hybrid or event");
+}
 function validateMemContextPackBudgetArgs(args) {
   const maxContextChars = contextPackMaxCharsArg(args);
   contextCompressionModeArg(args.compression, maxContextChars !== void 0);
+  contextPackRetrievalModeArg(args.retrievalMode);
 }
 function contextPackMaxCharsArg(args) {
   const maxChars = optionalNumberArg(args.maxChars, "maxChars", CONTEXT_PACK_MIN_HARD_BUDGET_CHARS, CONTEXT_PACK_MAX_CHARS_CAP);