> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini CLI Setup

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

<Note>
  **Prerequisite**: Install the `engram` binary first via [Homebrew](/installation#homebrew-macos-linux) or [binary download](/installation#download-binary).
</Note>

## One-Command Setup (Recommended)

```bash theme={null}
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

<Steps>
  <Step title="Install engram binary">
    ```bash theme={null}
    brew install gentleman-programming/tap/engram
    ```
  </Step>

  <Step title="Run setup command">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    gemini "list memory tools"
    ```

    The agent should list `mem_save`, `mem_search`, etc.
  </Step>
</Steps>

## What Gets Configured

### MCP Server Registration

Adds to `~/.gemini/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}
```

### Memory Protocol System Prompt

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

```markdown theme={null}
## 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`:

```bash theme={null}
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`):

```json theme={null}
{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}
```

Or via CLI:

```bash theme={null}
gemini mcp add engram engram mcp
```

### Add Memory Protocol

Copy the Memory Protocol from [DOCS.md](https://github.com/Gentleman-Programming/engram/blob/main/DOCS.md#memory-protocol-full-text) to `~/.gemini/system.md`.

### Enable System Prompt

Add to `~/.gemini/.env`:

```bash theme={null}
GEMINI_SYSTEM_MD=1
```

## Compaction Recovery

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

```markdown theme={null}
### 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
engram serve
```

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

## Next Steps

* Learn about the [Memory Protocol](/concepts/memory-protocol)
* Explore [MCP Tools](/features/mcp-tools)
* Set up [Git Sync](/features/git-sync) for team memory sharing