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

# Gemini CLI

> MCP wiring through settings.json plus a GEMINI.md guideline

<Note>
  Google sunsets Gemini CLI on 2026-06-18 in favor of Antigravity. If you are migrating, see [Antigravity](/docs/integrations/antigravity); its `agy` CLI reads the same `~/.gemini/GEMINI.md` guideline this adapter writes.
</Note>

## Setup

<Steps>
  <Step title="Start agentmemory">
    ```bash theme={"dark"}
    npx @agentmemory/agentmemory
    ```
  </Step>

  <Step title="Wire MCP">
    ```bash theme={"dark"}
    npx @agentmemory/agentmemory connect gemini-cli
    ```

    The adapter detects `~/.gemini/`, backs up `settings.json`, merges the entry, and verifies it after writing. Gemini's own CLI form works too: `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user`.
  </Step>

  <Step title="Restart Gemini CLI">
    Start a new `gemini` session and run `/mcp` to confirm the server and its tools are listed.
  </Step>

  <Step title="Verify">
    Ask the agent to save a fact with `memory_save`, then:

    ```bash theme={"dark"}
    curl -X POST http://localhost:3111/agentmemory/smart-search \
      -H 'Content-Type: application/json' \
      -d '{"query": "the fact you saved"}'
    ```
  </Step>
</Steps>

## What connect writes

```json ~/.gemini/settings.json theme={"dark"}
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}",
        "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET:-}",
        "AGENTMEMORY_TOOLS": "${AGENTMEMORY_TOOLS:-all}"
      }
    }
  }
}
```

## Capture model

Gemini CLI is MCP-only: no lifecycle hooks fire, so the agent must call the tools itself. `connect` therefore upserts a marked memory-usage block into the global `~/.gemini/GEMINI.md`, which Gemini injects into every session. The block tells the agent to recall at task start and save durable facts. Re-running connect updates only the marked block; the rest of your GEMINI.md is untouched. Skip with `--no-guidelines`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="/mcp does not list agentmemory">
    Gemini reads `settings.json` at startup. Exit and restart the CLI. If the entry is present but the server fails to spawn, run `npx -y @agentmemory/mcp` manually to surface the error.
  </Accordion>
</AccordionGroup>

Adapter source: `src/cli/connect/gemini-cli.ts` (shared JSON adapter) and `src/cli/connect/guidelines.ts`.