# facebookresearch/context-language-models architecture

> Architecture diagram of the GitHub repository facebookresearch/context-language-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/context-language-models
- Repository: https://github.com/facebookresearch/context-language-models

## Overview

The repository implements CLM agents whose main workflow lets a model edit its conversation context through a sandbox, then records the run as a context-aware trajectory. Separate branches evolve context-management skills in-context and provide suffix-cache reuse for serving. The README also describes reinforcement learning, but no RL source appears in the supplied tree. Relationships below are limited to README statements and SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`clm/clm_harness/clm_agent/harness.py`](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/clm_agent/harness.py) (CLM agent), [`clm/clm_harness/context_env/env.py`](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_env/env.py) (Context environment), [`clm/clm_harness/agent_trajectory_format/models.py`](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/models.py) (ATIF-CTX models), [`clm/clm_icl/evolve.py`](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/evolve.py) (Skill evolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["CLM agent runtime"]
  node_agent["CLM agent<br/>[harness.py]"]
  node_context["Context environment<br/>[env.py]"]
  node_context_text["Context text codec<br/>[context_string.py]"]
  node_edit_gate["Edit gate<br/>[edit_gate.py]"]
  node_budget["Context budgeting<br/>[budget.py]"]
  node_tokens["Token counting<br/>[tokens.py]"]
  node_resume["Trial resume<br/>[resume.py]"]
  node_skills["Skill support<br/>[skills.py]"]
end

subgraph group_trajectory["Trajectory and metrics"]
  node_trajectory_export["Trajectory export<br/>[harness_export.py]"]
  node_trajectory_builder["Trajectory builder<br/>[builder.py]"]
  node_trajectory_models["ATIF-CTX models<br/>[models.py]"]
  node_trajectory_validator["Trajectory validator<br/>[validator.py]"]
  node_flops["KV-cache FLOPs<br/>[kv_cache_flops.py]"]
end

subgraph group_icl["In-context learning"]
  node_evolution["Skill evolution<br/>[evolve.py]"]
  node_task_sources["Task sources<br/>[tasks.py]"]
  node_proposer["Skill proposer<br/>[propose.py]"]
  node_evolution_notes["Evolution notes<br/>[note.py]"]
end

subgraph group_serving["Efficient serving"]
  node_scr_config["Reuse configuration<br/>[config.py]"]
  node_scr_overlay["KV reuse overlay<br/>[overlay.py]"]
  node_site_hook["Server site hook<br/>[sitecustomize.py]"]
  node_scr_serve["Serving entry<br/>[serve.py]"]
end

node_user(("Task user"))
node_harbor["Harbor task runner"]
node_model["Language model"]

node_user -->|"starts task"| node_harbor
node_harbor -->|"runs agent"| node_agent
node_agent -.->|"requests completions"| node_model
node_agent -->|"uses sandbox"| node_context
node_agent -->|"restores state"| node_resume
node_agent -->|"installs skills"| node_skills
node_agent -->|"exports rollout"| node_trajectory_export
node_agent -->|"records metrics"| node_flops
node_context -->|"renders edits"| node_context_text
node_context -->|"checks edits"| node_edit_gate
node_context -->|"checks budget"| node_budget
node_context -->|"counts context"| node_tokens
node_budget -->|"counts tokens"| node_tokens
node_trajectory_export -->|"builds segments"| node_trajectory_builder
node_trajectory_export -->|"creates records"| node_trajectory_models
node_trajectory_builder -->|"constructs models"| node_trajectory_models
node_flops -->|"reads trajectories"| node_trajectory_models
node_trajectory_validator -->|"validates schema"| node_trajectory_models
node_evolution -->|"runs tasks"| node_task_sources
node_evolution -->|"requests candidates"| node_proposer
node_evolution -->|"uses notes"| node_evolution_notes
node_site_hook -->|"loads config"| node_scr_config
node_site_hook -->|"loads overlay"| node_scr_overlay
node_scr_serve -->|"uses config"| node_scr_config
node_scr_overlay -.->|"reuses KV cache"| node_model

click node_agent "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/clm_agent/harness.py"
click node_context "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_env/env.py"
click node_context_text "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_utils/context_string.py"
click node_edit_gate "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_env/edit_gate.py"
click node_budget "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/budget.py"
click node_tokens "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/tokens.py"
click node_resume "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/resume.py"
click node_skills "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/skills.py"
click node_trajectory_export "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/harness_export.py"
click node_trajectory_builder "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/builder.py"
click node_trajectory_models "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/models.py"
click node_trajectory_validator "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/validator.py"
click node_flops "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/flops_metrics/kv_cache_flops.py"
click node_evolution "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/evolve.py"
click node_task_sources "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/tasks.py"
click node_proposer "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/propose.py"
click node_evolution_notes "https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/note.py"
click node_scr_config "https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/config.py"
click node_scr_overlay "https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/overlay.py"
click node_site_hook "https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/_site/sitecustomize.py"
click node_scr_serve "https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/serve.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_agent,node_context,node_context_text,node_edit_gate,node_budget,node_tokens,node_resume,node_skills toneBlue
class node_trajectory_export,node_trajectory_builder,node_trajectory_models,node_trajectory_validator,node_flops toneAmber
class node_evolution,node_task_sources,node_proposer,node_evolution_notes toneMint
class node_scr_config,node_scr_overlay,node_site_hook,node_scr_serve,node_user,node_harbor toneRose
class node_model toneIndigo
```

## Components

### CLM agent runtime

- [CLM agent](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/clm_agent/harness.py): `clm/clm_harness/clm_agent/harness.py`
- [Context environment](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_env/env.py): `clm/clm_harness/context_env/env.py`
- [Context text codec](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_utils/context_string.py): `clm/clm_harness/context_utils/context_string.py`
- [Edit gate](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/context_env/edit_gate.py): `clm/clm_harness/context_env/edit_gate.py`
- [Context budgeting](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/budget.py): `clm/clm_harness/utils/budget.py`
- [Token counting](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/tokens.py): `clm/clm_harness/utils/tokens.py`
- [Trial resume](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/resume.py): `clm/clm_harness/utils/resume.py`
- [Skill support](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/utils/skills.py): `clm/clm_harness/utils/skills.py`

### Trajectory and metrics

- [Trajectory export](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/harness_export.py): `clm/clm_harness/agent_trajectory_format/harness_export.py`
- [Trajectory builder](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/builder.py): `clm/clm_harness/agent_trajectory_format/builder.py`
- [ATIF-CTX models](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/models.py): `clm/clm_harness/agent_trajectory_format/models.py`
- [Trajectory validator](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/agent_trajectory_format/validator.py): `clm/clm_harness/agent_trajectory_format/validator.py`
- [KV-cache FLOPs](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_harness/flops_metrics/kv_cache_flops.py): `clm/clm_harness/flops_metrics/kv_cache_flops.py`

### In-context learning

- [Skill evolution](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/evolve.py): `clm/clm_icl/evolve.py`
- [Task sources](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/tasks.py): `clm/clm_icl/tasks.py`
- [Skill proposer](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/propose.py): `clm/clm_icl/propose.py`
- [Evolution notes](https://github.com/facebookresearch/context-language-models/blob/main/clm/clm_icl/note.py): `clm/clm_icl/note.py`

### Efficient serving

- [Reuse configuration](https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/config.py): `suffix_cache_reuse/suffix_cache_reuse/config.py`
- [KV reuse overlay](https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/overlay.py): `suffix_cache_reuse/suffix_cache_reuse/overlay.py`
- [Server site hook](https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/_site/sitecustomize.py): `suffix_cache_reuse/suffix_cache_reuse/_site/sitecustomize.py`
- [Serving entry](https://github.com/facebookresearch/context-language-models/blob/main/suffix_cache_reuse/suffix_cache_reuse/serve.py): `suffix_cache_reuse/suffix_cache_reuse/serve.py`

### Other components

- **Task user**
- **Harbor task runner**
- **Language model**

## Connections

- Task user → Harbor task runner: starts task
- Harbor task runner → CLM agent: runs agent
- CLM agent → Language model: requests completions
- CLM agent → Context environment: uses sandbox (evidence: `clm/clm_harness/clm_agent/harness.py`)
- CLM agent → Trial resume: restores state (evidence: `clm/clm_harness/clm_agent/harness.py`)
- CLM agent → Skill support: installs skills (evidence: `clm/clm_harness/clm_agent/harness.py`)
- CLM agent → Trajectory export: exports rollout (evidence: `clm/clm_harness/clm_agent/harness.py`)
- CLM agent → KV-cache FLOPs: records metrics (evidence: `clm/clm_harness/clm_agent/harness.py`)
- Context environment → Context text codec: renders edits (evidence: `clm/clm_harness/context_env/env.py`)
- Context environment → Edit gate: checks edits (evidence: `clm/clm_harness/context_env/env.py`)
- Context environment → Context budgeting: checks budget (evidence: `clm/clm_harness/context_env/env.py`)
- Context environment → Token counting: counts context (evidence: `clm/clm_harness/context_env/env.py`)
- Context budgeting → Token counting: counts tokens (evidence: `clm/clm_harness/utils/budget.py`)
- Trajectory export → Trajectory builder: builds segments (evidence: `clm/clm_harness/agent_trajectory_format/harness_export.py`)
- Trajectory export → ATIF-CTX models: creates records (evidence: `clm/clm_harness/agent_trajectory_format/harness_export.py`)
- Trajectory builder → ATIF-CTX models: constructs models (evidence: `clm/clm_harness/agent_trajectory_format/builder.py`)
- KV-cache FLOPs → ATIF-CTX models: reads trajectories (evidence: `clm/clm_harness/flops_metrics/kv_cache_flops.py`)
- Trajectory validator → ATIF-CTX models: validates schema (evidence: `clm/clm_harness/agent_trajectory_format/validator.py`)
- Skill evolution → Task sources: runs tasks (evidence: `clm/clm_icl/evolve.py`)
- Skill evolution → Skill proposer: requests candidates (evidence: `clm/clm_icl/evolve.py`)
- Skill evolution → Evolution notes: uses notes (evidence: `clm/clm_icl/evolve.py`)
- Server site hook → Reuse configuration: loads config (evidence: `suffix_cache_reuse/suffix_cache_reuse/_site/sitecustomize.py`)
- Server site hook → KV reuse overlay: loads overlay (evidence: `suffix_cache_reuse/suffix_cache_reuse/_site/sitecustomize.py`)
- Serving entry → Reuse configuration: uses config (evidence: `suffix_cache_reuse/suffix_cache_reuse/serve.py`)
- KV reuse overlay → Language model: reuses KV cache
