Architecture

Architecture Overview

Cognitive Workbench is a pure-Python Zenoh-based stack for LLM cognitive architecture research. The system prioritizes inspectable agent behavior and fast iteration over stability.

Core Components

Launcher (launcher.py)

Orchestrates one or more character instances defined in scenario YAML files under scenarios/. Each character runs as an independent process with its own executive node.

Executive Node (executive_node.py)

Implements the OODA loop (Observe, Orient, Decide, Act) for each character:

• Observe: Collects current situation and sense data
• Orient: Assesses current state and goals
• Decide: Chooses next action via incremental planning
• Act: Executes the chosen action

Incremental Planner (incremental_planner.py)

Interleaves reasoning and tool execution using SGLang's structured generation. The planner:

• Maintains a tool catalog (world tools + core infospace tools)
• Generates plans step-by-step with reflection
• Executes tools and observes results before deciding next steps
• Uses SGLang's KV caching to avoid re-tokenizing large prefixes

Infospace Executor (infospace_executor.py)

Central execution engine that:

• Executes primitives (save, load, create, index, search, etc.)
• Executes Python tools (from src/tools/ and src/world-tools/<world_name>/)
• Manages plan-local bindings (plan_bindings stack)
• Maintains persistent world_state for world integrations
• Publishes action results to Zenoh for UI/logging

Resource Manager (infospace_resource_manager.py)

Manages persistent Notes and Collections:

• Creates and stores Notes (text documents)
• Creates and manages Collections (sets of Notes)
• Handles vector indexing (FAISS) for semantic search
• Persists resources to scenarios/<world_name>/resources/

FastAPI UI (fastapi_action_display.py)

Web dashboard for visualizing agent behavior:

• Displays plans, actions, and results in real-time
• Shows world state (State tab)
• Provides character management and control
• Uses WebSockets for live updates

Data Flow

Launcher
  └─> Executive Node (per character)
       ├─> Incremental Planner (SGLang)
       │    └─> Tool Catalog (world + core)
       │
       ├─> Infospace Executor
       │    ├─> Execute primitives
       │    ├─> Execute Python tools
       │    └─> Manage world_state
       │
       └─> Resource Manager
            ├─> Notes & Collections
            └─> Vector indexes

Communication (Zenoh)

All components communicate via Zenoh topics:

• cognitive/{character}/action - Action results
• cognitive/{character}/planning/plan_log - Plan execution logs
• cognitive/{character}/world_state - World state updates
• cognitive/{character}/control/* - Control commands (step, run, stop)

World Integrations

World-specific functionality is loaded per character via world_config.world_name:

• Tools loaded from src/world-tools/<world_name>/
• Resources stored in scenarios/<world_name>/resources/
• world_state initialized from world_config.state JSON
• init tool auto-executed on executor startup (if present)

Key Design Principles

1. Inspectability: All actions logged, world state visible in UI
2. Modularity: World tools isolated from core infospace primitives
3. Persistence: Notes, Collections, and world state survive across plans
4. Incremental Planning: Interleaved reasoning and execution (not pure planning)
5. Uniform Returns: All tools return consistent format via _create_uniform_return()