Skip to navigation
Getting Started

Installation

Package selection and runtime setup
View as Markdown

Choose Packages

# Node runtime + CLI
npm install @forbocai/node
# Browser runtime slices/thunks
npm install @forbocai/browser
# Core protocol/state/thunks only
npm install @forbocai/core

The legacy unscoped forbocai package is a thin redirect to @forbocai/core. New consumers should use the scoped packages directly.

Export Matrix

Export@forbocai/core@forbocai/node@forbocai/browser
createSDKStoreYesYes (extended)Yes (extended)
setNPCInfo, processNPC, updateNPCStateYes——
Protocol thunks (directive, context, verdict)Yes——
Remote memory thunksYes——
Bridge / Soul / Ghost thunksYes——
RTK Query API slice (sdkApi)Yes——
Functional core (Maybe, Either, pipe, curry)Yes——
createNodeCortex + Node cortex slice—Yes—
Node memory slice (LanceDB)—Yes—
Node vector slice—Yes—
CLI binary (forbocai)—Yes—
Native deps tooling (checkNativeDeps, setupNativeDeps)—Yes—
Browser cortex thunks (WebLLM)——Yes
Browser memory slice (Orama)——Yes
Browser vector slice——Yes

@forbocai/node and @forbocai/browser both depend on @forbocai/core. Install the environment-specific package and you get core automatically.

Requirements

  • Node.js 20+
  • For @forbocai/node: native build toolchain for node-llama-cpp (C++ compiler, CMake)
  • For @forbocai/browser: WebGPU-capable browser for WebLLM

Environment-Specific Gotchas

Concern@forbocai/node@forbocai/browser
Vector DBLanceDB (file-based, persists to disk)Orama (in-memory, ephemeral per session)
Cortex enginenode-llama-cpp (GGUF models, CPU/GPU)WebLLM (WebGPU, browser tab)
Model downloadAutomatic on first use via HTTPAutomatic on first use via WebLLM cache
Memory persistenceSurvives process restarts (LanceDB on disk)Lost on tab close (Orama in-memory)
CLInpx forbocai <command>N/A
Native depsRequires C++ toolchain for node-llama-cppNo native deps

API Configuration

Node runtime config resolution:

  1. FORBOCAI_API_URL
  2. ~/.forbocai.json (apiUrl)
  3. fallback default: http://localhost:8080

API key resolution:

  1. FORBOCAI_API_KEY
  2. ~/.forbocai.json (apiKey)

Recommended for hosted API usage:

export FORBOCAI_API_URL=https://api.forboc.ai
export FORBOCAI_API_KEY=fb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Minimal Integration (Node)

import { createSDKStore, setNPCInfo, processNPC } from '@forbocai/core';
import { createNodeCortex } from '@forbocai/node';
const store = createSDKStore();
const cortex = createNodeCortex('smollm2-135m');
await cortex.init();
store.dispatch(setNPCInfo({ id: 'npc_demo', persona: 'A helpful guide' }));
await store.dispatch(processNPC({
  npcId: 'npc_demo',
  text: 'Hello there',
  apiUrl: process.env.FORBOCAI_API_URL || 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY,
  cortex
})).unwrap();

Verify via CLI

npx forbocai doctor
npx forbocai status