GEMINI.md is the context (memory) file Gemini CLI and Gemini Code Assist read to learn how to work in your project — its stack, key commands, conventions, what not to do, and the definition of done. It lives at the repo root (checked into git so the team shares it). Gemini loads GEMINI.md hierarchically: a global ~/.gemini/GEMINI.md that applies to all projects, project-root and ancestor files, and subdirectory files for component-specific context, all concatenated into the session context.

What should go in a GEMINI.md file?

A one-line project overview, the stack, the key commands (build/test/lint/deploy), conventions and coding style the agent must follow, explicit don't-dos, and your definition of done. Keep it lean — research found bloated, dump-everything context files lowered task success ~3% and raised cost 20%+, while short curated ones improved success ~4%. Use @path imports rather than pasting long docs inline.

How does Gemini load GEMINI.md, and what is ~/.gemini/GEMINI.md?

Gemini CLI loads context files hierarchically and concatenates them: the global ~/.gemini/GEMINI.md (your personal, cross-project preferences) first, then GEMINI.md walking up from the working directory to the project root, then any GEMINI.md in subdirectories below for component-specific rules. The CLI footer shows how many context files are active, and you can inspect or reload them with /memory show and /memory refresh. The context filename is configurable via contextFileName in settings.

Is GEMINI.md the same as CLAUDE.md or AGENTS.md?

The content is the same; GEMINI.md is just where Gemini CLI looks, CLAUDE.md is where Claude Code looks, and AGENTS.md is the open standard read by 28+ tools. The clean setup is one source of truth — keep AGENTS.md canonical and import it from GEMINI.md with @AGENTS.md, or generate GEMINI.md, CLAUDE.md, .cursor/rules and the rest from one set of rules so they never drift.

GEMINI.md

GEMINI.md is the context (memory) file Gemini CLI and Gemini Code Assist read at session start to learn your project — stack, commands, conventions, what not to do, definition of done. It lives at your repo root, loads hierarchically, supports @imports, and pairs with a global ~/.gemini/GEMINI.md.

Generate your GEMINI.md free →

What is GEMINI.md?

A plain-Markdown file Gemini CLI loads into context automatically when you start working in a repo. Its job is to give the agent the context a new teammate would need. It's the Gemini-native version of the same idea as AGENTS.md and CLAUDE.md — same content, with Gemini-specific extras: hierarchical loading, @path imports, and a global file.

What goes in a GEMINI.md file?

Overview — one line on what the project is.
Stack — languages, framework, database, key libraries.
Commands — build, test, lint, dev, deploy.
Conventions — the decisions and coding style the agent must follow.
Don't — explicit anti-patterns and off-limits areas.
Definition of done — what must be true before a change ships.

GEMINI.md example

# Acme Web

> Senior full-stack engineer. Small, reviewable diffs. Tests with every change.

@docs/architecture.md

## Stack
Next.js 15 (App Router) · TypeScript · Tailwind · Drizzle ORM · Postgres

## Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint && pnpm typecheck`

## Conventions
- Server components by default; "use client" only when needed.
- All DB access through src/db/ (Drizzle) — never raw SQL in routes.

## Don't
- Don't add dependencies without asking.
- Don't commit secrets — use .env.local (see .env.example).

## Definition of done
- Lint + tests pass; new UI works at 375px.

Make one for your project →

Gemini-specific features

Hierarchical context. Gemini CLI concatenates GEMINI.md files in order: the global ~/.gemini/GEMINI.md, then files walking up from your working directory to the project root, then any GEMINI.md in subdirectories below (component-specific). More-specific files layer on top — handy in monorepos.
@ imports. Reference other files instead of pasting them: @docs/architecture.md, @README.md. Keeps GEMINI.md short and the source single.
Global file. ~/.gemini/GEMINI.md holds your personal, cross-project preferences and is read in addition to the project file.
/memory commands. In Gemini CLI, /memory show prints the combined context, /memory refresh reloads it after edits, and the footer shows how many context files are active.
Configurable filename. The context filename defaults to GEMINI.md but can be changed (or set to several names) via contextFileName in your Gemini settings.

Best practices

Keep it lean. ETH Zurich's Evaluating AGENTS.md found dump-everything files lowered task success ~3% and raised cost 20%+, while short curated ones improved success ~4%. Use @imports instead of inlining long docs.
Be specific. "DB access through src/db/" beats "write clean code."
One source of truth. If you also run other agents, keep AGENTS.md canonical and import it (@AGENTS.md) — don't maintain copies that drift.
Check it into git so the team shares the project file; keep personal prefs in ~/.gemini/GEMINI.md.

GEMINI.md vs CLAUDE.md vs AGENTS.md

Same guidance, different readers — AGENTS.md is the open standard (28+ tools), CLAUDE.md is Claude Code's, and GEMINI.md is Gemini CLI's (with hierarchical loading + the global file). The clean setup is one canonical file the rest import or are generated from. Full breakdown: AGENTS.md vs CLAUDE.md →

Generate GEMINI.md (and AGENTS.md, CLAUDE.md, Cursor, Copilot) — free

Fill in your project's rules once and get every file, correctly formatted, with a token-budget warning so they stay lean. No signup.

Open the Agent Memory Compiler →

Keep it in sync with your work

Generated files drift the moment your project changes. In TaskPrio your rules live in one place and your agents pull them over MCP with get_next_task — the memory and the task queue become one source of truth. Edit once; every agent stays current. See the MCP queue →

FAQ

What is GEMINI.md?

Gemini CLI's context (memory) file, auto-loaded at session start — stack, commands, conventions, don't-dos, definition of done. Lives at repo root; loads hierarchically and supports @imports + a global ~/.gemini/GEMINI.md.

What goes in it?

Overview, stack, commands, conventions, don't-dos, definition of done — kept lean; use @imports for long docs.

Is it the same as CLAUDE.md or AGENTS.md?

Same content, different reader. Keep one source: make AGENTS.md canonical and @AGENTS.md from GEMINI.md, or generate them all from one set of rules.

Generate your GEMINI.md → AGENTS.md vs CLAUDE.md →