recallnest 1.4.1 → 2.2.1

package/src/retriever.ts

@@ -8,14 +8,19 @@ import type { Embedder } from "./embedder.js";
 import { filterNoise } from "./noise-filter.js";
 import { shouldSkipRetrieval } from "./adaptive-retrieval.js";
 import { expandQuery } from "./query-expander.js";
+import { detectLang, tokenizeFts } from "./language-hook.js";
 import { type AccessTracker, computeHotnessScore, parseAccessMetadata } from "./access-tracker.js";
-import { weibullDecay, resolveTier } from "./decay-engine.js";
+import { weibullDecay, resolveTier, isDecayExempt, adjustHalfLifeForEmotion, computeArousalBoost } from "./decay-engine.js";
 import { logWarn } from "./stderr-log.js";
 import { extractBoundaryMetadata, isDurableMemoryScope, isTranscriptScope } from "./memory-boundaries.js";
 import type { TraceCollector } from "./retrieval-trace.js";
+import { extractTopicTag } from "./topic-tag.js";
 import { filterInterference } from "./rif.js";
+import { FrequencyTracker } from "./frequency-tracker.js";
 import { applyConfidenceWeight } from "./confidence-tracker.js";
 import { deduplicateByVersionGroup } from "./version-manager.js";
+import { deduplicateByClusterInsight } from "./consolidation-engine.js";
+import { isActiveMemory, recordAccess as recordEvolutionAccess, parseEvolution, computeDecayScore } from "./memory-evolution.js";
 import {
   isMultiVectorEnabled,
   extractMultiVectorText,
@@ -30,6 +35,17 @@ import { isKGModeEnabled } from "./kg-extractor.js";
 import { detectEntities } from "./query-entity-detector.js";
 import { buildGraph, pprTraverse } from "./ppr-traversal.js";
 import { logInfo } from "./stderr-log.js";
+import type { AuditLogger } from "./audit-log.js";
+import { parseEmotion, isEmotionScoringEnabled } from "./memory-schema.js";
+import { parseNarrative, isNarrativeModeEnabled } from "./narrative-schema.js";
+import type { EmotionMetadata } from "./memory-schema.js";
+import { detectEmotion } from "./emotion-detector.js";
+import { shouldReconstruct, reconstruct as runReconstruction } from "./context-reconstructor.js";
+import type {
+  ReconstructionLLMClient,
+  ReconstructionOutput,
+  CandidateExpansionDeps,
+} from "./context-reconstructor.js";
 
 // ============================================================================
 // Types & Configuration
@@ -101,6 +117,31 @@ export interface RetrievalConfig {
   rifThreshold?: number;
   /** RIF score ratio: demote if score < ratio * stronger result's score (default: 0.80). */
   rifScoreRatio?: number;
+  /**
+   * Source diversity: ensure top-k results span multiple scopes/sessions.
+   * When > 0 and candidates come from >= 3 distinct scopes, applies round-robin
+   * selection (one per scope first, then fill remaining slots by score).
+   * 0 = disabled (default). Recommended: 0.5 (moderate diversity).
+   */
+  sourceDiversity?: number;
+  /**
+   * Adaptive candidate pool multiplier for aggregation queries.
+   * When a query contains counting/listing signals ("how many", "all the", etc.),
+   * candidatePoolSize is multiplied by this factor.
+   * 1 = disabled (default). Recommended: 1.5.
+   */
+  adaptivePoolMultiplier?: number;
+  /**
+   * Enable multi-hop retrieval: after first-pass results, extract entities
+   * and run focused follow-up queries to improve cross-session coverage.
+   * Costs 1-3 extra embedding calls per retrieve. Default: false.
+   */
+  multiHop?: boolean;
+  /**
+   * Maximum number of entity-focused follow-up queries in multi-hop mode.
+   * Default: 3.
+   */
+  multiHopMaxQueries?: number;
 }
 
 export interface RetrievalContext {
@@ -118,6 +159,16 @@ export interface RetrievalContext {
   trace?: TraceCollector;
   /** Enable KG graph traversal (PPR) as an additional retrieval signal. */
   graph?: boolean;
+  /** Override config-level multiHop for this single retrieval call. */
+  multiHop?: boolean;
+  /** MP-1: Filter results by topicTag stored in metadata. */
+  topicTag?: string;
+  /** Request constructive retrieval reconstruction */
+  reconstruct?: boolean;
+  /** F3: Query memories valid at a specific point in time (ms timestamp). */
+  validAt?: number;
+  /** F3: When true, include expired memories (demoted 80%). Default: false. */
+  includeExpired?: boolean;
 }
 
 export interface RetrievalResult extends MemorySearchResult {
@@ -127,9 +178,19 @@ export interface RetrievalResult extends MemorySearchResult {
     graph?: { score: number; rank: number };
     fused?: { score: number };
     reranked?: { score: number };
+    /** HP-narrative: true when this result was pulled as a narrative sibling */
+    narrativeSibling?: boolean;
   };
 }
 
+/**
+ * Phase 4: Extended retrieval result set with optional first-class reconstruction.
+ * Backward-compatible — callers treating this as RetrievalResult[] still work.
+ */
+export type RetrievalResultSet = RetrievalResult[] & {
+  reconstruction?: ReconstructionOutput;
+};
+
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -180,6 +241,219 @@ function clamp01(value: number, fallback: number): number {
   return Math.min(1, Math.max(0, value));
 }
 
+/**
+ * F3: Filter results by temporal validity window.
+ * - Expired memories (validUntil < now) are demoted by 80% or excluded.
+ * - validAt: only return memories valid at a specific point in time.
+ */
+function filterByValidity(
+  results: RetrievalResult[],
+  now: number,
+  options: { validAt?: number; includeExpired?: boolean },
+): RetrievalResult[] {
+  const { validAt, includeExpired } = options;
+  const checkTime = validAt ?? now;
+
+  return results.reduce<RetrievalResult[]>((acc, r) => {
+    const evo = parseEvolution(r.entry.metadata, r.entry.timestamp);
+
+    // Point-in-time query: skip memories not yet valid or already expired at checkTime
+    if (validAt != null) {
+      if (evo.validFrom > checkTime) return acc; // not yet valid
+      if (evo.validUntil != null && evo.validUntil < checkTime) {
+        if (!includeExpired) return acc;
+        // Include but demote 80%
+        acc.push({ ...r, score: r.score * 0.2 });
+        return acc;
+      }
+      acc.push(r);
+      return acc;
+    }
+
+    // Default: check if expired relative to now
+    if (evo.validUntil != null && evo.validUntil < now) {
+      if (!includeExpired) return acc;
+      acc.push({ ...r, score: r.score * 0.2 });
+      return acc;
+    }
+
+    acc.push(r);
+    return acc;
+  }, []);
+}
+
+/** P0.1: Short query detection — ≤ 4 tokens (CJK chars count as 1 token each). */
+const SHORT_QUERY_TOKEN_THRESHOLD = 4;
+
+function isShortQuery(query: string): boolean {
+  return tokenize(query).length <= SHORT_QUERY_TOKEN_THRESHOLD;
+}
+
+/** P0.1: Minimum score discount for short queries to widen the candidate pool. */
+const SHORT_QUERY_MIN_SCORE_FACTOR = 0.6;
+
+/** P0.1: Anchor boost factor — how much a perfect anchor match boosts score. */
+const ANCHOR_BOOST_MAX = 0.25;
+
+/**
+ * P0.1: Boost scores for candidates whose metadata.anchor matches the query.
+ * Uses textOverlapScore (token coverage + density) — same as multi-vector blend.
+ * Short queries benefit most because anchor text is also short (≤80 chars).
+ */
+function applyAnchorBoost(results: RetrievalResult[], query: string): RetrievalResult[] {
+  if (results.length === 0) return results;
+  return results.map(r => {
+    const meta = parseMetadata(r.entry.metadata);
+    const anchor = meta.anchor;
+    if (typeof anchor !== "string" || !anchor) return r;
+    const overlap = textOverlapScore(query, anchor);
+    if (overlap <= 0) return r;
+    // Boost proportional to overlap quality, capped at ANCHOR_BOOST_MAX
+    const boost = 1 + overlap * ANCHOR_BOOST_MAX;
+    return { ...r, score: r.score * boost };
+  });
+}
+
+/**
+ * Emotion scoring stage: boost memories matching query emotional tone.
+ * No-op when query is neutral or memory lacks emotion data.
+ */
+export function applyEmotionWeight(
+  results: Array<{ score: number; metadata: string; [k: string]: unknown }>,
+  queryEmotion: EmotionMetadata | null,
+): typeof results {
+  if (!queryEmotion || Math.abs(queryEmotion.valence) < 0.2) {
+    return results;
+  }
+  return results.map(r => {
+    const memEmotion = parseEmotion(r.metadata);
+    if (!memEmotion) return r;
+    const alignment = 1 - Math.abs(queryEmotion.valence - memEmotion.valence) / 2;
+    const boost = 1.0 + 0.15 * alignment;
+    return { ...r, score: r.score * boost };
+  });
+}
+
+// ============================================================================
+// Source Diversity — round-robin across scopes for multi-session coverage
+// ============================================================================
+
+/** Minimum distinct sources to activate diversity logic. */
+const SOURCE_DIVERSITY_MIN_SOURCES = 3;
+
+/**
+ * Ensures top-k results span multiple scopes/sessions via round-robin.
+ * Each distinct source gets its top-1 result first, remaining slots fill by score.
+ */
+function applySourceDiversity(results: RetrievalResult[], limit: number): RetrievalResult[] {
+  if (results.length <= limit) return results;
+
+  // Group by scope
+  const byScope = new Map<string, RetrievalResult[]>();
+  for (const r of results) {
+    const key = r.entry.scope || "__default__";
+    const bucket = byScope.get(key);
+    if (bucket) bucket.push(r);
+    else byScope.set(key, [r]);
+  }
+
+  if (byScope.size < SOURCE_DIVERSITY_MIN_SOURCES) {
+    return results.slice(0, limit);
+  }
+
+  // Round-robin: each scope contributes its top-1
+  const selected: RetrievalResult[] = [];
+  const usedIds = new Set<string>();
+
+  // Sort scopes by their best result score (highest first)
+  const scopeEntries = [...byScope.entries()].sort(
+    (a, b) => (b[1][0]?.score ?? 0) - (a[1][0]?.score ?? 0),
+  );
+
+  for (const [, items] of scopeEntries) {
+    if (selected.length >= limit) break;
+    const top = items[0];
+    if (top && !usedIds.has(top.entry.id)) {
+      selected.push(top);
+      usedIds.add(top.entry.id);
+    }
+  }
+
+  // Fill remaining slots by global score
+  for (const r of results) {
+    if (selected.length >= limit) break;
+    if (!usedIds.has(r.entry.id)) {
+      selected.push(r);
+      usedIds.add(r.entry.id);
+    }
+  }
+
+  return selected;
+}
+
+// ============================================================================
+// Adaptive Candidate Pool — detect aggregation queries
+// ============================================================================
+
+const AGGREGATION_EN_RE = /\b(?:how many|how much|all the|every|list all|total number|count)\b/i;
+const AGGREGATION_CN_RE = /(?:多少[个件条只]?|一共|总共|所有的?|列举|有几[个件条只])/u;
+
+function isAggregationQuery(query: string): boolean {
+  return AGGREGATION_EN_RE.test(query) || AGGREGATION_CN_RE.test(query);
+}
+
+// ============================================================================
+// Multi-hop Entity Extraction — extract entities from retrieval results
+// ============================================================================
+
+const MULTI_HOP_STOP_WORDS = new Set([
+  "the", "a", "an", "is", "are", "was", "were", "be", "been",
+  "have", "has", "had", "will", "would", "can", "could", "should",
+  "do", "does", "did", "not", "no", "but", "and", "or", "if",
+  "this", "that", "these", "those", "it", "its", "user", "assistant",
+  "my", "your", "his", "her", "our", "their", "i", "you", "he", "she",
+  "we", "they", "me", "him", "us", "them", "who", "what", "where",
+  "when", "how", "why", "which", "about", "with", "from", "for",
+  "into", "also", "just", "very", "some", "more", "most", "other",
+]);
+
+const COMMON_CJK_STOP = /^(用户|助手|可以|需要|已经|没有|什么|这个|那个|因为|所以|但是|如果)$/;
+
+/**
+ * Extract salient entities from retrieval result texts.
+ * Focuses on proper nouns and CJK named entities.
+ * Returns unique entities sorted by frequency (most common first).
+ */
+function extractEntitiesFromResults(results: RetrievalResult[]): string[] {
+  const freq = new Map<string, number>();
+
+  for (const r of results) {
+    const text = r.entry.text;
+
+    // Capitalized multi-word entities: "Adobe Premiere Pro", "Sony A7III"
+    const capPattern = /\b([A-Z][a-zA-Z0-9]*(?:[\s\-][A-Z][a-zA-Z0-9]*)*)\b/g;
+    let match: RegExpExecArray | null;
+    while ((match = capPattern.exec(text)) !== null) {
+      const entity = match[1].trim();
+      if (entity.length < 2 || MULTI_HOP_STOP_WORDS.has(entity.toLowerCase())) continue;
+      freq.set(entity, (freq.get(entity) ?? 0) + 1);
+    }
+
+    // CJK named entities: sequences of 2-8 CJK chars (simple heuristic)
+    const cjkPattern = /([\p{Script=Han}]{2,8})/gu;
+    while ((match = cjkPattern.exec(text)) !== null) {
+      const entity = match[1];
+      if (COMMON_CJK_STOP.test(entity)) continue;
+      freq.set(entity, (freq.get(entity) ?? 0) + 1);
+    }
+  }
+
+  // Sort by frequency descending, then by length descending (prefer specific entities)
+  return [...freq.entries()]
+    .sort((a, b) => b[1] - a[1] || b[0].length - a[0].length)
+    .map(([entity]) => entity);
+}
+
 function parseMetadata(raw?: string): Record<string, unknown> {
   try {
     return JSON.parse(raw || "{}") as Record<string, unknown>;
@@ -353,6 +627,9 @@ function cosineSimilarity(a: number[], b: number[]): number {
 export class MemoryRetriever {
   private accessTracker?: AccessTracker;
   private kgStore?: KGStore;
+  private frequencyTracker?: FrequencyTracker;
+  private auditLogger?: AuditLogger;
+  private llmClient?: ReconstructionLLMClient;
   /**
    * Session-scoped suppression list (dopamine-inspired "do not disturb").
    * IDs in this set get a score penalty during retrieval but are NOT deleted.
@@ -376,6 +653,21 @@ export class MemoryRetriever {
     this.kgStore = kgStore;
   }
 
+  /** P0.2: Attach a FrequencyTracker for hit-count based boosting. */
+  setFrequencyTracker(tracker: FrequencyTracker): void {
+    this.frequencyTracker = tracker;
+  }
+
+  /** F-1: Attach an AuditLogger for recording retrieve operations. */
+  setAuditLogger(logger: AuditLogger): void {
+    this.auditLogger = logger;
+  }
+
+  /** Attach an LLM client for constructive retrieval reconstruction. */
+  setLLMClient(client: ReconstructionLLMClient): void {
+    this.llmClient = client;
+  }
+
   /** Suppress a memory ID for the current session (score × 0.3). */
   suppressForSession(id: string): void {
     this.sessionSuppressed.add(id);
@@ -386,13 +678,15 @@ export class MemoryRetriever {
     this.sessionSuppressed.clear();
   }
 
-  /** Resolve the minimum score for a given category, falling back to hardMinScore. */
-  private minScoreFor(category: string): number {
+  /** Resolve the minimum score for a given category, falling back to hardMinScore.
+   *  P0.1: When shortQuery is true, thresholds are lowered to widen the candidate pool. */
+  private minScoreFor(category: string, shortQuery = false): number {
     const map = this.config.categoryMinScores ?? DEFAULT_CATEGORY_MIN_SCORES;
-    return map[category] ?? this.config.hardMinScore;
+    const base = map[category] ?? this.config.hardMinScore;
+    return shortQuery ? base * SHORT_QUERY_MIN_SCORE_FACTOR : base;
   }
 
-  async retrieve(context: RetrievalContext): Promise<RetrievalResult[]> {
+  async retrieve(context: RetrievalContext): Promise<RetrievalResultSet> {
     const { query, limit, scopeFilter, category, includeArchived, trace, graph } = context;
     const safeLimit = clampInt(limit, 1, 20);
 
@@ -411,18 +705,152 @@ export class MemoryRetriever {
       results = await this.hybridRetrieval(query, safeLimit, scopeFilter, category, includeArchived, trace, graph);
     }
 
+    // LME-2: Multi-hop retrieval — extract entities from first-pass results,
+    // run focused follow-up queries, merge to improve cross-session coverage.
+    const useMultiHop = context.multiHop ?? this.config.multiHop ?? false;
+    if (useMultiHop && results.length > 0) {
+      results = await this.multiHopExpand(results, context);
+    }
+
+    // MP-1: Topic Tag post-filter — only keep results matching the requested topicTag
+    if (context.topicTag && results.length > 0) {
+      const tag = context.topicTag.toLowerCase();
+      results = results.filter(r => {
+        const entryTag = extractTopicTag(r.entry.metadata);
+        return entryTag?.toLowerCase() === tag;
+      });
+    }
+
+    // F3: Temporal validity filter — expired memories excluded by default
+    if (results.length > 0) {
+      results = filterByValidity(results, Date.now(), {
+        validAt: context.validAt,
+        includeExpired: context.includeExpired,
+      });
+    }
+
+    // P0.2: Record frequency hits for returned results (manual queries only)
+    // Moved after topicTag filter so filtered-out entries are not reinforced.
+    if (this.frequencyTracker && results.length > 0 && context.source !== "auto-recall") {
+      this.frequencyTracker.recordHits(results.map(r => r.entry.id));
+    }
+
+    // A-3: Record evolution access counts (async, non-blocking)
+    // Moved after topicTag filter so filtered-out entries are not reinforced.
+    if (results.length > 0 && context.source !== "auto-recall" && this.store.update) {
+      Promise.resolve().then(async () => {
+        for (const r of results) {
+          try {
+            const updated = recordEvolutionAccess(r.entry.metadata);
+            await this.store.update!(r.entry.id, { metadata: updated });
+          } catch (err) { console.error("[recallnest] Evolution access tracking failed:", err instanceof Error ? err.message : String(err)); }
+        }
+      });
+    }
+
     // Record access for returned results (async, non-blocking).
     // Only reinforce on manual retrieval — auto-recall must not strengthen noise.
-    // Tier 3.2: pass similarity scores for novelty gating — only novel retrievals
-    // (high query-result distance) trigger access reinforcement.
+    // Tier 3.2: pass raw vector similarity scores for novelty gating — only novel
+    // retrievals (high query-result distance) trigger access reinforcement.
     if (this.accessTracker && results.length > 0 && context.source !== "auto-recall") {
       this.accessTracker.recordAccess(
         results.map(r => r.entry.id),
-        results.map(r => r.score),
+        results.map(r => r.sources.vector?.score),
       );
     }
 
-    return results;
+    // F-1: Audit log — record retrieve operation (non-blocking, silent on failure)
+    try {
+      this.auditLogger?.log({
+        operation: "retrieve",
+        scope: context.scopeFilter?.[0],
+        actor: context.source || "manual",
+        details: `query="${context.query.slice(0, 80)}" hits=${results.length}`,
+      });
+    } catch {
+      // Audit must never block retrieval
+    }
+
+    // Phase 4: Constructive retrieval — first-class reconstruction (no metadata hack)
+    const resultSet = results as RetrievalResultSet;
+    const constructiveFlag = process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+    if (shouldReconstruct({
+      flagEnabled: constructiveFlag,
+      callerOptIn: context.reconstruct === true,
+      resultCount: results.length,
+      llmAvailable: this.llmClient
+        ? ("isAvailable" in this.llmClient ? (this.llmClient as { isAvailable(): boolean }).isAvailable() : true)
+        : false,
+    })) {
+      try {
+        const expansionDeps = this.buildExpansionDeps(context);
+        const reconstruction = await runReconstruction(
+          { query: context.query, results, mode: "search" },
+          this.llmClient!,
+          expansionDeps,
+        );
+        resultSet.reconstruction = reconstruction;
+      } catch {
+        // Silent degradation — return raw results
+      }
+    }
+
+    return resultSet;
+  }
+
+  /**
+   * LME-2: Multi-hop expansion — extract entities from first-pass results,
+   * run entity-focused follow-up queries, merge with original results.
+   * Improves cross-session coverage for aggregation/counting queries.
+   */
+  private async multiHopExpand(
+    firstPass: RetrievalResult[],
+    context: RetrievalContext,
+  ): Promise<RetrievalResult[]> {
+    const maxQueries = this.config.multiHopMaxQueries ?? 3;
+    const entities = extractEntitiesFromResults(firstPass);
+    if (entities.length === 0) return firstPass;
+
+    // Pick top entities that aren't already well-covered in the query
+    const queryLower = context.query.toLowerCase();
+    const novelEntities = entities
+      .filter(e => !queryLower.includes(e.toLowerCase()))
+      .slice(0, maxQueries);
+
+    if (novelEntities.length === 0) return firstPass;
+
+    // Run follow-up queries in parallel (entity + original query context)
+    const followUpPromises = novelEntities.map(entity =>
+      this.hybridRetrieval(
+        `${entity} ${context.query}`,
+        context.limit,
+        context.scopeFilter,
+        context.category,
+        context.includeArchived,
+        undefined, // no trace for follow-up
+        context.graph,
+      ).catch(() => [] as RetrievalResult[]),
+    );
+    const followUpResults = await Promise.all(followUpPromises);
+
+    // Merge: deduplicate by memory ID, keep highest score
+    const merged = new Map<string, RetrievalResult>();
+    for (const r of firstPass) {
+      merged.set(r.entry.id, r);
+    }
+    for (const batch of followUpResults) {
+      for (const r of batch) {
+        const existing = merged.get(r.entry.id);
+        if (!existing || r.score > existing.score) {
+          merged.set(r.entry.id, r);
+        }
+      }
+    }
+
+    // Sort by score descending, limit
+    return [...merged.values()]
+      .sort((a, b) => b.score - a.score)
+      .slice(0, context.limit);
   }
 
   private async vectorOnlyRetrieval(
@@ -439,7 +867,12 @@ export class MemoryRetriever {
 
     trace?.startStage("vector_search", 0);
     const queryVector = await this.embedder.embedQuery(searchQuery);
-    const results = await this.store.vectorSearch(queryVector, limit, this.config.minScore, scopeFilter);
+    // P0.1: Lower minScore for short queries
+    const shortQ = isShortQuery(searchQuery);
+    const vectorMinScore = shortQ
+      ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
+      : this.config.minScore;
+    const results = await this.store.vectorSearch(queryVector, limit, vectorMinScore, scopeFilter);
     trace?.endStage(results.length, results.map(r => r.score));
 
     // Filter by category if specified
@@ -464,8 +897,11 @@ export class MemoryRetriever {
       },
     } as RetrievalResult));
 
-    trace?.startStage("recency_boost", mapped.length);
-    const boosted = this.applyRecencyBoost(mapped);
+    // P0.1: Anchor boost for vector-only path
+    const anchorBoosted = applyAnchorBoost(mapped, searchQuery);
+
+    trace?.startStage("recency_boost", anchorBoosted.length);
+    const boosted = this.applyRecencyBoost(anchorBoosted);
     trace?.endStage(boosted.length, boosted.map(r => r.score));
 
     trace?.startStage("importance_weight", boosted.length);
@@ -476,8 +912,16 @@ export class MemoryRetriever {
     const confidenceWeighted = this.applyConfidence(weighted);
     trace?.endStage(confidenceWeighted.length, confidenceWeighted.map(r => r.score));
 
-    trace?.startStage("boundary_weight", confidenceWeighted.length);
-    const boundaryWeighted = this.applyBoundaryWeight(confidenceWeighted);
+    let afterEmotionVector = confidenceWeighted;
+    if (isEmotionScoringEnabled()) {
+      const queryEmotion = detectEmotion(query);
+      const adapted = confidenceWeighted.map(r => ({ ...r, metadata: r.entry.metadata ?? "{}" }));
+      const emotioned = applyEmotionWeight(adapted, queryEmotion);
+      afterEmotionVector = confidenceWeighted.map((r, i) => ({ ...r, score: emotioned[i]?.score ?? r.score }));
+    }
+
+    trace?.startStage("boundary_weight", afterEmotionVector.length);
+    const boundaryWeighted = this.applyBoundaryWeight(afterEmotionVector);
     trace?.endStage(boundaryWeighted.length, boundaryWeighted.map(r => r.score));
 
     trace?.startStage("asset_type_weight", boundaryWeighted.length);
@@ -492,22 +936,39 @@ export class MemoryRetriever {
     const timeDecayed = this.applyTimeDecay(lengthNormalized);
     trace?.endStage(timeDecayed.length, timeDecayed.map(r => r.score));
 
+    // B-1/E-1: Evolution decay blend — boost memories with high composite decay score
+    const evolutionBlended = this.applyEvolutionDecayBlend(timeDecayed);
+
+    // E-1: Access count boost — memories retrieved more often get a score nudge
+    const accessBoosted = this.applyAccessCountBoost(evolutionBlended);
+
     // Hotness blend: boost frequently + recently accessed memories
-    trace?.startStage("hotness_blend", timeDecayed.length);
-    const hotnessBlended = this.applyHotnessBlend(timeDecayed);
+    trace?.startStage("hotness_blend", accessBoosted.length);
+    const hotnessBlended = this.applyHotnessBlend(accessBoosted);
     trace?.endStage(hotnessBlended.length, hotnessBlended.map(r => r.score));
 
+    // P0.2: Frequency boost — repeatedly retrieved memories score higher
+    trace?.startStage("frequency_boost", hotnessBlended.length);
+    const frequencyBoosted = this.applyFrequencyBoost(hotnessBlended);
+    trace?.endStage(frequencyBoosted.length, frequencyBoosted.map(r => r.score));
+
     // Session suppression: temporarily penalize "do not disturb" memories
-    const afterSuppression = this.applySessionSuppression(hotnessBlended);
+    const afterSuppression = this.applySessionSuppression(frequencyBoosted);
+    const rescored = [...afterSuppression].sort((a, b) => b.score - a.score);
 
-    trace?.startStage("hard_min_score", afterSuppression.length);
-    const hardFiltered = afterSuppression.filter(r => r.score >= this.minScoreFor(r.entry.category));
+    trace?.startStage("hard_min_score", rescored.length);
+    const hardFiltered = rescored.filter(r => r.score >= this.minScoreFor(r.entry.category, shortQ));
     trace?.endStage(hardFiltered.length, hardFiltered.map(r => r.score));
 
-    trace?.startStage("noise_filter", hardFiltered.length);
+    // Evolution status filter: exclude superseded/archived/consolidated memories
+    const evolutionFiltered = includeArchived
+      ? hardFiltered
+      : hardFiltered.filter(r => isActiveMemory(r.entry.metadata));
+
+    trace?.startStage("noise_filter", evolutionFiltered.length);
     const denoised = this.config.filterNoise
-      ? filterNoise(hardFiltered, r => r.entry.text)
-      : hardFiltered;
+      ? filterNoise(evolutionFiltered, r => r.entry.text)
+      : evolutionFiltered;
     trace?.endStage(denoised.length, denoised.map(r => r.score));
 
     // RIF: demote near-duplicate weak results to improve diversity
@@ -523,8 +984,16 @@ export class MemoryRetriever {
     // Tier 3.3: Version group dedup — keep only the top-ranked version per group
     const versionDeduped = deduplicateByVersionGroup(deduplicated);
 
-    trace?.startStage("final_limit", versionDeduped.length);
-    const final = versionDeduped.slice(0, limit);
+    // LC-P2: Cluster insight dedup — prefer cluster summary over individual source memories
+    const clusterDeduped = deduplicateByClusterInsight(versionDeduped);
+
+    // Source diversity: round-robin across scopes for multi-session coverage
+    const diversified = (this.config.sourceDiversity ?? 0) > 0
+      ? applySourceDiversity(clusterDeduped, limit)
+      : clusterDeduped;
+
+    trace?.startStage("final_limit", diversified.length);
+    const final = diversified.slice(0, limit);
     trace?.endStage(final.length, final.map(r => r.score));
 
     return final;
@@ -539,7 +1008,14 @@ export class MemoryRetriever {
     trace?: TraceCollector,
     graph?: boolean,
   ): Promise<RetrievalResult[]> {
-    const candidatePoolSize = Math.max(this.config.candidatePoolSize, limit * 2);
+    // Adaptive pool: widen candidate pool for aggregation queries ("how many", "all the")
+    const multiplier = (this.config.adaptivePoolMultiplier ?? 1) > 1 && isAggregationQuery(query)
+      ? (this.config.adaptivePoolMultiplier ?? 1)
+      : 1;
+    const candidatePoolSize = Math.max(
+      Math.ceil(this.config.candidatePoolSize * multiplier),
+      limit * 2,
+    );
 
     // Temporal reasoning: extract time constraint and clean query for semantic search
     const temporal = parseTemporalQuery(query);
@@ -554,10 +1030,14 @@ export class MemoryRetriever {
       ? this.runPPRSearch(query, scopeFilter?.[0], trace)
       : Promise.resolve([] as RetrievalResult[]);
 
+    // Pre-tokenize expanded query for BM25 so CJK text produces meaningful FTS matches
+    const expandedQuery = expandQuery(searchQuery);
+    const ftsQuery = tokenizeFts(expandedQuery, detectLang(expandedQuery));
+
     trace?.startStage("vector_search", 0);
     const [vectorResults, bm25Results, pprResults] = await Promise.all([
       this.runVectorSearch(queryVector, candidatePoolSize, scopeFilter, category, includeArchived),
-      this.runBM25Search(expandQuery(searchQuery), candidatePoolSize, scopeFilter, category, includeArchived),
+      this.runBM25Search(ftsQuery, candidatePoolSize, scopeFilter, category, includeArchived),
       pprPromise,
     ]);
     trace?.endStage(vectorResults.length, vectorResults.map(r => r.score));
@@ -565,9 +1045,10 @@ export class MemoryRetriever {
     trace?.startStage("bm25_search", 0);
     trace?.endStage(bm25Results.length, bm25Results.map(r => r.score));
 
-    // Fuse results using RRF (async: validates BM25-only entries exist in store)
+    // Fuse results using weighted score fusion (async: validates BM25-only entries exist in store)
+    const shortQ = isShortQuery(searchQuery);
     trace?.startStage("rrf_fusion", vectorResults.length + bm25Results.length + pprResults.length);
-    const fusedResults = await this.fuseResults(vectorResults, bm25Results, pprResults);
+    const fusedResults = await this.fuseResults(vectorResults, bm25Results, pprResults, shortQ);
     trace?.endStage(fusedResults.length, fusedResults.map(r => r.score));
 
     // Temporal filter: when query has a time constraint, remove non-matching candidates
@@ -582,9 +1063,18 @@ export class MemoryRetriever {
     const multiVecBlended = this.applyMultiVectorBlend(temporalFiltered, searchQuery);
     trace?.endStage(multiVecBlended.length, multiVecBlended.map(r => r.score));
 
+    // P0.1: Anchor boost — short query terms matching short anchor text
+    trace?.startStage("anchor_boost", multiVecBlended.length);
+    const anchorBoosted = applyAnchorBoost(multiVecBlended, searchQuery);
+    trace?.endStage(anchorBoosted.length, anchorBoosted.map(r => r.score));
+
     // Apply minimum score threshold
-    trace?.startStage("min_score_filter", multiVecBlended.length);
-    const filtered = multiVecBlended.filter(r => r.score >= this.config.minScore);
+    trace?.startStage("min_score_filter", anchorBoosted.length);
+    // P0.1: Lower minScore for short queries to widen the candidate pool
+    const effectiveMinScore = isShortQuery(searchQuery)
+      ? this.config.minScore * SHORT_QUERY_MIN_SCORE_FACTOR
+      : this.config.minScore;
+    const filtered = anchorBoosted.filter(r => r.score >= effectiveMinScore);
     trace?.endStage(filtered.length, filtered.map(r => r.score));
 
     // Rerank if enabled
@@ -609,9 +1099,18 @@ export class MemoryRetriever {
     const confidenceWeighted = this.applyConfidence(importanceWeighted);
     trace?.endStage(confidenceWeighted.length, confidenceWeighted.map(r => r.score));
 
+    // Emotion scoring: boost memories matching query emotional tone
+    let afterEmotion = confidenceWeighted;
+    if (isEmotionScoringEnabled()) {
+      const queryEmotion = detectEmotion(query);
+      const adapted = confidenceWeighted.map(r => ({ ...r, metadata: r.entry.metadata ?? "{}" }));
+      const emotioned = applyEmotionWeight(adapted, queryEmotion);
+      afterEmotion = confidenceWeighted.map((r, i) => ({ ...r, score: emotioned[i]?.score ?? r.score }));
+    }
+
     // Prefer higher-authority durable memories over raw evidence when scores are close.
-    trace?.startStage("boundary_weight", confidenceWeighted.length);
-    const boundaryWeighted = this.applyBoundaryWeight(confidenceWeighted);
+    trace?.startStage("boundary_weight", afterEmotion.length);
+    const boundaryWeighted = this.applyBoundaryWeight(afterEmotion);
     trace?.endStage(boundaryWeighted.length, boundaryWeighted.map(r => r.score));
 
     // Separate pinned assets from synthesized briefs.
@@ -629,21 +1128,40 @@ export class MemoryRetriever {
     const timeDecayed = this.applyTimeDecay(lengthNormalized);
     trace?.endStage(timeDecayed.length, timeDecayed.map(r => r.score));
 
+    // B-1/E-1: Evolution decay blend — boost memories with high composite decay score
+    const evolutionBlended = this.applyEvolutionDecayBlend(timeDecayed);
+
+    // E-1: Access count boost — memories retrieved more often get a score nudge
+    const accessBoosted = this.applyAccessCountBoost(evolutionBlended);
+
     // Hotness blend: boost frequently + recently accessed memories
-    trace?.startStage("hotness_blend", timeDecayed.length);
-    const hotnessBlended = this.applyHotnessBlend(timeDecayed);
+    trace?.startStage("hotness_blend", accessBoosted.length);
+    const hotnessBlended = this.applyHotnessBlend(accessBoosted);
     trace?.endStage(hotnessBlended.length, hotnessBlended.map(r => r.score));
 
+    // P0.2: Frequency boost — repeatedly retrieved memories score higher
+    trace?.startStage("frequency_boost", hotnessBlended.length);
+    const frequencyBoosted = this.applyFrequencyBoost(hotnessBlended);
+    trace?.endStage(frequencyBoosted.length, frequencyBoosted.map(r => r.score));
+
     // Hard minimum score cutoff (post all scoring stages)
-    trace?.startStage("hard_min_score", hotnessBlended.length);
-    const hardFiltered = hotnessBlended.filter(r => r.score >= this.minScoreFor(r.entry.category));
+    // P0.1: lower thresholds for short queries (shortQ declared earlier for fuseResults)
+    const rescored = [...frequencyBoosted].sort((a, b) => b.score - a.score);
+
+    trace?.startStage("hard_min_score", rescored.length);
+    const hardFiltered = rescored.filter(r => r.score >= this.minScoreFor(r.entry.category, shortQ));
     trace?.endStage(hardFiltered.length, hardFiltered.map(r => r.score));
 
+    // Evolution status filter: exclude superseded/archived/consolidated memories
+    const evolutionFiltered = includeArchived
+      ? hardFiltered
+      : hardFiltered.filter(r => isActiveMemory(r.entry.metadata));
+
     // Filter noise
-    trace?.startStage("noise_filter", hardFiltered.length);
+    trace?.startStage("noise_filter", evolutionFiltered.length);
     const denoised = this.config.filterNoise
-      ? filterNoise(hardFiltered, r => r.entry.text)
-      : hardFiltered;
+      ? filterNoise(evolutionFiltered, r => r.entry.text)
+      : evolutionFiltered;
     trace?.endStage(denoised.length, denoised.map(r => r.score));
 
     // RIF: demote near-duplicate weak results to improve diversity
@@ -659,8 +1177,16 @@ export class MemoryRetriever {
     // Tier 3.3: Version group dedup — keep only the top-ranked version per group
     const versionDeduped = deduplicateByVersionGroup(deduplicated);
 
-    trace?.startStage("final_limit", versionDeduped.length);
-    const final = versionDeduped.slice(0, limit);
+    // LC-P2: Cluster insight dedup — prefer cluster summary over individual source memories
+    const clusterDeduped = deduplicateByClusterInsight(versionDeduped);
+
+    // Source diversity: round-robin across scopes for multi-session coverage
+    const diversified = (this.config.sourceDiversity ?? 0) > 0
+      ? applySourceDiversity(clusterDeduped, limit)
+      : clusterDeduped;
+
+    trace?.startStage("final_limit", diversified.length);
+    const final = diversified.slice(0, limit);
     trace?.endStage(final.length, final.map(r => r.score));
 
     return final;
@@ -806,7 +1332,18 @@ export class MemoryRetriever {
     vectorResults: Array<MemorySearchResult & { rank: number }>,
     bm25Results: Array<MemorySearchResult & { rank: number }>,
     graphResults: RetrievalResult[] = [],
+    shortQuery: boolean = false,
   ): Promise<RetrievalResult[]> {
+    // Adaptive weights: short queries (≤4 tokens) favor BM25 for exact keyword matching.
+    // For normal queries, use config weights directly.
+    const vW = shortQuery
+      ? this.config.vectorWeight * 0.7
+      : this.config.vectorWeight;
+    const bW = shortQuery
+      ? Math.min(this.config.bm25Weight * 1.5, 0.6)
+      : this.config.bm25Weight;
+    const totalW = vW + bW;
+
     // Create maps for quick lookup
     const vectorMap = new Map<string, MemorySearchResult & { rank: number }>();
     const bm25Map = new Map<string, MemorySearchResult & { rank: number }>();
@@ -827,7 +1364,7 @@ export class MemoryRetriever {
     // Get all unique document IDs
     const allIds = new Set([...vectorMap.keys(), ...bm25Map.keys(), ...graphMap.keys()]);
 
-    // Calculate RRF scores
+    // Calculate fused scores using configurable weights
     const fusedResults: RetrievalResult[] = [];
 
     for (const id of allIds) {
@@ -850,26 +1387,29 @@ export class MemoryRetriever {
       // Use the result with more complete data (prefer vector > graph > BM25)
       const baseResult = vectorResult || graphResult || bm25Result!;
 
-      // Use vector similarity as the base score.
-      // BM25 hit acts as a bonus (keyword match confirms relevance).
-      // Graph hit acts as a bonus (entity relationship confirms relevance).
       const vectorScore = vectorResult ? vectorResult.score : 0;
-      const bm25Hit = bm25Result ? 1 : 0;
+      const bm25Score = bm25Result ? bm25Result.score : 0;
       const graphScore = graphResult?.sources.graph?.score ?? 0;
 
-      // Base = vector score; BM25 hit boosts by up to 15%; graph boosts by up to 20%
-      // Graph-only results use their PPR score so entity-connected memories surface.
       let fusedScore: number;
-      if (vectorResult) {
+      if (vectorResult && bm25Result) {
+        // Both signals agree: weighted average + 5% dual-match confirmation bonus.
+        // Graph hit adds up to 15% on top.
         fusedScore = clamp01(
-          vectorScore + (bm25Hit * 0.15 * vectorScore) + (graphScore * 0.20),
+          ((vW * vectorScore + bW * bm25Score) / totalW) * 1.05 + (graphScore * 0.15),
           0.1,
         );
+      } else if (vectorResult) {
+        // Vector only: semantic match, graph as bonus
+        fusedScore = clamp01(vectorScore + (graphScore * 0.15), 0.1);
       } else if (graphResult) {
-        // Graph-only: use graph score as base, BM25 boosts
-        fusedScore = clamp01(graphScore + (bm25Hit * 0.10), 0.1);
+        // Graph only: entity-relationship match, BM25 as bonus
+        fusedScore = clamp01(graphScore + (bm25Score > 0 ? 0.10 : 0), 0.1);
       } else {
-        fusedScore = clamp01(bm25Result!.score, 0.1);
+        // BM25 only: exact keyword match without semantic confirmation.
+        // Short queries get a small boost since BM25 is more reliable for exact terms.
+        const bm25OnlyBoost = shortQuery ? 1.15 : 1.0;
+        fusedScore = clamp01(bm25Score * bm25OnlyBoost, 0.1);
       }
 
       fusedResults.push({
@@ -1178,22 +1718,33 @@ export class MemoryRetriever {
 
     const now = Date.now();
     const decayed = results.map(r => {
+      // HP-7: Exempt core/pinned/recently-accessed from decay
+      if (isDecayExempt(r.entry.metadata, r.entry.importance)) return r;
+
       const ts = (r.entry.timestamp && r.entry.timestamp > 0) ? r.entry.timestamp : now;
       const ageDays = (now - ts) / 86_400_000;
 
       // Use access-reinforced half-life if tracker is attached
-      const halfLife = this.accessTracker
+      let halfLife = this.accessTracker
         ? this.accessTracker.computeEffectiveHalfLife(baseHalfLife, r.entry.metadata)
         : baseHalfLife;
 
+      // HP-emo: Emotion-adjusted half-life — strong emotion slows forgetting
+      const emotion = isEmotionScoringEnabled() ? parseEmotion(r.entry.metadata) : null;
+      if (emotion) {
+        halfLife = adjustHalfLifeForEmotion(halfLife, emotion);
+      }
+
       // Resolve tier from metadata (defaults to peripheral)
       const tier = resolveTier(r.entry.metadata);
 
       // Weibull decay with tier-specific shape and floor
       const factor = weibullDecay(ageDays, halfLife, tier);
+      // HP-emo: Arousal boost — flashbulb memory effect (1.0–1.1x)
+      const arousalFactor = emotion ? computeArousalBoost(emotion) : 1.0;
       return {
         ...r,
-        score: clamp01(r.score * factor, r.score * 0.3),
+        score: clamp01(r.score * arousalFactor * factor, r.score * 0.3),
       };
     });
 
@@ -1208,6 +1759,214 @@ export class MemoryRetriever {
    *
    * No-op when hotnessWeight is 0 or AccessTracker is absent.
    */
+  /**
+   * B-1/E-1: Evolution decay blend — factor in composite decay score
+   * (time × frequency × importance) as a scoring signal.
+   * Weight increased from 0.05 to 0.10 with B-3 LLM importance assessment.
+   */
+  private applyEvolutionDecayBlend(results: RetrievalResult[]): RetrievalResult[] {
+    const EVOLUTION_BLEND_WEIGHT = 0.10;
+    return results.map(r => {
+      // HP-7: Exempt entries get max decay score (1.0) → no penalty
+      if (isDecayExempt(r.entry.metadata, r.entry.importance)) {
+        return {
+          ...r,
+          score: clamp01(r.score * (1 - EVOLUTION_BLEND_WEIGHT) + 1.0 * EVOLUTION_BLEND_WEIGHT, 0),
+        };
+      }
+      const evo = parseEvolution(r.entry.metadata, r.entry.timestamp);
+      const decay = computeDecayScore(evo, r.entry.importance, undefined, r.entry.metadata);
+      return {
+        ...r,
+        score: clamp01(r.score * (1 - EVOLUTION_BLEND_WEIGHT) + decay * EVOLUTION_BLEND_WEIGHT, 0),
+      };
+    });
+  }
+
+  /**
+   * E-1: Access count boost — memories with higher access_count get a score nudge.
+   * Complements frequency-tracker (query→memory mapping) by operating at
+   * the individual memory level (total retrieval hits across all queries).
+   * Formula: score *= 1 + log2(1 + accessCount) × 0.03, capped at ×1.15.
+   */
+  private applyAccessCountBoost(results: RetrievalResult[]): RetrievalResult[] {
+    return results.map(r => {
+      const evo = parseEvolution(r.entry.metadata, r.entry.timestamp);
+      if (evo.accessCount <= 0) return r;
+      const boost = Math.min(0.15, Math.log2(1 + evo.accessCount) * 0.03);
+      return {
+        ...r,
+        score: clamp01(r.score * (1 + boost), 0),
+      };
+    });
+  }
+
+  /**
+   * Phase 4: Build candidate expansion deps from internal stores.
+   * Each dep is only provided if the corresponding store/feature is available.
+   */
+  private buildExpansionDeps(context: RetrievalContext): CandidateExpansionDeps {
+    const deps: CandidateExpansionDeps = {};
+    const scope = context.scopeFilter?.[0];
+
+    // KG neighbor expansion — requires KG mode + attached KG store
+    if (isKGModeEnabled() && this.kgStore) {
+      const kgStore = this.kgStore;
+      const store = this.store;
+      deps.expandViaKG = async (results) => {
+        // Extract unique source_memory_ids from KG triples linked to result entities
+        const entityNames: string[] = [];
+        for (const r of results.slice(0, 5)) {
+          try {
+            const meta = JSON.parse(r.entry.metadata || "{}");
+            if (meta.kg_entities && Array.isArray(meta.kg_entities)) {
+              entityNames.push(...meta.kg_entities);
+            }
+          } catch (err) { console.error("[recallnest] KG entity extraction failed:", err instanceof Error ? err.message : String(err)); }
+        }
+        if (entityNames.length === 0) return [];
+        const unique = [...new Set(entityNames)].slice(0, 5);
+        const neighborhood = await kgStore.getNeighborhood(unique, 1, scope);
+        const sourceIds = new Set<string>();
+        const existingIds = new Set(results.map(r => r.entry.id));
+        for (const n of neighborhood) {
+          for (const t of n.triples) {
+            if (t.source_memory_id && !existingIds.has(t.source_memory_id)) {
+              sourceIds.add(t.source_memory_id);
+            }
+          }
+        }
+        // Fetch entries by ID
+        const expanded: RetrievalResult[] = [];
+        for (const id of [...sourceIds].slice(0, 5)) {
+          const entry = await store.getById(id);
+          if (entry) {
+            expanded.push({ entry, score: 0.5, sources: {} });
+          }
+        }
+        return expanded;
+      };
+    }
+
+    // Evolution chain expansion — walk supersedes/supersededBy links
+    if (this.store.getById) {
+      const store = this.store;
+      deps.expandViaEvolution = async (results) => {
+        const expanded: RetrievalResult[] = [];
+        const existingIds = new Set(results.map(r => r.entry.id));
+        for (const r of results.slice(0, 5)) {
+          const evo = parseEvolution(r.entry.metadata, r.entry.timestamp);
+          for (const linkedId of [evo.supersedes, evo.supersededBy].filter(Boolean) as string[]) {
+            if (existingIds.has(linkedId)) continue;
+            const entry = await store.getById(linkedId);
+            if (entry) {
+              existingIds.add(linkedId);
+              expanded.push({ entry, score: r.score * 0.6, sources: {} });
+            }
+          }
+        }
+        return expanded;
+      };
+    }
+
+    // Cluster member expansion — get sourceMemories from cluster insights
+    if (this.store.getById) {
+      const store = this.store;
+      deps.expandViaClusters = async (results) => {
+        const expanded: RetrievalResult[] = [];
+        const existingIds = new Set(results.map(r => r.entry.id));
+        for (const r of results.slice(0, 5)) {
+          try {
+            const meta = JSON.parse(r.entry.metadata || "{}");
+            if ((meta.cluster_insight || meta.cross_memory_pattern) && meta.evolution?.sourceMemories) {
+              for (const memberId of (meta.evolution.sourceMemories as string[]).slice(0, 3)) {
+                if (existingIds.has(memberId)) continue;
+                const entry = await store.getById(memberId);
+                if (entry) {
+                  existingIds.add(memberId);
+                  expanded.push({ entry, score: r.score * 0.5, sources: {} });
+                }
+              }
+            }
+          } catch (err) { console.error("[recallnest] Cluster member expansion failed:", err instanceof Error ? err.message : String(err)); }
+        }
+        return expanded;
+      };
+    }
+
+    // Narrative sibling expansion — reuse existing expandNarrativeSiblings logic
+    if (isNarrativeModeEnabled()) {
+      deps.expandViaNarrative = async (results) => {
+        const expanded = await this.expandNarrativeSiblings(results);
+        // Return only the new siblings (not in original results)
+        const existingIds = new Set(results.map(r => r.entry.id));
+        return expanded.filter(r => !existingIds.has(r.entry.id));
+      };
+    }
+
+    return deps;
+  }
+
+  /**
+   * HP-narrative: Expand retrieval results with narrative siblings.
+   * When a retrieved memory has narrative metadata, pull other memories
+   * sharing the same generalEventId to provide temporal context.
+   *
+   * Siblings are added with a dampened score (70% of the triggering result)
+   * and capped at 3 siblings per general event to avoid flooding.
+   */
+  async expandNarrativeSiblings(results: RetrievalResult[]): Promise<RetrievalResult[]> {
+    if (!isNarrativeModeEnabled() || results.length === 0) return results;
+
+    // Collect unique generalEventIds from results
+    const eventIdToScore = new Map<string, number>();
+    const existingIds = new Set(results.map(r => r.entry.id));
+
+    for (const r of results) {
+      const narrative = parseNarrative(r.entry.metadata);
+      if (!narrative) continue;
+      const existing = eventIdToScore.get(narrative.generalEventId);
+      if (!existing || r.score > existing) {
+        eventIdToScore.set(narrative.generalEventId, r.score);
+      }
+    }
+
+    if (eventIdToScore.size === 0) return results;
+
+    // Search store for siblings — use scope-based listing and filter by generalEventId
+    const siblings: RetrievalResult[] = [];
+    const MAX_SIBLINGS_PER_EVENT = 3;
+
+    try {
+      const allEntries = await this.store.list(undefined, undefined, 500, 0);
+      for (const entry of allEntries) {
+        if (existingIds.has(entry.id)) continue;
+        const narrative = parseNarrative(entry.metadata);
+        if (!narrative) continue;
+        const triggerScore = eventIdToScore.get(narrative.generalEventId);
+        if (triggerScore === undefined) continue;
+
+        // Count how many siblings we've already added for this event
+        const eventSiblingCount = siblings.filter(s => {
+          const sn = parseNarrative(s.entry.metadata);
+          return sn?.generalEventId === narrative.generalEventId;
+        }).length;
+        if (eventSiblingCount >= MAX_SIBLINGS_PER_EVENT) continue;
+
+        siblings.push({
+          entry,
+          score: triggerScore * 0.7,
+          sources: { narrativeSibling: true },
+        });
+        existingIds.add(entry.id);
+      }
+    } catch {
+      // Non-blocking — if store listing fails, return original results
+    }
+
+    return [...results, ...siblings].sort((a, b) => b.score - a.score);
+  }
+
   private applyHotnessBlend(results: RetrievalResult[]): RetrievalResult[] {
     const raw = this.config.hotnessWeight;
     const alpha = Math.min(1, Math.max(0, Number.isFinite(raw) ? raw : 0));
@@ -1228,6 +1987,20 @@ export class MemoryRetriever {
     return blended.sort((a, b) => b.score - a.score);
   }
 
+  /**
+   * P0.2: Frequency boost — memories that get repeatedly retrieved score higher.
+   * Unlike hotness (access-tracker based, decay-oriented), this is pure hit-count
+   * boost designed to surface "always relevant" memories like daily patrol rules.
+   */
+  private applyFrequencyBoost(results: RetrievalResult[]): RetrievalResult[] {
+    if (!this.frequencyTracker || results.length === 0) return results;
+    return results.map(r => {
+      const multiplier = this.frequencyTracker!.getBoostMultiplier(r.entry.id);
+      if (multiplier <= 1.0) return r;
+      return { ...r, score: Math.min(1, r.score * multiplier) };
+    });
+  }
+
   /**
    * MMR-inspired diversity filter: greedily select results that are both
    * relevant (high score) and diverse (low similarity to already-selected).