Skip to content

File-Based Memory Patterns

Markdown files in your repo give agents project-specific knowledge that survives across sessions.

Cross-Tool Convention

AGENTS.md has emerged as the cross-runtime standard:

Runtime Primary File AGENTS.md Support
Claude Code CLAUDE.md Yes, reads both
Cursor .cursorrules Migrating to AGENTS.md
Windsurf .windsurfrules Yes
Opencode AGENTS.md Native
Cline .clinerules Yes

For portability, create AGENTS.md and symlink tool-specific filenames:

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .cursorrules

Memory Hierarchy

Memory files stack from general to specific. Agents merge them when working in nested directories.

project/
├── AGENTS.md                    # Project-wide conventions
├── packages/
│   ├── api/
│   │   ├── AGENTS.md            # API-specific context
│   │   └── src/
│   │       └── auth/
│   │           └── AGENTS.md    # Auth module context
│   └── web/
│       └── AGENTS.md            # Frontend context

When working in packages/api/src/auth/, the agent loads all three levels. More specific files can override or extend general rules.

Enterprise Policy Layer

Large organizations add another layer above user preferences:

~/.claude/
├── enterprise/CLAUDE.md   # Organization-wide (managed)
└── CLAUDE.md              # Personal preferences

Enterprise policy files are often managed through MDM and not user-editable.

Local Overrides

For personal preferences that shouldn't be committed:

project/
├── AGENTS.md           # Committed, team-shared
└── AGENTS.local.md     # Gitignored, personal

Add *.local.md to .gitignore.

Lazy Loading

For large documentation, reference rather than embed:

## Style Guide

When modifying Python code, consult `docs/python-style.md` for detailed conventions.

The agent loads the referenced file only when relevant.

Some runtimes support explicit imports:

@import docs/api-conventions.md
@import docs/testing-guide.md

Check your runtime's documentation for supported syntax.

Path-Specific Rules

Some runtimes apply rules based on working directory:

## Path-Specific Rules

When in `packages/api/`:
- Use FastAPI conventions
- All routes need OpenAPI documentation

When in `packages/web/`:
- Follow React hooks conventions
- Components in PascalCase

What to Include

For guidance on what belongs in memory files, see Agent Rules. Key points: include navigation hints, domain vocabulary, command syntax, and non-obvious constraints. Skip generic best practices, personality instructions, and anything linters can enforce.