docs/users/features/memory.md
Every Qwen Code session starts with a fresh context window. Two mechanisms carry knowledge across sessions so you don't have to re-explain yourself every time:
QWEN.md is a plain text file where you write things Qwen should always know about your project or your preferences. Think of it as a permanent briefing that loads at the start of every conversation.
Add things you'd otherwise have to repeat every session:
npm run test, make build)Don't include things Qwen can figure out by reading your code. QWEN.md works best when it's short and specific — the longer it gets, the less reliably Qwen follows it.
| File | Who it applies to |
|---|---|
~/.qwen/QWEN.md | You, across all your projects |
QWEN.md in the project root | Your whole team (commit it to source control) |
.qwen/QWEN.local.md | Only you, only in this project (keep out of git) |
You can have any combination of these. Qwen loads all of them when you start a session.
If your repository already has an AGENTS.md file for other AI tools, Qwen reads that too. No need to duplicate instructions.
.qwen/QWEN.local.mdUse it for project-specific but personal instructions — things that belong to this project but shouldn't be shared with the team:
It loads after the shared project QWEN.md, so your local instructions can supplement or override the team's.
You must gitignore it yourself. Although .qwen/ is often treated as a local directory, qwen-code does not generate a .gitignore for you, and some projects commit .qwen/settings.json. Add this line to your .gitignore (or to your global git ignore):
.qwen/QWEN.local.md
/initRun /init and Qwen will analyze your codebase to create a starter QWEN.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.
You can point QWEN.md at other files so Qwen reads them too:
See @README.md for project overview.
# Conventions
- Git workflow: @docs/git-workflow.md
Use @path/to/file anywhere in QWEN.md. Relative paths resolve from the QWEN.md file itself.
Auto-memory runs in the background. After each of your conversations, Qwen quietly saves useful things it learned — your preferences, feedback you gave, project context — so it can use them in future sessions without you repeating yourself.
This is different from QWEN.md: you don't write it, Qwen does.
Qwen looks for four kinds of things worth remembering:
| What | Examples |
|---|---|
| About you | Your role, background, how you like to work |
| Your feedback | Corrections you made, approaches you confirmed |
| Project context | Ongoing work, decisions, goals not obvious from the code |
| External references | Dashboards, ticket trackers, docs links you mentioned |
Qwen doesn't save everything — only things that would actually be useful next time.
Auto-memory files live at ~/.qwen/projects/<project>/memory/. All branches and worktrees of the same repository share the same memory folder, so what Qwen learns in one branch is available in others.
Everything saved is plain markdown — you can open, edit, or delete any file at any time.
Qwen periodically goes through its saved memories to remove duplicates and clean up outdated entries. This runs automatically in the background once a day after enough sessions have accumulated. You can trigger it manually with /dream if you want it to run now.
While cleanup is running, ✦ dreaming appears in the corner of the screen. Your session continues normally.
Auto-memory is on by default. To toggle it, open /memory and use the switches at the top. You can turn off just the automatic saving, just the periodic cleanup, or both.
You can also set them in ~/.qwen/settings.json (applies to all projects) or .qwen/settings.json (this project only):
{
"memory": {
"enableManagedAutoMemory": true,
"enableManagedAutoDream": true
}
}
By default, auto-memory is private to you — it lives under your home directory and is never shared. Team memory is an opt-in tier that the whole team shares through git.
When enabled, Qwen gains a third memory directory at .qwen/team-memory/ inside the repository. It uses the same one-file-per-memory layout and MEMORY.md index as the private tiers. Because it is committed to the repo, it is shared with every collaborator the normal way: you git pull to receive teammates' memories and commit/push to share yours. Qwen routes durable, project-wide knowledge here — conventions every contributor must follow, shared reference pointers (trackers, dashboards) — while personal and fast-decaying notes stay private.
Enable it per project (or globally) in settings.json:
{
"memory": {
"enableTeamMemory": true
}
}
It is off by default. Keep these caveats in mind:
It is source-controlled and visible to everyone with repo access. Treat a team memory like committing to the repo.
Secrets are blocked. Writes to .qwen/team-memory/ are scanned for credentials (API keys, tokens, private keys); a detected secret is rejected, never written. The scan is a backstop, not a guarantee — don't put sensitive data there.
Changes are reviewable. Team memory writes appear in git status / the PR diff like any other file, so they can be reviewed before they're committed. In the default approval mode Qwen also asks before each team write; in AUTO_EDIT/YOLO mode (where you've opted into auto-approval) they are applied without a prompt but still surface in the diff.
The directory must be git-tracked. If your project's .gitignore excludes .qwen/*, re-include the path so it can be shared:
!.qwen/team-memory/
!.qwen/team-memory/**
Caveat: use the file-glob ignore form (.qwen/*), not a directory form with a trailing slash (.qwen/). A directory-form ignore makes git skip the folder entirely, so a !-reinclude below it is a no-op and the team tier stays silently empty in git. Qwen warns once at startup when the tier is enabled but its directory is git-ignored or outside any git repository, so this misconfiguration does not pass unnoticed.
QWEN_CODE_MEMORY_TEAM=1 / =0 overrides the setting for a single run.
By default you share team memory with the normal git workflow (pull to receive, commit/push to share). To have Qwen do it for you, enable sync:
{
"memory": {
"enableTeamMemory": true,
"enableTeamMemorySync": true
}
}
When on, at session start Qwen best-effort syncs the .qwen/team-memory/ directory: it rebuilds the shared MEMORY.md index, fast-forward-pulls collaborators' updates first, then commits your team-memory changes on top, and pushes only that sync commit (via an explicit single-branch refspec) — so the index you load reflects the latest. It only stages the team directory (your other working changes are never committed), and never blocks the session on a git failure. Off by default. QWEN_CODE_MEMORY_TEAM_SYNC=1 / =0 overrides the setting for a single run.
Two things to know before enabling it:
.qwen/team-memory/ (git has no path-scoped pull). So sync will fast-forward your branch to the remote tip. The push, by contrast, is scoped: it publishes only the commit this sync just created, so it never pushes other unpushed commits you have — if your branch is already ahead of upstream, sync commits locally and skips the push. Enable it on branches where the fast-forward pull is fine — or run it on a dedicated checkout.--ff-only never merges). When that happens sync simply does nothing that session; resolve the divergence (git pull) and it resumes. A branch with no upstream (no tracking configuration) still commits locally but skips the push — there is nowhere to push to./memoryOpens the Memory panel. From here you can:
~/.qwen/QWEN.md)/initGenerates a starter QWEN.md for your project. Qwen reads your codebase and fills in build commands, test instructions, and conventions it discovers.
/remember <text>Immediately saves something to auto-memory without waiting for Qwen to pick it up automatically:
/remember always use snake_case for Python variable names
/remember the staging environment is at staging.example.com
/forget <text>Removes auto-memory entries that match your description:
/forget old workaround for the login bug
/dreamRuns the memory cleanup now instead of waiting for the automatic schedule:
/dream
Open /memory to see which files are loaded. If your file isn't listed, Qwen can't see it — make sure it's in the project root or ~/.qwen/.
Instructions work better when they're specific:
Use 2-space indentation for TypeScript filesFormat code nicelyIf you have multiple QWEN.md files with conflicting instructions, Qwen may behave inconsistently. Review them and remove any contradictions.
Run /memory and select Open auto-memory folder. All saved memories are readable markdown files you can browse, edit, or delete.
If auto-memory is on but Qwen doesn't seem to remember things across sessions, try running /dream to force a cleanup pass. Also check /memory to confirm both toggles are enabled.
For things you always want Qwen to remember, add them to QWEN.md instead — auto-memory is best-effort, QWEN.md is guaranteed.