# Chain of context rule > Source: > Published: 2026-06-09 15:35:56+00:00 Chain of context is an operating model for making projects navigable by stateless agents. It is a way to organize files for agent ergonomics: make the filesystem easy to scan, sort, follow, and trust. The core idea: a human or AI agent should be able to land in a repo or folder, run `ls` and grep, read a few well-named files, follow links, and reconstruct what happened without needing a person to re-explain it. This matters because LLM sessions are stateless by default. They start cold. If the project is a pile of `download.txt` , `notes-final-v2.md` , and disconnected artifacts, the agent loses time rediscovering context and risks making bad assumptions. If the project is organized for progressive discovery, the filesystem becomes the memory scaffold. Chain of context turns the working environment into onboarding. The environment should answer: - What is this? - When did it happen? - Why does it matter? - What is the source of truth? - What should I read next? No single file needs to explain everything. Each file only needs to be named clearly, placed correctly, and linked to the next useful piece of context. Names should carry meaning. When a file is tied to a date, put the ISO date first: `YYYY-MM-DD-description.md` . This makes plain filesystem views sortable and lets agents reconstruct sequence from `ls` before opening anything. Use names like: `2026-04-05-first-meeting-summary.md` `status-report-feedback-classification.md` `2026-05-26-roadmap-weekly-dependencies.md` Avoid names like: `download.txt` `notes.md` `final-v2-real.md` A future agent should understand the rough purpose of a file from reading it before opening it. Structure should work like a CLI or a small wiki: - shallow overview first - deeper detail second - source artifacts last The agent should be able to move from folder → README/index → dated note → source transcript/MR/email/doc without guessing. Good structure lets context accumulate gradually instead of requiring a giant upfront explanation. This saves time, tokens, and money. Use hyperlinks/addressable pointers as connective tissue. Prefer linking to the source of truth over duplicating it. A durable note can summarize, but it should point to the artifact, transcript, issue, PR, email, or doc that supports the summary. The goal is not to create more prose. The goal is to preserve navigability. These serve different jobs. They are not prerequisites and can be overkill. Use them contextually. The front door for a folder. Use it to answer: - what this folder is - what is current - where the important files live - what someone should read next `README.md` works well for folders in a repo. `index.md` works well for wiki-style folders. They should orient, not explain everything. Good entry shape: ``` # Project Name One-sentence purpose. ## Current - Status: active - Source of truth: [Hosted doc](https://example.com) ## Map - [daily-log/](daily-log/) — dated breadcrumbs - [research/](research/) — durable topic notes - [sources/](sources/) — source artifacts and exports ``` Contextual operating rules for agents. Use it for behavior and constraints an agent should follow in this folder: - source-of-truth rules - sync rules - naming conventions - commands to run before editing - things not to touch - local workflow expectations The root `AGENTS.md` should stay high-level. Nested `AGENTS.md` files can be more specific to a folder, dataset, client, or workflow. Good entry shape: ``` # Agent Instructions - Read `README.md` first. - Preserve source artifacts; summarize by linking to them. - Before editing `data/current.csv`, pull the hosted source and confirm parity. - Add short dated breadcrumbs to `daily-log/` when project state changes. ``` A dated, append-only chain-of-context index. Use it for what happened today: - branch created - MR opened - eval run - doc updated - meeting transcript saved - subtle bug diagnosed - local state changed Keep entries short. Link to the artifact. Do not duplicate the artifact. 1 file per day is good. Good entry shape: ``` # 2026-06-09 - 14:25 — Linked `data/current-metrics.csv` to hosted spreadsheet ``; sync rules in `data/AGENTS.md`. - 14:40 — Saved meeting summary in `meetings/2026-06-09-planning-summary.md`; source transcript remains in `sources/`. ``` Topic-organized knowledge that should be findable later. Use it for refined understanding: - architecture - product decisions - data model discoveries - recurring workflows - implementation notes - refined and meaningful research Update these when understanding changes. The idea is taken from here: [https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) - use this as reference but don't let it over complicate things. Preferences about how to work, not project state. Use memory for durable collaboration preferences, not for branches, commits, or one-off project facts. Memories should be the concern of Agents and not saved in repo. ``` example-project/ README.md AGENTS.md daily-log/ 2026-06-09.md research/ workflow-notes.md sources/ 2026-06-09-meeting-transcript.md outputs/ 2026-06-09-project-brief.md ``` The `README.md` orients. `AGENTS.md` tells agents how to behave. `daily-log/` preserves sequence. `research/` holds durable understanding. `sources/` preserves provenance. `outputs/` holds deliverables. When deciding where something goes, ask: - Is it the front door for a folder? Put it in `README.md` or`index.md` . Does it help create a mental map quickly? - Is it an operating rule for agents? Put it in `AGENTS.md` . - Is it dated and tied to what happened in a session? Put a short pointer in the daily log. - Is it durable and should be findable by topic? Put it in the wiki or a research/doc folder. - Is it a source artifact? Preserve it with a descriptive name and link to it. ALWAYS LET THE DOMAIN DRIVE THE ARCHITECTURE. These are guidlines. The philosophy is more important. Coding agents do not need perfect memory if the project has a good chain of context. They need: - names that explain themselves - folders that imply where to go next - indexes that orient quickly - links that preserve provenance - daily breadcrumbs that show sequence This reduces repeated rediscovery, prevents context drift, and makes it easier for future sessions, teammates, and agents to pick up without re-deriving decisions. In short: chain of context is not documentation overhead. It is information architecture for stateless collaborators.