Gemini CLI Persistent Memory: A Practical MCP Setup

Gemini CLI persistent memory works best when you separate instructions from durable knowledge. Put stable operating rules in GEMINI.md; put evolving decisions, runbooks, and discoveries in a memory system your agent can search and update. That boundary prevents a useful instruction file from becoming a sprawling project diary.

For durable engineering knowledge, your agent's memory should be files you can read, edit, diff, and self-host—not only embeddings hidden behind a retrieval API. Meshnote exposes a plain-markdown wiki to Gemini CLI through MCP, so the same memory can serve other MCP-compatible agents instead of belonging to one chat product.

What the leading Gemini memory pages cover

The pages ranking for this query explain the available mechanisms, but not how to operate them as one system. MCP Market's Gemini Memory listing describes a local MCP extension that stores conversational context in SQLite and supports recall and management. A prominent Reddit result presents Clauder, which stores context locally and auto-loads it at session start, with an installer that edits ~/.gemini/settings.json. Both focus on adding persistence quickly.

The most comprehensive guide, from Data Lakehouse Hub, covers Gemini CLI's hierarchy of global, project, and subdirectory GEMINI.md files; explicit /memory entries; direct @file context; MCP transports; shell-derived context; and context-window hygiene. Google's current documentation, updated May 13, 2026, similarly recommends focused GEMINI.md files and provides /memory show and /memory reload for inspection and refresh.

The missing piece is an acceptance-tested workflow: what belongs in each layer, how to connect an authenticated remote markdown memory server, and how to prove a fact survives in a fresh process without turning every conversation into memory. That is the walkthrough below.

Use three context layers, not one giant memory file

Layer	Store here	Do not store here
`GEMINI.md`	Build commands, code style, repository boundaries, safety rules	Meeting notes, transient failures, long decision histories
Gemini session/context	The current task, files under inspection, command output	Facts needed next week or by another agent
Shared MCP memory	Architecture decisions, runbooks, source-backed research, recurring failure fixes	Secrets, raw transcripts, facts already obvious from source code

This structure is more useful than simply asking Gemini to “remember everything.” Instructions are eagerly loaded because they should constrain every task. Wiki memory is retrieved when relevant because a detailed incident note or product decision need not consume tokens during unrelated work. For a deeper treatment of server-side retrieval, see the MCP memory server guide; for another client implementation, compare the Claude Code persistent memory setup.

Working setup: connect Gemini CLI to Meshnote over MCP

First create a Meshnote project—for example, acme-api—and generate an API key in your account. Keys use the mnk_ prefix. Treat the key like a password and never commit it. Then add the hosted Streamable HTTP endpoint with Gemini CLI's documented MCP command:

gemini mcp add --transport http \
  --header "Authorization: Bearer mnk_REPLACE_WITH_YOUR_KEY" \
  meshnote https://meshnote.io/mcp

gemini mcp list

By default, gemini mcp add writes project-scoped configuration to .gemini/settings.json. Add --scope user before meshnote if you deliberately want the server available in every repository. Project scope is safer when different repositories should use different credentials or memory spaces.

Start Gemini CLI in the repository and run /mcp. You should see the Meshnote tool surface, including project and page operations. Then give Gemini this bounded instruction:

Use the Meshnote MCP tools with project "acme-api".
Before architecture or deployment work, search the wiki for relevant decisions.
Write only durable, verified knowledge: decisions with rationale, reusable runbooks,
and fixes likely to recur. Never store credentials or raw chat transcripts.
When a fact changes, update the existing page instead of creating a duplicate.

Place that policy in the repository's GEMINI.md if you want it applied every session. It tells the agent when to use memory without forcing a search before every trivial response.

Run a two-session persistence test

A successful MCP connection does not prove that your workflow recalls the right information. Use a deliberately non-obvious, non-secret decision and test it across fresh processes.

In session A, ask: Write a Meshnote page named "Webhook retry policy" for project "acme-api". Record that retries use capped exponential backoff, max six attempts, and the rationale: protect downstream services during incidents. Then read the page back and quote the saved policy.
Exit Gemini CLI completely. Do not continue the same conversation.
Start session B and ask: Search project "acme-api" memory. How many webhook delivery attempts are allowed, and why? Cite the page you used.
Open the corresponding markdown page in Meshnote and verify the answer, title, and rationale directly.

This tests four different failure modes: authenticated transport, write success, cross-session retrieval, and human auditability. If recall fails, inspect gemini mcp list and /mcp; if Gemini's instructions seem wrong, use /memory show to inspect the concatenated GEMINI.md context. Google's docs say edits made during a running session require /memory reload.

How the main memory approaches differ

Approach	Strong fit	Trade-off
Native Gemini memory and `GEMINI.md`	Personal preferences and repository instructions with no extra service	Not a shared, structured knowledge base across different agent products
Mem0	Application memory APIs, extraction, semantic retrieval, broad framework integrations	Optimized around programmatic retrieval rather than a human-curated markdown wiki
Zep / Graphiti	Temporal facts and relationship-heavy knowledge where “when was this true?” matters	A graph architecture brings more operational concepts than files alone
Letta	Stateful agents that actively manage memory as part of their runtime	Best when adopting its agent model, not merely attaching shared docs to existing clients
ChatGPT or Claude native memory	Convenient personal continuity inside the vendor's product	Less portable across clients and less suitable as a repository-owned team record
Meshnote markdown over MCP	Readable, versionable, agent-agnostic project knowledge with human curation	Requires editorial discipline; semantic or temporal systems can outperform manual pages on fuzzy or time-sensitive recall

These options are complementary. A customer-facing agent may need Mem0-style extraction or Zep's temporal graph, while engineering decisions live in readable pages. The important design choice is to match the store to the information and its review requirements. The self-hosted agent memory comparison goes deeper on deployment and ownership trade-offs.

A maintenance contract that keeps memory useful

Search before writing. Extend an existing decision or runbook instead of creating near-duplicates.
Store conclusions, not transcripts. Include the decision, rationale, date, scope, and links to source evidence.
Make staleness visible. Mark replaced guidance as superseded and link to the current page.
Keep secrets out. Memory is documentation, not a credential vault.
Review after incidents and releases. Delete obsolete facts and promote genuinely reusable lessons.

Persistent memory is valuable only when a developer can challenge and correct it. If readable shared memory fits your Gemini workflow, Start syncing — $8/mo. Teams that need to operate it in their own environment can choose Self-hosted for teams from $10/seat/month (minimum five seats).