Skip to content

Memory and Project Rules

An AI assistant starts every session knowing nothing about your project. It doesn't remember yesterday's decisions, your test command, your house style, or the one module that breaks if you touch it wrong. If that knowledge lives only in a conversation, it dies when the conversation ends — and you re-explain it forever.

The fix is persistent project memory: durable files, committed to the repo, that the agent loads automatically. This is the single most effective way to make an AI tool feel like it knows your codebase.

Why this matters — Limitation #2 (No real thinking / no persistent learning). Humans accumulate knowledge: you learn a codebase's quirks once and carry them for years, compounding. A model doesn't — it resets every session. Project memory is the workaround. It externalizes the lessons the model can't retain, so each session starts informed instead of blank. And because that memory shares the context window, how you structure it is itself a context-management problem (Limitation #1).

Two different "memories." This page is about assistant memory — files that make your coding tool remember your project between sessions. That's a separate problem from giving an end-user-facing product a memory of past interactions, which is a build-side pattern covered in Persistent Memory for an LLM App. Same word, different problem.

Don't rely on conversation history

Conversation history is the worst place to keep important rules. It's invisible to teammates, it vanishes when the session ends, and it gets buried as the context fills. If something matters every time — your test command, a coding convention, an architectural boundary — it belongs in a memory file, not in a chat message you'll have to repeat.

The memory files: CLAUDE.md, AGENTS.md, and repo rules

Most AI coding tools look for a conventional memory file at the repo root and load it automatically at the start of every session:

  • CLAUDE.md — the file Claude Code reads automatically.
  • AGENTS.md — an emerging cross-tool convention other agents read.
  • Other tools have their own equivalents (rules files, config directories).

The content matters more than the filename. A common and tidy approach is to keep one canonical file and have the tool-specific one simply point to it — for example, a CLAUDE.md whose entire contents are @AGENTS.md, so there's one source of truth and no drift between tools.

The key pattern: a thin root that points to focused files

Here's the pattern worth adopting deliberately, because it solves a real tension.

You want the agent to know a lot about your project. But if you cram everything — backend conventions, frontend stack, styling rules, deploy steps — into one giant memory file, that whole file loads into context every session, even when you're only touching one corner. That's exactly the context bloat Limitation #1 warns against: the model pays attention tax on backend rules while fixing a CSS bug.

The solution is a layered, pointer-based structure:

CLAUDE.md            → just points to AGENTS.md
AGENTS.md            → project overview + shared commands; points to focused files
agents/
  ├── BACKEND.md     → backend architecture & conventions
  ├── FRONTEND.md    → frontend stack & patterns
  └── UI_STYLES.md   → the styling contract

The root file is thin. The overview is shared and small. The heavy, domain-specific detail lives in focused files the agent loads only when the task calls for it. Working on the API? It pulls in the backend file. Touching a component? It reads the frontend and styling files. The context stays lean and relevant instead of carrying everything, all the time.

This is the direct, practical mitigation of limited memory: load only what this task needs.

Supporting example: AuditAgent

AuditAgent (an AI smart-contract auditing platform) uses exactly this structure:

  • CLAUDE.md is literally one line — @AGENTS.md — so Claude Code and any AGENTS.md-aware tool read the same source of truth.
  • AGENTS.md holds the project overview (a FastAPI backend with isolated scan pods, a Next.js frontend, a Docusaurus docs site), the common commands (how to start the dev server, the exact pytest invocation that excludes the slow property-based tests, lint commands), code style, testing strategy, and branching rules — then links out to the focused files.
  • agents/ holds the domain detail: BACKEND.md (the api/ vs core/ layout, scan phases, conventions), FRONTEND.md (Next.js 16 / React 19 stack, app-owned UI primitives, state libraries), and UI_STYLES.md (the OKLCH design-token contract — "never hardcode a color, use a primitive").
  • A separate design_decisions/ folder captures the why behind big choices, in files like AUTH.md, PERSISTENT_MEMORY.md, REPO_INDEXER.md, AUDIT_SCORE_ALGORITHM.md, and LLM_TOOLS_LOOP.md.

The point is general: a thin root, a shared overview, and focused files loaded on demand. AuditAgent is just one place it's working.

What to store

Good project memory is the stuff you'd otherwise explain to a new hire on day one:

  • Test, lint, build, and type-check commands — the exact invocations, including any non-obvious flags (e.g. "always exclude the slow test suite," "run through the project virtualenv, never system Python").
  • Important modules and where things live — a map so the agent points instead of scans (ties straight to Context Management).
  • Coding and comment style — formatting rules, naming, when to comment, patterns to prefer.
  • Architecture boundaries — what may depend on what, layers that must not be crossed, "services must work both standalone and in the pipeline."
  • Deploy checks — what must pass before shipping, how releases flow (e.g. feature branch → staging → main).
  • Known failure modes — the traps. "This service has two execution contexts." "Don't hardcode colors." "Reuse the existing helper before writing a new one."

If you find yourself explaining the same thing twice, that's the signal: write it into memory.

Team-shared memory vs. personal working memory

There are two kinds of memory, and they live in different places:

Team-shared memory Personal / working memory
What Conventions, commands, architecture, rules everyone must follow Your scratch notes, in-progress task context, personal reminders
Where Committed to the repo (CLAUDE.md, AGENTS.md, agents/) Git-ignored local files, or a personal memory file
Audience The whole team and every agent session Just you
Reviewed? Yes — it's part of the codebase No

Keep them separate. Team rules belong in version control where everyone (and every agent) benefits and changes are reviewed. Half-finished task notes and personal preferences should stay out of the shared files, ignored by git, so they don't impose your scratch work on teammates.

Review AI-generated memory edits before committing

Agents can update their own memory files — and they should, when they learn a durable lesson. But treat a memory edit like any other code change: review it before committing.

Memory is high-leverage in both directions. A good rule, committed, helps every future session. A wrong, stale, or overly broad rule misleads every future session — and it's worse than a code bug because it silently shapes everything the agent does afterward. Watch for memory that's too verbose (context bloat), too vague to act on, or simply incorrect. The bar for committed memory is high precisely because everyone inherits it.

Tooling helps here. The claude-md-management plugin can audit and improve your memory files — flagging bloat, gaps, and staleness, and proposing focused updates. It ships skills like claude-md-improver (audit a repo's CLAUDE.md files against a quality bar and apply targeted fixes) and revise-claude-md (fold the durable lessons from the current session back into memory). See Skills and Plugins.

Quick checklist

  • Durable rules live in committed memory files, not conversation history
  • A thin root (CLAUDE.md / AGENTS.md) points to focused, on-demand files
  • Memory covers commands, module map, style, boundaries, deploy checks, failure modes
  • Team-shared memory is committed and reviewed; personal working memory is git-ignored
  • AI-generated memory edits are reviewed before they're committed

Sources