@duckmind/deepquark-darwin-arm64 0.9.83 → 0.9.90

package/.deepquark/skills/bundled/knowledge-graph/lib/output-formatter.ts

@@ -0,0 +1,997 @@
+/**
+ * Output Formatter for token-efficient MCP responses
+ * @module output-formatter
+ */
+
+import { logTransformationFailure, logTransformationSuccess } from './transformation-log';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface FormatOptions {
+  maxLines?: number;
+  maxLineLength?: number;
+  collectMetrics?: boolean;
+  timeoutMs?: number;
+  query?: string;
+}
+
+export interface FormatResult {
+  output: string;
+  usedFallback: boolean;
+  error?: string;
+  metrics?: {
+    rawBytes: number;
+    compactBytes: number;
+    savingsPercent: number;
+    processingTimeMs: number;
+  };
+}
+
+export const DEFAULT_OPTIONS: FormatOptions = {
+  maxLines: 20,
+  maxLineLength: 120,
+  collectMetrics: false,
+  timeoutMs: 100,
+};
+
+export type OperationFormatter = (data: unknown, options: FormatOptions) => string;
+
+// ============================================================================
+// Formatter Registry
+// ============================================================================
+
+const formatterRegistry = new Map<string, OperationFormatter>();
+
+export function registerFormatter(operation: string, formatter: OperationFormatter): void {
+  formatterRegistry.set(operation, formatter);
+}
+
+// ============================================================================
+// Utility Functions (T007)
+// ============================================================================
+
+/**
+ * Convert ISO timestamp to human-readable relative time.
+ * Examples: "2h ago", "1d ago", "1mo ago", "1y ago"
+ */
+export function relativeTime(isoString: string): string {
+  const date = new Date(isoString);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+
+  const seconds = Math.floor(diffMs / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  const months = Math.floor(days / 30);
+  const years = Math.floor(days / 365);
+
+  if (years > 0) return `${years}y ago`;
+  if (months > 0) return `${months}mo ago`;
+  if (days > 0) return `${days}d ago`;
+  if (hours > 0) return `${hours}h ago`;
+  if (minutes > 0) return `${minutes}m ago`;
+  return 'just now';
+}
+
+/**
+ * Truncate UUID to last 8 characters with ellipsis prefix.
+ * Example: "550e8400-e29b-41d4-a716-446655440000" -> "...55440000"
+ */
+export function truncateUuid(uuid: string): string {
+  if (!uuid || uuid.length < 8) return uuid || '';
+  return `...${uuid.slice(-8)}`;
+}
+
+/**
+ * Truncate text at word boundary with ellipsis.
+ * The result including ellipsis will not exceed maxLength.
+ * Example: "This is a long text that needs truncation" (maxLength=25) -> "This is a long text..."
+ */
+export function truncateText(text: string, maxLength: number): string {
+  if (!text || text.length <= maxLength) return text || '';
+
+  // Account for ellipsis (3 chars) in max length
+  const effectiveMax = maxLength - 3;
+  if (effectiveMax <= 0) {
+    return `${text.slice(0, maxLength)}...`;
+  }
+
+  // Find last space before effective max
+  const truncated = text.slice(0, effectiveMax);
+  const lastSpace = truncated.lastIndexOf(' ');
+
+  // If no space found or space is at the beginning, just cut at effectiveMax
+  if (lastSpace <= 0) {
+    return `${truncated.trim()}...`;
+  }
+
+  return `${truncated.slice(0, lastSpace).trim()}...`;
+}
+
+// ============================================================================
+// MCP Response Type Guards
+// ============================================================================
+
+interface SearchNodesResponse {
+  nodes: Array<{
+    uuid?: string;
+    name: string;
+    labels?: string[]; // Actual MCP response uses labels array
+    entity_type?: string; // Legacy field
+    summary?: string;
+    created_at?: string;
+    group_id?: string;
+    attributes?: Record<string, unknown>; // For weighted scores, importance, etc.
+  }>;
+}
+
+interface SearchFactsResponse {
+  facts: Array<{
+    uuid?: string;
+    name: string; // Relation type (e.g., "ABOUT", "RELATES_TO")
+    fact: string; // Human-readable fact description
+    source_node_uuid?: string;
+    target_node_uuid?: string;
+    created_at?: string;
+    valid_at?: string;
+    // Legacy fields (older response format)
+    source?: { name: string };
+    target?: { name: string };
+    relation?: string;
+    confidence?: number;
+  }>;
+}
+
+interface GetEpisodesResponse {
+  episodes: Array<{
+    uuid?: string;
+    name: string;
+    content?: string;
+    created_at: string;
+    source_description?: string;
+  }>;
+}
+
+interface AddMemoryResponse {
+  message: string;
+  // Legacy fields (may not be present in newer server versions)
+  uuid?: string;
+  name?: string;
+  entities_extracted?: number;
+  facts_extracted?: number;
+}
+
+interface GetStatusResponse {
+  status: string;
+  message: string;
+  // Legacy fields (may not be present in newer server versions)
+  entity_count?: number;
+  episode_count?: number;
+  last_updated?: string;
+}
+
+interface DeleteResponse {
+  success: boolean;
+  uuid?: string;
+  message?: string;
+}
+
+interface ClearGraphResponse {
+  success: boolean;
+  deleted_entities?: number;
+  deleted_episodes?: number;
+}
+
+// Feature 009: Memory decay response types
+interface HealthMetricsResponse {
+  states: Record<string, number>;
+  aggregates: {
+    total: number;
+    average_decay: number;
+    average_importance: number;
+    average_stability: number;
+  };
+  age_distribution: Record<string, number>;
+  maintenance: {
+    last_run: string | null;
+    duration_seconds: number;
+    processed: number;
+    transitions: number;
+  };
+  generated_at: string;
+}
+
+interface MaintenanceResultResponse {
+  success: boolean;
+  memories_processed: number;
+  nodes_classified: {
+    found: number;
+    classified: number;
+    failed: number;
+    using_llm: boolean;
+  };
+  decay_scores_updated: number;
+  state_transitions: {
+    active_to_dormant: number;
+    dormant_to_archived: number;
+    archived_to_expired: number;
+    expired_to_soft_deleted: number;
+  };
+  soft_deleted_purged: number;
+  duration_seconds: number;
+  completed_at: string | null;
+  error: string | null;
+}
+
+interface ClassificationResponse {
+  importance: number;
+  stability: number;
+  is_permanent: boolean;
+  classification_source: string;
+}
+
+interface RecoveryResponse {
+  message: string;
+  uuid: string;
+  name: string;
+  new_state: string;
+}
+
+// Feature 020: Investigative search response types
+interface InvestigateEntityResponse {
+  entity: {
+    uuid: string;
+    name: string;
+    labels: string[];
+    summary?: string;
+    created_at?: string;
+    group_id?: string;
+  };
+  connections: Array<{
+    relationship: string;
+    direction: string;
+    hop_distance: number;
+    target_entity: {
+      uuid: string;
+      name: string;
+      labels: string[];
+      summary?: string;
+      created_at?: string;
+      group_id?: string;
+    };
+    fact?: string;
+    confidence?: number;
+  }>;
+  metadata: {
+    depth_explored: number;
+    total_connections_explored: number;
+    connections_returned: number;
+    cycles_detected: number;
+    cycles_pruned: number;
+    entities_skipped: number;
+    query_duration_ms: number;
+    max_connections_exceeded?: boolean;
+  };
+  warning?: string;
+}
+
+function isSearchNodesResponse(data: unknown): data is SearchNodesResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'nodes' in data &&
+    Array.isArray((data as SearchNodesResponse).nodes)
+  );
+}
+
+function isSearchFactsResponse(data: unknown): data is SearchFactsResponse {
+  if (typeof data !== 'object' || data === null) return false;
+  if (!('facts' in data)) return false;
+  const facts = (data as SearchFactsResponse).facts;
+  if (!Array.isArray(facts)) return false;
+  // Validate at least first fact has expected fields (name+fact or source+target+relation)
+  if (facts.length > 0) {
+    const first = facts[0];
+    const hasNewFormat = 'name' in first && 'fact' in first;
+    const hasLegacyFormat = 'source' in first && 'target' in first && 'relation' in first;
+    return hasNewFormat || hasLegacyFormat;
+  }
+  return true; // Empty array is valid
+}
+
+function isGetEpisodesResponse(data: unknown): data is GetEpisodesResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'episodes' in data &&
+    Array.isArray((data as GetEpisodesResponse).episodes)
+  );
+}
+
+function isAddMemoryResponse(data: unknown): data is AddMemoryResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'message' in data &&
+    typeof (data as AddMemoryResponse).message === 'string'
+  );
+}
+
+function isGetStatusResponse(data: unknown): data is GetStatusResponse {
+  return typeof data === 'object' && data !== null && 'status' in data && 'message' in data;
+}
+
+function isDeleteResponse(data: unknown): data is DeleteResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'success' in data &&
+    typeof (data as DeleteResponse).success === 'boolean'
+  );
+}
+
+function isClearGraphResponse(data: unknown): data is ClearGraphResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'success' in data &&
+    typeof (data as ClearGraphResponse).success === 'boolean'
+  );
+}
+
+function isHealthMetricsResponse(data: unknown): data is HealthMetricsResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'states' in data &&
+    'aggregates' in data &&
+    'age_distribution' in data
+  );
+}
+
+function isMaintenanceResultResponse(data: unknown): data is MaintenanceResultResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'success' in data &&
+    'memories_processed' in data &&
+    'state_transitions' in data
+  );
+}
+
+function isClassificationResponse(data: unknown): data is ClassificationResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'importance' in data &&
+    'stability' in data &&
+    'is_permanent' in data
+  );
+}
+
+function isRecoveryResponse(data: unknown): data is RecoveryResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'message' in data &&
+    'uuid' in data &&
+    'name' in data &&
+    'new_state' in data
+  );
+}
+
+function isInvestigateEntityResponse(data: unknown): data is InvestigateEntityResponse {
+  if (typeof data !== 'object' || data === null) return false;
+  const d = data as Record<string, unknown>;
+  return (
+    'entity' in d &&
+    typeof d.entity === 'object' &&
+    d.entity !== null &&
+    'connections' in d &&
+    Array.isArray(d.connections) &&
+    'metadata' in d &&
+    typeof d.metadata === 'object' &&
+    d.metadata !== null
+  );
+}
+
+// ============================================================================
+// Individual Formatters (T014-T020)
+// ============================================================================
+
+/**
+ * Format search_nodes / search_memory_nodes response
+ * Output: Found N entities for "query":
+ *         1. Name [Type] - Summary (truncated to 120 chars)
+ *         When weighted scores present: 📊 Score: 0.XX (S:0.XX R:0.XX I:0.XX)
+ */
+export function formatSearchNodes(data: unknown, options: FormatOptions): string {
+  if (!isSearchNodesResponse(data)) {
+    throw new Error('Invalid data format for search_nodes');
+  }
+
+  const { nodes } = data;
+  const query = options.query || 'query';
+  const maxLines = options.maxLines ?? DEFAULT_OPTIONS.maxLines ?? 20;
+
+  if (nodes.length === 0) {
+    return `No entities found for "${query}"`;
+  }
+
+  const lines: string[] = [`Found ${nodes.length} entities for "${query}":`];
+
+  // DEBUG: Log first node structure to understand what attributes are present
+  if (nodes.length > 0) {
+    const firstNode = nodes[0];
+    console.error('[DEBUG] First node keys:', Object.keys(firstNode));
+    console.error('[DEBUG] First node sample:', JSON.stringify(firstNode).substring(0, 500));
+  }
+
+  const displayNodes = nodes.slice(0, maxLines);
+  displayNodes.forEach((node, index) => {
+    const summary = truncateText(node.summary || '', 120);
+    // Use labels array (new format) or entity_type (legacy)
+    const entityType = node.labels?.[0] || node.entity_type || 'Entity';
+
+    let line = `${index + 1}. ${node.name} [${entityType}] - ${summary}`;
+
+    // Display weighted scores if present (Feature 009: Memory Decay Scoring)
+    if (node.attributes?.weighted_score !== undefined) {
+      const score = node.attributes.weighted_score as number;
+      const breakdown = node.attributes.score_breakdown as { semantic: number; recency: number; importance: number } | undefined;
+
+      if (breakdown) {
+        line += `\n   📊 Score: ${score.toFixed(2)} (S:${breakdown.semantic.toFixed(2)} R:${breakdown.recency.toFixed(2)} I:${breakdown.importance.toFixed(2)})`;
+      } else {
+        line += `\n   📊 Score: ${score.toFixed(2)}`;
+      }
+
+      // Show lifecycle state if present
+      if (node.attributes.lifecycle_state) {
+        const state = node.attributes.lifecycle_state as string;
+        line += ` [${state}]`;
+      }
+
+      // Show importance/stability if present
+      if (node.attributes.importance !== undefined || node.attributes.stability !== undefined) {
+        const imp = node.attributes.importance as number | undefined;
+        const stab = node.attributes.stability as number | undefined;
+        const parts = [];
+        if (imp !== undefined) parts.push(`Imp:${imp}`);
+        if (stab !== undefined) parts.push(`Stab:${stab}`);
+        if (parts.length > 0) line += ` (${parts.join(' ')})`;
+      }
+    }
+
+    lines.push(line);
+  });
+
+  if (nodes.length > maxLines) {
+    lines.push(`... and ${nodes.length - maxLines} more`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format search_facts / search_memory_facts response
+ * Output: Found N facts for "query":
+ *         1. [RELATION] Fact description (truncated)
+ */
+export function formatSearchFacts(data: unknown, options: FormatOptions): string {
+  if (!isSearchFactsResponse(data)) {
+    throw new Error('Invalid data format for search_facts');
+  }
+
+  const { facts } = data;
+  const query = options.query || 'query';
+  const maxLines = options.maxLines ?? DEFAULT_OPTIONS.maxLines ?? 20;
+
+  if (facts.length === 0) {
+    return `No facts found for "${query}"`;
+  }
+
+  const lines: string[] = [`Found ${facts.length} facts for "${query}":`];
+
+  const displayFacts = facts.slice(0, maxLines);
+  displayFacts.forEach((fact, index) => {
+    // New format: name is relation type, fact is description
+    if (fact.name && fact.fact) {
+      const relation = fact.name.toUpperCase();
+      // Use full fact text - no truncation to preserve complete knowledge
+      lines.push(`${index + 1}. [${relation}] ${fact.fact}`);
+    }
+    // Legacy format: source/target/relation objects
+    else if (fact.source && fact.target && fact.relation) {
+      const relation = fact.relation.toLowerCase().replace(/_/g, '-');
+      let line = `${index + 1}. ${fact.source.name} --${relation}--> ${fact.target.name}`;
+      if (fact.confidence !== undefined && fact.confidence > 0) {
+        line += ` (${(fact.confidence * 100).toFixed(0)}%)`;
+      }
+      lines.push(line);
+    }
+  });
+
+  if (facts.length > maxLines) {
+    lines.push(`... and ${facts.length - maxLines} more`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format get_episodes response
+ * Output: Recent episodes (N):
+ *         - [2h ago] Name - Content preview...
+ */
+export function formatGetEpisodes(data: unknown, options: FormatOptions): string {
+  if (!isGetEpisodesResponse(data)) {
+    throw new Error('Invalid data format for get_episodes');
+  }
+
+  const { episodes } = data;
+  const maxLines = options.maxLines ?? DEFAULT_OPTIONS.maxLines ?? 20;
+
+  if (episodes.length === 0) {
+    return 'No episodes found';
+  }
+
+  const lines: string[] = [`Recent episodes (${episodes.length}):`];
+
+  const displayEpisodes = episodes.slice(0, maxLines);
+  displayEpisodes.forEach((episode) => {
+    const time = relativeTime(episode.created_at);
+    // Use full content - no truncation to preserve complete knowledge
+    const content = episode.content || '';
+    lines.push(`- [${time}] ${episode.name} - ${content}`);
+  });
+
+  if (episodes.length > maxLines) {
+    lines.push(`... and ${episodes.length - maxLines} more`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format add_memory response
+ * Output: ✓ Episode queued: "Episode 'Name' queued for processing in group 'main'"
+ * Legacy: ✓ Episode added: "Name" (id: ...uuid8)
+ *           Extracted: N entities, M facts
+ */
+export function formatAddMemory(data: unknown, _options: FormatOptions): string {
+  if (!isAddMemoryResponse(data)) {
+    throw new Error('Invalid data format for add_memory');
+  }
+
+  // New format: server returns a message string
+  const lines: string[] = [`✓ ${data.message}`];
+
+  // Legacy format: include uuid and extraction stats if available
+  if (data.uuid) {
+    const uuid = truncateUuid(data.uuid);
+    const name = data.name || 'Unnamed episode';
+    lines[0] = `✓ Episode added: "${name}" (id: ${uuid})`;
+  }
+
+  if (data.entities_extracted !== undefined || data.facts_extracted !== undefined) {
+    const entities = data.entities_extracted ?? 0;
+    const facts = data.facts_extracted ?? 0;
+    lines.push(`  Extracted: ${entities} entities, ${facts} facts`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format get_status response
+ * Output: Knowledge Graph Status: OK
+ *         Connected to neo4j database
+ */
+export function formatGetStatus(data: unknown, _options: FormatOptions): string {
+  if (!isGetStatusResponse(data)) {
+    throw new Error('Invalid data format for get_status');
+  }
+
+  const status = data.status.toUpperCase();
+  const lines: string[] = [`Knowledge Graph Status: ${status}`];
+  lines.push(data.message);
+
+  // Include legacy stats if available
+  if (data.entity_count !== undefined && data.episode_count !== undefined) {
+    let statsLine = `Entities: ${data.entity_count} | Episodes: ${data.episode_count}`;
+    if (data.last_updated) {
+      statsLine += ` | Last update: ${relativeTime(data.last_updated)}`;
+    }
+    lines.push(statsLine);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format delete_episode / delete_entity_edge response
+ * Output: ✓ Deleted: ...uuid8
+ *     or: ✗ Delete failed: message
+ */
+export function formatDelete(data: unknown, _options: FormatOptions): string {
+  if (!isDeleteResponse(data)) {
+    throw new Error('Invalid data format for delete');
+  }
+
+  if (data.success) {
+    const uuid = data.uuid ? truncateUuid(data.uuid) : 'unknown';
+    return `✓ Deleted: ${uuid}`;
+  }
+  const message = data.message || 'Unknown error';
+  return `✗ Delete failed: ${message}`;
+}
+
+/**
+ * Format clear_graph response
+ * Output: ✓ Knowledge graph cleared
+ *           Removed: N entities, M episodes
+ */
+export function formatClearGraph(data: unknown, _options: FormatOptions): string {
+  if (!isClearGraphResponse(data)) {
+    throw new Error('Invalid data format for clear_graph');
+  }
+
+  if (!data.success) {
+    return '✗ Clear graph failed';
+  }
+
+  const lines: string[] = ['✓ Knowledge graph cleared'];
+
+  if (data.deleted_entities !== undefined || data.deleted_episodes !== undefined) {
+    const entities = data.deleted_entities ?? 0;
+    const episodes = data.deleted_episodes ?? 0;
+    lines.push(`  Removed: ${entities} entities, ${episodes} episodes`);
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Feature 009: Memory Decay Formatters
+// ============================================================================
+
+/**
+ * Format get_knowledge_health response
+ * Output: Memory Lifecycle Health:
+ *         Lifecycle States: Active, Dormant, Archived, Expired, Soft Deleted, Permanent
+ *         Aggregates: Total, Avg Decay, Avg Importance, Avg Stability
+ *         Age Distribution: < 7d, 7-30d, 30-90d, > 90d
+ *         Last Maintenance: timestamp, duration, processed, transitions
+ */
+export function formatHealthMetrics(data: unknown, _options: FormatOptions): string {
+  if (!isHealthMetricsResponse(data)) {
+    throw new Error('Invalid data format for get_knowledge_health');
+  }
+
+  const lines: string[] = ['Memory Lifecycle Health:'];
+
+  // Lifecycle states
+  lines.push('\nLifecycle States:');
+  lines.push(`  Active:       ${data.states.active.toLocaleString()}`);
+  lines.push(`  Dormant:      ${data.states.dormant.toLocaleString()}`);
+  lines.push(`  Archived:     ${data.states.archived.toLocaleString()}`);
+  lines.push(`  Expired:      ${data.states.expired.toLocaleString()}`);
+  lines.push(`  Soft Deleted: ${data.states.soft_deleted.toLocaleString()}`);
+  lines.push(`  Permanent:    ${data.states.permanent.toLocaleString()}`);
+
+  // Aggregates
+  lines.push('\nAggregates:');
+  lines.push(`  Total:         ${data.aggregates.total.toLocaleString()}`);
+  lines.push(`  Avg Decay:     ${data.aggregates.average_decay.toFixed(3)}`);
+  lines.push(`  Avg Importance: ${data.aggregates.average_importance.toFixed(2)}/5`);
+  lines.push(`  Avg Stability:  ${data.aggregates.average_stability.toFixed(2)}/5`);
+
+  // Age distribution
+  lines.push('\nAge Distribution:');
+  lines.push(`  < 7 days:    ${data.age_distribution.under_7_days.toLocaleString()}`);
+  lines.push(`  7-30 days:   ${data.age_distribution.days_7_to_30.toLocaleString()}`);
+  lines.push(`  30-90 days:  ${data.age_distribution.days_30_to_90.toLocaleString()}`);
+  lines.push(`  > 90 days:   ${data.age_distribution.over_90_days.toLocaleString()}`);
+
+  // Maintenance info
+  if (data.maintenance.last_run) {
+    lines.push('\nLast Maintenance:');
+    lines.push(`  Run: ${relativeTime(data.maintenance.last_run)}`);
+    lines.push(`  Duration: ${data.maintenance.duration_seconds.toFixed(1)}s`);
+    lines.push(`  Processed: ${data.maintenance.processed.toLocaleString()}`);
+    lines.push(`  Transitions: ${data.maintenance.transitions.toLocaleString()}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format run_decay_maintenance response
+ * Output: ✓ Maintenance completed successfully
+ *         Processed: N memories
+ *         Duration: X.Xs
+ *         Classification: Found/Classified/Failed
+ *         Decay scores updated: N
+ *         State Transitions: ACTIVE→DORMANT, etc.
+ *         Purged: N soft-deleted memories
+ */
+export function formatMaintenanceResult(data: unknown, _options: FormatOptions): string {
+  if (!isMaintenanceResultResponse(data)) {
+    throw new Error('Invalid data format for run_decay_maintenance');
+  }
+
+  const lines: string[] = [];
+
+  if (data.success) {
+    lines.push('✓ Maintenance completed successfully');
+  } else {
+    lines.push(`✗ Maintenance failed: ${data.error || 'Unknown error'}`);
+  }
+
+  lines.push(`  Processed: ${data.memories_processed.toLocaleString()} memories`);
+  lines.push(`  Duration: ${data.duration_seconds.toFixed(1)}s`);
+
+  // Classification results
+  if (data.nodes_classified.classified > 0) {
+    lines.push('\nClassification:');
+    lines.push(`  Found: ${data.nodes_classified.found}`);
+    lines.push(`  Classified: ${data.nodes_classified.classified} (${data.nodes_classified.using_llm ? 'LLM' : 'default'})`);
+    if (data.nodes_classified.failed > 0) {
+      lines.push(`  Failed: ${data.nodes_classified.failed}`);
+    }
+  }
+
+  // Decay scores
+  if (data.decay_scores_updated > 0) {
+    lines.push(`\nDecay scores updated: ${data.decay_scores_updated.toLocaleString()}`);
+  }
+
+  // State transitions
+  const st = data.state_transitions;
+  const total = st.active_to_dormant + st.dormant_to_archived + st.archived_to_expired + st.expired_to_soft_deleted;
+  if (total > 0) {
+    lines.push('\nState Transitions:');
+    lines.push(`  ACTIVE → DORMANT:     ${st.active_to_dormant}`);
+    lines.push(`  DORMANT → ARCHIVED:   ${st.dormant_to_archived}`);
+    lines.push(`  ARCHIVED → EXPIRED:   ${st.archived_to_expired}`);
+    lines.push(`  EXPIRED → SOFT_DEL:   ${st.expired_to_soft_deleted}`);
+    lines.push(`  Total:                ${total}`);
+  }
+
+  // Purged
+  if (data.soft_deleted_purged > 0) {
+    lines.push(`\nPurged: ${data.soft_deleted_purged.toLocaleString()} soft-deleted memories`);
+  }
+
+  if (data.completed_at) {
+    lines.push(`\nCompleted: ${relativeTime(data.completed_at)}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format classify_memory response
+ * Output: Memory Classification:
+ *         Importance: 3/3 ★★★☆☆
+ *         Stability:  4/5 ★★★★☆
+ *         Source: llm
+ *         Status: Subject to decay / PERMANENT (exempt from decay)
+ */
+export function formatClassification(data: unknown, _options: FormatOptions): string {
+  if (!isClassificationResponse(data)) {
+    throw new Error('Invalid data format for classify_memory');
+  }
+
+  const lines: string[] = ['Memory Classification:'];
+  lines.push(`  Importance: ${data.importance}/5 ${'★'.repeat(data.importance)}${'☆'.repeat(5 - data.importance)}`);
+  lines.push(`  Stability:  ${data.stability}/5 ${'★'.repeat(data.stability)}${'☆'.repeat(5 - data.stability)}`);
+  lines.push(`  Source:     ${data.classification_source}`);
+
+  if (data.is_permanent) {
+    lines.push(`  Status:     PERMANENT (exempt from decay)`);
+  } else {
+    lines.push(`  Status:     Subject to decay`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format recover_soft_deleted response
+ * Output: ✓ Memory recovered successfully
+ *         Name: Memory Name
+ *         UUID: ...uuid8
+ *         New State: ARCHIVED
+ */
+export function formatRecovery(data: unknown, _options: FormatOptions): string {
+  if (!isRecoveryResponse(data)) {
+    throw new Error('Invalid data format for recover_soft_deleted');
+  }
+
+  const lines: string[] = [`✓ ${data.message}`];
+  lines.push(`  Name: ${data.name}`);
+  lines.push(`  UUID: ...${data.uuid.slice(-8)}`);
+  lines.push(`  New State: ${data.new_state}`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Format investigate_entity response
+ * Output: Entity: [Type] Name - Summary
+ *         Connections:
+ *           1. [RELATION] Target [Type] (hop N)
+ *         Metadata: depth=X, connections=Y, cycles=Z
+ */
+export function formatInvestigateEntity(data: unknown, _options: FormatOptions): string {
+  if (!isInvestigateEntityResponse(data)) {
+    throw new Error('Invalid data format for investigate_entity');
+  }
+
+  const { entity, connections, metadata, warning } = data;
+  const lines: string[] = [];
+
+  // Format the primary entity
+  const entityType = entity.labels?.[0] || 'Entity';
+  const summary = entity.summary ? truncateText(entity.summary, 120) : '';
+  lines.push(`Entity: [${entityType}] ${entity.name}${summary ? ' - ' + summary : ''}`);
+
+  // Format connections
+  if (connections.length === 0) {
+    lines.push('No connections found.');
+  } else {
+    lines.push(`\nConnections (${connections.length}):`);
+    connections.forEach((conn, index) => {
+      const targetType = conn.target_entity.labels?.[0] || 'Entity';
+      const relation = conn.relationship.toUpperCase();
+      const directionSymbol = conn.direction === 'outbound' ? '→' : conn.direction === 'inbound' ? '←' : '↔';
+      const hopInfo = conn.hop_distance > 1 ? ` (hop ${conn.hop_distance})` : '';
+
+      let connLine = `  ${index + 1}. [${relation}] ${directionSymbol} ${conn.target_entity.name} [${targetType}]${hopInfo}`;
+
+      if (conn.fact) {
+        connLine += `\n     Fact: ${truncateText(conn.fact, 100)}`;
+      }
+
+      if (conn.confidence !== undefined) {
+        connLine += ` (${(conn.confidence * 100).toFixed(0)}% confidence)`;
+      }
+
+      lines.push(connLine);
+    });
+  }
+
+  // Format metadata
+  lines.push('\nMetadata:');
+  lines.push(`  Depth explored: ${metadata.depth_explored}`);
+  lines.push(`  Connections: ${metadata.connections_returned}/${metadata.total_connections_explored}`);
+  if (metadata.cycles_detected > 0) {
+    lines.push(`  Cycles detected: ${metadata.cycles_detected} (pruned: ${metadata.cycles_pruned})`);
+  }
+  if (metadata.entities_skipped > 0) {
+    lines.push(`  Entities skipped: ${metadata.entities_skipped}`);
+  }
+  lines.push(`  Query duration: ${metadata.query_duration_ms}ms`);
+  if (metadata.max_connections_exceeded) {
+    lines.push(`  ⚠ Max connections limit exceeded`);
+  }
+
+  // Add warning if present
+  if (warning) {
+    lines.push(`\n⚠ Warning: ${warning}`);
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Main Entry Point (T021)
+// ============================================================================
+
+// Register all built-in formatters
+registerFormatter('search_nodes', formatSearchNodes);
+registerFormatter('search_memory_nodes', formatSearchNodes);
+registerFormatter('search_facts', formatSearchFacts);
+registerFormatter('search_memory_facts', formatSearchFacts);
+registerFormatter('get_episodes', formatGetEpisodes);
+registerFormatter('add_memory', formatAddMemory);
+registerFormatter('add_episode', formatAddMemory);
+registerFormatter('get_status', formatGetStatus);
+registerFormatter('delete_episode', formatDelete);
+registerFormatter('delete_entity_edge', formatDelete);
+registerFormatter('clear_graph', formatClearGraph);
+// Feature 009: Memory decay formatters
+registerFormatter('get_knowledge_health', formatHealthMetrics);
+registerFormatter('run_decay_maintenance', formatMaintenanceResult);
+registerFormatter('classify_memory', formatClassification);
+registerFormatter('recover_soft_deleted', formatRecovery);
+// Feature 020: Investigative search
+registerFormatter('investigate_entity', formatInvestigateEntity);
+
+/**
+ * Main entry point for formatting MCP responses.
+ * Routes to the appropriate formatter based on operation name.
+ * Falls back to JSON on unknown operations or errors.
+ */
+export function formatOutput(
+  operation: string,
+  data: unknown,
+  options?: FormatOptions
+): FormatResult {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const startTime = performance.now();
+
+  // Calculate raw size
+  const rawJson = JSON.stringify(data, null, 2);
+  const rawBytes = new TextEncoder().encode(rawJson).length;
+
+  // Try to find and execute formatter
+  const formatter = formatterRegistry.get(operation);
+
+  if (!formatter) {
+    // Unknown operation - fallback to JSON
+    return {
+      output: rawJson,
+      usedFallback: true,
+      error: `No formatter registered for operation: ${operation}`,
+      metrics: opts.collectMetrics
+        ? {
+            rawBytes,
+            compactBytes: rawBytes,
+            savingsPercent: 0,
+            processingTimeMs: performance.now() - startTime,
+          }
+        : undefined,
+    };
+  }
+
+  try {
+    const output = formatter(data, opts);
+    const compactBytes = new TextEncoder().encode(output).length;
+    const processingTimeMs = performance.now() - startTime;
+    const savingsPercent = rawBytes > 0 ? ((rawBytes - compactBytes) / rawBytes) * 100 : 0;
+
+    // Log slow transformations
+    if (processingTimeMs >= 50) {
+      logTransformationSuccess(operation, rawBytes, processingTimeMs).catch(() => {});
+    }
+
+    return {
+      output,
+      usedFallback: false,
+      metrics: opts.collectMetrics
+        ? {
+            rawBytes,
+            compactBytes,
+            savingsPercent,
+            processingTimeMs,
+          }
+        : undefined,
+    };
+  } catch (error) {
+    const processingTimeMs = performance.now() - startTime;
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+    // Log transformation failure
+    logTransformationFailure(operation, rawBytes, errorMessage, processingTimeMs).catch(() => {});
+
+    return {
+      output: rawJson,
+      usedFallback: true,
+      error: errorMessage,
+      metrics: opts.collectMetrics
+        ? {
+            rawBytes,
+            compactBytes: rawBytes,
+            savingsPercent: 0,
+            processingTimeMs,
+          }
+        : undefined,
+    };
+  }
+}