One file. Loaded before every conversation. That's all it takes to turn a stateless AI coding assistant into something that actually remembers how your project works. I figured this out the hard way. Three months into using Claude Code on a production codebase, I was still correcting the same mistakes every session. "No, we use pnpm, not npm." "No, the test command is make test-integration, not pytest." "No, we don't use default exports here." Every correction vanished when the session ended. make test-integration pytest Then I created a CLAUDE.md file. Forty lines of project context. The corrections stopped overnight. But CLAUDE.md is just one file in what's become an entire ecosystem. There's AGENTS.md, .cursorrules, copilot-instructions.md, CLAUDE.local.md, and now Claude's auto-memory system. Your repo can end up looking like a markdown museum for confused bots. This guide covers all of them. What each file does, where it goes, and (most importantly) which ones you actually need. The Problem: Every Tool Wants Its Own File If you use more than one AI coding assistant (and if you've read my honest tier list of AI agent frameworks, you know why you might), you've probably noticed the mess. Claude wants CLAUDE.md. Cursor wants .cursorrules (or .cursor/rules/). GitHub Copilot wants .github/copilot-instructions.md. Windsurf wants .windsurf/rules. Google's Jules wants JULES.md. The content is almost identical across all of them. Your coding standards, your build commands, your test setup, your architectural patterns. But you're copying and pasting the same instructions into five different files. This is the fragmentation problem that AGENTS.md was created to solve. More on that in a minute. First, let's understand what each file actually does. CLAUDE.md: The One That Started It All CLAUDE.md is Claude Code's memory file. Drop it in your project root, and Claude reads it at the start of every session. Think of it as a briefing document for a new team member who has amnesia. Where it lives (hierarchy matters): Where it lives (hierarchy matters): Location
Scope
Shared?




Project root (./CLAUDE.md)
This project, all team members
Yes, via git


.claude/CLAUDE.md
Same as above, tidier location
Yes, via git


~/.claude/CLAUDE.md
All your projects, personal
No


./CLAUDE.local.md
This project, just you
No (auto-gitignored)


Enterprise path (/etc/claude-code/CLAUDE.md)
All users in org
IT-managed Location
Scope
Shared?




Project root (./CLAUDE.md)
This project, all team members
Yes, via git


.claude/CLAUDE.md
Same as above, tidier location
Yes, via git


~/.claude/CLAUDE.md
All your projects, personal
No


./CLAUDE.local.md
This project, just you
No (auto-gitignored)


Enterprise path (/etc/claude-code/CLAUDE.md)
All users in org
IT-managed Location
Scope
Shared? Location
Scope
Shared? Location Scope Shared? Project root (./CLAUDE.md)
This project, all team members
Yes, via git


.claude/CLAUDE.md
Same as above, tidier location
Yes, via git


~/.claude/CLAUDE.md
All your projects, personal
No


./CLAUDE.local.md
This project, just you
No (auto-gitignored)


Enterprise path (/etc/claude-code/CLAUDE.md)
All users in org
IT-managed Project root (./CLAUDE.md)
This project, all team members
Yes, via git Project root (./CLAUDE.md) ./CLAUDE.md This project, all team members Yes, via git .claude/CLAUDE.md
Same as above, tidier location
Yes, via git .claude/CLAUDE.md .claude/CLAUDE.md Same as above, tidier location Yes, via git ~/.claude/CLAUDE.md
All your projects, personal
No ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md All your projects, personal No ./CLAUDE.local.md
This project, just you
No (auto-gitignored) ./CLAUDE.local.md ./CLAUDE.local.md This project, just you No (auto-gitignored) Enterprise path (/etc/claude-code/CLAUDE.md)
All users in org
IT-managed Enterprise path (/etc/claude-code/CLAUDE.md) /etc/claude-code/CLAUDE.md All users in org IT-managed The hierarchy loads bottom-up. Enterprise policies load first, then your personal preferences, then project-level, then subdirectory-level. More specific instructions override broader ones. What actually belongs in it: What actually belongs in it: The /init command generates a starter file based on your project structure. Here's the counterintuitive part: delete most of what it generates. The default file includes obvious things (yes, Claude, this is a TypeScript project, I can see that from the package.json). Every line in CLAUDE.md competes for attention with the actual work. (If you've ever wondered why most AI agents fail in production, bad context management is half the answer.) delete most of what it generates Target: under 300 lines. Focus on what Claude would get wrong without the file. A good CLAUDE.md has four sections: Project context. One line. "Next.js e-commerce app with Stripe integration and Postgres."Code style preferences. Not "format code properly" but "use ES modules, prefer named exports, 2-space indentation."Commands. Exact strings: pnpm test:integration, make build-docker, npm run lint:fix. Claude uses these verbatim.Architecture decisions. "API routes go in /src/api/[resource]/route.ts. We use the repository pattern for database access." Project context. One line. "Next.js e-commerce app with Stripe integration and Postgres." Project context. Code style preferences. Not "format code properly" but "use ES modules, prefer named exports, 2-space indentation." Code style preferences. Commands. Exact strings: pnpm test:integration, make build-docker, npm run lint:fix. Claude uses these verbatim. Commands. pnpm test:integration make build-docker npm run lint:fix Architecture decisions. "API routes go in /src/api/[resource]/route.ts. We use the repository pattern for database access." Architecture decisions. (Everything else? Move it to separate files and use @imports.) The @imports system: The @imports system: CLAUDE.md supports importing other files with @path/to/file syntax: @path/to/file See @README.md for project overview
See @docs/api-patterns.md for API conventions
See @package.json for available npm scripts See @README.md for project overview
See @docs/api-patterns.md for API conventions
See @package.json for available npm scripts Imports can be recursive (referenced files can reference other files, up to 5 levels deep). This solves the "one giant file" problem. Keep your CLAUDE.md lean, move detailed guidance into separate files. For teams, this is powerful. The frontend team owns docs/frontend-rules.md. The security team owns docs/security.md. CLAUDE.md just imports them all. docs/frontend-rules.md docs/security.md The honest limitation: CLAUDE.md is Claude-only. If your team uses Cursor or Copilot alongside Claude Code, they won't read this file. That's where AGENTS.md comes in. The honest limitation: AGENTS.md: The Universal Standard AGENTS.md emerged in mid-2025 from a collaboration between Sourcegraph, OpenAI, Google, Cursor, and others. It's now maintained by the Agentic AI Foundation under the Linux Foundation. The pitch is simple: one file, any agent. It's supported by Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp, RooCode, and a growing list of others. a growing list of others How it works: How it works: Drop an AGENTS.md in your project root. It's standard Markdown, no special schema, no YAML frontmatter required. The closest AGENTS.md to the file being edited takes precedence, and explicit user prompts override everything. # AGENTS.md

## Project Overview
E-commerce platform built with Next.js 14, Postgres, and Stripe.

## Build & Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint:fix`

## Code Standards
- Use TypeScript strict mode
- Prefer named exports over default exports
- API routes follow REST conventions in /src/api/

## Testing Requirements
- All PRs must include tests
- Use vitest for unit tests, playwright for e2e # AGENTS.md

## Project Overview
E-commerce platform built with Next.js 14, Postgres, and Stripe.

## Build & Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint:fix`

## Code Standards
- Use TypeScript strict mode
- Prefer named exports over default exports
- API routes follow REST conventions in /src/api/

## Testing Requirements
- All PRs must include tests
- Use vitest for unit tests, playwright for e2e AGENTS.md vs CLAUDE.md vs README: AGENTS.md vs CLAUDE.md vs README: File
For
Purpose




README.md
Humans
Quick start, project description, contributing guide


AGENTS.md
All AI agents
Build steps, test commands, code conventions


CLAUDE.md
Claude specifically
Claude-specific behaviors, preferences, @imports File
For
Purpose




README.md
Humans
Quick start, project description, contributing guide


AGENTS.md
All AI agents
Build steps, test commands, code conventions


CLAUDE.md
Claude specifically
Claude-specific behaviors, preferences, @imports File
For
Purpose File
For
Purpose File For Purpose README.md
Humans
Quick start, project description, contributing guide


AGENTS.md
All AI agents
Build steps, test commands, code conventions


CLAUDE.md
Claude specifically
Claude-specific behaviors, preferences, @imports README.md
Humans
Quick start, project description, contributing guide README.md Humans Quick start, project description, contributing guide AGENTS.md
All AI agents
Build steps, test commands, code conventions AGENTS.md All AI agents Build steps, test commands, code conventions CLAUDE.md
Claude specifically
Claude-specific behaviors, preferences, @imports CLAUDE.md Claude specifically Claude-specific behaviors, preferences, @imports They're complementary, not competing. README is for humans, AGENTS.md is the universal agent brief, CLAUDE.md adds Claude-specific instructions on top. My recommendation: If you use multiple AI tools, put your shared instructions in AGENTS.md and keep CLAUDE.md for Claude-specific features like @imports and the /init workflow. If you only use Claude Code, CLAUDE.md alone is fine. My recommendation: The Other Memory Files (Quick Reference) Not every tool has adopted AGENTS.md yet, and some have features that go beyond what AGENTS.md covers. .cursorrules / .cursor/rules/*.mdc: Cursor's native format. The newer .mdc format supports YAML frontmatter with activation modes (Always, Auto Attached, Agent Requested, Manual). More granular than AGENTS.md, but Cursor-only. Cursor also reads AGENTS.md, so you can use both. Put shared rules in AGENTS.md, Cursor-specific behaviors in .cursor/rules/. .cursorrules / .cursor/rules/*.mdc: .mdc .github/copilot-instructions.md: GitHub Copilot's instruction file. Lives in the .github folder. Copilot also reads AGENTS.md now, so you may not need both. .github/copilot-instructions.md: .windsurfrules: Windsurf's format. Dual structure with global_rules.md for workspace-wide instructions. Windsurf supports AGENTS.md too. .windsurfrules: CLAUDE.local.md: Your personal, project-specific preferences that don't get committed to git. Auto-added to .gitignore. Use it for things like your sandbox URLs, preferred test data, or personal workflow quirks. (Your teammates don't need to know you always test with the username "butts123".) CLAUDE.local.md: Claude's Auto-Memory: The AI That Takes Its Own Notes This is the newest addition and the most interesting one. Claude Code now has an auto-memory system where Claude writes notes to itself during your sessions. It lives in ~/.claude/projects/<project>/memory/: ~/.claude/projects/<project>/memory/ memory/
├── MEMORY.md          # Index file, loaded every session
├── debugging.md       # Notes on debugging patterns
├── api-conventions.md # API design decisions
└── ... memory/
├── MEMORY.md          # Index file, loaded every session
├── debugging.md       # Notes on debugging patterns
├── api-conventions.md # API design decisions
└── ... The key difference from CLAUDE.md: you write CLAUDE.md, Claude writes MEMORY.md. You provide the instructions. Claude captures the learnings. you write CLAUDE.md, Claude writes MEMORY.md Only the first 200 lines of MEMORY.md load automatically. Topic files (debugging.md, etc.) load on-demand when Claude needs them. The practical workflow: The practical workflow: When Claude discovers something about your project ("oh, this codebase uses a custom ORM wrapper"), it saves that to auto-memory. Next session, it already knows. No more repeating yourself. You can trigger this manually too. At the end of a productive session, ask Claude: "Update your memory files with what you learned about our codebase today." The learnings persist. To review or edit what Claude has saved, run /memory during any session. /memory The honest limitation: Auto-memory is still rolling out. If you don't see it, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 in your environment. And because Claude writes these notes, quality varies. Review them periodically, just like you'd review any documentation. The honest limitation: CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 The /init Then Delete Workflow This is the fastest way to bootstrap a memory file for any new project. Run /init in your project directoryClaude generates a starter CLAUDE.md based on your project structure and detected tech stackDelete what you don't need Run /init in your project directory /init Claude generates a starter CLAUDE.md based on your project structure and detected tech stack Delete what you don't need Delete what you don't need Step 3 is where most people go wrong. The generated file is a starting point, not a finished product. It often includes filler that doesn't add value. ("This project uses JavaScript." Thanks, Claude. I can see the package.json.) The delete-first approach is faster than writing from scratch. You're editing down from a reasonable draft instead of staring at a blank file. After the initial setup, build your memory file organically. When Claude makes a wrong assumption (in my case, it kept importing from a deprecated internal package), don't just correct it once. Tell Claude: "add to my CLAUDE.md: always import from @company/utils-v2, not @company/utils." The instruction persists for future sessions. Every few weeks, ask Claude to review and optimize your CLAUDE.md. Instructions accumulate, some become redundant, others conflict. A quick cleanup keeps things sharp. What I Actually Use (My Setup) After experimenting with all of these on projects ranging from a document Q&A system to an internal agent that kept hallucinating company policy, here's what I settled on: AGENTS.md in project root with shared instructions (build commands, code standards, testing requirements). This covers any AI tool my team uses. AGENTS.md CLAUDE.md with @imports for Claude-specific behaviors. Stays lean, under 100 lines, mostly pointing to docs/ files. CLAUDE.md CLAUDE.local.md for my personal quirks (my preferred test data, sandbox URLs, shortcut commands I use constantly). CLAUDE.local.md Auto-memory enabled. I let Claude take its own notes and review them monthly. Auto-memory Everything else (.cursorrules, copilot-instructions.md) I've replaced with symlinks to AGENTS.md. One source of truth. # Symlink setup for multi-tool consistency
ln -sfn AGENTS.md .github/copilot-instructions.md
mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc # Symlink setup for multi-tool consistency
ln -sfn AGENTS.md .github/copilot-instructions.md
mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc (Is this elegant? No. Does it prevent instruction drift across tools? Yes.) Quick Decision Guide Situation
What to Use




Only use Claude Code
CLAUDE.md is all you need


Multiple AI tools, solo dev
AGENTS.md + CLAUDE.local.md


Team with mixed tools
AGENTS.md (shared) + CLAUDE.local.md (personal)


Enterprise/compliance needs
Enterprise CLAUDE.md + AGENTS.md + project CLAUDE.md Situation
What to Use




Only use Claude Code
CLAUDE.md is all you need


Multiple AI tools, solo dev
AGENTS.md + CLAUDE.local.md


Team with mixed tools
AGENTS.md (shared) + CLAUDE.local.md (personal)


Enterprise/compliance needs
Enterprise CLAUDE.md + AGENTS.md + project CLAUDE.md Situation
What to Use Situation
What to Use Situation What to Use Only use Claude Code
CLAUDE.md is all you need


Multiple AI tools, solo dev
AGENTS.md + CLAUDE.local.md


Team with mixed tools
AGENTS.md (shared) + CLAUDE.local.md (personal)


Enterprise/compliance needs
Enterprise CLAUDE.md + AGENTS.md + project CLAUDE.md Only use Claude Code
CLAUDE.md is all you need Only use Claude Code CLAUDE.md is all you need Multiple AI tools, solo dev
AGENTS.md + CLAUDE.local.md Multiple AI tools, solo dev AGENTS.md + CLAUDE.local.md Team with mixed tools
AGENTS.md (shared) + CLAUDE.local.md (personal) Team with mixed tools AGENTS.md (shared) + CLAUDE.local.md (personal) Enterprise/compliance needs
Enterprise CLAUDE.md + AGENTS.md + project CLAUDE.md Enterprise/compliance needs Enterprise CLAUDE.md + AGENTS.md + project CLAUDE.md The Convergence is Happening Six months ago, you needed five different files for five different tools. Today, most tools read AGENTS.md. The fragmentation problem isn't solved, but it's getting better. My bet: AGENTS.md becomes the standard the way README.md did. Not because it's technically superior, but because the Linux Foundation backing and broad tool support create enough gravity to pull the ecosystem together. CLAUDE.md, .cursorrules, and the rest will stick around for tool-specific features, but the shared context will live in one place. Until then, the symlink hack works fine. And honestly, having a memory file at all puts you ahead of most developers. I wrote an entire guide to building AI agents with LangGraph, and the number one issue people hit wasn't the framework. It was Claude forgetting their project setup between sessions. The gap between "Claude, we use pnpm" every session and "Claude already knows" is the difference between a tool and a teammate.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Target

Google

Keep

The Complete Guide to AI Agent Memory Files (CLAUDE.md, AGENTS.md, and Beyond)

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

5 AI Agent Workflows for Repeatable Success (Code Included)

What is AGENTS.md?

Developers Test Rulebook-AI as a Common Rule Set for Copilot, Cursor, and More

MCP Is Here to Save Developers From the AI Agent Glue-Code Nightmare

The Future Is Agents Orchestrating Agents Orchestrating Agents

How AI Agents Helped Migrate a Data Lake From Snowflake to BigQuery

5 AI Agent Workflows for Repeatable Success (Code Included)

What is AGENTS.md?

Developers Test Rulebook-AI as a Common Rule Set for Copilot, Cursor, and More

MCP Is Here to Save Developers From the AI Agent Glue-Code Nightmare

The Future Is Agents Orchestrating Agents Orchestrating Agents

How AI Agents Helped Migrate a Data Lake From Snowflake to BigQuery

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps