Memory MCP With Gemini CLI

Gemini CLI ships its own built-in memory concept — save_memory, writing to a GEMINI.md file — which means adding the standalone memory MCP server puts two different persistence mechanisms in play at once. This topic covers the actual MCP setup, how to keep it from colliding with Gemini CLI's native memory, and a team-knowledge-base pattern that plays to the graph model's strengths.

Installing and Connecting Memory MCP to Gemini CLI

Gemini CLI reads MCP server config from settings.json, either project-scoped (.gemini/settings.json) or user-scoped (~/.gemini/settings.json), under an mcpServers key — the same field name Claude Code and Cursor use, which makes porting configs between those three noticeably easier than porting to or from OpenCode.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/dat/agent-memory/english-grammar-platform.json"
      }
    }
  }
}

Recent Gemini CLI versions also support adding servers via a subcommand rather than hand-editing JSON:

gemini mcp add memory \
  -e MEMORY_FILE_PATH=/Users/dat/agent-memory/english-grammar-platform.json \
  -- npx -y @modelcontextprotocol/server-memory

Verify inside a session:

gemini
> /mcp
memory - Ready (9 tools)

If it reports 0 tools instead of 9, the usual cause is a stale npx cache resolving an old, cached package version that predates one of the tool additions — clear it and retry:

npx clear-npx-cache 2>/dev/null || rm -rf ~/.npm/_npx
npx -y @modelcontextprotocol/server-memory --version

Tips
- .gemini/settings.json uses mcpServers, matching Claude Code and Cursor's config shape — reuse those snippets directly rather than rewriting them.
- Run /mcp inside a session and check the tool count is 9, not just "connected" — a stale cached package can connect successfully while missing newer tools.
- Project-scoped .gemini/settings.json beats user-scoped for anything you want a teammate to inherit automatically when they clone the repo.

Capturing Decisions and Constraints as Retrievable Memories

Here's the collision to plan around explicitly: Gemini CLI's native save_memory tool writes free-text facts into GEMINI.md under a ## Gemini Added Memories section, read in full every session — functionally the same category of tool as CLAUDE.md. If you also connect the memory MCP server, you now have two systems an agent might reach for when told "remember this," and Gemini itself has no built-in rule for which one to prefer.

Resolve it with an explicit instruction, either in a system prompt or your GEMINI.md itself:

## Memory Policy

- Use the built-in `save_memory` tool ONLY for durable, universally-relevant
  facts (e.g. "always run tests with `uv run pytest`, never bare `pytest`").
- Use the `memory` MCP server (create_entities / add_observations) for
  task-conditional facts: architectural decisions, constraints, incidents,
  and anything that should be searchable rather than always-loaded.

With that split established, a typical capture prompt looks like this:

Prompt: We just decided to cap the async job queue's retry count at 3
with exponential backoff, because unlimited retries on a malformed
fixture file were spinning the worker pool. Store this as a memory
entity — not save_memory, use the memory MCP tool — entityType
"decision", name "queue-retry-policy".

{
  "type": "entity",
  "name": "queue-retry-policy",
  "entityType": "decision",
  "observations": [
    "Retry count capped at 3, exponential backoff",
    "Root cause: unlimited retries on a malformed fixture file spun the worker pool indefinitely",
    "Applies to the async fixture conversion queue introduced 2026-08"
  ]
}

Being this explicit ("not save_memory, use the memory MCP tool") in the early sessions of a project is worth the extra words — once the ## Memory Policy note is established and the agent has followed it correctly a few times, you can drop back to shorter prompts and trust the policy note to keep doing the disambiguating work.

Tips
- Write an explicit memory policy distinguishing save_memory/GEMINI.md from the MCP graph — Gemini CLI won't infer the split on its own.
- Be explicit in prompts about which mechanism to use during the first several sessions, until the policy note is reliably followed without restating it.
- Don't let the same fact get written to both systems — pick one per fact based on whether it's universal (GEMINI.md) or conditional (memory MCP).

Practical Example: Building a Team Knowledge Base an Agent Can Query

The knowledge-graph model earns its complexity most clearly when the memory isn't just "what one developer's agent learned" but a deliberately built reference multiple people's Gemini CLI sessions query. Take onboarding: instead of a wiki page a new hire reads once and half-remembers, seed the graph with entities a Gemini CLI session can query on demand, mid-task, exactly when relevant.

Seeding prompt (run once, by a senior dev):

  Build a team knowledge base in memory. Create these entities:

  1. entityType "component", name "topic-fixture-pipeline":
     "Converts markdown files under content/fixtures/{category}_category/
      into HTML stored in body_en/body_vi fields via
      content/fixtures/convert_topic_bodies.py"

  2. entityType "convention", name "modeltranslation-fields":
     "Base fields (title, body, excerpt, meta_title, meta_description)
      are always set to empty string; only {field}_en and {field}_vi
      are populated, per django-modeltranslation convention"

  3. entityType "component", name "maestro-test-suite":
     "Requires adb pm clear before auth-sensitive flows due to
      SecureStore / clearState issue — see feedback_maestro_securestore.md"

  Add relations: topic-fixture-pipeline -> modeltranslation-fields,
  relationType "follows_convention".

A new team member's first Gemini CLI session, working on a fixture-related task, gets this without anyone walking them through it live:

New hire's prompt: I need to add a new topic body. What's the process?

→ search_nodes("topic")
→ finds "topic-fixture-pipeline" and, via the relation, surfaces
  "modeltranslation-fields" as related context

Agent: You'll edit the markdown files under content/fixtures/{category}_category/
then run convert_topic_bodies.py. Note the convention: base title/body/excerpt
fields stay empty strings — only _en and _vi suffixed fields get populated.

This is a genuinely different use case from the personal-memory pattern in earlier topics — it's less "the agent remembers what we did" and more "the agent has read the onboarding doc and can answer questions about it," except the "doc" is queryable and cross-referenced instead of a page someone has to remember to open. The trade-off: someone still has to seed and maintain it deliberately. It doesn't build itself from ambient team activity, and if left unmaintained after a refactor, it becomes a knowledge base full of confidently wrong answers — worse than no knowledge base, because it looks authoritative.

Tips
- A seeded, team-wide knowledge graph beats a wiki page for on-demand queries during real tasks, but only while someone owns keeping it current.
- Use relations (follows_convention, depends_on) between onboarding-relevant entities so one search surfaces connected context automatically.
- Schedule a periodic review of team knowledge-base entities after major refactors — stale entries here are actively misleading, not just unhelpful.

Comparing Memory MCP Behavior Between Gemini CLI and Claude Code

Functionally, the memory server behaves identically under both clients — it's the same package, same tools, same JSON file format, and neither client changes the server's behavior. The differences are all on the client side, in how naturally each tool reaches for memory and what else competes with it:

That last row is the practically important one. Claude Code's CLAUDE.md is something the agent reads, not something it decides to write to mid-conversation the way save_memory is an active tool call Gemini CLI's agent can choose to invoke. That makes the "which memory mechanism did the agent just use" question sharper in Gemini CLI — worth checking explicitly the first few times you ask it to remember something, by inspecting either GEMINI.md's diff or the memory JSON file's diff, until you're confident the policy note from the earlier section is being followed.

Tips
- The memory server's behavior itself doesn't vary by client — differences you observe are client-side memory-mechanism competition, not server bugs.
- In Gemini CLI specifically, check which file actually changed (GEMINI.md vs the memory JSON) after a "remember this" instruction, until you trust the policy split is holding.
- gemini mcp add and claude mcp add differ enough in maturity and flag support that hand-editing the JSON config directly is the more portable habit to build across both tools.

Tips

Tips
- Gemini CLI's mcpServers config shape matches Claude Code and Cursor — reuse those config snippets with only the MEMORY_FILE_PATH value changed.
- Write an explicit memory policy separating save_memory/GEMINI.md (universal facts) from the memory MCP graph (conditional, searchable facts) — Gemini CLI won't split this on its own.
- A deliberately seeded team knowledge graph is a strong Gemini CLI use case, but treat it as a maintained asset, not a self-updating one.
- Verify which memory mechanism actually fired after a "remember this" prompt until the policy is reliably followed.