QWEN.md and AGENTS.md: what Qwen Code loads, in what order, and how to check

Qwen Code reads two instruction-file names by default: QWEN.md first, then AGENTS.md. At v0.26.2 both are loaded when both exist (memory-constants.ts). An instruction file is Markdown Qwen reads from disk at the start of a session and puts in the model's prompt; QWEN.md is Qwen's own name, and AGENTS.md is the shared name other coding agents also read. This is one of the first places a guide written for Gemini CLI will mislead you: Gemini CLI reads GEMINI.md by default and treats AGENTS.md as opt-in, while Qwen Code treats it as a peer default. The Gemini CLI page on AGENTS.md covers that side of the difference.

The loader calls them context files and wraps each in a --- Context from: <path> --- marker. A context file is not chat history, and it is not auto-memory: auto-memory is a separate, model-written store under ~/.qwen/projects/<project>/memory/.

The short answer:

• context.fileName replaces the list. Setting it to ["AGENTS.md"] drops QWEN.md; it does not add a name to the defaults.
• Discovery is upward only. Qwen checks the global folder and then walks from your working directory to the nearest .git root. It does not scan down into packages/.
• The answer is version-specific. Run qwen --version first. This page describes v0.26.2, released on 27 October 2026.

Checked against Qwen Code's documentation and its v0.26.2 source on 27 October 2026.

Status, 27 October 2026: the memory documentation mentions AGENTS.md only in passing, and never gives the default list or the replacement rule. The settings reference describes "the configured context file" in the singular. The source is the complete answer here.

What loads at startup#

Qwen Code builds one chain from several places. They are not all QWEN.md files, and they do not all arrive at the same moment.

A repository here means the nearest ancestor with a .git directory or a .git file; Qwen accepts both, which matters for worktrees (a second checkout sharing one repository) and submodules (a nested repository) (projectRoot.ts).

The documentation says the upward walk goes "up to either the project root (identified by a .git folder) or your home directory" (settings reference). That is a simplification: the code stops at the .git root, and the no-repository boundary is not exactly your home directory (memoryDiscovery.ts). The practical rule is to keep the file inside the repository and at or above the directory where you run qwen.

The order is built name by name, not directory by directory#

This is the part most summaries miss. Qwen does not collect every file at the repository root, then every file in a subdirectory. It loops over the configured names first, and walks the directory chain once per name.

Take this tree:

repo/                      # .git here
  QWEN.md                  # repo-wide rules
  AGENTS.md                # repo-wide rules for other tools
  services/
    QWEN.md                # rules for all services
    payments/
      QWEN.md              # rules for payments

Start Qwen in repo/services/payments with the default names. The chain is:

1. ~/.qwen/QWEN.md
2. repo/QWEN.md
3. repo/services/QWEN.md
4. repo/services/payments/QWEN.md
5. ~/.qwen/AGENTS.md
6. repo/AGENTS.md
7. repo/.qwen/QWEN.local.md

Among the files found by the search, every AGENTS.md file comes after every QWEN.md file, including a QWEN.md in the directory you started in. The blocks are concatenated in that order; Qwen Code does not have a formal precedence rule for two context files that contradict each other. The docs use "typically overrides or supplements" for more specific files, which is a reasonable expectation, not a guarantee (settings reference).

Two consequences follow:

• A root AGENTS.md is not sent before a nested QWEN.md. If both carry rules for the same thing, the order is name-first.
• A nested AGENTS.md is not found from the repository root. Starting at repo/ reads repo/AGENTS.md and repo/QWEN.md; services/AGENTS.md and packages/api/AGENTS.md wait until you start there. A request to add downward discovery is open (#6101, opened 1 July 2026, updated 12 August 2026).

What `context.fileName` changes#

context.fileName is the setting that controls the search names. It accepts a string or an array of strings (settings reference). At startup Qwen passes the value to setMemoryFilename, which replaces the built-in list rather than appending to it (config.ts).

{
  "context": {
    "fileName": ["AGENTS.md"]
  }
}

With that setting, QWEN.md is no longer read. If you want both, list both: ["QWEN.md", "AGENTS.md"] is the default spelled out. The array order is the order in which the name chains are built.

Three details that cause support questions:

• A project .qwen/settings.json value replaces a user value. For this key the higher-precedence file wins as a whole; the arrays are not concatenated. That is the default merge behaviour for settings arrays (deepMerge.ts).
• The name list is read when the session starts. Editing settings.json during a session does not rebuild it. Start a new session after the change.
• context.fileName does not control QWEN.local.md. That slot is hard-coded. Adding or removing names does not turn it off.

There is also a duplicate-file case to know about. If your context.fileName includes AGENTS.md and a CLAUDE.md whose whole content is @AGENTS.md, the text of AGENTS.md can reach the model twice: once as a context file and again as the import inside CLAUDE.md. A symlink to the same file is deduplicated, but an import is not (#15679, open, 26 October 2026). Either leave AGENTS.md out of the list and let the import supply it, or leave CLAUDE.md out.

`QWEN.local.md`: a fixed slot, not another search name#

The per-developer file lives at <repository>/.qwen/QWEN.local.md. It is loaded once, after every other context file, so your personal instructions can supplement or override the shared ones. It is not discovered by the upward walk, and it is not read from a subdirectory: the loader takes it from the repository root's .qwen/ directory (memory-constants.ts).

It has two gates:

• A real project root is required. If there is no .git ancestor, the slot is skipped. The loader does not fall back to the current directory, because that would turn one fixed file into a per-directory file.
• Folder trust applies when the feature is on. If folder trust is enabled and the folder is untrusted, the project chain and this slot are not loaded (trusted folders). The trust feature is off by default, so this only bites after someone enables it.

Qwen does not create a .gitignore entry for it; add .qwen/QWEN.local.md yourself (memory documentation). The feature request that added the slot is closed as completed (#4091, closed 25 May 2026).

Imports: an `@path` is inlined, not separately listed#

A line such as @docs/git-workflow.md inside a context file is expanded when the file is read. Relative paths resolve from the importing file, the imported text is inserted at the @ marker, and the result is sent as part of the parent's block (memoryImportProcessor.ts).

The limits matter for the checks below:

• Five levels deep by default, inside the project root only. A deeper import is left unexpanded; an import that resolves outside the repository is replaced with an Import failed... Path traversal attempt comment. A read error other than a missing file is replaced with a plain Import failed... comment.
• Not listed as its own file. The Read context files: notice and /context detail list the top-level file. The imported text is inside it, so a marker in an imported file can be in the prompt without the import appearing in the file list.
• A missing path is left as literal text. The @path stays in the prompt; it does not silently vanish.

Context files, rules and skills are different layers#

.qwen/rules/ is a separate always-on layer. A rule is a Markdown file under .qwen/rules/ (project) or ~/.qwen/rules/ (user). A rule without paths: is a baseline rule and goes into the system prompt from the first request. A rule with paths: stays out until a tool call touches a matching file, then is injected once for the rest of the session (rules documentation).

If a rule is meant to hold whether or not the model thought to look for it, a paths: rule or a permission rule is the better home than a paragraph in QWEN.md.

Why your `AGENTS.md` never loaded#

Start with the configured list, then check where you started Qwen.

• The effective list does not include it. Check the user file and the project file for context.fileName. A project value replaces the user value; ["QWEN.md"] or ["CLAUDE.md"] silently drops AGENTS.md.
• The file is below your starting directory. Discovery walks up, not down. Start Qwen in packages/api, or move the rules to the repository root.
• The file is a sibling or above the root. A directory that is not an ancestor is not on the path. A file above the .git root is out of scope; Qwen used to load one level above the root, and that was fixed (#13280, closed as completed 5 October 2026).
• The folder is untrusted. With folder trust enabled, an untrusted workspace skips the project chain, including AGENTS.md and QWEN.local.md. /permissions reopens the trust dialog (trusted folders).
• The setting is in a project file that is not being read. When folder trust is on and the folder is untrusted, its .qwen/settings.json is skipped too, so its context.fileName never applies.
• You edited the setting and did not restart. The name list is built at startup. A new session is the reliable check.
• The file is empty or whitespace-only. It can still be counted in the footer, but it is not attached to the prompt and does not appear in /context detail.
• The file is a global copy for another tool. Qwen's global folder is ~/.qwen (or $QWEN_HOME). It does not read ~/.gemini, ~/.claude, ~/.codex, or ~/.agents as a global instruction source.
• The file is CLAUDE.md or GEMINI.md. Neither is a default. Add it to context.fileName, or import it from a file that is loaded.
• An import is outside the repository. It is replaced with an Import failed... Path traversal attempt HTML comment in the prompt.
• An import is too deep, missing, or unreadable. Beyond five levels the @path is left unexpanded; it is not replaced with an error comment. A missing path is likewise left as literal text; a read error other than "not found" gets a plain Import failed... comment.

Prove what loaded#

The check is in the CLI, not in the model's answer. A model sees concatenated text, not the loader's file list, and it will often say it read a file because the question suggests it did.

The one-shot Read context files: line. In the interactive terminal, the first prompt of a session prints an info line naming the top-level files Qwen attached (AppContainer.tsx). It looks like this:

Read context files: ~/.qwen/QWEN.md, QWEN.md, .qwen/QWEN.local.md

The list is top-level files only. An imported file is inlined into its parent and is not named separately. The line is one-shot per session; after that, use /context detail.

The footer count. The footer shows a count such as 2 context files or 2 QWEN.md files. The label follows the configured names, not the files found: with the default two-name list it says context files even when every file that loaded is a QWEN.md (ContextSummaryDisplay.tsx). The count can include a blank memory-named file whose text never reached the prompt. Treat it as a hint.

/context detail. This is the useful one. It prints a Memory files section with one row per file and its token cost, plus the tool, skill and message categories (context-cost documentation). Read it on the first turn, before the conversation adds its own tokens. If your file is not in that section, it did not reach the prompt.

/memory is not the load list. The memory documentation says to open /memory to see which files are loaded. In the terminal UI at v0.26.2, the panel shows the auto-memory toggles and the user and project memory locations; with auto-memory on, those items open the auto-memory folders, not the chain of QWEN.md files (MemoryDialog.tsx). Use /context detail for the chain.

A marker test is the clearest full check:

1. Put a unique line in the global file, the repository file, and a nested file, for example CONTEXT-MARKER-GLOBAL.
2. Start a new session in the nested directory and send one short prompt. The Read context files: line should name the global, root and nested files.
3. Run /context detail. The Memory files rows should name the same paths.
4. If a marker is absent from both views, the file never loaded. If the marker is in /context detail and the rule is still ignored, the problem is adherence, not loading.

It loaded, but the rule is still ignored#

A context file is advice in a prompt, not an enforcement layer. Qwen appends context files after the base system prompt, then any appended prompt, then auto-memory (prompts.ts). Built-in tool guidance can outweigh a prose ban, and negative rules ("never commit", "do not run") are weak.

• Make the rule checkable and close to the work. "Run pnpm test before every commit" is easier to apply than "write clean code". Put a service-specific rule in that service's QWEN.md, or in a paths: rule.
• Use the enforcement layer for rules that must hold. A permissions.deny rule can block a tool, path or command pattern, and a PreToolUse hook can deny a call before it runs. The Qwen permissions page covers the rule layers; the Claude Code page on a loaded but ignored CLAUDE.md covers the general split between "not loaded" and "loaded but outranked".

Coming from Gemini CLI or Claude Code#

The file names are the first thing to change.

• From Gemini CLI: Qwen does not read GEMINI.md by default. Rename or copy it to QWEN.md, add GEMINI.md to context.fileName, or import it with @GEMINI.md from a loaded file. The Gemini CLI AGENTS.md page says AGENTS.md is opt-in there; in Qwen Code it is already in the list, so the AGENTS.md half carries over without a setting.
• From Claude Code: Qwen does not read CLAUDE.md by default. Add it to context.fileName, or keep AGENTS.md as the shared file. If your CLAUDE.md is the common one-line @AGENTS.md shim, do not also list AGENTS.md: that is the duplicate case above.
• Both: the global folder is ~/.qwen, not ~/.gemini or ~/.codex. Settings move with it: ~/.qwen/settings.json for the user, .qwen/settings.json for the repository. The handoff guide covers the rest of the move.

Where to go next#

• Qwen Code guides — the rest of the set: permissions, sessions, local models, MCP, skills and subagents.
• Persistent memory for Claude Code and Codex — where QWEN.md ends and model-written memory begins.
• Context compaction — what happens to these files when a long session is summarized.
• Why Qwen Code keeps asking for permission — when a rule has to be enforced rather than requested.
• Where did my Qwen Code session go? — the other half of "it was not there next time".
• One AGENTS.md for every coding agent — how a shared file reaches each tool, and why Qwen Code should not also get an import shim.