Gemini CLI Setup

One-command setup with system prompt injection for Google’s Gemini CLI

Prerequisite: Install the engram binary first via Homebrew or binary download.

One-Command Setup (Recommended)

engram setup gemini-cli

This command does three things:

1. Registers mcpServers.engram in ~/.gemini/settings.json (Windows: %APPDATA%\gemini\settings.json)
2. Writes ~/.gemini/system.md with the Engram Memory Protocol
3. Ensures ~/.gemini/.env contains GEMINI_SYSTEM_MD=1 so Gemini loads the system prompt

1. Install engram binary

   brew install gentleman-programming/tap/engram
   
2. Run setup command

   engram setup gemini-cli
   

   Output:

   ✓ Registered MCP server in ~/.gemini/settings.json
   ✓ Wrote Memory Protocol to ~/.gemini/system.md
   ✓ Added GEMINI_SYSTEM_MD=1 to ~/.gemini/.env
   
3. Verify installation

   gemini "list memory tools"
   

   The agent should list mem_save, mem_search, etc.

What Gets Configured

MCP Server Registration

Adds to ~/.gemini/settings.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Memory Protocol System Prompt

Writes the full Memory Protocol to ~/.gemini/system.md:

## Engram Persistent Memory — Protocol

You have access to Engram, a persistent memory system that survives across sessions and compactions.

### WHEN TO SAVE (mandatory — not optional)

Call `mem_save` IMMEDIATELY after any of these:
- Bug fix completed
- Architecture or design decision made
- Non-obvious discovery about the codebase
- Configuration change or environment setup
- Pattern established (naming, structure, convention)
- User preference or constraint learned

...

Environment Variable

Adds to ~/.gemini/.env:

GEMINI_SYSTEM_MD=1

This tells Gemini CLI to load system.md on every session start.

Manual Setup (Alternative)

If you prefer to configure manually:

Add MCP Server

Edit ~/.gemini/settings.json (Windows: %APPDATA%\gemini\settings.json):

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Or via CLI:

gemini mcp add engram engram mcp

Add Memory Protocol

Copy the Memory Protocol from DOCS.md to ~/.gemini/system.md.

Enable System Prompt

Add to ~/.gemini/.env:

GEMINI_SYSTEM_MD=1

Compaction Recovery

The Memory Protocol in system.md includes compaction recovery instructions:

### AFTER COMPACTION

If you see a message about compaction or context reset:
1. IMMEDIATELY call `mem_session_summary` with the compacted summary
2. Then call `mem_context` to recover additional context
3. Only THEN continue working

This ensures the agent persists work before compaction and recovers state after.

Platform-Specific Notes

Windows

engram setup gemini-cli writes to:

• MCP config: %APPDATA%\gemini\settings.json
• System prompt: %APPDATA%\gemini\system.md
• Environment: %APPDATA%\gemini\.env

macOS / Linux

engram setup gemini-cli writes to:

• MCP config: ~/.gemini/settings.json
• System prompt: ~/.gemini/system.md
• Environment: ~/.gemini/.env

Memory Protocol Behavior

With the Memory Protocol in system.md, the agent:

• Saves proactively after bugfixes, decisions, discoveries, patterns
• Searches reactively when you say “remember” or “what did we do”
• Searches proactively when starting work that might overlap past sessions
• Closes sessions with mem_session_summary before saying “done”
• Recovers state after compaction with mem_context

No manual prompting needed — the protocol is always active.

Troubleshooting

MCP tools not available

Check MCP server registration:

# macOS/Linux
cat ~/.gemini/settings.json | grep engram

# Windows
type %APPDATA%\gemini\settings.json | findstr engram

Agent doesn’t use memory

Check that system.md exists and GEMINI_SYSTEM_MD=1 is set:

# macOS/Linux
ls ~/.gemini/system.md
cat ~/.gemini/.env | grep GEMINI_SYSTEM_MD

# Windows
dir %APPDATA%\gemini\system.md
type %APPDATA%\gemini\.env | findstr GEMINI_SYSTEM_MD

Server not running

Manually start the server:

engram serve

Gemini CLI will connect via stdio, but the HTTP API is useful for debugging.

Next Steps

• Learn about the Memory Protocol
• Explore MCP Tools
• Set up Git Sync for team memory sharing