MemD Made Practical: How to Configure Memory for Claude Code Without Overcomplicating It
- Mark Kendall
- 6 hours ago
- 11 min read
MemD Made Practical: How to Configure Memory for Claude Code Without Overcomplicating It
One of the most important ideas in Claude Code architecture is also one of the easiest to misunderstand: memory.
When people hear “memory,” they sometimes assume there must be a major platform to install, configure, tune, and operate. But in Claude Code, the starting point is much simpler.
Claude Code already supports persistent project memory through files like CLAUDE.md. It can also import additional files using @path/to/file syntax, and Anthropic documents /memory as the command for viewing and editing loaded memory files.
So the real architectural question is not:
“How do I install memory?”
The better question is:
How do I design memory so Claude Code uses the right knowledge at the right time?
That is where MemD comes in.
For this article, we can define MemD as the Memory Design Layer: a simple, structured way to organize the knowledge Claude Code should remember across tasks, features, repos, teams, and delivery cycles.
The Big Clarification: MemD Is Not a Huge New System
MemD does not have to be a giant new memory database.
It does not have to be an enterprise platform on day one.
It does not require a six-month architecture project.
At the beginning, MemD can simply be a disciplined folder structure underneath your repo, connected to Claude Code through CLAUDE.md.
That is the beauty of it.
Claude Code gives you the memory mechanism.
MemD gives you the architecture.
In other words:
Claude Code remembers.
MemD decides what is worth remembering.
Why This Matters
A lot of teams use Claude Code like this:
They open the repo.
They ask Claude to work on a task.
Claude inspects files.
Claude makes changes.
The developer reviews the output.
The session ends.
That works.
But it does not automatically create an engineering learning system.
The next session may still require the same reminders:
Use this logging pattern.
Do not change this folder structure.
Run this test command.
Follow this API response format.
Do not introduce a new dependency.
Remember that auth is handled at the gateway.
Remember that this team wants small PRs.
Remember that we already rejected that design.
That is exactly what memory is for.
The goal of MemD is to prevent the team from re-teaching Claude Code the same things over and over.
The Simple Mental Model
Think of the Claude Code architecture this way:
Intent files describe the work.
They tell Claude what outcome you want.
Context files describe the current environment.
They tell Claude what matters for this repo, feature, or system.
Skills describe reusable capabilities.
They help Claude perform common types of work.
Hooks automate events.
They enforce checks, capture evidence, and trigger repeatable steps.
Agents divide the work.
They allow specialized execution across testing, security, documentation, API design, DevOps, and implementation.
MemD remembers what should survive.
It captures project knowledge, standards, decisions, lessons, patterns, and reusable assets.
That last part is what makes the whole system improve over time.
What Claude Code Already Gives You
Claude Code supports persistent memory mainly through CLAUDE.md files.
A typical project may have a root-level file like this:
That file can contain project instructions, repo conventions, build commands, testing rules, and workflow guidance.
Claude Code also supports importing other files from CLAUDE.md using @path/to/file syntax. This is what makes a clean MemD structure possible. Instead of stuffing everything into one huge memory file, you can break memory into logical sections and import them.
That means the configuration can be very lightweight.
You create the files.
You organize the knowledge.
You tell CLAUDE.md what to load.
That is the first version of MemD.
A Practical MemD File Structure
Here is a good starting structure:
your-repo/
memd/
This is enough to get started.
You do not need 40 files.
You do not need a complex database.
You do not need a full knowledge platform.
Start with a clean memory folder and grow it as the team learns.
The Root
The root CLAUDE.md is the front door.
This is the file Claude Code should see first. It should explain the project, how memory is organized, and which memory files should be loaded.
Example:
# Claude Code Project Memory
This repo uses a structured memory design layer called MemD.
MemD stores persistent project knowledge, architectural decisions, team standards, validation rules, lessons learned, reusable assets, skill routing, agent guidance, and hook behavior.
Before planning or implementing changes, review the relevant memory files below.
## Core Memory Imports
- @memd/project-knowledge.md
- @memd/architecture-decisions.md
- @memd/team-standards.md
- @memd/repo-conventions.md
- @memd/validation-rules.md
- @memd/lessons-learned.md
## Execution Support
- @memd/reusable-assets.md
- @memd/skill-routing.md
- @memd/agent-guidance.md
- @memd/hooks-memory.md
## Operating Rules
When working in this repo:
1. Start by understanding the user intent.
2. Check the relevant MemD files before making changes.
3. Follow existing repo conventions.
4. Prefer small, focused changes.
5. Do not introduce new dependencies without a clear reason.
6. Run or recommend the correct validation steps.
7. Update memory when a reusable lesson, decision, pattern, or rule is discovered.
This file is simple, but powerful.
It tells Claude Code:
“Do not start from scratch. Use the memory layer.”
What Goes Under
/memd
Now let’s walk through each file.
memd/project-knowledge.md
This file stores stable facts about the project.
# Project Knowledge
## Project Purpose
This repo supports the customer notification service for enterprise applications.
The service handles notification requests from internal systems and sends messages through approved channels such as email, SMS, or webhooks.
## Primary Technologies
- Backend: Python FastAPI
- Database: PostgreSQL
- Messaging: Kafka
- Deployment: AWS ECS
- Observability: OpenTelemetry and centralized logging
## Major Folders
- `/src/api` contains route handlers.
- `/src/services` contains business logic.
- `/src/models` contains domain models.
- `/src/integrations` contains external service clients.
- `/tests` contains unit and integration tests.
- `/docs` contains technical documentation.
## Important Notes
- Authentication is handled upstream by API Gateway.
- Do not add authentication logic directly inside route handlers unless explicitly required.
- All external calls should use integration clients, not raw inline HTTP calls.
This file helps Claude understand the basic shape of the system before it starts making decisions.
memd/architecture-decisions.md
This file captures decisions that should not be rediscovered every time.
# Architecture Decisions
## ADR-001: Authentication at the Gateway
Authentication is handled by API Gateway before requests reach this service.
Reason:
- Keeps service logic focused on business behavior.
- Avoids duplicate auth checks across services.
- Aligns with enterprise API governance.
Claude Guidance:
- Do not add local authentication middleware unless the intent file specifically asks for it.
- Preserve existing gateway-based assumptions.
## ADR-002: External Integrations Use Client Wrappers
All external service calls should go through integration client classes.
Reason:
- Improves testability.
- Centralizes retries, logging, and error handling.
- Prevents duplicated HTTP logic.
Claude Guidance:
- When adding a new external call, create or reuse a client under `/src/integrations`.
This is where MemD starts behaving like lightweight architecture governance.
It keeps Claude aligned with the design choices already made by the team.
memd/team-standards.md
This file tells Claude how the team expects work to be done.
# Team Standards
## Engineering Style
- Prefer clear, maintainable code over clever code.
- Keep changes small and focused.
- Follow existing patterns before introducing new ones.
- Do not rename files or restructure folders unless the intent requires it.
## Pull Request Expectations
Every meaningful code change should include:
- implementation
- tests
- documentation updates when behavior changes
- validation notes
- risks or assumptions
## Documentation Expectations
Update documentation when:
- API behavior changes
- configuration changes
- deployment behavior changes
- a new integration is added
- a new reusable pattern is introduced
## Dependency Rule
Do not add new third-party dependencies unless:
1. the existing codebase has no suitable option,
2. the dependency is actively maintained,
3. the reason is explained in the implementation notes.
This file helps Claude act like part of the team instead of an outside tool.
memd/repo-conventions.md
This file gets very practical.
# Repo Conventions
## API Route Pattern
Routes should be thin.
Route handlers should:
- validate input
- call service-layer functions
- return standardized responses
- avoid business logic
## Service Layer Pattern
Business rules belong in `/src/services`.
Service functions should:
- be testable
- avoid direct infrastructure calls when possible
- delegate external calls to integration clients
## Error Handling
Use the existing error response format:
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable message",
"details": {}
}
}
Logging
Use the shared logger utility.
Do not use raw print() statements in production code.
This is one of the most useful memory files because it tells Claude the local rules of the repo.
---
## `memd/validation-rules.md`
This file tells Claude how to prove the work is done.
```markdown
# Validation Rules
## Standard Validation Sequence
For backend changes, use this validation sequence:
1. Run unit tests.
2. Run integration tests when external behavior changes.
3. Run linting.
4. Run type checks if configured.
5. Confirm documentation updates.
6. Summarize evidence.
## Example Commands
```bash
pytest tests/unit
pytest tests/integration
ruff check .
mypy src
Evidence Requirements
After implementation, provide:
files changed
tests added or updated
commands run
results
known limitations
follow-up recommendations
This is where Claude Code starts becoming evidence-driven.
For enterprise work, this is critical.
The output should not just be “I changed the code.”
The output should be “Here is what changed, here is how it was validated, and here is the evidence.”
---
## `memd/lessons-learned.md`
This file captures what the team learns over time.
```markdown
# Lessons Learned
## Lesson: Do Not Mock the Entire Service Layer
Past issue:
Claude previously mocked too much of the service layer, causing tests to pass without validating real business logic.
Guidance:
Mock external integrations, not the core service behavior.
## Lesson: Environment Variables Must Be Documented
Past issue:
A feature added a new environment variable but did not update deployment documentation.
Guidance:
When adding configuration, update the environment variable documentation and deployment notes.
## Lesson: Avoid Large Multi-File Refactors During Feature Work
Past issue:
A small feature request caused unnecessary restructuring.
Guidance:
Keep feature changes focused unless the intent explicitly asks for refactoring.
This file is where mistakes become future prevention rules.
That is one of the highest-value uses of memory.
memd/reusable-assets.md
This file stores reusable prompts, templates, and checklists.
# Reusable Assets
## Feature Intent Template
```markdown
# Feature Intent
## Goal
Describe the business or technical outcome.
## Scope
What should change?
## Out of Scope
What should not change?
## Constraints
Architecture, security, performance, compliance, or repo constraints.
## Relevant Memory
- @memd/project-knowledge.md
- @memd/team-standards.md
- @memd/validation-rules.md
## Success Criteria
How will we know this is complete?
## Validation
What tests or checks should be run?
## Evidence Required
What should Claude report back?
Repo Review Checklist
Identify architecture style.
Identify build and test commands.
Identify major folders.
Identify risky areas.
Identify missing documentation.
Identify repeated patterns.
Identify validation gaps.
This file lets the team reuse its best patterns instead of recreating them.
---
## `memd/skill-routing.md`
This file explains when to use which skills.
```markdown
# Skill Routing
## Backend API Feature
For backend API changes, use this sequence:
1. repo-analysis
2. api-contract-review
3. implementation
4. test-generation
5. validation-report
6. documentation-update
## Documentation-Only Change
For documentation changes, use this sequence:
1. documentation-review
2. consistency-check
3. final-summary
## Refactoring Work
For refactoring, use this sequence:
1. repo-analysis
2. dependency-impact-review
3. refactor-plan
4. implementation
5. regression-test-review
6. validation-report
## Claude Guidance
Do not use every skill for every task. Choose the smallest useful sequence based on the intent.
This is where memory helps Claude choose the right reusable capabilities.
memd/agent-guidance.md
This file gives direction to sub-agents.
# Agent Guidance
## API Agent
Responsibilities:
- review API contracts
- preserve response formats
- check route/service separation
- ensure error handling is consistent
Relevant Memory:
- @memd/repo-conventions.md
- @memd/architecture-decisions.md
- @memd/validation-rules.md
## Testing Agent
Responsibilities:
- identify test coverage needs
- update or create tests
- avoid over-mocking
- confirm test evidence
Relevant Memory:
- @memd/validation-rules.md
- @memd/lessons-learned.md
## Documentation Agent
Responsibilities:
- update README files
- update API documentation
- document configuration changes
- summarize behavior changes
Relevant Memory:
- @memd/team-standards.md
- @memd/reusable-assets.md
## Security Agent
Responsibilities:
- review secrets handling
- check input validation
- avoid logging sensitive data
- confirm access assumptions
Relevant Memory:
- @memd/architecture-decisions.md
- @memd/team-standards.md
As soon as agents enter the picture, memory becomes even more important.
Without shared memory, each agent may behave differently.
With MemD, every agent works from the same operating model.
memd/hooks-memory.md
This file describes how hooks should use memory.
Claude Code hooks are user-defined commands, endpoints, or prompts that can run automatically at lifecycle events.
# Hooks Memory
## Pre-Commit Hook Guidance
Before commit:
- run standard validation
- check formatting
- check linting
- confirm no secrets are included
- summarize changed files
Relevant Memory:
- @memd/validation-rules.md
- @memd/team-standards.md
## Post-Feature Hook Guidance
After feature completion:
- summarize implementation
- summarize validation evidence
- identify reusable lessons
- recommend memory updates
## Memory Update Rule
After each meaningful feature, ask:
1. Was a new pattern created?
2. Was a mistake discovered?
3. Was a decision made?
4. Was a validation rule clarified?
5. Was a reusable template improved?
If yes, update the appropriate MemD file.
This is how memory becomes part of the delivery loop.
Not just documentation.
Not just notes.
A real learning mechanism.
How to Use MemD in a Feature Intent
Once MemD exists, your intent files should refer to it.
Example:
# Intent: Add Email Notification Support
## Goal
Add email notification support using the existing enterprise notification pattern.
## Scope
- Add email notification service logic.
- Add SMTP integration client if one does not already exist.
- Add unit tests.
- Add documentation for required environment variables.
- Provide validation evidence.
## Out of Scope
- Do not add SMS support.
- Do not redesign the notification service.
- Do not change authentication behavior.
## Relevant Memory
Before implementation, review:
- @memd/project-knowledge.md
- @memd/architecture-decisions.md
- @memd/repo-conventions.md
- @memd/validation-rules.md
- @memd/lessons-learned.md
## Success Criteria
- Email notifications can be sent through the approved SMTP pattern.
- External SMTP calls are isolated behind an integration client.
- Unit tests mock external SMTP behavior.
- Environment variables are documented.
- Validation evidence is provided.
## Evidence Required
Report:
- files changed
- tests added
- commands run
- validation results
- risks or assumptions
- recommended memory updates
That is the difference between a vague prompt and a serious engineering intent.
The intent tells Claude what to do.
MemD tells Claude how this team does work.
How Memory Gets Updated
This is the subtle but important part.
You do not just create memory once.
You maintain it.
After a feature, ask Claude Code to propose memory updates:
Review the completed work and recommend updates to the MemD memory layer.
Only recommend updates that are reusable for future work.
Classify each recommendation under:
- project knowledge
- architecture decisions
- team standards
- repo conventions
- validation rules
- lessons learned
- reusable assets
- skill routing
- agent guidance
- hooks memory
Then the architect or lead engineer reviews the recommendations.
Do not let memory become a junk drawer.
Good memory should be:
specific
current
safe
reusable
short enough to be useful
important enough to survive
Bad memory is worse than no memory.
What Not to Store in MemD
Do not store:
passwords
API keys
tokens
customer private data
temporary opinions
random chat history
large copied logs
outdated workarounds
duplicate notes
unapproved architectural decisions
MemD should not replace a secrets vault, database, document repository, or ticketing system.
It should contain the memory that improves Claude Code execution.
That is the boundary.
The Minimal Version
A team can start with just this:
your-repo/
memd/
And the root CLAUDE.md can be:
# Claude Code Memory
Use the MemD folder as the persistent memory layer for this repo.
Before implementation, review:
- @memd/project-knowledge.md
- @memd/team-standards.md
- @memd/validation-rules.md
- @memd/lessons-learned.md
- @memd/reusable-assets.md
Follow existing repo conventions, keep changes focused, validate the work, and recommend memory updates after meaningful changes.
That is enough to begin.
No massive platform.
No major setup.
No overengineering.
Just a good memory architecture.
The Architect’s Role
The architect does not need to manually write every memory entry.
But the architect should own the design of the memory layer.
The architect decides:
what belongs in memory
what does not belong in memory
what is shared across the team
what stays local
what gets reviewed
what gets deleted
what gets promoted into standards
what becomes a reusable asset
This is why MemD is an architecture layer.
It gives Claude Code continuity.
It gives teams consistency.
It gives agents alignment.
It gives hooks better rules.
It gives intent files reusable intelligence.
Final Thought
The important realization is this:
MemD is not hard to start.
At the beginning, it is mostly:
a CLAUDE.md file,
a /memd folder,
a few well-named Markdown files,
and the discipline to update memory when the team learns something reusable.
That is it.
But the impact is big.
Without memory, Claude Code is powerful but session-based.
With memory, Claude Code becomes repeatable.
With MemD, Claude Code becomes architectural.
Intent drives the work.
Context focuses the work.
Skills provide capability.
Hooks automate the work.
Agents scale the work.
MemD remembers how the team gets better.
That is why memory belongs in the core Claude Code architecture.
Not because it is complicated.
Because it is what turns AI-assisted coding into a learning engineering system.
Comments