GEMINI.md Guide: Context Files for Gemini CLI

GEMINI.md is the context file Gemini CLI reads at the start of every session: a plain markdown file of project instructions — tech stack, build commands, conventions, gotchas — loaded into the model's context before you type your first prompt. Instead of re-explaining your project in every chat, you write it down once and the agent carries it into every session.

Gemini CLI loads these files hierarchically: a global file at ~/.gemini/GEMINI.md, a project file at your repo root, and per-directory files deeper in the tree, all concatenated into what the CLI calls memory. This guide covers how that loading works, how to keep context modular with @file imports, how to inspect and update memory with /memory commands, and how GEMINI.md fits alongside AGENTS.md when your team runs more than one AI tool.

What is GEMINI.md and how Gemini CLI loads it

When Gemini CLI starts, it scans for context files, concatenates everything it finds (with separators marking which file each section came from), and injects the result into the model's instructions. The footer of the CLI shows how many context files are currently loaded, and /memory show prints the exact combined text the model sees.

Two properties follow from that mechanism, and they shape everything else in this guide:

• It's always on. Every line of every loaded GEMINI.md is in context on every turn. Good instructions pay rent constantly; stale ones cost tokens and attention constantly.
• It's just markdown. There's no schema to learn. Headings, bullet points, and short code snippets work best, because that's what models parse most reliably.

The content that earns its place is the stuff the agent can't infer from your code: which commands to run, which conventions are deliberate, and which mistakes it must never make. The Gemini CLI context file is an onboarding doc for an agent, not general documentation.

Hierarchical loading: global, project, and subdirectory files

The hierarchical context Gemini CLI assembles comes from three levels:

Concretely, Gemini CLI looks in three places: the global file, then project files found by walking up from your current directory toward the project root, then files found by scanning down into subdirectories beneath where you launched the CLI (skipping paths ignored by .gitignore or .geminiignore).

Order matters. Files are concatenated from most general to most specific — global first, deeper directories last. Since later instructions refine earlier ones, this gives you a natural override pattern: the global file says "prefer small, focused commits," the project file says "this repo uses conventional commits," and packages/api/GEMINI.md says "API changes must update the OpenAPI spec in the same commit."

If you use CLAUDE.md in Claude Code, this will feel familiar — the two systems are near-identical, as our CLAUDE.md guide shows. That similarity is worth exploiting, and we'll get to it in the AGENTS.md section below.

How to set up GEMINI.md: step by step

1. Create a project-root GEMINI.md

Start with the four sections that help most: commands, stack, conventions, and boundaries.

# my-app

## Commands
- Dev server: pnpm dev
- Tests: pnpm test
- Type check: pnpm typecheck
- Lint: pnpm lint

## Stack
- Next.js 15 (App Router), TypeScript strict mode
- Drizzle ORM + Postgres
- Vitest for tests

## Conventions
- Named exports only for components
- API routes return { data, error }
- Database columns are snake_case

## Do NOT
- Never edit generated files in src/db/migrations/
- Never use the any type
- Never commit .env files

2. Verify it loads

Run gemini from the repo root. The footer shows the number of context files in use, and you can confirm the content:

gemini
> /memory show

If your file isn't there, check that you launched the CLI inside the project and that the file isn't in an ignored directory.

3. Add a global file for personal preferences

Keep anything that's about you rather than the project in ~/.gemini/GEMINI.md:

# Personal preferences

- Be concise. Skip restating the plan before executing it.
- Prefer editing existing files over creating new ones.
- Always run the test suite before declaring a task done.

This file loads in every project, so keep it short and universally true.

4. Add subdirectory files where conventions diverge

In a monorepo, a single root file forces every rule on every package. Instead, push area-specific rules down the tree:

packages/api/GEMINI.md      # API conventions, error-shape rules
packages/web/GEMINI.md      # component patterns, styling rules
infra/GEMINI.md             # Terraform conventions, safety rails

5. Commit the project files

Project and subdirectory GEMINI.md files belong in git — they're team configuration, reviewed like code. The global file stays personal and uncommitted. If you edit any file mid-session, run /memory refresh to reload it.

@file imports for modular context

A root GEMINI.md that tries to hold everything becomes unreadable fast. Gemini CLI supports an import syntax that lets you compose context from smaller files:

# Project context

Core commands and conventions live in the sections below.

@./docs/agent/testing.md
@./docs/agent/api-conventions.md
@./docs/agent/security-rules.md

Each @path line is replaced with the contents of that file when context is loaded. Paths can be relative or absolute, relative paths resolve from the file doing the importing, and imported files can themselves import further files.

This is great for maintainability: each concern lives in one focused file, diffs stay reviewable, and the same security-rules.md can be imported by several entry points. One thing imports do not do is save tokens — imported content is inlined into memory just as if you'd pasted it. Modularity is for humans; the model sees one flattened document either way.

Managing memory with /memory commands

Gemini CLI memory is the loaded, concatenated context — and the /memory command family is how you inspect and manage it during a session:

/memory add is the interesting one. When you tell the CLI something worth remembering — "we deploy from the release branch, never main" — it appends the fact to your global ~/.gemini/GEMINI.md so future sessions start with it. Handy, but treat it as an inbox, not an archive: facts added this way land in your personal global file, invisible to teammates and unreviewed. Periodically promote the good ones into the committed project GEMINI.md and delete the rest.

/memory show is your debugging tool. If the agent keeps ignoring an instruction, check whether the instruction actually made it into memory — a file outside the scan path, or an ignored directory, is the usual culprit.

Keeping GEMINI.md lean — the bloat problem

Context files fail in a predictable way: they grow. Every incident adds a rule, nobody deletes anything, and a year later the agent is reading a 600-line document where the three rules that matter are buried between stale ones.

Bloat hurts twice. It burns context window on every single turn, and it dilutes instruction-following — models weight a handful of crisp rules far better than a wall of prose, and contradictory leftovers ("use yarn" three lines above "use pnpm") actively degrade output.

Heuristics that keep a GEMINI.md healthy:

1. If the agent can infer it from code, delete it. You don't need to document that the project uses TypeScript; the .ts files do that.
2. Every rule earns its place by preventing a real mistake. "Write good code" prevents nothing. "Never edit files in src/db/migrations/" prevents a specific, observed failure.
3. Push specificity down the tree. Rules that only matter in one package belong in that package's GEMINI.md, not the root.
4. Audit with /memory show quarterly. Read what the model reads. Anything you skim past, the model effectively skims too.
5. Prune /memory add accumulations. The auto-appended facts section of your global file is where one-off notes go to rot.

The same discipline applies to every tool's context file — our AI coding rules best practices guide goes deeper on writing rules that models actually follow.

GEMINI.md vs AGENTS.md and sharing context across tools

GEMINI.md is Gemini-specific. AGENTS.md is the cross-tool convention that Codex CLI and a growing list of agents read by default — the complete AGENTS.md guide covers its ecosystem. If your team runs multiple tools, maintaining parallel GEMINI.md, CLAUDE.md, and AGENTS.md copies of the same instructions is a drift factory.

Gemini CLI gives you two clean ways out. First, the context filename is configurable in .gemini/settings.json, and it accepts a single name or a list:

{
  "contextFileName": ["AGENTS.md", "GEMINI.md"]
}

With that setting, Gemini CLI reads your existing AGENTS.md hierarchy directly — no duplication. Second, if you want to keep a GEMINI.md entry point (say, for a few Gemini-specific notes), the import syntax makes it a one-liner:

@./AGENTS.md

Filename aliasing solves the two-tool case. It doesn't solve the ten-repo case, where the same conventions need to reach every project and every teammate's tool of choice. That's the problem a skills registry addresses: publish your conventions once to localskills.sh as a versioned skill, and each developer installs it into their tools' native formats in one command:

localskills install your-org/api-conventions --target claude cursor windsurf

The CLI writes .claude/skills/ for Claude Code, .cursor/rules for Cursor, .windsurf/rules/ for Windsurf, and so on — and because skills are plain markdown packages, the same content slots into an AGENTS.md-based Gemini CLI setup via the contextFileName trick above. Updates ship as new versions with rollback, instead of a copy-paste campaign across repos.

For a broader look at how the two CLIs compare beyond context files — agent quality, extensibility, pricing — see our Claude Code vs Gemini CLI comparison.

FAQ: GEMINI.md and Gemini CLI

Can Gemini CLI read AGENTS.md instead of GEMINI.md?

Yes. Set contextFileName in .gemini/settings.json to "AGENTS.md" (or a list of accepted names) and Gemini CLI loads those files through the same hierarchical mechanism. This is the standard move for teams consolidating on one cross-tool context file.

Where does /memory add save facts?

To your global context file at ~/.gemini/GEMINI.md, so remembered facts apply across all projects in future sessions. Team-relevant facts should be promoted by hand into the committed project GEMINI.md, since the global file is personal and unreviewed.

How do I check which GEMINI.md files are loaded?

The CLI footer shows a count of loaded context files, and /memory show prints the full concatenated content with markers indicating which file each section came from. After editing files mid-session, run /memory refresh.

Do @file imports reduce token usage?

No. Imported files are inlined into memory at load time, so the model sees the same flattened text either way. Imports exist for maintainability — smaller files, cleaner diffs, reusable fragments — not for shrinking context. To actually reduce tokens, delete stale rules and move area-specific instructions into subdirectory files.

---

One set of conventions, every tool your team uses — publish your rules as versioned skills on localskills.sh and stop maintaining per-tool copies.

npm install -g @localskills/cli
localskills login
localskills publish