---
id: "concept-icm-d1"
type: "concept"
source_timestamps: ["00:00:01", "00:00:44", "00:06:53"]
tags: ["architecture", "file-systems", "agent-design"]
related: ["claim-icm-superiority", "action-implement-folders", "concept-dialogue-structure", "entity-icm-paper-arxiv"]
definition: "A methodology that replaces complex AI orchestration frameworks with simple folder structures and markdown files to manage agent context and workflows."
sources: ["video"]
sourceVaultSlug: "interpretible-context-methodology-icm-2026Jun02"
originDay: 1
---
# Interpretible Context Methodology (ICM)

## Definition

The **Interpretible Context Methodology (ICM)** is a contrarian approach to building AI agent architectures. Instead of relying on complex multi-agent orchestration frameworks such as [[entity-langchain]] or [[entity-semantic-kernel]], ICM advocates for using plain text, markdown files, and standard folder hierarchies to manage context and workflows.

## Core Philosophy

An AI agent (typically [[entity-claude]]) can navigate a well-structured file system to:

- Gather necessary context on demand
- Understand constraints encoded as markdown
- Execute tasks deterministically without orchestration glue code

By breaking down workflows, prompt libraries, and specific 'skills' into discrete markdown files, users create a **highly transparent, easily modifiable, and human-readable architecture**.

## Claimed Benefits

- **Token reduction of 20–40%** versus framework-driven approaches (see [[claim-icm-superiority]] — note that this figure is anecdotal/case-study based, not a peer-reviewed benchmark).
- Faster execution and lower latency.
- Significantly lower barrier to entry for non-technical teams who only need to manage folders and text files instead of Python code or API integrations.
- Greater determinism and inspectability of agent behaviour.

## Formal Grounding (Companion Paper)

The talk's practitioner framing is formalized in the peer-companion paper [[entity-icm-paper-arxiv]] (*"Interpretable Context Methodology: Folder Structure as Agent Architecture,"* Van Clief & McDermott, arXiv:2603.16021, Edinburgh). The paper makes explicit a structure the video only implies — the **Five-Layer Context Hierarchy**:

- **Layer 0** — `CLAUDE.md` (global identity)
- **Layer 1** — `CONTEXT.md` (workspace routing)
- **Layer 2** — Stage `CONTEXT.md` (per-stage contracts)
- **Layer 3** — Reference material (stable across runs)
- **Layer 4** — Working artifacts (per-run content)

Numbered stage folders (`01_research`, `02_script`, `03_production`) carry explicit Inputs / Process / Outputs contracts, with **human review gates** between stages. The paper grounds the efficiency claim quantitatively: **2,000–8,000 focused tokens per stage** vs. a monolithic prompt **exceeding 40,000 tokens, most of it irrelevant** — invoking Liu et al.'s *"lost in the middle"* degradation as the mechanism. It also reframes ICM as **"interpretable" in Rudin's sense** (inherently inspectable, not post-hoc explained) and as Karpathy-style *"context engineering."* The full set of paper diagrams (five-layer hierarchy with token budgets, the folder tree, the token-composition chart, the review-gate pipeline) is captured and synthesized in [[exhibit-icm-paper-figures]].

## Cultural Validation

[[entity-anthropic]] and researchers such as [[entity-andrej-karpathy-d1]] independently arrived at similar ideas — Karpathy's 'LLM Wiki' approach mirrors ICM's emphasis on structured markdown as the substrate of agent context.

## Related Building Blocks

- The structural origin of ICM skills is explored in [[concept-dialogue-structure]].
- ICM is operationalized in the [[framework-skill-creation]] process.
- The maturity ladder for adopting ICM is described in [[concept-three-levels-ai]].
- Its ultimate expression is [[concept-voice-collaboration]].

## Prerequisites for Understanding

- [[prereq-llm-context]]
- [[prereq-markdown]]

## Open Questions

- [[question-icm-scaling]] — how does this scale to massive enterprise codebases?

## Counter-Perspective

See [[contrarian-frameworks]]. Note that Microsoft's Cloud Adoption Framework and other enterprise sources agree with the *starting* posture (single agent first) but argue that multi-agent frameworks remain valuable across security boundaries, multi-team environments, and at large scale.


## Related across days
- [[concept-icm-d2]]
- [[concept-five-layer-hierarchy]]
- [[framework-icm-architecture]]
- [[concept-stage-contracts]]
- [[synthesis-five-layer-fills-the-gap]]
- [[arc-talk-vs-paper-altitude]]