Nuillu

Build a lightweight cognitive agent that runs locally, inspired by Attention Schema Theory (AST).

Nuillu is pronounced like nu-illusion. In Japanese, ぬイリュージョン (nu-iryūjon). The name is a portmanteau of nu and illusion.

The agent is built as a small society of cooperating cognitive modules. The default runtime wiring currently includes sensory, cognition-gate, allocation, attention-schema, self-model, query-memory, memory, memory-compaction, memory-association, dreaming, interoception, homeostasis, policy, policy-compaction, reward, predict, surprise, and speak.

Modules cooperate through a non-cognitive blackboard, per-module memo logs, typed transient channels, and an admitted cognition log. The cognition-gate promotes selected memo/blackboard state into that cognitive surface; attention-schema may append concise first-person attention-experience entries; self-model integrates those attention entries with stable and current context in its own memo log. Durable module output is memo- or log-authoritative rather than request/response traffic.

Resource allocation is durable priority state rather than a wake path. Allocation wakes from memo updates and internal attention-control bids, then writes activation priorities for modules. Effective allocation controls active replicas and rate limiting. Homeostatic control can also drive or cap allocation from interoceptive state.

Two characteristics shape the implementation:

1. Multi-agent decomposition over readily available LLMs. Specialized cognitive roles are split across small, focused LLM calls instead of one large dedicated model.
2. Deterministic logic where LLMs should not be in the loop. Scheduling, ranking, decay, owner-stamped routing, and other state transitions are implemented as plain code, not LLM prompts.

Ideally, an agent of this shape would be a single large model with a purpose-built architecture and dedicated training. Developing and running that kind of model is not feasible for this project, so Nuillu approximates it under tighter constraints.

The multi-agent decomposition and the deterministic logic are therefore means, not ends. The end is a self-contained cognitive agent running on local hardware, and the project is an attempt to see what kinds of behavior, self-report, and adaptation fall out when such an agent has an explicit, shared model of its own attention instead of treating cognition as a single forward pass.

A proof-of-concept runtime is currently being built. Core crates, server/runtime wiring, eval tooling, and many built-in modules exist, but the project is still pre-alpha and APIs and behavior remain in flux. The design notes in docs/design/ are the source of truth for architectural intent. Nothing is published to crates.io.

The visualizer is the normal entry point; it starts the server runtime in-process.

cargo run -p nuillu-visualizer-egui-app -- --state <path to nuillu-exhibition>

nuillu-visualizer-egui is the embeddable egui library. Hosts feed it VisualizerServerMessage values with Visualizer::apply_server_message, call Visualizer::show(ui), and forward the returned VisualizerClientMessage values using their own transport.

Hosts can layer their FTL over the embedded fallback translations:

use nuillu_visualizer_egui::{Locale, Visualizer, VisualizerUiResources};

let resources = VisualizerUiResources::builder()
    .add_ftl(Locale::JaJp, include_str!("i18n/ja-JP/app.ftl"))
    .add_ftl(Locale::EnUs, include_str!("i18n/en-US/app.ftl"))
    .build()?;
let visualizer = Visualizer::with_resources(id, config, resources);

For each locale, user resources override the built-in include_str! resource; later calls to add_ftl have higher priority. Japanese then falls back to the combined English resources for keys that remain missing.

Hosts can also construct the menu bar and mix built-in controls with arbitrary egui widgets. Visualizer::show(ui) keeps the default menu bar.

let response = visualizer.show_with_menu_bar(ui, |ui, menu| {
    menu.tabs(ui);
    ui.separator();
    if ui.button("Host action").clicked() {
        menu.emit(VisualizerClientMessage::hello());
    }
    menu.view_menu(ui);
    menu.offered_actions(ui);
});

nuillu-server remains available for headless/runtime use and can be connected to by a visualizer with --host.

nuillu-eval evaluates and benchmarks any configured Nuillu agent, including nested subsystem topologies and host-provided modules. Cases, runtime-config overrides, assertions, timeline measurements, and multi-trial reports are documented in docs/eval.md.

Licensed under the Mozilla Public License, version 2.0 (MPL-2.0). See LICENSE for the full text.