[FEATURE] : Tunable Context Retention / MCP Tool-Result Eviction

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement

Claude Code retains MCP tool calls and their results in the session context, and over the course of a development session these results can consume a significant portion of the available context window. I have verified this by examining Claude Code session log files and have also observed high session/context usage.

I have built a set of local MCP servers that effectively provide a persistent knowledge base for my workspace, including targeted code search, file editing, file hashes, and Tree-sitter validation. However, this issue is not limited to locally hosted MCP servers. MCP integrations with systems such as Jira, GitHub, GitLab, documentation systems, and other external services can also return information that is easily and cheaply retrieved again when needed.

As more MCP servers are connected to a Claude Code environment, the problem will become increasingly significant. Each MCP call may provide useful information at the time it is made, but retaining the result indefinitely in the conversational context effectively treats every retrieved piece of external data as permanent working memory.

This creates an important distinction between persistent external knowledge and active conversational context that Claude Code currently does not allow the user to control.

For example, an issue retrieved from Jira may be useful for the next several turns, but there is little reason to consume context indefinitely with the complete issue description, comments, and metadata when Claude can simply query Jira again if that information becomes relevant later. In many cases, re-querying the external MCP is preferable or even necessary to check for changes, resulting in significant portions of the same information being repeated within the context window.

The problem is therefore not necessarily that individual MCP results are excessively large. The problem is cumulative retention. As MCP becomes a standard way to connect Claude Code to development environments, the number of tool calls and the amount of retrievable external information will continue to increase, making indefinite retention of MCP results increasingly expensive in context usage.

Proposed Solution

Proposed Solution

Provide a user-configurable context retention/eviction policy that mechanically removes or compresses older tool results from the active context before the next request is sent to the model.

For example:

MCP tool results:
    retain: 10 turns

After a result has exceeded its configured retention period, Claude Code could replace it with a small marker or reference rather than continuing to include the complete result in the model context.

Ideally, retention policies could be applied selectively by MCP server or tool, for example:

mcp__search__*    → retain 5 turns
mcp__edit__*      → retain 10 turns
mcp__github__*    → retain 20 turns
mcp__jira__*      → retain 20 turns

An advanced configuration could optionally support patterns or regular expressions to identify tool results that are safe to evict.

The critical characteristic is that this should be mechanical rather than LLM-driven. The user should be able to explicitly identify classes of information that are inexpensive to retrieve again. The original session history could remain available for auditing and debugging, but evicted results would no longer be included in the context sent to the model.

A useful implementation could provide several levels of retention:

1. Recent results — retain normally.
2. Older results — replace with a compact reference or marker.
3. Very old results — remove entirely from active context.
4. Session history — retain the complete original transcript outside the active model context.

This would effectively allow Claude Code to treat the context window as working memory, while MCP servers provide persistent external memory.

Alternative Solutions

Alternative Solutions

I currently use several techniques to manage context growth:

1. Minimize MCP result sets. Where possible, I design and configure MCP calls to return only the information needed for the immediate task rather than large result sets. This reduces individual tool-result size, but does not address cumulative retention over a long session.

1. Use sub-agents extensively. I delegate tasks to sub-agents and explicitly direct them to return a short summary rather than their complete working context. This keeps the parent session relatively small, but introduces additional complexity and is not applicable to every interaction.

1. Use /compact frequently. I typically run /compact every 10–20 turns. This helps control context growth, but requires manual intervention and relies on semantic summarization rather than a deterministic policy for information that I know can be safely discarded.

1. Request a summary before starting a new session. When a session becomes large, I ask Claude to produce a summary that can be used to establish the necessary context in a new session. This works, but requires an additional interaction and transfers the responsibility for context management to the model.

1. Break larger projects into separate sessions. For substantial work, I often perform research in one session and save the results as a Markdown file. I then start a new session to develop a scaffold-based plan consisting of individual sessions. Each session is subsequently executed from the command line and kept as small as practical. This is effective, but requires significant manual session and workflow management.

These techniques substantially reduce context usage, but they all work around the same underlying limitation: there is no user-configurable mechanism for automatically identifying and removing information from the active context once it has become stale.

The proposed tunable context-retention mechanism would automate part of this workflow, particularly the mechanical removal of older MCP results that can be cheaply retrieved again. It would complement rather than replace the techniques above.

Priority

Medium - Would be very helpful

Feature Category

API and model interactions

Use Case Example

Use Case Example

Consider a long-running feature development task in a Java/Angular application with MCP servers connected to the local codebase, GitHub/GitLab, and issue tracking.

1. I start a Claude Code session by retrieving the Jira issue for the feature. Claude uses the issue description and acceptance criteria to understand the task.

1. Claude uses my local MCP search server to find the relevant Java and Angular code, retrieve symbols, and understand the existing implementation.

1. Claude uses my MCP edit server to make several changes. Each edit returns a small amount of verification information, including the resulting file hash and Tree-sitter syntax validation.

1. During implementation, Claude queries GitHub/GitLab for related issues, commits, or documentation. These results are useful when making the relevant decisions but generally do not need to remain in context indefinitely.

1. The implementation continues for dozens or hundreds of turns. Additional MCP calls retrieve more code, issue information, documentation, and edit results.

1. At this point, much of the context consists of historical MCP results. The information was useful when retrieved, but much of it is now either stale, no longer relevant, or cheaply retrievable again from the MCP server.

1. With a tunable context-retention policy, I could configure MCP results to be retained for, for example, 10–20 turns. Older results could then be mechanically removed from the active context while remaining available through the underlying MCP service or session history.

1. If Claude later needs the Jira issue, source code information, or GitHub data again, it can simply query the appropriate MCP server and obtain the current information.

The important point is that the information does not need to be permanently retained in the model's working context to remain available. MCP provides an external, persistent knowledge source, while the Claude context should primarily contain the information currently needed for the task.

This would allow a long-running development session to remain focused on its current working state without accumulating every piece of external information retrieved during the history of the session.

Additional Context

Additional Context

I have verified the context-growth behavior by examining Claude Code session log files. MCP tool calls and their results represent a significant portion of the accumulated session data in my workflows.

I am not proposing that MCP results be permanently deleted from the session history. The desired behavior is to distinguish between the persistent session record and the active context sent to the model.

The feature should ideally operate before constructing the next request to the model, so evicted results do not consume context tokens. The original session history could remain intact for debugging, auditing, or other purposes.

A simple initial implementation could be based on tool-result age:

mcp tool results:
    retain for N turns

An advanced implementation could allow policies based on MCP server/tool name, such as:

mcp__jira__*      → 20 turns
mcp__github__*    → 20 turns
mcp__search__*    → 10 turns
mcp__edit__*      → 10 turns

Regex or glob-based matching would provide additional flexibility for advanced users.

This feature would be particularly valuable as MCP adoption increases and Claude Code environments connect to an increasing number of external knowledge sources. The more capable and inexpensive MCP retrieval becomes, the less justification there is for permanently retaining every retrieved result in the model's active context.