> ## Documentation Index > Fetch the complete documentation index at: https://mainbranch.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Agent Context System: Files and Directory Reference > A reference to every file and directory in the Agent Context System — what each one contains, who creates it, and what your agent does with it. 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:** | File | Contents | | ----------------- | ---------------------------------------------------------------- | | `conventions.md` | Full code patterns, naming conventions, file structure decisions | | `architecture.md` | System design, data flow, key architectural decisions | | `gotchas.md` | Extended 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 index** The 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 logs** Each 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 knowledge** Topic 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.