mpalpha · January 29, 2026 15:56
diff --git a/README.md b/README.md
diff --git a/index.js b/index.js
 #!/usr/bin/env node

 /**
 * Memory-Augmented Reasoning MCP Server
 * A concise MCP server for capturing and retrieving universal working knowledge.
 * Records meta-patterns about effective work with AI agents, tools, protocols, and processes.
 *
 * Version: 3.3.6
 * License: MIT
 */

 const Database = require('better-sqlite3');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');

 const VERSION = '3.3.6';

 // Custom error class for parameter validation (returns -32602 instead of -32603)
 // Phase 7.7: Support separate message (visible to agent) and details (in error.data)
 class ValidationError extends Error {
  constructor(message, details) {
    super(message);
    this.name = 'ValidationError';
    this.code = -32602; // Invalid params
    // If details provided, store separately for error.data
    // If only message provided, use it for both (backward compatible)
    this.details = details || message;

    // Log full error to stderr for debugging
    console.error(`[validation-error] ${message}`);
    if (details && details !== message) {
      console.error(`[validation-error] Full details: ${details}`);
    }
  }
 }

 // State tracking for session tokens
 const state = {
  sessionTokens: new Map(), // Map<sessionId, {expires: timestamp, created: timestamp}>
  sessionTokenTimeout: 3600000, // 60 minutes
  sessions: new Map() // NEW: Track phase completion for enhanced protocol (Phase 2)
 };

 // BUG #20 FIX: Background cleanup of expired session tokens (every 5 minutes)
 setInterval(() => {
  const now = Date.now();
  for (const [sessionId, tokenData] of state.sessionTokens.entries()) {
    if (tokenData.expires < now) {
      state.sessionTokens.delete(sessionId);
      // Clean up file system token
      const tokenFile = path.join(os.homedir(), `.protocol-session-${sessionId}.json`);
      try {
        fs.unlinkSync(tokenFile);
      } catch (err) {
        // Ignore errors - file may already be cleaned by GC
      }
    }
  }
 }, 300000); // 5 minutes

 // Expand environment variables in paths
 function expandPath(filePath) {
  if (!filePath) return filePath;

  // Expand ${HOME} or $HOME
  filePath = filePath.replace(/\$\{HOME\}|\$HOME/g, os.homedir());

  // Expand ${WORKSPACE_FOLDER} or $WORKSPACE_FOLDER with current working directory
  filePath = filePath.replace(/\$\{WORKSPACE_FOLDER\}|\$WORKSPACE_FOLDER/g, process.cwd());

  // Expand ~ at the beginning
  if (filePath.startsWith('~/')) {
    filePath = path.join(os.homedir(), filePath.slice(2));
  }

  return filePath;
 }

 // Database schema with FTS5 full-text search + informed reasoning enhancements
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS experiences (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  type TEXT NOT NULL CHECK(type IN ('effective', 'ineffective')),
  domain TEXT NOT NULL CHECK(domain IN ('Tools', 'Protocol', 'Communication', 'Process', 'Debugging', 'Decision')),
  situation TEXT NOT NULL,
  approach TEXT NOT NULL,
  outcome TEXT NOT NULL,
  reasoning TEXT NOT NULL,
  alternative TEXT,
  confidence REAL CHECK(confidence BETWEEN 0 AND 1),
  revision_of INTEGER,
  contradicts TEXT,
  supports TEXT,
  context TEXT,
  assumptions TEXT,
  limitations TEXT,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (revision_of) REFERENCES experiences(id)
 );

 CREATE INDEX IF NOT EXISTS idx_domain_type ON experiences(domain, type);
 CREATE INDEX IF NOT EXISTS idx_created ON experiences(created_at DESC);

 CREATE VIRTUAL TABLE IF NOT EXISTS experiences_fts USING fts5(
  situation, approach, outcome, reasoning, alternative, context, assumptions, limitations,
  content='experiences',
  content_rowid='id'
 );

 CREATE TRIGGER IF NOT EXISTS experiences_ai AFTER INSERT ON experiences BEGIN
  INSERT INTO experiences_fts(rowid, situation, approach, outcome, reasoning, alternative, context, assumptions, limitations)
  VALUES (new.id, new.situation, new.approach, new.outcome, new.reasoning, new.alternative, new.context, new.assumptions, new.limitations);
 END;

 CREATE TRIGGER IF NOT EXISTS experiences_ad AFTER DELETE ON experiences BEGIN
  DELETE FROM experiences_fts WHERE rowid = old.id;
 END;

 CREATE TRIGGER IF NOT EXISTS experiences_au AFTER UPDATE ON experiences BEGIN
  UPDATE experiences_fts SET situation=new.situation, approach=new.approach,
    outcome=new.outcome, reasoning=new.reasoning, alternative=new.alternative,
    context=new.context, assumptions=new.assumptions, limitations=new.limitations
  WHERE rowid = new.id;
 END;

 CREATE TABLE IF NOT EXISTS pattern_acceptance (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  domain TEXT NOT NULL,
  pattern_signature TEXT NOT NULL,
  presented_count INTEGER DEFAULT 0,
  accepted_count INTEGER DEFAULT 0,
  rejected_count INTEGER DEFAULT 0,
  acceptance_rate REAL GENERATED ALWAYS AS (
    CAST(accepted_count AS REAL) / NULLIF(presented_count, 0)
  ) STORED,
  last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(domain, pattern_signature)
 );

 CREATE INDEX IF NOT EXISTS idx_pattern_acceptance_domain ON pattern_acceptance(domain);
 CREATE INDEX IF NOT EXISTS idx_pattern_acceptance_rate ON pattern_acceptance(acceptance_rate DESC);

 CREATE TABLE IF NOT EXISTS protocol_sessions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL UNIQUE,
  started_at TEXT DEFAULT CURRENT_TIMESTAMP,
  last_activity TEXT DEFAULT CURRENT_TIMESTAMP,
  informed_reasoning_phases TEXT,
  protocol_steps_completed TEXT,
  checklist_items_verified TEXT,
  plan_approved BOOLEAN DEFAULT 0,
  plan_content TEXT,
  confidence_level TEXT,
  scope_boundaries TEXT,
  session_metadata TEXT
 );

 CREATE INDEX IF NOT EXISTS idx_session_id ON protocol_sessions(session_id);
 CREATE INDEX IF NOT EXISTS idx_last_activity ON protocol_sessions(last_activity DESC);

 CREATE TABLE IF NOT EXISTS protocol_events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  event_type TEXT NOT NULL,
  event_data TEXT,
  timestamp TEXT DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (session_id) REFERENCES protocol_sessions(session_id)
 );

 CREATE INDEX IF NOT EXISTS idx_events_session ON protocol_events(session_id, timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_events_type ON protocol_events(event_type);
 `;

 // Initialize database with schema
 function initDatabase(dbPath) {
  const dir = path.dirname(dbPath);
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }

  const db = new Database(dbPath);
  // Enable trusted_schema to allow FTS5 virtual table triggers
  db.exec('PRAGMA trusted_schema = ON;');
  db.exec(SCHEMA);
  return db;
 }

 // Load databases from environment variables
 function loadDatabases() {
  const dbs = {};

  // Always load user-level database (from env or default)
  const userDbPath = expandPath(
    process.env.MEMORY_AUGMENTED_REASONING_USER_DB ||
    path.join(os.homedir(), '.cursor', 'memory-augmented-reasoning.db')
  );
  dbs.user = initDatabase(userDbPath);

  // Load project-level database if env var is set
  if (process.env.MEMORY_AUGMENTED_REASONING_PROJECT_DB) {
    const projectDbPath = expandPath(process.env.MEMORY_AUGMENTED_REASONING_PROJECT_DB);
    dbs.project = initDatabase(projectDbPath);
  }

  return dbs;
 }

 // ============================================================================
 // SESSION MANAGEMENT
 // ============================================================================

 /**
 * Get Claude Code session ID with consistent priority chain
 * Priority: CLAUDE_SESSION_ID env → persistent session file → generate new
 * Matches hook implementations for consistency
 */
 function getSessionId() {
  // PRIORITY 1: Environment variable (set by Claude Code)
  if (process.env.CLAUDE_SESSION_ID) {
    return process.env.CLAUDE_SESSION_ID;
  }

  // PRIORITY 2: Persistent session file
  const sessionFilePath = path.join(os.homedir(), '.protocol-current-session-id');
  try {
    if (fs.existsSync(sessionFilePath)) {
      const sessionData = JSON.parse(fs.readFileSync(sessionFilePath, 'utf8'));
      // Check if session file is stale (>8 hours old)
      const age = Date.now() - sessionData.created;
      if (age < 8 * 60 * 60 * 1000) {
        return sessionData.session_id;
      }
    }
  } catch (err) {
    // Failed to read session file - continue to generate new
  }

  // PRIORITY 3: Generate new session ID and persist it
  const newSessionId = `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
  try {
    fs.writeFileSync(sessionFilePath, JSON.stringify({
      session_id: newSessionId,
      created: Date.now(),
      created_iso: new Date().toISOString()
    }));
  } catch (err) {
    // Failed to persist - session ID still usable, just won't persist across restarts
  }

  return newSessionId;
 }

 /**
 * Get or create protocol session
 */
 function getOrCreateSession(db, sessionId) {
  let session = db.prepare('SELECT * FROM protocol_sessions WHERE session_id = ?').get(sessionId);

  if (!session) {
    db.prepare(`
      INSERT INTO protocol_sessions (session_id)
      VALUES (?)
    `).run(sessionId);

    session = db.prepare('SELECT * FROM protocol_sessions WHERE session_id = ?').get(sessionId);
  }

  return session;
 }

 /**
 * Update session activity timestamp
 */
 function updateSessionActivity(db, sessionId) {
  db.prepare(`
    UPDATE protocol_sessions
    SET last_activity = CURRENT_TIMESTAMP
    WHERE session_id = ?
  `).run(sessionId);
 }

 /**
 * Record protocol event
 */
 function recordProtocolEvent(db, sessionId, eventType, eventData) {
  db.prepare(`
    INSERT INTO protocol_events (session_id, event_type, event_data)
    VALUES (?, ?, ?)
  `).run(sessionId, eventType, JSON.stringify(eventData));
 }

 /**
 * Update session phases
 */
 function updateSessionPhases(db, sessionId, phase) {
  const session = getOrCreateSession(db, sessionId);
  const phases = session.informed_reasoning_phases ? JSON.parse(session.informed_reasoning_phases) : [];

  if (!phases.includes(phase)) {
    phases.push(phase);
    db.prepare(`
      UPDATE protocol_sessions
      SET informed_reasoning_phases = ?
      WHERE session_id = ?
    `).run(JSON.stringify(phases), sessionId);
  }
 }

 // ============================================================================
 // DEDUPLICATION LOGIC
 // ============================================================================

 /**
 * Calculate string similarity using Dice coefficient
 * Returns value between 0 (no similarity) and 1 (identical)
 */
 function calculateStringSimilarity(str1, str2) {
  if (!str1 || !str2) return 0;
  if (str1 === str2) return 1;

  const normalize = (s) => s.toLowerCase().trim();
  const a = normalize(str1);
  const b = normalize(str2);

  if (a.length < 2 || b.length < 2) return 0;

  // Create bigram sets
  const aBigrams = new Set();
  const bBigrams = new Set();

  for (let i = 0; i < a.length - 1; i++) {
    aBigrams.add(a.substring(i, i + 2));
  }

  for (let i = 0; i < b.length - 1; i++) {
    bBigrams.add(b.substring(i, i + 2));
  }

  // Count intersections
  let intersection = 0;
  for (const bigram of aBigrams) {
    if (bBigrams.has(bigram)) intersection++;
  }

  // Dice coefficient
  return (2 * intersection) / (aBigrams.size + bBigrams.size);
 }

 /**
 * Compare two experiences to determine if they're similar
 * Returns true if experiences are similar enough to be considered duplicates
 */
 function areExperiencesSimilar(existing, newExperience, threshold = 0.7) {
  // Must be same domain
  if (existing.domain !== newExperience.domain) return false;

  // Must be same type (effective/ineffective)
  if (existing.type !== newExperience.type) return false;

  // Calculate similarity scores for key fields
  const situationSimilarity = calculateStringSimilarity(existing.situation, newExperience.situation);
  const approachSimilarity = calculateStringSimilarity(existing.approach, newExperience.approach);

  // Consider similar if situation AND approach are above threshold
  return situationSimilarity >= threshold && approachSimilarity >= threshold;
 }

 /**
 * Determine if new experience should update existing one
 * Update if: higher confidence OR better reasoning OR more specific
 */
 function shouldUpdateExperience(existing, newExperience) {
  const newConfidence = newExperience.confidence || 0;
  const existingConfidence = existing.confidence || 0;

  // Update if significantly higher confidence
  if (newConfidence > existingConfidence + 0.1) return true;

  // Update if same/similar confidence but better reasoning
  if (Math.abs(newConfidence - existingConfidence) < 0.1) {
    const newReasoningLength = (newExperience.reasoning || '').length;
    const existingReasoningLength = (existing.reasoning || '').length;

    // Update if new reasoning is significantly more detailed
    if (newReasoningLength > existingReasoningLength * 1.2) return true;

    // Update if new experience has more context/assumptions/limitations
    const newHasMore =
      (newExperience.context ? 1 : 0) +
      (newExperience.assumptions ? 1 : 0) +
      (newExperience.limitations ? 1 : 0);

    const existingHasMore =
      (existing.context ? 1 : 0) +
      (existing.assumptions ? 1 : 0) +
      (existing.limitations ? 1 : 0);

    if (newHasMore > existingHasMore) return true;
  }

  return false;
 }

 /**
 * Find similar experiences in database
 * Returns array of similar experiences
 */
 function findSimilarExperiences(db, newExperience) {
  // Query experiences with same domain and type
  const candidates = db.prepare(`
    SELECT * FROM experiences
    WHERE domain = ? AND type = ?
    ORDER BY created_at DESC
    LIMIT 50
  `).all(newExperience.domain, newExperience.type);

  // Filter to truly similar experiences
  const similar = [];
  for (const candidate of candidates) {
    if (areExperiencesSimilar(candidate, newExperience)) {
      similar.push(candidate);
    }
  }

  return similar;
 }

 /**
 * Check for duplicates and determine action
 * Returns: { action: 'save'|'update'|'skip', existingId?: number, reason: string }
 */
 function checkDuplication(db, newExperience) {
  const similarExperiences = findSimilarExperiences(db, newExperience);

  if (similarExperiences.length === 0) {
    return {
      action: 'save',
      reason: 'No similar experiences found'
    };
  }

  // Find best matching existing experience
  let bestMatch = similarExperiences[0];
  let highestSimilarity = 0;

  for (const similar of similarExperiences) {
    const situationSim = calculateStringSimilarity(similar.situation, newExperience.situation);
    const approachSim = calculateStringSimilarity(similar.approach, newExperience.approach);
    const avgSim = (situationSim + approachSim) / 2;

    if (avgSim > highestSimilarity) {
      highestSimilarity = avgSim;
      bestMatch = similar;
    }
  }

  // If very similar (>90%), check if update is warranted
  if (highestSimilarity > 0.9) {
    if (shouldUpdateExperience(bestMatch, newExperience)) {
      return {
        action: 'update',
        existingId: bestMatch.id,
        reason: `Updating existing experience #${bestMatch.id} with improved information`
      };
    } else {
      return {
        action: 'skip',
        existingId: bestMatch.id,
        reason: `Duplicate of existing experience #${bestMatch.id} (similarity: ${(highestSimilarity * 100).toFixed(1)}%)`
      };
    }
  }

  // If moderately similar (70-90%), save as new but note relationship
  if (highestSimilarity > 0.7) {
    return {
      action: 'save',
      relatedId: bestMatch.id,
      reason: `Similar to experience #${bestMatch.id} but distinct enough to save separately`
    };
  }

  // Not similar enough
  return {
    action: 'save',
    reason: 'Sufficiently distinct from existing experiences'
  };
 }

 // ============================================================================
 // END DEDUPLICATION LOGIC
 // ============================================================================

 // ============================================================================
 // AUTOMATIC SCOPE DETECTION (v3.1.0)
 // ============================================================================

 // Cache for project keywords (cleared on restart)
 const scopeDetectionCache = {
  projectKeywords: null,
  discoveredAt: null
 };

 // Load automatic experience recording configuration
 function loadAutoScopeConfig() {
  const configPath = path.join(process.cwd(), '.protocol-enforcer.json');
  if (fs.existsSync(configPath)) {
    try {
      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
      return config.automatic_experience_recording || {};
    } catch (e) {
      console.error('[memory-augmented-reasoning-mcp] Failed to load auto-scope config:', e.message);
    }
  }

  // Default configuration
  return {
    scope: 'auto',
    auto_discover_keywords: true,
    project_keywords: [],
    default_when_uncertain: 'project'
  };
 }

 // Auto-discover project keywords from git, package.json, directory structure
 function discoverProjectKeywords() {
  const startTime = Date.now();

  // Return cached if available and fresh
  if (scopeDetectionCache.projectKeywords && scopeDetectionCache.discoveredAt) {
    const age = Date.now() - scopeDetectionCache.discoveredAt;
    if (age < 3600000) { // Cache for 1 hour
      return scopeDetectionCache.projectKeywords;
    }
  }

  const keywords = new Set();

  // 1. Git repository name
  try {
    const gitConfigPath = path.join(process.cwd(), '.git', 'config');
    if (fs.existsSync(gitConfigPath)) {
      const gitConfig = fs.readFileSync(gitConfigPath, 'utf8');
      const urlMatch = gitConfig.match(/url\s*=\s*.+\/([^\/\n]+?)(?:\.git)?$/m);
      if (urlMatch) {
        keywords.add(urlMatch[1].toLowerCase());
      }
    }
  } catch (e) {
    // Silent fail
  }

  // 2. Package.json name
  try {
    const packagePath = path.join(process.cwd(), 'package.json');
    if (fs.existsSync(packagePath)) {
      const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
      if (pkg.name) {
        // Handle scoped packages like @org/package
        const pkgName = pkg.name.startsWith('@') ? pkg.name.split('/')[1] : pkg.name;
        keywords.add(pkgName.toLowerCase());
      }
    }
  } catch (e) {
    // Silent fail
  }

  // 3. Root directory name
  try {
    const rootDir = path.basename(process.cwd()).toLowerCase();
    if (rootDir && rootDir !== '.' && rootDir !== '..') {
      keywords.add(rootDir);
    }
  } catch (e) {
    // Silent fail
  }

  // 4. Top-level directories (src, lib, components, etc.)
  try {
    const topLevel = fs.readdirSync(process.cwd(), { withFileTypes: true });
    const relevantDirs = topLevel
      .filter(d => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'node_modules')
      .map(d => d.name.toLowerCase())
      .slice(0, 5); // Limit to first 5
    relevantDirs.forEach(dir => keywords.add(dir));
  } catch (e) {
    // Silent fail
  }

  const result = Array.from(keywords);

  // Cache results
  scopeDetectionCache.projectKeywords = result;
  scopeDetectionCache.discoveredAt = Date.now();

  const elapsed = Date.now() - startTime;
  console.error(`[memory-augmented-reasoning-mcp] Auto-discovered ${result.length} project keywords in ${elapsed}ms`);

  return result;
 }

 // Detect scope based on experience content
 function detectExperienceScope(experience, config) {
  const startTime = Date.now();

  // Combine all text fields for analysis
  const combinedText = [
    experience.situation,
    experience.approach,
    experience.outcome,
    experience.reasoning
  ].join(' ').toLowerCase();

  // 1. Manual config override (highest priority)
  if (config.project_keywords && config.project_keywords.length > 0) {
    for (const keyword of config.project_keywords) {
      if (combinedText.includes(keyword.toLowerCase())) {
        const elapsed = Date.now() - startTime;
        console.error(`[memory-augmented-reasoning-mcp] Scope: 'project' (manual keyword: ${keyword}, ${elapsed}ms)`);
        return 'project';
      }
    }
  }

  // 2. File path detection (project-specific paths)
  const projectPathPatterns = [
    '/src/', '/lib/', '/components/', '/modules/', '/packages/',
    '/app/', '/pages/', '/api/', '/server/', '/client/',
    '/test/', '/tests/', '/spec/', '/specs/',
    'src/', 'lib/', 'components/', 'app/'
  ];

  for (const pattern of projectPathPatterns) {
    if (combinedText.includes(pattern)) {
      const elapsed = Date.now() - startTime;
      console.error(`[memory-augmented-reasoning-mcp] Scope: 'project' (file path: ${pattern}, ${elapsed}ms)`);
      return 'project';
    }
  }

  // 3. Auto-discovered project keywords
  if (config.auto_discover_keywords !== false) {
    const projectKeywords = discoverProjectKeywords();
    for (const keyword of projectKeywords) {
      if (combinedText.includes(keyword)) {
        const elapsed = Date.now() - startTime;
        console.error(`[memory-augmented-reasoning-mcp] Scope: 'project' (auto keyword: ${keyword}, ${elapsed}ms)`);
        return 'project';
      }
    }
  }

  // 4. Generic tool/protocol patterns suggest user scope
  const userScopePatterns = [
    'read tool', 'write tool', 'edit tool', 'grep tool', 'glob tool', 'bash tool',
    'mcp server', 'protocol', 'hook', 'workflow', 'enforcement'
  ];

  let userMatches = 0;
  for (const pattern of userScopePatterns) {
    if (combinedText.includes(pattern)) {
      userMatches++;
    }
  }

  if (userMatches >= 2) {
    const elapsed = Date.now() - startTime;
    console.error(`[memory-augmented-reasoning-mcp] Scope: 'user' (generic patterns: ${userMatches}, ${elapsed}ms)`);
    return 'user';
  }

  // 5. Fall back to configured default
  const defaultScope = config.default_when_uncertain || 'project';
  const elapsed = Date.now() - startTime;
  console.error(`[memory-augmented-reasoning-mcp] Scope: '${defaultScope}' (default fallback, ${elapsed}ms)`);
  return defaultScope;
 }

 // ============================================================================
 // END AUTOMATIC SCOPE DETECTION
 // ============================================================================

 // Record experience to specified database
 function recordExperience(dbs, params) {
  // Validate required parameters upfront
  const required = ['type', 'domain', 'situation', 'approach', 'outcome', 'reasoning'];
  const missing = required.filter(field => !params[field]);

  if (missing.length > 0) {
    throw new ValidationError(
      `Invalid params: missing ${missing.join(', ')}`,
      `Missing required parameter: ${missing.join(', ')}\n` +
      `All required fields: type, domain, situation, approach, outcome, reasoning\n` +
      `Example: { type: "effective", domain: "Tools", situation: "...", approach: "...", outcome: "...", reasoning: "..." }`
    );
  }

  // Validate enum values
  const validTypes = ['effective', 'ineffective'];
  if (!validTypes.includes(params.type)) {
    throw new ValidationError(
      `Invalid params: type must be "effective" or "ineffective"`,
      `Invalid type: "${params.type}"\n` +
      `Valid values: "effective", "ineffective"\n` +
      `Example: { type: "effective", domain: "Tools", situation: "...", approach: "...", outcome: "...", reasoning: "..." }`
    );
  }

  const validDomains = ['Tools', 'Protocol', 'Communication', 'Process', 'Debugging', 'Decision'];
  if (!validDomains.includes(params.domain)) {
    throw new ValidationError(
      `Invalid params: domain must be one of: ${validDomains.join(', ')}`,
      `Invalid domain: "${params.domain}"\n` +
      `Valid values: ${validDomains.join(', ')}\n` +
      `Example: { type: "effective", domain: "Tools", situation: "...", approach: "...", outcome: "...", reasoning: "..." }`
    );
  }

  // Automatic scope detection (v3.1.0)
  let scope;
  if (params.scope && params.scope !== 'auto') {
    // Explicit scope provided (not "auto")
    scope = params.scope;
  } else {
    // Scope is "auto" or not provided - detect automatically
    const config = loadAutoScopeConfig();
    scope = detectExperienceScope(params, config);
  }

  const db = dbs[scope];

  if (!db) {
    throw new Error(`Database scope '${scope}' not configured`);
  }

  // Check for duplicates
  const duplicationCheck = checkDuplication(db, params);

  // Handle skip action
  if (duplicationCheck.action === 'skip') {
    // TEACH GATE: Clear recording requirement tokens
    try {
      const homeDir = os.homedir();
      const files = fs.readdirSync(homeDir);
      const recordingTokens = files.filter(f => f.startsWith('.protocol-recording-required-'));
      for (const file of recordingTokens) {
        try {
          fs.unlinkSync(path.join(homeDir, file));
        } catch (e) {
          // Silent fail
        }
      }
    } catch (e) {
      // Silent fail
    }

    return {
      success: true,
      action: 'skip',
      id: duplicationCheck.existingId,
      scope: scope,
      message: duplicationCheck.reason
    };
  }

  // Handle update action
  if (duplicationCheck.action === 'update') {
    const updateStmt = db.prepare(`
      UPDATE experiences
      SET situation = ?, approach = ?, outcome = ?, reasoning = ?,
          alternative = ?, confidence = ?, context = ?, assumptions = ?, limitations = ?,
          revision_of = ?
      WHERE id = ?
    `);

    updateStmt.run(
      params.situation,
      params.approach,
      params.outcome,
      params.reasoning,
      params.alternative || null,
      params.confidence || null,
      params.context || null,
      params.assumptions || null,
      params.limitations || null,
      duplicationCheck.existingId, // Mark as revision of existing
      duplicationCheck.existingId
    );

    // TEACH GATE: Clear recording requirement tokens
    try {
      const homeDir = os.homedir();
      const files = fs.readdirSync(homeDir);
      const recordingTokens = files.filter(f => f.startsWith('.protocol-recording-required-'));
      for (const file of recordingTokens) {
        try {
          fs.unlinkSync(path.join(homeDir, file));
        } catch (e) {
          // Silent fail
        }
      }
    } catch (e) {
      // Silent fail
    }

    return {
      success: true,
      action: 'update',
      id: duplicationCheck.existingId,
      scope: scope,
      message: duplicationCheck.reason
    };
  }

  // Handle save action (new experience)
  const insertStmt = db.prepare(`
    INSERT INTO experiences (
      type, domain, situation, approach, outcome, reasoning, alternative,
      confidence, revision_of, contradicts, supports, context, assumptions, limitations
    )
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
  `);

  const result = insertStmt.run(
    params.type,
    params.domain,
    params.situation,
    params.approach,
    params.outcome,
    params.reasoning,
    params.alternative || null,
    params.confidence || null,
    duplicationCheck.relatedId || params.revision_of || null,
    params.contradicts || null,
    params.supports || null,
    params.context || null,
    params.assumptions || null,
    params.limitations || null
  );

  // TEACH GATE: Clear recording requirement tokens for all sessions
  try {
    const homeDir = os.homedir();
    const files = fs.readdirSync(homeDir);
    const recordingTokens = files.filter(f => f.startsWith('.protocol-recording-required-'));

    for (const file of recordingTokens) {
      try {
        fs.unlinkSync(path.join(homeDir, file));
      } catch (e) {
        // Silent fail - token cleanup is not critical
      }
    }
  } catch (e) {
    // Silent fail - directory read errors are not critical
  }

  return {
    success: true,
    action: 'save',
    id: result.lastInsertRowid,
    scope: scope,
    message: duplicationCheck.reason,
    relatedTo: duplicationCheck.relatedId || null
  };
 }

 // Query with FTS5 full-text search
 function queryWithFTS(db, params, source) {
  if (params.query) {
    try {
      // Split query into terms, quote each individually, join with OR
      // This enables partial matching with BM25 relevance ranking
      const terms = params.query.trim().split(/\s+/)
        .map(term => `"${term.replace(/"/g, '""')}"`)
        .join(' OR ');

      // Use FTS5 for text search with BM25 ranking
      return db.prepare(`
        SELECT l.*, ? as source FROM experiences l
        JOIN experiences_fts ON l.id = experiences_fts.rowid
        WHERE experiences_fts MATCH ?
          AND (? IS NULL OR l.domain = ?)
          AND (? IS NULL OR l.type = ?)
        ORDER BY bm25(experiences_fts)
      `).all(source, terms, params.domain, params.domain, params.type, params.type);
    } catch (error) {
      // If FTS5 query fails (invalid syntax), fall back to LIKE search
      console.error('[memory-augmented-reasoning-mcp] FTS5 query failed, falling back to LIKE:', error.message);
      const likePattern = `%${params.query}%`;
      return db.prepare(`
        SELECT *, ? as source FROM experiences
        WHERE (situation LIKE ? OR approach LIKE ? OR outcome LIKE ? OR reasoning LIKE ?)
          AND (? IS NULL OR domain = ?)
          AND (? IS NULL OR type = ?)
        ORDER BY created_at DESC
      `).all(source, likePattern, likePattern, likePattern, likePattern, params.domain, params.domain, params.type, params.type);
    }
  } else {
    // Direct query without FTS
    return db.prepare(`
      SELECT *, ? as source FROM experiences
      WHERE (? IS NULL OR domain = ?)
        AND (? IS NULL OR type = ?)
      ORDER BY created_at DESC
    `).all(source, params.domain, params.domain, params.type, params.type);
  }
 }

 // Search experiences across both databases
 function searchExperiences(dbs, params) {
  // LEARN GATE: Clear search requirement and create completion token
  const searchRequiredPath = path.join(os.homedir(), '.protocol-search-required-token');
  if (fs.existsSync(searchRequiredPath)) {
    try {
      fs.unlinkSync(searchRequiredPath);
    } catch (e) {
      // Silent fail - token cleanup is not critical
    }
  }

  // Create session-specific search-completed token (5-minute TTL)
  const sessionId = getSessionId();
  const searchCompletedPath = path.join(os.homedir(), `.protocol-search-completed-${sessionId}`);
  const searchCompletedData = {
    completed: new Date().toISOString(),
    expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(), // 5 minutes
    session_id: sessionId
  };
  try {
    fs.writeFileSync(searchCompletedPath, JSON.stringify(searchCompletedData, null, 2));
  } catch (e) {
    // Silent fail - token creation is not critical
  }

  const results = [];

  // Search project database first (higher priority)
  if (dbs.project) {
    const projectResults = queryWithFTS(dbs.project, params, 'project');
    results.push(...projectResults);
  }

  // Search user database
  const userResults = queryWithFTS(dbs.user, params, 'user');
  results.push(...userResults);

  // Deduplicate by (domain, situation, approach)
  const seen = new Set();
  const deduped = [];

  for (const result of results) {
    const key = `${result.domain}|${result.situation}|${result.approach}`;
    if (!seen.has(key)) {
      seen.add(key);
      deduped.push(result);
    }
  }

  // Apply limit
  const limit = params.limit || parseInt(process.env.LEARNING_LIBRARY_MAX_RESULTS || '50');
  return deduped.slice(0, limit);
 }

 // Export experiences to JSON or Markdown
 function exportExperiences(dbs, params) {
  const scope = params.scope || 'user';
  const db = dbs[scope];

  if (!db) {
    throw new Error(`Database scope '${scope}' not configured`);
  }

  let query = 'SELECT * FROM experiences WHERE 1=1';
  const bindings = [];

  if (params.domain) {
    query += ' AND domain = ?';
    bindings.push(params.domain);
  }

  if (params.type) {
    query += ' AND type = ?';
    bindings.push(params.type);
  }

  query += ' ORDER BY created_at DESC';

  const experiences = db.prepare(query).all(...bindings);

  const format = params.format || 'json';
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
  const filename = params.filename || `experiences_${scope}_${timestamp}.${format === 'json' ? 'json' : 'md'}`;

  const exportDir = path.join(process.cwd(), '.cursor', 'experience-exports');
  if (!fs.existsSync(exportDir)) {
    fs.mkdirSync(exportDir, { recursive: true });
  }

  const exportPath = path.join(exportDir, filename);

  if (format === 'json') {
    fs.writeFileSync(exportPath, JSON.stringify(experiences, null, 2), 'utf8');
  } else {
    // Markdown format
    let markdown = `# Memory-Augmented Reasoning Export\n\n`;
    markdown += `**Scope:** ${scope}\n`;
    markdown += `**Date:** ${new Date().toISOString()}\n`;
    markdown += `**Count:** ${experiences.length}\n\n`;

    for (const experience of experiences) {
      markdown += `## ${experience.domain} - ${experience.type}\n\n`;
      markdown += `**Situation:** ${experience.situation}\n\n`;
      markdown += `**Approach:** ${experience.approach}\n\n`;
      markdown += `**Outcome:** ${experience.outcome}\n\n`;
      markdown += `**Reasoning:** ${experience.reasoning}\n\n`;
      if (experience.alternative) {
        markdown += `**Alternative:** ${experience.alternative}\n\n`;
      }
      markdown += `**Created:** ${experience.created_at}\n\n`;
      markdown += `---\n\n`;
    }

    fs.writeFileSync(exportPath, markdown, 'utf8');
  }

  return {
    success: true,
    path: exportPath,
    count: experiences.length,
    format: format
  };
 }

 // ============================================================================
 // PHASE 2: ACTIVE REASONING - informed_reasoning Tool Implementation
 // ============================================================================

 // Helper: Estimate token count (rough approximation: 1 token ≈ 4 characters)
 function estimateTokens(content) {
  if (!content) return 0;
  const str = typeof content === 'string' ? content : JSON.stringify(content);
  return Math.ceil(str.length / 4);
 }

 // Helper: Extract protocol rules from local documentation
 function extractProtocolRules(localDocs) {
  const rules = [];
  for (const doc of localDocs) {
    // Handle both 'path' and 'source' fields for flexibility
    const docPath = doc.path || doc.source || '';
    if (docPath.includes('.cursor/rules/') || docPath.endsWith('CLAUDE.md')) {
      // Extract rule-like patterns (lines starting with -, *, or numbered lists)
      const lines = doc.content.split('\n');
      for (const line of lines) {
        if (/^[-*\d]+\.?\s+/.test(line.trim()) && line.length > 20) {
          rules.push(line.trim());
        }
      }
    }
  }
  return rules;
 }

 // Helper functions for user intent extraction
 function extractGoal(problem) {
  const normalized = problem.toLowerCase().trim();

  // Detect informational requests
  if (normalized.match(/^(what|how|why|when|where|which|explain|tell|show|list)/)) {
    return `Understand ${normalized.split(/\s+/).slice(1, 5).join(' ')}`;
  }

  // Detect status/summary requests
  if (normalized.match(/(standup|status|summary|progress|update)/)) {
    return 'Brief status update';
  }

  // Detect action requests
  if (normalized.match(/^(create|add|implement|build|fix|update|refactor|optimize)/)) {
    const action = normalized.split(/\s+/)[0];
    const target = normalized.split(/\s+/).slice(1, 4).join(' ');
    return `${action.charAt(0).toUpperCase() + action.slice(1)} ${target}`;
  }

  // Default: extract first meaningful phrase
  return problem.split(/[.?!]/)[0].trim().slice(0, 50);
 }

 function extractPriority(problem) {
  const normalized = problem.toLowerCase();

  if (normalized.match(/(quick|brief|short|fast|asap)/)) {
    return 'Speed and clarity';
  }
  if (normalized.match(/(detailed|comprehensive|thorough|complete)/)) {
    return 'Completeness and accuracy';
  }
  if (normalized.match(/(fix|bug|error|broken)/)) {
    return 'Correctness and reliability';
  }
  if (normalized.match(/(optimize|performance|speed|slow)/)) {
    return 'Efficiency';
  }

  return 'Balance of speed and quality';
 }

 function extractFormat(problem) {
  const normalized = problem.toLowerCase();

  if (normalized.match(/(standup|status)/)) {
    return 'Git log + current work';
  }
  if (normalized.match(/^(list|show|display)/)) {
    return 'Structured list';
  }
  if (normalized.match(/(explain|how|why)/)) {
    return 'Detailed explanation';
  }
  if (normalized.match(/(summary|brief)/)) {
    return 'Concise summary';
  }

  return 'Clear and actionable';
 }

 function categorizeRequest(problem) {
  const normalized = problem.toLowerCase();

  if (normalized.match(/(standup|status|progress|update)/)) {
    return 'Recurring informational';
  }
  if (normalized.match(/(how|what|why|explain)/)) {
    return 'Knowledge request';
  }
  if (normalized.match(/(create|add|implement|build)/)) {
    return 'New feature';
  }
  if (normalized.match(/(fix|bug|error|broken)/)) {
    return 'Bug fix';
  }
  if (normalized.match(/(refactor|optimize|improve)/)) {
    return 'Code improvement';
  }

  return 'General task';
 }

 function generateFocusedQuery(problem) {
  const normalized = problem.toLowerCase().trim();

  // Extract key patterns (remove question marks, filler words)
  const fillerWords = ['a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been',
                       'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will',
                       'would', 'could', 'should', 'may', 'might', 'can', 'i', 'you',
                       'we', 'they', 'my', 'your', 'our', 'their', 'to', 'from', 'for'];

  const words = normalized
    .replace(/[?!.,;:]/g, '')
    .split(/\s+/)
    .filter(w => w.length > 2 && !fillerWords.includes(w));

  // Take first 3-5 meaningful words
  const keyWords = words.slice(0, 5).join(' ');

  // Limit to 20 words maximum
  const result = keyWords.split(/\s+/).slice(0, 20).join(' ');

  return result || problem.slice(0, 100);
 }

 function extractPatterns(problem) {
  const normalized = problem.toLowerCase().trim();
  const patterns = [];

  // Extract domain-specific patterns
  if (normalized.match(/(standup|status)/)) patterns.push('standup', 'status');
  if (normalized.match(/(jira|ticket|issue)/)) patterns.push('jira', 'ticket');
  if (normalized.match(/(git|commit|branch)/)) patterns.push('git', 'version-control');
  if (normalized.match(/(test|testing|spec)/)) patterns.push('testing');
  if (normalized.match(/(api|endpoint|request)/)) patterns.push('api');
  if (normalized.match(/(database|query|sql)/)) patterns.push('database');

  // Extract action patterns
  if (normalized.match(/^(how|what|why|explain)/)) patterns.push('informational');
  if (normalized.match(/^(create|add|implement)/)) patterns.push('creation');
  if (normalized.match(/^(fix|bug|error)/)) patterns.push('debugging');

  return patterns.length > 0 ? patterns : ['general'];
 }

 function categorizeDomain(problem) {
  const normalized = problem.toLowerCase();

  if (normalized.match(/(jira|ticket|issue|task)/)) return 'Tools';
  if (normalized.match(/(standup|status|summary|report)/)) return 'Communication';
  if (normalized.match(/(decide|choose|option|approach)/)) return 'Decision';
  if (normalized.match(/(bug|error|fix|broken)/)) return 'Debugging';
  if (normalized.match(/(how|why|explain|understand)/)) return 'Process';

  return null; // Search all domains
 }

 function identifyKeyFactors(problem) {
  const normalized = problem.toLowerCase();
  const factors = [];

  if (normalized.match(/(standup|status|brief|quick)/)) factors.push('recency', 'brevity');
  if (normalized.match(/(detailed|comprehensive|thorough)/)) factors.push('completeness', 'accuracy');
  if (normalized.match(/(similar|like|previous)/)) factors.push('similarity', 'recency');
  if (normalized.match(/(best|optimal|recommended)/)) factors.push('effectiveness', 'confidence');

  return factors.length > 0 ? factors : ['relevance'];
 }

 // Phase 1: ANALYZE - Identify relevant sources based on availableTools
 function analyzePhase(params) {
  const { problem, availableTools = [] } = params;

  // Validate required parameters
  if (!problem || typeof problem !== 'string' || problem.trim().length === 0) {
    const briefMsg = !problem
      ? 'Invalid params: missing problem parameter'
      : 'Invalid params: problem must be non-empty string';
    const details = !problem
      ? 'Missing required parameter: problem\nThe problem parameter must be a non-empty string describing what you want to solve.\nExample: { phase: "analyze", problem: "How to optimize database queries" }'
      : 'Invalid parameter: problem must be a non-empty string\nExample: { phase: "analyze", problem: "How to optimize database queries" }';
    throw new ValidationError(briefMsg, details);
  }

  // Extract user intent
  const userIntent = {
    goal: extractGoal(problem),
    priority: extractPriority(problem),
    expectedFormat: extractFormat(problem),
    context: categorizeRequest(problem)
  };

  const suggestedQueries = {};

  // Always suggest experience library query - now with focused generation
  if (availableTools.includes('memory-augmented-reasoning') || availableTools.length === 0) {
    suggestedQueries.learningLibrary = {
      query: generateFocusedQuery(problem),
      patterns: extractPatterns(problem),
      domain: categorizeDomain(problem),
      type: null, // Both effective and ineffective
      context: userIntent.context
    };
  }

  // Suggest local file searches
  suggestedQueries.localFiles = [
    'CLAUDE.md',
    '.cursor/rules/*.mdc',
    'README.md'
  ];

  // Suggest Context7 library documentation query
  if (availableTools.includes('context7')) {
    suggestedQueries.context7 = {
      libraryName: 'auto-detect',
      query: problem
    };
  }

  // Suggest Jira ticket search
  if (availableTools.includes('jira') || availableTools.includes('mcp-atlassian')) {
    suggestedQueries.jira = {
      jql: `text ~ "${problem.split(' ').slice(0, 3).join(' ')}" ORDER BY updated DESC`
    };
  }

  // Suggest Figma design search
  if (availableTools.includes('figma') || availableTools.includes('figma-desktop')) {
    suggestedQueries.figma = {
      nodeId: null, // Request current selection
      query: 'design specifications'
    };
  }

  // Suggest GitHub code search
  if (availableTools.includes('github')) {
    suggestedQueries.github = {
      query: problem.split(' ').slice(0, 5).join(' '),
      scope: 'code'
    };
  }

  // Suggest web search as fallback
  suggestedQueries.webSearch = {
    query: `${problem} best practices 2026`
  };

  return {
    phase: 'analyze',
    nextPhase: 'integrate',
    problem: problem,  // FIX #3: Store problem for later phases
    userIntent,  // NEW: User intent extraction
    suggestedQueries,
    keyFactors: identifyKeyFactors(problem),  // NEW: Search priorities
    estimatedComplexity: problem.length > 100 ? 'high' : problem.split(' ').length > 10 ? 'medium' : 'low'
  };
 }

 // Phase 2: INTEGRATE - Synthesize context from multiple sources
 function integratePhase(params, dbs, sessionData) {
  let { problem, gatheredContext = {} } = params;

  // FIX #1: Session-aware validation - Try to get problem from analyze phase if not provided
  if (!problem && sessionData?.phases?.analyze?.artifacts?.problem) {
    problem = sessionData.phases.analyze.artifacts.problem;
    console.error('[integrate] Using problem from analyze phase');
  }

  // Strict validation with minimal error message
  if (!problem || typeof problem !== 'string' || problem.trim().length === 0) {
    throw new ValidationError(
      'Invalid params: missing problem parameter',
      'Missing required parameter: problem (integrate phase)\n' +
      'Required: { phase: "integrate", session_id: "...", problem: "...", gatheredContext: {...} }'
    );
  }

  // Phase 7.5: Enforce that search_experiences was called before integrate
  if (sessionData?.phases?.analyze?.artifacts && !sessionData.phases.analyze.artifacts.searchCalled) {
    const suggestedQuery = sessionData.phases.analyze.artifacts.suggestedQueries?.learningLibrary?.query || problem;
    throw new ValidationError(
      'Invalid params: search_experiences not called before integrate',
      'Protocol violation: search_experiences must be called before integrate phase\n' +
      'Required sequence:\n' +
      '  1. informed_reasoning({ phase: "analyze", problem: "..." })\n' +
      '  2. search_experiences({ query: "..." })  ← YOU SKIPPED THIS\n' +
      '  3. informed_reasoning({ phase: "integrate", gatheredContext: { experiences: [...] } })\n' +
      '\n' +
      'Example:\n' +
      `  search_experiences({ query: "${suggestedQuery}" })\n` +
      '\n' +
      'Why: The system learns from past experiences. Skipping search means missing valuable patterns.'
    );
  }

  // Validate gatheredContext type
  if (gatheredContext && typeof gatheredContext !== 'object') {
    throw new ValidationError(
      'Invalid params: gatheredContext must be object',
      'Invalid parameter type: gatheredContext must be object (integrate phase)\n' +
      'Required: { phase: "integrate", session_id: "...", problem: "...", gatheredContext: {...} }'
    );
  }

  // FIX #4: Validate gatheredContext quality
  const experiences = gatheredContext.experiences || [];
  const localDocs = gatheredContext.localDocs || [];
  const mcpData = gatheredContext.mcpData || {};

  // Phase 7.5: Warn if no experiences found (they searched but found nothing)
  if (experiences.length === 0) {
    console.error('[memory-augmented-reasoning-mcp] WARNING: No experiences found in search. Consider recording this as a new pattern after task completion.');
  }

  const qualityMetrics = {
    experiencesCount: experiences.length,
    effectiveCount: experiences.filter(e => e.type === 'effective').length,
    ineffectiveCount: experiences.filter(e => e.type === 'ineffective').length,
    localDocsCount: localDocs.length,
    mcpDataKeys: Object.keys(mcpData).length,
    totalItems: experiences.length + localDocs.length + Object.keys(mcpData).length
  };

  // Log quality metrics to stderr for agent awareness
  console.error(`[integrate] Context quality: ${qualityMetrics.totalItems} items total ` +
    `(${qualityMetrics.experiencesCount} experiences, ${qualityMetrics.localDocsCount} docs, ` +
    `${qualityMetrics.mcpDataKeys} MCP sources)`);

  // Warn if context is empty or very minimal
  if (qualityMetrics.totalItems === 0) {
    console.error(
      '\n⚠️  WARNING: Empty gatheredContext provided\n' +
      '  IMPACT: synthesizedContext will be minimal (likely < 50 chars)\n' +
      '  ROOT CAUSE: You did not execute any queries from analyze phase\n\n' +
      '  RECOMMENDED ACTIONS:\n' +
      '    1. Call search_experiences(...) with queries from analyze phase\n' +
      '    2. Use Read tool to load relevant project files\n' +
      '    3. Query other MCP servers if applicable (jira, figma, context7)\n' +
      '    4. Pass gathered data in gatheredContext parameter:\n' +
      '       gatheredContext: {\n' +
      '         experiences: [...],  // from search_experiences results\n' +
      '         localDocs: [...],    // from Read tool results\n' +
      '         mcpData: {...}       // from other MCP servers\n' +
      '       }\n\n' +
      '  NOTE: Session validation requires synthesizedContext >= 50 chars.\n' +
      '        Empty context will cause validation failure.\n'
    );
  } else if (qualityMetrics.totalItems < 3) {
    console.error(
      `\n⚠️  WARNING: Minimal gatheredContext (only ${qualityMetrics.totalItems} item${qualityMetrics.totalItems === 1 ? '' : 's'})\n` +
      '  SUGGESTION: Execute more queries to improve context quality:\n' +
      '    - search_experiences(...) for relevant past experiences\n' +
      '    - Read tool for project documentation/code\n' +
      '    - MCP servers for external requirements\n'
    );
  } else if (qualityMetrics.experiencesCount === 0) {
    console.error(
      '\n💡 TIP: No experiences found in gatheredContext\n' +
      '  Consider calling search_experiences(...) to learn from past work\n'
    );
  }

  const synthesis = {
    summary: {},
    text: '',
    estimatedThoughts: 3,
    priority: []
  };

  let tokenCount = 0;
  const MAX_TOKENS = 20000;

  // TIER 1: MANDATORY - Project rules and protocols
  if (localDocs.length > 0) {
    synthesis.summary.projectRules = extractProtocolRules(localDocs);
    synthesis.priority.push('PROJECT_RULES');
    tokenCount += estimateTokens(synthesis.summary.projectRules);
  }

  // TIER 2: HIGH PRIORITY - Effective experiences
  const effective = experiences
    .filter(l => l.type === 'effective')
    .sort((a, b) => (b.confidence || 0) - (a.confidence || 0))
    .slice(0, 10);

  if (effective.length > 0 && tokenCount < MAX_TOKENS * 0.5) {
    synthesis.summary.effectiveExperiences = effective.map(l => ({
      id: l.id,
      approach: l.approach,
      outcome: l.outcome,
      confidence: l.confidence,
      context: l.context
    }));
    synthesis.priority.push('EFFECTIVE_LEARNINGS');
    tokenCount += estimateTokens(synthesis.summary.effectiveExperiences);
  }

  // TIER 2: Anti-patterns
  const ineffective = experiences.filter(l => l.type === 'ineffective');
  if (ineffective.length > 0 && tokenCount < MAX_TOKENS * 0.6) {
    synthesis.summary.antiPatterns = ineffective.map(l => ({
      id: l.id,
      avoidApproach: l.approach,
      useInstead: l.alternative,
      reasoning: l.reasoning
    }));
    synthesis.priority.push('ANTI_PATTERNS');
    tokenCount += estimateTokens(synthesis.summary.antiPatterns);
  }

  // TIER 3: External requirements (Jira, Figma, etc.)
  if (mcpData.jira && tokenCount < MAX_TOKENS * 0.75) {
    synthesis.summary.requirements = {
      summary: mcpData.jira.summary || mcpData.jira.fields?.summary,
      description: mcpData.jira.description || mcpData.jira.fields?.description
    };
    synthesis.priority.push('JIRA_REQUIREMENTS');
    tokenCount += estimateTokens(synthesis.summary.requirements);
  }

  if (mcpData.figma && tokenCount < MAX_TOKENS * 0.8) {
    synthesis.summary.designSpecs = mcpData.figma;
    synthesis.priority.push('FIGMA_DESIGNS');
    tokenCount += estimateTokens(synthesis.summary.designSpecs);
  }

  // TIER 4: Truncated summaries (library docs, code examples, web)
  if (mcpData.context7 && tokenCount < MAX_TOKENS * 0.9) {
    synthesis.summary.libraryDocs = {
      library: mcpData.context7.libraryName || 'auto-detected',
      summary: mcpData.context7.docs ? String(mcpData.context7.docs).slice(0, 500) : 'N/A'
    };
    tokenCount += estimateTokens(synthesis.summary.libraryDocs);
  }

  // Generate synthesized text
  let text = `# Context for: ${problem}\n\n`;

  if (synthesis.summary.projectRules && synthesis.summary.projectRules.length > 0) {
    text += `## Project Rules (MANDATORY)\n${synthesis.summary.projectRules.slice(0, 5).join('\n')}\n\n`;
  }

  if (synthesis.summary.effectiveExperiences && synthesis.summary.effectiveExperiences.length > 0) {
    text += `## Effective Patterns (from past work)\n`;
    for (const experience of synthesis.summary.effectiveExperiences.slice(0, 3)) {
      text += `- **Approach:** ${experience.approach}\n`;
      text += `  **Outcome:** ${experience.outcome} (confidence: ${experience.confidence || 'N/A'})\n`;
    }
    text += '\n';
  }

  if (synthesis.summary.antiPatterns && synthesis.summary.antiPatterns.length > 0) {
    text += `## Anti-Patterns (AVOID)\n`;
    for (const antiPattern of synthesis.summary.antiPatterns) {
      text += `- **Don't:** ${antiPattern.avoidApproach}\n`;
      text += `  **Instead:** ${antiPattern.useInstead}\n`;
    }
    text += '\n';
  }

  if (synthesis.summary.requirements) {
    text += `## Requirements\n${synthesis.summary.requirements.summary}\n\n`;
  }

  synthesis.text = text;

  // Estimate thoughts needed based on complexity
  const complexity =
    (synthesis.summary.projectRules?.length || 0) +
    (synthesis.summary.effectiveExperiences?.length || 0) +
    (synthesis.summary.antiPatterns?.length || 0);

  synthesis.estimatedThoughts = Math.max(3, Math.min(10, Math.ceil(complexity / 3)));

  return {
    phase: 'integrate',
    nextPhase: 'reason',
    contextSummary: synthesis.summary,
    synthesizedContext: synthesis.text,
    guidance: `⚠️ USER REQUIREMENT: informed_reasoning(phase='reason') MUST be called next.\nThe system needs all 4 phases to learn from this task properly.\nOther tools blocked until protocol complete.`,
    estimatedThoughts: synthesis.estimatedThoughts,
    tokenBudget: {
      used: tokenCount,
      remaining: MAX_TOKENS - tokenCount,
      warning: tokenCount > MAX_TOKENS * 0.9 ? 'Approaching token limit' : null
    }
  };
 }

 // Phase 3: REASON - Evaluate thought against context
 function reasonPhase(params, dbs) {
  const {
    problem,
    thought,
    thoughtNumber,
    totalThoughts,
    nextThoughtNeeded,
    isRevision = false,
    revisesThought = null,
    branchFromThought = null,
    branchId = null,
    needsMoreThoughts = false
  } = params;

  // Validate required parameters
  if (!thought || typeof thought !== 'string') {
    throw new ValidationError(
      'Invalid params: missing thought parameter',
      'Missing required parameter: thought (reason phase)\n' +
      'Required: { phase: "reason", session_id: "...", problem: "...", thought: "...", thoughtNumber: 1, totalThoughts: 3, nextThoughtNeeded: true }'
    );
  }

  if (typeof thoughtNumber !== 'number' || thoughtNumber < 1) {
    throw new ValidationError(
      'Invalid params: thoughtNumber must be >= 1',
      'Invalid parameter: thoughtNumber must be number >= 1 (reason phase)\n' +
      'Required: { phase: "reason", ..., thoughtNumber: 1, totalThoughts: 3, nextThoughtNeeded: true }'
    );
  }

  if (typeof totalThoughts !== 'number' || totalThoughts < 1) {
    throw new ValidationError(
      'Invalid params: totalThoughts must be >= 1',
      'Invalid parameter: totalThoughts must be number >= 1 (reason phase)\n' +
      'Required: { phase: "reason", ..., thoughtNumber: 1, totalThoughts: 3, nextThoughtNeeded: true }'
    );
  }

  if (thoughtNumber > totalThoughts) {
    throw new ValidationError(
      'Invalid params: thoughtNumber exceeds totalThoughts',
      'Invalid parameter: thoughtNumber cannot exceed totalThoughts (reason phase)\n' +
      'Required: thoughtNumber <= totalThoughts'
    );
  }

  if (typeof nextThoughtNeeded !== 'boolean') {
    throw new ValidationError(
      'Invalid params: nextThoughtNeeded must be boolean',
      'Invalid parameter: nextThoughtNeeded must be boolean (reason phase)\n' +
      'Required: { phase: "reason", ..., nextThoughtNeeded: true }'
    );
  }

  // Evaluate thought against available context
  const evaluation = {
    alignment: 'good',
    protocolCompliant: true,
    patternMatch: true,
    issues: []
  };

  // Check if thought mentions implementing without reading
  if (thought.toLowerCase().includes('implement') &&
      !thought.toLowerCase().includes('read') &&
      !thought.toLowerCase().includes('check') &&
      !thought.toLowerCase().includes('verify')) {
    evaluation.issues.push('Implementing without reading existing code first');
    evaluation.alignment = 'poor';
  }

  // Check if thought suggests adding features not requested
  if (thought.toLowerCase().match(/also|additionally|while we're at it/)) {
    evaluation.issues.push('Potential scope creep detected');
  }

  // Provide guidance
  let guidance = '';

  if (nextThoughtNeeded === false) {
    if (evaluation.issues.length === 0) {
      guidance = '⚠️ USER REQUIREMENT: record_experience MUST be called after Write/Edit operations.\nThe system learns from outcomes - recording is mandatory for institutional memory.\nFile operations now allowed, but must record results.';
    } else {
      guidance = `⚠️ USER REQUIREMENT: Issues detected: ${evaluation.issues.join(', ')}. Consider revising before proceeding.\nThe system learns from outcomes - recording is mandatory for institutional memory.\nFile operations now allowed, but must record results.`;
    }
  } else {
    guidance = '⚠️ USER REQUIREMENT: Continue reasoning until complete.\nThe system needs all 4 phases to learn from this task properly.';
  }

  // Suggest revision if major issues
  const revisionSuggestion = evaluation.issues.length > 0 && !isRevision ? {
    shouldRevise: true,
    thought: thoughtNumber,
    reason: evaluation.issues[0]
  } : undefined;

  // Suggest branching for exploration
  const branchSuggestion =
    thoughtNumber > 2 &&
    thought.toLowerCase().match(/could|might|alternative|or/) &&
    !branchId ? {
      shouldBranch: true,
      reason: 'Multiple approaches detected',
      branchOptions: ['option-a', 'option-b']
    } : undefined;

  return {
    phase: 'reason',
    thoughtNumber,
    totalThoughts: needsMoreThoughts ? totalThoughts + 1 : totalThoughts,
    nextPhase: nextThoughtNeeded ? 'reason' : 'record',
    guidance,
    suggestedActions: evaluation.issues.length > 0 ? ['Review effective experiences', 'Check protocol rules'] : [],
    nextThoughtNeeded,
    branches: branchId ? [branchId] : [],
    thoughtHistoryLength: thoughtNumber,
    evaluation,
    branchSuggestion,
    revisionSuggestion
  };
 }

 // Phase 4: RECORD - Capture experience
 function recordPhase(params, dbs) {
  const { problem, finalConclusion, relatedExperiences = [] } = params;

  // Validate required parameters
  if (!problem || typeof problem !== 'string' || problem.trim().length === 0) {
    const briefMsg = !problem
      ? 'Invalid params: missing problem parameter'
      : 'Invalid params: problem must be non-empty string';
    const details = !problem
      ? 'Missing required parameter: problem\nThe problem parameter must be a non-empty string.\nExample: { phase: "record", problem: "...", finalConclusion: "..." }'
      : 'Invalid parameter: problem must be a non-empty string\nExample: { phase: "record", problem: "...", finalConclusion: "..." }';
    throw new ValidationError(briefMsg, details);
  }

  if (!finalConclusion || typeof finalConclusion !== 'string' || finalConclusion.trim().length === 0) {
    const briefMsg = !finalConclusion
      ? 'Invalid params: missing finalConclusion parameter'
      : 'Invalid params: finalConclusion must be non-empty string';
    const details = !finalConclusion
      ? 'Missing required parameter: finalConclusion\nThe finalConclusion parameter must be a non-empty string summarizing the result.\nExample: { phase: "record", problem: "...", finalConclusion: "..." }'
      : 'Invalid parameter: finalConclusion must be a non-empty string\nExample: { phase: "record", problem: "...", finalConclusion: "..." }';
    throw new ValidationError(briefMsg, details);
  }

  // Auto-capture experience from reasoning session
  const experience = {
    type: 'effective',
    domain: 'Process',
    situation: problem,
    approach: finalConclusion,
    outcome: 'Reasoning completed with context',
    reasoning: 'Applied informed reasoning with multi-source context',
    confidence: 0.7,
    supports: relatedExperiences.length > 0 ? relatedExperiences.join(',') : null,
    scope: 'user'
  };

  try {
    const result = recordExperience(dbs, experience);

    return {
      phase: 'record',
      recorded: true,
      learningId: result.id,
      experience,
      guidance: `Saved ${experience.type} pattern to the experience library (ID: ${result.id}). Available for future reasoning sessions.`,
      relatedExperiences
    };
  } catch (error) {
    return {
      phase: 'record',
      recorded: false,
      experience,
      guidance: `Failed to record experience: ${error.message}`,
      relatedExperiences
    };
  }
 }

 // Check protocol compliance for current session
 function checkProtocolCompliance(dbs, params) {
  const { session_id, hook, tool_name } = params;
  const sessionId = session_id || getSessionId();

  if (!dbs.user) {
    return {
      compliant: false,
      reason: 'No user database available',
      violations: ['User database not loaded']
    };
  }

  const session = dbs.user.prepare('SELECT * FROM protocol_sessions WHERE session_id = ?').get(sessionId);

  if (!session) {
    return {
      compliant: false,
      reason: 'No protocol session found',
      violations: ['Session not initialized - call informed_reasoning first']
    };
  }

  // Check requirements based on hook
  const violations = [];
  const phases = session.informed_reasoning_phases ? JSON.parse(session.informed_reasoning_phases) : [];

  if (!phases.includes('analyze')) {
    violations.push('Must call informed_reasoning (analyze phase) first');
  }

  // Check for stale session (> 5 minutes since last activity)
  const lastActivity = new Date(session.last_activity);
  const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);
  if (lastActivity < fiveMinutesAgo) {
    violations.push('Session stale - must call informed_reasoning again');
  }

  return {
    compliant: violations.length === 0,
    reason: violations.length === 0 ? 'All requirements met' : 'Protocol violations detected',
    violations,
    session: {
      id: sessionId,
      phases_completed: phases,
      last_activity: session.last_activity
    }
  };
 }

 // Verify all artifacts meet quality standards (Phase 2)
 function verifyAllArtifacts(sessionData) {
  const { phases } = sessionData;
  const issues = [];

  // Check analyze phase artifacts
  if (phases.analyze && phases.analyze.completed) {
    const artifacts = phases.analyze.artifacts || {};
    const suggestedQueries = artifacts.suggestedQueries || {};

    // Validate suggested queries have non-empty strings
    const queryValues = Object.values(suggestedQueries);
    if (queryValues.length === 0) {
      issues.push('analyze: suggestedQueries is empty');
    } else {
      for (const [key, value] of Object.entries(suggestedQueries)) {
        if (typeof value === 'string') {
          if (value.length < 3) {
            issues.push(`analyze: suggestedQueries.${key} too short (${value.length} chars, min 3)`);
          }
        } else if (typeof value === 'object' && value !== null) {
          if (value.query && value.query.length < 3) {
            issues.push(`analyze: suggestedQueries.${key}.query too short`);
          }
        }
      }
    }
  }

  // Check integrate phase artifacts
  if (phases.integrate && phases.integrate.completed) {
    const artifacts = phases.integrate.artifacts || {};
    const synthesizedContext = artifacts.synthesizedContext;

    if (!synthesizedContext || typeof synthesizedContext !== 'string') {
      issues.push('integrate: synthesizedContext missing or not a string');
    } else if (synthesizedContext.length < 50) {
      // FIX #2: Enhanced validation messages - Detect common failure patterns
      const isStubOnly = synthesizedContext.includes('undefined') ||
                         /^#\s*Context\s+for:\s*\w*\s*\n\n$/.test(synthesizedContext);

      if (isStubOnly) {
        // Stub-only context indicates missing problem parameter
        issues.push(
          `integrate: synthesizedContext is stub only (${synthesizedContext.length} chars).\n` +
          '  ROOT CAUSE: Missing or undefined "problem" parameter in integrate phase.\n' +
          '  FIX: Pass problem parameter: informed_reasoning({ phase: "integrate", problem: "...", ... })\n' +
          '  NOTE: Problem should match what you provided in analyze phase.'
        );
      } else {
        // Short but not stub - likely empty gatheredContext
        issues.push(
          `integrate: synthesizedContext too short (${synthesizedContext.length} chars, min 50).\n` +
          '  ROOT CAUSE: Empty or minimal gatheredContext provided.\n' +
          '  FIX: Execute suggested queries from analyze phase:\n' +
          '    - search_experiences(...)\n' +
          '    - Read relevant files\n' +
          '    - Query other MCP servers\n' +
          '  Then pass results in gatheredContext parameter.'
        );
      }
    }
  }

  // Check reason phase artifacts
  if (phases.reason && phases.reason.completed) {
    const artifacts = phases.reason.artifacts || {};
    const thoughts = artifacts.thoughts;

    if (!Array.isArray(thoughts) || thoughts.length === 0) {
      issues.push(
        'reason: thoughts array is empty or missing.\n' +
        '  ROOT CAUSE: Called reason phase but no thoughts were recorded.\n' +
        '  FIX: Provide thought parameter: informed_reasoning({ phase: "reason", thought: "...", ... })'
      );
    } else {
      for (let i = 0; i < thoughts.length; i++) {
        const thought = thoughts[i];
        if (!thought.content || thought.content.length < 10) {
          issues.push(
            `reason: thought[${i}].content too short or missing (${thought.content?.length || 0} chars, min 10).\n` +
            '  FIX: Provide substantive reasoning in thought parameter.'
          );
        }
        if (!thought.evaluation) {
          issues.push(`reason: thought[${i}].evaluation missing (internal error)`);
        }
      }
    }
  }

  // Check record phase artifacts
  if (phases.record && phases.record.completed) {
    const artifacts = phases.record.artifacts || {};
    const finalConclusion = artifacts.finalConclusion;

    if (!finalConclusion || typeof finalConclusion !== 'string') {
      issues.push(
        'record: finalConclusion missing or not a string.\n' +
        '  ROOT CAUSE: Called record phase without finalConclusion parameter.\n' +
        '  FIX: Provide finalConclusion: informed_reasoning({ phase: "record", finalConclusion: "...", ... })'
      );
    } else if (finalConclusion.length < 20) {
      issues.push(
        `record: finalConclusion too short (${finalConclusion.length} chars, min 20).\n` +
        '  ROOT CAUSE: Conclusion not comprehensive enough.\n' +
        '  FIX: Provide detailed summary of reasoning and outcomes.'
      );
    }
  }

  return {
    valid: issues.length === 0,
    issues: issues
  };
 }

 // Main handler for informed_reasoning tool
 function informedReasoning(dbs, params) {
  const { phase } = params;

  // Clean up stale search tokens (analyze phase only)
  if (phase === 'analyze') {
    const searchTokenPath = path.join(os.homedir(), '.protocol-search-required-token');
    if (fs.existsSync(searchTokenPath)) {
      try {
        const token = JSON.parse(fs.readFileSync(searchTokenPath, 'utf8'));
        const age = Date.now() - token.timestamp;

        // Remove tokens older than 5 minutes
        if (age > 300000) {
          fs.unlinkSync(searchTokenPath);
        }
      } catch (e) {
        // Invalid token - remove it
        try {
          fs.unlinkSync(searchTokenPath);
        } catch (e2) {
          // Silent fail
        }
      }
    }

    // PHASE 2: Clean up expired session files (analyze phase only)
    const homeDir = os.homedir();
    try {
      const files = fs.readdirSync(homeDir);
      const now = Date.now();

      for (const file of files) {
        if (file.startsWith('.protocol-session-') && file.endsWith('.json')) {
          const sessionPath = path.join(homeDir, file);
          try {
            const sessionData = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));

            // Remove if expired
            if (sessionData.expires_at && sessionData.expires_at < now) {
              fs.unlinkSync(sessionPath);

              // Also clean up from memory
              if (sessionData.session_id) {
                state.sessionTokens.delete(sessionData.session_id);
                state.sessions.delete(sessionData.session_id);
              }
            }
          } catch (e) {
            // Invalid or corrupt session file - remove it
            try {
              fs.unlinkSync(sessionPath);
            } catch (e2) {
              // Silent fail
            }
          }
        }
      }
    } catch (e) {
      // Silent fail if we can't read home directory
    }
  }

  // ============================================================================
  // ENHANCED: Phase Order Enforcement (Path B Implementation)
  // ============================================================================

  const sessionId = params.session_id || getSessionId();

  // Load existing session from file if it exists (persistence across restarts)
  const sessionFile = path.join(os.homedir(), `.protocol-session-${sessionId}.json`);
  let sessionData = state.sessions.get(sessionId);

  if (!sessionData && fs.existsSync(sessionFile)) {
    try {
      sessionData = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
      // Restore to memory
      state.sessions.set(sessionId, sessionData);
    } catch (e) {
      // Invalid session file - will create new session below
      sessionData = null;
    }
  }

  // Get or create session data
  if (!sessionData) {
    const now = Date.now();
    sessionData = {
      session_id: sessionId,
      created_at: now,
      expires_at: now + state.sessionTokenTimeout,
      version: '2.1',
      phases: {
        analyze: { completed: false },
        integrate: { completed: false },
        reason: { completed: false },
        record: { completed: false }
      },
      allPhasesComplete: false,
      artifactsVerified: false
    };
    state.sessions.set(sessionId, sessionData);
  }

  // ENFORCE PHASE ORDER: Check prerequisites before executing phase
  if (phase === 'integrate' && !sessionData.phases.analyze.completed) {
    throw new ValidationError(
      'Phase order violation: Must complete analyze before integrate\n' +
      'Required sequence: analyze → integrate → reason → record'
    );
  }

  if (phase === 'reason' && !sessionData.phases.integrate.completed) {
    const missing = [];
    if (!sessionData.phases.analyze.completed) missing.push('analyze');
    missing.push('integrate');
    throw new ValidationError(
      `Phase order violation: Must complete ${missing.join(', ')} before reason\n` +
      'Required sequence: analyze → integrate → reason → record'
    );
  }

  if (phase === 'record' && !sessionData.phases.reason.completed) {
    const missing = [];
    if (!sessionData.phases.analyze.completed) missing.push('analyze');
    if (!sessionData.phases.integrate.completed) missing.push('integrate');
    missing.push('reason');
    throw new ValidationError(
      `Phase order violation: Must complete ${missing.join(', ')} before record\n` +
      'Required sequence: analyze → integrate → reason → record'
    );
  }

  // Execute the phase logic
  let result;
  switch (phase) {
    case 'analyze':
      result = analyzePhase(params);
      break;

    case 'integrate':
      result = integratePhase(params, dbs, sessionData);  // FIX #1: Pass sessionData
      break;

    case 'reason':
      result = reasonPhase(params, dbs);
      break;

    case 'record':
      result = recordPhase(params, dbs);
      break;

    default:
      throw new ValidationError(`Invalid phase: ${phase}\nRequired: phase must be "analyze", "integrate", "reason", or "record"`);
  }

  // ============================================================================
  // PHASE 2: Enhanced Session Tracking with Phases Object
  // ============================================================================

  // Update phase completion and artifacts
  const now = Date.now();
  sessionData.phases[phase].completed = true;
  sessionData.phases[phase].timestamp = now;

  // Capture phase-specific artifacts
  if (phase === 'analyze' && result.suggestedQueries) {
    sessionData.phases.analyze.artifacts = {
      problem: result.problem,  // FIX #3: Store problem for use in later phases
      suggestedQueries: result.suggestedQueries,
      timestamp: now,
      searchCalled: false  // Phase 7.5: Track if search_experiences was called
    };
  } else if (phase === 'integrate' && result.synthesizedContext) {
    sessionData.phases.integrate.artifacts = {
      synthesizedContext: result.synthesizedContext,
      contextSummary: result.contextSummary
    };
  } else if (phase === 'reason') {
    // Accumulate thoughts across multiple reason calls
    if (!sessionData.phases.reason.artifacts) {
      sessionData.phases.reason.artifacts = { thoughts: [] };
    }
    if (params.thought) {
      sessionData.phases.reason.artifacts.thoughts.push({
        thoughtNumber: params.thoughtNumber,
        content: params.thought,
        evaluation: result.evaluation,
        timestamp: now
      });
    }
  } else if (phase === 'record' && params.finalConclusion) {
    sessionData.phases.record.artifacts = {
      finalConclusion: params.finalConclusion,
      learningId: result.learningId
    };
  }

  // Check if all phases are complete
  const allComplete =
    sessionData.phases.analyze.completed &&
    sessionData.phases.integrate.completed &&
    sessionData.phases.reason.completed &&
    sessionData.phases.record.completed;

  sessionData.allPhasesComplete = allComplete;

  // Phase 7.10: Generate new session ID when session completes
  // Completed sessions become immutable historical records, not active sessions
  if (allComplete) {
    const newSessionId = `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
    const sessionFilePath = path.join(os.homedir(), '.protocol-current-session-id');

    try {
      fs.writeFileSync(sessionFilePath, JSON.stringify({
        session_id: newSessionId,
        created: Date.now(),
        created_iso: new Date().toISOString(),
        reason: 'previous_session_completed',
        previous_session_id: sessionId
      }));
      console.error(`[memory-augmented-reasoning-mcp] Session completed, generated new session ID: ${newSessionId}`);
      console.error(`[memory-augmented-reasoning-mcp] Previous session archived: ${sessionId}`);
    } catch (err) {
      console.error(`[memory-augmented-reasoning-mcp] Warning: Failed to generate new session ID: ${err.message}`);
    }
  }

  // Verify artifacts if all phases complete
  if (allComplete) {
    const verification = verifyAllArtifacts(sessionData);
    sessionData.artifactsVerified = verification.valid;
    if (!verification.valid) {
      sessionData.artifactIssues = verification.issues;
    }
  }

  // ENHANCED: Write session JSON after EVERY phase (for persistence)
  try {
    const tempFile = `${sessionFile}.tmp`;
    fs.writeFileSync(tempFile, JSON.stringify(sessionData, null, 2), 'utf8');
    fs.renameSync(tempFile, sessionFile);
    console.error(`[memory-augmented-reasoning-mcp] ✓ Session updated: phase ${phase} complete`);
  } catch (err) {
    console.error('[memory-augmented-reasoning-mcp] Failed to write session JSON:', err.message);
  }

  // ============================================================================
  // CRITICAL: Token creation MUST happen regardless of database availability
  // Issue: Token creation was inside if(dbs.user) block, causing tokens to not
  // be created when user database doesn't exist, blocking all file operations
  // Fix: Move token creation OUTSIDE database conditional block
  // ============================================================================

  // Write token file for hook verification (analyze phase only)
  // Token expires after 60 seconds to support parallel tool execution (Issue #3 fix)
  if (phase === 'analyze') {
    // STEP 1: Clear requirement token (satisfies user_prompt_submit requirement)
    const requirementFile = path.join(os.homedir(), '.protocol-informed-reasoning-required');
    try {
      if (fs.existsSync(requirementFile)) {
        fs.unlinkSync(requirementFile);
        console.error('[memory-augmented-reasoning-mcp] ✓ Requirement token cleared');
      }
    } catch (err) {
      console.error('[memory-augmented-reasoning-mcp] ✗ Failed to clear requirement token:', err.message);
    }

    // STEP 2: Create informed reasoning token (60s TTL for tool verification)
    const tokenFile = path.join(os.homedir(), '.protocol-informed-reasoning-token');
    try {
      const now = new Date();
      const expires = new Date(now.getTime() + 60000); // 60 seconds
      const tokenData = {
        sessionId,
        phase,
        timestamp: now.toISOString(),
        expires: expires.toISOString()
      };
      fs.writeFileSync(tokenFile, JSON.stringify(tokenData), 'utf8');
      console.error(`[memory-augmented-reasoning-mcp] ✓ Token created: ${tokenFile}`);
      console.error(`[memory-augmented-reasoning-mcp] Token data: ${JSON.stringify(tokenData)}`);
    } catch (err) {
      console.error('[memory-augmented-reasoning-mcp] ✗ FAILED to write token file:', err.message);
      console.error('[memory-augmented-reasoning-mcp] Stack:', err.stack);
    }

    // Create search-required token if learning library search was suggested
    if (result && result.suggestedQueries && result.suggestedQueries.learningLibrary) {
      const searchTokenPath = path.join(os.homedir(), '.protocol-search-required-token');
      try {
        const searchToken = {
          timestamp: Date.now(),
          sessionId,
          suggestedQuery: result.suggestedQueries.learningLibrary.query,
          domain: result.suggestedQueries.learningLibrary.domain,
          phase: 'analyze'
        };
        fs.writeFileSync(searchTokenPath, JSON.stringify(searchToken), 'utf8');
        console.error('[memory-augmented-reasoning-mcp] ✓ Search token created');
      } catch (err) {
        console.error('[memory-augmented-reasoning-mcp] ✗ Failed to write search token:', err.message);
      }
    }

    // STEP 3: Create session token (10min TTL for conversation optimization)
    const sessionTokenFile = path.join(os.homedir(), '.protocol-session-token');
    try {
      const now = Date.now();
      const expires = now + 600000; // 10 minutes
      const sessionTokenData = {
        sessionId,
        timestamp: now,
        expires: expires,
        created: new Date().toISOString()
      };
      fs.writeFileSync(sessionTokenFile, JSON.stringify(sessionTokenData), 'utf8');
      console.error('[memory-augmented-reasoning-mcp] ✓ Session token created (10min TTL)');
    } catch (err) {
      console.error('[memory-augmented-reasoning-mcp] ✗ Failed to create session token:', err.message);
    }
  }

  // Track session activity (only if we have a user database)
  if (dbs.user) {
    try {
      // Ensure session exists before recording activity
      getOrCreateSession(dbs.user, sessionId);
      updateSessionActivity(dbs.user, sessionId);
      recordProtocolEvent(dbs.user, sessionId, 'phase_completed', {
        phase,
        timestamp: new Date().toISOString()
      });
      updateSessionPhases(dbs.user, sessionId, phase);
    } catch (sessionError) {
      // Don't fail the request if session tracking fails
      console.error('[memory-augmented-reasoning-mcp] Session tracking error:', sessionError.message);
    }
  }

  // ============================================================================
  // BUG FIX: Session token file write removed - redundant and harmful
  //
  // ISSUE: Lines 1481-1548 (old code) were overwriting the enhanced session
  // file with a simple 3-field structure after lines 1383-1391 correctly wrote
  // the full enhanced structure.
  //
  // SOLUTION: Removed redundant session token creation code. The enhanced
  // session is already written correctly at lines 1383-1391 with full phase
  // tracking, artifacts, allPhasesComplete, and artifactsVerified fields.
  //
  // The old code created a simple tokenData with only:
  //   { session_id, created_at, expires_at }
  //
  // This was overwriting the enhanced structure from lines 1383-1391 that has:
  //   { session_id, created_at, expires_at, phases, allPhasesComplete,
  //     artifactsVerified, version, artifactIssues }
  // ============================================================================

  // ENHANCED: Include session tracking and next phase guidance in response
  const nextPhase = sessionData.allPhasesComplete ? null :
    !sessionData.phases.analyze.completed ? 'analyze' :
    !sessionData.phases.integrate.completed ? 'integrate' :
    !sessionData.phases.reason.completed ? 'reason' :
    !sessionData.phases.record.completed ? 'record' : null;

  // BUG FIX v2.1.3: Provide complete parameter guidance for each phase
  let phaseGuidance = '';
  if (sessionData.allPhasesComplete) {
    phaseGuidance = "✅ All phases complete - session token valid for THIS REQUEST - you may now use Write/Edit/NotebookEdit for THIS TASK. NEW user requests require running protocol again.";
  } else if (nextPhase === 'analyze') {
    phaseGuidance = `Next: call informed_reasoning({ phase: "analyze", session_id: "${sessionId}", problem: "your problem", availableTools: ["Read", "Grep", ...] })`;
  } else if (nextPhase === 'integrate') {
    // Phase 7.5: After analyze completes, require search before integrate
    const problem = sessionData.phases.analyze.artifacts?.problem || "your problem";
    const searchQuery = sessionData.phases.analyze.artifacts?.suggestedQueries?.learningLibrary?.query || problem;
    phaseGuidance = `⚠️ USER REQUIREMENT: BEFORE calling integrate, you MUST call search_experiences.\n\n` +
      `REQUIRED STEPS:\n` +
      `  STEP 1: search_experiences({ query: "${searchQuery}" })\n` +
      `  STEP 2: informed_reasoning({ phase: "integrate", session_id: "${sessionId}", problem: "${problem}", gatheredContext: { experiences: [results] } })\n\n` +
      `The system learns from past experiences - searching is MANDATORY, not optional.\n` +
      `Skipping search will cause an error at integrate phase.`;
  } else if (nextPhase === 'reason') {
    const problem = sessionData.phases.analyze.artifacts?.problem || "your problem";
    const estimatedThoughts = result.estimatedThoughts || 3;
    phaseGuidance = `Next: call informed_reasoning({ phase: "reason", session_id: "${sessionId}", problem: "${problem}", thought: "your reasoning step", thoughtNumber: 1, totalThoughts: ${estimatedThoughts}, nextThoughtNeeded: true })`;
  } else if (nextPhase === 'record') {
    const problem = sessionData.phases.analyze.artifacts?.problem || "your problem";
    phaseGuidance = `Next: call informed_reasoning({ phase: "record", session_id: "${sessionId}", problem: "${problem}", finalConclusion: "your conclusion" })`;
  }

  return {
    ...result,
    session_id: sessionId,
    phase_completed: phase,
    all_phases_complete: sessionData.allPhasesComplete,
    artifacts_verified: sessionData.artifactsVerified,
    next_phase: nextPhase,
    guidance: phaseGuidance
  };
 }

 // ============================================================================
 // END PHASE 2 IMPLEMENTATION
 // ============================================================================

 // MCP Protocol implementation
 async function main() {
  // Handle --version flag
  if (process.argv.includes('--version')) {
    console.log(`memory-augmented-reasoning-mcp v${VERSION}`);
    process.exit(0);
  }

  // Handle --check-compliance flag (CLI mode for hooks)
  if (process.argv.includes('--check-compliance')) {
    try {
      // Read hook input from stdin
      const stdin = fs.readFileSync(0, 'utf-8');
      const hookInput = JSON.parse(stdin);

      const sessionId = process.env.CLAUDE_SESSION_ID || hookInput.sessionId;
      const userDbPath = expandPath(
        process.env.MEMORY_AUGMENTED_REASONING_USER_DB ||
        path.join(os.homedir(), '.cursor', 'memory-augmented-reasoning.db')
      );
      const db = initDatabase(userDbPath);

      const session = db.prepare('SELECT * FROM protocol_sessions WHERE session_id = ?').get(sessionId);

      if (!session) {
        console.log(JSON.stringify({
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "deny",
            permissionDecisionReason: "⛔ No protocol session - call informed_reasoning first"
          }
        }));
        db.close();
        process.exit(0);
      }

      const phases = session.informed_reasoning_phases ? JSON.parse(session.informed_reasoning_phases) : [];
      const lastActivity = new Date(session.last_activity);
      const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);

      if (!phases.includes('analyze') || lastActivity < fiveMinutesAgo) {
        console.log(JSON.stringify({
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "deny",
            permissionDecisionReason: "⛔ Must call informed_reasoning (analyze phase) first"
          }
        }));
      } else {
        console.log(JSON.stringify({
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "allow",
            permissionDecisionReason: "✅ Protocol requirements met"
          }
        }));
      }

      db.close();
      process.exit(0);
    } catch (error) {
      console.error('[memory-augmented-reasoning-mcp] CLI mode error:', error.message);
      console.log(JSON.stringify({
        hookSpecificOutput: {
          hookEventName: "PreToolUse",
          permissionDecision: "deny",
          permissionDecisionReason: `⛔ Error checking compliance: ${error.message}`
        }
      }));
      process.exit(1);
    }
  }

  // Handle --record-last-session flag (CLI mode for automatic experience recording)
  if (process.argv.includes('--record-last-session')) {
    try {
      // Read recording token created by PostToolUse hook
      // NOTE: This is DIFFERENT from the protocol token consumed by PreToolUse
      const recordingTokenFile = path.join(os.homedir(), '.protocol-session-recording-token');

      // Extract context from token
      let sessionId = process.env.CLAUDE_SESSION_ID;
      let toolName = 'tool';
      let filePath = 'unknown';
      let timestamp = new Date().toISOString();
      let cwd = process.cwd();

      if (fs.existsSync(recordingTokenFile)) {
        try {
          const tokenData = JSON.parse(fs.readFileSync(recordingTokenFile, 'utf8'));
          sessionId = tokenData.sessionId || sessionId;
          toolName = tokenData.toolName || toolName;
          timestamp = tokenData.timestamp || timestamp;
          filePath = tokenData.context?.filePath || filePath;
          cwd = tokenData.context?.cwd || cwd;

          // Clean up the recording token after reading
          fs.unlinkSync(recordingTokenFile);
        } catch (e) {
          console.error('[memory-augmented-reasoning-mcp] Failed to read recording token:', e.message);
        }
      }

      if (!sessionId) {
        console.error('[memory-augmented-reasoning-mcp] No session ID found (checked recording token and CLAUDE_SESSION_ID env var)');
        process.exit(1);
      }

      // Load databases
      const dbs = loadDatabases();

      // Determine scope from config or use default
      let scope = 'project';
      const configPath = path.join(process.cwd(), '.protocol-enforcer.json');
      if (fs.existsSync(configPath)) {
        try {
          const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
          scope = config.automatic_experience_recording?.scope || 'project';
        } catch (e) {
          // Use default scope
        }
      }

      // Generate context-rich experience with unique situation string
      const fileDisplayName = filePath !== 'unknown' ? path.basename(filePath) : 'unknown file';
      const experience = {
        type: 'effective',
        domain: 'Tools',
        situation: `${toolName} operation on ${fileDisplayName} at ${timestamp}`,
        approach: `Protocol flow: informed_reasoning → verify_protocol_compliance → authorize_file_operation → ${toolName}`,
        outcome: `Successfully completed ${toolName} operation following protocol requirements`,
        reasoning: 'Following protocol workflow with automatic experience recording after successful tool execution',
        context: `session: ${sessionId}, file: ${filePath}, cwd: ${cwd}`,
        confidence: 0.8,
        scope: scope
      };

      // Record the experience
      const result = recordExperience(dbs, experience);

      console.log(`[memory-augmented-reasoning-mcp] Experience recorded automatically: ${result.id} (${result.action})`);

      // Close databases
      if (dbs.user) dbs.user.close();
      if (dbs.project) dbs.project.close();

      process.exit(0);
    } catch (error) {
      console.error('[memory-augmented-reasoning-mcp] Failed to record experience:', error.message);
      process.exit(1);
    }
  }

  // Load databases
  let dbs;
  try {
    dbs = loadDatabases();
    console.error('[memory-augmented-reasoning-mcp] Databases loaded successfully');
  } catch (error) {
    console.error('[memory-augmented-reasoning-mcp] FATAL: Failed to load databases:', error.message);
    console.error('[memory-augmented-reasoning-mcp] Stack:', error.stack);
    process.exit(1);
  }

  // Use readline for proper line-by-line stdin reading
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    terminal: false
  });

  rl.on('line', async (line) => {
    try {
      if (!line.trim()) return;

      const request = JSON.parse(line);
      await handleRequest(dbs, request);
    } catch (error) {
      // For parse errors, try to extract ID from malformed JSON, otherwise use -1
      let requestId = -1;
      try {
        const partialParse = JSON.parse(line);
        if (partialParse && partialParse.id !== undefined) {
          requestId = partialParse.id;
        }
      } catch (e) {
        // If we can't even partially parse, use -1
      }
      console.error('[memory-augmented-reasoning-mcp] Parse error:', error.message);
      sendError(requestId, -32700, 'Parse error', error.message);
    }
  });

  // Graceful shutdown when STDIN closes (client disconnects)
  rl.on('close', () => {
    console.error('[memory-augmented-reasoning-mcp] STDIN closed, shutting down gracefully');
    // Wait for stdout to flush before exiting to prevent truncating large responses
    setImmediate(() => {
      process.stdout.write('', () => {
        process.exit(0);
      });
    });
  });

  // Handle termination signals
  process.on('SIGTERM', () => {
    console.error('[memory-augmented-reasoning-mcp] Received SIGTERM, shutting down');
    process.exit(0);
  });

  process.on('SIGINT', () => {
    console.error('[memory-augmented-reasoning-mcp] Received SIGINT, shutting down');
    process.exit(0);
  });
 }

 // Handle MCP requests
 async function handleRequest(dbs, request) {
  try {
    const { id, method, params } = request;

    // BUG FIX v2.1.4: Handle notifications (no id field) separately from requests
    // Notifications should NEVER receive a response (neither success nor error)
    // This fixes the "Received a response for an unknown message ID" error
    const isNotification = (id === undefined || id === null);

    // Handle notifications silently without sending any response
    if (isNotification) {
      if (method === 'notifications/initialized') {
        // Client has finished initializing - handle silently
        console.error('[memory-augmented-reasoning-mcp] Client initialized');
        return; // No response for notifications
      }
      // For other unknown notifications, log but don't respond
      console.error(`[memory-augmented-reasoning-mcp] Received notification: ${method}`);
      return; // No response for notifications
    }

    // For requests (messages with an id), ensure we have a valid ID
    const requestId = id;

    switch (method) {
      case 'initialize':
        sendResponse(requestId, {
          protocolVersion: '2024-11-05',
          capabilities: {
            tools: {}
          },
          serverInfo: {
            name: 'memory-augmented-reasoning',
            version: VERSION
          }
        });
        break;

      case 'tools/list':
        sendResponse(requestId, {
          tools: [
            {
              name: 'record_experience',
              description: '📝 STEP 4 - TEACH: Record outcome for future sessions. USER REQUIREMENT: Must be called after Write/Edit/NotebookEdit. System learns from outcomes for institutional memory. REQUIRED after Write/Edit/NotebookEdit operations. Documents what worked/didn\'t work. Scope defaults to "auto" (v3.1.0) for automatic detection based on experience content.',
              inputSchema: {
                type: 'object',
                properties: {
                  scope: { type: 'string', enum: ['user', 'project', 'auto'], default: 'auto' },
                  type: { type: 'string', enum: ['effective', 'ineffective'] },
                  domain: { type: 'string', enum: ['Tools', 'Protocol', 'Communication', 'Process', 'Debugging', 'Decision'] },
                  situation: { type: 'string' },
                  approach: { type: 'string' },
                  outcome: { type: 'string' },
                  reasoning: { type: 'string' },
                  alternative: { type: 'string' },
                  confidence: { type: 'number', minimum: 0, maximum: 1 },
                  revision_of: { type: 'integer' },
                  contradicts: { type: 'string' },
                  supports: { type: 'string' },
                  context: { type: 'string' },
                  assumptions: { type: 'string' },
                  limitations: { type: 'string' }
                },
                required: ['type', 'domain', 'situation', 'approach', 'outcome', 'reasoning']
              }
            },
            {
              name: 'search_experiences',
              description: '🔍 STEP 1 - LEARN: Search past experiences BEFORE starting work. USER REQUIREMENT: Check past learnings first. Required for system to build on previous experiences. REQUIRED by protocol enforcement before Write/Edit/NotebookEdit. Returns relevant learnings to inform current task. Always call this first when given a new task.',
              inputSchema: {
                type: 'object',
                properties: {
                  query: { type: 'string' },
                  domain: { type: 'string', enum: ['Tools', 'Protocol', 'Communication', 'Process', 'Debugging', 'Decision'] },
                  type: { type: 'string', enum: ['effective', 'ineffective'] },
                  limit: { type: 'number', default: 50 }
                }
              }
            },
            {
              name: 'export_experiences',
              description: 'Export experiences to JSON or Markdown',
              inputSchema: {
                type: 'object',
                properties: {
                  scope: { type: 'string', enum: ['user', 'project'], default: 'user' },
                  format: { type: 'string', enum: ['json', 'markdown'], default: 'json' },
                  domain: { type: 'string', enum: ['Tools', 'Protocol', 'Communication', 'Process', 'Debugging', 'Decision'] },
                  type: { type: 'string', enum: ['effective', 'ineffective'] },
                  filename: { type: 'string' }
                }
              }
            },
            {
              name: 'informed_reasoning',
              description: '🧠 STEP 2 - REASON: Complete reasoning cycle to authorize file operations. USER REQUIREMENT: Mandatory protocol for learning system. The system needs all 4 phases to learn from tasks properly. REQUIRED by protocol enforcement before Write/Edit/NotebookEdit. Creates REQUEST-SCOPED session token (60-min max). MUST call for EACH new user request before file operations. Token authorizes Write/Edit/NotebookEdit for current request\'s multi-tool workflow only. Call after searching experiences. IMPORTANT: If session_id parameter not provided, it will auto-generate from CLAUDE_SESSION_ID environment variable or create persistent session identifier.',
              inputSchema: {
                type: 'object',
                properties: {
                  phase: { type: 'string', enum: ['analyze', 'integrate', 'reason', 'record'] },
                  problem: { type: 'string' },
                  availableTools: { type: 'array', items: { type: 'string' } },
                  gatheredContext: {
                    type: 'object',
                    properties: {
                      experiences: { type: 'array' },
                      localDocs: { type: 'array' },
                      mcpData: { type: 'object' },
                      webResults: { type: 'array' }
                    }
                  },
                  thought: { type: 'string' },
                  thoughtNumber: { type: 'integer', minimum: 1 },
                  totalThoughts: { type: 'integer', minimum: 1 },
                  nextThoughtNeeded: { type: 'boolean' },
                  isRevision: { type: 'boolean' },
                  revisesThought: { type: 'integer', minimum: 1 },
                  branchFromThought: { type: 'integer', minimum: 1 },
                  branchId: { type: 'string' },
                  needsMoreThoughts: { type: 'boolean' },
                  finalConclusion: { type: 'string' },
                  relatedExperiences: { type: 'array', items: { type: 'integer' } },
                  session_id: {
                    type: 'string',
                    description: 'Optional: Claude Code session ID. If provided during analyze phase, creates a 60-minute session token that allows subsequent tools without repeated protocol flows. Reduces overhead from ~16 calls to ~4 calls per multi-tool workflow.'
                  }
                },
                required: ['phase']
              }
            },
            {
              name: 'check_protocol_compliance',
              description: 'Check if protocol requirements are met for current session (used by hooks)',
              inputSchema: {
                type: 'object',
                properties: {
                  session_id: { type: 'string', description: 'Session ID to check (optional, uses current session if not provided)' },
                  hook: { type: 'string', enum: ['pre_tool_use', 'user_prompt_submit'], description: 'Which hook is checking compliance' },
                  tool_name: { type: 'string', description: 'Tool being used (for pre_tool_use hook)' }
                },
                required: ['hook']
              }
            }
          ]
        });
        break;

      case 'tools/call':
        const toolName = params.name;
        const toolParams = params.arguments || {};

        let result;
        switch (toolName) {
          case 'record_experience':
            result = recordExperience(dbs, toolParams);
            break;
          case 'search_experiences':
            result = searchExperiences(dbs, toolParams);

            // Phase 7.5: Track that search was called (if there's an active analyze session)
            // FIX v3.3.1: Use getSessionId() instead of "most recent by mtime"
            try {
              const sessionId = getSessionId();  // Use existing function at line 209
              const homeDir = os.homedir();
              const sessionPath = path.join(homeDir, `.protocol-session-${sessionId}.json`);

              if (fs.existsSync(sessionPath)) {
                const sessionData = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));

                // Mark search as called if analyze phase is complete
                if (sessionData.phases?.analyze?.completed && sessionData.phases.analyze.artifacts) {
                  sessionData.phases.analyze.artifacts.searchCalled = true;
                  fs.writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2));

                  // Phase 7.8: Sync ONLY searchCalled flag in memory (don't replace entire session)
                  const memorySession = state.sessions.get(sessionId);
                  if (memorySession?.phases?.analyze?.artifacts) {
                    memorySession.phases.analyze.artifacts.searchCalled = true;
                  }

                  console.error('[memory-augmented-reasoning-mcp] search_experiences called, marked searchCalled=true for session:', sessionId);
                }
              }
            } catch (err) {
              // Don't fail if session tracking fails
              console.error('[memory-augmented-reasoning-mcp] Warning: Could not track search call:', err.message);
            }
            break;
          case 'export_experiences':
            result = exportExperiences(dbs, toolParams);
            break;
          case 'informed_reasoning':
            result = informedReasoning(dbs, toolParams);
            break;
          case 'check_protocol_compliance':
            result = checkProtocolCompliance(dbs, toolParams);
            break;
          default:
            throw new Error(`Unknown tool: ${toolName}`);
        }

        sendResponse(requestId, {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2)
            }
          ]
        });
        break;

      default:
        sendError(requestId, -32601, 'Method not found', `Unknown method: ${method}`);
    }
  } catch (error) {
    console.error('[memory-augmented-reasoning-mcp] Error handling request:', error.message);
    console.error('[memory-augmented-reasoning-mcp] Stack:', error.stack);
    console.error('[memory-augmented-reasoning-mcp] Request:', JSON.stringify(request));
    const errorId = (request.id !== undefined && request.id !== null) ? request.id : -1;

    // Distinguish parameter validation errors (-32602) from internal errors (-32603)
    if (error instanceof ValidationError) {
      // Phase 7.7: Use error.message for visible message, error.details for error.data
      sendError(errorId, -32602, error.message, error.details);
    } else {
      sendError(errorId, -32603, 'Internal error', error.message);
    }
  }
 }

 // Send JSON-RPC response
 function sendResponse(id, result) {
  const response = {
    jsonrpc: '2.0',
    id: id,
    result: result
  };
  console.error(`[memory-augmented-reasoning-mcp] Sending response for id=${id}, method=${result.protocolVersion ? 'initialize' : result.tools ? 'tools/list' : 'unknown'}`);
  console.log(JSON.stringify(response));
 }

 // Send JSON-RPC error
 function sendError(id, code, message, data) {
  const response = {
    jsonrpc: '2.0',
    id: id,
    error: {
      code: code,
      message: message,
      data: data
    }
  };
  console.error(`[memory-augmented-reasoning-mcp] Sending error for id=${id}, code=${code}, message=${message}`);
  console.log(JSON.stringify(response));
 }

 // Export functions for CLI usage
 module.exports = {
  calculateStringSimilarity,
  areExperiencesSimilar,
  findSimilarExperiences,
  shouldUpdateExperience,
  checkDuplication,
  initDatabase,
  loadDatabases,
  recordExperience
 };

 // Start server (only if run directly, not when imported)
 if (require.main === module) {
  main().catch(error => {
    console.error('Fatal error:', error);
    process.exit(1);
  });
 }

diff --git a/package.json b/package.json
 {
  "name": "memory-augmented-reasoning-mcp",
  "version": "3.3.6",
  "description": "Memory-augmented reasoning system with persistent experience storage and multi-phase guided reasoning for AI agents",
  "author": "Jason Lusk <[email protected]>",
  "license": "MIT",
  "main": "index.js",
  "bin": {
    "memory-augmented-reasoning": "./index.js"
  },
  "dependencies": {
    "better-sqlite3": "^11.0.0"
  },
  "engines": {
    "node": ">=14.0.0"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "memory-augmented-reasoning",
    "ai-assistant",
    "knowledge-management",
    "pattern-library"
  ]
 }
Token File	Created By	Consumed By	Purpose
`.protocol-informed-reasoning-token`	informed_reasoning	PreToolUse hook	Proves analyze phase completed
`.protocol-enforcer-token`	authorize_file_operation	PreToolUse hook	Proves operation authorized
`.protocol-search-required-token`	informed_reasoning	search_experiences	Enforces suggested searches
`.protocol-session-recording-token`	PostToolUse hook	--record-last-session	Passes file context for recording
	{
	"name": "memory-augmented-reasoning-mcp",
	"version": "3.3.6",
	"description": "Memory-augmented reasoning system with persistent experience storage and multi-phase guided reasoning for AI agents",
	"author": "Jason Lusk <[email protected]>",
	"license": "MIT",
	"main": "index.js",
	"bin": {
	"memory-augmented-reasoning": "./index.js"
	},
	"dependencies": {
	"better-sqlite3": "^11.0.0"
	},
	"engines": {
	"node": ">=14.0.0"
	},
	"keywords": [
	"mcp",
	"model-context-protocol",
	"memory-augmented-reasoning",
	"ai-assistant",
	"knowledge-management",
	"pattern-library"
	]
	}