Tools: How I Create Memory for My Agents on Claude Code

How I Create Memory for My Agents on Claude Code ## Introduction ## The Architecture: Six Layers of Memory ## Layer 1: CLAUDE.md — The Constitution ## Project-Specific CLAUDE.md Files ## Layer 2: Agent Personas — Specialised Identities ## Layer 3: Skills — Reusable Knowledge Modules ## Layer 4: Auto Memory — Learning Across Sessions ## Layer 5: Plans — Persistent Iteration ## Layer 6: Permissions — Trust Boundaries ## How It All Comes Together ## Practical Tips ## Conclusion ## References AI agents forget everything. Every new session starts from zero — no context about your project, no memory of architectural decisions, no knowledge of your coding standards. You end up repeating yourself constantly. I run 14 specialised agents across multiple AWS projects — an HLD Architect, a DevOps Engineer, an SDET, a Defect Manager, a Technical Content Engineer, and more. Each one needs to understand the codebase, follow specific rules, and build on work from previous sessions. Repeating context every session is not an option. So I built a multi-layered memory architecture in Claude Code that gives my agents persistent knowledge, specialised expertise, and consistent behaviour across every conversation. Here is exactly how I do it. My agent memory system has six layers, each solving a different problem: Every layer is just markdown files. No databases, no APIs, no infrastructure — just files that Claude Code loads automatically. Every project has a CLAUDE.md file at its root. Claude Code reads this file automatically at the start of every session. It is the single most important file in my entire setup. My root CLAUDE.md sits at the workspace level and defines global rules that every agent must follow — what I call the TBT Law (Think Before Typing): These ten rules prevent the most common failure mode with AI agents: doing too much, too fast, without thinking. Every agent, regardless of persona, follows these rules. Below the TBT Law, the root CLAUDE.md defines: Each project directory has its own CLAUDE.md that inherits from the root and adds project-specific context: This means the agent immediately knows what the project is, what stack it uses, how it deploys, and how it connects to other services — before I type a single word. I have 14 agent persona files, each defined as a markdown document. When I need a specific type of expertise, I load the corresponding persona. Each persona file follows a consistent structure: The key insight is that personas are not prompts — they are persistent identity files that the agent loads and embodies for the entire session. The DevOps Engineer thinks differently from the SDET, who thinks differently from the HLD Architect. They have different priorities, different vocabularies, and different workflows. When I say "load the DevOps Engineer persona", the agent reads the file and adopts that identity — including its specific workflow, constraints, and communication style. Skills are the most underrated layer. They are standalone knowledge files (.skill.md) that any persona can reference. Think of them as shared libraries for agent knowledge. Examples from my setup: A skill file looks like this: The power of skills is composition. When the LLD Architect is designing a new service, it can reference the DynamoDB skill, the HATEOAS skill, and the Development Best Practices skill simultaneously. When the SDET is writing tests, it pulls from the API Proxy Testing skill. The knowledge is defined once and reused across every persona. Claude Code has a built-in auto memory feature. It stores persistent notes in a memory/ directory within each project: The MEMORY.md file is special — Claude Code loads the first 200 lines of it into every conversation automatically. This is where the agent stores things it has learned: I configure the agent to save memories with clear rules: The result is that the agent gets smarter over time. The first time it encounters the CloudFront routing behaviour, it investigates. The second time, it already knows. Plans bridge the gap between sessions. When a task is too large for one conversation, the agent writes a plan file: A plan follows a consistent structure: When a new session starts and the plan file exists, Claude Code includes a reminder: "A plan file exists from plan mode. If this plan is relevant to the current work and not already complete, continue working on it." This means the agent picks up exactly where it left off — no re-explanation needed. The final layer controls what each agent can actually do. Claude Code uses settings.local.json to define allowed operations per project: My permissions file is 276 lines long. It covers Git operations, AWS CLI commands (IAM, S3, Lambda, DynamoDB, CloudFront, Route53), Terraform, Python tooling, and testing frameworks. This is critical for the TBT Law. The agent can run tests and deploy to dev, but it cannot force-push to main or destroy production infrastructure without explicit approval. Here is a real workflow. I need to deploy a bug fix to a frontend app. I open the project. Claude Code loads CLAUDE.md (Layer 1) — the agent knows the stack, deployment targets, and global rules. I say "load the DevOps Engineer." The agent reads the persona file (Layer 2) — it now thinks like a DevOps engineer with CI/CD expertise. The agent references existing knowledge. It checks auto memory (Layer 4) for deployment patterns — it already knows the S3 bucket name, CloudFront distribution ID, and safe sync exclusions. It creates a plan. The plan (Layer 5) outlines: build, sync to S3, invalidate CloudFront, verify. Per TBT Law, it waits for my approval. I approve. The agent executes within its permissions (Layer 6) — it can run npm run build and aws s3 sync, but it asks before running destructive commands. SDET verification triggers. Per the CLAUDE.md mandatory rule, the SDET persona activates to verify the deployment — checking asset integrity, page load, and console errors. The agent saves what it learned. If it encountered a new pattern (like a CloudFront cache behaviour), it writes it to auto memory for next time. Six layers, all markdown files, zero infrastructure. Start with CLAUDE.md. You do not need all six layers on day one. A well-written CLAUDE.md with your project context and coding standards gives you 80% of the value. Write personas for recurring roles. If you find yourself repeatedly explaining "you are a DevOps engineer who follows these patterns", extract it into a persona file. Keep skills atomic. One skill, one topic. A DynamoDB skill should not also contain API design patterns. Composability comes from keeping them separate. Curate auto memory. Review what the agent saves. Remove outdated entries. The memory file is limited to 200 lines — keep it focused on patterns that are genuinely stable. Use plans for multi-session work. If a task will take more than one conversation, write a plan. The overhead of creating the plan pays for itself when you do not have to re-explain the context. Set permissions deliberately. Start restrictive and expand. It is easier to grant new permissions than to recover from an agent that deleted your production database. AI agents do not need to forget. The tools already exist in Claude Code — CLAUDE.md files, auto memory, plan persistence, and permission controls. What they need is architecture. By structuring memory into six layers — rules, personas, skills, learning, plans, and permissions — I have agents that understand my projects, follow my standards, learn from past sessions, and operate within clear boundaries. Every layer is a markdown file. Every file is version-controlled. The entire system is transparent, auditable, and easy to iterate on. The best part? The agents get better every week. Not because the model improved, but because the memory did. Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse CODE_BLOCK: ┌──────────────────────────────────────────────┐ │ Layer 6: Permissions (settings.local.json) │ What the agent CAN do ├──────────────────────────────────────────────┤ │ Layer 5: Plans (.claude/plans/*.md) │ What the agent IS doing ├──────────────────────────────────────────────┤ │ Layer 4: Auto Memory (memory/MEMORY.md) │ What the agent HAS learned ├──────────────────────────────────────────────┤ │ Layer 3: Skills (*.skill.md) │ HOW to do specific things ├──────────────────────────────────────────────┤ │ Layer 2: Agent Personas (*_Agent.md) │ WHO the agent is ├──────────────────────────────────────────────┤ │ Layer 1: CLAUDE.md (project instructions) │ The rules everyone follows └──────────────────────────────────────────────┘ Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: ┌──────────────────────────────────────────────┐ │ Layer 6: Permissions (settings.local.json) │ What the agent CAN do ├──────────────────────────────────────────────┤ │ Layer 5: Plans (.claude/plans/*.md) │ What the agent IS doing ├──────────────────────────────────────────────┤ │ Layer 4: Auto Memory (memory/MEMORY.md) │ What the agent HAS learned ├──────────────────────────────────────────────┤ │ Layer 3: Skills (*.skill.md) │ HOW to do specific things ├──────────────────────────────────────────────┤ │ Layer 2: Agent Personas (*_Agent.md) │ WHO the agent is ├──────────────────────────────────────────────┤ │ Layer 1: CLAUDE.md (project instructions) │ The rules everyone follows └──────────────────────────────────────────────┘ CODE_BLOCK: ┌──────────────────────────────────────────────┐ │ Layer 6: Permissions (settings.local.json) │ What the agent CAN do ├──────────────────────────────────────────────┤ │ Layer 5: Plans (.claude/plans/*.md) │ What the agent IS doing ├──────────────────────────────────────────────┤ │ Layer 4: Auto Memory (memory/MEMORY.md) │ What the agent HAS learned ├──────────────────────────────────────────────┤ │ Layer 3: Skills (*.skill.md) │ HOW to do specific things ├──────────────────────────────────────────────┤ │ Layer 2: Agent Personas (*_Agent.md) │ WHO the agent is ├──────────────────────────────────────────────┤ │ Layer 1: CLAUDE.md (project instructions) │ The rules everyone follows └──────────────────────────────────────────────┘ COMMAND_BLOCK: ## TBT Law (Inviolable) 1. Be patient — 80% planning, 20% implementation 2. Do not be overeager — never try to impress by doing unrequested work 3. Always seek approval before implementing any plan 4. Never make changes without a plan — plan first, always 5. Do not rush the user — be patient, wait for direction 6. Do not make decisions or assumptions on the user's behalf 7. If unsure, ask — never guess or assume 8. If the plan isn't working, STOP — no workarounds 9. Rushing and over-eager changes will break code or design 10. If rules are violated, admit openly — do not hide mistakes Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: ## TBT Law (Inviolable) 1. Be patient — 80% planning, 20% implementation 2. Do not be overeager — never try to impress by doing unrequested work 3. Always seek approval before implementing any plan 4. Never make changes without a plan — plan first, always 5. Do not rush the user — be patient, wait for direction 6. Do not make decisions or assumptions on the user's behalf 7. If unsure, ask — never guess or assume 8. If the plan isn't working, STOP — no workarounds 9. Rushing and over-eager changes will break code or design 10. If rules are violated, admit openly — do not hide mistakes COMMAND_BLOCK: ## TBT Law (Inviolable) 1. Be patient — 80% planning, 20% implementation 2. Do not be overeager — never try to impress by doing unrequested work 3. Always seek approval before implementing any plan 4. Never make changes without a plan — plan first, always 5. Do not rush the user — be patient, wait for direction 6. Do not make decisions or assumptions on the user's behalf 7. If unsure, ask — never guess or assume 8. If the plan isn't working, STOP — no workarounds 9. Rushing and over-eager changes will break code or design 10. If rules are violated, admit openly — do not hide mistakes COMMAND_BLOCK: # my-saas-landing - Project Instructions ## Project Overview **Repository**: my-saas-landing **Purpose**: Marketing landing page - Single-page scroll site **Stack**: React 18 + TypeScript + Vite ## Cross-App Navigation | Action | Target URL | |-------------------------|-------------------------------| | "Start Free Trial" | /app/onboarding | | "Buy" pricing button | /checkout?planId={id} | ## S3 Deployment Landing page files deploy to the root of my-web-public S3 bucket... Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # my-saas-landing - Project Instructions ## Project Overview **Repository**: my-saas-landing **Purpose**: Marketing landing page - Single-page scroll site **Stack**: React 18 + TypeScript + Vite ## Cross-App Navigation | Action | Target URL | |-------------------------|-------------------------------| | "Start Free Trial" | /app/onboarding | | "Buy" pricing button | /checkout?planId={id} | ## S3 Deployment Landing page files deploy to the root of my-web-public S3 bucket... COMMAND_BLOCK: # my-saas-landing - Project Instructions ## Project Overview **Repository**: my-saas-landing **Purpose**: Marketing landing page - Single-page scroll site **Stack**: React 18 + TypeScript + Vite ## Cross-App Navigation | Action | Target URL | |-------------------------|-------------------------------| | "Start Free Trial" | /app/onboarding | | "Buy" pricing button | /checkout?planId={id} | ## S3 Deployment Landing page files deploy to the root of my-web-public S3 bucket... COMMAND_BLOCK: # DevOps Engineer Agent ## Identity You are a Senior DevOps Engineer specialising in AWS infrastructure... ## Core Competencies - CI/CD pipeline design (GitHub Actions) - Infrastructure as Code (Terraform) - Container orchestration (ECS, ECR) - CloudFront distribution management ## Workflow 1. Assess current infrastructure state 2. Propose changes with risk assessment 3. Implement with rollback plan 4. Verify deployment 5. Document changes ## Constraints - Never modify production without approval - Always use Terraform for infrastructure changes - Follow the AWS Well-Architected Framework Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # DevOps Engineer Agent ## Identity You are a Senior DevOps Engineer specialising in AWS infrastructure... ## Core Competencies - CI/CD pipeline design (GitHub Actions) - Infrastructure as Code (Terraform) - Container orchestration (ECS, ECR) - CloudFront distribution management ## Workflow 1. Assess current infrastructure state 2. Propose changes with risk assessment 3. Implement with rollback plan 4. Verify deployment 5. Document changes ## Constraints - Never modify production without approval - Always use Terraform for infrastructure changes - Follow the AWS Well-Architected Framework COMMAND_BLOCK: # DevOps Engineer Agent ## Identity You are a Senior DevOps Engineer specialising in AWS infrastructure... ## Core Competencies - CI/CD pipeline design (GitHub Actions) - Infrastructure as Code (Terraform) - Container orchestration (ECS, ECR) - CloudFront distribution management ## Workflow 1. Assess current infrastructure state 2. Propose changes with risk assessment 3. Implement with rollback plan 4. Verify deployment 5. Document changes ## Constraints - Never modify production without approval - Always use Terraform for infrastructure changes - Follow the AWS Well-Architected Framework COMMAND_BLOCK: # DynamoDB Single Table Design ## When to Apply Apply when a service has 3+ entity types with relational access patterns. ## Partition Key Strategy - Use composite keys: {ENTITY_TYPE}#{ENTITY_ID} - GSI1PK for inverted lookups - GSI2PK for cross-entity queries ## Access Patterns | Pattern | PK | SK | Index | |---------|----|----|-------| | Get user by ID | USER#123 | METADATA | Table | | Get user's sites | USER#123 | SITE# | Table | | Get site by domain | DOMAIN#example.com | METADATA | GSI1 | Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # DynamoDB Single Table Design ## When to Apply Apply when a service has 3+ entity types with relational access patterns. ## Partition Key Strategy - Use composite keys: {ENTITY_TYPE}#{ENTITY_ID} - GSI1PK for inverted lookups - GSI2PK for cross-entity queries ## Access Patterns | Pattern | PK | SK | Index | |---------|----|----|-------| | Get user by ID | USER#123 | METADATA | Table | | Get user's sites | USER#123 | SITE# | Table | | Get site by domain | DOMAIN#example.com | METADATA | GSI1 | COMMAND_BLOCK: # DynamoDB Single Table Design ## When to Apply Apply when a service has 3+ entity types with relational access patterns. ## Partition Key Strategy - Use composite keys: {ENTITY_TYPE}#{ENTITY_ID} - GSI1PK for inverted lookups - GSI2PK for cross-entity queries ## Access Patterns | Pattern | PK | SK | Index | |---------|----|----|-------| | Get user by ID | USER#123 | METADATA | Table | | Get user's sites | USER#123 | SITE# | Table | | Get site by domain | DOMAIN#example.com | METADATA | GSI1 | COMMAND_BLOCK: ~/.claude/projects/{project-path}/memory/ ├── MEMORY.md # Always loaded (first 200 lines) ├── debugging.md # Detailed debugging notes ├── patterns.md # Confirmed patterns └── architecture.md # Architectural decisions Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: ~/.claude/projects/{project-path}/memory/ ├── MEMORY.md # Always loaded (first 200 lines) ├── debugging.md # Detailed debugging notes ├── patterns.md # Confirmed patterns └── architecture.md # Architectural decisions COMMAND_BLOCK: ~/.claude/projects/{project-path}/memory/ ├── MEMORY.md # Always loaded (first 200 lines) ├── debugging.md # Detailed debugging notes ├── patterns.md # Confirmed patterns └── architecture.md # Architectural decisions COMMAND_BLOCK: ## Confirmed Patterns - CloudFront Function handles SPA routing for all frontends - S3 bucket serves all frontend apps from different prefixes - Safe sync requires --exclude flags for other app prefixes - Browser cache causes stale content after deployments (hard refresh needed) ## AWS SSO - Profile name: dev - Token expires frequently — run `aws sso login --profile dev` Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: ## Confirmed Patterns - CloudFront Function handles SPA routing for all frontends - S3 bucket serves all frontend apps from different prefixes - Safe sync requires --exclude flags for other app prefixes - Browser cache causes stale content after deployments (hard refresh needed) ## AWS SSO - Profile name: dev - Token expires frequently — run `aws sso login --profile dev` COMMAND_BLOCK: ## Confirmed Patterns - CloudFront Function handles SPA routing for all frontends - S3 bucket serves all frontend apps from different prefixes - Safe sync requires --exclude flags for other app prefixes - Browser cache causes stale content after deployments (hard refresh needed) ## AWS SSO - Profile name: dev - Token expires frequently — run `aws sso login --profile dev` COMMAND_BLOCK: ~/.claude/plans/ ├── zazzy-puzzling-cloud.md # Frontend extraction plan ├── elegant-crunching-sunbeam.md # Security hardening rollout └── zazzy-percolating-lecun.md # CDN deployment plan Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: ~/.claude/plans/ ├── zazzy-puzzling-cloud.md # Frontend extraction plan ├── elegant-crunching-sunbeam.md # Security hardening rollout └── zazzy-percolating-lecun.md # CDN deployment plan COMMAND_BLOCK: ~/.claude/plans/ ├── zazzy-puzzling-cloud.md # Frontend extraction plan ├── elegant-crunching-sunbeam.md # Security hardening rollout └── zazzy-percolating-lecun.md # CDN deployment plan COMMAND_BLOCK: # Plan: Extract Landing Page into Standalone Repo ## Context The landing page was prototyped inside the main app... ## Step 1: Scaffold New Repo Create directory structure at /path/to/new/repo... ## Step 2: Create Fresh Files - vite.config.ts — base: '/' - App.tsx — no router, single-page scroll ## Step 3: Modify Copied Files - Navigation.tsx — remove router dependency - PricingPage.tsx — use window.location.href ## Verification 1. npm run dev → all sections render 2. npm run type-check → 0 errors 3. Images and assets load correctly Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Plan: Extract Landing Page into Standalone Repo ## Context The landing page was prototyped inside the main app... ## Step 1: Scaffold New Repo Create directory structure at /path/to/new/repo... ## Step 2: Create Fresh Files - vite.config.ts — base: '/' - App.tsx — no router, single-page scroll ## Step 3: Modify Copied Files - Navigation.tsx — remove router dependency - PricingPage.tsx — use window.location.href ## Verification 1. npm run dev → all sections render 2. npm run type-check → 0 errors 3. Images and assets load correctly COMMAND_BLOCK: # Plan: Extract Landing Page into Standalone Repo ## Context The landing page was prototyped inside the main app... ## Step 1: Scaffold New Repo Create directory structure at /path/to/new/repo... ## Step 2: Create Fresh Files - vite.config.ts — base: '/' - App.tsx — no router, single-page scroll ## Step 3: Modify Copied Files - Navigation.tsx — remove router dependency - PricingPage.tsx — use window.location.href ## Verification 1. npm run dev → all sections render 2. npm run type-check → 0 errors 3. Images and assets load correctly CODE_BLOCK: { "permissions": { "allow": [ "Bash(git add *)", "Bash(git commit *)", "Bash(aws s3 sync *)", "Bash(aws cloudfront create-invalidation *)", "Bash(terraform plan *)", "Bash(pytest *)", "Bash(npm run build *)" ] } } Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: { "permissions": { "allow": [ "Bash(git add *)", "Bash(git commit *)", "Bash(aws s3 sync *)", "Bash(aws cloudfront create-invalidation *)", "Bash(terraform plan *)", "Bash(pytest *)", "Bash(npm run build *)" ] } } CODE_BLOCK: { "permissions": { "allow": [ "Bash(git add *)", "Bash(git commit *)", "Bash(aws s3 sync *)", "Bash(aws cloudfront create-invalidation *)", "Bash(terraform plan *)", "Bash(pytest *)", "Bash(npm run build *)" ] } } - Mandatory SDET Verification — every plan must be tested after execution - Defect Management — every bug gets logged, reproduced, fixed, and verified - Deployment-First Verification — no fix is considered testable until deployed - Repository Isolation — every service gets its own repo - AWS Resource Naming Conventions — DynamoDB tables use plain names, S3 buckets include environment suffixes - DynamoDB_Single_Table.skill.md — Single-table design patterns, GSI strategies, access patterns - HATEOAS_Relational_Design.skill.md — API design with hypermedia links - Development_Best_Practices.skill.md — SOLID, TDD, BDD, DDD principles - Monolith_Anti_Pattern_Validation.skill.md — Six anti-patterns (AP-1 through AP-6) to detect - Step_Functions_Decision_Logic.skill.md — State machine patterns - API_Proxy_Testing.skill.md — End-to-end testing patterns - Save: Stable patterns confirmed across multiple sessions - Save: Key architectural decisions and important file paths - Save: Solutions to recurring problems - Don't save: Session-specific context or temporary state - Don't save: Speculative conclusions from reading a single file - I open the project. Claude Code loads CLAUDE.md (Layer 1) — the agent knows the stack, deployment targets, and global rules. - I say "load the DevOps Engineer." The agent reads the persona file (Layer 2) — it now thinks like a DevOps engineer with CI/CD expertise. - The agent references existing knowledge. It checks auto memory (Layer 4) for deployment patterns — it already knows the S3 bucket name, CloudFront distribution ID, and safe sync exclusions. - It creates a plan. The plan (Layer 5) outlines: build, sync to S3, invalidate CloudFront, verify. Per TBT Law, it waits for my approval. - I approve. The agent executes within its permissions (Layer 6) — it can run npm run build and aws s3 sync, but it asks before running destructive commands. - SDET verification triggers. Per the CLAUDE.md mandatory rule, the SDET persona activates to verify the deployment — checking asset integrity, page load, and console errors. - The agent saves what it learned. If it encountered a new pattern (like a CloudFront cache behaviour), it writes it to auto memory for next time. - Claude Code Documentation — Anthropic - CLAUDE.md Best Practices — Anthropic - Model Context Protocol (MCP) — Specification - Claude Code CLI — GitHub