Our coding agent was relearning the same codebase every session

Our coding agent was burning through tokens like crazy, constantly re-reading the same files, re-discovering the same patterns, and asking the same questions about our codebase structure every single session.

The problem? It had no persistent knowledge of what it had already learned.

We fixed it with a simple pattern: codebase snapshots. Every time our agent completes a significant task, it writes what it learned to a LEARNED.md file in the project root.

Here's the template we use:

# Codebase Knowledge - Last Updated: 2024-01-15

## Architecture Patterns
- Uses Next.js 13 with app router
- Database: Prisma + PostgreSQL
- Auth: NextAuth.js with GitHub provider

## Key Files & Their Purpose
- `/lib/db.ts` - Database connection singleton
- `/lib/auth.ts` - Auth configuration
- `/components/ui/` - Shadcn components (don't modify)

## Recent Discoveries
- API routes use middleware for auth checking
- Tests run with `npm run test:watch`
- Deployment happens via Vercel, triggers on main branch

## Common Gotchas
- Environment variables need NEXT_PUBLIC_ prefix for client-side
- Prisma schema changes require `npx prisma db push`
- TypeScript errors often resolve with `npm run type-check`

The agent updates this file whenever it discovers something new about the codebase. Next session, it reads LEARNED.md first before doing anything else.

Results: Our token usage dropped 40% immediately. More importantly, the agent stopped wasting 10-15 minutes every session just figuring out where things were.

The key insight: agents need institutional memory, not just conversation memory. Conversation memory disappears when the session ends. Institutional memory persists across sessions, teams, and even different agents working on the same codebase.

We've extended this pattern beyond just code. Our agents now maintain:

• LEARNED.md - Codebase architecture and patterns
• DECISIONS.md - Why we chose specific approaches
• GOTCHAS.md - Common mistakes and how to avoid them
• CONTACTS.md - Who to ask about different parts of the system

The pattern works because it mirrors how human developers actually learn codebases — through documentation, tribal knowledge, and hard-won experience. Your agent deserves the same advantage.

Start with just LEARNED.md. Have your agent read it at the start of every session and update it whenever it discovers something non-obvious. You'll be shocked how much faster your second session becomes.