In Gemini CLI 0.62.0, which GEMINI.md files reach the model, in what order, and how do you see exactly what it received?
answer
- home, repository, then touched folders
- upward walk stops at the .git root
- concatenated, never overridden
- /memory show versus /memory list
- context.fileName and @file.md imports
basics
~20 sGemini CLI concatenates ~/.gemini/GEMINI.md, the GEMINI.md files from the launch directory up to the repository root, and files found later in folders a tool touches. /memory show prints the combined text; /memory list prints the paths.
solid answer
~40 sAt 0.62.0 Gemini CLI builds one block of instructions from every context file it finds. First the global `~/.gemini/GEMINI.md`; then, walking upward from the directory you launched in, every `GEMINI.md` up to the first directory holding `.git` (the `context.memoryBoundaryMarkers` setting), ordered root to leaf; then, just in time, any `GEMINI.md` in a folder a tool reads or writes. Nothing overrides anything: the files are concatenated with their paths as separators and sent with every prompt. `/memory show` prints exactly that text, `/memory list` prints the file paths, and `/memory reload` (alias `refresh`) re-scans after you edit one. `@./file.md` imports another Markdown file inline, and `context.fileName` changes or extends the names it looks for, for example to read `AGENTS.md` too.
code
json · 6 lines{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"],
"memoryBoundaryMarkers": [".git"]
}
}go deeper
Know that ~/.gemini/GEMINI.md and the repository's GEMINI.md are both read, and that /memory show prints what the model gets.
Explain the three tiers - global, the upward walk to the .git root, just-in-time folders - and that the files are concatenated rather than overriding each other.
Debug a missing instruction methodically: /memory list for paths, /memory show for text, the boundary marker for files above the root, and /memory reload after edits.
Decide how a team splits guidance between global, root and nested files, and whether context.fileName should standardise on AGENTS.md alongside GEMINI.md across repositories.
## What a GEMINI.md file is A **context file** is a Markdown file of instructions that Gemini CLI, Google's open-source terminal agent, reads and sends to the model with every prompt. Its default name is `GEMINI.md` (the constant in the source is `DEFAULT_CONTEXT_FILENAME`). It carries project conventions, commands to run, style rules or a persona. It is **guidance the model reads**, not configuration the CLI enforces: a rule in it can still be ignored, which is why permissions live elsewhere (approval modes, policies, settings). ## Where Gemini CLI 0.62.0 looks The CLI assembles context from three tiers, in this order: 1. **Global** - `~/.gemini/GEMINI.md`, your personal defaults for every project. 2. **Workspace** - starting at the directory you launched in, the CLI walks **upward** and collects every context file it finds, stopping at the project root: the first directory that contains a `.git` marker. Files are ordered from the root down, so the repository-wide file comes before a nested one. The marker list is the setting `context.memoryBoundaryMarkers` (default `[".git"]`; an empty list disables the parent walk). A `GEMINI.md` sitting above the repository root - say in `~/work` - is outside that walk. 3. **Just in time** - when a tool reads or writes something in a directory, the CLI scans that directory and its ancestors, up to the same ceiling, for context files it has not loaded yet and adds them. A component's own `GEMINI.md` therefore arrives the first time the agent touches that component, not at startup. Installed **extensions** can contribute a context file as well (`contextFileName` in `gemini-extension.json`, or a `GEMINI.md` in the extension directory). ## Concatenation, not override Every file found is **concatenated**, with separators that name each file's path, and the result travels with each prompt. No file replaces another. | Situation | What the model receives | |---|---| | Global and repository files both say how to format commits | Both texts, global first | | A nested `GEMINI.md` contradicts the root one | Both texts; the model has to reconcile them | | A `GEMINI.md` in `~/work`, above a repository with `.git` | Not loaded by the workspace walk | | A sub-folder file the agent has not touched yet | Not loaded yet; it arrives just in time | The practical consequence: write the general rule once, put only genuinely local rules in nested files, and avoid two files that disagree, because there is no precedence rule to settle it for you. The CLI footer shows how many context files are loaded, a quick sign that a file you expected is missing. ## Seeing what the model received - `/memory show` - prints the **full concatenated text** currently loaded. This is the answer to "what did the model actually get?" - `/memory list` - prints the **paths** of the context files in use, which tells you which files loaded but not what they say. - `/memory reload` (alias `/memory refresh`) - re-scans and reloads every context file, for when you edited one mid-session. - `/init` - analyses the project and creates a tailored `GEMINI.md` to start from. ## Imports and renaming A large file can be split with **imports**: a line such as `@./docs/testing.md` or `@../shared/style-guide.md` pulls that Markdown file's content in at that point. Relative and absolute paths work, imported files may import others, circular imports are detected and stopped, the import-processor page gives a default maximum depth of five levels, and an `@` inside a code block or inline code span is ignored. The setting `context.fileName` takes a string or an array of names. Setting it to `["AGENTS.md", "GEMINI.md"]` makes the CLI treat both names as context files at every tier, so a repository that already keeps an `AGENTS.md` does not need a duplicate. ## Mistakes that show up in practice - Expecting the closest file to win and deleting shared rules from it: both files are sent, so the model sees the contradiction. - Debugging with `/memory list` and concluding the instructions are fine: it lists paths, not content. - Putting team rules in a `GEMINI.md` above the repository root and wondering why teammates never get them. - Editing `GEMINI.md` mid-session and forgetting `/memory reload`. - Treating a sentence in `GEMINI.md` as a security control; it is a request to the model, not a permission.
- A rule lives in services/billing/GEMINI.md, and Gemini CLI was launched at the repository root. When does the model see it?Not at startup: the workspace walk goes upward from the launch directory, so it never descends into `services/billing`. The file is loaded just in time, the first time a tool reads or writes something in that folder, and from then on it is part of the concatenated context. `/memory list` shows whether it has been picked up yet.
- How do you share one style guide between several GEMINI.md files without copying it?Keep the guide in its own Markdown file and import it with a line such as `@../shared/style-guide.md` in each `GEMINI.md`. The import processor inlines its content, handles nested imports, stops circular ones and ignores `@` inside code blocks. `/memory show` confirms the guide's text actually arrived.
- The closest GEMINI.md overrides the global one, so only one file is sent.
- Gemini CLI reads only the GEMINI.md in the directory you launched from.
- /memory list shows the instructions the model is actually receiving.
- The file must be called GEMINI.md; the name cannot be changed.
- An @file.md line is only a link the model may open later.
- A GEMINI.md anywhere above the repository is always loaded.
Assumes Gemini CLI 0.62.0: the .git-bounded upward walk, just-in-time loading and /memory list / reload (alias refresh) are as defined in that release's source.