Learning AI-DLC building a game, part 14: the memory layers

This is part 14 of a series on learning AI-DLC by building a game, World Rift Conflict, in Godot with an AWS backend. Part 1 set it up, and part 13 closed the UI work with the first desktop release. This one is a deep-dive: how AI-DLC remembers what it learned.

Parts so far:

• Part 1: setup
• Part 2: a proof of concept
• Part 3: automated E2E tests
• Part 4: what the reviews caught
• Part 5: inside a stage
• Part 6: a bugfix intent
• Part 7: ideation
• Part 8: inception
• Part 9: an AppSync deploy error
• Part 10: walking skeleton
• Part 11: retrospective
• Part 12: guards and hooks
• Part 13: a UI pass and a release
• Part 14: the memory layers
• Part 15: the agents and roles

TL;DR

1. An agent forgets everything between sessions. AI-DLC's memory is four Markdown files of rules, read at the start of every session: org, team, project and phase.
2. The layers only add. A narrower layer may make a broader rule more specific, but a rule that contradicts a broader one is refused, not applied.
3. Each file has one writer. The framework ships org.md and the phase files. A tool writes team.md at the practices interview. Learned rules go to project.md.
4. At the end of each stage, AI-DLC asks "Anything to add for next time?". Over six pieces of work, that wrote 53 rules, and the audit has one RULE_LEARNED row for each.
5. All 53 went to the project file. 41 of them are corrections to how the agent works with me, not facts about the game.

Why an agent needs memory

Every Claude Code session starts empty. Whatever an agent learned yesterday, for example that ampx exits 0 after a failed deploy, is gone today unless it was written down where the next session will read it.

AI-DLC writes it down as rules, in plain Markdown files in the repository, under aidlc/spaces/default/memory/. They are committed like code, so the memory has a history, and I can read and review every line of it.

Four files, one chain

The framework calls the order "a strict-additive five-layer chain": org → team → project → phase → stage. The fifth layer, stage, is "reserved for future use", so in practice there are four:

Layer	File	What it holds here	Who writes it
Org	org.md	framework defaults: trunk-based work, the default testing posture, conversation-language rules	the framework
Team	team.md	how we work: branches, the pre-push hook, testing posture, deployment, code style	a tool, at the practices interview
Project	project.md	53 learned rules, plus 11 affirmed Mandated and Forbidden rules	the learnings ritual and the practices tool
Phase	phases/*.md	guardrails per phase, for example "no implementation details in ideation artifacts"	the framework

"Strict-additive" means every applicable rule reaches the agent, and nothing is dropped at run time. A narrower rule can specialize a broader one. It cannot overrule it. The framework's reading guide is plain about it: "A narrower statement that contradicts broader policy is an admission error, not an override."

How the rules reach every agent

Claude Code loads them through its own CLAUDE.md mechanism. .claude/CLAUDE.md imports .claude/rules/aidlc.md, and that file has seven @ imports, one per memory file.

The imports do not point at the files I edit. They point at aidlc/active-memory/, a git-ignored copy that the engine rewrites at session start and with each step. Each copy carries one extra first line: "AI-DLC keeps this copy in step with aidlc/spaces/default/memory/org.md. Edit that file; this copy is replaced."

Helper agents do not see the session's CLAUDE.md context in the same way, so a hook delivers the rules to them. Before every hand-off to a helper agent, it appends the whole rule bundle to the agent's brief. In this project that bundle is about 30 KB. It is also why Claude Code's auto mode once refused a hand-off: a hook had changed the call after auto mode reviewed it.

One writer per file

org.md and the phase files came with the framework. I have not changed them, and their ## Corrections sections are still empty.

team.md says in its header: "Edit at the gate, not directly." It is written by practices-promote, a tool that runs when I approve the practices interview. It replaces five sections of team.md and appends the hard rules to project.md. The tool's source explains why a tool does it and not the agent. When the stage told the model to write the files itself, the model "hallucinates a sensitive-file permission policy that does not actually exist", stops, and "the workflow bricks". With a tool, the path is never the model's write target.

The interview ran three times here:

• 2026-10-27: the first run set the local merge with a pre-push hook, a separate test backend, and acceptance checks first. It added 2 Mandated rules, such as "ALWAYS tell the person when a push to GitHub is due", and 3 Forbidden ones, such as "NEVER push to GitHub from an agent".
• 2026-10-29: for the game itself. Branch per unit, the 80% coverage floor, multi-client end-to-end tests, and 6 more hard rules: the $50 monthly cost cap, players 13 and over, no pay-to-win, no card data, the checkout off until costs are known, and data terms that allow a game.
• 2026-11-06: for the UI work. Screen-fit tests, window sizes, and the contrast check. No new hard rules.

project.md gets everything learned along the way.

The learnings ritual

The ritual runs at the end of every stage, between "the stage is done" and the approval gate. The framework describes it as "tool-as-actor": a tool, aidlc-learnings.ts, finds candidate lessons in the stage's diary and shows them, and "the user decides keep / heading / scope". The question "Anything to add for next time?" is asked even when there are no candidates.

A kept note becomes one line in project.md, under a heading picked by kind: testing notes go to Testing Posture, prohibitions to Forbidden, anything else to Corrections. Each line ends with a date and a hidden comment:

- Deploy wrappers judge success by the tool's error lines as well as its exit code, because ampx exits 0 after a failed hotswap. (learned 2026-10-30) <!-- cid:261029-game-idea-brainstorm:code-generation:3317316715a5… -->

The comment names the piece of work, the stage, and a hash of the text. The hash stops the same lesson being written twice, for example after a crash. The agent never edits the file itself: "The orchestrator never Edits a rule or sensor file directly."

Counted in this project:

• 53 learned rules in project.md, and 53 RULE_LEARNED rows in the audit. They match one for one.
• 45 were offered by AI-DLC and 8 were mine, added at the "Anything to add?" question.
• By heading: Corrections 41, Testing Posture 8, Deployment 3, Forbidden 1.
• By piece of work: the game build 35, the end-to-end test kit 10, the sign-in proof of concept 8, the UI work 0.

What the rules say

Most of the useful ones came from something that broke. A few, word for word:

• "Before the first deploy of an AppSync JavaScript resolver, check each one with aws appsync evaluate-code…" That came from the deploy error in part 9.
• "Code that reads a secret or key trims surrounding whitespace before using it… (the stored Stripe key broke every checkout call this way)."
• "A server host or its start-up script is checked by a real fresh deploy before the unit's checkpoint… three live-host start-up defects passed every local test and showed only on the first real boot."
• "npm audit --omit=dev at a root that holds only devDependencies checks nothing and always passes."

The other kind is about the agent itself. 41 of the 53 sit under Corrections, and most of those are about how it should work with me: "Write every guided question with at most four options… so it fits one picker." "When offering the person choices…, explain what each option is and why it matters." "Code Generation may ask the person questions when a fact found while planning contradicts… the approved requirements, instead of guessing."

What I did not expect

• Nothing reached the team layer. All 53 learned rules went to project.md. team.md and org.md have none. For a solo project that makes sense, but it means the team file only changes at an interview.
• The conflict check never fired. I found no refused, conflicting or duplicate learning in any audit file. Either my notes never contradicted the org rules, or the check had nothing to catch. The records cannot tell me which.
• The ritual goes quiet as the rules pile up. The UI work asked "Anything to add?" nine times. Eight answers were "Nothing to add", and the ninth, a note about window and text sizes, became no rule.
• The team file went stale. Before the third interview, the code scan found three lines in team.md that no longer matched the code. It said eight pre-push checks when there were 16, and it called the base image pinned by digest when it was pinned by tag. The interview kept the file as its baseline and fixed those facts.
• The tool writes every line it is given. When the third interview had no new hard rule, the agent wrote an HTML comment instead of the words "No new rule", "because the promotion tool appends every non-comment line to project.md as a rule".
• AI-DLC does not know your other tools. Its agents read only their own knowledge folders. The Godot skills I had installed reached them only through a section in the root CLAUDE.md and a project rule saved at a learnings question.

What I would tell myself

• Answer the learnings question every time. It costs one line, and it is the only path from "the agent got this wrong" to "the next session knows". Only 8 of the 53 rules were my own notes, but they include the EvaluateCode and ampx rules above, and the one that brought the Godot skills in.
• Write the reason into the rule. "because ampx exits 0 after a failed hotswap" is what lets a later agent apply the rule to a case it was not written for.
• Read project.md now and then. 53 rules is a lot of context in every session. Rules about the agent's own behaviour are worth checking: are they still true, and are any repeated?
• Do not edit the active copy. aidlc/active-memory/ is replaced on the next step. Edit aidlc/spaces/<space>/memory/, and edit team.md only through the interview.

What is next

Part 15 is the other half of how AI-DLC works: the agents. Fourteen roles, which of them actually ran as separate agents in this project, and the ones that never ran at all.