How to Give Your AI Agent a Map of Your Notes

Write one plain INDEX.md file at the root of your notes — a catalog of every area, each with a link, a one-line summary, and a stable folder code. A local AI reads that map first, then drills into the files it points to — no upload, no embeddings, no vendor index. The map says where; your notes say what.

This is the oldest trick in computing, repurposed. "It is widely accepted that the 'README' concept was born around 1973-1974 on the MIT Incompatible Timesharing System (ITS)," as Ryan Grissinger writes in his history of the pattern.¹

Fifty years later, an agent opening a folder of notes faces the same problem a programmer did: what is in here, and where do I start? A map answers that in one read.

What is a map file for an AI agent?

A map file is a single plain-text document — usually INDEX.md or README.md — that lists every part of your notes with a one-line description and a link. The agent reads the map first to decide which files are relevant, then opens only those. It is a table of contents an AI can act on.

Andrej Karpathy described exactly this artifact in his "LLM Wiki" gist, where an index.md "is a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count."² The mechanism is just as plain: "When answering a query, the LLM reads the index first to find relevant pages, then drills into them."² The map is the entry point. Everything else is downstream of it.

The map says where; the instructions say how

Two different files do two different jobs — and conflating them is the most common mistake. A map describes where your knowledge lives — the layout of the territory. An instructions file describes how an agent should behave — its rules, conventions, and tone. You want both, kept separate.

The instructions layer already has a standard. AGENTS.md is "used by over 60k open-source projects. Think of it as a README for agents," per its specification site.³ That is the how: how to format output, which commands to run, what voice to use. We covered that layer in Your AI Agent Reads One Plain Markdown File.

The map is the missing companion — the where — and almost nobody writes it for a personal notes vault.

Keep the line clean. Rules and conventions go in the instructions file. Locations and summaries go in the map. When the two blur, the agent gets a wall of text that is neither a good rulebook nor a good index.

Why a small map beats dumping every note

A compact map works because it lets the agent see the shape of your knowledge without loading all of it. This is the principle behind how agents handle their own tools: only a name and a one-line description are loaded up front, and the full detail is fetched on demand. Your map is the same move, applied to your notes.

Anthropic's engineering team named the mechanism precisely. "At startup, the agent pre-loads the name and description of every installed skill into its system prompt," they write, and "this metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context."⁴ Progressive disclosure is the whole trick. A short catalog up front; the heavy content only when it is needed.

Dump three hundred notes into a chat and you pay for every token, every time — and bury the signal. A map is fifty lines that point at three hundred files. The agent reads fifty lines, picks five files, and reads those. That is the difference between scanning a library and reading its card catalog.

How to author the map: a five-step method

The whole method is one file and five passes. You can write the first version in fifteen minutes — and refine it as your notes grow. Each step adds one column of information the agent uses to decide what to open.

1. Create one INDEX.md at the root of your notes. This is the front door. Name it predictably so both you and any agent always know where to look.
2. List every major area, one line each. A line per project, topic, or folder — not per note. Aim for the areas you would name if a friend asked what you keep notes about.
3. Give each area a one-line brief. A single sentence: what this area is, in plain words. This is the summary the agent matches a query against.
4. Add a stable folder code. A short, unchanging identifier per area that matches the real folder name on disk, so a link never breaks when a title changes.
5. Link each area to its folder or entry note. A relative link the agent can follow. The map points; the agent drills.

The stable-code idea comes straight from Grissinger's own system: "The Short Code: A one-word identifier (e.g., Foghorn, Prism, Beacon). This matches the actual folder name on my hard drive," paired with "The Brief: A one-sentence description of what the project is."¹ A code plus a brief is the smallest unit a map needs.

A worked example you can copy

Here is a complete, copy-pasteable INDEX.md for a personal notes vault. Each row carries the code, the brief, and the link, and the header tells the agent what the file is and how to use it. Drop it at your root, swap in your own areas, and a local AI has an entry point on the first read.

# INDEX — Map of these notes

> This is the navigation map for this vault. Read this file first.
> Each row lists an area: a short code, a one-line brief, and where it lives.
> To answer a question, find the matching brief here, then open that folder.

## Areas

| Code      | What it is (one line)                                  | Where            |
|-----------|--------------------------------------------------------|------------------|
| `meridian`| Day job — projects, meetings, decisions, and follow-ups| [/meridian](./meridian/)   |
| `atlas`   | Personal research — reading notes and source summaries | [/atlas](./atlas/)         |
| `ledger`  | Money — accounts, subscriptions, yearly reviews        | [/ledger](./ledger/)       |
| `hearth`  | Home — recipes, repairs, appliance manuals, warranties | [/hearth](./hearth/)       |
| `compass` | Health — appointments, test results, questions to ask  | [/compass](./compass/)     |

## How to use this map

1. Match the question to a brief above.
2. Open that folder's own README or entry note.
3. Drill into specific notes from there. Do not scan unrelated areas.

_Last updated: 2026-06-26. Add a row when you start a new area; keep one line per area._

The header earns its place: it tells the agent the file is a map, names the read-first behavior, and states the drill-down rule in three steps. Each code matches a real folder, so a renamed note never orphans a link. Keep the table small — one row per area, never one per note — and the map stays a map.

For larger vaults, the same pattern nests. Grissinger calls the recursive form "The COMPASS System: A recursive documentation structure where every folder level contains a README, creating a unified map for both human navigation and AI context."¹ A root INDEX.md points at folders; each folder's own README.md maps its contents. The agent walks the levels it needs and ignores the rest.

Do you need a vector database to chat with your notes?

Not at personal scale. For a vault of roughly a hundred sources and a few hundred pages, a plain map beats the machinery. Karpathy is explicit about the bound: the index approach "works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure."² You skip the embeddings and the upload.

That bound is real, and it is a bound, not a law. "Moderate scale" is Karpathy's own phrase, and it is a ceiling. Past a few hundred pages, a map alone degrades — the agent still reads whole folders once the map points there, and the briefs get coarse.

At that size you pair the map with search or an index: the map becomes the coarse router, and a finer retrieval layer does the rest. We dug into the personal-scale case in A Personal RAG You Can Actually Audit; the map is the lightweight front door to it.

The reason this works on plain files at all is that markdown is already legible to a model — no conversion, no export, no lossy round-trip. That substrate argument lives in Why an LLM Reads Your Markdown Better Than an Export; the map is what you author on top of it.

How notes flow to an answer

The path from a question to an answer is short and inspectable. The agent reads the map, matches the question to one brief, opens that folder's notes, and answers from them. You can see every step — because every step is a file you wrote.

flowchart TD
  A[You ask a question] --> B[Agent reads INDEX.md]
  B --> C{Match a brief?}
  C -->|Yes| D[Open that folder]
  C -->|No| E[Ask you to clarify]
  D --> F[Read the notes there]
  F --> G[Answer from your notes]

Figure: How a map routes a query — the agent reads your INDEX.md first, matches the question to one area's brief, opens that folder, reads the notes inside, and answers from them. If nothing matches, it asks rather than scanning everything.

This flow is the practical payoff. Without a map, an agent's "discovery phase burns time and credits and repeats on every fresh chat," as Steve Sewell of Builder.io puts it.⁵ The map front-loads that discovery into one file you maintain once, so every fresh session starts oriented instead of lost.

Common mistakes

A map fails in predictable ways, and most of them come from treating it as a dumping ground instead of a router that points elsewhere. The map is small by design; the detail lives in the folders it links to. Avoid these five mistakes, and the map stays useful as your notes grow from a handful of areas.

• One row per note, not per area. A map with three hundred rows is just your file tree with extra steps. One line per area; let the folder's own README handle the detail.
• No link, just a name. The agent has to be able to follow the map. A row without a relative link is a label, not a route.
• Codes that drift. If the code does not match the real folder on disk, links break the first time you rename something. Pin the code to the folder name.
• Stale briefs. A one-line summary that no longer describes the folder sends the agent to the wrong place. Update the brief when the area changes, not the note.
• Assuming the agent reads it perfectly. A map reduces blind scanning; it does not guarantee the agent reads or parses it correctly every time. The agent can ignore or misread the map. Treat it as a strong hint, not a contract — and keep the map short enough that following it is the path of least resistance.

One honest caveat on tooling: the precise read-and-merge behavior differs by agent. Claude Code, for example, "reads CLAUDE.md files from three locations, merged in order: 1. ~/.claude/CLAUDE.md ... 2. ./CLAUDE.md ... 3. Subdirectory CLAUDE.md files," per DeployHQ's config-file guide.⁶ That precedence is one tool's documented behavior; other agents differ. Do not assume one tool's merge order is universal — write the map at your vault root, where every tool looks first.

Where this fits in MNMNOTE

The map is a plain file you author and own, sitting at the root of notes kept locally on your own device. It works for a local on-device model, for a hosted model you bring your own key to, and for future-you flipping through the vault. The artifact is the same every time: one markdown file, no vendor index.

One scoped point about privacy. If you run a local model, the map and the notes it points to stay on your device. If you opt into a hosted model, the agent reads the files you send it — the map plus the pages it drills into — and that text leaves your device for the provider you chose.

The map keeps that surface small, because the agent sends only what the map routes it to, not the whole vault. Scope the claim to the path you actually run.

There is a quieter benefit, too. The same map you write for an agent is the index a human refinds notes through — the one index note that beats a graph, now doing double duty.

How you shape each note inside those folders is its own retrieval question, covered in How You Structure a Note Is Its AI Retrieval. The map handles navigation across files; structure handles retrieval within one.

Frequently asked questions

How does an AI agent navigate my notes?

It reads a map file first. Author one INDEX.md at your vault root that lists every area with a link and a one-line summary; the agent reads that catalog, matches your question to a brief, and opens only the relevant files. As Karpathy puts it, the model "reads the index first to find relevant pages, then drills into them."²

What should an index or map file for AI contain?

A catalog of every area, each with three things: a relative link to its folder, a one-line brief describing what it is, and a stable short code matching the folder name on disk. Optionally add metadata like a last-updated date. Keep it to one row per area, never one per note, so the map stays a router and not a duplicate file tree.

What is the difference between AGENTS.md, CLAUDE.md, and a README map?

They split into how versus where. AGENTS.md and CLAUDE.md are instruction files — rules and conventions for how an agent behaves; AGENTS.md is the cross-tool "README for agents,"³ and CLAUDE.md merges across three locations in a defined order.⁶ A README or INDEX.md map is the navigation layer: where your knowledge lives. Write both, kept separate.

Do I need a vector database to chat with my notes?

Not at personal scale. For roughly a hundred sources and a few hundred pages, a plain map "works surprisingly well" and "avoids the need for embedding-based RAG infrastructure," in Karpathy's words.² For much larger vaults a map alone degrades — pair it with a search or index layer at that point.

How do I give an AI context about my whole vault without uploading it?

Author the map file in place and point your agent at the folder. A local model reads the map and the files it routes to without anything leaving your device. A hosted model reads only the text you send it — the map plus the pages it drills into — so the map keeps that surface as small as the question requires.

Will the agent actually read the map?

A map reduces blind scanning; it does not guarantee perfect reading. The agent can ignore or misparse it. Keep the map short, put it where the tool looks first (the vault root), and treat it as a strong, cheap hint rather than a contract — it lowers the cost of getting oriented without promising the agent never wanders.

This is, at heart, the README pattern wearing new clothes: a predictable place to learn where everything is, written once and read first. The technique traces to Andrej Karpathy's "LLM Wiki" gist, which is the direct precedent for mapping a personal notes vault rather than a codebase. The map says where; your notes say what.

Write the map in a plain markdown note you keep on your own device, and the front door to your vault is one file you control — try it at mnmnote.com.