claude-memory-layer 1.0.45 → 1.0.47

package/dist/mcp/index.js

@@ -10410,13 +10410,22 @@ 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",
-          description: "Maximum final context-pack characters after safe compression (default: no hard cap, max: 50000)"
+          minimum: 1e3,
+          maximum: 5e4,
+          description: "Maximum final context-pack characters after the selected compression mode and final assembly trimming (default: no hard cap, max: 50000)"
         },
         maxTokens: {
           type: "number",
-          description: "Maximum final context-pack tokens, estimated at ~4 chars/token, after safe compression (default: no hard cap)"
+          minimum: 250,
+          maximum: 12500,
+          description: "Maximum final context-pack tokens, estimated at ~4 chars/token after the selected compression mode and final assembly trimming (default: no hard cap)"
         },
         refreshLatest: {
           type: "boolean",
@@ -10563,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"]
@@ -13643,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"
@@ -21118,6 +21138,10 @@ var LOW_SIGNAL_CONTEXT_PATTERNS = [
   /<turn_aborted>/i,
   /^#\s*AGENTS\.md\s+instructions\b[\s\S]*<INSTRUCTIONS>/i,
   /^\s*(?:understood[,\s.]*)?(?:stopping|stopped|pausing|paused)\s+here\b[\s\S]{0,180}\blet\s+me\s+know\s+when\s+you(?:'d|\s+would)?\s+like\s+to\s+continue\b/i,
+  /^\s*\[?CONTEXT\s+COMPACTION\s*[—-]\s*REFERENCE\s+ONLY\]?\b[\s\S]{0,600}\b(?:earlier\s+turns\s+were\s+compacted|handoff\s+from\s+a\s+previous\s+context\s+window|active\s+task)\b/i,
+  /^\s*Summary\s+generation\s+was\s+unavailable\.\s*\d+\s+message\(s\)\s+were\s+removed\s+to\s+free\s+context\s+space\b/i,
+  /^\s*---\s*END\s+OF\s+CONTEXT\s+SUMMARY\b/i,
+  /^\s*\[Your\s+active\s+task\s+list\s+was\s+preserved\s+across\s+context\s+compression\]/i,
   /^➜\s+\S+\s+git:\([^)]*\)\s+/i,
   /^\$\s+\S+/i
 ];
@@ -21132,7 +21156,7 @@ var SHORT_REPAIR_FOLLOW_UP_PATTERNS = [
 var CURRENT_STATE_QUERY_PATTERNS = [
   /\bcurrent\b.*\b(?:state|status|deployment|blocker|pr|pull request)\b/i,
   /\b(?:still|as current|current)\b.*\b(?:unresolved|open|pending|not completed)\b/i,
-  /\b(?:old|obsolete|stale|resolved|already resolved)\b.*\b(?:current|still|unresolved|open|state|status)\b/i,
+  /\b(?:old|obsolete|stale|resolved|already resolved)\b.*\b(?:current|still|unresolved|open|status)\b/i,
   /(?:현재|아직|이전|오래된|해결된).*(?:상태|미해결|열린|블로커|PR|풀리퀘스트)/i
 ];
 var STALE_CONTENT_PATTERNS = [
@@ -21310,6 +21334,16 @@ function isShortRepairFollowUpQuery(query) {
   if (tokens.length > 8) return false;
   return SHORT_REPAIR_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
+function isLowConfidenceContextFallbackQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed) return false;
+  if (isGenericContinuationQuery(trimmed) || isShortRepairFollowUpQuery(trimmed)) return true;
+  const terms = new Set(tokenizeQualityText(trimmed));
+  if ((terms.has("compacted") || terms.has("compaction")) && terms.has("handoff")) return false;
+  const hasContinuationRecall = /^(?:continue|resume)\b/i.test(trimmed) && (terms.has("work") || terms.has("step") || terms.has("task") || terms.has("last") || terms.has("completed"));
+  const hasValidationGateRecall = terms.has("validation") && (terms.has("gate") || terms.has("check")) && (terms.has("run") || terms.has("before") || terms.has("commit") || terms.has("committing") || terms.has("change"));
+  return hasContinuationRecall || hasValidationGateRecall;
+}
 function isCurrentStateQuery(query) {
   const trimmed = query.trim();
   if (!trimmed) return false;
@@ -21483,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);
@@ -21513,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,
@@ -21531,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,
@@ -21550,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,
@@ -21570,14 +21608,37 @@ 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");
     }
-    const memories = await this.enrichResults(current.results.slice(0, opts.topK), opts);
+    const selectedResults = current.results.slice(0, opts.topK).filter((result2) => {
+      if (current.matchResult.confidence !== "none") return true;
+      if (isLowConfidenceContextFallbackQuery(query)) {
+        return (result2.semanticScore ?? result2.score) >= 0.5 || result2.score >= 0.5;
+      }
+      return (result2.semanticScore ?? result2.score) >= 0.62 || result2.score >= 0.62;
+    });
+    const memories = await this.enrichResults(selectedResults, opts, query);
     const context = this.buildContext(memories, opts.maxTokens);
     return {
       memories,
@@ -21585,7 +21646,7 @@ var Retriever = class {
       totalTokens: this.estimateTokens(context),
       context,
       fallbackTrace,
-      selectedDebug: current.results.slice(0, opts.topK).map((r) => this.debugDetailForResult(r)),
+      selectedDebug: selectedResults.map((r) => this.debugDetailForResult(r)),
       candidateDebug: (current.candidateResults || []).slice(0, Math.max(opts.topK * 3, 20)).map((r) => this.debugDetailForResult(r)),
       rawQueryText: current.queryRewriteKind ? query : void 0,
       effectiveQueryText: current.effectiveQueryText,
@@ -21652,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,
@@ -21680,6 +21746,7 @@ var Retriever = class {
     if (isCurrentStateQuery(options.query)) {
       filtered = filtered.filter((result2) => !isStaleOrSupersededContent(result2.content));
     }
+    filtered = filtered.filter((result2) => !isLowSignalContextContent(result2.content));
     filtered = filtered.filter(
       (result2) => this.isGraphPathResult(result2) || hasDiscriminativeTermOverlap(options.query, result2.content)
     );
@@ -21705,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);
@@ -22020,7 +22128,7 @@ var Retriever = class {
   async retrieveRecent(limit = 100) {
     return this.eventStore.getRecentEvents(limit);
   }
-  async enrichResults(results, options) {
+  async enrichResults(results, options, query) {
     const memories = [];
     for (const result2 of results) {
       const event = await this.eventStore.getEvent(result2.eventId);
@@ -22030,13 +22138,13 @@ var Retriever = class {
       }
       let sessionContext;
       if (options.includeSessionContext) {
-        sessionContext = await this.getSessionContext(event.sessionId, event.id);
+        sessionContext = await this.getSessionContext(event.sessionId, event.id, query);
       }
       memories.push({ event, score: result2.score, sessionContext });
     }
     return memories;
   }
-  async getSessionContext(sessionId, eventId) {
+  async getSessionContext(sessionId, eventId, query) {
     const sessionEvents = await this.eventStore.getSessionEvents(sessionId);
     const eventIndex = sessionEvents.findIndex((e) => e.id === eventId);
     if (eventIndex === -1) return void 0;
@@ -22044,7 +22152,9 @@ var Retriever = class {
     const end = Math.min(sessionEvents.length, eventIndex + 2);
     const contextEvents = sessionEvents.slice(start, end);
     if (contextEvents.length <= 1) return void 0;
-    return contextEvents.filter((e) => e.id !== eventId).map((e) => `[${e.eventType}]: ${e.content.slice(0, 200)}...`).join("\n");
+    const suppressStaleState = isCurrentStateQuery(query);
+    const contextLines = contextEvents.filter((e) => e.id !== eventId).filter((e) => !isLowSignalContextContent(e.content)).filter((e) => !(suppressStaleState && isStaleOrSupersededContent(e.content))).map((e) => `[${e.eventType}]: ${e.content.slice(0, 200)}...`);
+    return contextLines.length > 0 ? contextLines.join("\n") : void 0;
   }
   buildUnifiedContext(projectResult, sharedMemories) {
     let context = projectResult.context;
@@ -26689,10 +26799,11 @@ var ContextCompressor = class {
   compress(content, options) {
     const source = safeLabel(options.source) || "unknown";
     const mode = options.mode;
+    const sourceRef = safeSourceRef(options.sourceRef ?? sourceRefFromMetadata(options.metadata ?? {}));
     const contentType = detectContextContentType(content, options.metadata ?? {});
     const originalLines = nonEmptyLines(content).length;
     if (mode === "off") {
-      return result(content, {
+      return withSourceRefHint(result(content, {
         mode,
         source,
         contentType,
@@ -26701,21 +26812,21 @@ var ContextCompressor = class {
         originalLines,
         omittedLines: 0,
         signalCount: 0
-      });
+      }), sourceRef);
     }
     if (contentType === "log") {
-      return this.compressLog(content, mode, source, contentType);
+      return withSourceRefHint(this.compressLog(content, mode, source, contentType), sourceRef);
     }
     if (contentType === "markdown") {
-      return this.compressMarkdown(content, mode, source, contentType);
+      return withSourceRefHint(this.compressMarkdown(content, mode, source, contentType), sourceRef);
     }
     if (contentType === "diff") {
-      return this.compressDiff(content, mode, source, contentType);
+      return withSourceRefHint(this.compressDiff(content, mode, source, contentType), sourceRef);
     }
     if (contentType === "code") {
-      return this.compressCode(content, mode, source, contentType);
+      return withSourceRefHint(this.compressCode(content, mode, source, contentType), sourceRef);
     }
-    return this.compressPlain(content, mode, source, contentType);
+    return withSourceRefHint(this.compressPlain(content, mode, source, contentType), sourceRef);
   }
   compressLog(content, mode, source, contentType) {
     const lines = nonEmptyLines(content);
@@ -26853,11 +26964,15 @@ function summarizeCompressionTelemetry(metadata) {
   const totalOriginalChars = metadata.reduce((sum, item) => sum + item.originalChars, 0);
   const totalCompressedChars = metadata.reduce((sum, item) => sum + item.compressedChars, 0);
   const totalSavedChars = metadata.reduce((sum, item) => sum + item.savedChars, 0);
+  const totalOmittedLines = metadata.reduce((sum, item) => sum + item.omittedLines, 0);
+  const sourceRefsPreserved = metadata.filter((item) => item.sourceRefPreserved).length;
   return {
     totalItems: metadata.length,
     totalOriginalChars,
     totalCompressedChars,
     totalSavedChars,
+    totalOmittedLines,
+    sourceRefsPreserved,
     bySource: summarizeBy(metadata, "source"),
     byStrategy: summarizeBy(metadata, "strategy")
   };
@@ -26871,12 +26986,16 @@ function summarizeBy(metadata, key) {
       items: 0,
       originalChars: 0,
       compressedChars: 0,
-      savedChars: 0
+      savedChars: 0,
+      omittedLines: 0,
+      sourceRefsPreserved: 0
     };
     existing.items += 1;
     existing.originalChars += item.originalChars;
     existing.compressedChars += item.compressedChars;
     existing.savedChars += item.savedChars;
+    existing.omittedLines += item.omittedLines;
+    if (item.sourceRefPreserved) existing.sourceRefsPreserved += 1;
     groups.set(groupKey, existing);
   }
   return Array.from(groups.values()).sort((a, b) => String(a[key] ?? "").localeCompare(String(b[key] ?? "")));
@@ -26891,7 +27010,8 @@ function result(text, base) {
       ...base,
       compressedChars,
       savedChars,
-      compressionRatio
+      compressionRatio,
+      sourceRefPreserved: false
     }
   };
 }
@@ -26940,6 +27060,65 @@ function safeLabel(value) {
   const cleaned = value.replace(/[^A-Za-z0-9_.:-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
   return cleaned || void 0;
 }
+function sourceRefFromMetadata(metadata) {
+  const explicit = firstString(metadata, ["sourceRef", "source_ref", "sourceReference", "source_reference"]);
+  if (explicit) return explicit;
+  const citation = firstString(metadata, ["citationId", "citation_id", "memoryCitationId", "memory_citation_id"]);
+  if (citation) return citation.startsWith("mem:") ? citation : `mem:${citation}`;
+  const eventId = firstString(metadata, ["eventId", "event_id"]);
+  if (eventId) return eventId.startsWith("event:") ? eventId : `event:${eventId}`;
+  return void 0;
+}
+function firstString(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return void 0;
+}
+function safeSourceRef(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().replace(/^\[?(mem|event):/i, (_, prefix) => `${prefix.toLowerCase()}:`).replace(/\]?$/g, "");
+  if (!normalized || /(?:password|secret|api[_-]?key|token|bearer)/i.test(normalized)) return void 0;
+  const cleaned = normalized.replace(/[^A-Za-z0-9_.:-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 140);
+  return cleaned || void 0;
+}
+function withSourceRefHint(compression, sourceRef) {
+  if (!sourceRef) return compression;
+  if (compression.metadata.mode === "off" || compression.metadata.strategy === "none") {
+    return {
+      text: compression.text,
+      metadata: {
+        ...compression.metadata,
+        sourceRef,
+        sourceRefPreserved: false
+      }
+    };
+  }
+  const hint = `sourceRef=${sourceRef} expand=mem-source-ref`;
+  const text = compression.text.includes(hint) ? compression.text : addSourceRefHint(compression.text, hint);
+  const compressedChars = text.length;
+  const savedChars = Math.max(0, compression.metadata.originalChars - compressedChars);
+  const compressionRatio = compression.metadata.originalChars > 0 ? compressedChars / compression.metadata.originalChars : 1;
+  return {
+    text,
+    metadata: {
+      ...compression.metadata,
+      sourceRef,
+      sourceRefPreserved: text.includes(`sourceRef=${sourceRef}`) && text.includes("expand=mem-source-ref"),
+      compressedChars,
+      savedChars,
+      compressionRatio
+    }
+  };
+}
+function addSourceRefHint(text, hint) {
+  if (text.startsWith("[compressed ")) {
+    return text.replace(/^\[([^\]]+)\]/, `[$1; ${hint}]`);
+  }
+  return `[${hint}]
+${text}`;
+}
 
 // src/extensions/mcp/handlers.ts
 function resolveMemoryService(args) {
@@ -26977,6 +27156,9 @@ async function handleToolCall(name, args) {
     if (name === "mem-context-pack" && hasMemContextPackPerspectiveArgs(args)) {
       validateMemContextPackPerspectiveArgs(args);
     }
+    if (name === "mem-context-pack") {
+      validateMemContextPackBudgetArgs(args);
+    }
     if (MEMORY_OPERATION_TOOL_NAMES.has(name)) {
       return await handleMemoryOperationTool(name, args);
     }
@@ -27723,9 +27905,11 @@ async function handleExternalMarketContext(args) {
 }
 async function handleMemSearch(memoryService, args) {
   const query = args.query;
-  const topK = Math.min(args.topK || 5, 20);
+  const topK = numberArg(args.topK, 5, 1, 20);
+  const fetchTopK = Math.min(topK * 3, 20);
   const sessionId = args.sessionId;
-  const search = await retrieveMcpMemories(memoryService, query, { topK, sessionId });
+  const eventType = eventTypeArg(args.eventType);
+  const search = await retrieveMcpMemories(memoryService, query, { topK, fetchTopK, sessionId, eventType });
   const lines = [
     "## Memory Search Results",
     "",
@@ -27739,7 +27923,7 @@ async function handleMemSearch(memoryService, args) {
     const m = search.memories[i];
     const citationId = generateCitationId(m.event.id);
     const date = m.event.timestamp.toISOString().split("T")[0];
-    const preview = m.event.content.slice(0, 100) + (m.event.content.length > 100 ? "..." : "");
+    const preview = sanitizeOperationString(m.event.content, 100);
     lines.push(`### ${i + 1}. [mem:${citationId}] (score: ${m.score.toFixed(2)})`);
     lines.push(`**Type**: ${m.event.eventType} | **Date**: ${date}`);
     lines.push(`> ${preview}`);
@@ -27754,29 +27938,43 @@ async function handleMemSearch(memoryService, args) {
 var SEMANTIC_VECTOR_FALLBACK_WARNING = "Warning: semantic/vector retrieval unavailable; used keyword fallback.";
 var SEMANTIC_VECTOR_FALLBACK_FAILED_WARNING = "Warning: semantic/vector retrieval unavailable; keyword fallback failed.";
 async function retrieveMcpMemories(memoryService, query, options) {
+  const fetchTopK = Math.max(options.topK, options.fetchTopK ?? options.topK);
   try {
-    const result2 = await memoryService.retrieveMemories(query, {
-      topK: options.topK,
+    const retrieveOptions = {
+      topK: fetchTopK,
       sessionId: options.sessionId,
-      recordTrace: false
-    });
-    return { memories: result2.memories };
+      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)) {
       throw error;
     }
     try {
-      const memories = options.sessionId ? rankSessionKeywordMatches(
+      const candidates = options.sessionId ? rankSessionKeywordMatches(
         query,
         await memoryService.getSessionHistory(options.sessionId),
-        options.topK
-      ) : await memoryService.keywordSearch(query, { topK: options.topK });
-      return { memories, warning: SEMANTIC_VECTOR_FALLBACK_WARNING };
+        fetchTopK
+      ) : await memoryService.keywordSearch(query, { topK: fetchTopK });
+      return { memories: selectMcpMemoryResults(candidates, options.topK, options.eventType), warning: SEMANTIC_VECTOR_FALLBACK_WARNING };
     } catch {
       return { memories: [], warning: SEMANTIC_VECTOR_FALLBACK_FAILED_WARNING };
     }
   }
 }
+function selectMcpMemoryResults(memories, topK, eventType) {
+  return memories.filter((memory) => !isLowSignalContextContent(memory.event.content || "")).filter((memory) => eventType === void 0 || memory.event.eventType === eventType).slice(0, topK);
+}
+function eventTypeArg(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  const normalized = String(value).trim();
+  if (normalized === "user_prompt" || normalized === "agent_response" || normalized === "tool_observation" || normalized === "session_summary") {
+    return normalized;
+  }
+  throw new Error("Invalid eventType: expected user_prompt, agent_response, tool_observation, or session_summary");
+}
 function isVectorSchemaMismatchError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return /no vector column/i.test(message) || /query vector dimension/i.test(message) || /vector[^\n]{0,80}dimension/i.test(message) || /dimension[^\n]{0,80}vector/i.test(message) || /lancedb[^\n]{0,120}schema/i.test(message);
@@ -27812,7 +28010,7 @@ async function handleMemTimeline(memoryService, args) {
       lines.push(`Event ${targetId} not found.`);
       continue;
     }
-    const sessionEvents = recentEvents.filter((e) => e.sessionId === targetEvent.sessionId).sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    const sessionEvents = recentEvents.filter((e) => e.sessionId === targetEvent.sessionId).filter((e) => e.id === targetEvent.id || !isLowSignalContextContent(e.content || "")).sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
     const eventIndex = sessionEvents.findIndex((e) => e.id === targetEvent.id);
     const start = Math.max(0, eventIndex - windowSize);
     const end = Math.min(sessionEvents.length, eventIndex + windowSize + 1);
@@ -27823,7 +28021,8 @@ async function handleMemTimeline(memoryService, args) {
       const isTarget = e.id === targetEvent.id;
       const marker = isTarget ? "**\u2192**" : "   ";
       const time = e.timestamp.toLocaleTimeString();
-      const preview = e.content.slice(0, 60) + (e.content.length > 60 ? "..." : "");
+      const lowSignal = isLowSignalContextContent(e.content || "");
+      const preview = lowSignal ? "[low-signal context artifact suppressed; use mem-details for raw source]" : sanitizeOperationString(e.content, 60);
       const citationId = generateCitationId(e.id);
       lines.push(`${marker} ${time} [${citationId}] ${e.eventType}: ${preview}`);
     }
@@ -27875,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,
@@ -27895,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,
@@ -27955,6 +28155,7 @@ async function handleMemContextPack(memoryService, args) {
   if (compression !== "off" || maxContextChars !== void 0) {
     lines.push("### Compression Notice", "");
     lines.push("- Context-pack compression is applied only to LLM-facing previews; original events remain available through source refs.");
+    lines.push("- Privacy filters run before compression and final preview sanitization runs after compression.");
     if (maxContextChars !== void 0) {
       lines.push(`- Hard output budget: ${maxContextChars} characters; use follow-up lookups to expand trimmed sources.`);
     }
@@ -28096,7 +28297,8 @@ async function handleMemProjectTimeline(memoryService, args) {
   const limit = numberArg(args.limit, 50, 1, 500);
   const sessionLimit = numberArg(args.sessionLimit, 10, 1, 50);
   const recentEvents = await memoryService.getRecentEvents(limit);
-  const sessions = summarizeSessions(recentEvents, sessionLimit);
+  const timelineEvents = recentEvents.filter((event) => !isLowSignalContextContent(event.content || ""));
+  const sessions = summarizeSessions(timelineEvents, sessionLimit);
   const lines = [
     "## Project Memory Timeline",
     "",
@@ -28117,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.", "");
@@ -28145,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"));
@@ -28374,12 +28592,38 @@ 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;
   return [
     `${index}. [mem:${citationId}] score=${score.toFixed(2)} type=${event.eventType} date=${event.timestamp.toISOString()} session=${event.sessionId}`,
     `   source=${sourceForEvent(event)}`,
-    `   ${contextPackPreview(event, 260, formatOptions)}`,
+    `   ${contextPackPreview(event, previewBudget, formatOptions)}`,
     ""
   ].join("\n");
 }
@@ -28456,6 +28700,7 @@ function contextPackPreview(event, maxLength, options = DEFAULT_CONTEXT_PACK_FOR
   const compressed = MCP_CONTEXT_COMPRESSOR.compress(privacyFiltered, {
     mode: options.compression,
     source: sourceForEvent(event),
+    sourceRef: `mem:${generateCitationId(event.id)}`,
     metadata: {
       ...safeCompressionMetadata(event.metadata),
       eventType: event.eventType
@@ -28483,8 +28728,9 @@ function appendCompressionTelemetry(lines, metadata, maxChars) {
   const summary = summarizeCompressionTelemetry(metadata);
   const sources = summary.bySource.map((item) => `${item.source}:${item.items}`).join(",");
   const strategies = summary.byStrategy.map((item) => `${item.strategy}:${item.items}`).join(",");
+  const sourceRefsAvailable = metadata.filter((item) => item.sourceRef !== void 0).length;
   lines.push(
-    `- Compression telemetry: items=${summary.totalItems} originalChars=${summary.totalOriginalChars} compressedChars=${summary.totalCompressedChars} savedChars=${summary.totalSavedChars} sources=${sources || "n/a"} strategies=${strategies || "n/a"}`,
+    `- Compression telemetry: items=${summary.totalItems} originalChars=${summary.totalOriginalChars} compressedChars=${summary.totalCompressedChars} savedChars=${summary.totalSavedChars} omittedLines=${summary.totalOmittedLines} sourceRefsPreserved=${summary.sourceRefsPreserved}/${sourceRefsAvailable} sources=${sources || "n/a"} strategies=${strategies || "n/a"}`,
     ""
   );
 }
@@ -28494,18 +28740,32 @@ 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, CONTEXT_PACK_MIN_HARD_BUDGET_CHARS, CONTEXT_PACK_MAX_CHARS_CAP);
-  const maxTokens = optionalNumberArg(args.maxTokens, 250, Math.floor(CONTEXT_PACK_MAX_CHARS_CAP / 4));
+  const maxChars = optionalNumberArg(args.maxChars, "maxChars", CONTEXT_PACK_MIN_HARD_BUDGET_CHARS, CONTEXT_PACK_MAX_CHARS_CAP);
+  const maxTokens = optionalNumberArg(args.maxTokens, "maxTokens", 250, Math.floor(CONTEXT_PACK_MAX_CHARS_CAP / 4));
   const tokenChars = maxTokens === void 0 ? void 0 : maxTokens * 4;
   if (maxChars !== void 0 && tokenChars !== void 0) return Math.min(maxChars, tokenChars);
   return maxChars ?? tokenChars;
 }
-function optionalNumberArg(value, min, max) {
+function optionalNumberArg(value, name, min, max) {
   if (value === void 0 || value === null || value === "") return void 0;
   const parsed = typeof value === "number" ? value : Number(value);
-  if (!Number.isFinite(parsed)) return void 0;
-  return Math.min(max, Math.max(min, Math.floor(parsed)));
+  if (!Number.isFinite(parsed) || parsed < min || parsed > max) {
+    throw new Error(`Invalid ${name}: expected number between ${min} and ${max}`);
+  }
+  return Math.floor(parsed);
 }
 function applyContextPackBudget(text, maxChars) {
   if (maxChars === void 0 || text.length <= maxChars) return text;