{"slug": "ai-agent-memory-starts-with-a-documentation-table-of-contents", "title": "AI Agent Memory Starts with a Documentation Table of Contents", "summary": "A developer proposes that AI agent memory should be structured like a book's table of contents, using hierarchical directories and README indexes to help agents quickly find relevant documents. The approach organizes documentation by role (spec, architecture, test) and allows single files to be promoted into directories as subjects grow, enabling agents to ignore irrelevant content without reading entire files.", "body_md": "Good project memory for AI agents is not a larger pile of documents. It is a **hierarchical table of contents** that helps an agent reach the right document quickly and ignore irrelevant ones. Directories identify document roles and parent topics, filenames name individual entries, and each `README.md`\n\nroutes the agent to the next level. When a subject grows, a single file can be promoted into a directory with its own README and supporting documents. Paths, filenames, README indexes, and headings can therefore work like a book, letting an agent find the relevant specs, architecture, tests, and plans without reading the entire project.\n\nWhen documents are mixed in one directory or stored under names such as `NOTES.md`\n\nand `FINAL.md`\n\n, an agent cannot tell which file contains the current spec, architecture, or test strategy without opening it. When the path exposes the role, as in `docs/spec/CLI_INTERFACE.md`\n\n, `docs/arch/CLI_ARCHITECTURE.md`\n\n, and `docs/test/CLI_INTERFACE.md`\n\n, the table of contents distinguishes the spec, architecture, and tests before any body is loaded.\n\nGood project memory does not expose everything all the time. Paths and indexes help an agent find what the current task needs and exclude documents with different roles before reading them.\n\nWe rarely read a book from the first page to the last when looking for one answer. We inspect the table of contents and move to the relevant part and chapter. Project documentation can follow the same model.\n\n```\ndocs/\n├── README.md                         # Table of contents for the whole book\n├── concept/                          # Part 1: Core concepts\n│   ├── README.md                     # Part 1 index\n│   └── CONTEXT_CURATION.md           # Chapter: Context curation\n├── spec/                             # Part 2: Product behavior\n│   ├── README.md                     # Part 2 index\n│   ├── PROJECT_INITIALIZER.md        # Chapter 1: Project initialization\n│   └── cli/                          # Chapter 2: CLI\n│       ├── README.md                 # Chapter 2 index\n│       └── CONFIG_COMMAND.md         # Chapter 2, section 1: config command\n├── arch/                             # Part 3: Architecture and constraints\n│   ├── README.md                     # Part 3 index\n│   └── DOCS_STRUCTURE.md             # Chapter: Documentation structure\n└── test/                             # Part 4: Tests\n    ├── README.md                     # Part 4 index\n    └── CLI_INTERFACE.md              # Chapter: CLI regression tests\n```\n\nRead this structure as a route through nested indexes. `spec/`\n\nis the top-level index for product specs, and `PROJECT_INITIALIZER.md`\n\nis one entry beneath it. When the CLI subject grows, `cli/`\n\nbecomes a new child index and `cli/README.md`\n\nroutes readers within it. `CONFIG_COMMAND.md`\n\nis one entry in that child index. In book terms, these correspond to Part 2, Part 2 Chapter 1, Part 2 Chapter 2, and Part 2 Chapter 2 Section 1.\n\n| Full path | Role in the table of contents | Book notation |\n|---|---|---|\n`docs/README.md` |\nTop-level index for the whole book | Full table of contents |\n`docs/spec/README.md` |\nArea index for product behavior | Part 2 index |\n`docs/spec/PROJECT_INITIALIZER.md` |\nProject initialization entry | Part 2, Chapter 1 |\n`docs/spec/cli/README.md` |\nChild index for CLI documents | Part 2, Chapter 2 index |\n`docs/spec/cli/CONFIG_COMMAND.md` |\nconfig command entry | Part 2, Chapter 2, Section 1 |\n`docs/arch/DOCS_STRUCTURE.md` |\nArchitecture of the documentation system | A chapter in Part 3 |\n`docs/test/CLI_INTERFACE.md` |\nTest strategy for CLI behavior | A chapter in Part 4 |\n\nA small subject starts as one indexed file. When it grows, it becomes a directory with a `README.md`\n\nand its own child entries. The filename names the entry, while the full path is its address from the top-level index.\n\nA directory does more than group documents by topic. It tells an agent how to interpret the information inside.\n\n`concept/`\n\nexplains mental models and core concepts.`spec/`\n\ndefines the product's current specs.`arch/`\n\nexplains architectural rationale, structure, and technical constraints.`test/`\n\nrecords regression tests and manual test procedures.`report/`\n\npreserves evidence from research and measurement.`plan/`\n\nrecords the intent of active work.`archive/`\n\npreserves completed work and historical context.Consider this path:\n\n```\ndocs/spec/cli/CONFIG_COMMAND.md\n```\n\nThis document describes the CLI config command in the current product specs.\n\nPaths change the meaning even when documents cover the same subject.\n\n```\ndocs/arch/CLI_ARCHITECTURE.md\ndocs/test/CLI_INTERFACE.md\ndocs/archive/plan/cli-refactor/README.md\n```\n\nThe first explains architecture, the second explains testing, and the third records historical work. Their paths reveal role and freshness even when their bodies use similar terms.\n\nThe following filenames distinguish files but do not explain their contents.\n\n```\nDOCUMENT_1.md\nNOTES_NEW.md\nFINAL_V2.md\nMISC.md\n```\n\nThese names expose scope before the files are opened:\n\n```\nPROJECT_INITIALIZER.md\nCLI_INTERFACE.md\nLOAD_SNAPSHOT.md\nVALIDATION_ARCHITECTURE.md\n```\n\nA good filename works like a chapter title that is meaningful in the table of contents. Dotdotgod uses kebab-case for directories and UPPER_SNAKE_CASE for durable Markdown documents. `README.md`\n\nis the predictable entry point for every directory.\n\n`CONFIG_COMMAND.md`\n\nis more useful than `API_1.md`\n\nbecause it names behavior and domain instead of writing order. Stable, specific names let people and agents use the same vocabulary when finding and referencing documents.\n\nEach directory's `README.md`\n\nis a local index rather than a generic introduction.\n\n```\n# Product specifications\n\n- `CLI_INTERFACE.md`: user-facing CLI specs\n- `PROJECT_INITIALIZER.md`: project initialization behavior\n- `cli/`: detailed specs for individual CLI commands\n- `plan-mode/`: plan mode and staged execution specs\n```\n\nAn agent can read this README and choose the next document without opening every file in the directory. This is why adding, moving, or renaming a document should update the nearest README in the same change.\n\nDo not begin with a complex hierarchy. If a subject has one document, start with one file.\n\n```\ndocs/spec/PAYMENT.md\n```\n\nWhen the domain grows into multiple documents, promote it to a directory.\n\n```\ndocs/spec/payment/\n├── README.md\n├── LIST_API.md\n├── SUMMARY_API.md\n└── REFUND_POLICY.md\n```\n\n`payment/README.md`\n\nbecomes the intermediate index between the spec area and its individual documents. An agent narrows the search in four steps:\n\n`docs/README.md`\n\n.`docs/spec/README.md`\n\n.`docs/spec/payment/README.md`\n\n.The amount of possible context grows with the project, but an index keeps the context required for the current task small.\n\nWhen changing the current behavior of a CLI command, inspect `docs/spec/cli/`\n\nfirst. Read `docs/arch/`\n\nwhen implementation constraints matter, `docs/test/`\n\nwhen regression coverage matters, and `docs/archive/`\n\nonly when a historical decision is relevant.\n\nThe documentation structure answers two questions:\n\nGood project memory is not a system that injects every document into every prompt. It provides a route to relevant information and a boundary that excludes irrelevant information.\n\nIt is natural to begin project-memory design by asking what to store. First ask whether the information has a useful address.\n\nDirectories divide the book into parts, filenames name chapters, README indexes route readers, and headings narrow a document into sections.\n\nDesigning documentation for AI is not cosmetic file organization. It is designing a table of contents that lets an agent reach the chapter required by the current question without reading the whole project.", "url": "https://wpnews.pro/news/ai-agent-memory-starts-with-a-documentation-table-of-contents", "canonical_source": "https://dev.to/dotdotgod/ai-agent-memory-starts-with-a-documentation-table-of-contents-4h3", "published_at": "2026-07-19 08:13:24+00:00", "updated_at": "2026-07-19 09:01:12.191823+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "developer-tools"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/ai-agent-memory-starts-with-a-documentation-table-of-contents", "markdown": "https://wpnews.pro/news/ai-agent-memory-starts-with-a-documentation-table-of-contents.md", "text": "https://wpnews.pro/news/ai-agent-memory-starts-with-a-documentation-table-of-contents.txt", "jsonld": "https://wpnews.pro/news/ai-agent-memory-starts-with-a-documentation-table-of-contents.jsonld"}}