forbocai 0.1.0 → 0.2.0

package/dist/cli.js

@@ -26,25 +26,144 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/cli.ts
 var import_http = __toESM(require("http"));
 var import_https = __toESM(require("https"));
+var readline = __toESM(require("readline"));
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var VERSION = "0.2.0";
 var DEFAULT_API_URL = "https://forbocai-api.onrender.com";
-var API_URL = process.env.FORBOC_API_URL || DEFAULT_API_URL;
+var CONFIG_PATH = path.join(process.env.HOME || ".", ".forbocai.json");
+var config = {};
+try {
+  if (fs.existsSync(CONFIG_PATH)) {
+    config = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+  }
+} catch {
+}
+var API_URL = process.env.FORBOC_API_URL || config.apiUrl || DEFAULT_API_URL;
 var args = process.argv.slice(2);
 var command = args[0];
 var subcommand = args[1];
-var subcommand2 = args[2];
-if (command === "api" && subcommand === "status") {
-  checkApiStatus();
-} else if (command === "agent" && subcommand === "create") {
-  createAgent(subcommand2);
-} else if (command === "soul" && subcommand === "export") {
-  exportSoul(subcommand2);
-} else if (command === "soul" && subcommand === "import") {
-  importSoul(subcommand2);
+var arg3 = args[2];
+var arg4 = args[3];
+var routes = {
+  // Meta
+  "version": () => console.log(`ForbocAI SDK v${VERSION}`),
+  "doctor": doctor,
+  // Config
+  "config_set": () => configSet(subcommand, arg3),
+  "config_get": () => configGet(subcommand),
+  "config_list": configList,
+  // API
+  "api_status": checkApiStatus,
+  // Cortex
+  "cortex_models": listModels,
+  "cortex_init": () => cortexInit(arg3),
+  // Agent
+  "agent_create": () => createAgent(arg3),
+  "agent_list": listAgents,
+  "agent_chat": () => chatWithAgent(arg3),
+  "agent_delete": () => deleteAgent(arg3),
+  "agent_state": () => agentState(arg3),
+  "agent_process": () => agentProcess(arg3, arg4),
+  "agent_update": () => agentUpdate(arg3, args.slice(3)),
+  // Soul
+  "soul_export": () => exportSoul(arg3),
+  "soul_import": () => importSoul(arg3),
+  "soul_chat": () => chatWithSoul(arg3),
+  "soul_list": soulList,
+  "soul_verify": () => soulVerify(arg3),
+  // Ghost
+  "ghost_run": () => runGhost(arg3),
+  "ghost_status": () => ghostStatus(arg3),
+  "ghost_results": () => ghostResults(arg3),
+  "ghost_stop": () => ghostStop(arg3),
+  "ghost_history": ghostHistory,
+  // Memory
+  "memory_list": () => memoryList(arg3),
+  "memory_recall": () => memoryRecall(arg3, arg4),
+  "memory_store": () => memoryStore(arg3, args.slice(3).join(" ")),
+  "memory_clear": () => memoryClear(arg3),
+  "memory_export": () => memoryExport(arg3),
+  // Bridge
+  "bridge_validate": () => bridgeValidate(arg3),
+  "bridge_rules": bridgeRules
+};
+var routeKey = subcommand ? `${command}_${subcommand}` : command;
+if (routes[routeKey]) {
+  routes[routeKey]();
+} else if (command === "config" && subcommand === "set") {
+  configSet(arg3, arg4);
+} else if (command === "config" && subcommand === "get") {
+  configGet(arg3);
 } else {
   printUsage();
 }
+function doctor() {
+  console.log(`
+\x1B[36m\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557`);
+  console.log(`\u2551  ForbocAI Doctor                       \u2551`);
+  console.log(`\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\x1B[0m
+`);
+  console.log(`Checking system...
+`);
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0]);
+  const nodeOk = nodeMajor >= 18;
+  console.log(`${nodeOk ? "\u2713" : "\u2717"} Node.js: ${nodeVersion} ${nodeOk ? "" : "(requires 18+)"}`);
+  console.log(`\u2713 API URL: ${API_URL}`);
+  const configExists = fs.existsSync(CONFIG_PATH);
+  console.log(`${configExists ? "\u2713" : "\u25CB"} Config: ${configExists ? CONFIG_PATH : "Not configured (using defaults)"}`);
+  console.log(`
+Testing API connection...`);
+  const client = API_URL.startsWith("https") ? import_https.default : import_http.default;
+  client.get(`${API_URL}/status`, (res) => {
+    if (res.statusCode === 200) {
+      console.log(`\x1B[32m\u2713 API: Online\x1B[0m`);
+    } else {
+      console.log(`\x1B[31m\u2717 API: Returned ${res.statusCode}\x1B[0m`);
+    }
+    console.log(`
+\x1B[32mDiagnosis complete.\x1B[0m`);
+  }).on("error", (e) => {
+    console.log(`\x1B[31m\u2717 API: ${e.message}\x1B[0m`);
+    console.log(`
+\x1B[33mTip: Check your internet connection or API URL\x1B[0m`);
+  });
+}
+function configSet(key, value) {
+  if (!key || !value) {
+    console.error("Usage: forbocai config set <key> <value>");
+    return;
+  }
+  config[key] = value;
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+  console.log(`> Set ${key} = ${value}`);
+}
+function configGet(key) {
+  if (!key) {
+    console.error("Usage: forbocai config get <key>");
+    return;
+  }
+  console.log(config[key] || `(not set)`);
+}
+function configList() {
+  console.log(`
+Configuration (${CONFIG_PATH}):
+`);
+  if (Object.keys(config).length === 0) {
+    console.log("  (no configuration set)");
+  } else {
+    for (const [key, value] of Object.entries(config)) {
+      console.log(`  ${key}: ${value}`);
+    }
+  }
+  console.log(`
+Defaults:`);
+  console.log(`  apiUrl: ${DEFAULT_API_URL}`);
+}
 function checkApiStatus() {
   console.log(`> Connecting to Neuro-Symbolic Grid...`);
+  console.log(`> API: ${API_URL}`);
   const client = API_URL.startsWith("https") ? import_https.default : import_http.default;
   client.get(`${API_URL}/status`, (res) => {
     let data = "";
@@ -61,14 +180,53 @@ function checkApiStatus() {
         console.log(`> Version: ${json.version}`);
       } catch (e) {
         console.error("> Error: Invalid JSON response from server.");
-        console.log(data.substring(0, 100) + "...");
       }
     });
   }).on("error", (e) => {
     console.error(`> Error: ${e.message}`);
-    console.log(`> Hint: Is the local Haskell API running? (cd api/hs && cabal run)`);
+    console.log(`> Hint: Run 'forbocai doctor' to diagnose`);
   });
 }
+async function listModels() {
+  console.log(`> Fetching available models...`);
+  try {
+    const res = await fetch(`${API_URL}/cortex/models`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`
+  Available Models:
+`);
+    data.forEach((model) => {
+      console.log(`  \x1B[36m${model.id || model.modelId}\x1B[0m`);
+      console.log(`    Name: ${model.name || model.modelName}`);
+      console.log(`    Parameters: ${((model.parameters || 0) / 1e6).toFixed(0)}M`);
+      console.log(`    Size: ${model.downloadSize || "N/A"}`);
+      console.log(`    Capabilities: ${model.capabilities?.join(", ") || "N/A"}`);
+      console.log("");
+    });
+  } catch (e) {
+    console.error(`> Failed to list models:`, e);
+  }
+}
+async function cortexInit(model) {
+  const modelId = model || "smollm2-135m";
+  console.log(`> Initializing Cortex with model: ${modelId}...`);
+  try {
+    const res = await fetch(`${API_URL}/cortex/init`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: modelId })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`> Cortex Initialized!`);
+    console.log(`> Instance ID: \x1B[32m${data.cortexId || data.id}\x1B[0m`);
+    console.log(`> Model: ${data.model || modelId}`);
+    console.log(`> Status: ${data.status || "ready"}`);
+  } catch (e) {
+    console.error(`> Failed to initialize Cortex:`, e);
+  }
+}
 async function createAgent(persona) {
   const p = persona || "Default Persona";
   console.log(`> Creating Agent with persona: "${p}"...`);
@@ -86,6 +244,178 @@ async function createAgent(persona) {
     console.error(`> Failed to create agent:`, e);
   }
 }
+async function listAgents() {
+  console.log(`> Listing agents...`);
+  try {
+    const res = await fetch(`${API_URL}/agents`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    if (!data || data.length === 0) {
+      console.log(`> No agents found.`);
+      return;
+    }
+    console.log(`> Found ${data.length} agents:
+`);
+    data.forEach((agent, i) => {
+      console.log(`  ${i + 1}. \x1B[32m${agent.agentId}\x1B[0m`);
+      console.log(`     Persona: ${(agent.persona || "").substring(0, 50)}...`);
+      console.log(`     Mood: ${agent.mood || "unknown"}`);
+      console.log("");
+    });
+  } catch (e) {
+    console.error(`> Failed to list agents:`, e);
+  }
+}
+async function deleteAgent(agentId) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  console.log(`> Deleting Agent: ${agentId}...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}`, { method: "DELETE" });
+    if (!res.ok) throw new Error(res.statusText);
+    console.log(`> Agent \x1B[31mdeleted\x1B[0m: ${agentId}`);
+  } catch (e) {
+    console.error(`> Failed to delete agent:`, e);
+  }
+}
+async function agentState(agentId) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  console.log(`> Fetching state for Agent: ${agentId}...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/state`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`
+  Agent State:
+`);
+    console.log(`  Mood: \x1B[33m${data.stateMood || data.mood || "unknown"}\x1B[0m`);
+    if (data.stateInventory || data.inventory) {
+      const inv = data.stateInventory || data.inventory;
+      console.log(`  Inventory: ${inv.length > 0 ? inv.join(", ") : "(empty)"}`);
+    }
+    if (data.stateSkills || data.skills) {
+      console.log(`  Skills:`);
+      const skills = data.stateSkills || data.skills || {};
+      for (const [skill, level] of Object.entries(skills)) {
+        console.log(`    ${skill}: ${level}`);
+      }
+    }
+    if (data.stateRelationships || data.relationships) {
+      console.log(`  Relationships:`);
+      const rels = data.stateRelationships || data.relationships || {};
+      for (const [entity, value] of Object.entries(rels)) {
+        const indicator = value > 0 ? "\x1B[32m+" : "\x1B[31m";
+        console.log(`    ${entity}: ${indicator}${value}\x1B[0m`);
+      }
+    }
+  } catch (e) {
+    console.error(`> Failed to get agent state:`, e);
+  }
+}
+async function agentProcess(agentId, input) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  if (!input) {
+    console.error("Error: Input text required");
+    return;
+  }
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/process`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ inputText: input, context: { source: "cli" } })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`\x1B[32m${data.dialogue || data.response || "No response"}\x1B[0m`);
+    if (data.actions && data.actions.length > 0) {
+      console.log(`\x1B[2mActions: ${data.actions.map((a) => a.type).join(", ")}\x1B[0m`);
+    }
+  } catch (e) {
+    console.error(`> Error:`, e);
+  }
+}
+async function agentUpdate(agentId, updateArgs) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  const updates = {};
+  for (let i = 0; i < updateArgs.length; i++) {
+    if (updateArgs[i] === "--mood" && updateArgs[i + 1]) {
+      updates.mood = updateArgs[++i];
+    } else if (updateArgs[i] === "--inventory" && updateArgs[i + 1]) {
+      updates.inventory = updateArgs[++i].split(",");
+    }
+  }
+  if (Object.keys(updates).length === 0) {
+    console.error("Usage: forbocai agent update <id> --mood <mood> [--inventory <item1,item2>]");
+    return;
+  }
+  console.log(`> Updating Agent: ${agentId}...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/state`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ stateUpdate: updates })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    console.log(`> Agent updated!`);
+    for (const [key, value] of Object.entries(updates)) {
+      console.log(`  ${key}: ${value}`);
+    }
+  } catch (e) {
+    console.error(`> Failed to update agent:`, e);
+  }
+}
+async function chatWithAgent(agentId) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  console.log(`
+\x1B[36m\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\x1B[0m`);
+  console.log(`\x1B[36m\u2551  ForbocAI Agent Chat                   \u2551\x1B[0m`);
+  console.log(`\x1B[36m\u2551  Agent: ${agentId.substring(0, 28).padEnd(28)}  \u2551\x1B[0m`);
+  console.log(`\x1B[36m\u2551  Type 'exit' to quit                   \u2551\x1B[0m`);
+  console.log(`\x1B[36m\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\x1B[0m
+`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const promptUser = () => {
+    rl.question("\x1B[33m> You: \x1B[0m", async (input) => {
+      if (input.toLowerCase() === "exit" || input.toLowerCase() === "quit") {
+        console.log("\n> Disconnecting from agent...");
+        rl.close();
+        return;
+      }
+      try {
+        const res = await fetch(`${API_URL}/agents/${agentId}/process`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ inputText: input, context: { source: "cli" } })
+        });
+        if (!res.ok) throw new Error(res.statusText);
+        const data = await res.json();
+        console.log(`\x1B[32m> Agent: \x1B[0m${data.dialogue || data.response || "No response"}`);
+        if (data.actions && data.actions.length > 0) {
+          console.log(`\x1B[2m> Actions: ${data.actions.map((a) => a.type).join(", ")}\x1B[0m`);
+        }
+        console.log("");
+      } catch (e) {
+        console.error(`> Error: ${e}`);
+      }
+      promptUser();
+    });
+  };
+  promptUser();
+}
 async function exportSoul(agentId) {
   if (!agentId) {
     console.error("Error: Agent ID required");
@@ -128,12 +458,407 @@ async function importSoul(cid) {
     console.error(`> Failed to import soul:`, e);
   }
 }
+async function chatWithSoul(cid) {
+  if (!cid) {
+    console.error("Error: CID required");
+    return;
+  }
+  console.log(`> Waking Soul from cryo: ${cid}...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/import`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ cidRef: cid })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`> Soul awakened! Temporary Agent: ${data.agentId}`);
+    console.log(`> Persona: ${data.persona}
+`);
+    await chatWithAgent(data.agentId);
+  } catch (e) {
+    console.error(`> Failed to wake soul:`, e);
+  }
+}
+async function soulList() {
+  console.log(`> Listing exported Souls...`);
+  try {
+    console.log(`
+  Exported Souls:
+`);
+    console.log(`  (Soul listing requires local storage or API endpoint)`);
+    console.log(`  Use 'soul export <agentId>' to create a new Soul`);
+  } catch (e) {
+    console.error(`> Failed to list souls:`, e);
+  }
+}
+async function soulVerify(cid) {
+  if (!cid) {
+    console.error("Error: CID required");
+    return;
+  }
+  console.log(`> Verifying Soul: ${cid}...`);
+  try {
+    const res = await fetch(`${API_URL}/souls/${cid}`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`> Soul Verified!`);
+    console.log(`> Name: ${data.soulName}`);
+    console.log(`> DNA: ${(data.dna || "").substring(0, 50)}...`);
+    console.log(`> Signature: ${data.signature ? "\x1B[32m\u2713 Valid\x1B[0m" : "\x1B[33m\u25CB Not signed\x1B[0m"}`);
+  } catch (e) {
+    console.error(`> Failed to verify soul:`, e);
+  }
+}
+async function runGhost(suite) {
+  const testSuite = suite || "exploration";
+  console.log(`> Starting Ghost QA session...`);
+  console.log(`> Test Suite: ${testSuite}`);
+  try {
+    const res = await fetch(`${API_URL}/ghost/run`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ testSuite, duration: 300 })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`> Session Started!`);
+    console.log(`> Session ID: \x1B[36m${data.sessionId}\x1B[0m`);
+    console.log(`> Status: ${data.runStatus || "running"}`);
+    console.log(`
+> To check status: forbocai ghost status ${data.sessionId}`);
+    console.log(`> To get results:  forbocai ghost results ${data.sessionId}`);
+  } catch (e) {
+    console.error(`> Failed to start Ghost session:`, e);
+  }
+}
+async function ghostStatus(sessionId) {
+  if (!sessionId) {
+    console.error("Error: Session ID required");
+    return;
+  }
+  console.log(`> Checking Ghost session: ${sessionId}...`);
+  try {
+    const res = await fetch(`${API_URL}/ghost/${sessionId}/status`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    const statusColor = data.ghostStatus === "completed" ? "\x1B[32m" : data.ghostStatus === "failed" ? "\x1B[31m" : "\x1B[33m";
+    console.log(`> Status: ${statusColor}${(data.ghostStatus || "unknown").toUpperCase()}\x1B[0m`);
+    console.log(`> Progress: ${data.ghostProgress || 0}%`);
+    console.log(`> Duration: ${data.ghostDuration || 0}s`);
+    console.log(`> Errors: ${data.ghostErrors || 0}`);
+  } catch (e) {
+    console.error(`> Failed to get Ghost status:`, e);
+  }
+}
+async function ghostResults(sessionId) {
+  if (!sessionId) {
+    console.error("Error: Session ID required");
+    return;
+  }
+  console.log(`> Fetching Ghost results: ${sessionId}...`);
+  try {
+    const res = await fetch(`${API_URL}/ghost/${sessionId}/results`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557`);
+    console.log(`\u2551  Ghost QA Results                      \u2551`);
+    console.log(`\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+`);
+    const passRate = data.resultsTotalTests > 0 ? (data.resultsPassed / data.resultsTotalTests * 100).toFixed(1) : 0;
+    console.log(`  Total Tests: ${data.resultsTotalTests}`);
+    console.log(`  \x1B[32mPassed: ${data.resultsPassed}\x1B[0m`);
+    console.log(`  \x1B[31mFailed: ${data.resultsFailed}\x1B[0m`);
+    console.log(`  Pass Rate: ${passRate}%`);
+    console.log(`  Duration: ${data.resultsDuration}ms`);
+    console.log(`  Coverage: ${((data.resultsCoverage || 0) * 100).toFixed(1)}%`);
+    if (data.resultsMetrics) {
+      console.log(`
+  Metrics:`);
+      for (const [key, value] of data.resultsMetrics) {
+        console.log(`    ${key}: ${value}`);
+      }
+    }
+    if (data.resultsTests && data.resultsTests.length > 0) {
+      console.log(`
+  Tests:`);
+      data.resultsTests.forEach((test) => {
+        const icon = test.testPassed ? "\x1B[32m\u2713\x1B[0m" : "\x1B[31m\u2717\x1B[0m";
+        console.log(`    ${icon} ${test.testName} (${test.testDuration}ms)`);
+        if (test.testError) {
+          console.log(`      \x1B[31mError: ${test.testError}\x1B[0m`);
+        }
+      });
+    }
+  } catch (e) {
+    console.error(`> Failed to get Ghost results:`, e);
+  }
+}
+async function ghostStop(sessionId) {
+  if (!sessionId) {
+    console.error("Error: Session ID required");
+    return;
+  }
+  console.log(`> Stopping Ghost session: ${sessionId}...`);
+  console.log(`> Session stop requested (mock)`);
+  console.log(`> Status: \x1B[33mStopped\x1B[0m`);
+}
+async function ghostHistory() {
+  console.log(`> Fetching Ghost session history...`);
+  console.log(`
+  Recent Sessions:
+`);
+  console.log(`  (Session history requires persistent storage)`);
+  console.log(`  Use 'ghost run <suite>' to start a new session`);
+}
+async function memoryList(agentId) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  console.log(`> Listing memories for Agent: ${agentId}...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/memory`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    const memories = data.memories || data;
+    if (!memories || memories.length === 0) {
+      console.log(`> No memories found.`);
+      return;
+    }
+    console.log(`
+  Memories (${memories.length}):
+`);
+    memories.slice(0, 20).forEach((mem, i) => {
+      const importance = mem.importance || mem.memImportance || 0.5;
+      const bar = "\u2588".repeat(Math.floor(importance * 10));
+      console.log(`  ${i + 1}. [${bar.padEnd(10)}] ${(mem.text || mem.memText || "").substring(0, 50)}...`);
+    });
+    if (memories.length > 20) {
+      console.log(`
+  ... and ${memories.length - 20} more`);
+    }
+  } catch (e) {
+    console.error(`> Failed to list memories:`, e);
+  }
+}
+async function memoryRecall(agentId, query) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  if (!query) {
+    console.error("Error: Query required");
+    return;
+  }
+  console.log(`> Recalling memories for: "${query}"...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/memory/recall`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ recallQuery: query, recallLimit: 5 })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    const memories = data.recalledMemories || data;
+    if (!memories || memories.length === 0) {
+      console.log(`> No relevant memories found.`);
+      return;
+    }
+    console.log(`
+  Relevant Memories:
+`);
+    memories.forEach((mem, i) => {
+      const score = mem.score || mem.relevance || "?";
+      console.log(`  ${i + 1}. [Score: ${score}] ${(mem.text || mem.memText || "").substring(0, 60)}...`);
+    });
+  } catch (e) {
+    console.error(`> Failed to recall memories:`, e);
+  }
+}
+async function memoryStore(agentId, text) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  if (!text) {
+    console.error("Error: Memory text required");
+    return;
+  }
+  console.log(`> Storing memory...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/memory`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ storeText: text, storeType: "observation" })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    console.log(`> Memory stored!`);
+    console.log(`> ID: ${data.storedId || data.id}`);
+  } catch (e) {
+    console.error(`> Failed to store memory:`, e);
+  }
+}
+async function memoryClear(agentId) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  console.log(`> Clearing memories for Agent: ${agentId}...`);
+  console.log(`> \x1B[31mThis action cannot be undone!\x1B[0m`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question('Type "CONFIRM" to proceed: ', async (answer) => {
+    if (answer !== "CONFIRM") {
+      console.log("> Aborted.");
+      rl.close();
+      return;
+    }
+    try {
+      console.log(`> Memories cleared (mock)`);
+    } catch (e) {
+      console.error(`> Failed to clear memories:`, e);
+    }
+    rl.close();
+  });
+}
+async function memoryExport(agentId) {
+  if (!agentId) {
+    console.error("Error: Agent ID required");
+    return;
+  }
+  console.log(`> Exporting memories for Agent: ${agentId}...`);
+  try {
+    const res = await fetch(`${API_URL}/agents/${agentId}/memory`);
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    const filename = `memories_${agentId}_${Date.now()}.json`;
+    fs.writeFileSync(filename, JSON.stringify(data, null, 2));
+    console.log(`> Memories exported to: ${filename}`);
+  } catch (e) {
+    console.error(`> Failed to export memories:`, e);
+  }
+}
+async function bridgeValidate(actionFile) {
+  if (!actionFile) {
+    console.error("Error: Action file (JSON) required");
+    return;
+  }
+  console.log(`> Validating action from: ${actionFile}...`);
+  try {
+    const actionJson = fs.readFileSync(actionFile, "utf-8");
+    const action = JSON.parse(actionJson);
+    const res = await fetch(`${API_URL}/bridge/validate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ validateAction: action })
+    });
+    if (!res.ok) throw new Error(res.statusText);
+    const data = await res.json();
+    if (data.validationIsValid || data.valid) {
+      console.log(`> \x1B[32m\u2713 Action is VALID\x1B[0m`);
+    } else {
+      console.log(`> \x1B[31m\u2717 Action is INVALID\x1B[0m`);
+      console.log(`> Reason: ${data.validationReason || data.reason}`);
+    }
+  } catch (e) {
+    console.error(`> Failed to validate action:`, e);
+  }
+}
+async function bridgeRules() {
+  console.log(`> Fetching validation rules...`);
+  console.log(`
+  Built-in Rules:
+`);
+  console.log(`  \x1B[36mcore.movement\x1B[0m`);
+  console.log(`    Actions: MOVE, WALK, RUN`);
+  console.log(`    Validates: Coordinates, world bounds`);
+  console.log("");
+  console.log(`  \x1B[36mcore.attack\x1B[0m`);
+  console.log(`    Actions: ATTACK, HIT, STRIKE`);
+  console.log(`    Validates: Target exists`);
+  console.log("");
+  console.log(`  \x1B[36mcore.interact\x1B[0m`);
+  console.log(`    Actions: INTERACT, USE, PICKUP`);
+  console.log(`    Validates: Object specified`);
+  console.log("");
+  console.log(`  \x1B[36mcore.speak\x1B[0m`);
+  console.log(`    Actions: SPEAK, SAY, SHOUT`);
+  console.log(`    Validates: Text not empty`);
+  console.log("");
+  console.log(`  \x1B[36mcore.resources\x1B[0m`);
+  console.log(`    Actions: (all)`);
+  console.log(`    Validates: HP > 0, sufficient mana`);
+}
 function printUsage() {
-  console.log("Usage:");
-  console.log("  forbocai api status");
-  console.log("  forbocai agent create [<persona>]");
-  console.log("  forbocai soul export <agentId>");
-  console.log("  forbocai soul import <cid>");
-  console.log("\nEnvironment:");
-  console.log("  FORBOC_API_URL  Override API URL (default: render)");
+  console.log(`
+\x1B[36m\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551  ForbocAI CLI v${VERSION}                   \u2551
+\u2551  The Neuro-Symbolic Grid Interface     \u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\x1B[0m
+
+\x1B[1mUsage:\x1B[0m
+  forbocai <command> <subcommand> [options]
+
+\x1B[1mMeta:\x1B[0m
+  version                 Show SDK version
+  doctor                  Diagnose SDK/API issues
+
+\x1B[1mConfig:\x1B[0m
+  config set <k> <v>      Set configuration value
+  config get <key>        Get configuration value
+  config list             List all configuration
+
+\x1B[1mAPI:\x1B[0m
+  api status              Check API connection
+
+\x1B[1mCortex:\x1B[0m
+  cortex models           List available SLM models
+  cortex init [model]     Initialize Cortex with model
+
+\x1B[1mAgent:\x1B[0m
+  agent create [persona]  Create a new agent
+  agent list              List all agents
+  agent chat <id>         Interactive chat with agent
+  agent state <id>        View agent's current state
+  agent process <id> <t>  One-shot process input
+  agent update <id> ...   Update agent state
+  agent delete <id>       Delete an agent
+
+\x1B[1mMemory:\x1B[0m
+  memory list <agentId>   List agent's memories
+  memory recall <id> <q>  Semantic search memories
+  memory store <id> <t>   Store new observation
+  memory clear <id>       Clear all memories
+  memory export <id>      Export memories to JSON
+
+\x1B[1mBridge:\x1B[0m
+  bridge validate <file>  Validate action JSON
+  bridge rules            List validation rules
+
+\x1B[1mSoul:\x1B[0m
+  soul export <agentId>   Export agent to IPFS
+  soul import <cid>       Import agent from IPFS
+  soul chat <cid>         Wake and chat with Soul
+  soul list               List exported Souls
+  soul verify <cid>       Verify Soul signature
+
+\x1B[1mGhost:\x1B[0m
+  ghost run [suite]       Start QA test session
+  ghost status <id>       Check session progress
+  ghost results <id>      Get test results
+  ghost stop <id>         Stop running session
+  ghost history           List past sessions
+
+\x1B[1mEnvironment:\x1B[0m
+  FORBOC_API_URL          Override API URL
+
+\x1B[1mExamples:\x1B[0m
+  forbocai api status
+  forbocai agent create "A wise wizard"
+  forbocai agent chat agent_abc123
+  forbocai memory recall agent_abc123 "battle"
+  forbocai ghost run combat
+`);
 }