Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Memory

9.2. Work Conventions

The “conventions” part of MEMORY.md

This is one of the four main content types that belong in MEMORY.md: project conventions such as coding style, directory structure, and CI/CD tools, alongside environment facts, discovered workarounds, and lessons learned.

Good example content — concrete and immediately actionable

Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI goes through GitHub Actions.
Project uses tabs, 120-character line limit, Google-style docstrings.

Compare that with a bad example that is too vague to be useful: “User has a project.” That gives no value in a future session.

How this differs from AGENTS.md (section 7.2)

This is an easy point to confuse, so it needs to be explicit. AGENTS.md is a file written in advance by the user or team, located inside the repo itself, and loaded based on working-directory context. MEMORY.md work conventions are learned and written by the agent itself through actual work. They are not in the repo and are not committed. They complement AGENTS.md rather than replacing it, and the rule is to avoid repeating content that is already present in context files so you do not waste tokens on duplication.

Practical lessons

  • When you correct the agent about a convention, such as “Do not deploy directly to Vercel for this project, it must go through GitHub,” that is exactly the kind of content that should go into MEMORY.md as a correction. The agent can then apply it from the next session onward without being reminded again.
  • For conventions tied to one specific project rather than everything you do, always include the project name or path in the entry. Otherwise MEMORY.md turns into a pile of mixed rules with no clear scope.
  • If a process has more steps than a one-line note can hold, not just “use X” but an actual sequence of commands, conditions, and checks, that is a sign it should be promoted into a skill (sections 10.3/20.3) rather than crammed into MEMORY.md. Memory is for condensed facts. Skills are for procedures.