# Cursor Max Files in Context: Limits, Pruning, and Scaling Working Sets

Cursor does not enforce a rigid file-count limit, but prompt context is bounded by model token windows ranging from 20,000 to 200,000 tokens. Active Composer sessions experience reasoning degradation beyond 15 to 20 full files due to attention dilution and automatic context compaction. Managing multi-file projects requires separating indexed repositories from prompt context, using selective mentions, and offloading peripheral documents to external MCP workspaces.

Source: https://fast.io/resources/cursor-max-files-in-context/
Author: [Tom Langridge](https://fast.io/authors/tom-langridge/)
Last reviewed: 2026-10-30

## How Cursor Max Files in Context Impacts Model Attention

Loading twenty source files into a Cursor Composer session does not give the model more context; it crowds out the reasoning budget. When prompt tokens climb toward the ceiling of the active model, Cursor silently compacts chat history, drops earlier file references, or dilutes attention across irrelevant lines of code.

Cursor's max files in context refers to the maximum number of individual files that can be actively included in a Chat or Composer session before hitting model token limits, automatic context compaction, or selective file pruning. Unlike consumer chat interfaces that enforce arbitrary numerical file counters, Cursor places no fixed numeric cap on how many files you can attach with `@file`. Instead, the real boundary is the underlying model token window, which ranges from 20,000 to 200,000 tokens depending on the chosen model tier. On legacy request-based setups, [Cursor documentation](https://cursor.com/docs/models-and-pricing) details how Max Mode extends context window token limits beyond the default limit, billed at the model API rate plus 20 percent.

Every file added to a session is parsed into tokens that compete directly against other prompt elements. The active context window must accommodate:

- The system prompt and internal instructions defined by Cursor
- Tool schemas and execution capabilities available to the agent
- Project rules from `.cursorrules` or `.cursor/rules/`
- Active skill descriptions and instructions
- Connected Model Context Protocol (MCP) server definitions
- Multi-turn conversation transcripts, user instructions, and agent replies
- Terminal outputs, linter errors, and active git diffs
- Raw file contents injected via `@file` or `@folder` mentions

Because every full file attachment permanently consumes token space for the lifetime of that turn, packing multiple large source modules into prompt memory exhausts available headroom within a few turns.

### The 15 to 20 File Reasoning Degradation Threshold

In practice, Composer sessions experience reasoning degradation beyond 15 to 20 actively referenced full files. While a 200,000-token window theoretically holds dozens of modest scripts, real-world codebases carry heavy syntactic density. An average TypeScript, Python, or Go source file containing imports, data interfaces, business logic, and comments runs between 300 and 800 lines, consuming roughly 2,500 to 7,000 tokens. Referencing 20 complete files can easily consume 70,000 to 140,000 tokens in static file content alone.

When file tokens dominate the prompt, transformer models suffer from attention dilution, often called the lost-in-the-middle phenomenon. The model distributes its attention weights across thousands of lines of peripheral code rather than focusing on the specific function requiring modification. The symptoms are familiar: the agent overlooks explicit instructions, introduces regressions in unedited methods, hallucinates non-existent function arguments, or generates incomplete diff blocks.

### Pruning Thresholds and Multi-File Context Rules

File context pruning and automatic compaction begin when active prompt tokens consume the majority of the model context window, typically when attachments and conversation history fill around two-thirds of the available token budget. At this threshold, Cursor initiates background compaction to preserve generation headroom for the model's reply.

To prevent degraded output and context loss, follow three foundational rules when structuring multi-file working sets:

1. Target symbol-level references over entire files. Reference `@filename#symbol` or narrow functions with `@file` rather than broad directory inclusions.
2. Rely on codebase indexing for repository exploration. Allow Cursor to find relevant code snippets via background search rather than manually attaching every potentially related file.
3. Isolate peripheral documentation in external indexed stores. Keep non-code assets, such as architecture RFCs, API contracts, and design specs, in an external searchable workspace connected through MCP rather than injecting them directly into prompt memory.

## Comparing Codebase Indexing and Active Prompt Context

A frequent source of confusion among developers is the distinction between an indexed codebase and actively loaded prompt context. Competitors often blur this distinction, treating repository indexing as if the entire codebase were continuously present in the model's working memory. In reality, they are two separate systems operating at different layers of Cursor's architecture.

Codebase indexing is a background retrieval mechanism. Cursor scans the project repository locally, splits files into semantic chunks, calculates embeddings, and indexes keywords for Instant Grep. Files larger than `1 MB` are skipped automatically during indexing, as are files matched by `.gitignore`, `.cursorignore`, and Cursor's default exclusion list (such as lock files, `.env` files, build caches, and binary assets). Indexed files consume zero tokens in your active prompt context while at rest. They reside on disk and in local vector stores until a query retrieves them.

Active prompt context, by contrast, represents the ephemeral token payload transmitted over the wire to the language model during an inference request. When you explicitly attach a file with `@file auth.service.ts`, Cursor reads the entire file and injects its complete text into the prompt payload. That file now occupies working memory and incurs token consumption on every subsequent turn of the conversation.

The following comparison illustrates how these two systems handle repository data:

| Dimension | Codebase Indexing | Active Prompt Context |
|---|---|---|
| Storage Location | Local disk vector store and grep index | Ephemeral LLM context window memory |
| Token Consumption | 0 prompt tokens at rest | Consumes tokens for every included line |
| File Ingestion Scope | Scans entire repository (skipping >1 MB files) | Restricted to explicitly attached files or tool outputs |
| Retrieval Mechanism | Semantic embedding search and Instant Grep | Direct prompt injection via `@file` or `@folder` |
| Practical Capacity | Hundreds of thousands of lines across thousands of files | Bounded by model window (20k to 200k tokens) |
| Impact on Reasoning | Zero impact on attention distribution | High risk of attention dilution beyond 15-20 files |
| Primary Use Case | Discovery, finding references, pattern matching | Active editing, refactoring, direct code generation |

### The Cost of Indiscriminate Folder Mentions

Using `@folder` to pull an entire directory into Composer is the fastest way to exhaust your prompt budget. When you mention `@src/components/`, Cursor attempts to resolve every source file within that directory tree. If that folder contains a dozen UI components, style definitions, and test suites, prompt consumption immediately surges past 60,000 tokens.

This eager loading leaves little token headroom for the conversation history or the model's generation scratchpad. When working across modular directories, omit the `@folder` tag. Let the agent's internal search tools query the indexed codebase on demand, fetching only the specific interface declarations or component files needed for the task.

### How Agent Search Tools Protect Context Headroom

Cursor Agent employs dedicated search tools to inspect code without flooding the main conversation context. Instead of requiring you to anticipate every dependency, Agent runs regex searches, file globbing, and semantic queries against the index.

When deeper exploration is required, Agent can launch an Explore subagent. The subagent operates inside its own isolated context window running a fast model. It scans dozens of files, evaluates potential matches, and returns only a concise summary of relevant findings to the primary conversation thread. This architecture keeps the main Composer context lean and focused on code execution rather than intermediate search transcripts.

## Why Cursor Drops File Context During Long Sessions

When a conversation accumulates multiple turns or pulls in numerous files, Cursor encounters the hard upper boundary of the model context window. To prevent outright API failure, Cursor applies automatic context compaction. This background mechanism acts as an internal garbage collector for your prompt tokens, balancing session continuity against strict model token ceilings.

Context compaction compresses older conversation turns, past tool outputs, and historical code diffs into a condensed text summary. While compaction prevents the session from terminating abruptly, it alters what the model remembers. When the context manager summarizes earlier turns, specific implementation constraints, intermediate refactoring decisions, and edge-case exceptions are frequently flattened into broad topic overviews. Understanding how this compaction cycle operates helps developers avoid losing critical implementation rules mid-session.

### Why Cursor Appears to Ignore Attached Files

Developers often report that Cursor begins ignoring explicit `@file` references during extended coding sessions. This behavior stems from three primary technical causes:

- **Token Window Saturation:** When total input tokens approach the model ceiling, Cursor's context manager prioritizes the most recent user prompt, immediate system instructions, and active diffs. Earlier attached files are either truncated or dropped from the active prompt payload to stay under token limits.
- **Attention Degradation:** In prompts packed with 15 or more full files, the model's self-attention mechanism spreads across too many tokens. Even if the text of an attached file remains physically present in the payload, the model may fail to attend to relevant functions within it.
- **Ignore File Filtering:** If a file or its parent directory matches patterns in `.cursorignore` or `.gitignore`, Cursor blocks access. The file will not be injected into prompt context even if explicitly referenced with `@file`.

### Monitoring Token Pressure with the Context Breakdown Tray

Cursor provides a visual indicator to help developers track context consumption in real time. The circular context ring located next to the prompt input displays current window usage. When the ring approaches full capacity, compaction is imminent.

Clicking the context ring opens the context breakdown tray, which categorizes active token usage:

- **System Prompt:** Core instructions built into Cursor
- **Tools:** Schema definitions for agent tool execution
- **Rules:** Workspace guidelines from `.cursorrules` or `.cursor/rules/`
- **Skills:** Active skill instructions injected into context
- **MCP:** Tool definitions and schemas from connected MCP servers
- **Summarized Conversation:** Tokens consumed by compressed historical turns
- **Active Conversation:** Uncompressed recent messages, tool outputs, and attached file tokens

Monitoring this tray reveals when attached files consume excessive prompt space, allowing you to prune working sets before reasoning quality degrades.

## Scaling Working Sets Beyond IDE Limits with MCP and Intelligent Workspaces

Software projects frequently rely on large volumes of context that should never live in the IDE prompt. System architecture diagrams, OpenAPI specifications, third-party integration docs, database migration logs, and team runbooks easily total hundreds of thousands of words.

Storing these documents inside the local Git repository bloats the codebase index and tempts developers to attach them directly to Composer, accelerating context exhaustion. Keeping them in local unversioned folders creates isolation issues across distributed engineering teams. Standard cloud storage providers like Google Drive, Dropbox, Box, or OneDrive offer basic desktop file sync, but they were built for human file sharing rather than autonomous agent tool interaction; they lack native agent interfaces and semantic search endpoints.

Fast.io addresses this architectural boundary by providing an intelligent cloud workspace platform for agentic teams. Rather than forcing large reference corpuses into local repository folders or stuffing prompt windows with static text, engineering teams organize documentation, specifications, and project assets in shared Fast.io workspaces.

### Intelligence Mode and On-Demand Retrieval

When Intelligence Mode is enabled on a Fast.io workspace, all uploaded files are automatically indexed for hybrid search, combining full-text keyword matching, semantic embeddings, and metadata-based filtering. The workspace functions as an external intelligence layer for your development team and agents alike.

Instead of attaching an entire 40-page API specification to Cursor using `@file`, the document resides in Fast.io. When Cursor needs to verify an endpoint schema or payload structure, it queries the workspace on demand. The assistant retrieves only the specific, relevant passage required for the immediate task, leaving the remaining 190,000 tokens in Cursor's context window open for reasoning, multi-file diffing, and code generation.

### Connecting Cursor to Fast.io via Streamable HTTP MCP

Cursor connects directly to Fast.io through the Model Context Protocol using the dedicated coding agent endpoint over Streamable HTTP. Because the server is hosted remotely, configuration requires no local runtime dependencies or command wrappers.

To connect Cursor to your Fast.io workspace, add the server definition to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project root):

```json
{
  "mcpServers": {
    "fast-io": {
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}
```

After saving the configuration, Cursor initiates the OAuth 2.0 authorization flow in your browser. A Review Permissions screen allows you to grant Read Only or Read & Write access and select the specific organizations and workspaces Cursor can reach. Setup instructions and connection guides are documented at [Fast.io MCP Documentation](https://mcp.fast.io/docs).

Once connected, Cursor's agent queries workspace assets using native MCP search actions. For teams extracting structured information from incoming documents, such as pulling contract expiration dates or invoice schemas, [Metadata Views](/product/document-data-extraction/) automatically parse documents into queryable tables that agents can inspect via MCP.

### Persistent Substrate for Multi-Agent Engineering

Modern development environments increasingly combine multiple specialized agents: Cursor for IDE editing, Claude Code for CLI refactoring, and headless agents running in CI pipelines. When multiple agents collaborate on a project, storing reference files locally on a single developer's laptop causes fragmentation.

Fast.io provides the shared substrate where agents and human engineers collaborate. Key architectural features include:

- **Per-File Version History:** Every update creates an auditable version checkpoint, allowing developers to review changes or restore prior revisions if an agent makes an erroneous edit.
- **Org-Owned Workspaces:** Workspaces are owned by the organization rather than individual accounts, with role-based permissions managed cleanly at the organization, workspace, and share levels.
- **Detailed Activity Log:** A comprehensive log records every file change, upload, deletion, and permission update made by human teammates and AI agents.
- **Collaborative Notes:** Structured notes kept alongside code specs allow agents to persist architectural decisions and implementation progress without polluting source repositories.
- **Cloud Sync:** Connect external folders from Google Drive, Dropbox, Box, and OneDrive to a workspace, one-way or two-way, on a schedule or on demand.

Creating an account on Fast.io is free, while active project work runs in organizations on paid subscription plans. Monthly plans include a 14-day free trial, which requires a credit card. Paid subscription tiers are Starter at `$9.99/mo` (`3 seats`, `250 GB` storage, `5 workspaces`, and `100,000` monthly credits), Business at `$49.99/mo` (`10 seats`, `5 TB` storage, `50 workspaces`, and `600,000` monthly credits), and Enterprise at `$199.99/mo` (`30 seats` included, `25 TB` storage, `200 workspaces`, and `3,000,000` monthly credits). The [Fast.io Pricing](/pricing/) page and [Storage for Agents](/storage-for-agents/) guide document plan features and limits.

## Five Steps to Manage Multi-File Working Sets in Cursor

Managing complex codebases in Cursor without triggering context degradation requires deliberate working set hygiene. Applying disciplined boundaries to what enters prompt context prevents token saturation while preserving reasoning quality across demanding development tasks.

When working across interconnected services, engineers frequently default to attaching every related module into a single active session. Over the course of a multi-turn conversation, this accumulation degrades attention focus, wastes generation tokens, and triggers unwanted compaction. Instead of treating the prompt window as an open-ended workspace, developers achieve higher code accuracy by establishing strict boundaries between active files, project-wide rules, and external reference documentation. The following five steps provide a practical framework for keeping your Cursor sessions lightweight, accurate, and resilient against token exhaustion.

### 1. Scope File Mentions to Symbols and Line Ranges

Avoid passing entire files when only an interface or function signature is relevant. Use symbol-level mentions by typing `@filename#symbol` in the chat input. If you need Cursor to implement a client that conforms to an interface defined in `types.ts`, mention only `@types.ts#PaymentProvider` rather than loading the complete 2,000-line type definition file. This practice drops token consumption for that reference from thousands of tokens down to a few dozen.

### 2. Maintain an Aggressive .cursorignore File

Cursor automatically respects `.gitignore` rules, but production codebases contain numerous files that Git tracks but AI agents should never inspect. Create a `.cursorignore` file in the root of your project to block non-essential assets from being indexed or read into context:

```text
# build artifacts and caches
dist/
build/
.next/
*.tsbuildinfo

# third-party packages and minified scripts
vendor/
*.min.js
*.bundle.js

# large mock datasets and fixtures
tests/fixtures/large-payload.json
mock-data/
*.sql.dump

# documentation archives handled via mcp
docs/legacy/
specs/archive/
```

Blocking these files prevents accidental prompt injection and accelerates background codebase indexing.

### 3. Reset Composer Threads Between Atomic Edits

Long-running Composer conversations accumulate hidden token debt. Even after you finish editing an authentication module and move on to a database migration, earlier turn transcripts, previous file versions, and stale terminal logs remain in working memory.

Treat Composer threads as ephemeral work units. When a feature step or bug fix is complete and verified, commit the changes and start a fresh Composer session (`Cmd+N` or `Ctrl+N`). A clean session gives the agent the full 200,000-token window to reason about the next edit without carrying outdated context summaries.

### 4. Store Project Conventions in Cursor Rules

Developers often waste prompt tokens by repeatedly instructing Cursor on coding conventions, library preferences, and test patterns in their chat prompts. 

Extract recurring instructions into `.cursor/rules/` files. Cursor loads these rules directly into the system prompt configuration, applying them consistently without requiring manual file attachments or repeated explanations in chat. Keep rules concise and scoped to specific file globs so they activate only when editing matching extensions.

### 5. Offload Reference Knowledge to External MCP Stores

Do not use your local codebase as an archive for broad project documentation. Move technical specifications, architectural guidelines, API schemas, and customer requirements into a Fast.io workspace.

By querying external documentation through the Fast.io MCP endpoint, Cursor pulls only the exact paragraphs needed for the current prompt. This decouples total project knowledge from the IDE context window, allowing your team to expand reference libraries to any size without crowding the model's reasoning space.

## Frequently asked questions

### How many files can Cursor handle in context?

Cursor does not enforce a rigid numeric limit on the number of files you can attach in Chat or Composer. Instead, capacity is governed by the active model's token context window, which ranges from 20,000 to 200,000 tokens depending on the selected model tier. In practice, referencing dozens of full source files causes reasoning degradation and attention dilution, as raw code tokens crowd out the model's reasoning budget.

### Why is Cursor ignoring some of my @file references?

Cursor typically ignores `@file` references when a session approaches token capacity. When the context window fills up, Cursor compresses older turns and drops or truncates earlier file references to stay within model limits. In other cases, files are blocked because they match exclusion patterns in `.cursorignore` or `.gitignore`, or the model suffers from attention dilution across an overloaded prompt.

### How do I prevent Cursor from dropping file context?

To prevent context drops, start fresh Composer threads for each atomic task, use symbol-level mentions (`@filename#symbol`) instead of attaching full files, exclude build artifacts with `.cursorignore`, and monitor the context ring breakdown tray. For large documentation sets, store reference files in an external workspace like Fast.io and query them via MCP on demand.

### What is the difference between codebase indexing and prompt context in Cursor?

Codebase indexing is a background process that creates vector embeddings and local grep indices across your repository on disk, consuming zero prompt tokens while at rest. Active prompt context consists of the ephemeral tokens sent to the LLM on each generation turn, including system instructions, chat history, and files explicitly attached with `@file`.

### Does Cursor have a file size limit for context and indexing?

Cursor automatically skips files larger than `1 MB` during codebase indexing to prevent memory exhaustion and index bloat. While you can technically open larger files in the editor, attempting to attach large data files or unminified scripts into Chat or Composer consumes the model context window and triggers context compaction.

### How do I connect external workspace files to Cursor via MCP?

Add the Fast.io Streamable HTTP endpoint `https://mcp.fast.io/mcp/code` to your `~/.cursor/mcp.json` configuration file under `mcpServers`. Complete the browser OAuth prompt to select your organization and workspace. Cursor can then query indexed files and documentation dynamically through MCP tools without cluttering local context.

## Sources

- [Cursor: Models & Pricing](https://cursor.com/docs/models-and-pricing): Cursor extends context window token limits and model tokens on legacy plans through Max Mode billed at the model API rate plus 20 percent.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.