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)

1import { createSDKStore, setNPCInfo, processNPC } from '@forbocai/core';
2import { createNodeCortex } from '@forbocai/node';
3
4const store = createSDKStore();
5const cortex = createNodeCortex('smollm2-135m');
6await cortex.init();
7
8store.dispatch(setNPCInfo({ id: 'npc_demo', persona: 'A helpful guide' }));
9
10await store.dispatch(processNPC({
11  npcId: 'npc_demo',
12  text: 'Hello there',
13  apiUrl: process.env.FORBOCAI_API_URL || 'https://api.forboc.ai',
14  apiKey: process.env.FORBOCAI_API_KEY,
15  cortex
16})).unwrap();

Verify via CLI

$npx forbocai doctor
$npx forbocai status