{"id":"11-memory-files","number":11,"slug":"claude-md-agents-md-memory-files","title":"CLAUDE.md and AGENTS.md: memory files that work","short":"Memory files that work","module":"Your toolkit","summary":"Your agent starts every session with amnesia. A memory file, CLAUDE.md or AGENTS.md, is how it learns your project: commands, conventions and gotchas. The best ones are short, grown from real mistakes, pruned as models improve, and shared with the team.","voice":"Eric","scenes":[{"template":"title","chapter":"Intro","narration":"Your agent wakes up with amnesia at the start of every session. It doesn't remember your build command, your conventions, or the mistake it made yesterday. One small file fixes that.","params":{"kicker":"Lesson 11","module":"Module 3 · Your toolkit","title":"CLAUDE.md and AGENTS.md: *memory files* that work","subtitle":"Short, specific, grown from real mistakes.","bubble":"Who am I? Where's the test command?","mood":"think"},"start":0.5,"dur":12.119,"words":[{"text":"Your","s":0.8,"e":1.04},{"text":"agent","s":1.2,"e":1.36},{"text":"wakes","s":1.44,"e":1.68},{"text":"up","s":1.76,"e":1.84},{"text":"with","s":1.92,"e":2},{"text":"amnesia","s":2.12,"e":2.64},{"text":"at","s":2.72,"e":2.8},{"text":"the","s":2.84,"e":2.88},{"text":"start","s":2.96,"e":3.2},{"text":"of","s":3.32,"e":3.44},{"text":"every","s":3.6,"e":3.76},{"text":"session.","s":3.84,"e":4.64},{"text":"It","s":4.72,"e":4.8},{"text":"doesn't","s":4.88,"e":5.04},{"text":"remember","s":5.12,"e":5.44},{"text":"your","s":5.52,"e":5.6},{"text":"build","s":5.72,"e":5.84},{"text":"command,","s":5.92,"e":6.56},{"text":"your","s":6.64,"e":6.72},{"text":"conventions,","s":6.8,"e":7.68},{"text":"or","s":7.76,"e":7.84},{"text":"the","s":7.88,"e":7.92},{"text":"mistake","s":8.08,"e":8.32},{"text":"it","s":8.4,"e":8.48},{"text":"made","s":8.56,"e":8.64},{"text":"yesterday.","s":8.72,"e":9.76},{"text":"One","s":9.88,"e":10},{"text":"small","s":10.08,"e":10.4},{"text":"file","s":10.48,"e":10.72},{"text":"fixes","s":10.88,"e":11.2},{"text":"that.","s":11.28,"e":11.76}]},{"template":"filetree","chapter":"What it is","narration":"The community standard calls AGENTS.md a README for agents: a predictable place for the instructions a coding agent needs. Claude Code reads CLAUDE.md the same way. It's loaded automatically at the start of every session. Big repos can add nested files in subfolders, and you can keep a personal one for your own preferences.","params":{"title":"A README for agents","sub":"Loaded automatically, every session.","root":"my-app/","items":[{"path":"AGENTS.md","note":"the project's memory","hl":true,"at":"README for agents"},{"path":"CLAUDE.md","note":"same idea, for Claude Code","at":"Claude Code"},{"path":"packages/","at":"Big repos"},{"path":"packages/billing/AGENTS.md","note":"nested, local rules","at":"nested"},{"path":"~/.claude/CLAUDE.md","note":"your personal one","at":"personal"}]},"start":12.619,"dur":21.874,"words":[{"text":"The","s":12.919,"e":13.079},{"text":"community","s":13.319,"e":13.559},{"text":"standard","s":13.639,"e":14.039},{"text":"calls","s":14.119,"e":14.359},{"text":"AGENTS.md","s":14.519,"e":15.639},{"text":"a","s":15.799,"e":15.879},{"text":"README","s":15.959,"e":16.439},{"text":"for","s":16.519,"e":16.599},{"text":"agents:","s":16.879,"e":17.559},{"text":"a","s":17.639,"e":17.719},{"text":"predictable","s":17.879,"e":18.199},{"text":"place","s":18.359,"e":18.599},{"text":"for","s":18.679,"e":18.759},{"text":"the","s":18.799,"e":18.839},{"text":"instructions","s":18.919,"e":19.559},{"text":"a","s":19.599,"e":19.639},{"text":"coding","s":19.719,"e":20.039},{"text":"agent","s":20.119,"e":20.359},{"text":"needs.","s":20.439,"e":21.119},{"text":"Claude","s":21.399,"e":21.639},{"text":"Code","s":21.719,"e":21.959},{"text":"reads","s":22.039,"e":22.279},{"text":"CLAUDE.md","s":22.359,"e":23.319},{"text":"the","s":23.399,"e":23.479},{"text":"same","s":23.559,"e":23.799},{"text":"way.","s":23.919,"e":24.119},{"text":"It's","s":24.599,"e":24.759},{"text":"loaded","s":24.839,"e":25.159},{"text":"automatically","s":25.239,"e":25.879},{"text":"at","s":25.919,"e":25.959},{"text":"the","s":26.039,"e":26.119},{"text":"start","s":26.199,"e":26.439},{"text":"of","s":26.559,"e":26.679},{"text":"every","s":26.799,"e":26.919},{"text":"session.","s":27.079,"e":27.959},{"text":"Big","s":28.039,"e":28.199},{"text":"repos","s":28.439,"e":28.679},{"text":"can","s":28.759,"e":28.839},{"text":"add","s":28.959,"e":29.079},{"text":"nested","s":29.159,"e":29.559},{"text":"files","s":29.719,"e":29.879},{"text":"in","s":29.959,"e":30.119},{"text":"subfolders,","s":30.239,"e":30.999},{"text":"and","s":31.119,"e":31.239},{"text":"you","s":31.319,"e":31.399},{"text":"can","s":31.479,"e":31.559},{"text":"keep","s":31.639,"e":31.719},{"text":"a","s":31.759,"e":31.799},{"text":"personal","s":31.879,"e":32.279},{"text":"one","s":32.359,"e":32.439},{"text":"for","s":32.519,"e":32.599},{"text":"your","s":32.679,"e":32.759},{"text":"own","s":32.839,"e":32.919},{"text":"preferences.","s":33.239,"e":33.879}]},{"template":"code","chapter":"What goes in","narration":"What goes in it? Only what the agent can't figure out by itself. How to build and test, including how to run a single test. Conventions you can't infer from the code. Gotchas that have bitten you before. And pointers to where things live.","params":{"file":"AGENTS.md","lang":"md","lines":["# Shop API","## Commands","- Test one file: `pnpm test path/to/file`","- Typecheck before committing: `pnpm tsc --noEmit`","## Conventions","- Money is integer cents. Never floats.","- New endpoints go through `src/api/router.ts`","## Gotchas","- Never edit generated files in `src/gen/`","- Architecture notes: docs/ARCHITECTURE.md"],"hl":[{"from":2,"to":4,"at":"build and test","label":"how to verify","tone":"good"},{"from":5,"to":7,"at":"Conventions","label":"can't be inferred","tone":"human"},{"from":8,"to":9,"at":"Gotchas","label":"learned the hard way","tone":"bad"},{"from":10,"to":10,"at":"pointers","label":"a map","tone":"agent"}]},"start":34.493,"dur":16.597,"words":[{"text":"What","s":34.793,"e":34.933},{"text":"goes","s":34.953,"e":35.153},{"text":"in","s":35.193,"e":35.313},{"text":"it?","s":35.353,"e":35.593},{"text":"Only","s":36.073,"e":36.393},{"text":"what","s":36.473,"e":36.553},{"text":"the","s":36.593,"e":36.633},{"text":"agent","s":36.713,"e":37.033},{"text":"can't","s":37.113,"e":37.353},{"text":"figure","s":37.433,"e":37.673},{"text":"out","s":37.753,"e":37.833},{"text":"by","s":37.913,"e":37.993},{"text":"itself.","s":38.113,"e":38.913},{"text":"How","s":39.193,"e":39.353},{"text":"to","s":39.433,"e":39.513},{"text":"build","s":39.593,"e":39.833},{"text":"and","s":39.913,"e":39.993},{"text":"test,","s":40.073,"e":40.793},{"text":"including","s":41.073,"e":41.353},{"text":"how","s":41.433,"e":41.513},{"text":"to","s":41.593,"e":41.673},{"text":"run","s":41.753,"e":41.833},{"text":"a","s":41.913,"e":41.993},{"text":"single","s":42.153,"e":42.393},{"text":"test.","s":42.473,"e":43.113},{"text":"Conventions","s":43.353,"e":43.993},{"text":"you","s":44.033,"e":44.073},{"text":"can't","s":44.233,"e":44.473},{"text":"infer","s":44.553,"e":44.953},{"text":"from","s":45.033,"e":45.113},{"text":"the","s":45.193,"e":45.273},{"text":"code.","s":45.353,"e":45.913},{"text":"Gotchas","s":46.153,"e":46.633},{"text":"that","s":46.673,"e":46.713},{"text":"have","s":46.793,"e":46.873},{"text":"bitten","s":46.953,"e":47.193},{"text":"you","s":47.233,"e":47.273},{"text":"before.","s":47.353,"e":48.033},{"text":"And","s":48.233,"e":48.473},{"text":"pointers","s":48.713,"e":49.113},{"text":"to","s":49.193,"e":49.273},{"text":"where","s":49.353,"e":49.433},{"text":"things","s":49.593,"e":49.833},{"text":"live.","s":49.913,"e":50.473}]},{"template":"quote","chapter":"Keep it short","narration":"The most common mistake is making it too long. Anthropic's guide suggests a brutal test. For each line, ask: would removing this cause the agent to make mistakes? If not, cut it. Bloated files cause the agent to ignore your actual instructions.","params":{"text":"For each line, ask: “Would removing this cause Claude to make mistakes?” *If not, cut it.*","who":"Anthropic","role":"Best practices for Claude Code","src":"code.claude.com docs"},"start":51.09,"dur":17.538,"words":[{"text":"The","s":51.39,"e":51.47},{"text":"most","s":51.59,"e":51.71},{"text":"common","s":51.79,"e":52.11},{"text":"mistake","s":52.27,"e":52.59},{"text":"is","s":52.67,"e":52.75},{"text":"making","s":52.83,"e":53.07},{"text":"it","s":53.15,"e":53.23},{"text":"too","s":53.31,"e":53.55},{"text":"long.","s":53.63,"e":54.27},{"text":"Anthropic's","s":54.51,"e":55.15},{"text":"guide","s":55.31,"e":55.47},{"text":"suggests","s":55.71,"e":55.99},{"text":"a","s":56.03,"e":56.19},{"text":"brutal","s":56.27,"e":56.67},{"text":"test.","s":56.75,"e":57.39},{"text":"For","s":57.63,"e":57.79},{"text":"each","s":57.91,"e":58.03},{"text":"line,","s":58.11,"e":58.59},{"text":"ask:","s":58.79,"e":59.07},{"text":"would","s":59.47,"e":59.63},{"text":"removing","s":59.75,"e":60.11},{"text":"this","s":60.23,"e":60.35},{"text":"cause","s":60.43,"e":60.67},{"text":"the","s":60.75,"e":60.79},{"text":"agent","s":60.83,"e":61.15},{"text":"to","s":61.19,"e":61.23},{"text":"make","s":61.31,"e":61.47},{"text":"mistakes?","s":61.59,"e":62.27},{"text":"If","s":62.51,"e":62.67},{"text":"not,","s":62.75,"e":63.31},{"text":"cut","s":63.39,"e":63.55},{"text":"it.","s":63.63,"e":63.79},{"text":"Bloated","s":64.19,"e":64.51},{"text":"files","s":64.59,"e":64.91},{"text":"cause","s":64.99,"e":65.23},{"text":"the","s":65.27,"e":65.31},{"text":"agent","s":65.39,"e":65.63},{"text":"to","s":65.71,"e":65.79},{"text":"ignore","s":65.87,"e":66.27},{"text":"your","s":66.35,"e":66.51},{"text":"actual","s":66.59,"e":66.91},{"text":"instructions.","s":66.99,"e":68.03}]},{"template":"stat","chapter":"Keep it short","narration":"There's a reason. Dex Horthy notes that frontier models can only follow roughly a hundred and fifty to two hundred instructions with good consistency. Beyond that, they're half attending to all of them. And your memory file shares that budget with the system prompt, the tools and your request.","params":{"items":[{"value":"~150–200","label":"instructions a frontier model follows consistently","sub":"system prompt, tools, memory file and your prompt all share this budget","tone":"agent","at":"hundred and fifty"}],"src":"Dex Horthy, “Everything We Got Wrong About Research-Plan-Implement”"},"start":68.628,"dur":18.348,"words":[{"text":"There's","s":68.928,"e":69.168},{"text":"a","s":69.208,"e":69.248},{"text":"reason.","s":69.328,"e":69.808},{"text":"Dex","s":70.368,"e":70.688},{"text":"Horthy","s":70.728,"e":71.088},{"text":"notes","s":71.168,"e":71.408},{"text":"that","s":71.488,"e":71.568},{"text":"frontier","s":71.648,"e":72.048},{"text":"models","s":72.128,"e":72.448},{"text":"can","s":72.528,"e":72.768},{"text":"only","s":72.848,"e":73.008},{"text":"follow","s":73.168,"e":73.488},{"text":"roughly","s":73.568,"e":73.968},{"text":"a","s":74.048,"e":74.128},{"text":"hundred","s":74.168,"e":74.368},{"text":"and","s":74.448,"e":74.608},{"text":"fifty","s":74.715,"e":74.928},{"text":"to","s":75.008,"e":75.248},{"text":"two","s":75.328,"e":75.408},{"text":"hundred","s":75.488,"e":75.728},{"text":"instructions","s":75.808,"e":76.448},{"text":"with","s":76.528,"e":76.608},{"text":"good","s":76.688,"e":76.848},{"text":"consistency.","s":76.928,"e":77.728},{"text":"Beyond","s":78.288,"e":78.528},{"text":"that,","s":78.608,"e":79.088},{"text":"they're","s":79.128,"e":79.328},{"text":"half","s":79.448,"e":79.568},{"text":"attending","s":79.688,"e":79.968},{"text":"to","s":80.048,"e":80.128},{"text":"all","s":80.208,"e":80.288},{"text":"of","s":80.368,"e":80.448},{"text":"them.","s":80.528,"e":80.968},{"text":"And","s":81.248,"e":81.328},{"text":"your","s":81.408,"e":81.488},{"text":"memory","s":81.648,"e":81.808},{"text":"file","s":81.888,"e":82.208},{"text":"shares","s":82.288,"e":82.608},{"text":"that","s":82.688,"e":82.848},{"text":"budget","s":82.928,"e":83.168},{"text":"with","s":83.248,"e":83.328},{"text":"the","s":83.368,"e":83.408},{"text":"system","s":83.488,"e":83.808},{"text":"prompt,","s":83.888,"e":84.368},{"text":"the","s":84.408,"e":84.448},{"text":"tools","s":84.608,"e":85.008},{"text":"and","s":85.168,"e":85.328},{"text":"your","s":85.408,"e":85.488},{"text":"request.","s":85.768,"e":86.368}]},{"template":"chat","chapter":"Grow it from mistakes","narration":"So how do you write a good one? Don't write it all up front. Grow it from real mistakes. Mitchell Hashimoto says every line in Ghostty's agents file is based on a bad agent behavior, and together they almost completely resolved them. Boris Cherny's habit is the same: when the agent slips, tell it to add the lesson to the file.","params":{"messages":[{"from":"agent","text":"Added the new endpoint in `src/server.ts`.","tone":"bad","at":"mistakes"},{"from":"you","text":"Endpoints go through `src/api/router.ts`. Fix it, then add that rule to AGENTS.md so you remember next time.","at":"Boris"},{"from":"agent","text":"Fixed, and added: “New endpoints go through src/api/router.ts.”","tone":"good","at":"add the lesson"}]},"start":86.976,"dur":22.344,"words":[{"text":"So","s":87.276,"e":87.596},{"text":"how","s":87.916,"e":87.996},{"text":"do","s":88.076,"e":88.116},{"text":"you","s":88.156,"e":88.196},{"text":"write","s":88.236,"e":88.396},{"text":"a","s":88.436,"e":88.476},{"text":"good","s":88.556,"e":88.636},{"text":"one?","s":88.716,"e":89.276},{"text":"Don't","s":89.596,"e":89.836},{"text":"write","s":89.916,"e":90.076},{"text":"it","s":90.156,"e":90.236},{"text":"all","s":90.316,"e":90.396},{"text":"up","s":90.476,"e":90.556},{"text":"front.","s":90.636,"e":91.036},{"text":"Grow","s":91.516,"e":91.756},{"text":"it","s":91.836,"e":91.916},{"text":"from","s":92.076,"e":92.236},{"text":"real","s":92.396,"e":92.556},{"text":"mistakes.","s":92.636,"e":93.596},{"text":"Mitchell","s":93.916,"e":94.236},{"text":"Hashimoto","s":94.356,"e":94.876},{"text":"says","s":94.996,"e":95.116},{"text":"every","s":95.276,"e":95.596},{"text":"line","s":95.676,"e":95.916},{"text":"in","s":95.956,"e":95.996},{"text":"Ghostty's","s":96.076,"e":96.556},{"text":"agents","s":96.636,"e":96.956},{"text":"file","s":97.036,"e":97.356},{"text":"is","s":97.436,"e":97.516},{"text":"based","s":97.596,"e":97.836},{"text":"on","s":97.916,"e":97.996},{"text":"a","s":98.036,"e":98.076},{"text":"bad","s":98.236,"e":98.476},{"text":"agent","s":98.556,"e":98.796},{"text":"behavior,","s":98.876,"e":99.756},{"text":"and","s":99.836,"e":99.916},{"text":"together","s":99.996,"e":100.396},{"text":"they","s":100.556,"e":100.716},{"text":"almost","s":100.876,"e":101.036},{"text":"completely","s":101.116,"e":101.756},{"text":"resolved","s":101.996,"e":102.236},{"text":"them.","s":102.316,"e":102.676},{"text":"Boris","s":102.956,"e":103.276},{"text":"Cherny's","s":103.356,"e":103.756},{"text":"habit","s":103.876,"e":103.996},{"text":"is","s":104.076,"e":104.156},{"text":"the","s":104.196,"e":104.236},{"text":"same:","s":104.396,"e":105.116},{"text":"when","s":105.156,"e":105.196},{"text":"the","s":105.276,"e":105.316},{"text":"agent","s":105.356,"e":105.676},{"text":"slips,","s":105.756,"e":106.476},{"text":"tell","s":106.556,"e":106.716},{"text":"it","s":106.756,"e":106.796},{"text":"to","s":106.876,"e":106.956},{"text":"add","s":107.036,"e":107.196},{"text":"the","s":107.276,"e":107.356},{"text":"lesson","s":107.436,"e":107.756},{"text":"to","s":107.836,"e":107.916},{"text":"the","s":107.956,"e":107.996},{"text":"file.","s":108.076,"e":108.716}]},{"template":"statement","chapter":"Prune it","narration":"Then prune it, because models keep improving. A rule that was essential six months ago can over-constrain today's model. Thariq Shihipar from the Claude Code team expects memory files to shrink over time, and the team itself cut most of Claude Code's own system prompt for newer models.","params":{"text":"Yesterday's workaround can be today's *handcuff*. Prune as models improve.","sub":"The Claude Code team cut most of its own system prompt for newer models.","art":"pen","tone":"agent","sync":false},"start":109.32,"dur":18.426,"words":[{"text":"Then","s":109.62,"e":109.86},{"text":"prune","s":109.94,"e":110.18},{"text":"it,","s":110.26,"e":110.74},{"text":"because","s":110.82,"e":111.06},{"text":"models","s":111.14,"e":111.54},{"text":"keep","s":111.62,"e":111.86},{"text":"improving.","s":111.94,"e":112.78},{"text":"A","s":113.06,"e":113.14},{"text":"rule","s":113.26,"e":113.38},{"text":"that","s":113.42,"e":113.46},{"text":"was","s":113.54,"e":113.62},{"text":"essential","s":113.9,"e":114.18},{"text":"six","s":114.26,"e":114.5},{"text":"months","s":114.58,"e":114.74},{"text":"ago","s":114.82,"e":115.14},{"text":"can","s":115.22,"e":115.46},{"text":"over-constrain","s":115.58,"e":116.26},{"text":"today's","s":116.34,"e":116.66},{"text":"model.","s":116.74,"e":117.06},{"text":"Thariq","s":117.62,"e":117.94},{"text":"Shihipar","s":118.02,"e":118.58},{"text":"from","s":118.66,"e":118.74},{"text":"the","s":118.78,"e":118.82},{"text":"Claude","s":118.9,"e":119.22},{"text":"Code","s":119.34,"e":119.46},{"text":"team","s":119.54,"e":119.78},{"text":"expects","s":120.1,"e":120.5},{"text":"memory","s":120.58,"e":120.82},{"text":"files","s":120.98,"e":121.22},{"text":"to","s":121.3,"e":121.38},{"text":"shrink","s":121.46,"e":121.7},{"text":"over","s":121.78,"e":122.02},{"text":"time,","s":122.18,"e":122.74},{"text":"and","s":122.78,"e":122.82},{"text":"the","s":122.9,"e":122.94},{"text":"team","s":122.98,"e":123.14},{"text":"itself","s":123.26,"e":123.62},{"text":"cut","s":123.7,"e":123.86},{"text":"most","s":123.94,"e":124.18},{"text":"of","s":124.26,"e":124.3},{"text":"Claude","s":124.34,"e":124.58},{"text":"Code's","s":124.66,"e":124.98},{"text":"own","s":125.06,"e":125.22},{"text":"system","s":125.3,"e":125.54},{"text":"prompt","s":125.62,"e":125.94},{"text":"for","s":126.02,"e":126.1},{"text":"newer","s":126.18,"e":126.42},{"text":"models.","s":126.66,"e":127.14}]},{"template":"stack","chapter":"A map, not an encyclopedia","narration":"For big projects, think of the file as a map. OpenAI's harness engineering team keeps a top-level agents file of about a hundred lines that works as a table of contents, pointing to deeper documents like architecture and design notes. The agent reads those only when it needs them.","params":{"title":"A map, not an encyclopedia","sub":"OpenAI's harness engineering setup","layers":[{"label":"AGENTS.md","sub":"~100 lines: the table of contents","tone":"agent","icon":"list","at":"hundred lines"},{"label":"ARCHITECTURE.md","sub":"read when touching structure","tone":"paper","icon":"layers","at":"architecture"},{"label":"DESIGN.md","sub":"read when touching UI","tone":"paper","icon":"pen","at":"design"},{"label":"plans/, references/","sub":"read when needed","tone":"paper","icon":"doc","at":"only when"}]},"start":127.746,"dur":18.583,"words":[{"text":"For","s":128.046,"e":128.206},{"text":"big","s":128.286,"e":128.446},{"text":"projects,","s":128.526,"e":129.406},{"text":"think","s":129.486,"e":129.566},{"text":"of","s":129.606,"e":129.646},{"text":"the","s":129.686,"e":129.726},{"text":"file","s":129.886,"e":130.206},{"text":"as","s":130.286,"e":130.366},{"text":"a","s":130.406,"e":130.446},{"text":"map.","s":130.606,"e":131.246},{"text":"OpenAI's","s":131.566,"e":132.206},{"text":"harness","s":132.286,"e":132.606},{"text":"engineering","s":132.686,"e":133.166},{"text":"team","s":133.246,"e":133.566},{"text":"keeps","s":133.646,"e":133.806},{"text":"a","s":133.886,"e":133.966},{"text":"top-level","s":134.046,"e":134.526},{"text":"agents","s":134.686,"e":135.086},{"text":"file","s":135.166,"e":135.486},{"text":"of","s":135.566,"e":135.646},{"text":"about","s":135.766,"e":135.886},{"text":"a","s":135.966,"e":136.046},{"text":"hundred","s":136.086,"e":136.366},{"text":"lines","s":136.446,"e":136.846},{"text":"that","s":137.086,"e":137.246},{"text":"works","s":137.366,"e":137.486},{"text":"as","s":137.566,"e":137.646},{"text":"a","s":137.686,"e":137.726},{"text":"table","s":137.886,"e":138.046},{"text":"of","s":138.126,"e":138.206},{"text":"contents,","s":138.486,"e":139.166},{"text":"pointing","s":139.286,"e":139.566},{"text":"to","s":139.646,"e":139.726},{"text":"deeper","s":139.766,"e":139.966},{"text":"documents","s":140.046,"e":140.606},{"text":"like","s":140.686,"e":140.926},{"text":"architecture","s":141.286,"e":141.646},{"text":"and","s":141.686,"e":141.726},{"text":"design","s":141.806,"e":142.126},{"text":"notes.","s":142.206,"e":143.086},{"text":"The","s":143.166,"e":143.246},{"text":"agent","s":143.446,"e":143.646},{"text":"reads","s":143.806,"e":143.966},{"text":"those","s":144.166,"e":144.366},{"text":"only","s":144.446,"e":144.686},{"text":"when","s":144.766,"e":144.846},{"text":"it","s":144.886,"e":144.926},{"text":"needs","s":145.006,"e":145.246},{"text":"them.","s":145.326,"e":145.726}]},{"template":"statement","chapter":"Trails","narration":"Thorsten Ball calls nested files trails. Drop a small agents file into a subfolder, and the agent picks it up when it works there. The billing package can carry its own rules without cluttering everything else.","params":{"text":"Nested memory files leave *trails* for the agent.","sub":"Rules for packages/billing live in packages/billing. — Thorsten Ball","art":"branch","tone":"human","sync":false},"start":146.329,"dur":13.541,"words":[{"text":"Thorsten","s":146.629,"e":147.109},{"text":"Ball","s":147.189,"e":147.429},{"text":"calls","s":147.509,"e":147.749},{"text":"nested","s":147.829,"e":148.149},{"text":"files","s":148.309,"e":148.709},{"text":"trails.","s":148.949,"e":149.789},{"text":"Drop","s":150.069,"e":150.309},{"text":"a","s":150.349,"e":150.389},{"text":"small","s":150.469,"e":150.709},{"text":"agents","s":150.869,"e":151.189},{"text":"file","s":151.269,"e":151.509},{"text":"into","s":151.589,"e":151.749},{"text":"a","s":151.829,"e":151.909},{"text":"subfolder,","s":151.989,"e":152.789},{"text":"and","s":152.829,"e":152.869},{"text":"the","s":152.949,"e":153.029},{"text":"agent","s":153.109,"e":153.349},{"text":"picks","s":153.429,"e":153.589},{"text":"it","s":153.669,"e":153.749},{"text":"up","s":153.829,"e":153.909},{"text":"when","s":153.989,"e":154.069},{"text":"it","s":154.109,"e":154.149},{"text":"works","s":154.229,"e":154.469},{"text":"there.","s":154.589,"e":154.949},{"text":"The","s":155.189,"e":155.269},{"text":"billing","s":155.429,"e":155.589},{"text":"package","s":155.669,"e":155.989},{"text":"can","s":156.069,"e":156.229},{"text":"carry","s":156.349,"e":156.469},{"text":"its","s":156.589,"e":156.709},{"text":"own","s":156.789,"e":156.949},{"text":"rules","s":157.029,"e":157.349},{"text":"without","s":157.549,"e":157.749},{"text":"cluttering","s":157.829,"e":158.229},{"text":"everything","s":158.389,"e":158.549},{"text":"else.","s":158.629,"e":159.269}]},{"template":"compare","chapter":"Team habits","narration":"Two team habits. Check the file into the repo, so everyone benefits from every lesson; Boris calls it a network effect. And don't copy a stranger's giant setup. Birgitta Böckeler warns you'll inherit contradictions you can't see, and then blame the agent for following them.","params":{"left":{"title":"Don't","items":["Paste a stranger's 800-line setup","Front-load rules “just in case”","Keep rules the model no longer needs"],"at":"don't copy"},"right":{"title":"Do","items":["Check it in: one team, one memory","Add a line per real mistake","Prune after model upgrades"],"at":"Check the file"}},"start":159.87,"dur":18.426,"words":[{"text":"Two","s":160.17,"e":160.41},{"text":"team","s":160.49,"e":160.73},{"text":"habits.","s":160.81,"e":161.57},{"text":"Check","s":161.85,"e":162.01},{"text":"the","s":162.05,"e":162.09},{"text":"file","s":162.17,"e":162.49},{"text":"into","s":162.57,"e":162.73},{"text":"the","s":162.81,"e":162.85},{"text":"repo,","s":162.89,"e":163.45},{"text":"so","s":163.53,"e":163.77},{"text":"everyone","s":163.85,"e":164.25},{"text":"benefits","s":164.33,"e":164.73},{"text":"from","s":164.81,"e":164.97},{"text":"every","s":165.13,"e":165.37},{"text":"lesson;","s":165.45,"e":166.33},{"text":"Boris","s":166.41,"e":166.73},{"text":"calls","s":166.85,"e":166.97},{"text":"it","s":167.05,"e":167.13},{"text":"a","s":167.21,"e":167.29},{"text":"network","s":167.37,"e":167.69},{"text":"effect.","s":167.77,"e":168.41},{"text":"And","s":168.65,"e":168.89},{"text":"don't","s":169.13,"e":169.37},{"text":"copy","s":169.53,"e":169.69},{"text":"a","s":169.73,"e":169.77},{"text":"stranger's","s":169.85,"e":170.41},{"text":"giant","s":170.45,"e":170.73},{"text":"setup.","s":170.89,"e":171.61},{"text":"Birgitta","s":171.65,"e":172.01},{"text":"Böckeler","s":172.09,"e":172.57},{"text":"warns","s":172.65,"e":172.97},{"text":"you'll","s":173.01,"e":173.13},{"text":"inherit","s":173.37,"e":173.61},{"text":"contradictions","s":173.77,"e":174.33},{"text":"you","s":174.41,"e":174.49},{"text":"can't","s":174.57,"e":174.81},{"text":"see,","s":174.97,"e":175.45},{"text":"and","s":175.53,"e":175.61},{"text":"then","s":175.69,"e":175.77},{"text":"blame","s":175.85,"e":176.01},{"text":"the","s":176.09,"e":176.25},{"text":"agent","s":176.45,"e":176.65},{"text":"for","s":176.73,"e":176.81},{"text":"following","s":176.89,"e":177.29},{"text":"them.","s":177.37,"e":177.69}]},{"template":"quiz","chapter":"Quick check","narration":"Quick check. Your memory file has grown to nine hundred lines, and the agent seems to ignore half of it. What's the best fix? Tap your answer.","params":{"q":"Your memory file is 900 lines and the agent ignores half of it. Best fix?","options":["Add IMPORTANT to every rule","Cut it to what prevents real mistakes; link out to deeper docs","Split it into three files that all load at startup","Switch to a model with a bigger context window"],"answer":1,"explain":"Too much guidance becomes no guidance. Keep what prevents mistakes; load the rest only when needed."},"start":178.296,"dur":14.486,"words":[{"text":"Quick","s":178.596,"e":178.836},{"text":"check.","s":178.916,"e":179.236},{"text":"Your","s":179.716,"e":179.796},{"text":"memory","s":179.876,"e":180.116},{"text":"file","s":180.276,"e":180.516},{"text":"has","s":180.596,"e":180.676},{"text":"grown","s":180.756,"e":180.916},{"text":"to","s":180.996,"e":181.156},{"text":"nine","s":181.236,"e":181.396},{"text":"hundred","s":181.476,"e":181.716},{"text":"lines,","s":181.876,"e":182.516},{"text":"and","s":182.636,"e":182.756},{"text":"the","s":182.796,"e":182.836},{"text":"agent","s":182.916,"e":183.236},{"text":"seems","s":183.316,"e":183.556},{"text":"to","s":183.596,"e":183.636},{"text":"ignore","s":183.716,"e":184.036},{"text":"half","s":184.116,"e":184.356},{"text":"of","s":184.436,"e":184.516},{"text":"it.","s":184.596,"e":185.156},{"text":"What's","s":185.236,"e":185.396},{"text":"the","s":185.436,"e":185.476},{"text":"best","s":185.596,"e":185.716},{"text":"fix?","s":185.796,"e":186.356},{"text":"Tap","s":186.596,"e":186.836},{"text":"your","s":186.916,"e":186.996},{"text":"answer.","s":187.156,"e":187.636}]},{"template":"exercise","chapter":"Try it","narration":"Let your agent audit its own memory file. This prompt asks it to justify every line and propose a short version that links out to deeper docs.","params":{"title":"Try it with your agent","intro":"Audit (or create) your memory file:","prompt":"Read our AGENTS.md / CLAUDE.md (create one if missing).\nFor each line, say whether removing it would make you err.\nPropose a version under 60 lines: commands (incl. single test),\nconventions you can't infer, gotchas. Link out to deeper docs."},"start":192.782,"dur":10.119,"words":[{"text":"Let","s":193.082,"e":193.322},{"text":"your","s":193.402,"e":193.482},{"text":"agent","s":193.562,"e":193.882},{"text":"audit","s":194.042,"e":194.282},{"text":"its","s":194.362,"e":194.602},{"text":"own","s":194.682,"e":194.842},{"text":"memory","s":194.922,"e":195.162},{"text":"file.","s":195.242,"e":195.842},{"text":"This","s":196.122,"e":196.282},{"text":"prompt","s":196.442,"e":196.762},{"text":"asks","s":196.842,"e":197.162},{"text":"it","s":197.242,"e":197.322},{"text":"to","s":197.362,"e":197.402},{"text":"justify","s":197.482,"e":198.042},{"text":"every","s":198.122,"e":198.442},{"text":"line","s":198.522,"e":198.922},{"text":"and","s":199.002,"e":199.082},{"text":"propose","s":199.162,"e":199.482},{"text":"a","s":199.562,"e":199.642},{"text":"short","s":199.722,"e":199.962},{"text":"version","s":200.042,"e":200.362},{"text":"that","s":200.442,"e":200.522},{"text":"links","s":200.602,"e":200.842},{"text":"out","s":200.922,"e":201.002},{"text":"to","s":201.082,"e":201.162},{"text":"deeper","s":201.242,"e":201.482},{"text":"docs.","s":201.562,"e":202.282}]},{"template":"recap","chapter":"Recap","narration":"Recap. A memory file is a README for agents. Fill it with what the agent can't infer. Keep it short, grow it from real mistakes, and prune it as models improve. Make it a map, and share it with your team. Next: giving your agent new abilities with tools and MCP.","params":{"items":["A README for agents, loaded every session","Only what it *can't infer*","Short: grown from mistakes, pruned over time","A map with links; checked in for the team"],"next":"Tools, CLIs and MCP","next_at":"Next"},"start":202.901,"dur":21.126,"words":[{"text":"Recap.","s":203.201,"e":203.841},{"text":"A","s":204.321,"e":204.401},{"text":"memory","s":204.481,"e":204.801},{"text":"file","s":204.881,"e":205.281},{"text":"is","s":205.361,"e":205.441},{"text":"a","s":205.521,"e":205.601},{"text":"README","s":205.681,"e":206.161},{"text":"for","s":206.241,"e":206.321},{"text":"agents.","s":206.601,"e":207.121},{"text":"Fill","s":207.361,"e":207.521},{"text":"it","s":207.601,"e":207.681},{"text":"with","s":207.761,"e":207.841},{"text":"what","s":207.921,"e":208.001},{"text":"the","s":208.081,"e":208.121},{"text":"agent","s":208.161,"e":208.481},{"text":"can't","s":208.641,"e":208.881},{"text":"infer.","s":208.961,"e":209.521},{"text":"Keep","s":210.001,"e":210.081},{"text":"it","s":210.161,"e":210.241},{"text":"short,","s":210.321,"e":211.041},{"text":"grow","s":211.161,"e":211.281},{"text":"it","s":211.321,"e":211.361},{"text":"from","s":211.441,"e":211.601},{"text":"real","s":211.681,"e":211.841},{"text":"mistakes,","s":211.921,"e":212.721},{"text":"and","s":212.761,"e":212.801},{"text":"prune","s":212.961,"e":213.201},{"text":"it","s":213.281,"e":213.441},{"text":"as","s":213.521,"e":213.601},{"text":"models","s":213.681,"e":213.921},{"text":"improve.","s":214.001,"e":214.561},{"text":"Make","s":215.041,"e":215.121},{"text":"it","s":215.201,"e":215.241},{"text":"a","s":215.281,"e":215.321},{"text":"map,","s":215.361,"e":215.921},{"text":"and","s":216.001,"e":216.081},{"text":"share","s":216.241,"e":216.401},{"text":"it","s":216.441,"e":216.481},{"text":"with","s":216.561,"e":216.641},{"text":"your","s":216.721,"e":216.801},{"text":"team.","s":216.881,"e":217.201},{"text":"Next:","s":218.081,"e":218.721},{"text":"giving","s":218.961,"e":219.201},{"text":"your","s":219.281,"e":219.361},{"text":"agent","s":219.441,"e":219.761},{"text":"new","s":219.841,"e":220.001},{"text":"abilities","s":220.321,"e":220.641},{"text":"with","s":220.721,"e":220.801},{"text":"tools","s":220.881,"e":221.281},{"text":"and","s":221.361,"e":221.521},{"text":"MCP.","s":221.601,"e":222.481}]}],"total":224.427,"audio":"/audio/11-memory-files.mp3"}