claude-memory-layer 1.0.46 → 1.0.47

package/README.md

@@ -312,6 +312,7 @@ MCP client가 환경에 따라 PATH를 못 찾으면 `command -v claude-memory-l
 ### Advanced Features
 
 - **Citations System**: 검색 결과를 `[mem:abc123]` 형태로 추적하고 `source`/`mem-source-ref`로 근거 확인
+- **Source Neighbor Expansion**: `mem-source-ref(includeNeighbors=true, neighborWindow=1..5)`로 MemPalace식 hit 주변 세션 이벤트를 privacy-safe preview로 함께 확인
 - **Progressive Disclosure**: index → timeline → details 순서로 필요한 만큼만 확장해 토큰 비용 절감
 - **Codex/Hermes Importers**: read-only validate/replay 후 explicit import로만 mutation 수행
 - **Perspective Query Agent**: 관점별 observation + raw memory를 읽기 전용으로 조합하고 source refs를 유지
@@ -681,7 +682,7 @@ node dist/mcp/index.js
 | Context | `mem-context-pack` | 작업 시작용 relevant memory + recent timeline + follow-up refs |
 | Context | `mem-import-latest` | 최신 Claude/Codex/Hermes 세션을 bounded import 후 context-pack freshness 확보 |
 | Context | `mem-project-timeline` | 최근 프로젝트 메모리를 session/source/count/safe-preview로 요약 |
-| Context | `mem-source-ref` | `mem:`/`event:` ref를 redacted preview와 safe metadata로 해석 |
+| Context | `mem-source-ref` | `mem:`/`event:` ref를 redacted preview와 safe metadata로 해석; `includeNeighbors` + `neighborWindow`로 같은 세션의 전후 이벤트를 bounded/privacy-safe preview로 확장 |
 | Operations | `mem-facet-query` / `mem-facet-tag` | project-scoped facet 조회/태깅 |
 | Operations | `mem-action-list` / `mem-action-update` | 다음 작업/action 상태 조회·갱신 |
 | Operations | `mem-frontier` | blocked/next action frontier와 safe resume hints |
@@ -703,7 +704,7 @@ node dist/mcp/index.js
 ```text
 1. 새 작업 시작: mem-context-pack(projectPath, query)
 2. 최근 흐름 확인: mem-project-timeline(projectPath)
-3. 근거가 더 필요할 때: mem-source-ref(projectPath, ids=["mem:abc123"])
+3. 근거가 더 필요할 때: mem-source-ref(projectPath, ids=["mem:abc123"], includeNeighbors=true, neighborWindow=1)
 ```
 
 이 workflow는 Hermes/Codex/Claude Code가 같은 project-scoped memory backend를 공유할 때 특히 유용합니다. `mem-source-ref`는 raw transcript를 그대로 덤프하지 않고 allowlisted metadata와 privacy-filtered preview만 반환합니다.

package/dist/cli/index.js

@@ -2574,6 +2574,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"
@@ -10310,6 +10311,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);
@@ -10340,6 +10342,7 @@ var Retriever = class {
       decayPolicy: opts.decayPolicy,
       intentRewrite: opts.intentRewrite === true,
       graphHop: opts.graphHop,
+      retrievalMode,
       projectScopeMode: opts.projectScopeMode,
       projectHash: opts.projectHash,
       allowedProjectHashes: opts.allowedProjectHashes,
@@ -10358,6 +10361,7 @@ var Retriever = class {
         rerankWeights: opts.rerankWeights,
         decayPolicy: opts.decayPolicy,
         graphHop: opts.graphHop,
+        retrievalMode,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
         allowedProjectHashes: opts.allowedProjectHashes,
@@ -10377,6 +10381,7 @@ var Retriever = class {
         rerankWeights: opts.rerankWeights,
         decayPolicy: opts.decayPolicy,
         graphHop: opts.graphHop,
+        retrievalMode,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
         allowedProjectHashes: opts.allowedProjectHashes,
@@ -10397,10 +10402,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");
     }
@@ -10486,13 +10507,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,
@@ -10540,6 +10566,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);
@@ -21037,7 +21104,7 @@ async function runOperationCli(action, label) {
   }
 }
 var program = new Command();
-program.name("claude-memory-layer").description("Claude Code Memory Plugin CLI").version("1.0.46");
+program.name("claude-memory-layer").description("Claude Code Memory Plugin CLI").version("1.0.47");
 program.command("market-context").description("Fetch read-only DART/FRED/Finnhub context with structured MarketContextSnapshot bull/bear/risk/catalyst analysis").option("--company <name>", "Company name for DART fallback search and report subject").option("--dart-corp-code <code>", "Exact DART corp_code for issuer-specific filings").option("--symbol <ticker>", "Listed ticker for Finnhub company profile").option("--providers <list>", "Comma-separated providers: dart,fred,finnhub").option("--fred-series <list>", "Comma-separated FRED series IDs").option("--json", "Print structured JSON including analysis.marketSnapshot").option("--no-snapshot", "Disable MarketContextSnapshot and DART company snapshot analysis").action(async (options) => {
   try {
     await runMarketContextCommand(options);