What the Model Sees: Context, Memory, and History
Gemini CLI does not make decisions from the latest sentence alone. Its context system combines project guidance, extension material, information discovered while tools move through a codebase, and the history of earlier turns. This chapter explains how those layers enter the model's working request and how Gemini CLI manages them when a session becomes long or tool output becomes large. The practical result is a way to judge not only what the agent can do, but what instructions and evidence are shaping its next action.
That question becomes concrete in a repository with several parts. A general project guide might apply everywhere, while a service directory might contain instructions that matter only when the agent enters that part of the tree. A test command may then produce hundreds of lines, followed by an edit and a second test. Gemini CLI has to decide which guidance to load, which history to send, and how much output to preserve without allowing the working request to grow without limit.
The context hierarchy changes with the path
The simplest way to think about context is as a set of layers with different scopes. A global GEMINI.md can provide defaults for a user's projects. Workspace and parent-directory files can describe the repository or a shared project area. When a tool accesses a file or directory, Gemini CLI can look for more specific context in that location and its ancestors up to a trusted root. This just-in-time, or JIT, context means that a model can receive guidance relevant to the component it is actually examining rather than loading every instruction in the repository at startup.
The distinction is useful because scope and timing solve different problems. Broad instructions are appropriate for conventions that should apply across a project: how to run tests, how to format code, or what a deployment directory represents. Narrow instructions are appropriate for a component with unusual constraints. If every component's rules were placed in the global context, the model would have to filter a large amount of material on every request. If no local rules were available, it could apply a correct convention from one part of the repository to a different part where it does not belong.
Gemini CLI's documented hierarchy also includes extension memory and user-project memory. Context files can be modularized by importing other Markdown files, and the filename can be customized when a project uses names such as AGENTS.md or CONTEXT.md. These features change how instructions are organized, not the basic responsibility of the context layer: supply relevant guidance before the model chooses its next action.
The implementation keeps these sources distinct while loading them. It discovers global, extension, project, and user-project memory, removes duplicate file identities, reads the selected files, and categorizes their contents. When a workspace is trusted, MCP-provided instructions can be added to the project memory. When a path is accessed, the memory manager can discover new subdirectory context and return it to the caller. The result is a context that can grow as the agent learns which part of the workspace it is operating in.
The trust check in this lifecycle is important. Project context is not neutral background; it can influence how the model interprets a task and which tools it considers. Gemini CLI's folder-trust system is designed to inspect project configuration before granting that project full influence. Its discovery phase can identify custom commands, MCP servers, hooks, skills, agents, settings, security warnings, and discovery errors. In an untrusted workspace, the documented restrictions include ignoring project settings and .env files, disabling tool auto-acceptance, avoiding MCP connections, and suppressing automatic local memory loading. The core memory manager also returns no project or JIT context when the folder is untrusted.
This is a deeper boundary than “the model may not edit yet.” An untrusted project may contain instructions that tell the agent how to behave, a settings file that adds integrations, or an environment file that changes the process it launches. Loading those inputs before a person evaluates the workspace would give the project a chance to shape the very agent deciding whether to trust it. Trust therefore governs both execution reach and informational reach.
The system prompt is assembled from more than memory files. The prompt provider includes the active approval mode, available tool names, skill metadata, subagent definitions, planning state, sandbox state, Git context, and operational guidance. It can also reinject the active topic and adjust the prompt for the current model family. That composition explains why two otherwise similar requests can behave differently: a different approval mode changes the available workflow, a newly activated skill changes the procedures in context, and a tool-accessed directory can add local guidance.
This does not mean that every instruction in context is authoritative. A GEMINI.md file is guidance for the model, not a sandbox and not proof that the model will obey it. Context can explain a safe way to work, but policy and execution controls still decide whether a requested command or edit is allowed. Conversely, a strong sandbox cannot repair a misleading instruction that causes the model to investigate the wrong files. Context and authorization solve different problems and must be evaluated together.
There is also a practical information-quality issue. A context file may be accurate at the repository root but too broad for a nested component. An imported document may be useful but outdated. MCP instructions may describe an external system whose behavior the local repository cannot verify. The hierarchy makes these materials available; it does not establish their truth. Readers should treat context as an input to inspect, not as an invisible source of certainty.
Imagine asking Gemini CLI to repair a failing test in a repository that contains both a web application and a deployment service. The root guidance may explain the general test command, while the deployment directory may say that its configuration is generated and must not be edited directly. When the agent reads a file in that directory, JIT discovery can add the local rule at the moment it becomes relevant. The model's next tool request is then shaped by both the broad convention and the narrower constraint. If the workspace is untrusted, however, the local project guidance is not simply treated as “probably right”; the relevant project memory is withheld along with other project-supplied configuration. This example shows why context scope is an engineering decision. Too little context leaves the model guessing. Too much context creates noise and makes conflicting instructions harder to detect. Trust determines whether project instructions enter the system at all, while scope determines how much influence they should have once they are allowed in.
History is both record and working set
Context from files is only one side of the model's request. The other side is the conversation accumulated through the agent loop. Gemini CLI records sessions automatically. The stored record can include prompts, model responses, tool executions, token-usage statistics, and thought summaries when available. Sessions are associated with a project, so changing the project changes the history that the CLI can resume.
Durable history serves recovery and accountability. If a developer interrupts an investigation after several tool calls, resuming can restore the sequence rather than starting with a vague reminder. Named checkpoints can mark a decision point, and a Git worktree can give parallel sessions separate copies of a codebase. A record of the earlier tool outputs also gives the model and the person a way to reconstruct why a change was made.
But the history used for the next model request is not necessarily identical to the full record. Gemini CLI distinguishes comprehensive history from curated history. Comprehensive history preserves the interaction, including entries that may be invalid, empty, or unsuitable for another API request. Curated history selects the usable turns that can be sent back to the model. Tool responses are recorded with stable identifiers so they can be associated with the calls that produced them, while invalid turns can be filtered or repaired before another request.
This separation resolves a tension between auditability and protocol validity. A complete record is useful when investigating what happened. A model request must satisfy the current model's expectations about roles, parts, function calls, and response order. Sending every raw event back without checking it could make a later request invalid. Sending only a cleaned summary would make recovery and diagnosis harder. Keeping both views lets Gemini CLI preserve the record while preparing a usable working set.
The working set still has a finite budget. A long debugging session may contain repeated logs, large search results, intermediate thoughts, and several versions of the same file. The context manager represents conversation history in a graph, estimates the tokens represented by its nodes, and applies management when the retained budget is exceeded. Depending on the situation, it can compress history, distill a tool result, truncate output, or protect selected nodes from being discarded. The aim is not simply to delete old text; it is to keep a request coherent enough for the next decision.
Tool output is a clear example of the trade-off. A test suite can emit a long log even when only a few lines explain the failure. Passing the entire log into every subsequent request consumes context and can bury the relevant signal. Gemini CLI can distill output when context management is active. In other cases, it can save oversized shell or MCP output to a temporary file and give the model a bounded representation. The next response can therefore remain within a workable budget, but a conclusion based on a bounded representation should be checked when the omitted material could change the diagnosis.
Compression and truncation also differ from a normal user-facing summary. They occur inside a running protocol with tool calls, responses, and model-specific validity constraints. The chat implementation tracks the history length and prompt-token estimate, closes an unanswered tool-response turn before recording a new user message, and can retry after an invalid or empty response. These measures protect the next request from structural errors, but they do not make every transformation reversible. An operator should be cautious when a high-stakes decision depends on details that have been compressed or abbreviated.
Session limits make the boundary visible. The public session guide documents a default retention period and settings for maximum age, maximum count, and minimum retention, as well as a maximum number of turns for an individual session. When a turn limit is reached, interactive work stops with an informational message while non-interactive work exits with an error. These are operational controls against unbounded context and cost, not evidence that a task has reached a correct conclusion.
The same records create privacy obligations. A session can contain a user's original request, sensitive file contents, commands, tool arguments, external-service responses, and the model's interpretation of them. Retaining history makes recovery possible, but it also preserves a detailed account of the work. Telemetry can add another copy or view of the interaction, depending on configuration. A team deciding how long to keep sessions should therefore consider not only disk usage and convenience, but also who may access the record and whether prompts or tool output should be exported.
The most reliable way to interpret a long Gemini CLI session is to ask what kind of information is present at each stage. Persistent context supplies instructions. JIT context supplies local relevance. History supplies prior observations and decisions. Compression and truncation shape the amount of that history the model can use. Policy and sandbox controls still determine what the model may do. No single layer substitutes for the others.
That distinction gives the context system a precise role in the larger agent. Gemini CLI does not merely remember everything or load every file. It selects, adds, filters, manages, and records information as the task develops. The benefit is a model that can work across a real project without carrying the entire project into every request. The cost is that operators must understand scope, trust, retention, and information loss well enough to know when the working context is reliable and when it needs inspection.