GEMINI.md for Gemini CLI

What GEMINI.md is

The Gemini CLI docs call them context files: "Context files, which use the default name GEMINI.md, are a powerful feature for providing instructional context to the Gemini model." The CLI "loads various context files from several locations, concatenates the contents of all found files, and sends them to the model with every prompt." That last clause is the cost model in one line: whatever is in your GEMINI.md files is paid on every turn, exactly as a CLAUDE.md is in Claude Code (see how many tokens a CLAUDE.md costs).

The file is plain markdown with no frontmatter and no required headings. The docs' own example is a title, a "General Instructions" list and a "Coding Style" list: "Use 2 spaces for indentation", "Always use strict equality (=== and !==)". The CLI footer "displays the number of loaded context files", which is the quickest way to see that a file was picked up.

The hierarchy: global, project, subdirectory

The GEMINI.md page and the configuration reference describe three tiers, joined in this order:

1. Global: ~/.gemini/GEMINI.md. "Provides default instructions for all your projects." Your personal preferences go here, never the team's.
2. Project root and ancestors: the CLI "searches for the configured context file in the current working directory and then in each parent directory up to either the project root (identified by a .git folder) or your home directory." The stop marker is configurable: context.memoryBoundaryMarkers defaults to [".git"], and "an empty array disables parent traversal."
3. Subdirectories, just in time: "When a tool accesses a file or directory, the CLI automatically scans for GEMINI.md files in that directory and its ancestors up to a trusted root." A component's own GEMINI.md arrives mid-session, when the model first reads or edits something there, not at launch.

The two pages disagree on subfolders. The configuration reference still says the CLI "also scans for the configured context file in subdirectories below the current working directory", "limited to 200 directories by default" by context.discoveryMaxDirs. The GEMINI.md page no longer mentions that scan, and the current discovery code loads subfolder files only just in time, so treat the 200-directory scan as legacy behaviour that your version may or may not have. /memory list shows what actually loaded.

On precedence: "Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general)." Note the "typically". The files are concatenated "with separators indicating their origin and path", so nothing is actually removed; a more specific file simply comes later in the prompt. If the global file says one thing and the project file says the opposite, both are in front of the model. Keep them from disagreeing.

~/.gemini/GEMINI.md
  # you: "reply tersely", "prefer pnpm"
repo/GEMINI.md
  # team: build, test, layout, conventions
repo/packages/api/GEMINI.md
  # only when work touches packages/api

Two settings extend the search. context.includeDirectories adds other folders to the workspace, and context.loadMemoryFromIncludeDirectories (default false) controls whether a memory reload scans their GEMINI.md files too.

Imports with @file.md

A GEMINI.md can pull in other files: "You can break down large GEMINI.md files into smaller, more manageable components by importing content from other files using the @file.md syntax." The Memory Import Processor page gives the forms: @./file.md (same folder), @../file.md (parent), @./components/file.md, and absolute paths such as @/absolute/path/to/file.md.

# Acme web

@./docs/agent/commands.md
@./docs/agent/conventions.md

## Gemini CLI only
- Run `/memory show` after editing any of the imported files.

Facts from the same page that matter when you use this:

• Imports nest, and "to prevent infinite recursion, there's a configurable maximum import depth (default: 5 levels)." Claude Code's equivalent is four hops.
• Circular imports are "detected and prevented".
• "@ imports inside" code blocks and inline code spans "are properly ignored", so an npm scope in backticks, such as `@acme/ui`, is safe. An unquoted one may be read as an import.
• A missing file does not abort the load: "the import will fail gracefully with an error comment in the output."
• Imports are validated against allowed directories, "preventing access to sensitive files outside the allowed scope."

As with CLAUDE.md, imports organise text; they do not reduce it. The imported content is in the prompt on every turn. The browser checker does not follow imports; the Claude Code plugin does, and flags an import whose file is missing or resolves outside the project.

The context file name setting

The name GEMINI.md is a default, not a requirement. "To specify a different name or a list of names, use the context.fileName property" in settings.json. The configuration reference types it as string | string[]. Settings files live in four places; the two you will use are the user file at ~/.gemini/settings.json and the project file at .gemini/settings.json "within your project's root directory", and "project settings override user settings."

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

The docs show the list form with ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]. They do not say in what order two files found in the same folder are concatenated, so if you list more than one name, avoid having both in one folder or keep them from contradicting each other. The global file follows the same setting: the reference describes it as ~/.gemini/<configured-context-filename>.

The /memory commands

The commands reference lists three sub-commands under /memory:

• /memory show: "Display the full, concatenated content of the current hierarchical memory that has been loaded from all GEMINI.md files." The tutorial adds that "this prints the raw text the model receives at the start of the session. It's excellent for debugging why the agent might be ignoring a rule."
• /memory list: "Lists the paths of the GEMINI.md files in use for hierarchical memory."
• /memory refresh: "Reload the hierarchical instructional memory from all GEMINI.md files found in the configured locations (global, project/ancestors, and sub-directories)." The GEMINI.md page and the tutorial call the same command /memory reload; the docs are inconsistent on the name, so if one spelling is not recognised in your version, try the other.

Edits to a GEMINI.md during a session are not picked up until you reload: "If you edit a GEMINI.md file while a session is running, the agent won't know immediately." The current reference does not list a /memory add sub-command. Saving a fact from chat works differently now: the memory files page says the agent "persists durable facts, user preferences, and project details by editing Markdown memory files directly", routing "shared project instructions" to the repository GEMINI.md and "cross-project personal preferences" to ~/.gemini/GEMINI.md. So a GEMINI.md in a shared repository can change because someone asked the agent to remember something. Review it in pull requests like any other file.

One source for GEMINI.md and AGENTS.md

If Gemini CLI is not the only agent on the project, you do not want a GEMINI.md that drifts from the AGENTS.md everyone else reads. There are two clean options.

Option 1: tell Gemini CLI to read AGENTS.md. Commit a .gemini/settings.json with context.fileName set to ["AGENTS.md", "GEMINI.md"]. Every teammate's CLI then loads AGENTS.md from the root and from subfolders, and a GEMINI.md is only needed where there is something Gemini-specific to say. The project settings file is the point: a user-level setting would work only on your machine.

Option 2: a thin GEMINI.md that imports AGENTS.md. No settings change, and the same shape Claude Code users adopt for CLAUDE.md:

@./AGENTS.md

## Gemini CLI
- Use `/memory show` to confirm AGENTS.md loaded.

Either way, keep in mind who reads what. Codex, Cursor and Copilot read AGENTS.md directly. Copilot also reads a root GEMINI.md as agent instructions, so with option 2 Copilot sees both files; its docs describe no import syntax, so to Copilot the @./AGENTS.md line is just text. Claude Code reads AGENTS.md when there is no CLAUDE.md; the details are in AGENTS.md vs CLAUDE.md. A symlink from GEMINI.md to AGENTS.md is a third option with the usual caveat that Windows checkouts without core.symlinks turn it into a one-line text file.

Keeping it short

The Gemini CLI docs give no line or token limit for GEMINI.md. The tutorial's advice is "Keep it focused: Avoid adding excessive content to GEMINI.md. Keep instructions actionable and relevant to code generation", and "Review often: Periodically check your GEMINI.md files to remove outdated rules." It also suggests negative constraints: telling the agent what not to do "is often more effective than vague positive instructions."

Because the hierarchy concatenates rather than replaces, the total matters more than any one file. Keep the global file to a few lines of personal preference, the root file to what every task needs, and push component-specific rules down into the subfolder that owns them so they load just in time instead of always. The writing rules from CLAUDE.md best practices carry over unchanged: exact commands, exact paths, rules a reviewer could check, no contradictions.

Checklist

• Personal preferences in ~/.gemini/GEMINI.md, team facts in the root file, component rules in subfolders
• No rule in the global file contradicts the project file
• Every @./path import exists; npm scopes and other @names are in backticks
• Import chains are shallow (the default depth limit is 5)
• If other agents are used, context.fileName in .gemini/settings.json or a thin importing GEMINI.md keeps one source
• /memory show looks like what you expect, and /memory list shows no surprise files
• Nothing hidden: read the raw file for HTML comments and invisible characters before merging

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

Sources, read on 14 October 2026, all in the google-gemini/gemini-cli docs: Provide context with GEMINI.md files, Configuration reference (context settings and "Context files"), Memory Import Processor, Commands reference (/memory), Memory management tutorial and Memory files. Quotes are exact. Also read: memoryDiscovery.ts in the Gemini CLI source. Related: Cursor rules, GitHub Copilot custom instructions.