Gemini CLI Memory Across Sessions

Gemini CLI connects to MemoryRouter through its built-in MCP client. You add the remote server to settings.json, sign in once with OAuth, and the agent gets tools to search and store memories in your MemoryRouter vault. That vault lives outside the session, so what you stored is still there after /compress, after you quit, and in a brand new session.

The same vault is reachable from Claude Code, Codex, ChatGPT, and Claude. A decision you store from Gemini CLI can be recalled in any of them.

This is a remote MCP connection, not a native Gemini CLI plugin or extension. There is no hook package for Gemini CLI today, so recall and capture are model-directed: the agent decides when to call the tools.

How this fits with Gemini CLI's own memory

Gemini CLI already has useful local memory, and MemoryRouter does not replace it:

• GEMINI.md context files. Gemini CLI loads ~/.gemini/GEMINI.md, project GEMINI.md files, and just-in-time context files, then sends them with every prompt. /memory show displays the context that is currently loaded.
• Memory files. When you ask it to remember something, the agent edits Markdown memory files: shared project instructions, a private per-project memory folder, or your global GEMINI.md.
• Auto Memory. An experimental, off-by-default feature that mines past local sessions and proposes memory patches and skills for you to approve.

Those files are instructions on one machine. Keep using them for how you want the agent to work. Use MemoryRouter for the record of the work itself, such as decisions, reasoning, and rejected approaches, when you want it searchable from a fresh session or from another tool.

Prerequisites

• Gemini CLI installed and authenticated (npm install -g @google/gemini-cli).
• A MemoryRouter account and a vault you are allowed to use.
• A local browser. Gemini CLI's OAuth flow opens one and listens on a localhost callback, so it does not work in a headless shell or a plain SSH session.
• A trusted folder. Gemini CLI disables MCP servers, including user-level ones, when the current folder is untrusted.

You do not need a model-provider API key in MemoryRouter for this setup. Gemini CLI keeps using its own model and authentication.

Add the server

Merge this entry into the mcpServers object of your user settings file, ~/.gemini/settings.json. Use .gemini/settings.json in a project instead if you only want memory in that repository.

{
  "mcpServers": {
    "memoryrouter": {
      "httpUrl": "https://mcp.memoryrouter.ai/mcp",
      "oauth": {
        "enabled": true,
        "scopes": ["memories:read", "memories:write"]
      }
    }
  }
}

httpUrl selects Gemini CLI's Streamable HTTP transport. The scopes list asks for recall and storage only. MemoryRouter scopes are independent, so this connection cannot delete memories or run consolidation. Add memories:delete or memories:reflect later only if you want those tools.

Do not paste a Memory Key into headers. The MCP server accepts OAuth access tokens, not mk_ keys.

Authenticate

Start Gemini CLI from a trusted folder and run:

/mcp auth memoryrouter

Your browser opens the MemoryRouter consent screen. Sign in, review the listed permissions, and choose the vault this connection should use. Gemini CLI discovers the authorization server, registers itself, and stores the tokens in ~/.gemini/mcp-oauth-tokens.json, refreshing them when they expire.

Check the connection with /mcp list inside the CLI or gemini mcp list from your shell. The server should show as connected with its tools listed.

One OAuth connection is bound to one vault. To switch vaults, run /mcp auth memoryrouter again and choose a different vault.

Make recall a habit

MCP tools are called when the model decides they are useful. A short instruction in GEMINI.md makes that more consistent. It does not guarantee a tool call on every turn.

## Memory
- At the start of a task, search MemoryRouter for earlier decisions about this project.
- When I say "remember this", store it in MemoryRouter as one concise memory.

By default Gemini CLI asks you to confirm each MCP tool call. You can set "trust": true on the server entry to skip those prompts, but leave it off until you are comfortable with what the tools do.

Cross-session proof

Use a synthetic fact, not source code or secrets.

1. In a Gemini CLI session, ask: "Store this in MemoryRouter: the demo project's release phrase is ORCHID-7419." Approve the store_memory call and check that it succeeded.
2. Quit Gemini CLI, or run /compress, so the fact is no longer in the active context.
3. Start a new session and ask: "Search MemoryRouter for the demo project's release phrase." Do not include the answer.
4. Confirm the search_memories result contains ORCHID-7419. Check the tool result, not only the model's reply.
5. Optional: ask the same question from Claude Code, Codex, or ChatGPT connected to the same vault.

This is a test you run in your own account. Recall is relevance-ranked over the vault, not a dump of every memory on every request.

What the agent can do

With memories:read and memories:write, Gemini CLI can use search_memories, date_search_memories, inspect_memory, memory_status, the search alias, and store_memory. The MCP server reference lists every tool, its inputs, and the scope it requires.

Why not the base URL route

Gemini CLI can send its Gemini API traffic to another host with GOOGLE_GEMINI_BASE_URL. Pointing that at MemoryRouter is not a supported or tested setup. Gemini CLI's client calls Gemini API methods beyond content generation, while MemoryRouter's native Gemini endpoint serves only generateContent and streamGenerateContent. Use the MCP route on this page.

Limitations

• Capture is model-directed. Nothing is stored unless the agent calls store_memory, and nothing is recalled unless it calls a search tool.
• Connecting does not import earlier Gemini CLI sessions or your GEMINI.md files.
• OAuth needs a local browser and a localhost callback. Headless and remote shells are not supported by this flow.
• A shared vault is shared. Use a separate vault and a separate connection when projects or people must stay isolated.

Troubleshooting

To stop using memory, run gemini mcp disable memoryrouter or gemini mcp remove memoryrouter. Removing the server does not delete memories already in the vault. See security and data isolation for deletion.

Next steps

• MCP server reference: tools, scopes, and vaults
• Gemini CLI memory overview
• Coding tools guide
• Gemini CLI MCP documentation
• Create a MemoryRouter account