For official documentation, see the Anthropic Claude Code docs. MCP specifications are available at modelcontextprotocol.io.
Regular AI chatbots forget everything when a conversation ends. However, the Claude Code memory system lets you carry context across sessions. In other words, you get an AI that remembers your preferences, past decisions, and ongoing projects.
This article explains how the Claude Code memory system works, from its file-based architecture to practical configuration examples drawn from my own setup.
How the Claude Code Memory System Works
The Claude Code memory system is file-based and remarkably simple. No external database or service is required — memories are stored as plain Markdown files.
.claude/projects/<project-dir>/memory/
├── MEMORY.md # Index (table of contents)
├── user_profile.md # User information
├── feedback_*.md # Behavioral feedback
├── project_*.md # Project context
└── reference_*.md # External resource pointersMEMORY.md serves as the index linking to all memory files. Claude Code reads this index automatically at the start of every conversation, then references individual files as needed. Consequently, your preferences and project context are reflected in every session.
📊 Memory Loading Flow
Four Memory Types
1. User — Personal Information
Stores information about yourself that the AI should remember: your role, skill level, preferences, and personal details needed for bookings. As a result, the AI’s suggestions become tailored to your specific needs over time.
2. Feedback — Behavioral Guidelines
Records explicit instructions like “do this” and “never do that.” The biggest benefit: you only need to say it once. Each feedback entry in the Claude Code memory system includes a Why (the reason) and How to apply (when the rule kicks in). This context helps the AI make proper judgment calls in edge cases.
Examples from my actual feedback memories:
- Research before answering — never guess
- Use k-chrome MCP as the first choice for browser automation
- Always confirm before sending LINE messages
- Delete temporary files after completing tasks
- Never suggest stopping a polling job — continue until told to stop
3. Project — Ongoing Work Context
Captures context that cannot be derived from code or git history: project goals, ongoing inquiries, travel plans, and business decisions. Since project context changes quickly, regular updates are essential to prevent the AI from acting on stale information.
4. Reference — External Resource Pointers
Points to information in external systems: documentation locations, support contacts, and monitoring dashboards. These pointers help the AI know where to look when external data is needed.
Memory File Format
Each file in the Claude Code memory system uses YAML frontmatter with Markdown content:
---
name: feedback_browser_automation
description: Browser automation MCP priority rules
type: feedback
---
Use k-chrome MCP as the primary tool.
**Why:** Preserves existing Chrome profile login sessions
**How to apply:** For any browser operation, try k-chrome firstManaging the MEMORY.md Index
MEMORY.md lists all memory files as one-line entries under 150 characters each. Organize entries semantically by category, and keep the total under 200 lines. Exceeding this wastes tokens during the automatic loading phase.
Memory Maintenance — Regular Cleanup
Without maintenance, the Claude Code memory system degrades over time. Therefore, regular cleanup is essential. Remove outdated memories, merge duplicates, and delete anything derivable from code or git history.
In my experience, I once reduced 32 memory files to 17 — nearly half were unnecessary. Since then, I perform monthly cleanup to keep the system lean and accurate.
Next Up
The next article covers Scheduled Execution. You will learn how to set up cron-like recurring tasks and see the automated jobs I run for invoicing, data syncing, and monitoring.
