Language guide

What Cognia describes

Cognia describes the enduring substrate of a neural system rather than a single forward pass. The source answers five questions:

1. Which units exist and what state do they carry?
2. How are units grouped and connected?
3. Which values change connection strength or excitability?
4. How does the system learn, remember and compete for attention?
5. Which regions are visible as inputs, outputs or controller ports?

The source is declarative. Ordering declarations does not define an execution schedule unless a construct explicitly has temporal semantics, such as an edge delay or a runtime controller update.

Files and names

A file starts with a version pragma and may set a deterministic seed:

cognia "0.2";
seed 2026;

Keywords are contextual rather than globally reserved. Names are case-sensitive. A dotted endpoint such as vision.features.cells traverses instances and exposed ports.

Neurons and populations

A neuron defines a reusable unit type. Its state may include activation, leak, bias and gain. A population allocates arrays of those units:

neuron RateUnit {
    state {
        activation: float = 0.0;
        leak: float = 0.2;
        bias: float = 0.0;
        gain: float = 2.0;
    }
}

population Features {
    neurons { cells: RateUnit[32]; }
}

leak controls state persistence. gain scales normalized recurrent drive. In the present runtime, distinct leak values also determine visualization/runtime layer ordering: equal leak values are treated as one layer.

Neuron declarations can also describe stochastic firing with a probability expression. The runtime exposes both continuous activation and sampled firing state.

Circuits, modules and constructs

A circuit composes populations or nested circuits and connects their endpoints. A module adds cognition-oriented facilities such as ignition, memory, focus, growth and polarization. A construct is a reusable structural component with parameters and an explicit interface; learning policy intentionally belongs to the network using the construct, not to the construct itself.

Use the smallest abstraction that communicates intent:

• population for one homogeneous group;
• circuit for reusable connectivity;
• module for an attention, memory or polarized region;
• construct for parameterized reusable structure;
• network for an executable substrate;
• brain for composition of networks and channels.

Instantiation and interfaces

Reusable declarations are instantiated with use:

use Encoder as encoder;
use WorkingMemory as memory;

Nested internals should be exposed through declared ports. Endpoint resolution is checked semantically, including nested paths. Port widths and flow types must agree when binding or connecting components.

Connections

connect encoder.out -> memory.cells {
    pattern: random(0.25);
    weight: normal(0.0, 0.2);
    delay: 1;
    plasticity: none;
}

Connection patterns include full, local, one_to_one, broadcast, random and chain. A deterministic seed makes random expansion reproducible. Weight expressions can use constants, distributions and chemistry modulation. delay selects a previous source activation from a ring buffer; zero uses the fast current-state path.

Plasticity is per edge. Omitting plasticity means no runtime learning. Use an explicit none, fixed or frozen when immutability is important to the reader.

Sources and sensory regions

A source declares external data shape and kind. At runtime, sensory regions are ordered and packed at the beginning of the graph. The full Sensory application maps camera, audio and text cortex output to sensory regions by ordinal position, not by source name. The HTTP server accepts the already preprocessed raw sensory vector.

Chemistry

chemistry {
    dopamine: float = 1.0;
    acetylcholine: float = 1.0;
}

Chemistry values are global runtime modulators that relax toward baselines and may be driven by activity. Edge weights and plasticity rates can reference them. A chemistry-aware weight is compiled into a base term plus a modulator index, avoiding re-expanding graph structure each tick.

Chemistry is modulation, not an imperative scripting system. Event-driven chemistry declarations may validate even when a particular event path is not yet fired by the runtime; consult the limitations page.

Networks, competition and outputs

A network is the principal executable unit. It instantiates components, connects or binds endpoints, declares workspace competition and exposes outputs:

network Classifier {
    use Features as features;
    use Decision as decision;

    connect features.cells -> decision.cells {
        pattern: full;
        weight: normal(0.0, 0.1);
        plasticity: none;
    }

    output classification from decision.cells as class {
        vocab: "left", "right";
        loss: softmax_cross_entropy;
    }
}

Output types are signal, text and classification. Signal outputs apply host-side hysteresis in the stateful path. Text and classification outputs decode an argmax using their vocabulary; classification uses pre-activation logits for softmax training and inference.

Stateful execution

Recurrence means that an input does not uniquely determine an output; previous states matter. The runtime offers three useful modes:

• isolated evaluation: reset, load input, settle, return output;
• living-mind stepping: load a held input and advance workspace-aware ticks;
• raw sequence feeding: preserve recurrent and delayed state while advancing propagation without the full workspace loop.

Choose the mode before designing the dataset and metric. A model trained as a sequence reservoir should not be evaluated as independent rows.

Design advice

• Start from a checked-in example and preserve its evaluation path.
• Set seed whenever comparing architectures.
• Keep fixed reservoirs explicitly non-plastic and train only their readout.
• Use distinct train/test sequences, including unseen lengths for memory claims.
• Measure a mechanism against an otherwise identical ablation.
• Treat visualization as diagnosis, not evidence; publish numeric metrics and reproduction commands.