Concepts

Cóncépts // Sýstém_Dóc

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

This document explains the core concepts and architecture of the ForbocAI SDK. Understanding these abstractions will help you design effective AI-powered NPCs for your games.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       Your Game                             │
├─────────────────────────────────────────────────────────────┤
│                      ForbocAI SDK                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Agent   │  │  Memory  │  │  Bridge  │  │   Soul   │    │
│  │          │◄─┤  (RAG)   │  │ (Neuro-  │  │ (Export/ │    │
│  │ Persona  │  │          │  │ Symbolic)│  │  Import) │    │
│  └────┬─────┘  └──────────┘  └────┬─────┘  └──────────┘    │
│       │                           │                          │
│       ▼                           ▼                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                      Cortex                           │   │
│  │           (Local SLM Inference Engine)                │   │
│  └──────────────────────────────────────────────────────┘   │
31: ├─────────────────────────────────────────────────────────────┤
│     Developer Runtime   │   Storage   │  IPFS Gateway       │
└─────────────────────────────────────────────────────────────┘

Cortex

The Cortex is the local-first inference engine. It runs quantized Small Language Models (SLMs) in your environment—no external API required.

Key Properties

• Zero Latency — No network round-trips; inference happens on-device
• Zero Cost — No API token fees; users provide their own compute
• Privacy-First — Prompts and responses never leave the device
• Offline-Capable — Works without internet after initial model download

Model Selection

The Cortex supports multiple quantized models. Smaller models are faster but less capable:

Agent

An Agent is an autonomous entity with a persona, state, and memory. Agents process inputs and produce structured outputs (dialogue + actions).

Agent Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CREATE    │────▶│   ACTIVE    │────▶│  EXPORTED   │
│  (Persona)  │     │ (Processing)│     │   (Soul)    │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       │                   ▼                   │
       │            ┌─────────────┐            │
       └───────────▶│  IMPORTED   │◀───────────┘
                    │ (from Soul) │
                    └─────────────┘

Agent State

An agent maintains internal state that influences its behavior:

1
interface AgentState {
2
  // Core attributes
3
  inventory: string[];
4
  skills: Record<string, number>;
5
  relationships: Record<string, number>;  // -100 to 100
6
  
7
  // Emotional state (influences dialogue tone)
8
  mood: 'hostile' | 'suspicious' | 'neutral' | 'friendly' | 'loyal';
9
  fear: number;      // 0-100
10
  confidence: number; // 0-100
11
  
12
  // Custom attributes (application-specific)
13
  [key: string]: unknown;
14
}

Processing Flow

When agent.process() is called:

1. Recall — Relevant memories are retrieved via semantic search
2. Prompt — System prompt + persona + memories + context + input are assembled
3. Generate — Cortex generates a structured response (dialogue + action)
4. Validate — Bridge validates the action against application rules
5. Update — Agent state is updated based on the interaction
6. Store — The interaction is stored as a new memory

Memory (RAG Pipeline)

The Memory system provides persistent, semantic recall for agents. It uses Retrieval-Augmented Generation (RAG) to inject relevant past events into the agent’s context.

How It Works

1. Observe — Events are converted to natural language descriptions
2. Embed — Text is converted to vectors using a local embedding model
3. Store — Vectors are persisted in IndexedDB
4. Recall — Semantic search finds relevant memories before generation

Memory Types

Memory Decay (Optional)

Memories can be configured to decay over time or with distance:

1
const agent = await Agent.create({
2
  memoryConfig: {
3
    decay: 'temporal',       // 'none' | 'temporal' | 'importance'
4
    decayRate: 0.01,         // Relevance reduces by 1%/day
5
    maxMemories: 1000        // Oldest memories pruned when exceeded
6
  }
7
});

Bridge (Neuro-Symbolic Validation)

The Bridge ensures AI-generated actions are valid within your application’s rules. It prevents hallucinations from breaking game state.

The Problem

LLMs can generate anything, including impossible actions:

1
{ "action": "EQUIP", "item": "legendary_sword" }
2
// But the agent doesn't have a legendary_sword!

The Solution

The Bridge validates actions before execution:

1
const bridge = new Bridge({
2
  rules: [
3
    // Built-in rule: can only equip owned items
4
    Bridge.rules.requireOwnership('EQUIP', 'inventory'),
5
    
6
    // Custom rule: no trading during combat
7
    (action, context) => {
8
      if (action.type === 'TRADE' && context.inCombat) {
9
        return { valid: false, reason: 'INVALID_DURING_COMBAT' };
10
      }
11
      return { valid: true };
12
    }
13
  ]
14
});

Validation Flow

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│   SLM   │────▶│ Parse   │────▶│ Bridge  │────▶│ Execute │
│ Output  │     │ Action  │     │ Validate│     │ or      │
│         │     │         │     │         │     │ Reject  │
└─────────┘     └─────────┘     └─────────┘     └─────────┘

Soul

A Soul is a portable snapshot of an agent’s complete being—its persona, memories, and state. Souls enable agents to persist across sessions or transfer between applications.

Soul Schema

1
interface Soul {
2
  // Identity
3
  id: string;
4
  version: string;
5
  createdAt: string;
6
  
7
  // Persona
8
  persona: string;
9
  baseModelWeights?: string;  // Optional LoRA CID
10
  
11
  // Memory
12
  memories: Array<{
13
    text: string;
14
    embedding: number[];
15
    timestamp: string;
16
    type: string;
17
  }>;
18
  
19
  // State
20
  state: AgentState;
21
  
22
  // Provenance (for verification)
23
  signature?: string;
24
  trainingProof?: string;  // ERC-7007 verification
25
}

Storage Options

Economy & Protocol (Solana)

The ForbocAI Protocol is built on Solana to enable a high-frequency, low-latency Asset Economy.

The $FAI Token

$FAI is the unified utility token for the entire ecosystem.

• Network: Solana (SPL Token)
• Contract: 7zwfQkkPv9aUF6VXA8CbZabJYpXCRJTYbQnjxjynpump
• Utility:
  1. Minting Souls: Spending $FAI to “birth” new agent NFTs.
  2. Inference Credits: Spending $FAI to buy API credits for the Cloud Brain (Logic Engine).
  3. Marketplace: The base currency for trading high-value Agents.

Metaplex Core (The Asset Standard)

We use Metaplex Core instead of legacy standards (like ERC-721) because it is designed for Applications, not just Art.

• Low Cost: Minting and updating assets costs fractions of a penny.
• Dynamic Data: Core assets have efficient plugin systems that allow us to update the “Memory Hash” of an agent frequently without incurring high gas fees.
• Zero Copy: The asset handles are lightweight, enabling games to check ownership of thousands of agents instantly.

Ghost Agents

Ghost Agents are headless AI instances that autonomously test your application. They run at accelerated speed to validate content, find bugs, and collect metrics.

Capabilities

• Exploration — Traverse levels to measure coverage and find dead-ends
• Dialogue Testing — Exercise conversation trees to find broken paths
• Balance Metrics — Collect time-to-kill, death rates, resource curves
• Regression Detection — Compare runs across builds to catch regressions

Example Usage

1
const results = await GhostAgent.run({
2
  level: 'dungeon_01',
3
  goal: 'maximize_exploration',
4
  timeout: 60_000,
5
  seed: 12345
6
});
7
8
console.log(results.explorationCoverage);  // 0.94 (94%)
9
console.log(results.deathCount);           // 2
10
console.log(results.deadEnds);             // []

Learn More

The ForbocAI SDK is built on functional programming principles. For a deeper understanding of the patterns used in this architecture: