Context Substrate

A shared context layer that agents read from and write to before and after doing work — a queryable medium for the knowledge that accumulates as agents operate on a codebase (what worked, what didn't, conventions, patterns, decisions). Its defining properties are what separate it from a pile of docs: it is agent-first, not human-first (a human "almost never runs this command"); it is structured, not prose, so it is cheap to query and dense to store; it is anchored to specific sections of the code (a file, directory, module), so an agent about to touch src/cli/main.ts can pull exactly the records relevant to that path; and it is dynamic, updated at the throughput LLMs produce rather than curated by hand.

The demoed instance is mulch (an agent-first CLI, ml): agents ml prime at session start to inject relevant records, scope-load per file with ml prime --files <path>, and ml record <domain> --type <convention|pattern|failure|decision|reference|guide> --description "…" before finishing. Records are typed, timestamped, ID'd, per-file-anchored, and carry evidence links auto-populated from git (--evidence-gh, --evidence-seeds, --relates-to); writes are atomic so multiple agents can record concurrently. A query returns structured entries grouped by domain with staleness ("updated 20h ago") and ml doctor / ml prune for integrity and archival — "no silent caps" applied to agent memory.

The substrate is the agent-first, structured relative of the AI Second Brain (a personal, human+agent store whose virtue is being "just files"). It is the same query-first storage discipline as Query-Shaped Storage, and it is delivered as a CLI Tools over MCP Servers surface precisely because agents drive it. The load-bearing — and contentious — claim is that for this agent-to-agent channel, structured data beats markdown; see the tension noted below and in the distillate.

Claims

A context substrate is a queryable layer agents read from and write to, anchored to specific sections of the codebase, so an agent primes exactly the relevant prior knowledge before working. principle — durable: the value of accumulated agent knowledge is realised only if it is retrievable at the point of use; anchoring retrieval to the code being touched is what makes priming cheap and relevant.
The substrate should be agent-first, not human-first — written for agents to query, which a human almost never runs directly. best practice — context: the machine-to-machine memory channel of a codebase (distinct from a human-facing knowledge base); "best" holds because the reader is the model, so it should be optimised for machine query, not human browsing.
For an agent-first, high-throughput store, structured data beats markdown — it reduces ambiguity, forces concision, and is queryable from the start instead of grepped. (best practice) — context: the agent-to-agent substrate specifically, not human knowledge; markdown "could work" but rots, goes stale, and invites verbose creative writing. This is in explicit tension with AI Second Brain's "boring markdown is beautiful / just files" — the axis that reconciles them is who reads it (agent-only, machine-queried → structured; human+agent, portable → markdown). Do not read it as an invariant that markdown is always wrong.
The substrate must be dynamic because LLMs produce far more output than humans can — a static store can't keep pace. observation — the throughput asymmetry is why hand-maintained markdown directories become "extremely difficult to maintain over time."
Structure the store from the get-go so it is queryable without grepping through prose. best practice — context: stores you will query programmatically and often; structuring up front trades a little authoring rigidity for cheap, unambiguous retrieval later.
A substrate like this is lightweight — buildable "in an afternoon" with no servers or fancy tools. observation — the implementation cost is low; the value is in the discipline of priming/recording, not in heavy infrastructure (Agentic Simplicity).

AI Second Brain — the human+agent, "just files" cousin; the substrate is the agent-first, structured version, and the two hold the graph's live tension over structured-vs-markdown.
Query-Shaped Storage — the substrate is query-first storage: shape it by how agents will ask, anchored to the code they touch.
CLI Tools over MCP Servers — the substrate is delivered as an agent-driven CLI (ml, sd), the token- efficient, own-the-contract surface agents prefer.
Evergreen vs Volatile Context — the ingest-discipline question for what the substrate should hold vs leave reachable; typed failure/decision records are the evergreen kind.
Decision Log — the substrate's typed decision records are a decision log made first-class and machine-queryable.
Agent Rituals — how the substrate is wired into a run: prime at the start, record before you finish.
Context Routing — anchoring records to files/dirs is routing at storage time; the substrate is the destination a CLAUDE.md router points agents to.
Extended Mind — the principle altitude: the substrate is extended cognition for agents, admitted by the Parity Principle's role-not-mechanism test (structured records need not resemble a context window to count as memory).
Distillate: The Agentic Engineering Meta
Distillate: Andy Clark — What is Extended Mind? (Closer To Truth)

Context Substrate

Claims

Related

Linked from