The memory system
Working with Claude on Projects
The memory system is what turns a Project from a convenience into a genuine long-term collaborator. Without it, every session starts from scratch. With it, Claude walks into each session already knowing who you are, how you like to work, what decisions have been made, and where to find reference information. This chapter covers the four memory types, how to write entries that actually work, and what not to put in memory.
How the Memory System Works
Memory is stored as plain markdown files on disk — there is nothing magical or opaque about it. Each file has a YAML frontmatter block that identifies it, and a body with the actual content. An index file called MEMORY.md lists all memory files with one-line summaries so Claude can quickly decide which ones are relevant to load.
Claude reads MEMORY.md at the start of every session. When a memory file seems relevant to the current task, Claude reads that file too. When Claude learns something worth saving — or when you explicitly ask it to remember something — it writes or updates the appropriate file and adds a line to MEMORY.md.
The Four Memory Types
User memories tell Claude who it's working with. They shape how Claude explains things, what it assumes you already know, and what level of detail is appropriate. A good user memory makes every response feel like it was written for you specifically — because it was.
Save facts about role, expertise level (especially where it varies by domain), goals, learning style, and anything that should change how Claude frames its answers. Avoid saving negative observations or anything you wouldn't want a colleague to write about you.
--- name: user-profile description: Philip's background, role, and working style metadata: type: user --- # Philip Osztromok Senior developer and systems administrator. Deep Linux/networking experience — explain at peer level, no hand-holding on fundamentals. New to Python (coming from Java/JS) — frame Python concepts in terms of Java equivalents where helpful. Current goal: FastAPI web app. Prefers vi/vim for terminal editing. Strongly dislikes nano. Responds well to direct answers; dislikes excessive hedging.
Notice what this does: Claude now knows not to explain what SSH is, but should explain Python's approach to classes if it comes up. It knows to suggest vim, never nano. And it knows Philip wants directness. None of this needs to be re-stated in every session.
Feedback memories are behavioural rules that come from actual experience working together. They prevent Claude from making the same mistake twice — and equally importantly, they lock in approaches that worked so Claude doesn't drift away from them.
The structure matters here: lead with the rule, then add a Why: line and a How to apply: line. Knowing the reason behind a rule lets Claude apply it intelligently in edge cases rather than blindly following it when it doesn't apply.
--- name: feedback-course-pdf description: Always generate and run the PDF build script with the final chapter metadata: type: feedback --- Always generate and run the PDF build script in the same response as the final chapter of any course. Do not wait for the user to ask. **Why:** User confirmed this is always wanted — having to prompt for the PDF after the final chapter is unnecessary friction. **How to apply:** After writing the final lesson HTML, immediately write the PDF build script and run it in the same response.
Two triggers for saving feedback: corrections ("don't do X") and confirmations ("yes, exactly that"). Corrections are easy to notice. Confirmations are quieter — watch for the user accepting an unusual choice without pushback, or saying "perfect, keep doing that."
Project memories capture the ongoing state of work — not the code itself, but the context and motivation behind it. What are we building? Why this approach and not another? What's the deadline? What was decided and what was rejected?
These memories decay — a decision made in January may be irrelevant by March. The Why: line is especially important here: it lets Claude (and you) judge whether the memory is still load-bearing when the project evolves.
--- name: website-rebuild-decision description: Chose FastAPI+Jinja2 over Next.js for site rebuild metadata: type: project --- Using FastAPI + Jinja2 for the osztromok.com rebuild, not Next.js. **Why:** Philip is learning Python and wants the rebuild to be a learning project. Next.js would require JS expertise he's building separately. FastAPI aligns with the meal planner app goal. **How to apply:** All rebuild suggestions should assume FastAPI/Python backend, not Node/React. Don't suggest Next.js alternatives.
Always convert relative dates to absolute dates when saving project memories ("Thursday" → "2026-06-19"). A memory that says "the deadline is next Thursday" is meaningless a month later.
Reference memories are pointers — they tell Claude where to look, not what's there. Bug tracker, monitoring dashboard, API docs, a specific Slack channel, the server IP for a dev environment. Claude can't visit URLs on its own, but knowing they exist helps it direct you to the right place.
--- name: server-reference description: Server details for osztromok.com — IP, stack, config locations metadata: type: reference --- # osztromok.com Server - **Host:** VPS, Debian 12 Bookworm - **Web server:** Apache 2.4 - **DB:** MySQL 8, accessible via localhost only - **Config:** Apache vhosts in /etc/apache2/sites-available/ - **Web root:** /var/www/osztromok.com/public/ - **Course files:** /var/www/osztromok.com/public/claude-generated-files/
Reference memories are the most stable — server configs and tool locations don't change often. They're also the most actionable: when Claude knows where things live, its suggestions can be immediately specific rather than generic.
MEMORY.md — The Index
MEMORY.md is loaded every single session. It's an index, not a memory store — each entry is one line, pointing to a file with a hook that tells Claude when to read it. Keep it concise; lines after 200 will be truncated.
# Memory Index - [User Profile](user_profile.md) — Senior dev, Linux/networking expert, learning Python for FastAPI - [Editor Preference](feedback_editor.md) — Always suggest vim, never nano - [Course PDF Rule](feedback_course_pdf.md) — Generate PDF automatically with final chapter - [Website Rebuild](website_rebuild_decision.md) — Using FastAPI+Jinja2, not Next.js - [Server Reference](server_reference.md) — osztromok.com VPS details, Apache config paths
The one-line hook is what Claude uses to decide whether to load the full file. Make it specific enough to be useful — "user info" is not a useful hook; "Senior dev, Linux expert, learning Python for FastAPI" is.
What NOT to Save in Memory
These live in the codebase. Read the files — don't duplicate them in memory where they'll go stale.
git log is authoritative. A memory summarising recent commits is outdated the moment the next commit lands.
The fix is in the code. The context belongs in the commit message. Memory is for enduring patterns, not one-time solutions.
What you're working on right now is ephemeral. Use a task list or notes file — not the memory system — for current work state.
No duplication. If a rule is in the project instructions file, don't also put it in memory — it creates conflicts when one is updated and the other isn't.
A log of what sessions covered is an archive, not a memory. Ask yourself: what's surprising or non-obvious here? That's the part worth saving.
How to Trigger Memory Saves
Say "remember this"
The most direct trigger. Claude will save it to the appropriate memory file and update MEMORY.md immediately.
Correct Claude's behaviour
"Don't do X" or "I prefer Y" — Claude recognises corrections and saves them as feedback memories proactively.
Confirm a non-obvious approach
"Yes, exactly" or accepting an unusual choice signals Claude that the approach was right — it saves this as a positive feedback memory.
Provide project context explicitly
When you explain why a decision was made or share a constraint, Claude saves this as a project memory — especially if you frame it as background context.
Periodically consolidate
Run /consolidate-memory to have Claude review all memory files, merge duplicates, remove stale entries, and sharpen descriptions. Memory quality degrades without maintenance.