Skip to main content
The Agent Context System adds a small, deliberate set of files to your repository. Some are committed and shared across your team. Others are gitignored and personal. Understanding what each file does — and who reads it, when — helps you get the most out of the system from day one.

​
Repository layout

your-repo/
├── AGENTS.md                    # Committed. Always loaded. Under 120 lines.
├── .agents.local.md             # Gitignored. Personal scratchpad.
├── agent-context                # CLI: init, validate, promote commands.
├── agent_docs/                  # Deeper docs. Read only when needed.
│   ├── conventions.md
│   ├── architecture.md
│   └── gotchas.md
├── scripts/
│   └── init-agent-context.sh    # Wrapper for npx skills installs
└── CLAUDE.md                    # Symlink → AGENTS.md (created by init)

​
Memory system layout

The .agents/ directory holds the structured memory system used for session logging and auto-consolidation: 
.agents/
├── local.md                    # Index (200 lines max, ~25KB cap)
├── logs/
│   ├── 2026-03-25.md           # Daily log (append-only)
│   └── 2026-03-26.md           # Daily log (append-only)
└── topics/
    ├── patterns.md             # Curated patterns
    ├── gotchas.md              # Curated gotchas
    └── preferences.md          # Curated preferences

​
Key files explained

AGENTS.md is the most important file in the system. It is committed to version control, shared across your whole team, and loaded into the agent’s prompt at the start of every session.What it contains:
  • Project name, stack, and package manager
  • Build, test, lint, and dev server commands
  • One-line architecture overview (one line per directory)
  • Compressed project knowledge: patterns, boundaries, and gotchas in pipe-delimited shorthand
  • Numbered rules the agent follows on every turn
  • Pointers to agent_docs/ for deeper references
Who creates it: You create it manually during setup and edit it as your project evolves. Run ./agent-context init to get the template.What the agent does with it: Reads it at the start of every session, before doing any work. Every rule, pattern, and gotcha in this file is applied on every turn — no lookup required.The 120-line limit: Frontier LLMs reliably follow about 150-200 instructions. Claude Code’s system prompt uses ~50. That leaves ~120 for your project context. Going over doesn’t give you more coverage — it gives you instructions that get quietly deprioritized. Keep this file under 120 lines.
Cursor, Copilot, Codex, and Windsurf all read AGENTS.md directly. Claude Code reads CLAUDE.md, which the init script creates as a symlink to AGENTS.md — so you maintain one source of truth for all agents.
.agents.local.md is your private, gitignored scratchpad. It never gets committed to version control and is local to you — not shared with your team.What it contains:
  • Your personal preferences (tone, code style, planning style)
  • Settled patterns specific to how you work
  • Gotchas the agent has hit in past sessions
  • Dead ends — approaches tried and failed, with reasons
  • A “Ready to Promote” section where the agent flags stable patterns
  • A session log, with one entry per session appended at the end
Who creates it: The init script creates it from the template at scripts/agents-local-template.md. You customize the preferences section once, then the agent maintains the rest.What the agent does with it: Reads it at session start alongside AGENTS.md. Appends a session log entry at the end of each session (with your approval). Compresses it when it hits 300 lines and flags patterns that have recurred across 3+ sessions in the “Ready to Promote” section.
The agent must show you the proposed session log entry before writing it. It does not append directly without your approval.
agent_docs/ holds deeper reference material that the agent reads only when the task requires it. This keeps the always-loaded context in AGENTS.md lean and focused on what matters every session.What it contains:
FileContents
conventions.mdFull code patterns, naming conventions, file structure decisions
architecture.mdSystem design, data flow, key architectural decisions
gotchas.mdExtended known traps with full explanations and context
Who creates it: You fill these in after setup. Delete files that don’t apply to your project.What the agent does with it: References these files only when AGENTS.md’s compressed knowledge isn’t enough for the task at hand. For most day-to-day tasks, the agent never needs to open agent_docs/.
Think of agent_docs/ as the full manual. AGENTS.md is the cheat sheet. The cheat sheet covers 90% of sessions. The manual covers the rest.
The .agents/ directory is the memory system’s home. It is gitignored and local to you.local.md — the indexThe index is capped at 200 lines (~25KB). It doesn’t store content directly — it stores pointers to topic files, with a one-line summary for each entry (~150 chars max). The agent reads this at session start to know what memory topics exist and where to find them.logs/ — daily append-only logsEach day gets its own file (e.g., 2026-03-25.md). The agent appends session entries here. These files are never edited — only appended to. During auto-consolidation, entries from daily logs are promoted to topic files and the logs are pruned.topics/ — curated knowledgeTopic files (patterns.md, gotchas.md, preferences.md) are de-duplicated, dated, and merged during consolidation. Unlike daily logs, topic files are curated — they represent settled, reviewed knowledge. Auto-consolidation runs when ≥24 hours have passed since the last consolidation and ≥5 sessions have accumulated.Who creates it: The init script creates the directory. The agent creates and maintains the files inside it.What the agent does with it: Reads local.md (the index) and relevant topic files at session start. Appends to today’s daily log at session end. Triggers consolidation when the conditions are met.
Auto-consolidation achieves roughly a 9:1 compression ratio (107 KB → 11.6 KB validated). This keeps the memory system from growing unbounded while preserving what matters.

​
Other files

agent-context is the CLI. Use it to initialize the system, validate AGENTS.md, and promote flagged patterns. Run ./agent-context init to set up a new project, ./agent-context validate to check file health, and ./agent-context promote to review patterns flagged for promotion. scripts/init-agent-context.sh is a thin wrapper around agent-context init for backwards compatibility with npx skills add installs. If you installed via npx skills, use this script instead of the CLI directly. CLAUDE.md is a symlink to AGENTS.md, created by the init script. Claude Code reads CLAUDE.md rather than AGENTS.md directly. The symlink means you maintain one file — AGENTS.md — and all agents read it, regardless of what filename they expect.