Heat Tracking

How Soma decides what to load into your context. The heat system is built into the boot extension — this protocol helps you understand what's happening and how to tune it. Editing this file won't change the heat system's behavior.

TL;DR

Cold (0-2): skipped. Warm (3-7): TL;DR only. Hot (8+): full body. Heat decays each session, bumps on use. /pin heats, /kill drops to 0.

How It Works

Every protocol and muscle has a heat value. Higher heat = more presence in your system prompt.

Heat	State	What Loads
0-2	Cold	Nothing. Listed as "available" in boot.
3-7	Warm	Breadcrumb — 1-2 sentence summary.
8+	Hot	Full content injected into system prompt.

Auto-Detection

Soma watches tool results and bumps heat when it sees relevant patterns:

Protocols:

• Frontmatter writes → frontmatter-standard +1
• Preload writes → breath-cycle +1
• Checkpoint commits → session-checkpoints +1

Muscles:

• File reads matching muscle triggers: → muscle heat +1
• Script execution matching muscle name → muscle heat +1
• SVG/logo file writes → svg-logo-design +1

Limitation: most protocol usage isn't detectable from tool results. A protocol like working-style has no tool signature — its heat only changes via manual /pin or heat-default in frontmatter.

Decay

On session end, unused protocols lose decayRate heat (default: 1). A protocol you stop using naturally fades from context. Use /pin to keep something hot.

Settings

{
  "protocols": {
    "warmThreshold": 3,
    "hotThreshold": 8,
    "maxHeat": 15,
    "decayRate": 1,
    "maxBreadcrumbsInPrompt": 10,
    "maxFullProtocolsInPrompt": 3
  },
  "muscles": {
    "tokenBudget": 2000,
    "maxFull": 2,
    "maxDigest": 8
  },
  "heat": {
    "autoDetect": true,
    "autoDetectBump": 1,
    "pinBump": 5
  }
}

Tuning Guide

Goal	Adjust
Load more protocols	Raise maxFullProtocolsInPrompt, lower hotThreshold
Faster protocol rotation	Raise decayRate to 2-3
Keep everything loaded	Set decayRate: 0, pin what you want
Minimize prompt size	Lower maxFull and tokenBudget
Disable auto-detection	Set autoDetect: false — manual only

Commands

Command	Effect
/pin <name>	Bump heat by pinBump (default +5)
/kill <name>	Drop heat to 0

Source

• Protocol loading: core/protocols.ts → discoverProtocols(), buildProtocolInjection()
• Muscle loading: core/muscles.ts → discoverMuscles(), buildMuscleInjection()
• Heat state: .soma/state.json (protocol heat values)
• Auto-detection: extensions/soma-boot.ts → tool_result event handler
• Settings: core/settings.ts → ProtocolSettings, MuscleSettings, HeatSettings

---

Heat Tracking Protocol

TL;DR

• Three temperatures: cold (0-2, name only), warm (3-7, breadcrumb in prompt), hot (8+, full body in prompt)
• Auto-detection is limited: only specific tool results trigger heat (frontmatter writes, git commands, SVG, checkpoints). Many protocol uses go undetected.
• Manual controls: /pin <name> → hot, /kill <name> → cold
• Decays -1 per session if unused (on session shutdown)
• Thresholds and limits are configurable in settings.json, not fixed

Rule

Every protocol and muscle has a temperature that determines how it loads into the agent's boot context.

Temperature Scale

Range	State	Boot Behavior
0-2	COLD	Not loaded. Discoverable via search.
3-7	WARM	Breadcrumb (1-2 sentence TL;DR) injected.
8+	HOT	Full protocol content injected.

How Heat Changes

Automated (limited set):

The extension watches tool_result events and bumps heat when specific patterns match:

Pattern	Triggers Heat For
Write file with YAML frontmatter	frontmatter-standard
Git commands (config/commit/push)	git-identity
Write to preload/continuation file	breath-cycle
Write .svg file	svg-logo-design (muscle)
Checkpoint commits (.soma git)	session-checkpoints

This is a limited set. Many protocol applications (e.g., following community-safe rules, applying pattern-evolution principles) are NOT auto-detected. The heat system will under-count usage for protocols without matching tool patterns.

Manual:

Action	Effect
/pin <name>	Bump heat by settings.heat.pinBump (default +5)
/kill <name>	Drop heat to 0

Decay:

On session shutdown, any protocol/muscle NOT used this session decays by settings.protocols.decayRate (default -1).

Configuration

In settings.json (all values have sensible defaults):

{
  "protocols": {
    "hotThreshold": 8,
    "warmThreshold": 3,
    "maxHot": 3,
    "maxWarm": 10,
    "decayRate": 1
  },
  "heat": {
    "autoDetect": true,
    "autoDetectBump": 1,
    "pinBump": 5
  }
}

State Storage

• Protocols: .protocol-state.json in .soma/ — JSON map of name → heat + events
• Muscles: heat: field in each muscle's YAML frontmatter

When to Apply

Automatically — during every inhale (protocol/muscle loading) and every session shutdown (decay). The extension handles this.

When NOT to Apply

If you prefer static loading (all protocols always fully loaded), set all heat values high and decayRate: 0. Works fine for small protocol sets.

Heat Tracking Protocol

TL;DR

• Three temperatures: cold (0-2, name only), warm (3-7, breadcrumb in prompt), hot (8+, full body in prompt)
• Heat rises on use: +2 explicit reference, +1 applied in action. Decays -1 per session if unused
• Pin to hot: user says "always use X" → heat 10. Kill: "stop using X" → heat 0
• Limits: max 3 full protocols in prompt, max 10 breadcrumbs. Highest heat wins ties
• State persists across sessions, updated during exhale phase

Rule

Every protocol has a temperature that determines how it loads into the agent's system prompt.

Temperature Scale

Range	State	System Prompt Behavior
0-2	COLD	Not loaded. Discoverable via search.
3-7	WARM	Breadcrumb (1-2 sentence TL;DR) injected.
8+	HOT	Full protocol content injected.

Heat Events

Event	Δ Heat	Example
User explicitly references protocol	+2	"Use the frontmatter standard"
Agent applies protocol in action	+1	Agent adds frontmatter to a file
Session ends, protocol was used	+0	Heat holds, no decay
Session ends, protocol NOT used	-1	Cooling — unused protocols fade
User says "always use X"	→ 10	Manual pin to HOT
User says "stop using X"	→ 0	Manual kill to COLD

Limits (Token Budget)

• Max full protocols in prompt: 3
• Max breadcrumbs in prompt: 10
• Max heat: 15
• Decay rate: 1 per unused session

If more protocols qualify for HOT than the max, highest heat wins. Same for WARM breadcrumbs.

When to Apply

During every inhale (protocol loading) and every exhale (heat update). This protocol is always-on.

When NOT to Apply

If you prefer static protocol loading (all protocols always fully loaded), disable heat tracking and load everything. Works fine for small protocol sets.

Heat Tracking Protocol

TL;DR

• Three temperatures: cold (0-2, name only), warm (3-7, breadcrumb in prompt), hot (8+, full body in prompt)
• Heat rises on use: +2 explicit reference, +1 applied in action. Decays -1 per session if unused
• Pin to hot: user says "always use X" → heat 10. Kill: "stop using X" → heat 0
• Limits: max 3 full protocols in prompt, max 10 breadcrumbs. Highest heat wins ties
• State persists across sessions, updated during exhale phase

Rule

Every protocol has a temperature that determines how it loads into the agent's system prompt.

Temperature Scale

Range	State	System Prompt Behavior
0-2	COLD	Not loaded. Discoverable via search.
3-7	WARM	Breadcrumb (1-2 sentence TL;DR) injected.
8+	HOT	Full protocol content injected.

Heat Events

Event	Δ Heat	Example
User explicitly references protocol	+2	"Use the frontmatter standard"
Agent applies protocol in action	+1	Agent adds frontmatter to a file
Session ends, protocol was used	+0	Heat holds, no decay
Session ends, protocol NOT used	-1	Cooling — unused protocols fade
User says "always use X"	→ 10	Manual pin to HOT
User says "stop using X"	→ 0	Manual kill to COLD

Limits (Token Budget)

• Max full protocols in prompt: 3
• Max breadcrumbs in prompt: 10
• Max heat: 15
• Decay rate: 1 per unused session

If more protocols qualify for HOT than the max, highest heat wins. Same for WARM breadcrumbs.

When to Apply

During every inhale (protocol loading) and every exhale (heat update). This protocol is always-on.

When NOT to Apply

If you prefer static protocol loading (all protocols always fully loaded), disable heat tracking and load everything. Works fine for small protocol sets.