Cadence

Website · Examples · Paper · PyPI · Documentation · Changelog

Research toward general intelligence through overlap consensus, equilibrium detuning and self-reflection.

Cadence's goal is a continuing learning system with the flexibility of animal and human problem solving: acquiring skills from experience, retaining useful knowledge, imagining alternatives and creating solutions across domains. The mission is to find the smallest persistent state and local update rule that can support these abilities. The building block stays as simple as possible, like in nature; every part of a brain answers with a settled state of that one rule; and where a choice appears, evolution across lives is preferred to design. General intelligence is the research goal; the current library establishes bounded learning, memory and control results.

The building block is a bounded, observer-like patch with local state, ports, records, readback and repair. A disturbance exposes disagreement. The network can explore a possible response, test it against actual consequences and settle into a revised organization. We seek fewer mechanisms that solve more problems.

The roadmap

We want to reach a point where we can effortlessly evolve a human-like brain, teach it first by imitation and then through its own life, and give it an experience identical to that of a human living in our world. Brains with capabilities far beyond ours are thinkable on the same path; human-level competence comes first, as a sensible milestone. The steps from the brains in this library to that milestone are tracked as issues in this repository, rung by rung, each with its task, its control and its falsifier.

In familiar terms

Cadence is a library for computation through local state, ports and repair, with NumPy implementations and optional accelerated backends. Its graph and temporal learners use free and nudged equilibrium contrasts. Record and belief models use causal or finite-iteration computations and train slow weights by an explicit adjoint backward scan. Record stores additionally learn by local writes. These are distinct implementations with different guarantees; the numerical and learning contracts explain how to choose and check them. A night of sleep can transfer a record store's completions into slow weights under its declared training procedure. Cadence for machine-learning people maps each brain to the model you know, says where each learning signal comes from, and lists the shapes and the words.

Get started

python -m pip install cadence-net     # Python 3.11+ and NumPy; torch, MLX and Numba are optional

Three brains, each trained in front of you in seconds from fixed seeds, with every neuron and synapse animated, the distance from equilibrium as a heat on the neurons, the last change on the synapses, the learning plotted as it is measured, and a line of text for each phase:

git clone https://github.com/muellerberndt/cadence-examples.git
cd cadence-examples
python -m quickstart.demo stream     # or: decide, body

Nothing is hosted and there is no checkpoint; the quickstarts in your browser says what equilibrium means in each brain and what detuning buys. The same three brains in Python are the quickstarts. This is the record patch: it hears a stream, recalls every outcome after one pass by day, and after a night with the stream closed says every outcome from its weights alone:

import numpy as np
from cadence import RecordPatchNet

rng = np.random.default_rng(21)
net = RecordPatchNet(
    12, 12, 5, seed=4, cells=2048, active=16, record_rate=1.0, groups=(5,), slowest=8.0
)
symbols = rng.integers(12, size=(3, 8))
heard = np.eye(12)[symbols]
outcome = np.eye(5)[(symbols + np.roll(symbols, 1, axis=1)) % 5]  # the last two symbols decide

for _ in range(8):  # the day: one write per moment, slow weights at rate zero
    net.reset()
    net.observe(heard, outcome, rate=0.0)
net.reset()
awake = net.imagine(heard, state=np.zeros((3, 12)))
assert np.array_equal(awake.output.argmax(-1), outcome.argmax(-1))  # the store recalls

night = net.sleep([heard], passes=240, rate=8.0, backtrack=True)  # dreams, then dawn
alone = RecordPatchNet.restore(net.snapshot())
alone.records.tables["y"][:] = 0.0  # the same weights with an empty store
assert np.array_equal(alone.imagine(heard, state=np.zeros((3, 12))).output.argmax(-1), outcome.argmax(-1))
print(night)

Build your own brain takes your own data to a trained, evaluated and saved brain of each kind, and troubleshooting answers the first questions.

Deep Recursive Settlement Networks

Deep Recursive Settlement Networks (DRSNs) place observing patches and the patches they observe in one equilibrium. Each observer reads current activity and sends feedback while all populations, including the answer neurons, keep settling together. Adding a level adds participants to the same computation; it gives no level an unconditional final word.

from cadence import PatchNet

brain = PatchNet.recursive(inputs=8, layers=[32, 16, 8], outputs=2, seed=7)
# One base population, two observer populations, one joint solver and learning rule.

Available in 0.18.0, the builder lets you choose the number and size of these populations without introducing another runtime or solver. The recursive settlement guide explains the wiring, whole-state residual checks, local learning and causal interventions. Performance evaluations are ongoing: numerical and causal tests establish the joint-settlement mechanism; a capability advantage from recursive depth and competitive training efficiency against transformers remain hypotheses.

Which brain

The public families share state and port concepts, with distinct solver and learning contracts:

Everything composes through ports: two record patches in depth (RecordPatchStack), several coupled through finite port-repair rounds (JointRecordPatches), a grid read through a tied kernel at the port (StructuredPort), and a genome that evolve mutates and selects across lives. The architecture guide is the contract of the temporal patch.

Examples

The worked applications live in the examples repository, each a static page that runs its brain in the browser with the library's arithmetic, with the receipts behind every number it states and a check that recomputes them; the examples page lists them all. Two of them:

A fly in the Matrix · live · code Import 150,802 retained neurons, supply sensory inputs and read settled neural outputs. Local mushroom-body learning changes responses; a supplied body controller executes goals. The example documents its model, assistance and source-bound checks.

Amen, the jungle composer · live · code One record patch starts from silence, hears each half-beat it plays and computes sixteen bars of drums, bass and texture.

They are application tests, not definitions of the architecture. A result in one does not establish transfer to the others. Every example states what is supplied, what is learned, what was measured and what it does not show, and pins the release its checks were run against.

Build on an example with explicit sensory and action interfaces, reproducible checks and measured resource costs. Report what is supplied, what is learned and which behaviors the evidence supports. The examples repository's contributing section says what an example needs to live there, including the card every example README carries.

Documentation

• Start: for machine-learning people · quickstarts · in your browser · build your own brain · troubleshooting
• Build: record patch · belief patch · a brain that reads itself · how to build a rung demo · temporal learning, planning, learn, act and observe, response protection · compose a brain, write a cortex, local learning, records and memory, reward, evolve a brain
• Measure: task design · common missteps · scaling · certificate · protocols · receipts · the brain viewer · backends
• Reference: API · changelog · Lean proofs · contributing
• The ideas: architecture · equilibrium world models · creativity and self-reflection · the paper

Many brains at once on a graphics processor: cadence.population.PopulationPatch runs a population of record patches, each in many worlds, in lockstep; the guide has the two-line use, what batches, the kernel at the width of a game, and how a population trains across several devices.

The index is the full map.

Four shared principles

• Overlap consensus: patches repair disagreement across their shared boundaries. The resulting equilibrium is an internally consistent model; its predictions have to agree with experience.
• Equilibrium detuning: observed outcomes perturb that equilibrium. Local positive/negative contrasts change learned relationships; the same operation can adjust proposed actions while holding the model fixed.
• Self-readback: a patch's proposed actions and predicted consequences are available to the same brain and tested by its next observation. Physical readback is evidence; an imagined outcome never is.
• Metacognition as recursive self-observation: a patch of the same kind reads the beliefs, residuals and surprises of the rest of the brain through ordinary ports, and its settled state steers them: which evidence counts, where a sense samples, what a habit holds, how long a repair runs. Because it is bounded it cannot steer everything at once, so it must select what matters for what it is computing; that selection is attention. Because it is a patch it can be read in turn, and the levels form a ladder from reflex to a robot that acts and speaks among people. The genome decides which readbacks exist, and a rung is earned only by a task the brain below it fails at matched information and compute. The rungs, their experiments and their issues are tracked in this repository's issues. The ladder orders what a brain earns; its nursery orders what the world supplies in one life, from the self by contingency to words, and its breeder what pays for a brain across lives.

The graph implementation supports joint recursive settlement; other families provide detached self-readback, sequential steering or private proposal revision under their own contracts. A learned advantage from recursive depth, curiosity and reliable creativity are hypotheses with their tests on the ladder. Creativity and self-reflection defines these goals and their behavioral tests.

Equilibrium world models

Cadence is being developed toward evolving equilibrium world models: brains whose internal representation of an actor in its world grows more accurate and expressive through experience. The representation should carry what is happening, what persists out of sight, what the actor controls and what its actions could cause. It need not describe those relationships in words to use them.

An equilibrium here need not mean motionless activity. A skilled actor can follow a coherent, changing trajectory of perceptions, expectations and actions. When events unfold as expected, the carried state should be close to a useful interpretation of the next moment. Familiar danger can prompt a learned response immediately. Extra inference is needed when competing interpretations or consequential choices warrant it.

The proposed mechanism is recursive composition through bounded, observer-like, self-reading patches. Scene, body, candidate action and retrieved experience meet through learned nonlinear ports. One interpretation can become input to another, allowing the system to revise its understanding before acting. Actual evidence anchors that revision; changing the interpretation and learning new relationships are distinct operations. A random outcome can require a new response and be consistent with a correctly learned probability distribution. Teaching detuning uses a specified target to compute a learning signal; it is not synonymous with surprise.

Skilled demonstrations and the actor's own actions supply complementary experience. Watching reveals useful behavior and situations; acting tests what controls actually cause. The same learned relationships should support private branches that explore possible futures without altering factual memory. Plans must be judged by subsequent real outcomes. Grounded replay and sleep should then consolidate reliable relationships and successful decisions into cheaper habits, while unfamiliar situations can reopen deliberation.

This is the architectural vision. Current APIs provide components and bounded demonstrations, not the complete evolving world model. Each successive release is intended to take a concrete step toward this goal. Progress must be shown in prediction, retention, useful internal planning and behavior at declared resource budgets; a new version alone does not establish it. The equilibrium world-model guide explains the mechanism, the distinction between evidence repair and learning, and the current implementation boundaries.

What the library establishes

Imagined continuations are isolated. Branches use the learned network without changing live activity, parameters or factual bookkeeping. Controlled experiments demonstrate useful planning. Creativity requires additional evidence that novel proposals satisfy meaningful constraints and survive actual evaluation; musical improvisation is one possible example.

Retained experience and new learning are tested together. Protected-path memory is conditional and finite. Importance is supplied; automatic relevance, selective forgetting, specialization and broad skill transfer are research requirements. The task-design guide and common missteps explain how to measure them.

General mechanisms, different applications. Games, language, multimodal perception, embodied control and creative work should use the same learning and memory mechanisms with declared observation and action ports. The scaling goal is better learned behavior from more experience and training, with as little manual design as possible. Measure unique experience, repeated training and model capacity separately while keeping port meanings and task evaluation fixed. The scaling guide defines these comparisons and the current computational limits.

Application demonstrations are published only when they establish their claimed behavior. Recall and interpolation are useful development tests; original creation requires stronger evidence. Every example states what is supplied, what is learned, what was measured and what it does not show, and carries a check that recomputes its numbers. Research receipts are available with the paper without presenting those tests as finished products.

Proofs and compatibility

The bundled Lean library contains 169 checked conditional theorems about the mathematical components and their limits. It does not certify the complete Python implementation or prove intelligence. The paper identifies assumptions and reproducible evidence.

The PatchNet graph interface and GenericBrain are kept for the experiments that used them; they are distinct compositions, not parts of the two primitives. API reference.

Development installs use python -m pip install -e ".[dev]"; contributing lists the checks. Optional backends apply to their documented graph APIs; the temporal implementation is NumPy. Pin a release or exact commit for reproducible work. MIT licensed.

Origins

Cadence started as an offshoot of a physics theory, Observer Patch Holography, which models reality itself as a metaphorical brain: a distributed network of observers that finds global equilibria by repairing local conflict. The two projects complement each other and share many of their theorems.