Every engineer who has used Claude for more than a week has hit the same wall: the session ends, the context evaporates, and tomorrow you re-explain your architecture, your naming conventions, and the three approaches you already ruled out. The model isn’t the problem. The problem is that you’re treating a stateless API call like a persistent teammate. Claude has no memory between conversations unless you build one — and the fix is simpler than most people expect. A folder of plain markdown files, a consistent structure, and a deliberate habit of reading and writing that folder at the start and end of every session will give you a knowledge base that survives indefinitely.
Why Claude forgets, and why that's actually fine
Claude’s context window is large, but it is not persistent. Each new conversation starts empty. Anthropic’s own documentation on context management for AI coding workflows is explicit that the model has no built-in cross-session memory; anything you want carried forward must be supplied in the prompt. This is a constraint, not a bug. It means you control exactly what the model sees, which is better for correctness and far better for security than an opaque memory store you can’t audit.
The practical consequence: your knowledge base is not something Claude maintains. It is something you maintain, in a format Claude can read and write cheaply. Plain markdown is the right choice because it is diffable in git, readable in any editor, and token-efficient compared to JSON or XML scaffolding.
The folder structure that works
Keep it boring. A single repository, five files, no database:
- project.md — what the system does, the stack, the constraints that don’t change.
- decisions.md — an append-only log of choices made and the reason for each. This is the file that saves you from re-litigating settled questions.
- conventions.md — naming, formatting, error-handling patterns, test layout.
- open-questions.md — unresolved items, with the date each was raised.
- session-log.md — a short entry per working session: what changed, what was learned, what to do next.
The discipline that makes this work is a two-step ritual. At the start of a session, paste or attach project.md, decisions.md, and conventions.md. At the end, ask Claude to draft an entry for session-log.md summarising what was decided, then review and commit it yourself. Never let the model write directly to decisions.md without your review — that file is your source of truth and it should only contain claims you have verified.
What to put in each file, and what to leave out
The most common failure mode is over-stuffing. A 4,000-line project.md burns context and buries the signal. Aim for the smallest set of facts that would change Claude’s output if omitted.
Include: language and framework versions, the deployment target, hard constraints (“no new dependencies without approval”), and the two or three architectural decisions that everything else depends on. Exclude: full source files, verbose meeting notes, and anything already visible in the repository. If Claude can read it from the code, don’t duplicate it in prose.
For decisions.md, use a fixed format so the file stays scannable:
- Date — when the decision was made.
- Decision — one sentence, active voice.
- Reason — the constraint or trade-off that drove it.
- Revisit if — the condition under which this should be reopened.
That last field is the one most teams skip and the one that pays off most. It tells future-you, and future-Claude, when a past decision has expired.
Keeping it honest: review, version, and verify
A knowledge base that drifts from reality is worse than none, because it confidently misleads. Two safeguards prevent this. First, version everything in git — every session log and decision is a commit, so you can see when a claim entered the record and what changed around it. Second, treat any model-generated summary as a draft. Claude is good at compressing a conversation into bullet points; it is not a reliable narrator of what you actually agreed to.
There is also a security dimension. If your notes contain customer names, internal endpoints, or credentials, they will be sent to the model every session. Keep secrets out of the knowledge base entirely, and if your team handles regulated data, route the workflow through a reviewed process rather than a personal folder. For teams that want this pattern standardised across engineers rather than improvised per person, Code N Rob’s engineering workflow guidance covers how to structure AI-assisted development without leaking context you shouldn’t.
Start small. Create the five files today, fill in project.md and conventions.md from memory, and commit them. Then run one session with the read-and-write ritual and see how much less time you spend re-explaining yourself. The knowledge base compounds — every session you log makes the next one cheaper. If you want a second pair of eyes on how your team is wiring AI agents into real projects, get in touch with Code N Rob and we’ll look at it with you.
