You've had this conversation: "As I mentioned earlier, we use TypeScript with strict mode, we prefix interfaces with 'I', we don't use any, and our API follows REST conventions." You find yourself repeating the same context every time you start a new conversation with AI. Each new session forgets everything from previous sessions. You waste time re-establishing context that never changes.
The solution is simple but powerful: persist state in files.
When you store project knowledge, decisions, and context in files within your repository, AI systems can read them directly. You stop repeating yourself. Context becomes cumulative rather than reset each session. New team members (or future you) can understand decisions without hunting through git history.
This lesson explores what to persist, how to structure it, and why file-based persistence is the secret to effective AI collaboration.
Here's the fundamental limitation: AI systems have no persistent memory between sessions.
Each conversation starts fresh:
The AI doesn't remember your previous conversations. It doesn't learn about your project over time. Each session is a blank slate.
Without persistent state, you face:
The 20 minutes you spend writing a context file pays for itself after just two sessions. That's the laziness that pays off.
Files in your repository are the one thing AI systems can read and that persists across sessions:
Every AI session reads these files. Context is shared automatically. Knowledge accumulates.
Not all state is equal. Some changes constantly (current task status), some rarely changes (architecture decisions), some never changes (project language).
The most direct way to persist state for AI collaboration is through context files that AI systems automatically read.
Claude Code automatically reads CLAUDE.md in your project root. This is the perfect place to capture project-specific knowledge:
Every Claude Code session reads this automatically. No more repeating conventions.
The Handshake: When Claude Code sees CLAUDE.md, it doesn't just read it—it treats your project-specific conventions as context that takes precedence over generic patterns. Think of it as a handshake between you and the AI: "These are MY rules for THIS project."
Different AI tools read different files:
One of the most valuable things to persist: why you made technical decisions.
Six months later, you won't remember why you chose PostgreSQL over MongoDB. A new developer won't know why you used Redux instead of Context API. These decisions deserve persistent documentation.
When someone (or AI) asks "Why did we use PostgreSQL?", you don't need to remember. The ADR explains the decision, alternatives considered, and tradeoffs.
This is especially valuable for AI: when suggesting changes, AI can read ADRs and respect previous decisions rather than re-opening settled debates.
The highest form of state persistence: someone (or some AI) can understand your entire project from the files alone.
Complete Context:
Self-Documenting Structure:
Someone opening this project for the first time can:
AI can do the same—giving it complete context without you explaining anything.
Capture coding conventions in context files:
AI follows these automatically. Code stays consistent.
Document current work to help future sessions:
When you return to a project after a break, you know exactly where you left off.
Document things that trip people up:
AI can warn about these when suggesting changes.
Here's a powerful pattern: ask the AI to maintain a scratchpad.md or session-notes.md file where it records its own reasoning.
The insight: Documentation is for others. Persisting state is for the loop. When the AI writes down its thought process, the next session picks up mid-thought instead of starting from scratch.
But you migrated to MongoDB six months ago.
Fix: Treat context files like code—update them in the same commit as your code changes. Renamed a function? Update CLAUDE.md in that commit. Changed the tech stack? Update the context file before merging. This ties directly to Principle 4 (Atomic Changes): one logical change, one commit, documentation included.
These are formatting conventions—let your linter handle them. Context files should capture meaningful decisions, not trivia.
Some decisions in Slack, some in email, some in tickets, some in people's heads.
Fix: If it's a decision, write an ADR. If it's a convention, add to CLAUDE.md. If it's not in git, it doesn't exist.
Pasting entire library documentation, full API references, or every possible convention into CLAUDE.md.
The problem: AI has a limited context window. Stuffing too much in means the AI might miss the important parts—or run out of room for your actual conversation.
Golden Rule: Keep context files dense but concise. Link to external docs instead of pasting them. Summarize the parts you actually use. If your CLAUDE.md is longer than 200 lines, ask yourself what can be moved to separate files that AI reads only when relevant.
AI systems can be guided to read specific context:
This focuses AI's attention on relevant context rather than reading everything.
Without state persistence:
With state persistence:
The difference is dramatic. With good state persistence, your AI collaboration gets better over time. Each session benefits from all previous documentation. You're not starting fresh—you're continuing an ongoing conversation.
Files are the durable layer that both General Agents share. The specific file types differ, but the principle is universal.
In Cowork: Ask Cowork to maintain a progress.md file tracking what's been completed. Create a context.md file before starting complex projects. These files serve the same purpose as CLAUDE.md—they persist knowledge that would otherwise be lost between sessions.
Non-coder tip: Start every Cowork session with: "Before answering any questions, please read 'project_brief.docx' in my files." This simple prompt gives Cowork the same "memory" that CLAUDE.md gives Claude Code. The principle is universal—only the file format changes.
The meta-insight: Both interfaces are stateless. The AI doesn't remember you. But files do. The more you invest in persistent context files, the smarter every future session becomes—regardless of which interface you use.
What you're learning: How to capture project-specific knowledge in a format that AI systems can use. You're learning to identify what context matters and how to structure it for maximum impact.
What you're learning: How to document technical decisions in a way that preserves the "why" behind choices. You're learning to create knowledge assets that compound in value over time.
What you're learning: How to design a project for maximum reproducibility. You're learning to create a self-documenting codebase where knowledge persists and compounds—making collaboration with humans and AI more effective.
Never persist sensitive data (API keys, passwords, tokens, personal information) in context files like CLAUDE.md. These files are committed to version control and visible to anyone with repository access. Use environment variables (.env files in .gitignore) for secrets. If you accidentally commit a secret, rotate it immediately—removing it from git history is not enough.