Use GEMINI.md context files to give Gemini persistent project knowledge, and master session saving and checkpointing for complex multi-session tasks.
GEMINI.md is a Markdown file you place in your project root (or any directory) that Gemini CLI automatically reads at the start of every session. It's the equivalent of Claude Code's CLAUDE.md — a way to give Gemini durable, project-specific knowledge without repeating it in every prompt.
# Project: StoreFront API
## Architecture Overview
REST API built with Fastify + TypeScript, deployed on Cloud Run.
PostgreSQL via Drizzle ORM. Redis for caching and sessions.
## Development Commands
- `yarn dev` — start dev server with hot reload (port 3001)
- `yarn test` — run Vitest unit tests
- `yarn test:e2e` — run Playwright E2E tests against staging
- `yarn db:migrate` — run pending Drizzle migrations
- `yarn lint` — ESLint + Prettier check
## Code Conventions
- All route handlers in `src/routes/` — one file per resource
- Validation with Zod at the boundary; no runtime checks deeper in the stack
- Database access only through `src/db/` — never raw SQL in routes
- Use `pino` for structured logging; log level from `LOG_LEVEL` env var
## Environment Variables
Required: DATABASE_URL, REDIS_URL, SESSION_SECRET, STRIPE_SECRET_KEY
Optional: LOG_LEVEL (default: info), PORT (default: 3001)
## Do Not
- Do not commit `.env` files
- Do not use `any` in TypeScript
- Do not bypass Zod validation for "convenience"When you run gemini in this directory, it reads GEMINI.md and loads it into the context window before your first message. All conversations in this session start with that knowledge.
GEMINI.md files cascade through the directory hierarchy. If you have:
project/
GEMINI.md ← loaded for any session in project/
src/
GEMINI.md ← also loaded when working in src/
src/api/
GEMINI.md ← also loaded when working in src/api/
Multiple GEMINI.md files are merged, with deeper ones taking precedence for conflicting instructions. Use subdirectory GEMINI.md files for area-specific context (e.g., API-specific conventions in src/api/GEMINI.md).
During a session, you can add notes to GEMINI.md without leaving the REPL:
This appends the note to a ## Gemini Added Memory section in GEMINI.md, making it durable across sessions.
Complex tasks — migrating a database schema, refactoring a module, debugging a subtle race condition — can take hours and span multiple conversations. Gemini CLI's session save/load feature lets you pause and resume without losing context.
At any point in a conversation:
/chat save db-migration-postgres-15
Gemini saves the full conversation history, tool call results, and loaded file contents to ~/.gemini/sessions/db-migration-postgres-15.json.
In a new terminal session or the next day:
gemini
/chat load db-migration-postgres-15
The conversation resumes exactly where it left off, with all context intact.
/chat list
Saved sessions:
auth-refactor 34 messages 2 days ago
db-migration 67 messages 5 days ago
setup-redis-cache 18 messages 1 week ago
Sessions are stored locally in ~/.gemini/sessions/. You can delete old ones manually or they persist indefinitely.
You can define custom slash commands in GEMINI.md under a ## Commands section:
## Commands
/review: Review the currently staged git changes for correctness and style.
Run `git diff --cached` first, then analyze the diff.
/release-notes: Generate release notes from the git log since the last tag.
Run `git log $(git describe --tags --abbrev=0)..HEAD --oneline` and format
the output as a user-facing changelog.
/security-audit: Check all route handlers for missing authentication middleware.
Read each file in src/routes/ and flag any that don't call requireAuth().In the REPL, typing /review runs that command definition automatically.
Custom commands defined in GEMINI.md are session-scoped. They're loaded when gemini starts in that directory and are available throughout the session.
GEMINI.md gives every Gemini session a shared, persistent understanding of your project — no repeated setup. Session saving lets you pause and resume complex multi-day tasks without losing context. Custom commands turn repetitive prompts into single-word shortcuts. The next module covers MCP servers and GitHub Actions integration for Gemini CLI.