# ynkling/clankers architecture

> Architecture diagram of the GitHub repository ynkling/clankers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ynkling/clankers
- Repository: https://github.com/ynkling/clankers

## Overview

BDH is a byte-level language-model implementation of a biologically inspired neural architecture. Its main workflow trains on token sequences, predicts next-token logits, and can autoregressively generate text. The core model combines sparse latent neuron activations, causal attention, multiplicative interactions, and residual decoding; separate files explore context-routed channels and explicit Hebbian recurrence. The map reflects the README and sampled source; broader documented claims such as scale-free topology are not independently confirmed by these excerpts.

Main entry points: [`bdh.py`](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py) (BDH model), [`train.py`](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/train.py) (Training script), [`bdh_mc.py`](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py) (Multi-channel BDH), [`train_two_task.py`](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/train_two_task.py) (Two-task training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["BDH model"]
  node_baseline["BDH model<br/>[bdh.py]"]
  node_embedding["Token embedding<br/>[bdh.py]"]
  node_sparse["Sparse neurons<br/>[bdh.py]"]
  node_attention["Causal attention<br/>[bdh.py]"]
  node_interaction["Neuron interaction<br/>[bdh.py]"]
  node_readout["Language readout<br/>[bdh.py]"]
  node_generation["Text generation<br/>[bdh.py]"]
end

subgraph group_variants["Memory variants"]
  node_mcmodel["Multi-channel BDH<br/>[bdh_mc.py]"]
  node_context["Context gate<br/>[bdh_mc.py]"]
  node_channelweights["Channel weights<br/>[bdh_mc.py]"]
  node_recurrent["Hebbian recurrence<br/>[bdh_recurrent.py]"]
  node_multichannelmemory["Gated memory model"]
end

subgraph group_training["Training workflows"]
  node_trainer["Training script<br/>[train.py]"]
  node_twotask["Two-task training<br/>[train_two_task.py]"]
end

node_user(("User"))
node_corpus["Byte corpus"]

node_user -->|"starts training"| node_trainer
node_corpus -->|"provides bytes"| node_trainer
node_trainer -->|"trains"| node_baseline
node_baseline -->|"embeds tokens"| node_embedding
node_embedding -->|"projects"| node_sparse
node_sparse -->|"queries keys"| node_attention
node_attention -->|"returns context"| node_interaction
node_interaction -->|"updates residual"| node_sparse
node_baseline -->|"projects logits"| node_readout
node_baseline -->|"generates tokens"| node_generation
node_generation -->|"returns text"| node_user
node_trainer -.->|"trains variant"| node_mcmodel
node_mcmodel -->|"projects context"| node_context
node_context -->|"blends channels"| node_channelweights
node_channelweights -->|"supplies weights"| node_mcmodel
node_twotask -->|"trains tasks"| node_mcmodel
node_twotask -->|"loads task bytes"| node_corpus
node_recurrent -.->|"implements recurrence"| node_multichannelmemory

click node_trainer "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/train.py"
click node_baseline "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_embedding "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_sparse "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_attention "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_interaction "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_readout "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_generation "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py"
click node_mcmodel "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py"
click node_context "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py"
click node_channelweights "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py"
click node_twotask "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/train_two_task.py"
click node_recurrent "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_recurrent.py"
click node_multichannelmemory "https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_multichannel.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_baseline,node_embedding,node_sparse,node_attention,node_interaction,node_readout,node_generation,node_user toneBlue
class node_mcmodel,node_context,node_channelweights,node_recurrent,node_multichannelmemory toneAmber
class node_trainer,node_twotask toneMint
class node_corpus toneIndigo
```

## Components

### BDH model

- [BDH model](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`
- [Token embedding](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`
- [Sparse neurons](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`
- [Causal attention](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`
- [Neuron interaction](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`
- [Language readout](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`
- [Text generation](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh.py): `bdh.py`

### Memory variants

- [Multi-channel BDH](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py): `bdh_mc.py`
- [Context gate](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py): `bdh_mc.py`
- [Channel weights](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_mc.py): `bdh_mc.py`
- [Hebbian recurrence](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_recurrent.py): `bdh_recurrent.py`
- [Gated memory model](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/bdh_multichannel.py): `bdh_multichannel.py`

### Training workflows

- [Training script](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/train.py): `train.py`
- [Two-task training](https://github.com/ynkling/clankers/blob/claude/bdh-repo-curl-obgdqk/train_two_task.py): `train_two_task.py`

### Other components

- **User**
- **Byte corpus**

## Connections

- User → Training script: starts training
- Byte corpus → Training script: provides bytes
- Training script → BDH model: trains
- BDH model → Token embedding: embeds tokens
- Token embedding → Sparse neurons: projects
- Sparse neurons → Causal attention: queries keys
- Causal attention → Neuron interaction: returns context
- Neuron interaction → Sparse neurons: updates residual
- BDH model → Language readout: projects logits
- BDH model → Text generation: generates tokens
- Text generation → User: returns text
- Training script → Multi-channel BDH: trains variant
- Multi-channel BDH → Context gate: projects context
- Context gate → Channel weights: blends channels
- Channel weights → Multi-channel BDH: supplies weights
- Two-task training → Multi-channel BDH: trains tasks
- Two-task training → Byte corpus: loads task bytes
- Hebbian recurrence → Gated memory model: implements recurrence