# GEMINI.md — context Gemini CLI reads every time

Course: Gemini CLI from Zero — https://zero2vibecode.com/learn/gemini-cli
Canonical URL: https://zero2vibecode.com/learn/gemini-cli/0-3-gemini-md
Verified against: Gemini CLI v0.65.0 (2026-10-22)
Last updated: 2026-10-22

GEMINI.md is a Markdown file of instructions that Gemini CLI sends to the model with every prompt: a global one in your home folder, plus the ones in your project. Write down what you would otherwise repeat, check what was loaded with /memory show, and keep it short.

Three sessions in, you notice you keep typing the same sentences. The test command. The folder that is generated and must not be touched. The convention nobody wrote down.

Write them down once instead.

## What GEMINI.md is

A Markdown file of instructions. Gemini CLI loads the GEMINI.md files it finds, joins their contents, and sends them to the model with every prompt. You stop repeating yourself, and the model stops forgetting.

The Gemini CLI docs' own example starts like this:

```text
# Project: My TypeScript Library

## General Instructions

- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
```

## Where it is read from

Gemini CLI loads context files from three kinds of place, in this order:

1. **Global:** `~/.gemini/GEMINI.md` in your home folder. Defaults for every project — how you like explanations, conventions you always want.
2. **Workspace:** GEMINI.md files in the folders you are working in and their parent folders. Project rules go here, usually in the project root.
3. **Just in time:** when one of its tools reads a file or folder, Gemini CLI also looks for GEMINI.md files in that folder and its ancestors, up to a trusted root. A note in `src/payments/` is picked up when the work reaches `src/payments/`.

The footer shows how many context files are loaded, which is a quick check that yours was found. For the full picture, type:

```text
/memory show
```

It prints the combined content of everything that was loaded — the actual text the model is getting.

## Let it draft one

`/init` looks at the current folder and generates a GEMINI.md tailored to it. Use it, then read every line and cut what is not true. A confident, wrong context file is worse than none.

Large files can be split: a line such as `@./docs/style-guide.md` inside GEMINI.md imports that file's content, so the root file stays a short index.

## What earns a line

The test: *would I otherwise say this at the start of every session?*

- **Commands:** how to run the tests, the build, the linter.
- **Boundaries:** generated folders, vendored code, anything not to be edited by hand.
- **Conventions you cannot see in the code:** "Dates are stored as UTC strings."

Every line goes with every prompt, so keep it short. Fifteen rules that matter beat three hundred lines of aspirations.

Write the exercise version in the terminal: the test command and one hands-off folder.

## Already have an AGENTS.md?

GEMINI.md is only the default name. In `settings.json`, `context.fileName` takes a list, so Gemini CLI can read the file your other tools already use:

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

**On Antigravity CLI.** 
Google's migration guide for Antigravity CLI says it reads workspace rules from both GEMINI.md and AGENTS.md, and global rules from `~/.gemini/GEMINI.md`, with no changes needed to existing files. What you write in this lesson carries over.

**Should GEMINI.md be committed to Git?**

Yes, for project rules: everyone working on the project gets the same context, and it changes together with the code. Personal preferences belong in ~/.gemini/GEMINI.md instead.

**Is GEMINI.md the same as the memory tool?**

They are related but not the same. GEMINI.md is a file you write and maintain. The /memory command manages the context loaded from those files, and the docs describe a separate memory tool for saving facts during a session.