Documentation that maintains itself, written by the system that has to obey it.
MELT is based on a simple observation:
In AI-assisted codebases, changes rarely go wrong because the model cannot generate code.
They go wrong because architectural intent slowly evaporates across sessions, prompts, refactors, contributors, and time.
You do not lose architectural clarity all at once.
It drifts in fragments:
MELT treats architectural memory as a first-class engineering artifact.
Not documentation theater. Not endless ADR collections. Not AI hype.
Just durable operational memory for humans and agents.
Fair question. MELT doesn’t invent new primitives — it fixes how existing ones fail in practice.
AGENTS.md in most projects is descriptive and goes stale. It lists the stack and build commands, then sits unused. It tells the agent what exists, not what must never break.
ADRs are written for humans. Each decision is a full document — context, options, rationale. Great for an architect reading once a month. But an agent can’t hold 40 ADRs in context before every change. It’s an archive, not working memory.
MELT keeps a small, living DECISIONS.md that the agent actually reads before every change. Three principles make it work:
1. Capture only the non-obvious.
DECISIONS.md doesn’t repeat what the agent can already see in the code. It captures the choices the agent would otherwise get wrong by default — the ones that aren’t derivable from the codebase alone. “Use Noda Time, not DateTime.Now()” lives here because the model’s training pulls it toward DateTime.Now() no matter what the code around it does.
2. Stay concise.
Writing a rule down isn’t enough. Patterns like DateTime.Now() or new Date() are burned into the model’s priors — it has seen millions of them and only a handful of clock abstractions like IClock or java.time.Clock. A single rule competes against that default, and in a bloated file it loses. The rule has to be short, sharp, and impossible to scroll past.
3. Trim actively. A decision file that grows unbounded dies the same death as an unread ADR. Past a certain size, the model stops reading its own constitution. So you compress — actively, regularly. The stricter you filter on principle 1, the shorter the file, and the more reliably the model obeys it.
These three reinforce each other: tight selection keeps the file small, small files get read, read files actually constrain the agent. That loop — not the files themselves — is MELT.
AGENTS.md in your project folderAGENTS.md with name CLAUDE.mdDECISIONS.md in your project folderCHANGELOG.mddocs/concepts/docs/implemented/Read AGENTS.md and analyze the current repository structure, architecture, conventions, and implementation patterns.
Then:
1. Populate DECISIONS.md with the real architectural invariants, constraints, conventions, and cross-module rules already present in the system.
2. Remove placeholder sections that are not relevant.
3. Keep only durable decisions with long-term architectural value.
4. Do not invent abstractions, layers, or processes that do not already exist.
5. Prefer operational reality over idealized architecture.
6. Keep DECISIONS.md compact and maintainable.
7. If uncertain whether something is a durable invariant — omit it.
The goal is not to document everything.
The goal is to create durable architectural memory that future agent sessions can reliably obey.
This is a good starting point, but not a working document. Update it manually with the architectural intent that lives in your head — the model cannot extract what you have never written down.
MELT separates:
The temporary reasoning melts away.
The distilled system knowledge remains.
AGENTS.md / CLAUDE.md
DECISIONS.md
CHANGELOG.md
docs/
Operational contract for the coding agent.
Defines:
This is not architecture documentation.
It is agent operating procedure.
Durable architectural memory.
Contains:
This is intentionally compact.
Only information with long-term architectural value belongs here.
Temporary implementation trail.
During development it may contain:
At the end of a feature or session, the user may ask the agent to compress it into:
Signal remains.
Noise melts away.
Temporary feature specifications and implementation scaffolding.
Most concept documents are expected to disappear after implementation.
Concepts stable enough to survive implementation and become long-term system knowledge.
MELT is intentionally minimal.
The goal is not more process.
The goal is reducing architectural entropy in long-running AI-assisted development.
Documentation stops being something humans write and nobody reads.
It becomes durable memory shared between humans and agents.
Experimental.
Built from real-world usage in production systems with coding agents.