On this page
Gemini CLI Memory and Context Management Guide
This guide explains Gemini CLI's advanced tiered memory, JIT context alignment, and hierarchical context management features. Even after the tool's June 2026 shutdown for non-enterprise users, these open-source architecture patterns are valuable for any developer building terminal AI agents.
Google spent early 2026 building the most sophisticated context-engineering architecture in any terminal AI agent—then locked out the developers who helped create it. Between February and April, the team merged major PRs implementing tiered memory, JIT context alignment, auto-memory, and project-level scoping, hardening the codebase into something genuinely powerful. On June 18, 2026, Gemini CLI stopped serving requests for every non-enterprise user. The open-source tool that amassed over 100,000 GitHub stars and 6,000 merged community contributions now functions only if you hold an enterprise license. What follows is a practical guide to the memory and context management features that exist in the codebase—features worth understanding whether you’re an enterprise user maintaining workflows or someone evaluating what a terminal agent’s context architecture should look like.
How Hierarchical Memory Loads and Resolves Conflicts
Gemini CLI’s memory system loads context from three layers, each with a distinct scope and priority. Context is loaded hierarchically from Global (~/.gemini/GEMINI.md), Project Root (./GEMINI.md), and Subdirectory (./src/GEMINI.md) files. The global layer applies to every project on your machine. The project root layer applies to the current repository. The subdirectory layer applies only when you’re working inside that specific folder.
What makes this more than a simple overlay is the conflict resolution mechanism. Hierarchical memory renders in the system prompt using XML tags (<global_context>, <extension_context>, <project_context>) with a clear priority rule: project context overrides extension context, which overrides global context. If your global file says “use tabs” but your project root says “use spaces,” the project wins. This matters more than you’d think—most teams have coding standards that contradict personal preferences, and the precedence order prevents silent overrides.
The context.memoryBoundaryMarkers setting controls how far upward the CLI searches for GEMINI.md files. The default is [".git"], meaning discovery stops at the first directory containing a .git folder. You can add other markers or set an empty array to disable parent traversal entirely. For monorepos where you want workspace-level rules to propagate into sub-projects, understanding this boundary is essential.
Tiered Memory and JIT Context Placement
Raw hierarchical loading is necessary but not sufficient for long sessions. The real problem is context bloat: tool results accumulate, the window fills, and the model loses track of what matters. The tiered memory architecture addresses this with two mechanisms. First, stash_context offloads noisy tool results exceeding 2k tokens to a session-level archive. Second, query_archive retrieves specific details from that archive via background model calls. The archive uses a 10-item FIFO eviction policy—older stashed items get dropped as new ones arrive.
The JIT context alignment PR refined where memory actually gets injected into the model’s input. When JIT context is enabled, memory is separated across injection points: Tier 1 (global) goes into the system instruction, Tier 2 (extension + project) goes into the first user message, and Tier 3 (subdirectory) remains in tool output. This isn’t arbitrary. The first user message is inherently protected from compression, masking, and truncation—so Tier 2 memory survives the operations that would normally degrade it in a long conversation.
The practical takeaway: if you’re running sessions that span dozens of tool calls, JIT context keeps your project-level instructions visible while stashing the noise. You’ll find that the model follows your coding standards more consistently in session step 40 than it would without this tiering.
Project-Scoped Memory and Auto Memory
Not everything you want the agent to remember belongs in a file committed to the repository. The save_memory tool now supports a scope parameter that solves this. The save_memory tool’s scope parameter works as follows: "global" writes to ~/.gemini/GEMINI.md (the default, applying everywhere), while "project" writes to ~/.gemini/memory/<project>/GEMINI.md and loads as Tier 1 memory via JIT context. Project-scoped memory is private to your user account and never committed to the repo—useful for local dev environment details like “the test DB is on port 5433” that shouldn’t leak into version control.
Auto Memory takes a different approach to persistence. Auto Memory is an experimental feature that scans past session transcripts for recurring workflows and drafts them as SKILL.md files in a project-local inbox. You review, accept, or discard each extracted skill before it becomes available to future sessions. It complements save_memory—where that tool captures single facts into GEMINI.md, Auto Memory captures multi-step procedures into reusable skills.
The distinction matters for workflow design. If you find yourself repeatedly walking the agent through the same debugging procedure, Auto Memory will eventually notice and offer to codify it. If you just need the agent to remember a port number, save_memory with project scope is the right tool.
Conductor, Plan Mode, and Persistent Context
For teams that need more structure than memory files alone provide, Conductor takes context persistence to its logical conclusion. Conductor is an open-source Gemini CLI extension that stores developer context as version-controlled Markdown files in Git repositories, replacing ephemeral chat sessions. It enforces a three-stage lifecycle—context creation, specification and planning, then implementation—with checkpoints requiring human verification at each phase.
Plan mode complements this by providing a safe exploration layer. Plan mode restricts Gemini CLI to read-only tools for safe exploration, and the ask_user tool enables the agent to pause for clarification. You can ask the agent to “research how to migrate this database” and it will map dependencies without risking eager code changes. Plan mode also supports read-only MCP tools, so the agent can pull context from GitHub issues, database schemas, or documentation without modifying anything.
The combination is powerful for large codebases. Conductor maintains persistent specs and plans across sessions. Plan mode lets the agent explore safely before committing to changes. Together they address the core problem of context-driven development: ensuring the agent understands your architecture before it starts rewriting it. For more on how these workflows hold up after the shutdown, see our guide to Gemini CLI for large codebases.
Quotas, Pricing, and the Access Reality
Here’s where context management meets cost. The architecture is impressive, but who can actually use it?
| Authentication Method | Tier | Max Requests/Day | Model Access |
|---|---|---|---|
| Google account | Individual (free) | 1,000 | Flash + Pro (was free; Pro restricted March 25) |
| Gemini API key | Unpaid | 250 | Flash only |
| Google AI Pro | Paid | 1,500 | Flash + Pro |
| Code Assist Standard | Enterprise | 1,500 | Full |
| Code Assist Enterprise | Enterprise | 2,000 | Full |
Unpaid Gemini API key authentication provides 250 maximum model requests per user per day, limited to Flash models only. That’s barely enough for a single extended refactoring session. The 1,000,000 token context window is generous on paper, but you’ll burn through your daily quota fast if you’re loading large codebases into that window repeatedly.
Starting March 25, 2026, free tier users were restricted to Gemini Flash models; Gemini Pro models became accessible only via paid subscriptions. This happened three months before the full shutdown, effectively degrading the free experience in stages.
For API key users paying as they go, Gemini 3.5 Flash pricing sits at $1.50 per 1M input tokens, $9.00 per 1M output tokens, and $0.15 per 1M tokens per hour for context caching storage. Context caching at $0.15/M tokens/hour matters if you’re repeatedly loading the same large codebase—the cache saves both tokens and latency on subsequent calls. For a deeper cost comparison against alternatives, see our analysis of Gemini CLI vs Codex pricing and tradeoffs.
The Open-Source Sunset Pattern
What I find most revealing about the context management architecture isn’t the technical design—it’s the timeline. The tiered memory PR was filed February 19. JIT context alignment landed March 17. Project-level memory scope merged March 31. Auto Memory shipped April 18. The default for Auto Configure Max Old Space Size was flipped from false to true on April 2 to eliminate out-of-memory issues. The v0.45.0 release on June 3 completed a major refactoring of the context management system. These are not the commits of a project being wound down. They’re the commits of a project being hardened for production—just not the production that the contributors will have access to.
Antigravity CLI is the closed-source replacement for Gemini CLI, which remains open source under Apache 2.0. The open-source code still exists. The architecture decisions—tiered memory, JIT placement, hierarchical rendering, boundary markers—are all there in the commit history. But the tool those decisions hardened is now gated behind enterprise licenses, and the community that built it faces a hard wall.
This is what I call the open-source sunset pattern: community contributions refine a codebase toward production quality, then the steward consolidates that quality into a closed successor. The contributors improved a product they would soon be locked out of. For developers evaluating Google-led open-source projects going forward, this timeline should be required reading. Our post on Gemini CLI’s open-source paywall traces this dynamic in more detail.
What to Do With This Architecture Now
If you’re an enterprise user, the context management features described here are still available and worth configuring. Set up your GEMINI.md hierarchy. Enable JIT context. Use project-scoped memory for local environment details. Install Conductor for structured workflows. Run plan mode before major refactors. The architecture is sound—the access question is separate from the engineering question.
If you’re not an enterprise user, the Gemini CLI codebase remains Apache 2.0. The context management patterns—hierarchical loading with conflict resolution, tiered injection points, stash-and-retrieve for long sessions, project-scoped private memory—are design patterns worth studying and porting. Any terminal agent needs to solve these problems. The Gemini CLI implementation is now the most thoroughly documented example of how to do it.
The question that remains open isn’t technical. It’s whether developers will contribute to Google’s next open-source AI project knowing this is how the last one ended. The commands reference for what still works after June 18 covers the current state for exempt users—but the larger question is who builds the next context architecture, and under what terms.