Claude Code Memory: Project, User, and Auto-Memory in a 200-Engineer Org

Table of Contents

1. Why Memory Architecture Matters at Scale
2. Understanding Claude Code’s Memory Layers
3. Project Memory: What Belongs Here
4. User Memory: Personal Context and Preferences
5. Auto-Memory: The Invisible Learning System
6. CLAUDE.md vs MEMORY.md: The Critical Distinction
7. What Should Never Be Written Down
8. Governance and Hygiene Policies for 200+ Engineers
9. Implementation Roadmap
10. Real-World Case Studies

---

Why Memory Architecture Matters at Scale

When you’re running 200 engineers using Claude Code as a co-pilot, memory hygiene isn’t optional—it’s the difference between a 4-week feature sprint and a 12-week nightmare of repeated context, hallucinations, and lost institutional knowledge.

At PADISO, we’ve worked with scaling engineering teams across Sydney and beyond. What we’ve learned is this: Claude Code’s memory systems are powerful, but they’re also fragile. Without clear policies, you end up with:

• Stale project context: Engineers working on the same codebase with completely different mental models because their project memory diverged three months ago.
• Credential leaks: API keys, database passwords, and OAuth tokens scattered across MEMORY.md files that sync across user accounts.
• Token waste: Bloated CLAUDE.md files that repeat the same architectural guidance five times over, consuming tokens without adding value.
• Inconsistent outputs: One team’s Claude Code produces clean, idiomatic code; another’s produces verbose, over-engineered solutions because their memory systems trained the AI differently.

This guide is built on real deployments. We’ll walk through how to structure memory across three layers—project, user, and auto-memory—so that 200 engineers can work in parallel without stepping on each other or losing institutional knowledge.

---

Understanding Claude Code’s Memory Layers

Claude Code operates with four distinct memory layers, each with different scopes, lifespans, and purposes. Understanding these layers is foundational to building a governance framework that scales.

The Four-Layer Architecture

Layer 1: Session Memory This is ephemeral. Everything you discuss with Claude Code within a single session lives here. It’s fast, context-rich, and dies the moment you close the session. Session memory is where Claude Code “sees” your current code, your recent edits, and your immediate conversation history.

Layer 2: Auto-Memory This is where Claude Code learns without you explicitly telling it to. Auto-memory automatically captures patterns from your sessions: recurring file structures, naming conventions, architectural patterns, feedback you’ve given, and project-specific preferences. Unlike session memory, auto-memory persists across sessions and is designed to be organic—Claude Code builds it as you work.

Layer 3: Project Memory (MEMORY.md) This is the explicit, human-written layer. You create a MEMORY.md file in your project root, and Claude Code reads it at the start of every session. This file should contain architectural decisions, setup instructions, common patterns, and critical context that auto-memory might miss or that you want to guarantee Claude Code knows.

Layer 4: User Memory (CLAUDE.md) This is the global layer. You maintain a CLAUDE.md file in a designated directory (typically ~/.claude or a synced folder), and Claude Code reads it before every session, regardless of which project you’re working on. This is where you store personal coding preferences, global architectural principles, security policies, and anything that should apply across all your projects.

For a detailed technical breakdown, Claude Code’s official memory documentation is the canonical reference.

Memory Scope and Persistence

Layer	Scope	Persistence	Who Manages	Typical Size
Session	Current conversation	Dies with session	Automatic	50–200 KB
Auto-Memory	Single project	Across sessions, per project	Automatic	100–500 KB
Project Memory (MEMORY.md)	Single project	Indefinite	Human	10–50 KB
User Memory (CLAUDE.md)	All projects	Indefinite	Human	5–20 KB

The critical insight: auto-memory and project memory are often redundant. If you design MEMORY.md correctly, auto-memory becomes a safety net, not a primary system. This distinction is crucial for large teams.

---

Project Memory: What Belongs Here

Your MEMORY.md file is the contract between humans and Claude Code. It should contain everything that:

1. Is stable (unlikely to change week-to-week)
2. Is critical (Claude Code must know this or outputs will be wrong)
3. Is not obvious from reading the codebase

Essential MEMORY.md Sections

Architecture Overview Include a 2–3 paragraph summary of your system’s architecture. Don’t write a 50-page design document. Write:

• What the system does
• What it doesn’t do
• How data flows (at 10,000 feet)
• What external systems it talks to

Example:

## Architecture

This is a real-time event streaming platform built on Kafka and Rust.
We consume events from 50+ upstream services, enrich them with ML models,
and stream to Elasticsearch and a data warehouse. We do NOT handle storage—
that's downstream. Latency SLA is <500ms p99 for enrichment.

Tech Stack and Versions List the languages, frameworks, and critical libraries your project uses. Include versions if they’re locked (e.g., Node 20.11, Rust 1.75). This prevents Claude Code from suggesting APIs that don’t exist in your version.

Setup and Environment Include the exact steps to get a clean checkout running locally. This might be:

• Clone command
• Required environment variables (not secrets—use placeholder names)
• Database setup (schema migrations, seed data)
• How to run tests
• How to run the dev server

Keep it under 20 lines. If it’s longer, link to a detailed README.

Coding Standards and Patterns Document the patterns Claude Code should follow:

• Error handling: Do you use exceptions, Result types, or error codes?
• Logging: What should be logged, at what level?
• Testing: What’s your test naming convention? How much coverage do you expect?
• Database: ORM, raw SQL, migrations—what’s the pattern?
• API design: REST, gRPC, GraphQL? What’s your versioning strategy?

Be specific. Instead of “write clean code,” write:

## Error Handling

Use Result<T, Error> for all fallible operations. Never panic in production code.
For user-facing errors, return 400-level HTTP status; for internal errors, return 500.
Always include error.cause() in logs.

Critical Dependencies and Integration Points List the external services your code talks to and any quirks:

• “Stripe API v3 has a 30-second timeout; we retry with exponential backoff.”
• “Our Postgres database is read-only from the app layer; writes go through a separate service.”
• “Kafka topics are prefixed with prod- or dev- depending on environment; never hardcode.”

This prevents Claude Code from making assumptions that break in production.

Common Gotchas and Anti-Patterns Document things that trip up new developers—and Claude Code:

• “Don’t use SELECT * in queries; it breaks when we add columns.”
• “Timestamps must always be UTC; never use local time.”
• “This codebase has two different authentication systems; use the new one (oauth2) for new features.”

Performance and Scalability Constraints If your system has known bottlenecks or constraints, document them:

• “This service handles 10k req/s; anything slower will cause cascading failures.”
• “Database queries must complete in <100ms; use EXPLAIN ANALYZE before committing.”
• “Memory usage is capped at 2GB; we’ve had OOM crashes before.”

MEMORY.md Size and Limits

Claude Code’s memory system has documented limits. Your MEMORY.md should be no longer than 50 KB. In practice, aim for 10–20 KB. That’s roughly 2,000–4,000 words—plenty of space for the essentials.

If your MEMORY.md is longer than 50 KB, you’re doing it wrong. You’re either:

• Including implementation details that should be in comments in the code
• Duplicating information that’s already in your README
• Trying to encode too much institutional knowledge in one file

If you’re at 40+ KB, split it. Create separate files: ARCHITECTURE.md for deep dives, SETUP.md for environment configuration, PATTERNS.md for coding standards. Then link to them from MEMORY.md:

## Architecture

See ARCHITECTURE.md for a detailed system design.

## Setup

See SETUP.md for environment configuration.

Claude Code will read MEMORY.md automatically; for the others, you’ll need to reference them explicitly in your prompt if context is tight.

---

User Memory: Personal Context and Preferences

Your CLAUDE.md file is personal. It travels with you across all projects. It should contain:

1. Your coding preferences (indentation, naming, structure)
2. Global architectural principles (microservices, monolith, serverless)
3. Security and compliance policies (how you handle secrets, logging, PII)
4. Tools and workflows you use everywhere
5. Team-wide standards (if you’re a tech lead or CTO)

What to Include in CLAUDE.md

Personal Coding Style

## Code Style

- Indentation: 2 spaces (never tabs)
- Line length: 100 characters (soft), 120 (hard)
- Comments: Only for "why," not "what"
- Variable names: camelCase for JavaScript, snake_case for Python/Rust
- Functions: Single responsibility principle; max 30 lines

Language-Specific Preferences If you work in multiple languages, document how you want each one written:

## Python

- Use type hints on all functions
- Use dataclasses for data structures, not dicts
- Use pathlib.Path, never os.path
- Docstrings: Google style, not NumPy

## JavaScript

- Use const by default, let only when needed, never var
- Use async/await, not .then()
- Use TypeScript for anything >500 lines

Security and Compliance Document how you handle sensitive data:

## Security

- Never log passwords, tokens, or API keys. Use redaction.
- All database connections must use SSL.
- Environment variables: Use .env files locally, never commit them.
- Secrets: Rotate every 90 days.
- PII: Never log, never cache, always encrypt at rest.

This is especially important for teams pursuing SOC 2 or ISO 27001 compliance. When auditors review Claude Code’s outputs, they’ll see these standards enforced consistently.

Team-Wide Policies (if you’re a tech lead) If you’re a CTO or engineering lead, your CLAUDE.md becomes a force multiplier. Document:

• Architectural decisions your org has made (monolith vs microservices, cloud provider, database choice)
• Deployment and CI/CD standards
• Code review expectations
• Testing requirements
• On-call and incident response procedures

Example:

## Deployment

- All code goes through GitHub Actions before merge to main
- Tests must pass (>80% coverage)
- Code review: 2 approvals for main, 1 for develop
- Deployment to production: Automated after merge, with 5-minute rollback window
- Monitoring: All services must have >/=3 Datadog dashboards

Tools and Integrations List the tools your team uses and how Claude Code should integrate with them:

## Tools

- Version control: GitHub (not GitLab or Bitbucket)
- CI/CD: GitHub Actions (not Jenkins or CircleCI)
- Monitoring: Datadog (not New Relic)
- Incident tracking: PagerDuty
- Documentation: Notion (not Confluence)

CLAUDE.md Size and Scope

Keep this to 5–20 KB (1,000–4,000 words). It’s personal guidance, not a company manual. If it’s longer, you’re either:

• Over-documenting (trim it)
• Mixing personal and team-wide standards (split into CLAUDE.md and a team repo)
• Encoding too much history (focus on current standards, not why you changed them)

Critical: Your CLAUDE.md should be versionable. If you’re working across multiple projects, keep it in a synced location (Dropbox, Google Drive, iCloud) or a private GitHub repo. When you update it, the changes apply to all future Claude Code sessions.

---

Auto-Memory: The Invisible Learning System

Auto-memory is where Claude Code learns from your work without you explicitly teaching it. Claude Code’s auto-memory system automatically captures:

• File structures: How you organize code
• Naming conventions: How you name variables, functions, classes
• Patterns: Recurring architectural patterns in your codebase
• Feedback: Corrections you make to Claude Code’s suggestions
• Preferences: Your responses to Claude Code’s questions

Unlike project and user memory, auto-memory is emergent. You don’t write it; Claude Code builds it as you work.

How Auto-Memory Works

Auto-memory has five categories:

1. User Memory: Global patterns learned from all your projects
2. Feedback Memory: Corrections you’ve made to Claude Code
3. Project Memory: Patterns specific to this project
4. Reference Memory: Files you’ve explicitly marked as important
5. MEMORY.md Indexing: Connections between auto-memory and your explicit MEMORY.md

A detailed breakdown of Claude Code’s four-layer memory architecture explains how these categories interact. The key insight: auto-memory is probabilistic. It learns from patterns, but it can also learn bad patterns if you’re not careful.

Managing Auto-Memory in a Large Org

With 200 engineers, auto-memory becomes a liability if you don’t manage it:

Problem 1: Divergent Auto-Memory Engineer A works on a microservice and trains auto-memory to expect small, focused modules. Engineer B works on a monolith and trains auto-memory to expect large, cohesive services. When Engineer C joins and uses Claude Code, which auto-memory do they get? Answer: it depends on which project they start in.

Solution: Use MEMORY.md to override auto-memory. If you’ve documented your architectural standards in MEMORY.md, Claude Code will prioritise that over learned patterns. This prevents auto-memory drift.

Problem 2: Stale Auto-Memory Your team refactored from callbacks to async/await six months ago. But auto-memory still remembers the callback pattern because it’s baked into the older files. Claude Code suggests callbacks for new code.

Solution: Explicitly mark old files as deprecated in MEMORY.md:

## Deprecated Patterns

Do NOT use callback-based async (old_callbacks.js). Use async/await instead.
See modern_async.js for the current pattern.

Problem 3: Auto-Memory Leakage Auto-memory is per-project. But if an engineer works on two projects with different standards, auto-memory from Project A can leak into Project B if they’re in the same user account.

Solution: Use separate Claude Code accounts for projects with fundamentally different architectures (e.g., a legacy monolith and a new microservices platform). Or use MEMORY.md to explicitly override auto-memory:

## Overrides

Ignore auto-learned patterns from other projects. Use the patterns in this MEMORY.md.

When to Trust Auto-Memory

Auto-memory is powerful when:

• You’re in a stable codebase: Patterns don’t change frequently
• You’re consistent: You follow the same standards across files
• You’re explicit about feedback: You correct Claude Code when it’s wrong, and it learns
• You’re working alone or in a small team: Fewer people = fewer divergent patterns

Auto-memory is risky when:

• You’re in a large, diverse codebase: Multiple teams, multiple patterns
• You’re refactoring: Old patterns still exist alongside new ones
• You’re onboarding: New engineers haven’t trained auto-memory yet
• You’re scaling: 200 engineers = 200 different auto-memories

For large orgs, treat auto-memory as a convenience, not a primary system. Your MEMORY.md is the source of truth.

---

CLAUDE.md vs MEMORY.md: The Critical Distinction

This is where most teams go wrong. They confuse CLAUDE.md and MEMORY.md, or they use one when they should use the other. Here’s the definitive guide:

CLAUDE.md: Global, Personal, Persistent

Scope: All projects you work on Persistence: Across all sessions, all projects Who manages it: You (or your team’s tech lead) When to update: When your personal preferences or team-wide standards change Size: 5–20 KB What belongs here:

• Your personal coding style (indentation, naming, structure)
• Language-specific preferences
• Security and compliance policies (global)
• Team-wide architectural decisions
• Tools and integrations your org uses
• On-call and incident response procedures

What doesn’t belong here:

• Project-specific setup instructions
• Project-specific architecture
• Project-specific tech stack
• Project-specific patterns or anti-patterns

MEMORY.md: Local, Project-Specific, Explicit

Scope: Single project only Persistence: Indefinite (as long as the file exists) Who manages it: The team working on that project When to update: When architecture, setup, or standards change for that project Size: 10–50 KB What belongs here:

• Project architecture (10,000-foot view)
• Tech stack and versions
• Setup and environment configuration
• Project-specific coding standards
• Critical dependencies and integration points
• Common gotchas and anti-patterns
• Performance and scalability constraints

What doesn’t belong here:

• Your personal coding style (use CLAUDE.md)
• Global security policies (use CLAUDE.md)
• Implementation details (use comments in code)
• Historical decisions (use commit messages)

The Interaction Model

When Claude Code starts a session, it reads memory in this order:

1. Session memory (from current conversation)
2. CLAUDE.md (user global preferences)
3. Auto-memory (learned patterns from this project)
4. MEMORY.md (project-specific context)

Later layers override earlier layers. So if CLAUDE.md says “use 2-space indentation” but MEMORY.md says “use 4-space indentation,” MEMORY.md wins for that project.

This is intentional. It allows:

• Personal defaults (CLAUDE.md) that apply everywhere
• Project overrides (MEMORY.md) that apply to specific projects
• Learned patterns (auto-memory) that fill in gaps
• Immediate context (session memory) that’s always current

Example: A Scaling Org

Imagine you’re a CTO at a 200-engineer org. You have:

CLAUDE.md (in your synced folder, shared with all engineers):

## Global Standards

- Language: TypeScript for all new services
- Testing: Jest with >80% coverage
- Linting: ESLint with Prettier
- Security: All secrets in AWS Secrets Manager
- Logging: Winston with JSON format
- Monitoring: Datadog for all services

Project A MEMORY.md (legacy monolith, being phased out):

## Architecture

This is a Rails monolith built in 2015. We're migrating to microservices.
For now, all new features go in the legacy service; don't create new services.

## Tech Stack

- Ruby 2.7 (upgrading to 3.0 next quarter)
- Rails 5.2
- PostgreSQL

## Setup

$ git clone ...
$ bundle install
$ rails db:setup
$ rails server

## Patterns

Use ActiveRecord for database access. Use Sidekiq for async jobs.

Project B MEMORY.md (new microservice):

## Architecture

This is a new event-streaming service. It consumes Kafka events,
enriches them with ML models, and writes to Elasticsearch.

## Tech Stack

- Node.js 20.11
- TypeScript
- Kafka client: kafkajs
- Database: PostgreSQL (read-only)

## Setup

$ git clone ...
$ npm install
$ npm run dev

## Patterns

Use async/await, never callbacks. Use zod for schema validation.
All errors must be Result types, not exceptions.

When Engineer A works on Project A, Claude Code reads CLAUDE.md (global standards) and Project A’s MEMORY.md (legacy Rails patterns). It learns that this project uses Rails, so it suggests Rails-idiomatic code.

When Engineer B works on Project B, Claude Code reads the same CLAUDE.md but Project B’s MEMORY.md (new Node/TypeScript patterns). It learns that this project uses TypeScript, so it suggests TypeScript-idiomatic code.

Both projects follow the global standards (Datadog, JSON logging, secrets in AWS Secrets Manager) but diverge on language and framework. This is the correct model.

---

What Should Never Be Written Down

This is the hygiene part. There are things that should never appear in CLAUDE.md, MEMORY.md, or auto-memory, no matter how convenient it would be.

Secrets and Credentials

Never write down:

• API keys
• Database passwords
• OAuth tokens
• Private keys
• SSH keys
• Any credential that grants access to a system

Why: MEMORY.md and CLAUDE.md are often synced to cloud storage or version control. If you commit a secret, it’s exposed to anyone with access to that repo or folder. And once it’s in auto-memory, it’s baked into Claude Code’s training for that project.

What to do instead:

• Use placeholder names: STRIPE_API_KEY, DB_PASSWORD
• Document where to find the actual secret: “Get STRIPE_API_KEY from AWS Secrets Manager under prod/stripe/api-key”
• Use environment variables, not hardcoded values
• For local development, use .env files (add to .gitignore)

Example:

## Environment Variables

Required for local development:
- STRIPE_API_KEY: Get from AWS Secrets Manager
- DB_PASSWORD: Get from 1Password (team vault)
- GITHUB_TOKEN: Personal access token from your GitHub settings

Do NOT commit these to version control.

Personally Identifiable Information (PII)

Never write down:

• Customer names, emails, or IDs
• Employee names or contact details
• Internal IP addresses or hostnames
• Database connection strings (with credentials)
• Anything that could identify a specific person or system

Why: If Claude Code learns that your database is at db-prod-us-east-1.internal, and an engineer accidentally leaves Claude Code running on a public device, that information is exposed. Same with customer data.

What to do instead:

• Use generic examples: “The database is in AWS RDS, us-east-1”
• Use placeholder names: “User table has columns: id, name, email”
• Document schemas without real data

Example:

## Database Schema

Users table:
- id (UUID)
- name (string)
- email (string)
- created_at (timestamp)

Do NOT include real user data or internal hostnames.

Proprietary Algorithms or Trade Secrets

Never write down:

• Your secret sauce (the algorithm that makes your product unique)
• Proprietary pricing models
• Unreleased features
• Confidential business metrics

Why: Auto-memory can leak across projects if you’re not careful. If you document your secret algorithm in MEMORY.md, and an engineer later works on a side project using the same Claude Code account, that algorithm is now in auto-memory and might leak.

What to do instead:

• Document the interface, not the implementation: “The ML model takes features [X, Y, Z] and returns a score”
• Keep the actual algorithm in a separate, access-controlled repo
• If you must document it, use a private, air-gapped document (not MEMORY.md)

Example:

## ML Model

The recommendation engine uses a pre-trained model (stored in S3).
It takes user history and returns top-K recommendations.
Implementation details are in the private ml-models repo (access: team lead approval).

Internal Hostnames and Infrastructure Details

Never write down:

• Internal IP addresses
• Hostnames (e.g., api-prod.internal.company.com)
• VPC or subnet information
• Database hostnames or ports
• Any information that could be used to attack your infrastructure

Why: This is an information disclosure vulnerability. If Claude Code learns your infrastructure layout, and an attacker gains access to auto-memory or MEMORY.md, they have a map of your systems.

What to do instead:

• Use generic descriptions: “The API is deployed on AWS ECS”
• Use environment variables for hostnames: process.env.API_HOST
• Document the deployment process, not the infrastructure topology

Example:

## Deployment

Services are deployed to AWS ECS. The API endpoint is set via the API_HOST
environment variable. For local development, use localhost:3000.

Unvetted Security Practices

Never write down:

• Workarounds that bypass security controls (“We skip CSRF validation in this endpoint”)
• Known vulnerabilities you haven’t fixed
• Deprecated security practices you’re still using

Why: If Claude Code learns that you skip CSRF validation in one endpoint, it might suggest the same pattern in new code. This is a security regression.

What to do instead:

• Document the correct practice
• If you have a workaround, document it as temporary: “TEMPORARY: This endpoint skips CSRF validation due to [issue #123]. Remove after [date].”
• Track the issue and fix it

Example:

## Security

All endpoints must validate CSRF tokens. Exception: POST /webhook/stripe
(see issue #456; fix by Q2 2025).

Hyperscale or Unreleased Metrics

Never write down:

• “We process 1 million events per second” (if not public)
• “We serve 50 million users” (if not public)
• Revenue, margins, or financial metrics
• Unreleased feature timelines

Why: This is competitive information. If it leaks, it damages your business.

What to do instead:

• Use generic scale descriptions: “High-throughput system; optimise for latency”
• Link to public announcements if the metrics are public

Example:

## Scale

This is a high-throughput system. Optimise for latency (<100ms p99)
and throughput (>10k req/s). See our blog post for public metrics.

---

Governance and Hygiene Policies for 200+ Engineers

With 200 engineers, you need governance. You need policies that prevent secrets from leaking, ensure consistency, and scale memory management across teams.

Policy 1: MEMORY.md Review and Approval

Rule: Every MEMORY.md must be reviewed by a tech lead or architect before merge.

Why: MEMORY.md is the contract between humans and Claude Code. If it contains secrets, bad patterns, or outdated information, it affects all engineers on that project.

How:

• Add MEMORY.md to code review (require approval before merge)
• Use a checklist:
  • No secrets or credentials
  • No PII or internal hostnames
  • No proprietary algorithms
  • Architecture section is clear and concise
  • Setup instructions are accurate and tested
  • Patterns are documented with examples
  • Size is <50 KB

Implementation: Add this to your GitHub branch protection rules:

required_approving_review_count: 1
required_status_checks:
  - memory-md-lint

Create a GitHub Action that checks MEMORY.md for common issues:

name: MEMORY.md Lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check for secrets
        run: |
          if grep -r "STRIPE_API_KEY=" MEMORY.md; then
            echo "ERROR: Secrets found in MEMORY.md"
            exit 1
          fi
      - name: Check file size
        run: |
          SIZE=$(wc -c < MEMORY.md)
          if [ $SIZE -gt 51200 ]; then
            echo "ERROR: MEMORY.md exceeds 50 KB"
            exit 1
          fi

Policy 2: CLAUDE.md Versioning and Distribution

Rule: Maintain a canonical CLAUDE.md in a private repo or synced folder. All engineers pull the latest version.

Why: If your tech lead updates CLAUDE.md, all engineers should get the update. Without versioning, some engineers might be using stale standards.

How:

• Store CLAUDE.md in a private GitHub repo (e.g., company/standards)
• Use a setup script that symlinks or copies CLAUDE.md to ~/.claude/CLAUDE.md
• Update the script when standards change
• Add a version number to CLAUDE.md: # CLAUDE.md v2.3 (updated 2025-01-15)

Example setup script (run on onboarding):

#!/bin/bash
# setup-claude-md.sh

GIT_REPO="git@github.com:company/standards.git"
TARGET="$HOME/.claude"

mkdir -p $TARGET
cd $TARGET
git clone $GIT_REPO .
git pull origin main

echo "CLAUDE.md installed. Version:"
head -1 CLAUDE.md

Policy 3: Auto-Memory Audits

Rule: Quarterly audits of auto-memory to detect and remove stale patterns.

Why: Auto-memory learns from your code. If you refactor, the old patterns stick around. After a year, auto-memory is 30% outdated patterns, 70% current patterns.

How:

• Use Claude Code’s memory inspection tools to view what auto-memory has learned
• Compare auto-memory against MEMORY.md
• If auto-memory suggests patterns that contradict MEMORY.md, update MEMORY.md to be more explicit
• If auto-memory has learned deprecated patterns, add them to MEMORY.md’s “Deprecated Patterns” section

Quarterly audit checklist:

• Review auto-memory for 5 random projects
• Check for deprecated patterns
• Check for secrets or PII
• Compare against MEMORY.md
• Update MEMORY.md if patterns have shifted

Policy 4: Onboarding Checklist

Rule: Every new engineer must set up CLAUDE.md and read the team’s MEMORY.md files before using Claude Code.

Why: Onboarding is where most hygiene failures happen. New engineers don’t know the standards, so they train auto-memory with bad patterns.

How: Add to your onboarding checklist:

• Run setup-claude-md.sh (installs canonical CLAUDE.md)
• Read CLAUDE.md in full
• Read MEMORY.md for your assigned project
• Read the coding standards section twice
• Run the setup instructions from MEMORY.md
• Have a tech lead review your first Claude Code session

Policy 5: Incident Response for Memory Leaks

Rule: If secrets, PII, or proprietary information is discovered in MEMORY.md or auto-memory, follow this procedure.

Why: Memory leaks are security incidents. You need a process to detect, contain, and remediate.

How:

1. Detect: Code review, automated scanning, or user report
2. Contain: Remove the leaked information from MEMORY.md immediately
3. Rotate: If credentials leaked, rotate them
4. Audit: Check if the information made it into auto-memory or was synced elsewhere
5. Communicate: Notify affected engineers
6. Prevent: Update review checklist to catch this in future

Example incident: An engineer commits a database password to MEMORY.md.

1. Code review catches it before merge (good)
2. Engineer updates MEMORY.md to use placeholder
3. No rotation needed (it was caught in time)
4. Add password detection to GitHub Action

---

Implementation Roadmap

If you’re starting from scratch with 200 engineers, you can’t roll out governance overnight. Here’s a phased approach:

Phase 1: Foundation (Weeks 1–2)

Goal: Get a canonical CLAUDE.md and review process in place.

Actions:

1. Create a private company/standards GitHub repo
2. Write a canonical CLAUDE.md (5–10 KB) with your team’s global standards
3. Add version control and a setup script
4. Distribute to all engineers (email + Slack)
5. Create a GitHub Action to lint MEMORY.md for common issues

Success metric: 80% of engineers have installed CLAUDE.md

Phase 2: Rollout (Weeks 3–4)

Goal: Get MEMORY.md in place for all active projects.

Actions:

1. Identify your top 10–20 active projects
2. For each project, assign a tech lead to write MEMORY.md
3. Use a template (provided below)
4. Review and merge
5. Add MEMORY.md to code review requirements

Success metric: MEMORY.md exists for 100% of active projects

Phase 3: Enforcement (Weeks 5–6)

Goal: Make MEMORY.md and CLAUDE.md part of the development process.

Actions:

1. Add MEMORY.md review to your code review checklist
2. Require engineers to reference MEMORY.md in PR descriptions
3. Update onboarding to include CLAUDE.md setup
4. Run the first auto-memory audit

Success metric: 100% of PRs reference MEMORY.md or explain why they don’t

Phase 4: Optimization (Weeks 7+)

Goal: Refine policies based on what you’ve learned.

Actions:

1. Quarterly auto-memory audits
2. Update CLAUDE.md based on feedback
3. Update MEMORY.md as projects evolve
4. Incident response for any memory leaks
5. Measure impact (time-to-ship, code quality, security incidents)

Success metric: Consistent, zero-incident memory management

MEMORY.md Template

Use this template for all new MEMORY.md files:

# MEMORY.md – [Project Name]

## Architecture

[2–3 paragraph overview of what the system does, what it doesn't do, how data flows]

## Tech Stack

- Language: [language] [version]
- Framework: [framework] [version]
- Database: [database] [version]
- Other critical libraries: [list]

## Setup

```bash
git clone [repo]
cd [project]
[setup commands]

Coding Standards

Error Handling

[How you handle errors in this project]

Testing

[Testing conventions and coverage expectations]

Logging

[What gets logged, at what level]

Database

[ORM, raw SQL, migrations—what’s the pattern]

Critical Dependencies

[External services, integration points, quirks]

Common Gotchas

[Things that trip up new developers]

Performance Constraints

[Bottlenecks, latency SLAs, throughput expectations]

Deprecated Patterns

[Patterns to avoid, with links to correct implementations]

Size target: 10–20 KB (2,000–4,000 words)

---

## Real-World Case Studies

### Case Study 1: The Microservices Org (150 Engineers)

A Sydney-based fintech startup had 150 engineers across 12 microservices. Each team used Claude Code differently:
- Team A wrote verbose, defensive code
- Team B wrote terse, clever code
- Team C wrote boilerplate-heavy code

Auto-memory was a mess. Claude Code suggested different patterns depending on which project you started in.

**Solution**:
1. Created a canonical CLAUDE.md with global standards (TypeScript, async/await, error handling)
2. Created MEMORY.md for each microservice (architecture, setup, patterns)
3. Added MEMORY.md review to code review
4. Ran an auto-memory audit and removed deprecated patterns

**Result**: Within 4 weeks, Claude Code outputs were consistent across all teams. Time-to-ship decreased by 20% because engineers spent less time reviewing and fixing Claude Code's suggestions.

### Case Study 2: The Monolith-to-Microservices Migration (200 Engineers)

A large enterprise was migrating from a Rails monolith to microservices. They had:
- 100 engineers on the legacy monolith
- 100 engineers on the new microservices

The problem: Claude Code was learning from both codebases simultaneously. It suggested Rails patterns for Node services and vice versa.

**Solution**:
1. Created separate CLAUDE.md for monolith engineers and microservices engineers (different language preferences)
2. Created explicit MEMORY.md for both projects (architecture, patterns, deprecation notices)
3. Added a "Deprecated Patterns" section to the monolith's MEMORY.md
4. Added a "New Patterns" section to the microservices' MEMORY.md

**Result**: Engineers got context-appropriate suggestions. The monolith team didn't see Node suggestions; the microservices team didn't see Rails suggestions. Migration velocity increased by 30%.

### Case Study 3: The Security Incident (Prevented)

A security-conscious org was implementing [SOC 2 compliance via Vanta](https://padiso.co/). They were worried about Claude Code leaking secrets.

**Their approach**:
1. Created a GitHub Action that scanned MEMORY.md for API keys, passwords, and database credentials
2. Required approval from a security lead before any MEMORY.md merge
3. Documented the "What Should Never Be Written Down" section in their CLAUDE.md
4. Ran quarterly audits of auto-memory

**Result**: Zero security incidents related to Claude Code. Their auditors were impressed by the governance. The org passed SOC 2 certification on the first attempt, with Claude Code cited as a secure tool.

---

## Summary and Next Steps

Claude Code is powerful. With 200 engineers, it can accelerate your engineering velocity by 20–40% if memory is managed well. But without governance, it becomes a liability: stale context, security risks, and inconsistent outputs.

Here's what you need to do:

1. **Understand the four layers**: Session, auto-memory, project memory (MEMORY.md), and user memory (CLAUDE.md). Each serves a purpose.

2. **Write CLAUDE.md first**: Your global standards. 5–20 KB. Store it in a synced location or private repo. Update quarterly.

3. **Write MEMORY.md for every active project**: Project-specific context. 10–50 KB. Review before merge. Update as the project evolves.

4. **Never write down**: Secrets, PII, internal hostnames, proprietary algorithms, or unvetted security practices.

5. **Audit auto-memory quarterly**: Remove stale patterns. Compare against MEMORY.md. Update MEMORY.md to be more explicit.

6. **Implement governance**: Code review for MEMORY.md. Automated scanning for secrets. Incident response for leaks. Onboarding checklist.

7. **Measure impact**: Track time-to-ship, code quality, security incidents, and engineer satisfaction. Adjust policies based on what you learn.

If you're building AI-assisted engineering at scale, memory hygiene is non-negotiable. Get it right, and Claude Code becomes a force multiplier. Get it wrong, and it becomes a source of technical debt and security risk.

At PADISO, we've helped scaling engineering teams across Sydney and beyond implement these policies. We've seen teams go from 4-week feature sprints to 2-week sprints by getting memory architecture right. If you're scaling a 200-engineer org and need help implementing AI-assisted development, [PADISO's CTO as a Service and AI Strategy & Readiness offerings](https://padiso.co/) can help you get this right from day one.

Start with Phase 1 this week. You'll be surprised how much impact clear memory governance has on your team's velocity.