Claude Code Context, Memory, MCP, and Context7: Fix the Right Layer First

If Claude Code loses track halfway through a task, run /context and reduce the material in that conversation. If a project rule disappears after a restart, check Memory files in /context, then use /memory to edit the right persistent file. If Context7 cannot connect or returns the wrong documentation, inspect the MCP entry and its actual tool result. Adding a memory server is rarely the first repair for any of these symptoms.

The distinction matters: context is what Claude can work with now; persistent instructions and auto memory help future sessions; MCP provides external tools and data. Context7 retrieves library documentation. It does not save your project preferences or restore a lost conversation.

The commands and integration details below follow the official documentation checked on October 6, 2026. In particular, the current Context7 plugin uses browser sign-in and does not read CONTEXT7_API_KEY.

Fast Answer: Which Layer Failed?

Use the map to choose the first check; the command behavior and setup instructions below are the current reference. A connected server, a listed memory location and a model saying “I remember” are three different signals, and none by itself proves the task succeeded.

What /context Proves

/context shows the working conversation's context usage and categories. That includes material loaded at startup and material added while you work: instructions, memory, tools, file reads, conversation history and tool results. Use the actual breakdown rather than assuming every model has the same window size or every MCP server loads all its definitions immediately. Claude Code context-window documentation.

Start with the point where behavior changed. If the session was useful until a tool returned a huge log, fix the size of that output. If it was crowded before the task began, inspect startup instructions and available integrations. If it keeps revisiting abandoned approaches, preserve the current decision and remove that conversational residue.

A practical recovery sequence is:

1. Write a short checkpoint containing the goal, changed files, completed checks, unresolved issue and next action. Keep required constraints beside the task.
2. Compact with a focus on the work you need to continue. For example:

/compact Preserve the failing authentication test, changed files, completed checks, the unchanged public API constraint, and the next debugging step. Drop abandoned storage approaches.

3. Read the resulting summary and correct a missing condition before resuming.
4. Make the next read smaller: one relevant function, one error interval, or one documentation question.
5. If you are starting an unrelated task, save the checkpoint to a file and use /clear; then provide the checkpoint when it is needed again.

The example describes what to preserve, not a guarantee that compaction retains every detail. Root instruction files and unscoped rules are reloaded after compaction; nested or path-scoped instructions reload when the work calls for them. A constraint mentioned only in the conversation may be lost in its summary. A subagent can handle a large side investigation and return a concise finding, but it needs its own task inputs rather than an assumption that it inherited everything you know. Instruction loading after compaction.

Repeated compaction followed immediately by the same enormous read is a sign that you are refilling the window. Request a filtered result instead. For a log, ask for the first relevant error and its nearby lines. For docs, ask for the specific API and version. For a database, ask for a count and a small sample before requesting all rows.

High process memory or a hung CLI is a separate runtime symptom; it is not proof that persistent memory is disabled. Keep that distinction when deciding whether to investigate the process or the conversation.

What Built-In Memory Owns

Persistent instructions tell Claude how to work in your project. Auto memory records selected preferences, feedback and project knowledge learned during work. Neither mechanism is a full transcript, and neither makes behavioral instructions a hard permission boundary. Claude Code memory documentation.

A project rule disappears after restart

First launch from the intended repository and open /context. Look for the expected instruction file under Memory files. Then open /memory to select or edit the relevant file. /memory can show a location that does not exist yet and create it when selected; that location list alone is not evidence that its contents were loaded.

For example, if your requirement is “run the existing authentication tests before changing the login handler,” save that requirement in the project's persistent instructions. Do not rely on a conversational reminder or assume auto memory saves every turn. Start a fresh session in the same project, confirm the file appears in /context, and give Claude a small planning task that requires the rule:

Before changing the login handler, identify the existing authentication
checks this repository requires. Give me the planned validation steps
without editing files.

Check the answer against the saved rule and the repository. Seeing the filename proves loading; seeing the correct plan checks whether the instruction was understood. If the file loads but behavior remains wrong, look for ambiguous or contradictory instructions rather than repeatedly reinstalling memory.

Instruction files found up the directory tree are combined. Moving into a subdirectory can bring additional instructions into play; those files are not a simple “nearest file wins” settings override. Imports organize instructions but still add their contents at startup. Keep enduring rules explicit and move large reference material out of the always-loaded text.

Does Claude Code read AGENTS.md?

Current Claude Code supports direct AGENTS.md loading from version 2.1.277. By default, it uses those files when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the launch directory or its ancestors. User-global and managed instructions do not block that default. If both project formats exist, check Project instructions in /config rather than assuming both load. Some session types have additional limitations. Current AGENTS.md conditions.

The repair is to confirm your version and selected instruction mode, then verify the expected file in /context. A repository's AGENTS.md existing on disk is not sufficient proof. Conversely, older advice that Claude Code never reads AGENTS.md is no longer generally correct.

Auto memory does not retain the fact you expected

Use /memory to check whether auto memory is enabled and open its folder. Verify that the fact was saved and is relevant to this repository. Auto memory is selective: an important instruction you want followed every session belongs in explicit instructions, not in the hope that it will be inferred and saved.

The startup limit is the first 200 lines or 25KB of MEMORY.md, whichever comes first. Detailed topic files are read on demand. This is an auto-memory index limit, not a 200-line loading cap for every CLAUDE.md. Put a short, useful reference in the index and the detail in a topic file when necessary. Auto-memory loading limits.

Worktrees and subdirectories of the same Git repository share auto memory on the same machine. That does not mean memory automatically syncs across machines, and a private instruction file in one worktree may still be absent from another. When continuity breaks, check which repository and file you are using before adding external storage.

What MCP Owns

MCP connects Claude Code to an external service or tool. Inspect it when the integration itself is missing, duplicated, unauthorized or failing. Start in the project where the problem happens:

claude mcp list
claude mcp get context7

Here context7 is an example manual server name. For a plugin, select its entry in /mcp and use the actual registered name if you need CLI details; plugin server names can be scoped. list and get describe the configuration and health, while /mcp provides status, authentication and reconnection controls. Current releases show failure detail in an Issue: field when it is available; that diagnostic detail requires version 2.1.219 or later. MCP management and status.

Read the state before changing anything:

Scopes explain why “it worked in another project” is not enough. Local scope is private to the current project and stored in ~/.claude.json; project scope uses the repository's shared .mcp.json; user scope loads across your projects. These paths describe Claude Code's documented storage; you do not need to publish their contents to troubleshoot.

The same server name in multiple scopes can hide the definition you intended to use. The selected definition is a whole entry, not a merge of one scope's URL and another scope's headers. Confirm the active scope and avoid adding a second Context7 integration just to repair the first. Change the faulty field or reconnect the intended entry before removing and recreating anything.

Tool Search can defer MCP definitions on supported paths. It does not make returned documentation or logs free of context cost. With a custom provider or proxy, support depends on the model and whether that route forwards the required tool references; an environment setting cannot create support on a path that lacks it. For the narrower task of reducing output, use the MCP context budget ledger to distinguish definitions from result load.

When Context7 MCP Install Fails

Choose one integration route and diagnose that route. The setup CLI, hosted plugin and manual MCP configuration have different authentication behavior. Mixing instructions between them is a common way to repair the wrong thing.

Setup CLI: choose CLI or MCP mode

Run the documented setup command in your terminal:

npx ctx7 setup --claude

This route needs an environment capable of running npx. It uses OAuth device login, generates an API key, installs a skill, and lets you choose CLI or MCP mode. The device flow gives you a verification link and code that can be opened on another device, including when setup runs on an SSH host. Context7 setup for Claude Code.

Follow the chosen mode through to a documentation result. If you chose CLI mode, the absence of an MCP entry is not by itself an installation failure. If you chose MCP mode, check the resulting entry in /mcp. The installed skill can trigger on library questions automatically; the phrase use context7 is an explicit request, not a universal prerequisite.

Hosted plugin: sign in through /mcp

Run these as two separate commands inside Claude Code:

/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplace

Restart Claude Code, open /mcp, select Context7 and follow browser sign-in. The hosted plugin provides resolve-library-id and query-docs without requiring local Node.js, npm or npx. It does not read CONTEXT7_API_KEY, so exporting that variable and restarting is not a fix for the plugin's account or usage association. Use the setup or manual route if you specifically need API-key authentication. Context7 plugin and sign-in.

Manual MCP: choose HTTP authentication deliberately

For a private entry in the current project using the documented remote OAuth endpoint:

claude mcp add --scope local --transport http context7 https://mcp.context7.com/mcp/oauth

Then open /mcp and complete authentication. Manual OAuth uses /mcp/oauth; the hosted plugin manages its own integration and documents /mcp. Do not change the plugin's endpoint merely to make it resemble this manual example. Context7 manual authentication.

For a shared project configuration using a Context7 API key, the following is a complete .mcp.json shape. Merge the entry with any existing mcpServers rather than overwriting other servers:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CONTEXT7_API_KEY}"
      }
    }
  }
}

Supply your Context7 key as CONTEXT7_API_KEY in the environment that launches Claude Code; the JSON contains a variable reference, not the secret. Project-scoped entries may need approval. The explicit type: "http" matters: a URL alone is not a complete Claude Code HTTP entry. These headers follow Context7's manual client configuration, and variable expansion follows Claude Code's .mcp.json support.

If authentication fails, check the variable's presence in the launch environment and the header's exact shape, including trailing whitespace. Never paste a real key into a public report. This variable is read because the manual configuration references it; it remains irrelevant to the hosted plugin.

A local stdio integration is a different branch: it launches a process and uses API-key authentication, not the remote OAuth flow. A failed npx spawn therefore calls for checking the executable and arguments; a remote HTTP entry has no local Context7 process to spawn. Keep transport-specific fixes in their own branch.

Verify that the right documentation was actually retrieved

Installation is not the endpoint. Ask a small question tied to the package version in your project:

Use Context7 with /vercel/next.js. For Next.js 15 App Router,
retrieve the documentation for setting and reading cookies in a Server
Action. Show the retrieved version or explain if that version is not
available. Give one minimal example and its documentation source.

The library ID here is a documented Context7 example; the version and task are an illustrative request, not a claim that every indexed version is available. A known ID can skip resolve-library-id. In MCP mode, inspect the query-docs call and returned content. In CLI mode, inspect the corresponding documentation retrieval result. Context7 usage and library IDs.

Confirm three things: the package is correct, the returned version supports the requested answer, and the result addresses the feature you asked about. If the version cannot be established, the answer should say so rather than silently substitute another version. If no retrieval happened, “Context7 is installed” or “I used the latest docs” is not proof. If retrieval worked but the answer is wrong, fix the query or interpretation instead of reinstalling the server.

For a persistent connection failure, capture the actual issue and then use the documented CLI debug options:

claude --debug='mcp,startup' --debug-file ./claude-context7-debug.log

The = form binds the debug category filter; a space-separated filter does not. Keep the log private and share only the relevant redacted excerpt. This uses the current CLI debug reference; it does not depend on an undocumented claude mcp logs context7 recipe or an assumed health-check endpoint.

Smaller Fixes Before External Memory

Choose a skill for a repeatable method, such as a review checklist or release procedure. Choose a subagent for a large side investigation whose raw output does not belong in the main conversation. Choose code search for locating a function. Keep persistent project instructions for requirements the team expects each new session to follow.

These choices can work together. A project instruction can identify the required review procedure, a skill can supply its steps, and an MCP tool can fetch the external issue being reviewed. They do not need to duplicate each other's contents.

When External Memory MCP Is Justified

External memory becomes useful when the required continuity exceeds local project memory: shared recall across a team, retrieval across tools, or records that must be available on several machines. Define what must be saved and how it will be retrieved before choosing a server.

A usable decision includes who can read the records, where they are stored, how updates and deletion work, and whether the server saves raw conversations or selected facts. If all you need is one project convention after restart, fix the instruction file. If you need a reviewed team decision available across separate environments, external storage may fit. Neither case is solved by the number of tools installed.

Fix Matrix and Evidence Packet

Save only enough evidence to distinguish the failing step:

Change one relevant thing and repeat the same small check. For a rule, verify loading and behavior in a fresh session. For Context7, verify a returned documentation result. For context bloat, verify that the next step can proceed without loading the same oversized output again. Stop changing the memory architecture once the existing workflow produces the required result.

FAQ

Is Claude Code context the same as memory?

No. Context is the active working conversation. Persistent instructions and auto memory can load into it, but a conversation's presence in context does not make it durable storage. Context7 documentation results also occupy working context without becoming project memory.

Does /memory show which files were loaded?

Use Memory files in /context to verify loading. /memory manages file locations and auto-memory controls; it can list a file that has not been created. A listed location is therefore not enough. Memory loading and management.

What if Context7 MCP install failed in Claude Code?

Identify whether you used the setup CLI, plugin or manual MCP entry. Check the intended entry and its status, complete that route's authentication, and request a small version-specific documentation result. For the hosted plugin, sign in through /mcp; exporting CONTEXT7_API_KEY does not configure it. Current Context7 integration.

Does Tool Search remove MCP context cost?

No. It can defer tool definitions where supported, but tool names, server instructions and returned results still have costs. If one request overwhelms the session, narrow its output rather than treating discovery settings as an output filter.

Should I install a Claude Code memory MCP?

Use it when you have a defined need for shared or external recall and a suitable storage policy. A missing project rule, a crowded conversation or a failed Context7 connection should first be repaired in its existing mechanism.

What should I do after compaction feels wrong?

Compare the summary with your checkpoint, restore missing task constraints, and reduce the next read. Put enduring instructions in a persistent file. Do not treat a compressed conversation as a complete backup of everything discussed.