GEMINI.md: what it is and how to write one

Ahmet Karaca · 30 October 2026

What is GEMINI.md for?

It holds the instructions Gemini CLI should always have: project commands, coding conventions, and how you prefer to work. The file belongs to Gemini CLI, the terminal agent. It does not affect the Gemini app in a browser, which keeps its own settings.

There is no required structure. Plain headings and short lists are enough, and each line is worth keeping only if it changes what the agent does.

Where does Gemini CLI look for GEMINI.md?

Gemini CLI joins the contents of every file it finds and sends the result with each prompt. The footer of the CLI shows how many context files are loaded.

How do you see and reload what is loaded?

• /memory show prints the full joined text, which is exactly what the model is given.
• /memory reload scans all the locations again, which is useful after editing a file during a session.

When an instruction seems to be ignored, /memory show is the first thing to check: it settles whether the file was loaded at all.

What should go in a project GEMINI.md?

Commands the agent cannot guess, conventions it would otherwise break, and files it must not touch. Anything general enough to apply to every repository belongs in the personal file instead.

# Project: billing-api

## Commands
- Test: npm test
- Lint before every commit: npm run lint

## Conventions
- All amounts are integers in minor units.
- Do not edit generated files under src/generated/.

What should go in the personal file?

~/.gemini/GEMINI.md is the place for how you work, as opposed to how a project works. It follows you into every repository and is not shared with anyone.

# How I work

- Ask before deleting files or running destructive commands.
- Propose a short plan before changing more than three files.
- Write commit messages in the language the repository already uses.

Gemini CLI can also write here itself. Asked to remember something, the agent edits a Markdown memory file: shared project instructions go to the repository's GEMINI.md, private project notes to a per-project memory folder, and personal preferences that apply across projects to ~/.gemini/GEMINI.md. These are ordinary files and can be read and corrected by hand.

How do you split a large GEMINI.md?

A file can import others with the @file.md syntax, using relative or absolute paths. This keeps the main file short and lets several projects share one style guide.

# Project

@./docs/style-guide.md
@../shared/commit-rules.md

Can Gemini CLI use AGENTS.md instead?

Yes, with one setting. The file name is configurable through context.fileName in settings.json, which accepts a single name or a list. A repository that already keeps its instructions in AGENTS.md can then serve Gemini CLI from the same file.

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

Sources, checked on 30 October 2026

• Gemini CLI docs: GEMINI.md files
• Gemini CLI docs: Memory files
• Gemini CLI docs: Manage context and memory
• Gemini CLI docs: Configuration