Context Management - Gemini CLI

Context files (GEMINI.md) are a powerful way to provide project-specific instructions, coding standards, and persistent context to Gemini CLI. Instead of repeating instructions in every prompt, define them once in context files.

What Are Context Files?

Context files are Markdown files (default name: GEMINI.md) that contain instructions, preferences, and information about your project. The CLI automatically loads these files and includes their content with every prompt sent to the model.

Think of GEMINI.md files as persistent system prompts that guide the AI’s behavior for your specific project or workspace.

Why Use Context Files?

Consistency

Ensure the AI follows your coding standards and conventions every time

Efficiency

No need to repeat instructions in every prompt

Team Alignment

Share project conventions with all team members using Gemini CLI

Context Awareness

The AI understands your project structure and preferences automatically

Context Hierarchy

Gemini CLI loads context files from multiple locations in a hierarchical manner. All found files are concatenated and sent to the model with every prompt.

Global Context

Location: ~/.gemini/GEMINI.mdScope: Provides default instructions for all your projectsUse for:

Personal coding preferences
General AI behavior guidelines
Universal tool preferences

Example:

# Global Instructions

- Always write clear, concise commit messages
- Prefer functional programming patterns
- Use descriptive variable names

Workspace Context

Location: GEMINI.md files in workspace directories and their parentsScope: Project-level instructions for active workspacesUse for:

Project-specific conventions
Technology stack preferences
Architecture guidelines

Example:

# Project: E-commerce Platform

- Use TypeScript for all new code
- Follow REST API naming conventions
- Run tests before committing

Just-in-Time Context

Location: Automatically discovered when tools access files/directoriesScope: Component or module-specific instructionsUse for:

Module-specific patterns
Component guidelines
Localized conventions

Example:

# Components Directory

- All components must have PropTypes
- Use CSS Modules for styling
- Export component and types separately

The CLI footer displays the number of loaded context files, giving you a visual indicator of active context.

Creating Context Files

Global Context File

Create a global context file for all your projects:

mkdir -p ~/.gemini
touch ~/.gemini/GEMINI.md

Example global context:

~/.gemini/GEMINI.md

# My Global Gemini CLI Instructions

## General Preferences

- Always explain your reasoning
- Ask for clarification when requirements are ambiguous
- Suggest best practices and alternatives

## Code Style

- Use 2 spaces for indentation
- Maximum line length: 100 characters
- Always use strict equality (=== and !==)

## Git Workflow

- Write commit messages in present tense
- Include ticket numbers in commit messages
- Always run tests before committing

Project Context File

Create a project-level context file at your project root:

cd /path/to/your/project
touch GEMINI.md

Example project context:

GEMINI.md

# Project: TypeScript Library

## Project Overview

This is a TypeScript library for data validation with zero dependencies.

## Technology Stack

- TypeScript 5.x
- Node.js 18+
- Jest for testing
- ESLint + Prettier

## Coding Standards

### TypeScript

- Enable strict mode in tsconfig.json
- Prefix interface names with `I` (e.g., `IUserService`)
- Use `type` for union types, `interface` for object shapes

### Documentation

- All public functions must have JSDoc comments
- Include @example annotations for complex functions
- Keep comments up-to-date with code changes

### Testing

- Minimum 80% code coverage
- Use descriptive test names: "should [expected behavior] when [condition]"
- Group related tests with describe blocks

## File Organization

src/ validators/ # Validation functions types/ # TypeScript type definitions
utils/ # Helper utilities index.ts # Main exports

## Before Committing

Run `npm test` to ensure all tests pass
Run `npm run lint` to check for style issues
Update CHANGELOG.md if needed

Component-Specific Context

Create context files in subdirectories for component-specific instructions:

src/components/GEMINI.md

# React Components

## Component Structure

- Use functional components with hooks
- One component per file
- Co-locate styles with components

## Props

- Define PropTypes for all components
- Use TypeScript interfaces for complex props
- Provide default props where appropriate

## Naming

- PascalCase for component names
- camelCase for prop names
- Suffix event handlers with "Handler" (e.g., `onClickHandler`)

## Styling

- Use CSS Modules (.module.css)
- Follow BEM naming convention
- Mobile-first responsive design

Managing Context

Use the /memory command to interact with context files:

View Current Context

See all loaded context:

/memory show

This displays the full concatenated content of all GEMINI.md files currently loaded.

Refresh Context

Reload all context files:

/memory refresh

Useful after editing context files to ensure changes are picked up.

Add to Global Context

Append text to your global GEMINI.md:

/memory add Always use semantic versioning for releases

This adds the text to ~/.gemini/GEMINI.md immediately.

Use /memory add during sessions to capture important conventions or preferences you discover.

Modular Context with Imports

Break large GEMINI.md files into smaller, manageable pieces using the @file.md import syntax.

Basic Import

GEMINI.md

# Main Project Context

General project information here.

@./docs/coding-style.md
@./docs/testing-guidelines.md
@./docs/deployment-process.md

Import Paths

Supports both relative and absolute paths:

# Relative imports
@./components/component-guidelines.md
@../shared/common-patterns.md

# Absolute imports
@/docs/architecture.md

Example Modular Structure

project-root/
  GEMINI.md                    # Main context file
  docs/
    context/
      coding-style.md           # Code style guide
      testing.md                # Testing conventions
      architecture.md           # System architecture
      api-conventions.md        # API design patterns

Main GEMINI.md:

# Project Context

This project is a REST API for managing user data.

## Detailed Guidelines

@./docs/context/coding-style.md
@./docs/context/testing.md
@./docs/context/architecture.md
@./docs/context/api-conventions.md

Memory Import Processor

Learn more about the import system and advanced features

Customizing Context File Names

While GEMINI.md is the default, you can configure custom filenames in your settings.json.

~/.gemini/settings.json

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

The CLI will search for all specified filenames in the hierarchy order.

Best Practices

Start small and iterate

Begin with basic instructions and add more as you discover useful patterns:

Start with critical conventions
Add more details as you work
Remove instructions that aren’t helpful
Refine based on actual usage

Be specific and actionable

✅ Good: “Use async/await instead of Promise.then() for asynchronous operations”❌ Vague: “Write good code”Specific instructions help the model make the right decisions.

Organize by topic

Use clear sections and headings:

# Project Context

## Code Style
...

## Testing
...

## Deployment
...

Include examples

Examples make instructions clearer:

## Commit Messages

Format: `type(scope): description`

Examples:
- `feat(auth): add OAuth login`
- `fix(api): handle null response`
- `docs(readme): update installation steps`

Version control your context

Commit GEMINI.md files to your repository:

Share conventions with team
Track changes over time
Maintain consistency across environments

Use imports for large projects

Break down context into focused modules:

@./frontend-guidelines.md
@./backend-guidelines.md
@./database-schema.md

Easier to maintain and update specific sections.

Context File Examples

Backend API Project

GEMINI.md

# Backend API Project

## Stack

- Node.js + Express
- PostgreSQL
- Redis for caching
- JWT authentication

## API Design

- Use RESTful conventions
- Versioned endpoints: `/api/v1/...`
- Return consistent error format:
  ```json
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid email format",
      "field": "email"
    }
  }

Database

Use migrations for schema changes
Never commit raw SQL in application code
Use parameterized queries to prevent SQL injection

Security

Validate all input
Sanitize output
Use rate limiting on public endpoints
Never log sensitive data (passwords, tokens)

### Frontend React Project

```markdown GEMINI.md
# React Frontend Project

## Technology

- React 18 + TypeScript
- Vite for build tooling
- React Query for data fetching
- TailwindCSS for styling

## Component Guidelines

- Functional components only
- Custom hooks for shared logic
- Props destructuring in function signature
- Use React.FC type for components

## State Management

- Local state with useState for component-specific data
- React Query for server state
- Context API for global app state (theme, auth)

## File Structure

components/ Button/ Button.tsx Button.test.tsx Button.module.css index.ts

## Styling

- Use Tailwind utility classes
- Custom CSS modules for complex components
- Follow mobile-first approach

Data Science Project

GEMINI.md

# Data Science Project

## Environment

- Python 3.11
- Jupyter notebooks for exploration
- Poetry for dependency management

## Code Style

- Follow PEP 8
- Type hints for all functions
- Docstrings in NumPy style

## Data Processing

- Use pandas for tabular data
- NumPy for numerical operations
- Keep raw data immutable
- Document data transformations

## Notebooks

- Clear markdown explanations
- Visualizations for key insights
- Export final code to .py modules

## Model Development

- Track experiments with MLflow
- Version datasets and models
- Document hyperparameters
- Include model evaluation metrics

Troubleshooting

Context not loading

Check:

File is named GEMINI.md (or your configured name)
File is in a recognized location (global, workspace, or accessed directory)
Use /memory show to verify loaded content
Try /memory refresh to reload

Too much context

Symptoms: Token limits reached, slow responsesSolutions:

Break large files into focused modules with imports
Remove overly verbose instructions
Use component-specific context files instead of one large file
Focus on essential conventions only

Imports not working

Check:

Import paths are correct
Imported files exist
Use relative (./) or absolute (/) paths correctly
No circular imports

AI not following context

Possible causes:

Instructions too vague
Conflicting instructions in different files
Context overridden by specific user prompts

Solutions:

Make instructions more specific and actionable
Review all loaded context with /memory show
Reinforce important instructions in your prompt

Next Steps

How It Works

Understand how context is loaded and processed

Memory Tool

Save persistent memories during sessions

Memory Import Processor

Advanced import syntax and features

Custom Commands

Create reusable command shortcuts

Get Started

Core Concepts

CLI Usage

Tools & Extensions

Advanced

Resources

​What Are Context Files?

​Why Use Context Files?

Consistency

Efficiency

Team Alignment

Context Awareness

​Context Hierarchy

​Creating Context Files

​Global Context File

​Project Context File

​Component-Specific Context

​Managing Context

​View Current Context

​Refresh Context

​Add to Global Context

​Modular Context with Imports

​Basic Import

​Import Paths

​Example Modular Structure

Memory Import Processor

​Customizing Context File Names

​Best Practices

​Context File Examples

​Backend API Project

​Database

​Security

​Data Science Project

​Troubleshooting

​Next Steps

How It Works

Memory Tool

Memory Import Processor

Custom Commands

Build docs developers (and LLMs) love

What Are Context Files?

Why Use Context Files?

Context Hierarchy

Creating Context Files

Global Context File

Project Context File

Component-Specific Context

Managing Context

View Current Context

Refresh Context

Add to Global Context

Modular Context with Imports

Basic Import

Import Paths

Example Modular Structure

Customizing Context File Names

Best Practices

Context File Examples

Backend API Project

Database

Security

Data Science Project

Troubleshooting

Next Steps