Gemini CLI persistent memory: making context survive between sessions

Gemini CLI keeps its persistent memory in plain Markdown files on disk. Context files named GEMINI.md are read when a session starts, and their contents ride along in the request context on every turn after that. Anything you want the agent to know next week has to be written into one of those files.

So “how do I make Gemini CLI remember something” has a literal answer: put it in a GEMINI.md file. You can edit the file in your editor, or run /memory add at the Gemini prompt, which appends the line for you. Which file you pick decides whether the fact applies to one repository or to everything you do on that machine.

Where Gemini CLI looks for context files

The CLI does not read a single file. It concatenates every context file it finds and sends the result as part of your prompt. The order is the global file first, then any GEMINI.md in ancestor directories down to your working directory, then files in directories below it.

Location	Applies to (by convention)	Good for
~/.gemini/GEMINI.md	Every project on this machine	Your preferences, house style, tools you always use
GEMINI.md in the project root or an ancestor directory	The whole repository	Architecture, conventions, build and test commands
GEMINI.md in a subdirectory	Code under that directory	Rules for one service or package

The middle column says “by convention” for a reason. Everything discovered is merged into one block of context for the whole session, so a subdirectory file does not bind the model to the files beneath it. More specific files tend to win because the model reads them last, not because the CLI enforces anything.

The three commands that control what is loaded

These are typed at the Gemini CLI prompt, not in a shell.

# Print the full concatenated context the model is receiving
/memory show

# Append a fact to the global file
/memory add "I prefer short commit messages"

# Reload context files after editing them by hand
/memory refresh

/memory add always writes to the same place: the global file at ~/.gemini/GEMINI.md, under a generated ## Gemini Added Memories heading. It does not append to the project file you happen to be sitting in. A rule that applies to one repository has to be typed into that repository’s own GEMINI.md by hand.

Editing a context file in your editor changes nothing in a session that is already open until /memory refresh reloads it.

Saved chats are not queryable memory

Context files are not the only thing Gemini CLI writes to disk. /chat save <tag> stores the current conversation under a name, /chat resume <tag> brings it back, and /chat list shows what you have saved. With checkpointing turned on, /restore rolls your files back to a snapshot taken before a tool call changed them.

None of that is memory in the sense people mean when they search for it. A saved chat returns only when you name it, and a fresh session starts with no knowledge that it exists. It is a bookmark on one conversation, not a store the agent consults on its own.

What /memory add is good at, and what it is not

/memory add captures something mid-task without making you leave the terminal. The limitations show up once the file has a few dozen lines in it.

Appended facts land in a flat list. There is no structure, no date, no reason attached, and no distinction between a rule the agent must always follow and a decision made once in March. Since the file rides in the context on every turn, its length costs tokens and dilutes the instructions that matter.

There is also no way to query the file. You can read it and you can grep it, but you cannot ask “what did we decide about authentication” and get an answer. On a project running longer than a few weeks, that gap is the real problem.

Split instructions from history

The fix is a discipline, not a tool. Treat GEMINI.md as instructions, not as a log.

Instructions are things that must be true on every turn: use this package manager, run this test command, never edit generated files. They belong in GEMINI.md, kept short and edited rather than appended to. If a rule changes, replace the old line instead of adding a contradicting one below it, because the model will see both.

History is different. Decisions, findings, root causes, and the reasoning behind a choice are things you look up on demand. A plain folder of Markdown files handles them:

docs/decisions/2026-08-14-auth-provider.md
docs/decisions/2026-08-21-queue-vs-cron.md
docs/findings/flaky-test-root-cause.md

GEMINI.md then carries one line pointing the agent at that folder, and the agent opens a decision only when the task touches it.

Context files also support imports. A line like @./docs/conventions.md inside GEMINI.md pulls that file in when the context is built, which keeps a long instruction set modular. It does not solve the history problem, because an imported file is still always-on context and costs the same tokens as inline text. That trade-off is the same across every terminal agent, and it is covered in why AI agents forget everything between sessions.

Keeping the same memory on more than one machine

GEMINI.md lives on the machine you wrote it on. A project file rides along in Git, which solves half the problem. The global file at ~/.gemini/GEMINI.md does not, and neither does anything the agent has learned about you rather than about the code.

The common answer is a dotfiles repository with the global file symlinked into place, and it wins on real ground. It costs nothing, needs no application installed, works on a headless server or in continuous integration, and gets reviewed in pull requests alongside the code it governs. If your memory is project-scoped and already committed, you do not need anything else on this page.

What that route does not give you is a store you can query, prune, or read comfortably outside a text editor. The mechanics are covered in syncing agent instruction files across computers.

Using a notes vault as the memory store

The other option is to keep the history in a notes vault the agent can query. Jotura is a local-first Markdown notes app, built first for one person’s own notes with encryption and sharing, with the agent tooling added later on those foundations. Notes are ordinary .md files in an ordinary folder, and the jotura command-line tool ships with the app.

jotura memory log --kind decision \
  --title "Chose Postgres over SQLite for the API" \
  --body "Needs concurrent writers"

jotura memory recall "database choice"

jotura context "add a background job to the API"

Gemini CLI runs these through its shell tool, and only when something tells it to. That instruction is two lines in GEMINI.md:

Before proposing an approach, run `jotura memory recall "<topic>"`.
When work finishes, log the outcome with `jotura memory log`.

Keeping the instruction files in the vault

An Agents/ folder inside the vault holds your instruction files, and jotura agents sync reconciles it with the locations each tool expects. Your global Gemini instructions go to ~/.gemini/GEMINI.md, with equivalents for Claude Code, Codex, and Copilot. Project-level GEMINI.md files stay in their repositories, where Git already handles them.

The sync runs both ways, pulling system edits back into the vault as well as pushing vault edits outward. Add --dry-run to print the plan without writing. A file changed on both sides is skipped until you pick a side with --prefer vault or --prefer system.

On a new machine, restore the vault, run jotura agents sync, and the instruction files are back where each tool looks for them. Jotura Sync carries the vault between machines end to end encrypted, at 4 pounds per month or 40 pounds per year with no free trial.

The app itself is free on Mac, Windows, Linux, and Android, with no iOS version. Jotura is closed source, with no plugins, no graph view, and no publish-to-web. What the CLI exposes to agents is listed on the agent CLI page.

Frequently asked questions

Does Gemini CLI remember the conversation itself? Only if you save it. /chat save <tag> writes the transcript to disk and /chat resume <tag> brings it back by name. A new session starts without it, so anything you want carried forward automatically has to live in a context file.

Where does /memory add put things? In ~/.gemini/GEMINI.md, under a heading called ## Gemini Added Memories. That file applies to every project on the machine, so repository-specific rules belong in the repository’s own GEMINI.md instead.

Can I rename GEMINI.md? Yes. Set contextFileName in ~/.gemini/settings.json. It accepts a list as well as a single name, which helps if you want more than one filename recognized.

Why is the agent ignoring an instruction that is definitely in my file? Most often the file changed after the session started. Run /memory refresh, then /memory show to confirm the instruction is loaded. The next most common cause is a contradicting line elsewhere in the hierarchy, usually an older appended fact nobody removed.

How big should a context file be? Small enough that you would happily read it in full. If a section is relevant to one task in twenty, it belongs in a note the agent opens on request.

How do I check what my agent has stored about me? Open ~/.gemini/GEMINI.md first and read the ## Gemini Added Memories block that /memory add maintains. Then check the project files, and run /memory show for the concatenated result. There is a fuller walkthrough in auditing what your AI agent remembers.