When I need a reminder of what we're doing.

Interpretable Context Methodology (ICM) is a systems-first AI orchestration framework developed by Jake Van Clief that replaces complex, multi-agent coding frameworks with a standard computer filesystem structure.

Instead of writing heavy Python or TypeScript code (using frameworks like LangChain, AutoGen, or Semantic Kernel) to pass data, manage memory, and coordinate agents, ICM maps sequential AI workflows directly onto numbered folders and plain Markdown files. A single Large Language Model (LLM)—such as Claude Code—serves as the primary engine, changing its "role" or behavior dynamically as it reads through the directory. [1, 2, 3, 4]

🏛️ The Core Philosophy: "Folder Structure as Architecture"

In traditional agentic development, workflows are locked inside compiled code, making them hard to audit, debug, or change. ICM treats the filesystem itself as the code: [2, 3, 5]

Sequential Stages: Workflows are broken down into numbered directories representing stages (e.g., 01_research/, 02_drafting/, 03_review/).
The Agentic Loop: The LLM scans the directory, executes the current folder's instructions, dumps the output file into the next folder, and advances down the pipeline.
Local Determinism: Heavy automation code is avoided. If a non-AI task is required (like downloading a file or converting a format), it is handled by simple, local Python shell scripts triggered by the directory structure. [1, 2, 3, 6]

📑 The 5-Layer Context Hierarchy

According to Van Clief’s research paper, "Interpretable Context Methodology: Folder Structure as Agentic Architecture," an LLM navigates a standardized five-layer context hierarchy within the workspace to understand its current bounds: [1, 6]

📁 WORKSPACE ROOT (Project Vault)

│

├── 📜 IDENTITY.md <- Layer 1: Global rules, brand identity, style guidelines

├── 📜 ROUTING.md <- Layer 2: Pipeline map; instructs LLM where to go next

│

├── 📁 01_Research/

│ ├── 📜 CONTEXT.md <- Layer 3: Stage Contract (Inputs, Rules, and Deliverables)

│ ├── 📁 reference_material/ <- Layer 4: Reference data, documentation, raw sources

│ └── 📁 working_artifacts/ <- Layer 5: The active output files and intermediate steps

Identity Layer: Outlines global rules, code styles, tones, or project parameters.
Routing Layer: A high-level layout telling the LLM which files to look at, which to skip, and how tasks link together.
Stage Contracts (CONTEXT.md): A file inside each numbered folder explicitly defining what the AI must do in that specific "room".
Reference Material: Static inputs, guidelines, or source documents needed for execution.
Working Artifacts: The actual text, code, or data produced by the AI at that stage. [2, 6, 7, 8, 9]

🛠️ Why Use ICM? Key Advantages

Human-in-the-Loop "Edit Surfaces": Because every intermediate step is just a standard Markdown or text file on your local machine, a human can pause the pipeline, open a file, edit it, and save it. The AI seamlessly picks up the human's manual edits in the next stage.
Token Efficiency: Instead of cramming an entire massive prompt history and project codebase into a single, bloated LLM chat window, the folder routing isolates context. The AI only opens and reads what is required for the current sub-folder.
Platform Agnostic & Future-Proof: Because the architecture relies entirely on the local operating system's filesystem, it cannot be rendered obsolete by LLM API updates. You can swap the underlying model (e.g., from GPT to Claude) instantly without rewrite overhead.
Separation of Concerns: You configure the factory, not the product. You design the folder rules once, and every time you run a project through those folders, it adheres perfectly to your specifications. [4, 6, 8, 9, 10, 11]

1 comment

When I need a reminder of what we're doing.