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.
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 metacognition ladder orders the steps from the brains in this library to that milestone, rung by rung, each with its task, its control, its falsifier and its issue.
Cadence is a NumPy library of brains that compute by settling into an equilibrium and learn by detuning it. A brain is a set of patches joined by ports: groups of neurons with their synapses, or one context vector with a record store beside it. The answer is the state the brain settles into under its inputs. Learning settles once more with the outputs nudged toward the outcome and moves every synapse on the product of its own two ends in the two settled states, so nothing is propagated backward. The record store is a fixed sparse code of the reading addressing a table that takes an outcome in one write and reads it back at the same reading, and a night of sleep moves what the store holds into the slow weights. 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.
python -m pip install cadence-net # Python 3.11+ and NumPy; torch, MLX and Numba are optionalThree 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:
cadence-demo stream # a record patch learns a stream, remembers in one shot, and sleeps
cadence-demo decide # a settling brain decides
cadence-demo body # a temporal patch learns a consequence and plansNothing 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.
Two primitives, composed through ports, and the belief patch that composes them toward a world model:
| You want | Start with | What it supplies |
|---|---|---|
| to learn from a stream of events, keep single facts after one exposure, and generalise overnight | the record patch, RecordPatchNet | A gated linear context with a record store inside the patch: an observation is written once by day, and by night the slow weights learn from the store's own dreams (sleep), with nothing outside the patch consulted. Categorical ports, batched writes, a store narrower than its port and a two-patch stack. One pass of writes, with no gradient, gives a small grammar for 0.8 of its never-taught combinations; one night lifts the slow weights alone to 1.0. |
| a decision or evaluation over a fixed set of inputs, an explicit wiring, a policy that learns from reward | the settling brain: a brain of regions (Genome, develop, Brain, Learner) |
Local repair of a settled state under any wiring, including a measured connectome; learning by the contrast of a free and a nudged settle; cortices, a records cortex, reward through eligibility traces, evolution of the genome, and a certificate on the settling. |
| continuous observations and actions, a learned dynamics model, private planning | the temporal patch, TemporalPatchNet | Local repair of observed paths, persistent context, private imagination, continuous planning and protected responses; learning by the contrast of a free and a nudged settle of the whole path. |
| a belief carried under action, repaired by evidence, that imagines with no observation | the belief patch, BeliefPatch | A belief carried by a learned transition under the executed action and repaired by a few iterations of one nonlinear map with the record store read inside it. The composition toward a learned world model, trained with the imagination loss so the transition carries the belief. |
Everything composes through ports: two record patches in depth (RecordPatchStack),
several settled as one equilibrium (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.
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 The 150,802 neurons of a fruit fly, brain and nerve cord wired as measured, as one settling brain flying a body with physics; the physiology gates against shuffled wirings; the mushroom body learning which smell means sugar. |
 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 your own. Fork an example, break it, give the same brain a different body or a different sense, and put a task in front of it that nobody has tried. Every example, finished or half-working, is data for us: it says what the architecture does where we have not looked, and that is what scales this work toward the full humanoid simulation. Hack things. Be crazy. Chaos is how we learn. The examples repository's contributing section says what an example needs to live there, including the card every example README carries.
- Start: for machine-learning people · quickstarts · in your browser · build your own brain · troubleshooting
- Build: record patch · belief patch · 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 metacognition ladder · the paper
The index is the full map.
- 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 metacognition ladder states the rungs, their experiments and their issues.
The current implementation provides detached self-readback and private proposal revision. Learned steering patches, curiosity and reliable creativity are hypotheses with their tests on the ladder. Creativity and self-reflection defines these goals and their behavioral tests.
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.
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.
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,
GenericBrain, EquilibriumActor,
content memory, rehearsal and sequence readback 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.
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.