> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claude-mem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini CLI Setup

> Add persistent memory to Gemini CLI with claude-mem

# Gemini CLI Setup

> **Give Gemini CLI persistent memory across sessions.**

Gemini CLI starts every session from scratch. Claude-mem changes that by capturing observations, decisions, and patterns — then injecting relevant context into each new session.

<Info>
  **How it works:** Claude-mem installs lifecycle hooks into Gemini CLI that capture tool usage, agent responses, and session events. A local worker service extracts semantic observations and injects relevant history at session start.
</Info>

## Prerequisites

* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and configured
* [Node.js](https://nodejs.org/) 18+
* The `~/.gemini` directory must exist (created by Gemini CLI on first run)

## Installation

### Step 1: Install claude-mem

```bash theme={null}
npx claude-mem install
```

The installer will:

1. Auto-detect Gemini CLI (checks for `~/.gemini` directory)
2. Prompt you to select **Gemini CLI** from the IDE picker
3. Install 8 lifecycle hooks into `~/.gemini/settings.json`
4. Inject context configuration into `~/.gemini/GEMINI.md`
5. Start the worker service

### Step 2: Configure an AI provider

Claude-mem needs an AI provider to extract observations from your sessions. Choose one:

<Tabs>
  <Tab title="Gemini API (Free)">
    The simplest option — use Gemini's own API for observation extraction:

    1. Get a free API key from [Google AI Studio](https://aistudio.google.com/apikey)
    2. Add it to your settings:

    ```bash theme={null}
    mkdir -p ~/.claude-mem
    cat > ~/.claude-mem/settings.json << 'EOF'
    {
      "CLAUDE_MEM_PROVIDER": "gemini",
      "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_API_KEY"
    }
    EOF
    ```

    <Tip>
      **Free tier:** 1,500 requests/day with `gemini-2.5-flash-lite`. Enable billing on Google Cloud for 4,000 RPM without charges.
    </Tip>
  </Tab>

  <Tab title="Claude SDK">
    If you have a Claude API key:

    ```bash theme={null}
    mkdir -p ~/.claude-mem
    cat > ~/.claude-mem/settings.json << 'EOF'
    {
      "CLAUDE_MEM_PROVIDER": "claude"
    }
    EOF
    ```

    Set your API key via environment variable:

    ```bash theme={null}
    export ANTHROPIC_API_KEY="your-key"
    ```
  </Tab>

  <Tab title="OpenRouter">
    For access to 100+ models:

    ```bash theme={null}
    mkdir -p ~/.claude-mem
    cat > ~/.claude-mem/settings.json << 'EOF'
    {
      "CLAUDE_MEM_PROVIDER": "openrouter",
      "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_KEY"
    }
    EOF
    ```
  </Tab>
</Tabs>

### Step 3: Verify installation

```bash theme={null}
# Check worker is running
npx claude-mem status

# Check hooks are installed — look for claude-mem entries
cat ~/.gemini/settings.json | grep claude-mem
```

Open [http://localhost:37777](http://localhost:37777) to see the memory viewer.

### Step 4: Start using Gemini CLI

Launch Gemini CLI normally. Claude-mem works in the background:

```bash theme={null}
gemini
```

On session start, you'll see claude-mem context injected with your recent observations and project history.

## What gets captured

Claude-mem registers 8 of Gemini CLI's 11 lifecycle hooks:

| Hook             | Purpose                                     |
| ---------------- | ------------------------------------------- |
| **SessionStart** | Injects memory context into the session     |
| **SessionEnd**   | Marks session complete, triggers summary    |
| **PreCompress**  | Captures session summary before compression |
| **Notification** | Records system events (permissions, etc.)   |
| **BeforeAgent**  | Captures user prompts                       |
| **AfterAgent**   | Records full agent responses                |
| **BeforeTool**   | Logs tool invocations before execution      |
| **AfterTool**    | Captures tool results after execution       |

Three model-level hooks (BeforeModel, AfterModel, BeforeToolSelection) are intentionally skipped — they fire per-LLM-call and are too noisy for memory capture.

## Troubleshooting

### Hooks not firing

1. Verify hooks exist in settings:
   ```bash theme={null}
   cat ~/.gemini/settings.json
   ```
   You should see entries like `"SessionStart"`, `"AfterTool"`, etc. with claude-mem commands.

2. Restart Gemini CLI after installation.

3. Re-run the installer:
   ```bash theme={null}
   npx claude-mem install
   ```

### Worker not running

```bash theme={null}
# Check status
npx claude-mem status

# View logs
npx claude-mem logs

# Restart worker
npx claude-mem restart
```

### No context appearing at session start

1. Ensure the worker is running (check [http://localhost:37777](http://localhost:37777))
2. You need at least one previous session with observations for context to appear
3. Check your AI provider is configured in `~/.claude-mem/settings.json`

### Raw escape codes in output

If you see characters like `[31m` or `[0m` in the session context, your claude-mem version may need updating:

```bash theme={null}
npx claude-mem install
```

This was fixed in v10.6.3+ — the Gemini CLI adapter now strips ANSI color codes automatically.

## Uninstalling

```bash theme={null}
npx claude-mem uninstall
```

This removes hooks from `~/.gemini/settings.json` and cleans up `~/.gemini/GEMINI.md`.

## Next Steps

* [Gemini Provider](/usage/gemini-provider) — Configure the Gemini AI provider for observation extraction
* [Configuration](/configuration) — All settings options
* [Search Tools](/usage/search-tools) — Search your memory from within sessions
* [Troubleshooting](/troubleshooting) — Common issues and solutions