Architecture decision

Agent Memory vs AGENTS.md

Should information be remembered dynamically or committed as shared project guidance?

Get the short answerReview evidence

The short answer

Commit stable team truth to AGENTS.md. Use memory for revisable, user- or project-specific learnings that should persist but do not belong in the repository contract.

Choose

Memory and context

The systems that decide what an agent sees now, what it can retrieve later, and which durable facts persist across sessions.

  • The information is a learned preference, debugging observation, or evolving project note.
  • Users need to inspect, edit, expire, or delete it independently.
  • Loading it selectively is better than adding it to every session.
Open the Memory and context guide

Choose

Repository instructions

Durable, version-controlled guidance that tells coding agents how a repository is organized, how to verify work, and which boundaries matter.

  • The whole team should review and version the guidance.
  • The instruction defines repository architecture, commands, or completion rules.
  • A fresh environment should receive it from source control.
Open the Repository instructions guide
Use both

How the layers combine

  1. 01

    Use memory to collect repeated observations.

  2. 02

    Promote a verified, durable pattern into AGENTS.md through normal code review.

  3. 03

    Remove stale memory after the shared instruction becomes authoritative.

Decision review

Questions to answer before implementation

  • Who owns the information and who should see it?
  • Is the item stable enough for source control?
  • Does it contain sensitive data or secrets?
  • Can stale or conflicting versions be corrected?
  • Does the startup context remain concise?

Evidence ledger

Primary documentation for both sides

Reviewed July 26, 2026. Use the provider documentation for current configuration and security behavior.

Codex memories

OpenAI

Codex memory behavior, inspection, and user control.

How Claude remembers your project

Anthropic

CLAUDE.md locations, loading behavior, concise instruction guidance, and AGENTS.md interoperability.

Effective context engineering for AI agents

Anthropic

Context selection, compaction, structured notes, and long-horizon agent patterns.

AGENTS.md specification and examples

AGENTS.md

The portable AGENTS.md format and repository instruction pattern.

Codex AGENTS.md guidance

OpenAI

Codex discovery, precedence, scope, and maintenance guidance.