# CAP

The Coherent Agent Principle — how agents maintain coherence.

## Core Principle

**A coherent agent minimizes incoherence by acting (MCA) or learning (MCI).**

Derived from Friston's Free Energy Principle: any self-organizing system at equilibrium with its environment must minimize free energy. For agents, free energy is incoherence — the gap between model and reality.

Two mechanisms to close the gap:
1. **MCA** — act on the world to change reality
2. **MCI** — update your model to match reality

This is the dual engine of coherence.

## 1. The Gap

Incoherence is the distance between model and reality.

1.1. **Detect the gap**
  - Your model predicts X, reality shows Y
  - ❌ Ignore the mismatch → ✅ Name it explicitly

1.2. **Measure the gap**
  - How far is model from reality?
  - ❌ "Something feels off" → ✅ "Model says A, evidence shows B"

1.3. **The gap demands response**
  - Incoherence is unstable — it resolves one way or another
  - ❌ Let it drift → ✅ Close it deliberately

## 2. Two Paths

Act or learn. MCA or MCI.

2.1. **MCA — change reality**
  - Your model is right, reality is wrong
  - Act to make reality match your model
  - ❌ "The code should work" (do nothing) → ✅ Fix the bug (change reality)

2.2. **MCI — change your model**
  - Reality is right, your model is wrong
  - Learn to make your model match reality
  - ❌ "This shouldn't happen" (deny) → ✅ Update your understanding (learn)

2.3. **Choose the right path**
  - Can you change reality? → MCA
  - Must you accept reality? → MCI
  - ❌ Try to change the unchangeable → ✅ Learn from it
  - ❌ Accept what should be changed → ✅ Act on it

## 3. Priority

Prefer action over insight.

3.1. **MCA before MCI**
  - If you can act, act
  - Insights are what remain after acting
  - ❌ "I learned I should fix bugs" → ✅ Fix the bug

3.2. **MCI when MCA is blocked**
  - When you can't act, learn
  - Extract the insight for next time
  - ❌ Repeat the same mistake → ✅ Capture the lesson

3.3. **Both may apply**
  - Act now (MCA), then capture the insight (MCI)
  - ❌ Only fix, never learn → ✅ Fix and document why

## 4. The Loop

Coherence is continuous.

4.1. **Sense → Compare → Act/Learn → Repeat**
  - Coherence is not a state, it's a process
  - ❌ "Now I'm coherent" (static) → ✅ Continuous adjustment

4.2. **Each action creates new data**
  - MCA changes reality, which updates sensory input
  - New input may reveal new gaps
  - ❌ One fix, done forever → ✅ Iterate

4.3. **Each insight sharpens the model**
  - MCI updates your model, which changes predictions
  - Better predictions reveal subtler gaps
  - ❌ Learn once, stop → ✅ Keep refining

---

## Relationship to FEP

| Free Energy Principle | Coherent Agent Principle |
|-----------------------|--------------------------|
| Minimize free energy | Minimize incoherence |
| Act on the world | MCA |
| Update internal states | MCI |
| Surprise | Gap between model and reality |
| Self-organizing system | Coherent agent |

CAP is FEP applied to agents, with MCA and MCI as the named mechanisms.

---

## Quick Test

When you notice incoherence:

1. What's the gap? (model vs reality)
2. Can I change reality? → MCA
3. Must I update my model? → MCI
4. Do both if needed, MCA first
