MemoryRouter
All posts

Gemini CLI Memory: The Part It Is Told Never to Save

John Rood··6 min read

The most useful sentence about Gemini CLI memory is in its system prompt. In v0.66.0, the paragraph that tells the model how to remember things ends by telling it what to leave out: "Never save transient session state, summaries of code changes, bug fixes, or task-specific findings." The stated reason is that those files "are loaded into every session and must stay lean."

Read that once and you know what a fresh Gemini CLI session will not have. It will know your conventions. It will not know why the export test was flaky on Tuesday.

How Gemini CLI remembers in 2026

There is no memory database. When you say "remember this," the model edits Markdown with its ordinary file tools. The prompt says so directly: there is no save_memory tool. Older tutorials still tell you to run /memory add, and that subcommand is gone. A May reply on issue #26563 put the change plainly: the model now uses edit or write_file to remember things. The /memory command in the current source has four subcommands, show, list, reload (with refresh as an alias), and inbox.

The model routes each fact to exactly one of four places:

  • ./GEMINI.md for team conventions and architecture rules, committed with the repo.
  • A subdirectory GEMINI.md for rules that apply to one part of the tree.
  • A private MEMORY.md index for this project, kept on your machine and out of the repo, with longer notes in sibling files it points to.
  • ~/.gemini/GEMINI.md for personal preferences that follow you into every project.

If a fact could fit more than one tier, the prompt tells the model to ask you which. It also forbids writing the same fact into two tiers.

Then there is Auto Memory, which is experimental and off by default. Once you enable it, a background pass reads sessions that have sat idle for at least three hours and have ten or more user messages, then drafts memory patches and skills into an inbox. Nothing applies until you approve it in /memory inbox, and it cannot touch a project GEMINI.md.

Why the exclusion is right

Those files go into the prompt in every session, whether the task needs them or not. Append every bug fix and finding to GEMINI.md and you pay for last month's debugging on every request, while your actual instructions get harder for the model to find. Google drew the line in the right place. A file that loads unconditionally should hold rules and preferences, and nothing that only matters when a specific question comes up.

Where the findings go instead

By default, nowhere durable.

During a session the findings sit in context, and context gets summarized. /compress replaces the conversation with a summary, and the CLI also compresses on its own once usage crosses model.compressionThreshold, which defaults to half the context. After that, the cause of the bug survives only if the summary happened to keep it. Quit and start fresh, and the model sees your memory files, which the prompt kept clean of exactly that material.

So the work that cost you an afternoon is the work Gemini CLI is designed to forget: why the retry wrapper fired twice, or which library you dropped because it pinned an old protobuf. You want both back the next time the same file breaks, and neither belongs in a file loaded on every turn.

The material needs a store that is searched when a question touches it and stays out of the prompt when it does not.

Add a vault Gemini CLI can search

MemoryRouter plugs into Gemini CLI over MCP. Merge this into the mcpServers object in ~/.gemini/settings.json:

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

Open the CLI inside a folder you have marked as trusted, then run /mcp auth memoryrouter. A browser opens, you sign in, and you pick the vault this connection writes to. The flow needs a local browser, so do it on your own machine rather than over SSH. Those two scopes cover search and storage and nothing else, so no tool on this connection can remove anything from the vault.

This is an MCP connection, and Gemini CLI has no hook package for MemoryRouter today, so searching and storing happen only when the model picks those tools. A finding the model never stores is a finding the vault never sees. One instruction in your global GEMINI.md closes most of that gap, and it belongs there because it is a standing workflow rule:

## MemoryRouter
- Before working on a file or bug, search MemoryRouter for earlier findings about it.
- After you find a root cause or abandon an approach, store one memory in MemoryRouter with the cause and the reason.

By default every MCP call waits for your approval. Leave that on for the first week. Watching each store go by teaches you quickly what the model thinks is worth keeping.

The vault is not tied to Gemini CLI. Codex, Claude Code, Claude and ChatGPT can all connect to the same one, so a root cause stored from a Gemini CLI session is searchable from Codex tomorrow. The Gemini CLI setup guide covers troubleshooting and the full tool list, and the Gemini CLI memory overview is the short version of where native memory ends.

One route to skip: redirecting GOOGLE_GEMINI_BASE_URL to MemoryRouter is unsupported. MCP is the path.

Prove the split

Run this once with a made-up finding, so nothing real goes in.

  1. Ask Gemini CLI to store in MemoryRouter: "The invoice export test fails because the fixture clock is UTC; adding sleeps was rejected." Approve the call.
  2. Run /compress, then quit.
  3. Open a fresh session and run /memory show. The finding is not in the loaded context, which is the rule doing its job.
  4. Ask why the invoice export test was failing. Check that the search_memories result carries the UTC answer before you trust the reply.

Step 3 is the part worth seeing. Your memory files stayed lean, and the finding came back anyway, from a store that was searched instead of loaded.

Start a 14-day trial and connect Gemini CLI before your next debugging session. It is $20 a month after the trial.

All posts