wolverine-ai 1.0.0

package/src/backup/backup-manager.js

@@ -0,0 +1,321 @@
+const fs = require("fs");
+const path = require("path");
+const chalk = require("chalk");
+
+/**
+ * Smart Backup Manager — manages versioned backups with stability tracking.
+ *
+ * Backup lifecycle:
+ * 1. UNSTABLE: Created when a fix is applied, before verification
+ * 2. VERIFIED: The fix ran without immediately crashing (same error)
+ * 3. STABLE:   The server ran successfully for STABILITY_THRESHOLD without crashing
+ *
+ * Retention policy:
+ * - Unstable backups: deleted after 7 days
+ * - Verified backups: kept for 7 days, then pruned unless promoted to stable
+ * - Stable backups:   after 7 days, keep only 1 per day (most recent each day)
+ *
+ * Storage layout:
+ *   .wolverine/
+ *     backups/
+ *       manifest.json         — tracks all backups with metadata
+ *       <timestamp>/          — one directory per backup event
+ *         <filename>.bak      — the original file content
+ */
+
+const WOLVERINE_DIR = ".wolverine";
+const BACKUPS_DIR = path.join(WOLVERINE_DIR, "backups");
+const MANIFEST_FILE = path.join(BACKUPS_DIR, "manifest.json");
+
+// Stability threshold: how long the server must run without the same crash
+// to consider a fix "stable" (default: 30 minutes)
+const STABILITY_THRESHOLD_MS = 30 * 60 * 1000;
+
+// Retention: unstable/verified backups older than this are pruned
+const RETENTION_UNSTABLE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+class BackupManager {
+  constructor(projectRoot) {
+    this.projectRoot = path.resolve(projectRoot);
+    this.backupsDir = path.join(this.projectRoot, BACKUPS_DIR);
+    this.manifestPath = path.join(this.projectRoot, MANIFEST_FILE);
+    this._ensureDirs();
+    this.manifest = this._loadManifest();
+  }
+
+  /**
+   * Create a backup of specific files or the entire server/ directory.
+   * Returns a backupId that can be used to rollback or promote.
+   *
+   * @param {string[]|null} filePaths — specific files, or null to backup entire server/
+   */
+  createBackup(filePaths) {
+    const backupId = Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 6);
+    const timestamp = Date.now();
+    const backupDir = path.join(this.backupsDir, backupId);
+    fs.mkdirSync(backupDir, { recursive: true });
+
+    // If no specific files, backup the entire server/ directory
+    if (!filePaths || filePaths.length === 0) {
+      filePaths = this._collectServerFiles();
+    }
+
+    const files = [];
+    for (const filePath of filePaths) {
+      const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(this.projectRoot, filePath);
+      if (!fs.existsSync(absPath)) continue;
+      // Skip large files (>10MB) and binary blobs
+      try {
+        const stat = fs.statSync(absPath);
+        if (stat.size > 10 * 1024 * 1024) continue;
+      } catch { continue; }
+
+      const relativePath = path.relative(this.projectRoot, absPath);
+      const backupFile = path.join(backupDir, relativePath.replace(/[/\\]/g, "__"));
+      fs.copyFileSync(absPath, backupFile);
+
+      files.push({
+        original: absPath,
+        relative: relativePath,
+        backup: backupFile,
+      });
+    }
+
+    const entry = {
+      id: backupId,
+      timestamp,
+      status: "unstable",
+      files,
+      errorSignature: null,
+      promotedAt: null,
+      verifiedAt: null,
+    };
+
+    this.manifest.backups.push(entry);
+    this._saveManifest();
+
+    return backupId;
+  }
+
+  /**
+   * Rollback to a specific backup.
+   */
+  rollbackTo(backupId) {
+    const entry = this.manifest.backups.find(b => b.id === backupId);
+    if (!entry) {
+      console.log(chalk.red(`Backup ${backupId} not found.`));
+      return false;
+    }
+
+    let allRestored = true;
+    for (const file of entry.files) {
+      if (fs.existsSync(file.backup)) {
+        fs.copyFileSync(file.backup, file.original);
+        console.log(chalk.yellow(`  ↩️  Restored: ${file.relative}`));
+      } else {
+        console.log(chalk.red(`  ❌ Backup file missing: ${file.backup}`));
+        allRestored = false;
+      }
+    }
+
+    return allRestored;
+  }
+
+  /**
+   * Rollback to the most recent backup (any status).
+   */
+  rollbackLatest() {
+    if (this.manifest.backups.length === 0) return false;
+    const latest = this.manifest.backups[this.manifest.backups.length - 1];
+    console.log(chalk.yellow(`\n↩️  Rolling back to backup ${latest.id} (${new Date(latest.timestamp).toISOString()})...`));
+    return this.rollbackTo(latest.id);
+  }
+
+  /**
+   * Mark a backup as verified (fix didn't immediately reproduce the error).
+   */
+  markVerified(backupId) {
+    const entry = this.manifest.backups.find(b => b.id === backupId);
+    if (entry && entry.status === "unstable") {
+      entry.status = "verified";
+      entry.verifiedAt = Date.now();
+      this._saveManifest();
+    }
+  }
+
+  /**
+   * Mark a backup as stable (server ran for the full stability threshold).
+   */
+  markStable(backupId) {
+    const entry = this.manifest.backups.find(b => b.id === backupId);
+    if (entry && (entry.status === "verified" || entry.status === "unstable")) {
+      entry.status = "stable";
+      entry.promotedAt = Date.now();
+      this._saveManifest();
+      console.log(chalk.green(`  🏆 Backup ${backupId} promoted to STABLE.`));
+    }
+  }
+
+  /**
+   * Set the error signature on a backup (for tracking what error this fix addressed).
+   */
+  setErrorSignature(backupId, signature) {
+    const entry = this.manifest.backups.find(b => b.id === backupId);
+    if (entry) {
+      entry.errorSignature = signature;
+      this._saveManifest();
+    }
+  }
+
+  /**
+   * Run the retention policy — prune old backups.
+   *
+   * Rules:
+   * 1. Unstable/verified backups older than 7 days → delete
+   * 2. Stable backups older than 7 days → keep only 1 per day (most recent each day)
+   * 3. All stable backups within 7 days → keep
+   */
+  prune() {
+    const now = Date.now();
+    const cutoff = now - RETENTION_UNSTABLE_MS;
+    let pruned = 0;
+
+    // Separate backups by status
+    const toKeep = [];
+    const stableOld = [];
+
+    for (const entry of this.manifest.backups) {
+      if (entry.status === "stable") {
+        if (entry.timestamp < cutoff) {
+          stableOld.push(entry);
+        } else {
+          toKeep.push(entry);
+        }
+      } else {
+        // Unstable or verified
+        if (entry.timestamp < cutoff) {
+          this._deleteBackupFiles(entry);
+          pruned++;
+        } else {
+          toKeep.push(entry);
+        }
+      }
+    }
+
+    // For old stable backups: keep 1 per day
+    if (stableOld.length > 0) {
+      const byDay = new Map();
+      for (const entry of stableOld) {
+        const dayKey = new Date(entry.timestamp).toISOString().slice(0, 10);
+        if (!byDay.has(dayKey)) {
+          byDay.set(dayKey, []);
+        }
+        byDay.get(dayKey).push(entry);
+      }
+
+      for (const [, dayEntries] of byDay) {
+        // Sort by timestamp descending, keep the newest per day
+        dayEntries.sort((a, b) => b.timestamp - a.timestamp);
+        toKeep.push(dayEntries[0]); // keep the most recent
+        for (let i = 1; i < dayEntries.length; i++) {
+          this._deleteBackupFiles(dayEntries[i]);
+          pruned++;
+        }
+      }
+    }
+
+    this.manifest.backups = toKeep;
+    this._saveManifest();
+
+    if (pruned > 0) {
+      console.log(chalk.gray(`  🧹 Pruned ${pruned} old backup(s).`));
+    }
+
+    return pruned;
+  }
+
+  /**
+   * Get summary stats for logging.
+   */
+  getStats() {
+    const counts = { unstable: 0, verified: 0, stable: 0 };
+    for (const entry of this.manifest.backups) {
+      counts[entry.status] = (counts[entry.status] || 0) + 1;
+    }
+    return {
+      total: this.manifest.backups.length,
+      ...counts,
+    };
+  }
+
+  // -- Private --
+
+  _ensureDirs() {
+    fs.mkdirSync(this.backupsDir, { recursive: true });
+  }
+
+  _loadManifest() {
+    if (fs.existsSync(this.manifestPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(this.manifestPath, "utf-8"));
+      } catch {
+        return { version: 1, backups: [] };
+      }
+    }
+    return { version: 1, backups: [] };
+  }
+
+  _saveManifest() {
+    fs.writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2), "utf-8");
+  }
+
+  _deleteBackupFiles(entry) {
+    const backupDir = path.join(this.backupsDir, entry.id);
+    if (fs.existsSync(backupDir)) {
+      for (const file of fs.readdirSync(backupDir)) {
+        fs.unlinkSync(path.join(backupDir, file));
+      }
+      fs.rmdirSync(backupDir);
+    }
+  }
+
+  /**
+   * Collect all files in the server/ directory for full backup.
+   * Includes: .js, .json, .sql, .db, .sqlite, .yaml, .yml, .env, .html, .css
+   * Excludes: node_modules, .git, large binaries
+   */
+  _collectServerFiles() {
+    const serverDir = path.join(this.projectRoot, "server");
+    if (!fs.existsSync(serverDir)) return [];
+
+    const files = [];
+    const SKIP = new Set(["node_modules", ".git", ".wolverine"]);
+    const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+
+    const walk = (dir) => {
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+
+      for (const entry of entries) {
+        if (SKIP.has(entry.name)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else {
+          try {
+            const stat = fs.statSync(fullPath);
+            if (stat.size <= MAX_FILE_SIZE) {
+              files.push(fullPath);
+            }
+          } catch {}
+        }
+      }
+    };
+
+    walk(serverDir);
+    return files;
+  }
+}
+
+module.exports = { BackupManager, STABILITY_THRESHOLD_MS };

package/src/brain/brain.js

@@ -0,0 +1,315 @@
+const chalk = require("chalk");
+const { VectorStore } = require("./vector-store");
+const { embed, embedBatch, compactAndEmbed } = require("./embedder");
+const { scanProject, mapToChunks } = require("./function-map");
+
+/**
+ * The Wolverine Brain — semantic memory + project context.
+ *
+ * On startup:
+ * 1. Load persisted vector store from .wolverine/brain/
+ * 2. Scan the project to build a live function map
+ * 3. Seed wolverine documentation (only on first init)
+ * 4. Embed function map chunks into the "functions" namespace
+ *
+ * During operation:
+ * - remember(): Compact + embed + store a new memory
+ * - recall(): Semantic search for relevant context
+ * - getContext(): Build a context string for the AI agent
+ *
+ * Namespaces:
+ * - "docs"      — wolverine documentation, how self-healing works
+ * - "functions"  — live function map (routes, exports, classes)
+ * - "errors"     — past errors and their contexts
+ * - "fixes"      — successful fixes and their explanations
+ * - "learnings"  — patterns learned from fix successes/failures
+ */
+
+// Seed documents — wolverine's knowledge about itself
+const SEED_DOCS = [
+  {
+    text: "Wolverine Node.js is an autonomous self-healing server agent. It monitors a Node.js process, catches crashes, analyzes errors using AI, generates code fixes, verifies them, and restarts the server. It operates as a process manager similar to PM2 but with AI-powered repair capabilities.",
+    metadata: { topic: "overview" },
+  },
+  {
+    text: "Wolverine heal pipeline: crash detected → error parsed (file, line, message) → prompt injection scan (AUDIT_MODEL) → rate limit check → fast path repair (CODING_MODEL via Responses/Chat API) → if fast path fails verification → escalate to multi-file agent (REASONING_MODEL with tools: read_file, write_file, list_files, search_files) → verify fix (syntax check + boot probe) → rollback on failure.",
+    metadata: { topic: "heal-pipeline" },
+  },
+  {
+    text: "Wolverine backup system: every fix creates a backup before patching. Status lifecycle: UNSTABLE (just created) → VERIFIED (fix passed boot probe) → STABLE (server ran 30min+ without crash). Retention: unstable backups pruned after 7 days. Stable backups older than 7 days keep 1 per day.",
+    metadata: { topic: "backup-system" },
+  },
+  {
+    text: "Wolverine security: file sandbox restricts all reads/writes to the project directory. Prompt injection detection runs on every error (regex layer + AI audit via AUDIT_MODEL). Rate limiter prevents error explosion cost with sliding window, min gap, hourly token budget, and exponential backoff for error loops.",
+    metadata: { topic: "security" },
+  },
+  {
+    text: "Wolverine model tiers: REASONING_MODEL for deep multi-step debugging. CODING_MODEL for code repair generation. CHAT_MODEL for explanations and summaries. AUDIT_MODEL for security scans (runs every error, keep cheap). UTILITY_MODEL for JSON formatting and thought compaction. TEXT_EMBEDDING_MODEL for brain vector embeddings.",
+    metadata: { topic: "model-config" },
+  },
+  {
+    text: "Wolverine performance monitoring: tracks HTTP endpoint response times, detects slow endpoints (>2s avg), identifies spam/DDoS patterns (>100 req/min to one endpoint), flags response time spikes (5x normal), detects high error rates (>20%). Triggers AI analysis for optimization suggestions.",
+    metadata: { topic: "perf-monitoring" },
+  },
+  {
+    text: "Wolverine brain: semantic vector database for long-term memory. Stores project function maps, past errors, successful fixes, and learned patterns. Uses TEXT_EMBEDDING_MODEL for embeddings and UTILITY_MODEL to compact thoughts before embedding. In-memory cosine similarity search for speed. Persisted to .wolverine/brain/.",
+    metadata: { topic: "brain" },
+  },
+  {
+    text: "Wolverine health checks: periodically pings the server's /health endpoint. After 3 consecutive failures, force-kills and triggers heal cycle. Configurable interval, timeout, and fail threshold. Prevents undetected hangs and frozen servers.",
+    metadata: { topic: "health-checks" },
+  },
+  {
+    text: "Wolverine fix verification: after applying a patch, runs a 2-step validation. Step 1: node --check for syntax errors. Step 2: boot probe — starts the server on an ephemeral port for 10s. If same error recurs: fix didn't work, rollback. If different error: fix broke something else, rollback. If alive: fix works, proceed.",
+    metadata: { topic: "verification" },
+  },
+  {
+    text: "Wolverine multi-file agent: 15-turn agent loop with tools. Can read any file, write any file type (js, json, sql, yaml, env, dockerfile), list directories, and search across the codebase. Used when the fast path single-file fix fails. Tracks token budget (50k max) to control costs.",
+    metadata: { topic: "agent" },
+  },
+  {
+    text: "Wolverine supports the Responses API for codex models and Chat Completions API for standard models. Auto-detects based on model name. Codex models use openai.responses.create() with input/instructions/tools. Standard models use openai.chat.completions.create() with messages/tools.",
+    metadata: { topic: "api-support" },
+  },
+  {
+    text: "Common Node.js errors Wolverine fixes: ReferenceError (undefined variables, typos), TypeError (calling methods on wrong types, null access), SyntaxError (missing brackets, invalid JSON), EADDRINUSE (port already in use), MODULE_NOT_FOUND (missing dependencies), ECONNREFUSED (database/service connection failures), unhandled promise rejections.",
+    metadata: { topic: "common-errors" },
+  },
+  {
+    text: "Server uses Fastify (5.6x faster than Express, 114k req/s). server/index.js wires routes with fastify.register(require('./routes/X'), {prefix:'/X'}). Route files: async function routes(fastify) { fastify.get('/', async () => ({...})); } module.exports = routes. server/routes/ has one file per resource. server/config/settings.json for all settings.",
+    metadata: { topic: "server-structure" },
+  },
+  {
+    text: "Server best practices: validate all input, use express.json() with size limits. Never expose secrets in responses. Use env vars for config. Add /health endpoint returning status+uptime+memory. Keep routes thin — logic in services. Use async/await never block event loop. Global error handler middleware. Consistent error format: {error:'message'}. One route file per resource. Rate limit public endpoints.",
+    metadata: { topic: "server-best-practices" },
+  },
+  {
+    text: "Wolverine editable scope: only files inside server/ can be modified by the agent. src/, bin/, tests/, .env, package.json, node_modules/ are all protected. The agent's _isProtectedPath guard blocks writes to anything outside server/. Direct edits target the script wolverine was launched with (server/index.js by default).",
+    metadata: { topic: "editable-scope" },
+  },
+  {
+    text: "SQL Skill: wolverine has a SQL skill at src/skills/sql.js providing: (1) sqlGuard() middleware that blocks SQL injection attacks on all endpoints by scanning query params, body, URL params, and headers for injection patterns like UNION SELECT, stacked queries, tautologies, comment bypass, hex encoding, timing attacks. (2) SafeDB class for parameterized-only database queries — blocks string concatenation in SQL. Usage: const {db,sqlGuard}=require('../src/skills/sql'); app.use(sqlGuard()); db.all('SELECT * FROM users WHERE id=?',[id]);",
+    metadata: { topic: "skill-sql" },
+  },
+  {
+    text: "SQL injection patterns wolverine detects: OR/AND tautologies ('1'='1'), UNION SELECT, stacked queries (;DROP TABLE), comment bypass (-- or #), hex encoding (0x), CHAR() encoding, SLEEP/BENCHMARK timing attacks, INFORMATION_SCHEMA probing, LOAD_FILE/INTO OUTFILE data exfiltration. All blocked with 403 and logged as security.sqli_blocked events.",
+    metadata: { topic: "skill-sql-patterns" },
+  },
+  {
+    text: "Database best practices: SafeDB uses split connections — separate read connection (concurrent, never waits) and write connection (single writer, FIFO queue). Write queue drains synchronously in one microtask, zero delays. WAL mode means readers never block writers. Each write is microseconds. db.transaction(fn) queues as single atomic unit. No busy_timeout, no blocking, no IPC. Reads: db.get(), db.all() are instant. Writes: db.run(), db.exec() go through queue.",
+    metadata: { topic: "skill-sql-best-practices" },
+  },
+  {
+    text: "Sub-agent system: wolverine can spawn specialized sub-agents for divide-and-conquer. 7 types: explore (read-only, investigates codebase), plan (read-only, proposes fix strategy), fix (read+write, applies targeted fix), verify (read-only, checks if fix works), research (searches brain+web for solutions), security (audits for vulnerabilities), database (handles DB issues with SQL skill). Each type has restricted tools and a specific model.",
+    metadata: { topic: "sub-agents" },
+  },
+  {
+    text: "Sub-agent workflow: explore→plan→fix. Explorer finds relevant files, Planner proposes a strategy using exploration results, Fixer executes the plan. Used automatically on goal loop iteration 3+ and dashboard LARGE tier commands. Sub-agents can also run in parallel via spawnParallel() for independent tasks like running security audit + explore simultaneously.",
+    metadata: { topic: "sub-agent-workflow" },
+  },
+  {
+    text: "Sub-agent tool restrictions (claw-code pattern): explore gets read_file/glob/grep/git. plan gets read_file/glob/grep/brain. fix gets read_file/write_file/edit_file/glob/grep. verify gets read_file/glob/grep/bash. research gets read_file/grep/web_fetch/brain. security gets read_file/glob/grep. database gets read_file/write_file/edit_file/glob/grep/bash. No agent gets tools it doesn't need.",
+    metadata: { topic: "sub-agent-tools" },
+  },
+  {
+    text: "Heal pipeline escalation: Iteration 1 uses fast path (CODING_MODEL, single file, cheapest). Iteration 2 uses single agent (REASONING_MODEL, multi-file, 8 turns). Iteration 3+ uses sub-agents (explore→plan→fix, 3 specialized agents with restricted tools). Each iteration gets context from previous failures. Deep research (RESEARCH_MODEL) triggers after 2+ failures.",
+    metadata: { topic: "heal-escalation" },
+  },
+  {
+    text: "Process manager: wolverine monitors memory (RSS/heap) every 10s, detects memory leaks (N consecutive growth samples → auto-restart), enforces memory limit (default 512MB), tracks CPU%, probes all routes every 30s, detects response time degradation trends (stable/degrading/improving). Analytics dashboard shows memory/CPU charts and per-route health.",
+    metadata: { topic: "process-manager" },
+  },
+  {
+    text: "Auto-clustering: wolverine detects machine capabilities (cores, RAM, disk, platform, Docker/K8s, cloud provider) and forks optimal workers. 2 cores = 2 workers, 3-4 = cores-1, 5-8 = cores-1 cap 6, 9+ = cores/2 cap 16. Workers auto-respawn on crash with exponential backoff. CLI: --single (no cluster), --workers N (fixed), --info (show system). Settings in server/config/settings.json cluster.mode.",
+    metadata: { topic: "clustering" },
+  },
+  {
+    text: "System detection: wolverine --info shows CPU cores/model/speed, total/free RAM, disk space, Node version, platform, container environment (Docker, Kubernetes), cloud provider (AWS, GCP, Azure, Railway, Fly, Render, Heroku). Used by ClusterManager to auto-scale worker count. Dashboard API: GET /api/system returns full machine info.",
+    metadata: { topic: "system-detection" },
+  },
+  {
+    text: "Configuration: all settings in server/config/settings.json (models, port, telemetry, rate limits, health checks, clustering, cors, logging). Secrets only in .env.local (API keys, admin key). Config loader priority: env vars > settings.json > defaults. Agent can read and edit settings.json since it's inside server/.",
+    metadata: { topic: "configuration" },
+  },
+  {
+    text: "Platform telemetry: lightweight background process, zero-config. Default platform: api.wolverinenode.xyz. Auto-registers on first run (retries every 60s until platform responds), saves key to .wolverine/platform-key. Heartbeat payload matches PLATFORM.md spec: instanceId, server (name/port/uptime/status/pid), process (memoryMB/cpuPercent), routes, repairs, usage (tokens/cost/calls/byCategory), brain, backups. Offline-resilient: queues up to 1440 heartbeats locally, drains on reconnect. No chalk dependency, cached version/key in memory, minimal IO. Opt out: WOLVERINE_TELEMETRY=false. Override URL: WOLVERINE_PLATFORM_URL.",
+    metadata: { topic: "platform-telemetry" },
+  },
+  {
+    text: "Telemetry architecture: 4 files, ~250 lines total. heartbeat.js sends one HTTP POST every 60s (5s timeout, non-blocking). register.js auto-registers and caches key in memory + disk. queue.js appends to JSONL file only on failure, trims lazily. telemetry.js collects from subsystems using optional chaining (no crashes if subsystem missing). All secrets redacted before sending. Response bodies drained immediately (res.resume). No blocking, no delays, no busy waits.",
+    metadata: { topic: "telemetry-architecture" },
+  },
+];
+
+class Brain {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.store = new VectorStore(projectRoot);
+    this.functionMap = null;
+    this._initialized = false;
+  }
+
+  /**
+   * Initialize the brain. Call once on startup.
+   * Scans project, seeds docs if needed, embeds function map.
+   */
+  async init() {
+    const stats = this.store.getStats();
+    const isFirstRun = stats.totalEntries === 0;
+
+    console.log(chalk.gray(`  🧠 Brain: ${stats.totalEntries} memories loaded`));
+
+    // 1. Seed wolverine docs on first run
+    if (isFirstRun) {
+      console.log(chalk.gray("  🧠 First run — seeding wolverine documentation..."));
+      await this._seedDocs();
+    }
+
+    // 2. Scan project for live function map
+    console.log(chalk.gray("  🧠 Scanning project for function map..."));
+    this.functionMap = scanProject(this.projectRoot);
+    console.log(chalk.gray(`  🧠 Found: ${this.functionMap.routes.length} routes, ${this.functionMap.functions.length} functions, ${this.functionMap.classes.length} classes`));
+
+    // 3. Embed function map (replace old "functions" entries)
+    await this._embedFunctionMap();
+
+    // 4. Save
+    this.store.save();
+
+    this._initialized = true;
+    const finalStats = this.store.getStats();
+    console.log(chalk.gray(`  🧠 Brain ready: ${finalStats.totalEntries} total memories`));
+    if (finalStats.namespaces) {
+      const ns = Object.entries(finalStats.namespaces).map(([k, v]) => `${k}:${v}`).join(", ");
+      console.log(chalk.gray(`  🧠 Namespaces: ${ns}`));
+    }
+  }
+
+  /**
+   * Remember something — compact, embed, and store.
+   *
+   * @param {string} namespace - "errors", "fixes", "learnings"
+   * @param {string} rawText - The raw text to remember
+   * @param {object} metadata - Structured metadata
+   */
+  async remember(namespace, rawText, metadata = {}) {
+    const { compacted, embedding } = await compactAndEmbed(rawText);
+    const id = this.store.add(namespace, compacted, embedding, metadata);
+    this.store.save();
+    return id;
+  }
+
+  /**
+   * Recall relevant memories — two-tier search for speed.
+   *
+   * Tier 1: Fast keyword search (instant, no API call)
+   * Tier 2: Semantic embedding search (API call, only if keywords miss)
+   */
+  async recall(query, options = {}) {
+    const topK = options.topK || 5;
+
+    // Tier 1: keyword search (instant)
+    const keywordResults = this.store.keywordSearch(query, { topK, namespace: options.namespace, minTokens: 1 });
+    if (keywordResults.length >= topK) {
+      return keywordResults;
+    }
+
+    // Tier 2: semantic search (API call — only if keyword search didn't find enough)
+    try {
+      const queryEmbedding = await embed(query);
+      const semanticResults = this.store.search(queryEmbedding, { topK, ...options });
+
+      // Merge: keyword results first (they're more precise), then semantic
+      const seen = new Set(keywordResults.map(r => r.id));
+      const merged = [...keywordResults];
+      for (const r of semanticResults) {
+        if (!seen.has(r.id)) {
+          merged.push(r);
+          seen.add(r.id);
+        }
+      }
+      return merged.slice(0, topK);
+    } catch {
+      // If embedding API fails, return keyword results only
+      return keywordResults;
+    }
+  }
+
+  /**
+   * Build a full context string for the agent.
+   * Includes: function map summary + relevant memories.
+   */
+  async getContext(errorMessage) {
+    const parts = [];
+
+    // Function map summary (always included — fast, no API call)
+    if (this.functionMap) {
+      parts.push("## Server Function Map\n" + this.functionMap.summary);
+    }
+
+    // Two-tier recall: keyword first, semantic fallback
+    if (errorMessage) {
+      const memories = await this.recall(errorMessage, { topK: 5, minScore: 0.3 });
+      if (memories.length > 0) {
+        parts.push("\n## Relevant Context from Brain");
+        for (const mem of memories) {
+          const nsLabel = mem.namespace.toUpperCase();
+          parts.push(`[${nsLabel}] ${mem.text}`);
+        }
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Get stats for dashboard/logging.
+   */
+  getStats() {
+    return {
+      ...this.store.getStats(),
+      functionMap: this.functionMap ? {
+        routes: this.functionMap.routes.length,
+        functions: this.functionMap.functions.length,
+        classes: this.functionMap.classes.length,
+        files: this.functionMap.files.length,
+      } : null,
+    };
+  }
+
+  // -- Private --
+
+  async _seedDocs() {
+    const texts = SEED_DOCS.map(d => d.text);
+    const embeddings = await embedBatch(texts);
+
+    for (let i = 0; i < SEED_DOCS.length; i++) {
+      this.store.add("docs", SEED_DOCS[i].text, embeddings[i], SEED_DOCS[i].metadata);
+    }
+
+    console.log(chalk.gray(`  🧠 Seeded ${SEED_DOCS.length} documentation entries`));
+  }
+
+  async _embedFunctionMap() {
+    // Clear old function map entries
+    const oldEntries = this.store.getNamespace("functions");
+    for (const entry of oldEntries) {
+      this.store.delete(entry.id);
+    }
+
+    // Generate chunks from the live map
+    const chunks = mapToChunks(this.functionMap);
+    if (chunks.length === 0) return;
+
+    const texts = chunks.map(c => c.text);
+    const embeddings = await embedBatch(texts);
+
+    for (let i = 0; i < chunks.length; i++) {
+      this.store.add("functions", chunks[i].text, embeddings[i], chunks[i].metadata);
+    }
+
+    console.log(chalk.gray(`  🧠 Indexed ${chunks.length} function map chunks`));
+  }
+}
+
+module.exports = { Brain, SEED_DOCS };