recallnest 1.4.1 → 2.2.1

package/src/rif.ts

@@ -22,34 +22,60 @@ import type { RetrievalResult } from "./retriever.js";
  * @param results - Scored results sorted by score descending
  * @param similarityThreshold - Cosine similarity above which two results are "near-duplicate" (default: 0.85)
  * @param scoreRatio - A result scoring below this ratio of its near-duplicate is demoted (default: 0.80)
+ * @param clusterTopK - F2: Max results per semantic cluster before demotion (default: 3)
  */
 export function filterInterference(
   results: RetrievalResult[],
   similarityThreshold = 0.85,
   scoreRatio = 0.80,
+  clusterTopK = 3,
 ): RetrievalResult[] {
   if (results.length <= 2) return results;
 
   const kept: RetrievalResult[] = [];
   const demoted: RetrievalResult[] = [];
 
+  // F2: Track cluster membership — each kept result seeds or joins a cluster
+  // clusterMap: kept-index → cluster-id
+  const clusterMap: number[] = [];
+  const clusterCounts = new Map<number, number>(); // cluster-id → count
+  let nextClusterId = 0;
+
   for (const candidate of results) {
-    // Check if this candidate is a weak near-duplicate of any kept result
     let isDemoted = false;
+    let matchedClusterId: number | null = null;
 
-    for (const selected of kept) {
-      const sim = cosineSimilarity(candidate.entry.vector, selected.entry.vector);
-      if (sim > similarityThreshold && candidate.score < selected.score * scoreRatio) {
-        isDemoted = true;
+    for (let i = 0; i < kept.length; i++) {
+      const sim = cosineSimilarity(candidate.entry.vector, kept[i].entry.vector);
+      if (sim > similarityThreshold) {
+        matchedClusterId = clusterMap[i];
+        // Original RIF: demote if score too low relative to stronger result
+        if (candidate.score < kept[i].score * scoreRatio) {
+          isDemoted = true;
+          break;
+        }
+        // F2: Cluster top-K — demote if cluster already has K members
+        const count = clusterCounts.get(matchedClusterId) ?? 0;
+        if (count >= clusterTopK) {
+          // Demote with 50% score penalty instead of full demotion
+          demoted.push({ ...candidate, score: candidate.score * 0.5 });
+          isDemoted = true;
+          break;
+        }
         break;
       }
     }
 
-    if (isDemoted) {
-      demoted.push(candidate);
-    } else {
+    if (!isDemoted) {
+      const cid = matchedClusterId ?? nextClusterId++;
+      clusterMap.push(cid);
+      clusterCounts.set(cid, (clusterCounts.get(cid) ?? 0) + 1);
       kept.push(candidate);
+    } else if (matchedClusterId == null) {
+      // Demoted by score ratio, not cluster overflow
+      demoted.push(candidate);
     }
+    // cluster overflow case already pushed to demoted above
   }
 
   // Demoted results go to the end as fallback

package/src/runtime-config.ts

@@ -2,15 +2,17 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 
+import { metaDir } from "./compat.js";
 import { MemoryStore, validateStoragePath } from "./store.js";
 import { createEmbedder, getVectorDimensions, type EmbeddingConfig } from "./embedder.js";
 import { createRetriever, type RetrievalConfig, DEFAULT_RETRIEVAL_CONFIG } from "./retriever.js";
 import { applyRetrievalProfile } from "./retrieval-profiles.js";
 import { AccessTracker } from "./access-tracker.js";
+import { FrequencyTracker } from "./frequency-tracker.js";
 import { createLLMClient, type LLMClient, type LLMConfig } from "./llm-client.js";
 import { logInfo } from "./stderr-log.js";
 
-export type RecallMode = "full" | "summary" | "off";
+export type RecallMode = "full" | "light" | "summary" | "off";
 
 export interface LocalMemoryConfig {
   dbPath: string;
@@ -42,7 +44,7 @@ export interface LocalMemoryConfig {
 }
 
 export function loadDotEnv(): void {
-  const envPath = resolve(import.meta.dir, "../.env");
+  const envPath = resolve(metaDir(import.meta), "../.env");
   if (!existsSync(envPath)) return;
   const content = readFileSync(envPath, "utf-8");
   for (const line of content.split("\n")) {
@@ -60,13 +62,13 @@ export function loadDotEnv(): void {
 export function findConfigPath(): string {
   if (process.env.LOCAL_MEMORY_CONFIG) return resolve(process.env.LOCAL_MEMORY_CONFIG);
 
-  const localConfig = resolve(import.meta.dir, "../config.json");
+  const localConfig = resolve(metaDir(import.meta), "../config.json");
   if (existsSync(localConfig)) return localConfig;
 
   const branded = join(homedir(), ".config", "recallnest", "config.json");
   if (existsSync(branded)) return branded;
 
-  const exampleExists = existsSync(resolve(import.meta.dir, "../config.json.example"));
+  const exampleExists = existsSync(resolve(metaDir(import.meta), "../config.json.example"));
   throw new Error(
     "Config not found.\n" +
     (exampleExists
@@ -95,7 +97,7 @@ export function expandHome(p: string): string {
 }
 
 export function createComponents(config: LocalMemoryConfig, profileName?: string) {
-  const dbPath = resolve(import.meta.dir, "..", expandHome(config.dbPath));
+  const dbPath = resolve(metaDir(import.meta), "..", expandHome(config.dbPath));
   validateStoragePath(dbPath);
 
   const embeddingConfig: EmbeddingConfig = {
@@ -121,6 +123,13 @@ export function createComponents(config: LocalMemoryConfig, profileName?: string
   const accessTracker = new AccessTracker(store);
   retriever.setAccessTracker(accessTracker);
 
+  // P0.2: Attach frequency tracker for hit-count based boosting
+  const dataDir = resolve(metaDir(import.meta), "..", expandHome(config.dbPath), "..");
+  const frequencyTracker = new FrequencyTracker({
+    filePath: join(dataDir, "frequency-stats.json"),
+  });
+  retriever.setFrequencyTracker(frequencyTracker);
+
   // Create LLM client if configured (optional, graceful)
   let llm: LLMClient | null = null;
   if (config.llm) {
@@ -130,11 +139,11 @@ export function createComponents(config: LocalMemoryConfig, profileName?: string
     }
   }
 
-  return { store, embedder, retriever, profile, accessTracker, llm };
+  return { store, embedder, retriever, profile, accessTracker, frequencyTracker, llm };
 }
 
 export function createStoreOnly(config: LocalMemoryConfig): MemoryStore {
-  const dbPath = resolve(import.meta.dir, "..", expandHome(config.dbPath));
+  const dbPath = resolve(metaDir(import.meta), "..", expandHome(config.dbPath));
   validateStoragePath(dbPath);
   return new MemoryStore({
     dbPath,
@@ -144,18 +153,24 @@ export function createStoreOnly(config: LocalMemoryConfig): MemoryStore {
 
 export function createComponentResolver(config: LocalMemoryConfig) {
   const cache = new Map<string, ReturnType<typeof createComponents>>();
+  const MAX_COMPONENT_CACHE_SIZE = 32;
 
   return function getComponents(profileName?: string) {
     const key = profileName || "default";
     const cached = cache.get(key);
     if (cached) return cached;
+    // Evict oldest entry if cache is full
+    if (cache.size >= MAX_COMPONENT_CACHE_SIZE) {
+      const firstKey = cache.keys().next().value;
+      if (firstKey !== undefined) cache.delete(firstKey);
+    }
     const created = createComponents(config, profileName);
     cache.set(key, created);
     return created;
   };
 }
 
-const VALID_RECALL_MODES: RecallMode[] = ["full", "summary", "off"];
+const VALID_RECALL_MODES: RecallMode[] = ["full", "light", "summary", "off"];
 
 /**
  * Resolve effective recall mode: per-call override > env var > config > default ("summary").

package/src/scope-inventory.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
+import { metaDir } from "./compat.js";
 import { suppressesLegacyScopeIssue } from "./legacy-scope-review.js";
 import { classifyLegacyScope, type LegacyScopeAudit, type LegacyScopeIssueKind, type MemoryStore } from "./store.js";
 
@@ -205,9 +206,9 @@ export async function collectScopeInventory(options: ScopeInventoryOptions): Pro
     recommendation: "Migrate or delete historical unscoped memory rows before removing compatibility shims.",
   };
 
-  const pinsDir = options.pinsDir || resolve(import.meta.dir, "../data/pins");
-  const checkpointsDir = options.checkpointsDir || resolve(import.meta.dir, "../data/session-checkpoints");
-  const workflowObservationsDir = options.workflowObservationsDir || resolve(import.meta.dir, "../data/workflow-observations");
+  const pinsDir = options.pinsDir || resolve(metaDir(import.meta), "../data/pins");
+  const checkpointsDir = options.checkpointsDir || resolve(metaDir(import.meta), "../data/session-checkpoints");
+  const workflowObservationsDir = options.workflowObservationsDir || resolve(metaDir(import.meta), "../data/workflow-observations");
 
   const pinLayer = scanJsonLayer({
     dir: pinsDir,

package/src/scope-policy.ts

@@ -137,6 +137,10 @@ export function buildRetrievalContext(
     includeArchived: base.includeArchived,
     trace: base.trace,
     graph: base.graph,
+    topicTag: base.topicTag,
+    reconstruct: base.reconstruct,
+    validAt: base.validAt,
+    includeExpired: base.includeExpired,
     scopeFilter: selection.scopeFilter,
   };
 }

package/src/session-distiller.ts

@@ -0,0 +1,307 @@
+import type { LLMClient } from "./llm-client.js";
+import type { Embedder } from "./embedder.js";
+import type { MemoryStore } from "./store.js";
+import type { ConflictCandidateStore } from "./conflict-store.js";
+import type { KGExtractor } from "./kg-extractor.js";
+import type { AuditLogger } from "./audit-log.js";
+import type { StoredMemoryRecord, DurableMemoryCategory } from "./memory-schema.js";
+import { persistMemory } from "./capture-engine.js";
+import { detectLang, getSessionPromptHook } from "./language-hook.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ConversationMessage {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+  tool_name?: string;
+  timestamp?: string;
+}
+
+export interface MicrocompactResult {
+  tokens_freed: number;
+  tools_cleared: number;
+}
+
+export interface SummaryResult {
+  text: string;
+  dimensions: Record<string, string>;
+}
+
+export interface PersistResult {
+  memories_stored: number;
+  memories_deduped: number;
+  memories_conflicted: number;
+  ids: string[];
+}
+
+export interface DistillResult {
+  microcompact: MicrocompactResult;
+  summary: SummaryResult;
+  persisted: PersistResult;
+  compacted_messages: ConversationMessage[];
+}
+
+interface PersistDeps {
+  store: Pick<MemoryStore, "store" | "list" | "update" | "getById" | "get" | "vectorSearch">;
+  embedder: Pick<Embedder, "embedPassage">;
+  conflictStore?: Pick<ConflictCandidateStore, "save" | "replace" | "getOpenByFingerprint" | "getLatestByFingerprint">;
+  llm?: LLMClient | null;
+  kgExtractor?: KGExtractor | null;
+  auditLogger?: AuditLogger | null;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const CLEARABLE_TOOLS = new Set([
+  "read_file", "bash", "grep", "glob", "web_search", "web_fetch",
+  "edit_file", "write_file", "Read", "Write", "Edit", "Bash",
+  "Grep", "Glob", "WebSearch", "WebFetch",
+]);
+
+// Session summary fallback prompts (used when babel-memory is not installed)
+
+const DEFAULT_DIMENSION_LABELS: Record<string, string> = {
+  user_intent: "User intent and requests",
+  technical_concepts: "Key technical concepts",
+  files_and_code: "Files and code segments involved",
+  errors_and_fixes: "Errors and fix records",
+  problem_solving: "Problem solving process",
+  user_quotes: "User original quotes preserved",
+  unfinished_tasks: "Unfinished tasks",
+  current_state: "Current work state",
+  next_steps: "Suggested next steps",
+};
+
+const DEFAULT_SESSION_SYSTEM = `You are a session summarizer. Analyze the conversation and produce a structured summary.
+Wrap the summary in <summary></summary> tags.
+Use numbered ## headings for each dimension:
+${Object.entries(DEFAULT_DIMENSION_LABELS).map(([, label], i) => `## ${i + 1}. ${label}`).join("\n")}
+If a dimension has no relevant content, write "N/A".`;
+
+interface DimensionMapping {
+  category: DurableMemoryCategory;
+  importance: number;
+}
+
+const DIMENSION_TO_MEMORY: Record<string, DimensionMapping> = {
+  user_intent: { category: "events", importance: 0.5 },
+  files_and_code: { category: "entities", importance: 0.6 },
+  errors_and_fixes: { category: "cases", importance: 0.7 },
+  problem_solving: { category: "patterns", importance: 0.8 },
+  user_quotes: { category: "preferences", importance: 0.7 },
+};
+
+// ============================================================================
+// Layer 1: Microcompact
+// ============================================================================
+
+export function microcompact(
+  messages: ConversationMessage[],
+  opts: { preserveRecent?: number; keepRecentTools?: number } = {},
+): { messages: ConversationMessage[]; result: MicrocompactResult } {
+  const preserveRecent = opts.preserveRecent ?? 6;
+  const keepRecentTools = opts.keepRecentTools ?? 5;
+
+  if (messages.length === 0) {
+    return { messages: [], result: { tokens_freed: 0, tools_cleared: 0 } };
+  }
+
+  const cutoff = Math.max(0, messages.length - preserveRecent);
+  let tokensFreed = 0;
+  let toolsCleared = 0;
+
+  // Find tool messages eligible for clearing (before the preserve window)
+  const toolIndices: number[] = [];
+  for (let i = 0; i < cutoff; i++) {
+    const msg = messages[i];
+    if (msg.role === "tool" && msg.tool_name && CLEARABLE_TOOLS.has(msg.tool_name)) {
+      toolIndices.push(i);
+    }
+  }
+
+  // Keep the most recent N tool results even if they're before the cutoff
+  const indicesToClear = new Set(
+    toolIndices.slice(0, Math.max(0, toolIndices.length - keepRecentTools)),
+  );
+
+  const compacted: ConversationMessage[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (indicesToClear.has(i)) {
+      const tokenCount = Math.ceil(msg.content.length / 4);
+      tokensFreed += tokenCount;
+      toolsCleared++;
+      compacted.push({
+        ...msg,
+        content: `[Cleared: ${msg.tool_name}, ~${tokenCount} tokens]`,
+      });
+    } else {
+      compacted.push({ ...msg });
+    }
+  }
+
+  return {
+    messages: compacted,
+    result: { tokens_freed: tokensFreed, tools_cleared: toolsCleared },
+  };
+}
+
+// ============================================================================
+// Layer 2: LLM Structured Summary
+// ============================================================================
+
+export async function summarizeSession(
+  messages: ConversationMessage[],
+  llm: LLMClient,
+): Promise<SummaryResult> {
+  const conversationText = messages
+    .map((m) => `[${m.role}${m.tool_name ? `:${m.tool_name}` : ""}] ${m.content.slice(0, 500)}`)
+    .join("\n")
+    .slice(0, 8000);
+
+  // Use babel-memory bilingual prompt if available, otherwise fallback to defaults
+  const lang = detectLang(conversationText);
+  const babelPrompt = getSessionPromptHook(lang);
+  const sessionSystemPrompt = babelPrompt?.system ?? DEFAULT_SESSION_SYSTEM;
+  const dimensionLabels = babelPrompt?.dimensionLabels ?? DEFAULT_DIMENSION_LABELS;
+  const dimensionKeys = Object.keys(dimensionLabels);
+
+  const raw = await llm.chatLong(sessionSystemPrompt, conversationText, 2000);
+
+  if (!raw) {
+    return { text: "", dimensions: {} };
+  }
+
+  // Extract <summary> block, discard <analysis>
+  const summaryMatch = raw.match(/<summary>([\s\S]*?)<\/summary>/);
+  const summaryText = summaryMatch ? summaryMatch[1].trim() : raw;
+
+  // Parse dimensions from ## headings
+  const dimensions: Record<string, string> = {};
+  const sections = summaryText.split(/^## \d+\.\s*/m).filter(Boolean);
+
+  for (const section of sections) {
+    const firstLine = section.split("\n")[0].trim().toLowerCase();
+    for (const key of dimensionKeys) {
+      const label = dimensionLabels[key].toLowerCase();
+      if (firstLine.includes(label) || label.includes(firstLine.replace(/\s+/g, " ").trim())) {
+        const body = section.split("\n").slice(1).join("\n").trim();
+        if (body && body !== "N/A") {
+          dimensions[key] = body;
+        }
+        break;
+      }
+    }
+  }
+
+  return { text: summaryText, dimensions };
+}
+
+// ============================================================================
+// Layer 3: Extract and Persist
+// ============================================================================
+
+export async function extractAndPersist(
+  summary: SummaryResult,
+  deps: PersistDeps,
+  scope: string,
+): Promise<PersistResult> {
+  const result: PersistResult = {
+    memories_stored: 0,
+    memories_deduped: 0,
+    memories_conflicted: 0,
+    ids: [],
+  };
+
+  for (const [dimKey, mapping] of Object.entries(DIMENSION_TO_MEMORY)) {
+    const dimText = summary.dimensions[dimKey];
+    if (!dimText || dimText.trim().length < 10) continue;
+
+    try {
+      const stored = await persistMemory(deps, {
+        text: dimText.slice(0, 4000),
+        category: mapping.category,
+        importance: mapping.importance,
+        scope,
+        source: "agent" as const,
+        tags: ["session_distill", dimKey],
+      });
+
+      trackDisposition(result, stored);
+    } catch {
+      // Non-fatal: continue with other dimensions
+    }
+  }
+
+  return result;
+}
+
+function trackDisposition(result: PersistResult, stored: StoredMemoryRecord): void {
+  result.ids.push(stored.id);
+  switch (stored.disposition) {
+    case "deduped":
+      result.memories_deduped++;
+      break;
+    case "conflict":
+      result.memories_conflicted++;
+      break;
+    default:
+      result.memories_stored++;
+      break;
+  }
+}
+
+// ============================================================================
+// Full Pipeline
+// ============================================================================
+
+export async function distillSession(
+  messages: ConversationMessage[],
+  deps: PersistDeps & { llm: LLMClient },
+  opts: {
+    scope?: string;
+    preserveRecent?: number;
+    keepRecentTools?: number;
+    persist?: boolean;
+  } = {},
+): Promise<DistillResult> {
+  const scope = opts.scope || "default";
+  const shouldPersist = opts.persist ?? true;
+
+  // Layer 1: Microcompact
+  const { messages: compacted, result: microcompactResult } = microcompact(
+    messages,
+    { preserveRecent: opts.preserveRecent, keepRecentTools: opts.keepRecentTools },
+  );
+
+  // Layer 2: Summarize (using compacted messages minus preserved recent)
+  const preserveRecent = opts.preserveRecent ?? 6;
+  const cutoff = Math.max(0, compacted.length - preserveRecent);
+  const oldMessages = compacted.slice(0, cutoff);
+  const summaryResult = oldMessages.length > 0
+    ? await summarizeSession(oldMessages, deps.llm)
+    : { text: "", dimensions: {} };
+
+  // Layer 3: Persist (optional)
+  let persistResult: PersistResult = {
+    memories_stored: 0,
+    memories_deduped: 0,
+    memories_conflicted: 0,
+    ids: [],
+  };
+
+  if (shouldPersist && Object.keys(summaryResult.dimensions).length > 0) {
+    persistResult = await extractAndPersist(summaryResult, deps, scope);
+  }
+
+  return {
+    microcompact: microcompactResult,
+    summary: summaryResult,
+    persisted: persistResult,
+    compacted_messages: compacted,
+  };
+}

package/src/session-output.ts

@@ -82,6 +82,41 @@ export function formatResumeContext(response: ResumeContextResponse): string {
     ...listBlock("Recent cases", response.recentCases),
   );
 
+  // CC-7: Collapsed items with renderLevel + staleness hints
+  if (response.collapsedItems && response.collapsedItems.length > 0) {
+    lines.push("Collapsed context (mixed granularity):");
+    for (const item of response.collapsedItems) {
+      const hint = item.stalenessHint ? ` ${item.stalenessHint}` : "";
+      lines.push(`[${item.renderLevel}] ${item.text}${hint}`);
+    }
+  }
+
+  // CC-8: Essential context (pinned memories, active patterns, open loops)
+  if (response.essentialContext) {
+    const ec = response.essentialContext;
+    const hasContent = (ec.pinnedMemories && ec.pinnedMemories.length > 0)
+      || (ec.activePatterns && ec.activePatterns.length > 0)
+      || (ec.openLoops && ec.openLoops.length > 0);
+    if (hasContent) {
+      lines.push("Essential context:");
+      if (ec.pinnedMemories && ec.pinnedMemories.length > 0) {
+        for (const pin of ec.pinnedMemories) {
+          lines.push(`- Pinned: ${pin}`);
+        }
+      }
+      if (ec.activePatterns && ec.activePatterns.length > 0) {
+        for (const pattern of ec.activePatterns) {
+          lines.push(`- Pattern: ${pattern}`);
+        }
+      }
+      if (ec.openLoops && ec.openLoops.length > 0) {
+        for (const loop of ec.openLoops) {
+          lines.push(`- Open loop: ${loop}`);
+        }
+      }
+    }
+  }
+
   if (response.latestCheckpoint) {
     lines.push("Latest checkpoint:");
     lines.push(`Session: ${response.latestCheckpoint.sessionId}`);
@@ -92,5 +127,10 @@ export function formatResumeContext(response: ResumeContextResponse): string {
     lines.push(`Summary: ${response.latestCheckpoint.summary}`);
   }
 
+  // CC-1: Injection hint for prompt placement
+  if (response.injectionHint) {
+    lines.push(`Injection hint: ${response.injectionHint} (place recalled context as user message attachment for better prompt cache hit rate)`);
+  }
+
   return lines.join("\n");
 }

package/src/session-schema.ts

@@ -40,15 +40,51 @@ export const ResumeCheckpointSummarySchema = z.object({
 
 export const ResumeResponseModeSchema = z.enum(["default", "recall-only"]);
 
+export const CollapsedItemSchema = z.object({
+  entryId: z.string(),
+  text: z.string(),
+  renderLevel: z.enum(["L0", "L1", "L2"]),
+  stalenessHint: z.string().optional(),
+});
+
+/** CC-8: Essential context reconstructed after compact — pinned memories, active patterns, open loops. */
+export const EssentialContextSchema = z.object({
+  pinnedMemories: z.array(z.string()).max(3).optional(),
+  activePatterns: z.array(z.string()).max(2).optional(),
+  openLoops: z.array(z.string()).max(3).optional(),
+});
+
 export const ResumeContextResponseSchema = z.object({
   summary: boundedStringSchema("summary", 800),
   resolvedScope: optionalBoundedStringSchema(160),
   stableContext: normalizedStringListSchema("stableContext", 6, 220),
   relevantPatterns: normalizedStringListSchema("relevantPatterns", 6, 220),
   recentCases: normalizedStringListSchema("recentCases", 6, 220),
+  /** CC-7: Mixed-granularity collapsed view of all recalled items. */
+  collapsedItems: z.array(CollapsedItemSchema).max(20).optional(),
+  /** CC-8: Essential context reconstructed after compact. */
+  essentialContext: EssentialContextSchema.optional(),
   latestCheckpoint: ResumeCheckpointSummarySchema.optional(),
+  /** CC-1: Hint for where to inject recalled context in the prompt. */
+  injectionHint: z.enum(["system_prompt", "user_attachment"]).default("user_attachment").optional(),
+  /** Upstream #345: Mark recalled context as ephemeral — host should discard on compaction, not persist to transcript. */
+  ephemeral: z.boolean().default(true).optional(),
   responseMode: ResumeResponseModeSchema.default("default"),
   responseGuidance: optionalBoundedStringSchema(400),
+  /** Constructive retrieval: LLM-synthesized reconstruction of context. */
+  reconstructedContext: z.string().max(2000).optional(),
+  /** Confidence score (0-1) for the reconstructed context. */
+  reconstructionConfidence: z.number().min(0).max(1).optional(),
+  /** Phase 4: Contradictions detected during reconstruction. */
+  reconstructionContradictions: z.array(z.object({
+    memoryIds: z.tuple([z.string(), z.string()]),
+    description: z.string().max(300),
+  })).max(5).optional(),
+  /** HP-narrative: Memories grouped by autobiographical life period. */
+  narrativeGroups: z.array(z.object({
+    period: z.string().max(120),
+    items: z.array(z.string().max(240)).max(5),
+  })).max(10).optional(),
   generatedAt: z.string().datetime(),
 });
 
@@ -56,5 +92,6 @@ export type SessionCheckpointInput = z.infer<typeof SessionCheckpointInputSchema
 export type SessionCheckpointRecord = z.infer<typeof SessionCheckpointRecordSchema>;
 export type ResumeContextRequest = z.infer<typeof ResumeContextRequestSchema>;
 export type ResumeContextResponse = z.infer<typeof ResumeContextResponseSchema>;
+export type EssentialContext = z.infer<typeof EssentialContextSchema>;
 export type RetrievalProfileName = z.infer<typeof RetrievalProfileSchema>;
 export type ResumeResponseMode = z.infer<typeof ResumeResponseModeSchema>;

package/src/session-store.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
+import { metaDir } from "./compat.js";
 import type { SessionCheckpointRecord } from "./session-schema.js";
 import { SessionCheckpointRecordSchema } from "./session-schema.js";
 import { normalizeCheckpointScope, type CheckpointQuality } from "./session-engine.js";
@@ -66,7 +67,7 @@ export interface CheckpointGcResult {
 }
 
 export class SessionCheckpointStore {
-  constructor(private readonly dir = resolve(import.meta.dir, "../data/session-checkpoints")) {}
+  constructor(private readonly dir = resolve(metaDir(import.meta), "../data/session-checkpoints")) {}
 
   get dataDir(): string {
     return ensureDir(this.dir);
@@ -76,7 +77,11 @@ export class SessionCheckpointStore {
     const parsed = SessionCheckpointRecordSchema.parse(record);
     const timestampToken = parsed.updatedAt.replace(/[:.]/g, "-");
     const path = join(this.dataDir, `${timestampToken}-${parsed.checkpointId}.json`);
-    writeFileSync(path, JSON.stringify(parsed, null, 2) + "\n");
+    try {
+      writeFileSync(path, JSON.stringify(parsed, null, 2) + "\n");
+    } catch (err) {
+      console.error("[recallnest] Failed to save session checkpoint:", err instanceof Error ? err.message : String(err));
+    }
     return parsed;
   }