GC-101 · Module 1

GEMINI.md Deep Dive

4 min read

GEMINI.md is the project memory file for Gemini CLI — the equivalent of Claude Code's CLAUDE.md. It tells Gemini about your project: architecture, conventions, build commands, and any rules the AI should follow. Without it, Gemini starts every session from scratch. With it, Gemini understands your project's context from the first prompt.

GEMINI.md files load hierarchically from three locations. First, the global file at ~/.gemini/GEMINI.md applies to every project. Second, a project-level GEMINI.md in your repository root applies to that specific project. Third, subdirectory GEMINI.md files apply when working within that directory. Each level can override or extend the one above it. This hierarchy mirrors how .gitignore scoping works.

~/.gemini/GEMINI.md          # Global — applies everywhere
./GEMINI.md                  # Project — applies to this repo
./src/GEMINI.md              # Subdirectory — applies within src/
./src/components/GEMINI.md   # Deeper subdirectory — more specific overrides

The /init command auto-generates a GEMINI.md by scanning your codebase. It identifies your tech stack, project structure, and common patterns, then produces a starter file. This is the fastest way to bootstrap project context. Run /init when you first start using Gemini CLI on an existing project, then refine the generated file manually.

# Auto-generate a GEMINI.md from your codebase
/init

# Add a runtime memory note without editing the file
/memory add "Always use TypeScript strict mode in this project"
/memory add "Run npm test after every code change"

The /memory add command lets you inject context at runtime without manually editing GEMINI.md. These notes persist for the session and can be saved to the file. This is useful for capturing decisions as you make them — "we decided to use Zustand instead of Redux" or "the API endpoint changed to /v2/users."

Do This

  • Run /init on every new project to bootstrap GEMINI.md
  • Keep GEMINI.md focused — architecture, build commands, key conventions
  • Use /memory add for session-specific context that may not warrant a permanent entry
  • Check in your project GEMINI.md to version control so the whole team benefits

Avoid This

  • Write GEMINI.md from scratch when /init gives you 80% of what you need
  • Dump your entire API documentation into GEMINI.md — use @ references instead
  • Keep GEMINI.md in .gitignore — it's a shared team resource, not personal config
  • Ignore subdirectory GEMINI.md files when different modules have different conventions