# Memory Lives in Files, Not Chats: Managing AI Agent Context > Why AI coding agents lose the thread between sessions, and how a small state file in the repo lets any new Claude session resume exactly where work stopped. - URL: https://shotmatic.app/blog/memory-lives-in-files - Category: Agent Context - Published: 2026-09-27 - Author: Tu Nguyen ## Key takeaways - An agent session is a convenience; the source of truth is a state file committed in the repo. - A useful state file answers four questions: which phase, what is the next step, what is blocked, and what was already tried. - Every session should start with 'read the state file first' and end by updating it. - If you lose a session, switch machines or hit the context limit, a fresh session plus the state file continues the work. You open a new session, type *"continue the payment screen"*, and the agent confidently starts over — re-creating a component you deleted yesterday for a good reason. You explain again. Tomorrow you explain again. The agent is not being careless. It simply has no memory of yesterday unless you give it one. This post is about where that memory should live. Short answer: **in a file in the repo, not in the chat.** This is part 2 of *The ShotMatic Method*. Part 1 is [the overall workflow](https://shotmatic.app/blog/ai-agent-project-workflow). ## Why chat history is a bad memory Resuming the exact session (`claude --resume `) is genuinely useful — the agent keeps its reasoning, its recent tool output and your preferences. But as the *only* memory it fails in predictable ways: - **It gets long.** Long conversations get summarized or compacted, and details fall out. - **It is local.** The session lives on the machine where it ran. On your other laptop it doesn't exist. - **It is hard to find.** After a few weeks you have dozens of sessions and no idea which one had the payment task. - **It is not reviewable.** You can't `git diff` a conversation to see what changed in the plan. So use sessions for speed, and use files for truth. ## The four questions a state file answers A state file does not need a schema to be useful. It needs to answer, in under a minute of reading: 1. **Where are we?** — the current phase, e.g. `Phase 4/6 · store listing`. 2. **What is next?** — exactly one next step, concrete enough to start without asking. 3. **What is blocked?** — anything waiting on you or on someone else (an API key, a review, a decision). 4. **What was already tried?** — the failed approaches, so the next session doesn't walk the same loop. A minimal Markdown version: ```markdown # State — Tip Split Phase: 4/6 · store listing Next: write the 5 screenshot captions (see plan/listing.md for sizes) Blocked: — Tried: - 2026-09-20 auto-generated captions from the README: too long for the store, dropped. ``` Or, if you want a tool to read it, the same thing as JSON. ShotMatic reads a `progress.json` per repo with fields like `phase`, `next` and `blocker`; the format is documented in the app and a starter file is generated for you. ## The session ritual: read first, write last The file only works if every session uses it. Two lines in your starting prompt are enough: ```text Read plan/state.md before doing anything. Tell me the phase and next step you found. When you finish, update plan/state.md: new phase, new next step, and anything you tried that failed. ``` Asking the agent to repeat the phase back is a cheap check that it actually read the file — and that the file says what you think it says. ## What this buys you - **Lost session? No problem.** Start a new one with the ritual above; nothing important was only in the chat. - **Switching machines** works the same way: pull the repo, start a session, keep going. - **Different agents** can take over. The same file works for Claude, ChatGPT or anything that reads text. - **Honest progress.** The phase in the file is what you review, so the board of all your projects can be built from files instead of from your memory — which is what makes [running many projects in parallel](https://shotmatic.app/blog/run-10-projects-in-parallel) possible. ## Rules that keep the file trustworthy - **Don't invent numbers.** If the phase is unknown, write `Phase —/6`, not a guess. A visible gap reminds you to fix it; a wrong number looks right and misleads you. - **One next step, not five.** A list of next steps is a to-do list; it hides which one matters. See [Phases, not to-do lists](https://shotmatic.app/blog/phases-not-todo-lists). - **Keep "tried" short and dated.** It is there to prevent loops, not to be a diary. - **Commit it with the code** it describes, so history lines up. ## Where ShotMatic fits ShotMatic is built on exactly this idea: the repo keeps the memory, the agent does the work, and the app only shows you what the files say. Each task remembers its Claude session, so ✦ resumes the exact conversation when it exists — and when it doesn't, ✦ starts a new session with a prompt that already says *read the state file first*, the phase and the next step. ## FAQ **Why does Claude Code forget what we did yesterday?** Each session only knows what is in its own conversation. Resuming the same session helps, but conversations get long, get compacted, or live on another machine. Writing the important state into a file in the repo makes it available to any session. **What should go into an agent state file?** The current phase, the single next step, anything blocking progress, and a short log of what was tried and failed. Keep it short enough to read in under a minute. **Should I commit the state file?** Yes. Committing it gives you history, lets it travel between machines with the code, and lets tools read it without any database.