Mastering Project Memory with CLAUDE.md

AI agents suffer from context drift. Whether you use Claude Code, Aider, or AZMX AI, the agent eventually forgets your specific naming conventions or the exact way you handle error boundaries. A project memory file—commonly known as CLAUDE.md or AZMX.md—serves as a persistent, version-controlled source of truth that anchors the agent to your project's unique constraints.

The Problem with Ephemeral Context

Most AI coding tools rely on the current chat history and a RAG-based search of your codebase. While effective for finding functions, this approach fails to communicate intent. An LLM can see that you use Zod for validation, but it cannot know that you strictly forbid the use of any types in your API layer unless told explicitly.

Project memory files solve this by providing a high-density instruction set that is injected into the system prompt or read during the initial project indexing. This reduces token waste and prevents the agent from suggesting patterns that contradict your established architecture.

Core CLAUDE.md Best Practices

1. Define the Tech Stack Explicitly

Do not assume the agent knows your versions. Specify the exact runtime and primary libraries. This prevents the agent from suggesting deprecated APIs or features from a newer version you haven't upgraded to yet.

# Tech Stack
- Runtime: Node.js v22.x (LTS)
- Framework: Next.js 15 (App Router)
- State Management: Zustand
- Database: PostgreSQL via Prisma

2. Establish Coding Standards

Focus on the non-obvious. If you follow standard PEP 8 or Airbnb style guides, just mention them. Spend your space on project-specific quirks, such as how you handle asynchronous errors or where you store utility functions.

• Naming: Use kebab-case for files, PascalCase for components.
• Patterns: Prefer functional components over classes.
• Testing: Write Vitest tests in __tests__ directories adjacent to the source.

3. Map the Architecture

Agents often struggle with deep directory nesting. Provide a high-level map of where critical logic resides. This guides the agent to look in /src/lib/core before attempting to create a duplicate utility in /src/utils.

4. Maintain a "Recent Changes" Log

The most effective project memory files are living documents. When you make a significant architectural pivot—such as switching from REST to GraphQL—update the memory file immediately. This prevents the agent from hallucinating the old API structure based on stale files in the codebase.

Integrating Memory with Agent Tooling

Different tools handle project memory differently. Aider and Claude Code look for specific markers or files in the root directory. AZMX AI utilizes AZMX.md to provide a similar grounding mechanism, ensuring that sub-agents maintain consistency across complex tasks.

When using an agent with a real PTY terminal, like AZMX AI, the memory file acts as the guardrail for shell commands. If your AZMX.md specifies that the project uses pnpm instead of npm, the agent is less likely to trigger the wrong package manager during a dependency install.

Comparison of Memory Approaches

Comparing project memory to other context methods reveals why a dedicated file is superior for long-term maintenance:

• System Prompts: Too static. Updating a system prompt across a team is difficult. A CLAUDE.md file is committed to Git and evolves with the code.
• Custom Instructions: Often global. You don't want your React preferences applied to a Python data science project.
• RAG (Retrieval Augmented Generation): Probabilistic. RAG might find a relevant file, but it won't necessarily prioritize the rule over a legacy example found in the code.

Avoiding Common Pitfalls

To keep your project memory efficient, avoid these mistakes:

• Too much detail: Do not list every single function. If it is in the code, the agent can find it. Use the memory file for rules, not documentation.
• Contradictions: Ensure your memory file matches your eslintrc or prettierrc. If the memory file says "use semicolons" but the linter removes them, the agent will enter a loop of endless corrections.
• Ignoring the Deny-list: Never put secrets or environment variables in your memory file. Use a .env.example for structure and keep the actual keys in a secure vault. AZMX AI enforces this by default via a deny-list that refuses to read .env or .ssh directories.

Implementation Checklist

Start your project memory file with these sections:

1. Project Goal: One sentence on what the app actually does.
2. Core Tech: Versions and primary libraries.
3. Critical Paths: Where the most important logic lives.
4. Style Guide: Non-negotiable coding patterns.
5. Command Reference: The exact commands for build, test, and lint.

By implementing these best practices, you move from fighting the AI to collaborating with it. The goal is to reduce the cognitive load on the agent, which directly translates to higher quality code and fewer regression bugs.