Where Claude keeps what it knows: teaching notes
Notes for 17-praxis-where-claude-keeps-what-it-knows.html (11 slides). This deck explains how Claude Code is put together: what it remembers, where those files sit and who each one applies to. It builds one picture a layer at a time, and it ends on the distinction that saves teams the most trouble: an instruction is advice, a setting is a control. People leave knowing where to put a rule so it reaches the right people.
How to use these notes
- For groups already using Claude Code, or about to roll it out to a team. It follows 02 (Claude Code 101) and 08 (Agent Skills), and it's the deck to use when someone asks "where did it get that from?" or "why didn't it follow the rule?"
- Plan on 30 to 45 minutes, depending on how many hand-backs you do. Every slide adds one thing to the last picture, so don't skip ahead. The build is the lesson.
- Have Claude Code open on your own machine with a real repository. Slides 3, 5 and 8 are much stronger when you show the actual files.
- Blocks marked Back to your card, Brief it like a new hire and Run it live are the three moves from T0, how we teach Praxis. Use the names and tasks on the group's Use Case Cards wherever you see [name].
- The new hire map carries this whole deck. Claude's memory is the new starter's handbook, notebook and filing cabinet. The four depths are company policy, your own way of working, the team's rules and a note on your own desk.
Where Claude keeps what it knows
Three stores, four depths, one folder name. People who use Claude Code every day often can't say where its rules and memory come from. By the end they can, and they can check it themselves.
"Today is about where Claude Code keeps what it knows about you, your team and your project. It sounds technical. It's actually one simple pattern, and once you see it you'll know where to put every rule you want it to follow."
Set the frame early. When you take someone on, some of what they know comes from the company handbook, some from their manager, some from the notes they take themselves. Claude is the same, and this deck shows where each of those lives.
"Think about the last person who joined your team. Where did they learn how things are done? Which parts were written down, and which did they just pick up?"
The whole thing on one screen
Seven steps in three groups: what exists, where it sits and why it matters. Each picture is the one before with one thing added.
"We'll build this up one layer at a time. First what exists, then where it sits, then why that matters for you and your team. If you only remember one slide, it's step 4."
Twenty seconds here. Point at step 4 and step 7 so people know where the two big ideas are.
Everything is a file
There's no hidden memory database. Three things get called memory and each has a different author. You write CLAUDE.md. Claude writes the memory folder as it works. The tool writes the transcripts. All three are plain text on your own machine.
"When people say Claude 'remembers', they mean one of three things. The rules you've written for it. The notes it's written for itself. And the log of what was said. All three are text files. You can open them, read them, change them and delete them."
On the map: CLAUDE.md is the handbook you give the new starter. The memory folder is the notebook they keep. The transcripts are a recording of every conversation you've had with them.
- Kick off
- In a real repository, type
/memory, then open one of the files it lists in a text editor. - Expect
- A few seconds.
- While it runs
- Ask the group to guess what's in the file before you open it.
- When it lands
- Read out a couple of lines. Point out that it's ordinary text anyone could edit.
Local storage doesn't mean local processing. The files live on the workstation, but when a session loads one, its contents go to the API as part of the prompt, the same as any source file Claude reads. Say this plainly. It's the first thing IT will ask.
"So my data never leaves my laptop?" That's the misreading the key concept above is there to prevent. Correct it on the spot.
They all live in one folder
In your home directory there's a folder called .claude. It holds your own CLAUDE.md, your personal skills and the memory Claude keeps, one folder per repository. Every checkout of the same repository shares one memory, and two developers on the same codebase build separate memories that neither can see.
"Everything personal sits in one folder in your home directory. Your preferences, your procedures and Claude's notes on each project. Those notes are yours. If a colleague works on the same code, Claude keeps a separate set of notes for them."
- "If Claude learns something useful while working with you, does your colleague benefit? What would you have to do so they did?"
(wait: the answer is that it has to be written into a shared file, which is where slide 6 goes)
This is what it actually looks like
The same thing as a directory listing from a working laptop. Nothing on the previous slide is abstract, and there's one new file here: settings.json, which comes back on slide 10.
- Kick off
- Open your own
~/.claudefolder in the file browser or runls ~/.claudein a terminal. Check beforehand that nothing private is on show. - Expect
- Instant.
- While it runs
- Match each folder on your screen to a line on the slide.
- When it lands
- Ask the people with Claude Code installed to open theirs. Someone always finds a memory folder they didn't know about.
People who are surprised or uneasy about the transcripts. That's fair. Say they're plain files they can read and delete, and that the retention settings are something to agree with IT.
The same folder, in the repository
A second .claude folder and CLAUDE.md live in the codebase itself, and they're committed. That's the difference between a habit you have and a standard your team has. The repository is drawn inside your home folder because it reaches fewer people, even though it doesn't sit there on disk.
"Your home folder is you, on every project. The repository is everyone who works on this project. Put a rule in your home folder and it's your habit. Commit it to the repository and it's the team's standard."
On the map: your home folder is the way you personally like things done. The repository is the team handbook that every new starter on this project gets on day one.
- "[name], take your card. Name one rule that's your own preference and one that everyone on the task should follow."
- "Where does each one go?"
People reading the nested boxes as folders inside folders on disk. Say it straight away: the nesting shows who a file reaches.
One folder name, four depths
Two more layers: one outside yours, set for the whole machine by IT, and one inside the repository, CLAUDE.local.md, which stays out of version control and is just you on this project. Four layers in total. They add up rather than replace each other, read from the outside in.
"There are four places a CLAUDE.md can sit. The machine, set by IT for everyone. Your home folder, for you on every project. The repository, for everyone on this project. And a local file in the repository that's just for you, just here. Claude reads all four and adds them together. Where you put a rule decides who it applies to."
Where a file sits decides who it applies to. Same folder name, four audiences. Everything else in the deck follows from this.
On the map: company policy from head office, your own way of working, the team handbook for this project and a sticky note on your own desk. A new starter follows all four at once.
"You're the new hire. Head office says one thing, the team handbook says another. Which do you follow, and who do you ask?"
Use this to show why layers that contradict each other cause trouble. They add up, so conflicting rules leave Claude to choose.
- "[name], take one rule from your card. Which of the four layers does it belong in, and why that one?"
- "[name], do you agree? Who would miss out if it went one layer further in?"
(go round two or three cards. The debate about which layer is the lesson)
- Developer
- The repository CLAUDE.md, and CLAUDE.local.md for their own shortcuts.
- Team lead
- The repository layer: it's where the team's standard lives and gets reviewed like code.
- IT or admin
- The machine layer, deployed to everyone, for the rules that can't vary by team.
- Consultant or contractor
- Their home folder, so their way of working travels with them from client to client.
Not all of it loads at once
Some files load at the start of every session and use up context whether they're relevant or not: all four CLAUDE.md layers, the first 200 lines of MEMORY.md and the unscoped rules. The rest wait on disk until Claude reaches for them: skills, memory topics and path-scoped rules. A skill costs only its one-line description until it's used.
"Everything in CLAUDE.md is read before you've typed a word, every session. That's space in its working memory you've spent up front. Skills are different: Claude only sees their one-line description until it needs one. So keep CLAUDE.md short and put the long procedures in skills."
On the map: CLAUDE.md is what the new starter reads every single morning before they begin. The skills are binders in the filing cabinet that they open when a job calls for one. You wouldn't make them reread the whole cabinet every day.
- Kick off
- Start a fresh session in your repository and type
/contextbefore anything else. - Expect
- A few seconds.
- While it runs
- Ask the group to guess how much is used before the first prompt.
- When it lands
- Point to the memory and instructions lines. That's what CLAUDE.md costs on every session.
- "For your card, what does Claude need to know every time, and what only once in a while?"
- "[name], which of those belongs in CLAUDE.md and which in a skill?"
The CLAUDE.md that has grown to hundreds of lines. Someone in the room has one. Ask them how many of those lines matter on a normal day.
Skills use the same four places
A skill is a folder with a SKILL.md in it: a written procedure. It goes in the same four places as everything else: managed for the whole organisation, personal in your home folder, project in the repository or inside a plugin. If the same name is in two places, the outer one wins. Where you put it is how you share it.
"There's nothing new to learn about where skills go. Put a procedure in the repository and everyone who clones it has it. Put the same file in your home folder and it helps just you. That choice is how you share it."
- "Is there a procedure in your card that the whole team should run the same way? Where would you put it?"
- "[name], and one that's just your own way of doing things?"
"Why isn't my project skill working?" when there's one with the same name further out. The outer one wins. Tie back to deck 08, where this is one of the five things that go wrong.
Instructions advise. Settings enforce.
Both live in the same four folders, and only one is a control. CLAUDE.md and rules are context: Claude reads them and follows them, most of the time. settings.json and hooks run whatever Claude decides: they block a command or a path, or run a check at a fixed moment. If something has to be impossible, a written instruction isn't enough.
"Writing 'never touch the production database' in CLAUDE.md is advice. Claude will follow it nine times out of ten. If it has to be ten out of ten, it goes in settings, where it's blocked whatever Claude decides."
On the map: telling the new starter "don't touch payroll" is an instruction. Not giving them the key to payroll is a setting. You'd do both for anything that matters.
"[name], you've just hired someone to help with your card. What's the one thing you'd tell them never to do? Would you trust them to remember, or would you take away the key?"
People reach for an instruction when they need a control, then wonder why it held nine times out of ten. This is the slide that stops real incidents. Make sure every person can say which of their rules are advice and which have to be enforced.
- "Go through the rules on your card. Mark each one: advice or control?"
- "[name], read out one you marked as a control. Group, do you agree it can't be left to judgement?"
Compliance rules written only in CLAUDE.md. That's the most common version of this mistake. For regulated clients, turn it into a to-do: move the must-never rules into settings with IT.
Where it sits decides who it applies to
The whole deck in one line: everything is a file, and where it sits decides who it applies to. Three commands let them check it themselves: /memory lists the files, /context shows what loaded and /doctor explains why something isn't taking effect.
"If you remember one thing: it's all files, and where a file sits decides who it applies to. And when something isn't working the way you expect, you don't have to guess. Three commands tell you what's going on."
- Kick off
- Run
/doctorin your repository. - Expect
- A few seconds.
- While it runs
- Ask which of the three commands they'd reach for first when a rule is being ignored.
- When it lands
- Read any warning out and say which slide it relates to.
Ask each person to go back to their card and write, for each rule, where it lives and whether it's advice or a control. That list is what you check at the start of the next session.