forbocai 0.2.0 → 0.3.0

package/README.md

@@ -78,6 +78,31 @@ npm install forbocai
 
 ---
 
+## CLI Reference
+
+`CLI_Tóols // Cómmand_Líne`
+
+The SDK includes a comprehensive CLI for managing your AI infrastructure.
+
+```bash
+# Agents
+npx forbocai agent create "A wise wizard"
+npx forbocai agent list
+npx forbocai agent chat <agentId>
+
+# Memory & Bridge
+npx forbocai memory recall <agentId> "battle"
+npx forbocai bridge validate action.json
+
+# System
+npx forbocai status
+npx forbocai doctor
+```
+
+See [full CLI documentation](https://forbocai.docs.buildwithfern.com/docs/pages/cli).
+
+---
+
 ## Quick Start
 
 `Quíck_Stárt // Éxample`

package/dist/index.d.mts

@@ -17,7 +17,7 @@ interface CortexStatus {
     id: string;
     model: string;
     ready: boolean;
-    engine: 'webballm' | 'mock' | 'remote';
+    engine: 'webllm' | 'mock' | 'remote';
 }
 interface CompletionOptions {
     temperature?: number;
@@ -107,7 +107,7 @@ interface ICortex {
  */
 declare const createCortex: (config: CortexConfig) => ICortex;
 /**
- * Pure function to generate completion text
+ * Pure function to generate completion text (Fallback/Mock)
  * Deterministic output for same input (functional principle)
  */
 declare const generateCompletion: (prompt: string, options: CompletionOptions, modelId: string) => string;
@@ -173,14 +173,14 @@ interface IMemory {
     recall(query: string, limit?: number): Promise<MemoryItem[]>;
     list(limit?: number, offset?: number): Promise<MemoryItem[]>;
     clear(): Promise<void>;
-    export(): MemoryItem[];
+    export(): Promise<MemoryItem[]>;
     import(memories: MemoryItem[]): Promise<void>;
 }
 /**
  * Configuration for the memory module
  */
 interface MemoryModuleConfig extends MemoryConfig {
-    /** Storage key for IndexedDB persistence */
+    /** Storage key/Database name for IndexedDB persistence */
     storageKey?: string;
     /** API URL for optional cloud sync */
     apiUrl?: string;
@@ -210,7 +210,7 @@ declare const rankMemoriesByRelevance: (memories: readonly MemoryItem[], query:
  */
 declare const createMemory: (config?: MemoryModuleConfig) => IMemory;
 /**
- * Mock Memory for testing
+ * Mock Memory for testing (In-Memory Fallback)
  */
 declare class MockMemory implements IMemory {
     private memories;
@@ -218,7 +218,7 @@ declare class MockMemory implements IMemory {
     recall(query: string, limit?: number): Promise<MemoryItem[]>;
     list(limit?: number, offset?: number): Promise<MemoryItem[]>;
     clear(): Promise<void>;
-    export(): MemoryItem[];
+    export(): Promise<MemoryItem[]>;
     import(memories: MemoryItem[]): Promise<void>;
 }
 
@@ -313,6 +313,8 @@ interface SoulExportConfig {
     includeMemories?: boolean;
     /** Sign with wallet (for NFT minting) */
     sign?: boolean;
+    /** Use local IPFS node (Helia) */
+    useLocalNode?: boolean;
 }
 /**
  * Soul export result
@@ -331,6 +333,8 @@ interface SoulImportConfig {
     apiUrl?: string;
     /** Verify signature before import */
     verifySignature?: boolean;
+    /** Use local IPFS node (Helia) */
+    useLocalNode?: boolean;
 }
 /**
  * Interface for Soul operations
@@ -359,11 +363,11 @@ declare const validateSoul: (soul: Soul) => {
     errors: string[];
 };
 /**
- * Export agent Soul to IPFS via API
+ * Export agent Soul to IPFS (Helia or API)
  */
 declare const exportSoulToIPFS: (agentId: string, soul: Soul, config?: SoulExportConfig) => Promise<SoulExportResult>;
 /**
- * Import Soul from IPFS by CID
+ * Import Soul from IPFS by CID (Helia or API)
  */
 declare const importSoulFromIPFS: (cid: string, config?: SoulImportConfig) => Promise<Soul>;
 /**

package/dist/index.d.ts

@@ -17,7 +17,7 @@ interface CortexStatus {
     id: string;
     model: string;
     ready: boolean;
-    engine: 'webballm' | 'mock' | 'remote';
+    engine: 'webllm' | 'mock' | 'remote';
 }
 interface CompletionOptions {
     temperature?: number;
@@ -107,7 +107,7 @@ interface ICortex {
  */
 declare const createCortex: (config: CortexConfig) => ICortex;
 /**
- * Pure function to generate completion text
+ * Pure function to generate completion text (Fallback/Mock)
  * Deterministic output for same input (functional principle)
  */
 declare const generateCompletion: (prompt: string, options: CompletionOptions, modelId: string) => string;
@@ -173,14 +173,14 @@ interface IMemory {
     recall(query: string, limit?: number): Promise<MemoryItem[]>;
     list(limit?: number, offset?: number): Promise<MemoryItem[]>;
     clear(): Promise<void>;
-    export(): MemoryItem[];
+    export(): Promise<MemoryItem[]>;
     import(memories: MemoryItem[]): Promise<void>;
 }
 /**
  * Configuration for the memory module
  */
 interface MemoryModuleConfig extends MemoryConfig {
-    /** Storage key for IndexedDB persistence */
+    /** Storage key/Database name for IndexedDB persistence */
     storageKey?: string;
     /** API URL for optional cloud sync */
     apiUrl?: string;
@@ -210,7 +210,7 @@ declare const rankMemoriesByRelevance: (memories: readonly MemoryItem[], query:
  */
 declare const createMemory: (config?: MemoryModuleConfig) => IMemory;
 /**
- * Mock Memory for testing
+ * Mock Memory for testing (In-Memory Fallback)
  */
 declare class MockMemory implements IMemory {
     private memories;
@@ -218,7 +218,7 @@ declare class MockMemory implements IMemory {
     recall(query: string, limit?: number): Promise<MemoryItem[]>;
     list(limit?: number, offset?: number): Promise<MemoryItem[]>;
     clear(): Promise<void>;
-    export(): MemoryItem[];
+    export(): Promise<MemoryItem[]>;
     import(memories: MemoryItem[]): Promise<void>;
 }
 
@@ -313,6 +313,8 @@ interface SoulExportConfig {
     includeMemories?: boolean;
     /** Sign with wallet (for NFT minting) */
     sign?: boolean;
+    /** Use local IPFS node (Helia) */
+    useLocalNode?: boolean;
 }
 /**
  * Soul export result
@@ -331,6 +333,8 @@ interface SoulImportConfig {
     apiUrl?: string;
     /** Verify signature before import */
     verifySignature?: boolean;
+    /** Use local IPFS node (Helia) */
+    useLocalNode?: boolean;
 }
 /**
  * Interface for Soul operations
@@ -359,11 +363,11 @@ declare const validateSoul: (soul: Soul) => {
     errors: string[];
 };
 /**
- * Export agent Soul to IPFS via API
+ * Export agent Soul to IPFS (Helia or API)
  */
 declare const exportSoulToIPFS: (agentId: string, soul: Soul, config?: SoulExportConfig) => Promise<SoulExportResult>;
 /**
- * Import Soul from IPFS by CID
+ * Import Soul from IPFS by CID (Helia or API)
  */
 declare const importSoulFromIPFS: (cid: string, config?: SoulImportConfig) => Promise<Soul>;
 /**

package/dist/index.js

@@ -65,14 +65,18 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/cortex.ts
+var import_web_llm = require("@mlc-ai/web-llm");
+var MODEL_CONFIG = {
+  "smollm2-135m": "HuggingFaceTB/SmolLM2-135M-Instruct-q4f16_1-MLC",
+  "llama3-8b": "Llama-3-8B-Instruct-q4f16_1-MLC",
+  "default": "HuggingFaceTB/SmolLM2-135M-Instruct-q4f16_1-MLC"
+};
 var createCortex = (config) => {
   return new WebLLMCortex(config);
 };
 var generateCompletion = (prompt, options, modelId) => {
-  const baseResponse = `Response to: ${prompt}`;
   const temperature = options.temperature ?? 0.7;
-  const maxTokens = options.maxTokens ?? 1024;
-  return baseResponse;
+  return `[Mock Response] Model: ${modelId}, Temp: ${temperature}. Response to: ${prompt}`;
 };
 var processObservationToDirective = (observation) => {
   return {
@@ -90,6 +94,7 @@ var generateActionFromDirective = (directive) => {
 var WebLLMCortex = class {
   constructor(config) {
     this.status = null;
+    this.engine = null;
     this.config = {
       ...config,
       temperature: config.temperature ?? 0.7,
@@ -101,53 +106,70 @@ var WebLLMCortex = class {
     if (this.status?.ready) {
       return this.status;
     }
-    const apiUrl = this.config.apiUrl || "http://localhost:8080";
     try {
-      const response = await fetch(`${apiUrl}/cortex/init`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          requestedModel: this.config.model,
-          authKey: this.config.authKey
-          // Send the key!
-        })
-      });
-      if (!response.ok) {
-        console.warn("Cortex Authorization Failed:", response.statusText);
-        throw new Error("Authorization Failed");
+      const isBrowser = typeof window !== "undefined";
+      if (isBrowser && this.config.gpu) {
+        console.log(`> Initializing WebLLM with model: ${this.config.model}`);
+        const selectedModel = MODEL_CONFIG[this.config.model] || MODEL_CONFIG["default"];
+        this.engine = await (0, import_web_llm.CreateMLCEngine)(selectedModel, {
+          initProgressCallback: (progress) => {
+            console.log(`> Model Loading: ${(progress.progress * 100).toFixed(1)}% - ${progress.text}`);
+          }
+        });
+        this.status = {
+          id: "webllm-" + Math.random().toString(36).substring(7),
+          model: this.config.model,
+          ready: true,
+          engine: "webllm"
+        };
+        return this.status;
+      } else {
+        console.warn("WebGPU unavailable (Node.js or disabled). Falling back to mock/API.");
+        throw new Error("WebGPU unavailable");
       }
-      const data = await response.json();
-      const newStatus = {
-        id: data.cortexId,
-        model: this.config.model,
-        ready: true,
-        engine: "webballm"
-      };
-      this.status = newStatus;
-      return newStatus;
     } catch (e) {
-      console.warn("Failed to connect to Neural Grid. Falling back to offline mode.");
-      const newStatus = {
+      console.warn("Using offline/mock mode due to initialization failure:", e);
+      this.status = {
         id: "offline-" + Math.random().toString(36).substring(7),
         model: this.config.model,
         ready: true,
         engine: "mock"
       };
-      this.status = newStatus;
-      return newStatus;
+      return this.status;
     }
   }
   async complete(prompt, options = {}) {
-    if (!this.status?.ready) {
-      throw new Error("Cortex not initialized");
+    if (!this.status?.ready) await this.init();
+    if (this.engine) {
+      const response = await this.engine.chat.completions.create({
+        messages: [{ role: "user", content: prompt }],
+        temperature: options.temperature ?? this.config.temperature,
+        max_tokens: options.maxTokens ?? this.config.maxTokens
+      });
+      return response.choices[0]?.message?.content || "";
+    } else {
+      return generateCompletion(prompt, options, this.config.model);
     }
-    const result = generateCompletion(prompt, options, this.config.model);
-    return result;
   }
   async *completeStream(prompt, options = {}) {
-    const result = await this.complete(prompt, options);
-    for (const char of result) {
-      yield char;
+    if (!this.status?.ready) await this.init();
+    if (this.engine) {
+      const stream = await this.engine.chat.completions.create({
+        messages: [{ role: "user", content: prompt }],
+        temperature: options.temperature ?? this.config.temperature,
+        max_tokens: options.maxTokens ?? this.config.maxTokens,
+        stream: true
+      });
+      for await (const chunk of stream) {
+        const content = chunk.choices[0]?.delta?.content || "";
+        if (content) yield content;
+      }
+    } else {
+      const result = generateCompletion(prompt, options, this.config.model);
+      for (const char of result) {
+        await new Promise((r) => setTimeout(r, 10));
+        yield char;
+      }
     }
   }
   async processObservation(observation) {
@@ -167,21 +189,24 @@ var MockCortex = class {
     };
   }
   async complete(prompt) {
-    return generateCompletion(prompt, {}, "mock-model");
+    return `Mock response to: ${prompt}`;
   }
   async *completeStream(prompt) {
-    yield `Mock streaming response to: ${prompt}`;
+    yield `Mock `;
+    yield `streaming `;
+    yield `response `;
+    yield `to: ${prompt}`;
   }
   async processObservation(observation) {
     return {
       type: "system-prompt",
-      content: "Mock processing of observation"
+      content: "Mock processing"
     };
   }
   async generateAction(directive) {
     return {
       type: "mock-action",
-      reason: "Mock action generation"
+      reason: "Mock action"
     };
   }
 };
@@ -300,6 +325,7 @@ var fromSoul = (soul, cortex) => {
 };
 
 // src/memory.ts
+var import_idb = require("idb");
 var createMemoryItem = (text, type = "observation", importance = 0.5) => {
   return {
     id: `mem_${Date.now()}_${Math.random().toString(36).substring(7)}`,
@@ -337,129 +363,128 @@ var rankMemoriesByRelevance = (memories, query, limit = 5) => {
   return scored.sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.memory);
 };
 var createMemory = (config = {}) => {
-  return new LocalMemory(config);
+  return new IndexedDBMemory(config);
 };
-var LocalMemory = class {
+var IndexedDBMemory = class {
   constructor(config) {
+    this.DB_NAME = "forbocai_db";
+    this.STORE_NAME = "memories";
     this.config = {
       decay: config.decay ?? "none",
       maxContextWindow: config.maxContextWindow ?? 10,
       storageKey: config.storageKey ?? "forbocai_memory",
       ...config
     };
-    this.memories = [];
-    this.loadFromStorage();
+    if (typeof window !== "undefined" && window.indexedDB) {
+      this.dbPromise = (0, import_idb.openDB)(this.config.storageKey || this.DB_NAME, 1, {
+        upgrade(db) {
+          if (!db.objectStoreNames.contains("memories")) {
+            const store = db.createObjectStore("memories", { keyPath: "id" });
+            store.createIndex("timestamp", "timestamp");
+            store.createIndex("agentId", "agentId");
+          }
+        }
+      });
+    } else {
+      console.warn("IndexedDB not available (Node.js environment). Falling back to in-memory.");
+      this.dbPromise = Promise.resolve({
+        getAll: async () => [],
+        put: async () => {
+        },
+        clear: async () => {
+        },
+        getAllFromIndex: async () => [],
+        transaction: () => ({ objectStore: () => ({ put: async () => {
+        } }), done: Promise.resolve() })
+      });
+    }
+  }
+  async getAllMemories() {
+    const db = await this.dbPromise;
+    try {
+      return await db.getAll(this.STORE_NAME) || [];
+    } catch {
+      return [];
+    }
   }
-  /**
-   * Store a new memory observation
-   */
   async store(text, type = "observation", importance = 0.5) {
     const memory = createMemoryItem(text, type, importance);
-    this.memories = [...this.memories, memory];
-    this.saveToStorage();
+    const db = await this.dbPromise;
+    try {
+      await db.put(this.STORE_NAME, memory);
+    } catch (e) {
+    }
     if (this.config.apiUrl && this.config.agentId) {
-      try {
-        await fetch(`${this.config.apiUrl}/agents/${this.config.agentId}/memory`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            observation: text,
-            importance
-          })
-        });
-      } catch (e) {
-        console.warn("Failed to sync memory to API:", e);
-      }
+      this.syncToApi(text, importance).catch(() => {
+      });
     }
     return memory;
   }
-  /**
-   * Recall memories relevant to a query (semantic search)
-   */
+  async syncToApi(text, importance) {
+    try {
+      await fetch(`${this.config.apiUrl}/agents/${this.config.agentId}/memory`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ observation: text, importance })
+      });
+    } catch (e) {
+    }
+  }
   async recall(query, limit = 5) {
-    let processedMemories = this.memories;
+    let memories = await this.getAllMemories();
     if (this.config.decay === "temporal") {
       const now = Date.now();
-      processedMemories = this.memories.map(
-        (mem) => applyTemporalDecay(mem, now)
-      );
+      memories = memories.map((mem) => applyTemporalDecay(mem, now));
     }
-    const results = rankMemoriesByRelevance(
-      processedMemories,
-      query,
-      limit
-    );
+    const results = rankMemoriesByRelevance(memories, query, limit);
     if (this.config.apiUrl && this.config.agentId) {
       try {
-        const response = await fetch(
-          `${this.config.apiUrl}/agents/${this.config.agentId}/memory/recall`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ query, similarity: 0.5 })
-          }
-        );
-        if (response.ok) {
-          const apiMemories = await response.json();
-          return [...results, ...apiMemories.slice(0, limit - results.length)];
-        }
+        const apiResults = await this.recallFromApi(query);
+        return [...results, ...apiResults.slice(0, limit - results.length)];
       } catch (e) {
-        console.warn("Failed to recall from API:", e);
       }
     }
     return results;
   }
-  /**
-   * List all memories (paginated)
-   */
+  async recallFromApi(query) {
+    const response = await fetch(
+      `${this.config.apiUrl}/agents/${this.config.agentId}/memory/recall`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ query, similarity: 0.5 })
+      }
+    );
+    if (response.ok) return await response.json();
+    return [];
+  }
   async list(limit = 50, offset = 0) {
-    return this.memories.slice(offset, offset + limit).map((m) => ({ ...m }));
+    const db = await this.dbPromise;
+    try {
+      const all = await db.getAllFromIndex(this.STORE_NAME, "timestamp");
+      return all.reverse().slice(offset, offset + limit);
+    } catch {
+      return [];
+    }
   }
-  /**
-   * Clear all memories
-   */
   async clear() {
-    this.memories = [];
-    this.saveToStorage();
-  }
-  /**
-   * Export all memories for backup/portability
-   */
-  export() {
-    return this.memories.map((m) => ({ ...m }));
-  }
-  /**
-   * Import memories (e.g., from Soul)
-   */
-  async import(memories) {
-    const existingIds = new Set(this.memories.map((m) => m.id));
-    const newMemories = memories.filter((m) => !existingIds.has(m.id));
-    this.memories = [...this.memories, ...newMemories];
-    this.saveToStorage();
-  }
-  /**
-   * Load memories from localStorage (browser) or skip (Node)
-   */
-  loadFromStorage() {
-    if (typeof window === "undefined" || !window.localStorage) return;
+    const db = await this.dbPromise;
     try {
-      const stored = localStorage.getItem(this.config.storageKey);
-      if (stored) {
-        this.memories = JSON.parse(stored);
-      }
-    } catch (e) {
-      console.warn("Failed to load memories from storage:", e);
+      await db.clear(this.STORE_NAME);
+    } catch {
     }
   }
-  /**
-   * Save memories to localStorage (browser) or skip (Node)
-   */
-  saveToStorage() {
-    if (typeof window === "undefined" || !window.localStorage) return;
+  async export() {
+    return this.getAllMemories();
+  }
+  async import(memories) {
+    const db = await this.dbPromise;
     try {
-      localStorage.setItem(this.config.storageKey, JSON.stringify(this.memories));
-    } catch (e) {
-      console.warn("Failed to save memories to storage:", e);
+      const tx = db.transaction(this.STORE_NAME, "readwrite");
+      const store = tx.objectStore(this.STORE_NAME);
+      for (const mem of memories) await store.put(mem);
+      await tx.done;
+    } catch {
     }
   }
 };
@@ -481,7 +506,7 @@ var MockMemory = class {
   async clear() {
     this.memories = [];
   }
-  export() {
+  async export() {
     return [...this.memories];
   }
   async import(memories) {
@@ -780,6 +805,24 @@ var validateAction = (action, rules, context = {}) => {
 };
 
 // src/soul.ts
+var import_helia = require("helia");
+var import_json = require("@helia/json");
+var import_blockstore_core = require("blockstore-core");
+var heliaNode = null;
+var heliaJson = null;
+var getHelia = async () => {
+  if (heliaNode) return { node: heliaNode, j: heliaJson };
+  try {
+    const blockstore = new import_blockstore_core.MemoryBlockstore();
+    heliaNode = await (0, import_helia.createHelia)({ blockstore });
+    heliaJson = (0, import_json.json)(heliaNode);
+    console.log("> Helia IPFS Node Initialized:", heliaNode.libp2p.peerId.toString());
+    return { node: heliaNode, j: heliaJson };
+  } catch (e) {
+    console.warn("Failed to init Helia (IPFS):", e);
+    return null;
+  }
+};
 var createSoul = (id, name, persona, state, memories = []) => {
   return {
     id,
@@ -793,8 +836,8 @@ var createSoul = (id, name, persona, state, memories = []) => {
 var serializeSoul = (soul) => {
   return JSON.stringify(soul, null, 2);
 };
-var deserializeSoul = (json) => {
-  const parsed = JSON.parse(json);
+var deserializeSoul = (json2) => {
+  const parsed = JSON.parse(json2);
   if (!parsed.id || !parsed.persona || !parsed.state) {
     throw new Error("Invalid Soul format: missing required fields");
   }
@@ -820,6 +863,21 @@ var validateSoul = (soul) => {
   };
 };
 var exportSoulToIPFS = async (agentId, soul, config = {}) => {
+  if (config.useLocalNode !== false) {
+    const helia = await getHelia();
+    if (helia) {
+      try {
+        const cid = await helia.j.add(soul);
+        return {
+          cid: cid.toString(),
+          ipfsUrl: `ipfs://${cid.toString()}`,
+          soul
+        };
+      } catch (e) {
+        console.warn("Helia add failed, falling back to API", e);
+      }
+    }
+  }
   const apiUrl = config.apiUrl || "https://forbocai-api.onrender.com";
   try {
     const response = await fetch(`${apiUrl}/agents/${agentId}/soul/export`, {
@@ -847,6 +905,14 @@ var exportSoulToIPFS = async (agentId, soul, config = {}) => {
   }
 };
 var importSoulFromIPFS = async (cid, config = {}) => {
+  if (config.useLocalNode !== false) {
+    const helia = await getHelia();
+    if (helia) {
+      try {
+      } catch (e) {
+      }
+    }
+  }
   const apiUrl = config.apiUrl || "https://forbocai-api.onrender.com";
   try {
     const response = await fetch(`${apiUrl}/souls/${cid}`, {
@@ -862,7 +928,6 @@ var importSoulFromIPFS = async (cid, config = {}) => {
       version: "1.0.0",
       name: data.soulName,
       persona: data.dna,
-      // DNA contains the persona
       state: { mood: "neutral", inventory: [], skills: {}, relationships: {} },
       memories: []
     };

package/dist/index.mjs

@@ -1,12 +1,16 @@
 // src/cortex.ts
+import { CreateMLCEngine } from "@mlc-ai/web-llm";
+var MODEL_CONFIG = {
+  "smollm2-135m": "HuggingFaceTB/SmolLM2-135M-Instruct-q4f16_1-MLC",
+  "llama3-8b": "Llama-3-8B-Instruct-q4f16_1-MLC",
+  "default": "HuggingFaceTB/SmolLM2-135M-Instruct-q4f16_1-MLC"
+};
 var createCortex = (config) => {
   return new WebLLMCortex(config);
 };
 var generateCompletion = (prompt, options, modelId) => {
-  const baseResponse = `Response to: ${prompt}`;
   const temperature = options.temperature ?? 0.7;
-  const maxTokens = options.maxTokens ?? 1024;
-  return baseResponse;
+  return `[Mock Response] Model: ${modelId}, Temp: ${temperature}. Response to: ${prompt}`;
 };
 var processObservationToDirective = (observation) => {
   return {
@@ -24,6 +28,7 @@ var generateActionFromDirective = (directive) => {
 var WebLLMCortex = class {
   constructor(config) {
     this.status = null;
+    this.engine = null;
     this.config = {
       ...config,
       temperature: config.temperature ?? 0.7,
@@ -35,53 +40,70 @@ var WebLLMCortex = class {
     if (this.status?.ready) {
       return this.status;
     }
-    const apiUrl = this.config.apiUrl || "http://localhost:8080";
     try {
-      const response = await fetch(`${apiUrl}/cortex/init`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          requestedModel: this.config.model,
-          authKey: this.config.authKey
-          // Send the key!
-        })
-      });
-      if (!response.ok) {
-        console.warn("Cortex Authorization Failed:", response.statusText);
-        throw new Error("Authorization Failed");
+      const isBrowser = typeof window !== "undefined";
+      if (isBrowser && this.config.gpu) {
+        console.log(`> Initializing WebLLM with model: ${this.config.model}`);
+        const selectedModel = MODEL_CONFIG[this.config.model] || MODEL_CONFIG["default"];
+        this.engine = await CreateMLCEngine(selectedModel, {
+          initProgressCallback: (progress) => {
+            console.log(`> Model Loading: ${(progress.progress * 100).toFixed(1)}% - ${progress.text}`);
+          }
+        });
+        this.status = {
+          id: "webllm-" + Math.random().toString(36).substring(7),
+          model: this.config.model,
+          ready: true,
+          engine: "webllm"
+        };
+        return this.status;
+      } else {
+        console.warn("WebGPU unavailable (Node.js or disabled). Falling back to mock/API.");
+        throw new Error("WebGPU unavailable");
       }
-      const data = await response.json();
-      const newStatus = {
-        id: data.cortexId,
-        model: this.config.model,
-        ready: true,
-        engine: "webballm"
-      };
-      this.status = newStatus;
-      return newStatus;
     } catch (e) {
-      console.warn("Failed to connect to Neural Grid. Falling back to offline mode.");
-      const newStatus = {
+      console.warn("Using offline/mock mode due to initialization failure:", e);
+      this.status = {
         id: "offline-" + Math.random().toString(36).substring(7),
         model: this.config.model,
         ready: true,
         engine: "mock"
       };
-      this.status = newStatus;
-      return newStatus;
+      return this.status;
     }
   }
   async complete(prompt, options = {}) {
-    if (!this.status?.ready) {
-      throw new Error("Cortex not initialized");
+    if (!this.status?.ready) await this.init();
+    if (this.engine) {
+      const response = await this.engine.chat.completions.create({
+        messages: [{ role: "user", content: prompt }],
+        temperature: options.temperature ?? this.config.temperature,
+        max_tokens: options.maxTokens ?? this.config.maxTokens
+      });
+      return response.choices[0]?.message?.content || "";
+    } else {
+      return generateCompletion(prompt, options, this.config.model);
     }
-    const result = generateCompletion(prompt, options, this.config.model);
-    return result;
   }
   async *completeStream(prompt, options = {}) {
-    const result = await this.complete(prompt, options);
-    for (const char of result) {
-      yield char;
+    if (!this.status?.ready) await this.init();
+    if (this.engine) {
+      const stream = await this.engine.chat.completions.create({
+        messages: [{ role: "user", content: prompt }],
+        temperature: options.temperature ?? this.config.temperature,
+        max_tokens: options.maxTokens ?? this.config.maxTokens,
+        stream: true
+      });
+      for await (const chunk of stream) {
+        const content = chunk.choices[0]?.delta?.content || "";
+        if (content) yield content;
+      }
+    } else {
+      const result = generateCompletion(prompt, options, this.config.model);
+      for (const char of result) {
+        await new Promise((r) => setTimeout(r, 10));
+        yield char;
+      }
     }
   }
   async processObservation(observation) {
@@ -101,21 +123,24 @@ var MockCortex = class {
     };
   }
   async complete(prompt) {
-    return generateCompletion(prompt, {}, "mock-model");
+    return `Mock response to: ${prompt}`;
   }
   async *completeStream(prompt) {
-    yield `Mock streaming response to: ${prompt}`;
+    yield `Mock `;
+    yield `streaming `;
+    yield `response `;
+    yield `to: ${prompt}`;
   }
   async processObservation(observation) {
     return {
       type: "system-prompt",
-      content: "Mock processing of observation"
+      content: "Mock processing"
     };
   }
   async generateAction(directive) {
     return {
       type: "mock-action",
-      reason: "Mock action generation"
+      reason: "Mock action"
     };
   }
 };
@@ -234,6 +259,7 @@ var fromSoul = (soul, cortex) => {
 };
 
 // src/memory.ts
+import { openDB } from "idb";
 var createMemoryItem = (text, type = "observation", importance = 0.5) => {
   return {
     id: `mem_${Date.now()}_${Math.random().toString(36).substring(7)}`,
@@ -271,129 +297,128 @@ var rankMemoriesByRelevance = (memories, query, limit = 5) => {
   return scored.sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.memory);
 };
 var createMemory = (config = {}) => {
-  return new LocalMemory(config);
+  return new IndexedDBMemory(config);
 };
-var LocalMemory = class {
+var IndexedDBMemory = class {
   constructor(config) {
+    this.DB_NAME = "forbocai_db";
+    this.STORE_NAME = "memories";
     this.config = {
       decay: config.decay ?? "none",
       maxContextWindow: config.maxContextWindow ?? 10,
       storageKey: config.storageKey ?? "forbocai_memory",
       ...config
     };
-    this.memories = [];
-    this.loadFromStorage();
+    if (typeof window !== "undefined" && window.indexedDB) {
+      this.dbPromise = openDB(this.config.storageKey || this.DB_NAME, 1, {
+        upgrade(db) {
+          if (!db.objectStoreNames.contains("memories")) {
+            const store = db.createObjectStore("memories", { keyPath: "id" });
+            store.createIndex("timestamp", "timestamp");
+            store.createIndex("agentId", "agentId");
+          }
+        }
+      });
+    } else {
+      console.warn("IndexedDB not available (Node.js environment). Falling back to in-memory.");
+      this.dbPromise = Promise.resolve({
+        getAll: async () => [],
+        put: async () => {
+        },
+        clear: async () => {
+        },
+        getAllFromIndex: async () => [],
+        transaction: () => ({ objectStore: () => ({ put: async () => {
+        } }), done: Promise.resolve() })
+      });
+    }
+  }
+  async getAllMemories() {
+    const db = await this.dbPromise;
+    try {
+      return await db.getAll(this.STORE_NAME) || [];
+    } catch {
+      return [];
+    }
   }
-  /**
-   * Store a new memory observation
-   */
   async store(text, type = "observation", importance = 0.5) {
     const memory = createMemoryItem(text, type, importance);
-    this.memories = [...this.memories, memory];
-    this.saveToStorage();
+    const db = await this.dbPromise;
+    try {
+      await db.put(this.STORE_NAME, memory);
+    } catch (e) {
+    }
     if (this.config.apiUrl && this.config.agentId) {
-      try {
-        await fetch(`${this.config.apiUrl}/agents/${this.config.agentId}/memory`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            observation: text,
-            importance
-          })
-        });
-      } catch (e) {
-        console.warn("Failed to sync memory to API:", e);
-      }
+      this.syncToApi(text, importance).catch(() => {
+      });
     }
     return memory;
   }
-  /**
-   * Recall memories relevant to a query (semantic search)
-   */
+  async syncToApi(text, importance) {
+    try {
+      await fetch(`${this.config.apiUrl}/agents/${this.config.agentId}/memory`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ observation: text, importance })
+      });
+    } catch (e) {
+    }
+  }
   async recall(query, limit = 5) {
-    let processedMemories = this.memories;
+    let memories = await this.getAllMemories();
     if (this.config.decay === "temporal") {
       const now = Date.now();
-      processedMemories = this.memories.map(
-        (mem) => applyTemporalDecay(mem, now)
-      );
+      memories = memories.map((mem) => applyTemporalDecay(mem, now));
     }
-    const results = rankMemoriesByRelevance(
-      processedMemories,
-      query,
-      limit
-    );
+    const results = rankMemoriesByRelevance(memories, query, limit);
     if (this.config.apiUrl && this.config.agentId) {
       try {
-        const response = await fetch(
-          `${this.config.apiUrl}/agents/${this.config.agentId}/memory/recall`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ query, similarity: 0.5 })
-          }
-        );
-        if (response.ok) {
-          const apiMemories = await response.json();
-          return [...results, ...apiMemories.slice(0, limit - results.length)];
-        }
+        const apiResults = await this.recallFromApi(query);
+        return [...results, ...apiResults.slice(0, limit - results.length)];
       } catch (e) {
-        console.warn("Failed to recall from API:", e);
       }
     }
     return results;
   }
-  /**
-   * List all memories (paginated)
-   */
+  async recallFromApi(query) {
+    const response = await fetch(
+      `${this.config.apiUrl}/agents/${this.config.agentId}/memory/recall`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ query, similarity: 0.5 })
+      }
+    );
+    if (response.ok) return await response.json();
+    return [];
+  }
   async list(limit = 50, offset = 0) {
-    return this.memories.slice(offset, offset + limit).map((m) => ({ ...m }));
+    const db = await this.dbPromise;
+    try {
+      const all = await db.getAllFromIndex(this.STORE_NAME, "timestamp");
+      return all.reverse().slice(offset, offset + limit);
+    } catch {
+      return [];
+    }
   }
-  /**
-   * Clear all memories
-   */
   async clear() {
-    this.memories = [];
-    this.saveToStorage();
-  }
-  /**
-   * Export all memories for backup/portability
-   */
-  export() {
-    return this.memories.map((m) => ({ ...m }));
-  }
-  /**
-   * Import memories (e.g., from Soul)
-   */
-  async import(memories) {
-    const existingIds = new Set(this.memories.map((m) => m.id));
-    const newMemories = memories.filter((m) => !existingIds.has(m.id));
-    this.memories = [...this.memories, ...newMemories];
-    this.saveToStorage();
-  }
-  /**
-   * Load memories from localStorage (browser) or skip (Node)
-   */
-  loadFromStorage() {
-    if (typeof window === "undefined" || !window.localStorage) return;
+    const db = await this.dbPromise;
     try {
-      const stored = localStorage.getItem(this.config.storageKey);
-      if (stored) {
-        this.memories = JSON.parse(stored);
-      }
-    } catch (e) {
-      console.warn("Failed to load memories from storage:", e);
+      await db.clear(this.STORE_NAME);
+    } catch {
     }
   }
-  /**
-   * Save memories to localStorage (browser) or skip (Node)
-   */
-  saveToStorage() {
-    if (typeof window === "undefined" || !window.localStorage) return;
+  async export() {
+    return this.getAllMemories();
+  }
+  async import(memories) {
+    const db = await this.dbPromise;
     try {
-      localStorage.setItem(this.config.storageKey, JSON.stringify(this.memories));
-    } catch (e) {
-      console.warn("Failed to save memories to storage:", e);
+      const tx = db.transaction(this.STORE_NAME, "readwrite");
+      const store = tx.objectStore(this.STORE_NAME);
+      for (const mem of memories) await store.put(mem);
+      await tx.done;
+    } catch {
     }
   }
 };
@@ -415,7 +440,7 @@ var MockMemory = class {
   async clear() {
     this.memories = [];
   }
-  export() {
+  async export() {
     return [...this.memories];
   }
   async import(memories) {
@@ -714,6 +739,24 @@ var validateAction = (action, rules, context = {}) => {
 };
 
 // src/soul.ts
+import { createHelia } from "helia";
+import { json } from "@helia/json";
+import { MemoryBlockstore } from "blockstore-core";
+var heliaNode = null;
+var heliaJson = null;
+var getHelia = async () => {
+  if (heliaNode) return { node: heliaNode, j: heliaJson };
+  try {
+    const blockstore = new MemoryBlockstore();
+    heliaNode = await createHelia({ blockstore });
+    heliaJson = json(heliaNode);
+    console.log("> Helia IPFS Node Initialized:", heliaNode.libp2p.peerId.toString());
+    return { node: heliaNode, j: heliaJson };
+  } catch (e) {
+    console.warn("Failed to init Helia (IPFS):", e);
+    return null;
+  }
+};
 var createSoul = (id, name, persona, state, memories = []) => {
   return {
     id,
@@ -727,8 +770,8 @@ var createSoul = (id, name, persona, state, memories = []) => {
 var serializeSoul = (soul) => {
   return JSON.stringify(soul, null, 2);
 };
-var deserializeSoul = (json) => {
-  const parsed = JSON.parse(json);
+var deserializeSoul = (json2) => {
+  const parsed = JSON.parse(json2);
   if (!parsed.id || !parsed.persona || !parsed.state) {
     throw new Error("Invalid Soul format: missing required fields");
   }
@@ -754,6 +797,21 @@ var validateSoul = (soul) => {
   };
 };
 var exportSoulToIPFS = async (agentId, soul, config = {}) => {
+  if (config.useLocalNode !== false) {
+    const helia = await getHelia();
+    if (helia) {
+      try {
+        const cid = await helia.j.add(soul);
+        return {
+          cid: cid.toString(),
+          ipfsUrl: `ipfs://${cid.toString()}`,
+          soul
+        };
+      } catch (e) {
+        console.warn("Helia add failed, falling back to API", e);
+      }
+    }
+  }
   const apiUrl = config.apiUrl || "https://forbocai-api.onrender.com";
   try {
     const response = await fetch(`${apiUrl}/agents/${agentId}/soul/export`, {
@@ -781,6 +839,14 @@ var exportSoulToIPFS = async (agentId, soul, config = {}) => {
   }
 };
 var importSoulFromIPFS = async (cid, config = {}) => {
+  if (config.useLocalNode !== false) {
+    const helia = await getHelia();
+    if (helia) {
+      try {
+      } catch (e) {
+      }
+    }
+  }
   const apiUrl = config.apiUrl || "https://forbocai-api.onrender.com";
   try {
     const response = await fetch(`${apiUrl}/souls/${cid}`, {
@@ -796,7 +862,6 @@ var importSoulFromIPFS = async (cid, config = {}) => {
       version: "1.0.0",
       name: data.soulName,
       persona: data.dna,
-      // DNA contains the persona
       state: { mood: "neutral", inventory: [], skills: {}, relationships: {} },
       memories: []
     };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "forbocai",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "The Infrastructure Layer for Autonomous AI Characters",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -16,15 +16,20 @@
         "postinstall": "node postinstall.js"
     },
     "dependencies": {
-        "@mlc-ai/web-llm": "^0.2.0",
-        "zod": "^3.22.4",
-        "axios": "^1.6.2"
+        "@helia/json": "^5.0.6",
+        "@mlc-ai/web-llm": "^0.2.80",
+        "axios": "^1.6.2",
+        "blockstore-core": "^6.1.2",
+        "datastore-core": "^11.0.2",
+        "helia": "^6.0.18",
+        "idb": "^8.0.3",
+        "zod": "^3.22.4"
     },
     "devDependencies": {
+        "@types/node": "^20.0.0",
         "tsup": "^8.5.1",
         "typescript": "^5.9.3",
-        "vitest": "^1.0.0",
-        "@types/node": "^20.0.0"
+        "vitest": "^1.0.0"
     },
     "files": [
         "dist",