# state-spaces/mamba architecture

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

- Interactive diagram: https://gitdiagram.com/state-spaces/mamba
- Repository: https://github.com/state-spaces/mamba

## Overview

Mamba is a PyTorch state-space sequence-modeling library, exposing Mamba-1, Mamba-2/SSD, and Mamba-3 blocks plus a complete causal language-model example. The principal workflow is token IDs entering generation, passing through the language-model head, embedding/backbone blocks, and a selected SSM implementation, then returning logits or generated tokens. Lower layers provide selective-scan, SSD, and GPU kernels, with inference-state caching for decoding. The graph reflects README capabilities and sampled call sites; some unsampled variant wiring is shown only where documented.

Main entry points: [`mamba_ssm/modules/mamba3.py`](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba3.py) (Mamba-3 Block), [`mamba_ssm/utils/generation.py`](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/utils/generation.py) (Generation API), [`mamba_ssm/modules/block.py`](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/block.py) (Sequence Block), [`mamba_ssm/models/mixer_seq_simple.py`](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py) (LM Head)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_generation["Generation API<br/>[generation.py]"]
end

subgraph group_model["Model Stack"]
  node_lm_head["LM Head"]
  node_backbone["Mixer Backbone"]
  node_embedding["Token Embedding"]
  node_block["Sequence Block<br/>[block.py]"]
end

subgraph group_ssm["SSM Algorithms"]
  node_mamba1["Mamba-1 Block<br/>[mamba_simple.py]"]
  node_mamba2["Mamba-2 Block<br/>[mamba2.py]"]
  node_mamba3["Mamba-3 Block<br/>[mamba3.py]"]
  node_selective["Selective SSM"]
end

subgraph group_kernels["GPU Kernels"]
  node_ssd["SSD Operations<br/>[ssd_combined.py]"]
  node_scan_cuda["CUDA Scan<br/>[selective_scan.cpp]"]
  node_mamba3_gpu["Mamba-3 Kernels"]
  node_mamba3_tile["Mamba-3 Tile Kernels<br/>[mamba3_mimo.py]"]
  node_step_kernel["Mamba-3 Step<br/>[mamba3_step_fn.py]"]
end

subgraph group_inference["Inference"]
  node_state_cache["Inference State<br/>[generation.py]"]
end

node_caller(("Model Caller"))
node_logits["Logits"]
node_tokens["Generated Tokens"]

node_caller -->|"calls"| node_generation
node_generation -->|"invokes model"| node_lm_head
node_lm_head -->|"runs backbone"| node_backbone
node_backbone -->|"embeds tokens"| node_embedding
node_backbone -->|"runs blocks"| node_block
node_block -.->|"selects mixer"| node_mamba1
node_block -.->|"selects mixer"| node_mamba2
node_block -.->|"selects mixer"| node_mamba3
node_mamba1 -->|"calls scan"| node_selective
node_mamba2 -->|"runs SSD"| node_ssd
node_selective -.->|"dispatches CUDA"| node_scan_cuda
node_mamba3 -.->|"dispatches kernels"| node_mamba3_gpu
node_mamba3 -.->|"dispatches kernels"| node_mamba3_tile
node_mamba3 -.->|"runs step"| node_step_kernel
node_mamba3 -->|"updates state"| node_state_cache
node_lm_head -->|"returns logits"| node_logits
node_generation -->|"manages cache"| node_state_cache
node_generation -->|"samples tokens"| node_tokens

click node_generation "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/utils/generation.py"
click node_lm_head "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py"
click node_backbone "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py"
click node_embedding "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py"
click node_block "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/block.py"
click node_mamba1 "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba_simple.py"
click node_mamba2 "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba2.py"
click node_mamba3 "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba3.py"
click node_selective "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/selective_scan_interface.py"
click node_ssd "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/triton/ssd_combined.py"
click node_scan_cuda "https://github.com/state-spaces/mamba/blob/main/csrc/selective_scan/selective_scan.cpp"
click node_mamba3_gpu "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/triton/mamba3/mamba3_siso_combined.py"
click node_mamba3_tile "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/tilelang/mamba3/mamba3_mimo.py"
click node_step_kernel "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/cute/mamba3/mamba3_step_fn.py"
click node_state_cache "https://github.com/state-spaces/mamba/blob/main/mamba_ssm/utils/generation.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_generation toneBlue
class node_lm_head,node_backbone,node_embedding,node_block toneAmber
class node_mamba1,node_mamba2,node_mamba3,node_selective toneMint
class node_ssd,node_scan_cuda,node_mamba3_gpu,node_mamba3_tile,node_step_kernel toneRose
class node_state_cache,node_caller,node_logits,node_tokens toneIndigo
```

## Components

### Public API

- [Generation API](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/utils/generation.py): `mamba_ssm/utils/generation.py`

### Model Stack

- [LM Head](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py): `mamba_ssm/models/mixer_seq_simple.py`
- [Mixer Backbone](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py): `mamba_ssm/models/mixer_seq_simple.py`
- [Token Embedding](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/models/mixer_seq_simple.py): `mamba_ssm/models/mixer_seq_simple.py`
- [Sequence Block](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/block.py): `mamba_ssm/modules/block.py`

### SSM Algorithms

- [Mamba-1 Block](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba_simple.py): `mamba_ssm/modules/mamba_simple.py`
- [Mamba-2 Block](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba2.py): `mamba_ssm/modules/mamba2.py`
- [Mamba-3 Block](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/modules/mamba3.py): `mamba_ssm/modules/mamba3.py`
- [Selective SSM](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/selective_scan_interface.py): `mamba_ssm/ops/selective_scan_interface.py`

### GPU Kernels

- [SSD Operations](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/triton/ssd_combined.py): `mamba_ssm/ops/triton/ssd_combined.py`
- [CUDA Scan](https://github.com/state-spaces/mamba/blob/main/csrc/selective_scan/selective_scan.cpp): `csrc/selective_scan/selective_scan.cpp`
- [Mamba-3 Kernels](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/triton/mamba3/mamba3_siso_combined.py): `mamba_ssm/ops/triton/mamba3/mamba3_siso_combined.py`
- [Mamba-3 Tile Kernels](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/tilelang/mamba3/mamba3_mimo.py): `mamba_ssm/ops/tilelang/mamba3/mamba3_mimo.py`
- [Mamba-3 Step](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/ops/cute/mamba3/mamba3_step_fn.py): `mamba_ssm/ops/cute/mamba3/mamba3_step_fn.py`

### Inference

- [Inference State](https://github.com/state-spaces/mamba/blob/main/mamba_ssm/utils/generation.py): `mamba_ssm/utils/generation.py`

### Other components

- **Model Caller**
- **Logits**
- **Generated Tokens**

## Connections

- Model Caller → Generation API: calls
- Generation API → LM Head: invokes model
- LM Head → Mixer Backbone: runs backbone
- Mixer Backbone → Token Embedding: embeds tokens
- Mixer Backbone → Sequence Block: runs blocks
- Sequence Block → Mamba-1 Block: selects mixer
- Sequence Block → Mamba-2 Block: selects mixer
- Sequence Block → Mamba-3 Block: selects mixer
- Mamba-1 Block → Selective SSM: calls scan
- Mamba-2 Block → SSD Operations: runs SSD
- Selective SSM → CUDA Scan: dispatches CUDA
- Mamba-3 Block → Mamba-3 Kernels: dispatches kernels
- Mamba-3 Block → Mamba-3 Tile Kernels: dispatches kernels
- Mamba-3 Block → Mamba-3 Step: runs step
- Mamba-3 Block → Inference State: updates state
- LM Head → Logits: returns logits
- Generation API → Inference State: manages cache
- Generation API → Generated Tokens: samples tokens
