recallnest 1.4.1 → 2.2.1

package/src/mcp-server.ts

@@ -31,10 +31,12 @@ const TOOL_TIERS: Record<string, ToolTier> = {
   store_memory: "core",
   checkpoint_session: "core",
   latest_checkpoint: "core",
+  list_tools: "core",
 
   set_reminder: "core",
 
   // Advanced
+  batch_store: "advanced",
   auto_capture: "advanced",
   store_case: "advanced",
   store_workflow_pattern: "advanced",
@@ -46,8 +48,18 @@ const TOOL_TIERS: Record<string, ToolTier> = {
   list_assets: "advanced",
   list_pins: "advanced",
   memory_stats: "advanced",
+  data_checkup: "advanced",
+  memory_lint: "advanced",
+  export_graph: "advanced",
+  dream: "advanced",
   memory_drill_down: "advanced",
   export_memory: "advanced",
+  store_skill: "advanced",
+  retrieve_skill: "advanced",
+  import_conversations: "advanced",
+  distill_session: "advanced",
+  scan_skill_promotions: "governance",
+  forget_memory: "advanced",
 
   // Governance (CLI-only, not in MCP by default)
   workflow_observe: "governance",
@@ -71,21 +83,25 @@ function shouldRegisterTool(toolName: string): boolean {
   return true;
 }
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { autoRegisterBabelMemory } from "./language-hook.js";
 import { z } from "zod";
 import type { RetrievalResult } from "./retriever.js";
 import type { MemoryStore } from "./store.js";
-import { distillResults, formatExplainResults, formatSearchResults, selectBriefSeedResults, summarizeResults } from "./memory-output.js";
+import { distillResults, formatExplainResults, formatSearchResults, formatBriefResults, formatFullResults, selectBriefSeedResults, summarizeResults } from "./memory-output.js";
 import { archiveDirtyBriefAsset, assetSummaryLine, buildBriefAsset, buildPinAsset, listDirtyBriefAssets, listMemoryAssets, listPinAssets, saveBriefAsset, savePinAsset, writeExportArtifact } from "./memory-assets.js";
 import { indexAsset, indexPinnedAsset } from "./asset-sync.js";
 import { createComponentResolver, loadConfig, loadDotEnv, resolveRecallMode } from "./runtime-config.js";
-import { DurableMemoryCategorySchema, StoreMemorySourceSchema } from "./memory-schema.js";
+import { DurableMemoryCategorySchema, StoreMemorySourceSchema, PrivacyTierSchema, isPredictiveMemoryEnabled } from "./memory-schema.js";
 import { persistCaseMemory, persistMemory, persistMemoryBatch, persistWorkflowPattern, promoteMemory } from "./capture-engine.js";
+import { persistSkill, retrieveSkills } from "./skill-engine.js";
+import { SkillImplementationTypeSchema } from "./skill-schema.js";
+import { scanForPromotions, formatPromotionResult } from "./skill-promotion.js";
 import { autoCapture } from "./capture-heuristic.js";
 import { ConsolidationEngine, formatConsolidationResult } from "./consolidation-engine.js";
 import { renderMemories, type RenderMode } from "./context-renderer.js";
 import { buildSessionCheckpointResult } from "./session-engine.js";
 import { SessionCheckpointStore } from "./session-store.js";
-import { composeResumeContext } from "./context-composer.js";
+import { composeLightResumeContext, composeResumeContext } from "./context-composer.js";
 import { formatCheckpointSaved, formatCheckpointSummary, formatResumeContext } from "./session-output.js";
 import { ConflictStatusSchema } from "./conflict-schema.js";
 import { KGStore } from "./kg-store.js";
@@ -93,6 +109,10 @@ import { createKGExtractor, isKGModeEnabled, type KGExtractor } from "./kg-extra
 import { resolveConflictCandidate } from "./conflict-engine.js";
 import { escalateConflicts } from "./conflict-escalation.js";
 import { ConflictCandidateStore } from "./conflict-store.js";
+import { runDataCheckup, formatCheckupReport } from "./data-checkup.js";
+import { runMemoryLint, formatMemoryLintReport } from "./memory-lint.js";
+import { exportMemoryGraph, formatGraphExportResult } from "./graph-export.js";
+import { runDream, formatDreamResult } from "./dream-pipeline.js";
 import { formatConflictAudit, formatConflictClusters, formatConflictEscalation, formatConflictList, formatConflictRecord, formatConflictResolution } from "./conflict-output.js";
 import { CONFLICT_ATTENTION_LEVELS, summarizeConflictLifecycle } from "./conflict-lifecycle.js";
 import { buildConflictAuditSummary, clusterConflicts } from "./conflict-advisor.js";
@@ -103,7 +123,11 @@ import { WorkflowObservationStore } from "./workflow-observation-store.js";
 import { buildManagedCheckpointObservation, buildManagedResumeObservation } from "./workflow-observation-managed.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
 import { matchesTemporalConstraint, type TemporalConstraint } from "./temporal-parser.js";
-import { setReminder, checkTriggers, fireReminder, formatReminders } from "./prospective-memory.js";
+import { setReminder, checkTriggers, fireReminder, formatReminders, suggestPredictedReminders, formatSuggestedReminders, acceptPredictedReminder, demotePredictedReminder } from "./prospective-memory.js";
+import type { PredictionContext } from "./prediction-engine.js";
+import { forgetMemory, forgetByScope } from "./forget-engine.js";
+import { createAuditLogger } from "./audit-log.js";
+// distill_session uses dynamic import("./session-distiller.js") at call time
 
 function entryToRetrievalResult(entry: Awaited<ReturnType<MemoryStore["get"]>>): RetrievalResult {
   if (!entry) {
@@ -167,12 +191,16 @@ const server = new McpServer({
 type ToolSchema = Parameters<typeof server.tool>[2];
 type ToolHandler = Parameters<typeof server.tool>[3];
 
+/** Map of all registered tool names to their descriptions (populated during registration). */
+const TOOL_DESCRIPTIONS = new Map<string, string>();
+
 function registerTool(name: string, description: string, schema: ToolSchema, handler: ToolHandler): void {
   if (!shouldRegisterTool(name)) {
     // stdout is reserved for MCP JSON-RPC on stdio transports.
     console.error(`[MCP] Skipping ${name} (tier: ${TOOL_TIERS[name]})`);
     return;
   }
+  TOOL_DESCRIPTIONS.set(name, description);
   server.tool(name, description, schema, handler);
 }
 
@@ -214,7 +242,7 @@ registerTool(
 
 registerTool(
   "workflow_health",
-  "Inspect workflow observation health. With workflowId, return a 7d/30d health report; without workflowId, return a dashboard of the most degraded workflows.",
+  "Inspect workflow observation health: 7d/30d report for one workflow or dashboard of degraded workflows. Read-only. Use when checking if continuity primitives are succeeding or degrading.",
   {
     workflowId: z.string().min(1).max(120).optional().describe("Optional workflow primitive id"),
     scope: z.string().min(1).max(160).optional().describe("Optional scope filter"),
@@ -235,10 +263,10 @@ registerTool(
 
 registerTool(
   "workflow_evidence",
-  "Generate an evidence pack for a workflow primitive, including recent issue observations, top signals, and suggested next actions.",
+  "Generate an evidence pack for a workflow primitive with recent issues, top signals, and suggested actions. Read-only. Use when investigating why a workflow is degraded and you need concrete failure examples.",
   {
-    workflowId: z.string().min(1).max(120).describe("Workflow primitive id"),
-    scope: z.string().min(1).max(160).optional().describe("Optional scope filter"),
+    workflowId: z.string().min(1).max(120).describe("Workflow primitive id, e.g. 'resume_context'"),
+    scope: z.string().min(1).max(160).optional().describe("Scope filter, e.g. 'project:recallnest'"),
     limit: z.number().int().min(1).max(20).default(5).describe("Max recent issue observations to include"),
   },
   async ({ workflowId, scope, limit }) => {
@@ -267,8 +295,19 @@ registerTool(
     source: StoreMemorySourceSchema.default("manual").describe("How this memory was captured"),
     tags: z.array(z.string().min(1).max(40)).max(8).default([]).describe("Optional tags"),
     canonicalKey: z.string().min(1).max(120).optional().describe("Optional stable key for merge/update semantics"),
+    topicTag: z.string().min(1).max(60).optional().describe("Optional topic tag for intra-scope partitioning (e.g. 'auth', 'deploy', 'testing'). Auto-detected if omitted."),
+    privacyTier: PrivacyTierSchema.default("durable").describe("Privacy tier: ephemeral (auto-expire, no KG), private (persist, no KG), durable (default), shared (cross-scope)"),
+    validUntil: z.union([z.string(), z.number()]).optional().describe("Optional expiration: ISO date string or ms timestamp. Memory will be deprioritized after this time."),
+    eventTime: z.union([z.string(), z.number()]).optional().describe("Optional event time: when the event actually happened (ISO date or ms), distinct from storage time."),
+    confidence: z.union([
+      z.number().min(0).max(1),
+      z.object({
+        score: z.number().min(0).max(1),
+        reliability: z.enum(["direct", "inferred", "hearsay"]).optional(),
+      }),
+    ]).optional().describe("Optional confidence override: number (0-1) or {score, reliability}. Auto-assigned from source if omitted."),
   },
-  async ({ text, category, importance, scope, source, tags, canonicalKey }) => {
+  async ({ text, category, importance, scope, source, tags, canonicalKey, topicTag, privacyTier, validUntil, eventTime, confidence }) => {
     const { store, embedder } = getComponents();
     const stored = await persistMemory({
       store,
@@ -283,6 +322,13 @@ registerTool(
       source,
       tags,
       canonicalKey,
+      topicTag,
+      privacyTier,
+      // F3: Pass temporal validity params (extracted by persistMemory before Zod parse)
+      validUntil,
+      eventTime,
+      // F1: Pass confidence override (extracted by persistMemory before Zod parse)
+      confidence,
     });
 
     return {
@@ -357,7 +403,7 @@ registerTool(
 
 registerTool(
   "set_reminder",
-  "Set a prospective memory reminder: 'next time X comes up, remind me about Y'. The reminder is stored and automatically triggered during future retrievals when the trigger condition is matched.",
+  "Set a prospective memory reminder that auto-triggers during future search_memory calls when the trigger keywords match. Side effect: stores a reminder entry. Use when you need a future nudge tied to a specific context.",
   {
     trigger: z.string().min(1).max(200).describe("Trigger condition — keywords that should activate this reminder"),
     action: z.string().min(1).max(500).describe("What to remind about when the trigger fires"),
@@ -505,7 +551,7 @@ registerTool(
 
 registerTool(
   "promote_memory",
-  "Promote an evidence memory into durable memory. Use this when a transcript snippet or imported artifact contains a fact worth keeping across windows, and you want an explicit authority upgrade instead of leaving it as raw evidence.",
+  "Promote an evidence memory into durable memory with an authority upgrade. Side effect: creates a new durable entry linked to the source evidence. Use when a transcript snippet or imported artifact contains a fact worth keeping across windows.",
   {
     memoryId: z.string().min(1).max(128).describe("Existing evidence memory ID or unique prefix"),
     text: z.string().min(1).max(4000).optional().describe("Optional cleaned durable text; defaults to the source entry text"),
@@ -547,9 +593,9 @@ registerTool(
 
 registerTool(
   "list_conflicts",
-  "List or inspect open conflict candidates when incoming evidence promotions disagree with an existing durable memory for the same canonical key.",
+  "List or inspect conflict candidates where promoted evidence disagrees with existing durable memory. Read-only. Use when reviewing pending conflicts before resolution.",
   {
-    conflictId: z.string().min(1).max(128).optional().describe("Optional conflict ID to inspect a single record"),
+    conflictId: z.string().min(1).max(128).optional().describe("Conflict ID to inspect a single record, e.g. 'c1d2e3f4'"),
     status: ConflictStatusSchema.optional().describe("Optional status filter"),
     attention: z.enum(CONFLICT_ATTENTION_LEVELS).optional().describe("Optional lifecycle filter: fresh / aging / stale / escalated / resolved"),
     canonicalKey: z.string().min(1).max(120).optional().describe("Optional canonical key filter"),
@@ -583,7 +629,7 @@ registerTool(
 
 registerTool(
   "resolve_conflict",
-  "Resolve a stored conflict candidate by keeping the existing durable memory, accepting the incoming promoted evidence, or merging the two texts.",
+  "Resolve a conflict candidate by keeping existing, accepting incoming, or merging texts. Side effect: updates conflict status and may modify durable memory. Use when list_conflicts shows open conflicts that need a decision.",
   {
     conflictId: z.string().min(1).max(128).describe("Conflict ID to resolve"),
     resolution: z.enum(["accept_incoming", "keep_existing", "merge"]).describe("How to resolve the conflict"),
@@ -614,7 +660,7 @@ registerTool(
 
 registerTool(
   "audit_conflicts",
-  "Generate a terminal-friendly conflict audit summary so you can see which stale or escalated conflict clusters should be reviewed first.",
+  "Generate a conflict audit summary showing priority clusters by staleness and escalation level. Read-only. Use when triaging which conflict clusters to resolve first.",
   {
     status: ConflictStatusSchema.optional().describe("Optional status filter"),
     canonicalKey: z.string().min(1).max(120).optional().describe("Optional canonical key filter"),
@@ -639,7 +685,7 @@ registerTool(
 
 registerTool(
   "escalate_conflicts",
-  "Preview or apply the conflict aging policy so stale or escalated open conflicts are explicitly marked for operator review.",
+  "Preview or apply conflict aging policy to mark stale conflicts for operator review. Side effect: when apply=true, persists escalation metadata. Use when conflicts have aged past their attention threshold.",
   {
     attention: z.enum(["stale", "escalated"]).default("stale").describe("Only consider stale or escalated conflicts"),
     canonicalKey: z.string().min(1).max(120).optional().describe("Optional canonical key filter"),
@@ -712,10 +758,10 @@ registerTool(
 
 registerTool(
   "latest_checkpoint",
-  "Fetch the latest saved checkpoint for a session or shared scope. Useful for inspecting current work state before resume_context exists.",
+  "Fetch the most recent saved checkpoint for a session or shared scope. Read-only. Use when you need to inspect current work state without running a full resume_context.",
   {
-    sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier filter"),
-    scope: z.string().min(1).max(160).optional().describe("Optional shared scope filter"),
+    sessionId: z.string().min(1).max(160).optional().describe("Session identifier filter, e.g. 'abc123'"),
+    scope: z.string().min(1).max(160).optional().describe("Shared scope filter, e.g. 'project:recallnest'"),
   },
   async ({ sessionId, scope }) => {
     const latest = await checkpointStore.getLatest({ sessionId, scope });
@@ -730,7 +776,7 @@ registerTool(
 
 registerTool(
   "resume_context",
-  "Compose startup context for a fresh window by combining stable durable memory, relevant patterns and cases, plus the latest checkpoint for the current scope or session.",
+  "Compose startup context for a fresh window by combining durable memory, patterns, cases, and the latest checkpoint. Read-only. Use when entering a new session and you need to recover prior decisions, open loops, and next actions.",
   {
     task: z.string().min(1).max(500).optional().describe("Optional current task or question to bias recall"),
     scope: z.string().min(1).max(160).optional().describe("Optional shared scope for project or terminal continuity"),
@@ -738,7 +784,7 @@ registerTool(
     limitPerSection: z.number().int().min(1).max(6).default(3).describe("Max items per section"),
     includeLatestCheckpoint: z.boolean().default(true).describe("Whether to include the latest checkpoint summary"),
     profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
-    mode: z.enum(["full", "summary", "off"]).optional().describe("Override recall mode (default: from config.recallMode)"),
+    mode: z.enum(["full", "light", "summary", "off"]).optional().describe("Override recall mode: 'full' (default), 'light' (<300 tokens), 'summary' (checkpoint only), 'off'"),
   },
   async ({ task, scope, sessionId, limitPerSection, includeLatestCheckpoint, profile: profileName, mode: modeOverride }) => {
     const effectiveMode = resolveRecallMode(config, modeOverride);
@@ -785,6 +831,44 @@ registerTool(
       };
     }
 
+    // --- light mode: <300 token ultra-light wake-up ---
+    if (effectiveMode === "light") {
+      const { retriever: lightRetriever } = getComponents(profileName);
+      const lightScope = resolveScopeSelection({
+        scope,
+        sessionId,
+        operation: "resume_context",
+        allowUnscoped: true,
+      });
+      const lightResult = await composeLightResumeContext({
+        retriever: lightRetriever,
+        checkpointStore,
+      }, {
+        task,
+        scope: lightScope.resolvedScope,
+        sessionId,
+        limitPerSection: limitPerSection,
+        includeLatestCheckpoint,
+        profile: profileName,
+      });
+      await saveManagedObservation({
+        workflowId: "resume_context",
+        outcome: "success",
+        summary: `Managed resume_context returned light-mode context (~${lightResult.text.length} chars).`,
+        scope: lightScope.resolvedScope || scope || "global",
+        source: "managed:recallnest",
+        signal: "managed-resume-light",
+        task,
+        tags: ["managed", "recallnest", "light-mode"],
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: lightResult.text,
+        }],
+      };
+    }
+
     // --- full mode: existing compose behavior ---
     const { retriever, profile } = getComponents(profileName);
     const scopeSelection = resolveScopeSelection({
@@ -822,7 +906,7 @@ registerTool(
 // --- search_memory tool ---
 registerTool(
   "search_memory",
-  "IMPORTANT: Use this tool proactively at the start of tasks to recall relevant past conversations, decisions, and patterns. Search when: starting a new task, debugging, writing, making decisions, or when the user references past work. Do NOT wait for the user to ask you to search. Query with key nouns/verbs from the user's message.",
+  "Search indexed memories by semantic similarity and return ranked results with optional temporal filtering. Read-only, but may fire stored reminders as a side effect. Use proactively at the start of tasks, when debugging, writing, or when the user references past work.",
   {
     query: z.string().describe("Search query — natural language or keywords"),
     limit: z.number().min(1).max(20).default(5).describe("Max results to return"),
@@ -835,19 +919,37 @@ registerTool(
     after: z.string().optional().describe("Filter memories stored after this date (ISO format YYYY-MM-DD, or relative like '最近30天', 'last 7 days')"),
     before: z.string().optional().describe("Filter memories stored before this date (ISO format YYYY-MM-DD, or relative)"),
     graph: z.boolean().default(false).optional().describe("Enable KG graph traversal (PPR) for relationship-aware search. Use when query involves entity relationships (e.g. 'what tools does Alice use', 'Bob的朋友')."),
+    includeArchived: z.boolean().default(false).optional().describe("When true, also return archived/superseded/consolidated memories (default: only active)"),
+    detail_level: z.enum(["brief", "normal", "full"]).default("normal").optional()
+      .describe("Result detail level: brief (ID+score+one-liner), normal (default, current behavior), full (include metadata)"),
+    topicTag: z.string().min(1).max(60).optional()
+      .describe("Filter by topic tag (e.g. 'auth', 'deploy', 'testing'). Only returns memories tagged with this topic."),
+    reconstruct: z.boolean().default(false).describe(
+      "Return LLM-synthesized reconstruction alongside raw results. Requires RECALLNEST_CONSTRUCTIVE_RETRIEVAL=true."
+    ),
+    validAt: z.string().optional().describe("Query memories valid at a specific point in time (ISO date, e.g. '2025-06-15'). Returns only memories whose validity window covers this date."),
+    includeExpired: z.boolean().default(false).optional().describe("When true, include expired memories in results (demoted 80%). Default: only active/non-expired."),
   },
-  async ({ query, limit, scope, sessionId, allScopes, category, profile: profileName, render, after, before, graph }) => {
+  async ({ query, limit, scope, sessionId, allScopes, category, profile: profileName, render, after, before, graph, includeArchived, detail_level, topicTag, reconstruct, validAt, includeExpired }) => {
     const { retriever, profile } = getComponents(profileName);
     // Ensure KG store is attached to non-default profile retrievers for PPR
     if (graph && kgStoreInstance) retriever.setKGStore(kgStoreInstance);
+    // Attach LLM client for constructive retrieval if available
+    if (reconstruct && llm) retriever.setLLMClient(llm);
     let results = await retriever.retrieve(buildRetrievalContext({
       query,
-      limit: (after || before) ? limit * 3 : limit, // Over-fetch when temporal filtering will reduce results
+      limit: (after || before || topicTag) ? limit * 3 : limit,
       category,
       scope,
       sessionId,
       allScopes,
       graph,
+      includeArchived,
+      topicTag,
+      reconstruct,
+      // F3: Temporal validity filtering
+      validAt: validAt ? new Date(validAt).getTime() : undefined,
+      includeExpired: includeExpired ?? undefined,
     }, {
       operation: "search_memory",
     }));
@@ -896,10 +998,59 @@ registerTool(
       }
     }
 
+    // HP-predictive: Surface predicted reminders alongside search results
+    let suggestedText = "";
+    if (isPredictiveMemoryEnabled()) {
+      try {
+        const recentCheckpoints = await checkpointStore.listRecent({ scope, limit: 5 });
+        const recentObservations = await workflowObservationStore.listRecent({ scope, limit: 20 });
+        const predictionCtx: PredictionContext = {
+          checkpoints: recentCheckpoints,
+          workflowObservations: recentObservations,
+          frequentMemories: [], // Populated by access tracker in future iteration
+          uncoveredTopics: results.length === 0 && query ? [query] : [],
+        };
+        const suggestions = await suggestPredictedReminders(store, embedder, predictionCtx, scope ?? "global");
+        suggestedText = formatSuggestedReminders(suggestions);
+      } catch {
+        // Prediction failure is non-critical — silently skip
+      }
+    }
+
+    const level = detail_level ?? "normal";
+    const sections: string[] = [];
+
+    // Phase 4: Read reconstruction from first-class field (no metadata hack)
+    const reconstruction = (results as import("./retriever.js").RetrievalResultSet).reconstruction;
+    if (reconstruction?.reconstructed) {
+      const sourceIds = reconstruction.sources.map(s => s.id).join(", ");
+      const sourceTypes = [...new Set(reconstruction.sources.map(s => s.source.type))].join(", ");
+      sections.push(
+        `## Reconstructed Context (confidence: ${reconstruction.confidence.toFixed(2)}, coverage: ${reconstruction.coverage.toFixed(2)})\n${reconstruction.reconstructed}\n\nSources (${sourceTypes}): ${sourceIds}`
+      );
+      // Render contradictions if detected
+      if (reconstruction.contradictions.length > 0) {
+        const conflictLines = reconstruction.contradictions.map(c =>
+          `- \u26a0\ufe0f ${c.description} [${c.memoryIds.join(" vs ")}]`
+        );
+        sections.push(`### Contradictions Detected\n${conflictLines.join("\n")}`);
+      }
+    }
+
+    let body: string;
+    if (level === "brief") {
+      body = formatBriefResults(results, { query });
+    } else if (level === "full") {
+      body = formatFullResults(results, { query, profile: profile.name });
+    } else {
+      body = formatSearchResults(results, { query, profile: profile.name });
+    }
+    sections.push(body);
+
     return {
       content: [{
         type: "text" as const,
-        text: formatSearchResults(results, { query, profile: profile.name }) + reminderText,
+        text: sections.join("\n\n") + reminderText + suggestedText,
       }],
     };
   }
@@ -907,15 +1058,15 @@ registerTool(
 
 registerTool(
   "explain_memory",
-  "Explain why the indexed memories matched: retrieval path, freshness, file/session, and matched terms.",
+  "Explain why memories matched a query: retrieval path, freshness, scope, and matched terms. Read-only. Use when search results seem unexpected and you need to debug ranking or scope filtering.",
   {
-    query: z.string().describe("Search query — natural language or keywords"),
-    limit: z.number().min(1).max(20).default(5).describe("Max results to analyze"),
-    scope: z.string().optional().describe("Optional explicit scope"),
-    sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier to infer session:<id> scope"),
-    allScopes: z.boolean().default(false).describe("When true, explicitly allow cross-scope search"),
-    category: DurableMemoryCategorySchema.optional().describe("Filter by memory category"),
-    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
+    query: z.string().describe("Search query to explain — natural language or keywords, e.g. 'auth migration'"),
+    limit: z.number().min(1).max(20).default(5).describe("Maximum number of matched results to analyze and explain (default: 5)"),
+    scope: z.string().optional().describe("Restrict to a specific scope, e.g. 'project:myapp'. Omit to use default scope"),
+    sessionId: z.string().min(1).max(160).optional().describe("Session identifier to infer session-scoped search, e.g. 'abc123'"),
+    allScopes: z.boolean().default(false).describe("Set to true to search across all scopes instead of the default scope"),
+    category: DurableMemoryCategorySchema.optional().describe("Filter results by memory category, e.g. 'preference', 'decision', 'fact'"),
+    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile that tunes ranking: 'debug' for technical, 'fact-check' for precision"),
   },
   async ({ query, limit, scope, sessionId, allScopes, category, profile: profileName }) => {
     const { retriever, profile } = getComponents(profileName);
@@ -940,14 +1091,14 @@ registerTool(
 
 registerTool(
   "distill_memory",
-  "Distill retrieved memories into a compact briefing with source map, takeaways, and reusable evidence.",
+  "Distill retrieved memories into a compact briefing with source map, key takeaways, and reusable evidence. Use this when you need a synthesized summary of stored knowledge on a topic rather than raw search results. Returns a structured briefing with citations. Read-only — does not modify stored memories.",
   {
-    query: z.string().describe("Topic or task to distill"),
-    limit: z.number().min(1).max(20).default(8).describe("Max results to distill"),
-    scope: z.string().optional().describe("Optional explicit scope"),
-    sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier to infer session:<id> scope"),
-    allScopes: z.boolean().default(false).describe("When true, explicitly allow cross-scope search"),
-    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
+    query: z.string().describe("Natural language topic or task to distill, e.g. 'authentication migration decisions'"),
+    limit: z.number().min(1).max(20).default(8).describe("Maximum number of retrieved memories to include in the distillation (default: 8)"),
+    scope: z.string().optional().describe("Restrict search to a specific scope, e.g. 'project:myapp'. Omit to use the default scope"),
+    sessionId: z.string().min(1).max(160).optional().describe("Session identifier to infer session-scoped search, e.g. 'abc123'"),
+    allScopes: z.boolean().default(false).describe("Set to true to search across all scopes instead of the default scope"),
+    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile that tunes ranking weights: 'writing' for narrative, 'debug' for technical, 'fact-check' for high-precision"),
   },
   async ({ query, limit, scope, sessionId, allScopes, profile: profileName }) => {
     const { retriever, profile } = getComponents(profileName || "writing");
@@ -971,15 +1122,15 @@ registerTool(
 
 registerTool(
   "brief_memory",
-  "Create a structured memory brief from retrieved results and feed it back into recall.",
+  "Create a structured memory brief by retrieving and summarizing relevant memories, then persist it as a reusable asset indexed for future recall. Use this when you want to consolidate scattered knowledge on a topic into a single retrievable document. Side effect: writes a new brief asset to disk and indexes it in the vector store for future search.",
   {
-    query: z.string().describe("Topic or task to turn into a memory brief"),
-    limit: z.number().min(1).max(20).default(8).describe("Max results to distill into the brief"),
-    scope: z.string().optional().describe("Optional explicit scope"),
-    sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier to infer session:<id> scope"),
-    allScopes: z.boolean().default(false).describe("When true, explicitly allow cross-scope search"),
-    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
-    title: z.string().optional().describe("Optional brief title"),
+    query: z.string().describe("Natural language topic or task to brief, e.g. 'deployment pipeline architecture decisions'"),
+    limit: z.number().min(1).max(20).default(8).describe("Maximum number of source memories to include in the brief (default: 8)"),
+    scope: z.string().optional().describe("Restrict search to a specific scope, e.g. 'project:myapp'. Omit to use the default scope"),
+    sessionId: z.string().min(1).max(160).optional().describe("Session identifier to infer session-scoped search, e.g. 'abc123'"),
+    allScopes: z.boolean().default(false).describe("Set to true to search across all scopes instead of the default scope"),
+    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile that tunes ranking weights: 'writing' for narrative, 'debug' for technical, 'fact-check' for high-precision"),
+    title: z.string().optional().describe("Human-readable title for the brief asset, e.g. 'Q1 Auth Migration Summary'. Auto-generated if omitted"),
   },
   async ({ query, limit, scope, sessionId, allScopes, profile: profileName, title }) => {
     const { retriever, profile, store, embedder } = getComponents(profileName || "writing");
@@ -1012,16 +1163,16 @@ registerTool(
 
 registerTool(
   "pin_memory",
-  "Promote one retrieved memory into a pinned asset for later reuse.",
+  "Pin a retrieved memory as a high-importance reusable asset on disk. Side effect: boosts importance to 0.95, writes pin asset file, and indexes it. Use when a search result is critical and should be surfaced in future recalls.",
   {
-    memory_id: z.string().describe("Memory ID or unique prefix from search/explain output"),
-    scope: z.string().optional().describe("Optional explicit scope"),
-    sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier to infer session:<id> scope"),
-    allScopes: z.boolean().default(false).describe("When true, explicitly allow cross-scope reads"),
-    title: z.string().optional().describe("Optional pinned title"),
-    summary: z.string().optional().describe("Optional pinned summary"),
-    query: z.string().optional().describe("Optional query that led to this pin"),
-    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
+    memory_id: z.string().describe("Memory ID or unique prefix from search/explain output, e.g. 'a1b2c3d4'"),
+    scope: z.string().optional().describe("Explicit scope filter, e.g. 'project:recallnest'"),
+    sessionId: z.string().min(1).max(160).optional().describe("Session identifier to infer session:<id> scope, e.g. 'abc123'"),
+    allScopes: z.boolean().default(false).describe("When true, allow cross-scope reads to find the memory"),
+    title: z.string().optional().describe("Human-readable title for the pin, e.g. 'Auth migration decision'"),
+    summary: z.string().optional().describe("Short summary override for the pinned asset"),
+    query: z.string().optional().describe("Original query that led to this pin, e.g. 'auth decisions'"),
+    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile for ranking, e.g. 'debug'"),
   },
   async ({ memory_id, scope, sessionId, allScopes, title, summary, query, profile: profileName }) => {
     const { store, embedder } = getComponents(profileName);
@@ -1057,15 +1208,15 @@ registerTool(
 
 registerTool(
   "export_memory",
-  "Export a distilled memory briefing to a markdown or json artifact on disk.",
+  "Export a distilled memory briefing to a markdown or JSON file on disk. Side effect: writes an export artifact file. Use when you need an offline-readable snapshot of knowledge on a topic.",
   {
-    query: z.string().describe("Topic or task to export"),
-    limit: z.number().min(1).max(20).default(8).describe("Max results to export"),
-    scope: z.string().optional().describe("Optional explicit scope"),
-    sessionId: z.string().min(1).max(160).optional().describe("Optional session identifier to infer session:<id> scope"),
-    allScopes: z.boolean().default(false).describe("When true, explicitly allow cross-scope search"),
-    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
-    format: z.enum(["md", "json"]).default("md").describe("Export format"),
+    query: z.string().describe("Topic or task to export, e.g. 'auth migration decisions'"),
+    limit: z.number().min(1).max(20).default(8).describe("Maximum number of source memories to include in the export (default: 8)"),
+    scope: z.string().optional().describe("Restrict to a specific scope, e.g. 'project:recallnest'. Omit to use default scope"),
+    sessionId: z.string().min(1).max(160).optional().describe("Session identifier to infer session-scoped search, e.g. 'abc123'"),
+    allScopes: z.boolean().default(false).describe("Set to true to search across all scopes instead of the default scope"),
+    profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile for ranking, e.g. 'writing'"),
+    format: z.enum(["md", "json"]).default("md").describe("Export format: 'md' for markdown, 'json' for structured JSON"),
   },
   async ({ query, limit, scope, sessionId, allScopes, profile: profileName, format }) => {
     const { retriever, profile } = getComponents(profileName || "writing");
@@ -1098,9 +1249,9 @@ registerTool(
 
 registerTool(
   "list_assets",
-  "List recent structured memory assets, including pinned memories and distilled briefs.",
+  "List recent structured memory assets (pinned memories and distilled briefs) sorted by creation date. Read-only. Use when you need an inventory of persisted knowledge artifacts — for example, before creating a new brief to avoid duplicates. Returns asset type, title, scope, creation date, and file path for each entry.",
   {
-    limit: z.number().min(1).max(50).default(12).describe("Max assets to list"),
+    limit: z.number().min(1).max(50).default(12).describe("Maximum number of assets to return, sorted most-recent-first (default: 12, max: 50)"),
   },
   async ({ limit }) => {
     const rows = listMemoryAssets(limit);
@@ -1118,7 +1269,7 @@ registerTool(
 
 registerTool(
   "list_dirty_briefs",
-  "Preview dirty memory briefs that were generated before the current brief-cleanup rules.",
+  "List memory briefs generated before current cleanup rules that may need re-indexing. Read-only. Use when auditing brief quality or before running clean_dirty_briefs.",
   {},
   async () => {
     const rows = listDirtyBriefAssets();
@@ -1136,9 +1287,9 @@ registerTool(
 
 registerTool(
   "clean_dirty_briefs",
-  "Archive dirty briefs and remove their indexed asset scopes. Use preview mode first if unsure.",
+  "Archive dirty briefs and remove their indexed asset entries. Side effect: when apply=true, moves briefs to archive and deletes index rows. Use when list_dirty_briefs shows stale briefs that need cleanup.",
   {
-    apply: z.boolean().default(false).describe("When false, preview only. When true, archive and delete indexed rows."),
+    apply: z.boolean().default(false).describe("When false, preview only (no writes). When true, archive briefs and delete indexed rows."),
   },
   async ({ apply }) => {
     const rows = listDirtyBriefAssets();
@@ -1159,9 +1310,17 @@ registerTool(
     let archived = 0;
     let deleted = 0;
     for (const row of rows) {
-      archiveDirtyBriefAsset(row);
-      archived += 1;
-      deleted += await store.bulkDelete([row.scope]);
+      try {
+        archiveDirtyBriefAsset(row);
+        archived += 1;
+      } catch (err) {
+        console.error("[recallnest] Failed to archive dirty brief:", err instanceof Error ? err.message : String(err));
+      }
+      try {
+        deleted += await store.bulkDelete([row.scope]);
+      } catch (err) {
+        console.error("[recallnest] Failed to delete dirty brief index rows:", err instanceof Error ? err.message : String(err));
+      }
     }
 
     return {
@@ -1175,7 +1334,7 @@ registerTool(
 
 registerTool(
   "consolidate_memories",
-  "Run semantic consolidation on a scope: cluster similar memories, merge near-duplicates, link related entries, and detect contradictions. Dry-run by default — set apply=true to actually archive merged entries.",
+  "Run semantic consolidation: cluster similar memories, merge near-duplicates, and detect contradictions. Side effect: when apply=true, archives merged entries. Use when a scope has grown large and needs deduplication.",
   {
     scope: z.string().min(1).max(160).describe("Scope to consolidate (e.g. project:recallnest)"),
     clusterThreshold: z.number().min(0.5).max(1.0).default(0.82).describe("Min similarity to form a cluster (default 0.82)"),
@@ -1215,11 +1374,59 @@ registerTool(
   }
 );
 
+// --- forget_memory tool (Ethics Layer) ---
+registerTool(
+  "forget_memory",
+  "Permanently forget a memory with full cascade: delete primary entry, remove KG triples, demote related memories, and log an audit trail. Requires confirm=true for durable-tier memories. Use when the user explicitly requests a memory be forgotten, or to clean up sensitive/incorrect data.",
+  {
+    memoryId: z.string().min(1).max(128).describe("Memory ID to forget (full UUID or 8+ hex prefix)"),
+    confirm: z.boolean().default(false).describe("Required confirmation — must be true for durable-tier memories"),
+    reason: z.string().min(1).max(200).optional().describe("Reason for forgetting (recorded in audit trail)"),
+    scope: z.string().min(1).max(160).optional().describe("Optional scope filter for permission check"),
+  },
+  async ({ memoryId, confirm, reason, scope }) => {
+    const { store } = getComponents();
+    const auditLogger = createAuditLogger();
+    const scopeFilter = scope ? [scope] : undefined;
+
+    const result = await forgetMemory(
+      { store, kgStore: kgStoreInstance, auditLogger },
+      { memoryId, confirm, reason, scopeFilter },
+    );
+
+    if (!result.success) {
+      return {
+        content: [{
+          type: "text" as const,
+          text: `❌ Forget failed: ${result.error}`,
+        }],
+      };
+    }
+
+    const lines = [
+      `✅ Memory ${result.memoryId.slice(0, 8)} forgotten.`,
+      `Privacy tier: ${result.evidence?.privacyTier || "unknown"}`,
+      `KG triples removed: ${result.kgTriplesRemoved ? "yes" : "no/N/A"}`,
+      `Cascade demoted: ${result.cascadeResult.demotedCount} related memories`,
+    ];
+    if (result.evidence?.reason) {
+      lines.push(`Reason: ${result.evidence.reason}`);
+    }
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: lines.join("\n"),
+      }],
+    };
+  },
+);
+
 registerTool(
   "list_pins",
-  "List recently pinned memory assets.",
+  "List pinned memory assets sorted by creation date, showing title, scope, importance score, and file path. Read-only. Use when you need to review high-value memories that were explicitly pinned via pin_memory, or to check if a topic already has a pinned reference before creating a new one.",
   {
-    limit: z.number().min(1).max(50).default(10).describe("Max pinned assets to list"),
+    limit: z.number().min(1).max(50).default(10).describe("Maximum number of pinned assets to return, sorted most-recent-first (default: 10, max: 50)"),
   },
   async ({ limit }) => {
     const rows = listPinAssets(limit);
@@ -1238,7 +1445,7 @@ registerTool(
 // --- memory_stats tool ---
 registerTool(
   "memory_stats",
-  "Show statistics of the indexed memory database",
+  "Show aggregate statistics of the memory database: total entries, counts by source and category. Read-only. Use when you need an overview of memory store health or size.",
   {},
   async () => {
     const stats = await store.stats();
@@ -1270,15 +1477,97 @@ registerTool(
   }
 );
 
+// ============================================================================
+// LC-P4: Data Checkup Tool
+// ============================================================================
+
+registerTool(
+  "data_checkup",
+  "Run health checks on the memory database: vector dimensions, orphans, tier distribution, and conflict backlog. Read-only. Use when diagnosing data quality issues or before a consolidation run.",
+  {},
+  async () => {
+    const openConflicts = (await conflictStore.listRecent({ status: "open", limit: 200 })).length;
+    const report = await runDataCheckup({ store, openConflictCount: openConflicts });
+    return {
+      content: [{ type: "text" as const, text: formatCheckupReport(report) }],
+    };
+  }
+);
+
+// ============================================================================
+// Memory Lint Tool
+// ============================================================================
+
+registerTool(
+  "memory_lint",
+  "Run memory quality lint checks: contradictions, duplicates, stale entries, and orphans. Read-only. Returns a health score (0-100) and actionable findings. Use for periodic memory hygiene or before consolidation.",
+  {
+    scope: z.string().min(1).max(160).optional().describe("Optional scope filter, e.g. 'project:recallnest'. Omit to lint all scopes"),
+    verbose: z.boolean().default(false).describe("Include all individual findings in output (default: summarized)"),
+  },
+  async ({ scope, verbose }) => {
+    const report = await runMemoryLint({ store, scope, verbose });
+    return {
+      content: [{ type: "text" as const, text: formatMemoryLintReport(report) }],
+    };
+  }
+);
+
+// ============================================================================
+// Knowledge Graph Export Tool
+// ============================================================================
+
+registerTool(
+  "export_graph",
+  "Export memories as an interactive HTML knowledge graph. Creates a self-contained HTML file with a force-directed visualization. Open in any browser. Use when the user wants to visualize their memory network.",
+  {
+    scope: z.string().min(1).max(160).optional().describe("Optional scope filter"),
+    maxNodes: z.number().int().min(10).max(500).default(200).describe("Maximum nodes to include (default 200)"),
+  },
+  async ({ scope, maxNodes }) => {
+    const { path, graph } = await exportMemoryGraph(store, { scope, maxNodes });
+    return {
+      content: [{ type: "text" as const, text: formatGraphExportResult(path, graph) }],
+    };
+  }
+);
+
+// ============================================================================
+// AD-1: Dream Pipeline Tool
+// ============================================================================
+
+registerTool(
+  "dream",
+  "Run a full memory consolidation cycle (Orient, Gather, Consolidate, Prune). Side effect: may archive low-value entries and generate insight memories. Use when memory count is high and you need periodic maintenance.",
+  {
+    scope: z.string().min(1).max(160).optional().describe("Scope to consolidate, e.g. 'project:myapp'. Omit to consolidate across all scopes"),
+    force: z.boolean().default(false).describe("Set to true to force consolidation even if recent write count is below the automatic threshold"),
+  },
+  async ({ scope, force }) => {
+    const resolvedScope = scope || "project:default";
+    const components = getComponents();
+    const result = await runDream({
+      store: components.store,
+      llm: components.llm,
+      embedder: components.embedder,
+      scope: resolvedScope,
+      force,
+    });
+    return {
+      content: [{ type: "text" as const, text: formatDreamResult(result) }],
+    };
+  }
+);
+
 // ============================================================================
 // Memory Drill-Down Tool
 // ============================================================================
 
 registerTool(
   "memory_drill_down",
-  "Get deeper content for a memory entry. Use after seeing compact summaries to get the full text or structured overview.",
+  "Retrieve the full or overview-level content of a single memory entry. Read-only. Use when search returned compact summaries and you need the complete text or L1 overview.",
   {
-    id: z.string().describe("Memory ID or prefix (at least 8 hex chars)"),
+    id: z.string().describe("Memory ID or unique prefix (at least 8 hex chars), e.g. 'a1b2c3d4'"),
     level: z.enum(["overview", "full"]).optional().default("full")
       .describe("Content depth: 'overview' (L1) or 'full' (L2, default)"),
   },
@@ -1329,9 +1618,347 @@ registerTool(
   },
 );
 
+// ============================================================================
+// Skill Memory Tools (D-1)
+// ============================================================================
+
+registerTool(
+  "store_skill",
+  "Store an executable skill with trigger conditions, implementation, and verification steps. Side effect: persists a new skill entry and indexes it. Use when you identify a reusable procedure worth automating across sessions.",
+  {
+    name: z.string().min(1).max(120).describe("Unique skill identifier, e.g. 'deploy_production' or 'run_migrations'"),
+    description: z.string().min(1).max(500).describe("Natural language description of what the skill does (used for semantic retrieval matching)"),
+    triggerPattern: z.string().min(1).max(300).describe("Natural language pattern describing when to suggest this skill, e.g. 'user asks to deploy to production'"),
+    implementationType: SkillImplementationTypeSchema.describe("Execution type: 'bash' for shell scripts, 'python' for Python code, 'mcp_tool_chain' for MCP sequences, 'instruction_sequence' for step-by-step instructions"),
+    implementation: z.string().min(1).max(5000).describe("Executable content: the actual script, code, or instruction steps to run"),
+    inputSchema: z.record(z.string(), z.unknown()).optional().describe("JSON Schema defining the skill's input parameters, e.g. {\"env\": {\"type\": \"string\"}}"),
+    verification: z.string().max(500).optional().describe("Steps to verify the skill executed correctly, e.g. 'check deployment URL returns 200'"),
+    scope: z.string().min(1).max(160).describe("Scope to store the skill under, e.g. 'project:recallnest'"),
+    source: z.enum(["manual", "agent", "api"]).default("agent").describe("How this skill was captured: 'manual' by user, 'agent' by AI, or 'api' programmatically"),
+    tags: z.array(z.string().max(60)).max(6).default([]).describe("Optional categorization tags, e.g. ['deployment', 'production']"),
+  },
+  async ({ name, description, triggerPattern, implementationType, implementation, inputSchema, verification, scope, source, tags }) => {
+    const { store, embedder } = getComponents();
+    const stored = await persistSkill(store, embedder, {
+      name,
+      description,
+      triggerPattern,
+      implementationType,
+      implementation,
+      inputSchema,
+      verification,
+      scope,
+      source,
+      tags,
+    });
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: [
+          `Stored skill ${stored.id.slice(0, 8)}`,
+          `Name: ${stored.name}`,
+          `Type: ${stored.implementationType}`,
+          `Scope: ${stored.scope}`,
+          `Tags: ${stored.tags.join(", ") || "-"}`,
+          `Stored at: ${stored.storedAt}`,
+        ].join("\n"),
+      }],
+    };
+  },
+);
+
+registerTool(
+  "retrieve_skill",
+  "Retrieve executable skills matching a task description by semantic similarity. Read-only. Use when you need a stored procedure to act on, not just recall knowledge.",
+  {
+    query: z.string().min(1).max(300).describe("Natural language task description to match, e.g. 'deploy the app to production'"),
+    scope: z.string().min(1).max(160).optional().describe("Restrict to skills in a specific scope, e.g. 'project:myapp'. Omit to search all scopes"),
+    limit: z.number().min(1).max(10).default(3).describe("Maximum number of matching skills to return, sorted by relevance (default: 3)"),
+  },
+  async ({ query, scope, limit }) => {
+    const { store, embedder } = getComponents();
+    const results = await retrieveSkills(store, embedder, query, scope, limit);
+
+    if (results.length === 0) {
+      return {
+        content: [{
+          type: "text" as const,
+          text: "No matching skills found.",
+        }],
+      };
+    }
+
+    const formatted = results.map(({ skill, score }, index) => [
+      `## ${index + 1}. ${skill.name} (score: ${score.toFixed(3)})`,
+      `**Description**: ${skill.description}`,
+      `**Trigger**: ${skill.triggerPattern}`,
+      `**Type**: ${skill.implementationType}`,
+      skill.verification ? `**Verification**: ${skill.verification}` : null,
+      `**Tags**: ${skill.tags.join(", ") || "-"}`,
+      "",
+      "```",
+      skill.implementation,
+      "```",
+    ].filter((line): line is string => line !== null).join("\n")).join("\n\n---\n\n");
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Found ${results.length} skill(s):\n\n${formatted}`,
+      }],
+    };
+  },
+);
+
+// --- D-2: scan_skill_promotions tool ---
+registerTool(
+  "scan_skill_promotions",
+  "Scan cases and patterns in a scope for potential promotion to reusable skills. Read-only. Use when you want to discover recurring procedures that deserve formalization as skills.",
+  {
+    scope: z.string().min(1).max(160).describe("Project scope to scan for promotion candidates"),
+    minOccurrences: z.number().min(2).max(20).default(3).describe("Minimum similar cases to trigger a promotion suggestion"),
+  },
+  async ({ scope, minOccurrences }) => {
+    const { store } = getComponents();
+    const result = await scanForPromotions(store, scope, {
+      minCaseOccurrences: minOccurrences,
+    });
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: formatPromotionResult(result),
+      }],
+    };
+  },
+);
+
+// --- MCP-1: list_tools tool ---
+registerTool(
+  "list_tools",
+  "List available RecallNest tools with one-line descriptions, filtered by tier. Read-only. Use when you need to discover advanced or governance tools beyond the core set.",
+  {
+    tier: z.enum(["core", "advanced", "full"]).default("advanced").optional()
+      .describe("Which tier of tools to list. Returns tools at this tier and below."),
+  },
+  async ({ tier }) => {
+    const requestedTier = tier ?? "advanced";
+    const tierOrder: Record<string, number> = { core: 0, advanced: 1, governance: 2 };
+    const maxOrder = requestedTier === "full" ? 2 : tierOrder[requestedTier] ?? 1;
+
+    const lines: string[] = [`Available tools (tier: ${requestedTier}):`];
+    for (const [toolName, toolTier] of Object.entries(TOOL_TIERS)) {
+      if ((tierOrder[toolTier] ?? 999) > maxOrder) continue;
+      const desc = TOOL_DESCRIPTIONS.get(toolName);
+      const oneLiner = desc
+        ? desc.split(/[.!]\s/)[0]?.slice(0, 100) ?? desc.slice(0, 100)
+        : "(no description)";
+      lines.push(`- ${toolName}: ${oneLiner}`);
+    }
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: lines.join("\n"),
+      }],
+    };
+  },
+);
+
+// --- MCP-3: batch_store tool ---
+registerTool(
+  "batch_store",
+  "Store multiple memories in a single call with deduplication. Side effect: persists up to 20 entries. Use when you have several facts to store at once, more efficient than repeated store_memory calls.",
+  {
+    memories: z.array(z.object({
+      text: z.string().min(1),
+      category: DurableMemoryCategorySchema.default("events"),
+      importance: z.number().min(0).max(1).default(0.7),
+      tags: z.array(z.string()).max(6).default([]),
+    })).min(1).max(20),
+    scope: z.string().min(1).max(160),
+    source: z.enum(["manual", "agent", "api"]).default("agent"),
+  },
+  async ({ memories, scope, source }) => {
+    const { store, embedder } = getComponents();
+    const stored = await persistMemoryBatch({
+      store,
+      embedder,
+      conflictStore,
+      kgExtractor,
+    }, {
+      scope,
+      source,
+      defaultImportance: 0.7,
+      memories: memories.map((m) => ({
+        text: m.text,
+        category: m.category,
+        importance: m.importance,
+        tags: m.tags,
+      })),
+    });
+
+    const counts = { new: 0, deduped: 0, updated: 0 };
+    for (const r of stored) {
+      if (r.disposition === "deduped") counts.deduped++;
+      else if (r.disposition === "updated") counts.updated++;
+      else counts.new++;
+    }
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Stored ${stored.length} memories (${counts.new} new, ${counts.deduped} deduped, ${counts.updated} updated)`,
+      }],
+    };
+  },
+);
+
+// --- MP-2: import_conversations tool ---
+
+registerTool(
+  "import_conversations",
+  "Import a conversation file (Claude Code JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON, or plaintext) into memory. Auto-detects format or use explicit format parameter. Messages are normalized and stored via the standard persistMemory pipeline.",
+  {
+    content: z.string().min(1).max(500_000).describe("Raw file content to import"),
+    scope: z.string().min(1).max(160).describe("Target scope for imported memories, e.g. 'project:myapp'"),
+    format: z.enum(["auto", "claude-code", "claude-ai", "chatgpt", "slack", "plaintext"]).default("auto").describe("Conversation format. Use 'auto' to detect automatically."),
+  },
+  async ({ content, scope, format }) => {
+    const { detectFormat, normalizeConversation, ingestNormalizedMessages } = await import("./conversation-importer.js");
+    const { embedder } = getComponents();
+
+    const resolvedFormat = format === "auto" ? detectFormat(content) : format;
+    const messages = normalizeConversation(content, resolvedFormat);
+
+    if (messages.length === 0) {
+      return {
+        content: [{
+          type: "text" as const,
+          text: `No messages found (detected format: ${resolvedFormat})`,
+        }],
+      };
+    }
+
+    const result = await ingestNormalizedMessages(
+      { store, embedder, llm, conflictStore, kgExtractor },
+      messages,
+      scope,
+    );
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: [
+          `Import complete (format: ${resolvedFormat})`,
+          `Total: ${result.total}`,
+          `Stored: ${result.stored}`,
+          `Rejected: ${result.rejected}`,
+          result.errors.length > 0 ? `Errors: ${result.errors.join("; ")}` : null,
+        ].filter(Boolean).join("\n"),
+      }],
+    };
+  },
+);
+
+// --- S15: distill_session tool ---
+registerTool(
+  "distill_session",
+  "Distill a conversation session into structured knowledge and persist to long-term memory. Three layers: (1) microcompact clears old tool results at zero cost, (2) LLM summarizes into 9 dimensions, (3) extracts durable knowledge into RecallNest. Use when a session is ending or context is getting large. Side effect: persists extracted memories.",
+  {
+    messages: z.array(z.object({
+      role: z.enum(["user", "assistant", "system"]),
+      content: z.union([
+        z.string(),
+        z.array(z.object({
+          type: z.enum(["text", "tool_use", "tool_result"]),
+          name: z.string().optional(),
+          id: z.string().optional(),
+          input: z.record(z.unknown()).optional(),
+          content: z.string().optional(),
+          text: z.string().optional(),
+          tool_use_id: z.string().optional(),
+        })),
+      ]),
+    })).min(1).max(500).describe("Conversation messages to distill"),
+    scope: z.string().min(1).max(160).describe("Memory scope for persisted knowledge, e.g. 'project:recallnest'"),
+    preserveRecent: z.number().min(0).max(20).default(6).describe("Keep the N most recent messages verbatim (default: 6)"),
+    keepRecentTools: z.number().min(0).max(20).default(5).describe("Keep the N most recent tool results during microcompact (default: 5)"),
+    persist: z.boolean().default(true).describe("Whether to persist extracted knowledge to RecallNest (default: true)"),
+  },
+  async ({ messages, scope, preserveRecent, keepRecentTools, persist }) => {
+    const { store, embedder } = getComponents();
+    const { distillSession } = await import("./session-distiller.js");
+
+    const result = await distillSession(
+      { messages, scope, preserveRecent, keepRecentTools, persist },
+      {
+        llm: llmClient,
+        persistMemory: async (input) => {
+          const stored = await persistMemory({
+            store, embedder, conflictStore, kgExtractor,
+          }, input);
+          return { disposition: stored.disposition, id: stored.id };
+        },
+      },
+    );
+
+    const lines = [
+      `Microcompact: ${result.microcompact.toolsCleared} tool results cleared, ~${result.microcompact.tokensFreed} tokens freed`,
+    ];
+    if (result.summary) {
+      lines.push(`Summary: 9-dimension structured summary generated`);
+    }
+    if (result.persisted) {
+      const p = result.persisted;
+      lines.push(`Persisted: ${p.memoriesStored} stored, ${p.memoriesDeduped} deduped, ${p.memoriesConflicted} conflicted, ${p.memoriesRejected} rejected`);
+    }
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: lines.join("\n"),
+      }],
+    };
+  },
+);
+
+// ============================================================================
+// Global error handlers — prevent silent crashes from unhandled async errors
+// ============================================================================
+
+process.on("unhandledRejection", (reason) => {
+  console.error("[recallnest] Unhandled promise rejection:", reason instanceof Error ? reason.stack || reason.message : String(reason));
+});
+
+process.on("uncaughtException", (err) => {
+  console.error("[recallnest] Uncaught exception:", err.stack || err.message);
+  // Give stderr a chance to flush before exiting
+  setTimeout(() => process.exit(1), 100);
+});
+
 // ============================================================================
 // Start
 // ============================================================================
 
+// Auto-register babel-memory language processor if installed (non-blocking)
+autoRegisterBabelMemory().then((ok) => {
+  if (ok) console.error("[recallnest] babel-memory registered");
+}).catch((err) => {
+  console.error("[recallnest] babel-memory registration failed:", err instanceof Error ? err.message : String(err));
+});
+
 const transport = new StdioServerTransport();
-await server.connect(transport);
+const CONNECT_TIMEOUT_MS = 30_000;
+try {
+  await Promise.race([
+    server.connect(transport),
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error("MCP server.connect() timed out after 30s")), CONNECT_TIMEOUT_MS)
+    ),
+  ]);
+} catch (err) {
+  console.error("[recallnest] Fatal: MCP connection failed:", err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}