Memory

모든 Qwen Code 세션은 새로운 컨텍스트 창으로 시작됩니다. 두 가지 메커니즘이 세션 간에 지식을 전달하므로 매번 다시 설명할 필요가 없습니다:

QWEN.md — _사용자_가 한 번 작성하면 Qwen이 매 세션에 읽는 지시사항
Auto-memory — Qwen이 사용자로부터 학습한 내용을 바탕으로 직접 작성하는 메모

QWEN.md: Qwen에게 주는 지시사항

QWEN.md는 Qwen이 프로젝트나 선호도에 대해 항상 알아야 할 내용을 작성하는 일반 텍스트 파일입니다. 모든 대화 시작 시 로드되는 영구 브리핑이라고 생각하면 됩니다.

QWEN.md에 포함할 내용

매 세션마다 반복해서 설명해야 할 내용을 추가합니다:

빌드 및 테스트 명령어 (npm run test, make build)
팀이 따르는 코딩 컨벤션 (“모든 새 파일에 JSDoc 주석을 반드시 포함”)
아키텍처 결정 사항 (“repository pattern을 사용하며, 컨트롤러에서 데이터베이스를 직접 호출하지 않는다”)
개인 선호도 (“항상 npm 대신 pnpm 사용”)

Qwen이 코드를 읽으면 알 수 있는 내용은 포함하지 않습니다. QWEN.md는 짧고 구체적일수록 효과적입니다 — 길어질수록 Qwen이 덜 정확하게 따릅니다.

QWEN.md 생성 위치

파일	적용 대상
`~/.qwen/QWEN.md`	모든 프로젝트에 걸쳐 본인만
프로젝트 루트의 `QWEN.md`	전체 팀 (소스 컨트롤에 커밋)
`.qwen/QWEN.local.md`	이 프로젝트에서만 본인만 (git에 포함하지 않음)

이들 중 원하는 조합으로 사용할 수 있습니다. Qwen은 세션 시작 시 모든 파일을 로드합니다.

리포지토리에 다른 AI 도구용 AGENTS.md 파일이 이미 있다면, Qwen이 해당 파일도 읽습니다. 지시사항을 중복할 필요가 없습니다.

`.qwen/QWEN.local.md` 사용 시기

프로젝트별 개인 지시사항에 사용합니다 — 이 프로젝트에 속하지만 팀과 공유하지 않아야 하는 내용:

본인의 클러스터 ID, 컨테이너 레지스트리 네임스페이스, 클라우드 계정
로컬 환경을 하드코딩한 개인 디버그 명령어
진행 중인 작업에 대해 Qwen이 알아야 하지만 커밋하고 싶지 않은 메모

공유 프로젝트 QWEN.md 이후에 로드되므로, 로컬 지시사항으로 팀의 지시사항을 보완하거나 재정의할 수 있습니다.

직접 gitignore에 추가해야 합니다. .qwen/은 종종 로컬 디렉토리로 취급되지만, qwen-code가 .gitignore를 자동으로 생성하지 않으며, 일부 프로젝트는 .qwen/settings.json을 커밋합니다. 다음 줄을 .gitignore에 추가합니다 (또는 전역 git ignore에 추가):


.qwen/QWEN.local.md

`/init`으로 자동 생성

/init을 실행하면 Qwen이 코드베이스를 분석하여 빌드 명령어, 테스트 지침, 발견한 컨벤션이 포함된 초기 QWEN.md를 생성합니다. 이미 존재하면 덮어쓰지 않고 추가 사항을 제안합니다.

다른 파일 참조

QWEN.md에서 다른 파일을 가리켜 Qwen이 함께 읽도록 할 수 있습니다:


프로젝트 개요는 @README.md를 참조하세요.
 
# Conventions
 
- Git 워크플로우: @docs/git-workflow.md

QWEN.md 내 어디서든 @path/to/file을 사용합니다. 상대 경로는 QWEN.md 파일 자체를 기준으로 해석됩니다.

Auto-memory: Qwen이 학습하는 내용

Auto-memory는 백그라운드에서 실행됩니다. 각 대화 후에 Qwen이 학습한 유용한 내용 — 선호도, 피드백, 프로젝트 컨텍스트 — 를 조용히 저장하여 다음 세션에서 반복 없이 사용할 수 있습니다.

QWEN.md와 다릅니다: 사용자가 작성하는 것이 아니라 Qwen이 작성합니다.

Qwen이 저장하는 내용

Qwen은 기억할 가치가 있는 네 가지 유형의 내용을 찾습니다:

항목	예시
사용자에 대해	역할, 배경, 작업 방식 선호도
사용자의 피드백	수정한 내용, 확인한 접근 방식
프로젝트 컨텍스트	진행 중인 작업, 코드에서 명확하지 않은 결정, 목표
외부 참조	언급한 대시보드, 티켓 트래커, 문서 링크

Qwen이 모든 것을 저장하는 것은 아닙니다 — 다음번에 실제로 유용할 내용만 저장합니다.

저장 위치

Auto-memory 파일은 ~/.qwen/projects/<project>/memory/에 저장됩니다. 같은 체크아웃의 모든 브랜치가 동일한 메모리 폴더를 공유하므로, 한 브랜치에서 Qwen이 학습한 내용은 다른 브랜치에서도 사용 가능합니다. 각 연결된 git worktree는 자체 메모리 폴더를 가지며, 채팅 및 기타 세션 상태의 worktree별 격리에 맞춥니다 — 모든 worktree에 필요한 리포지토리 전체 컨벤션은 팀 메모리에 저장합니다.

저장된 모든 것은 일반 마크다운이며, 언제든지 파일을 열거나, 편집하거나, 삭제할 수 있습니다.

고정 메모

관리되는 메모리 디렉토리의 pinned/ 아래에 자동 메모리 유지보수가 보존해야 할 수작업 문서를 넣습니다. 예: ~/.qwen/projects/<project>/memory/pinned/architecture.md 또는 ~/.qwen/memories/pinned/preferences.md. 다른 메모 문서와 동일한 프론트매터를 사용합니다. 유효한 고정 파일은 Qwen이 읽을 수 있으며 MEMORY.md가 재빌드될 때 다른 메모 문서와 동일한 크기 및 파일 수 제한 아래 포함됩니다.

관리되는 메모리 루트 바로 안의 최상위 pinned/ 디렉토리만 보호됩니다; memory/project/pinned/ 같은 중첩 디렉토리는 일반 쓰기 가능 메모리입니다. 자동 추출 및 Dream 워커는 예약된 디렉토리 이름을 대소문자 구분 없이 매칭합니다.

자동 추출은 고정 레코드와 유효한 인덱스 항목을 변경하지 않도록 지시되며, Dream은 통합 중 pinned/를 건너뛰도록 지시됩니다. 자동 추출과 포크된 Dream 워커 모두 백그라운드 정리를 포함하여 pinned/로 해석되는 경로를 포함해 쓰기 및 편집 도구에 대한 고정 파일 경계를 적용합니다; 기존 읽기 전용 셸 정책이 명령줄 삭제를 차단합니다. 사용자는 여전히 이 파일들을 직접 제어하며 명시적인 /forget 요청으로 제거할 수 있습니다.

참고: 표시되는 /dream 슬래시 명령어는 메인 에이전트에서 실행됩니다. 동일한 건너뛰기 지시를 받지만, 포크된 워커의 결정적 턴별 도구 게이트는 아직 받지 않습니다.

주기적 정리

Qwen은 주기적으로 저장된 메모리를 검토하여 중복을 제거하고 오래된 항목을 정리합니다. 충분한 세션이 쌓이면 하루에 한 번 백그라운드에서 자동으로 실행됩니다. 지금 실행하려면 /dream으로 수동 트리거할 수 있습니다.

정리가 백그라운드에서 실행되는 동안에도 세션은 정상적으로 계속됩니다.

활성화/비활성화

Auto-memory는 기본적으로 켜져 있습니다. 토글하려면 /memory를 열고 상단의 스위치를 사용합니다. 자동 저장만, 주기적 정리만, 또는 둘 다 끌 수 있습니다.

~/.qwen/settings.json(모든 프로젝트에 적용) 또는 .qwen/settings.json(이 프로젝트만)에서도 설정할 수 있습니다:


{
  "memory": {
    "enableManagedAutoMemory": true,
    "enableManagedAutoDream": true
  }
}

팀 메모리 (협업자와 공유)

기본적으로 auto-memory는 본인만 비공개입니다 — 홈 디렉토리 아래에 저장되며 공유되지 않습니다. 팀 메모리는 전체 팀이 git을 통해 공유하는 옵트인 티어입니다.

활성화하면 Qwen이 리포지토리 내부의 .qwen/team-memory/에 세 번째 메모리 디렉토리를 갖습니다. 비공개 티어와 동일한 파일당 하나의 메모리 레이아웃과 MEMORY.md 인덱스를 사용합니다. 리포에 커밋되므로 모든 협업자와 일반적인 방식으로 공유됩니다: git pull로 팀원의 메모리를 받고, commit/push로 본인의 메모리를 공유합니다. Qwen은 내구성 있는 프로젝트 전체 지식을 여기에 라우팅합니다 — 모든 기여자가 따라야 할 컨벤션, 공유 참조 포인터 (트래커, 대시보드) — 반면 개인적이고 빠르게 변화하는 메모는 비공개로 유지됩니다.

settings.json에서 프로젝트별 (또는 전역)로 활성화합니다:


{
  "memory": {
    "enableTeamMemory": true
  }
}

기본적으로 꺼져 있습니다. 다음 주의사항을 염두에 두세요:

소스 컨트롤에 포함되며 리포 접근 권한이 있는 모든 사람에게 보입니다. 팀 메모리를 리포에 커밋하는 것과 동일하게 취급하세요.
비밀은 차단됩니다. .qwen/team-memory/에 대한 쓰기는 자격 증명(API 키, 토큰, 개인 키)에 대해 스캔됩니다; 감지된 비밀은 거부되며 절대 기록되지 않습니다. 스캔은 최종 방어선이지 보장이 아닙니다 — 민감한 데이터를 туда 두지 마세요.
변경 사항이 검토 가능합니다. 팀 메모리 쓰기는 다른 파일과 마찬가지로 git status / PR diff에 나타나므로 커밋 전에 검토할 수 있습니다. 기본 승인 모드에서 Qwen은 각 팀 쓰기 전에 확인을 요청합니다; AUTO_EDIT/YOLO 모드(자동 승인을 선택한 경우)에서는 프롬프트 없이 적용되지만 여전히 diff에 표시됩니다.
디렉토리가 git 추적 대상이어야 합니다. 프로젝트의 .gitignore가 .qwen/*를 제외하면, 해당 경로를 다시 포함하여 공유할 수 있게 합니다:
```
!.qwen/team-memory/
!.qwen/team-memory/**
```
주의: 디렉토리 형태가 아닌 파일-glob ignore 형태(.qwen/*)를 사용하세요. 디렉토리 형태(.qwen/)는 git이 폴더를 완전히 건너뛰게 하여, 아래의 ! 재포함이 무효가 되고 팀 티어가 git에서 조용히 비어 있게 됩니다. Qwen은 티어가 활성화되었지만 디렉토리가 git-ignore되었거나 git 리포지토리 외부에 있을 때 시작 시 한 번 경고하므로 이 잘못된 설정은 unnoticed로 지나가지 않습니다.

QWEN_CODE_MEMORY_TEAM=1 / =0은 단일 실행에 대해 설정을 재정의합니다.

자동 git 동기화 (선택 사항)

기본적으로 일반적인 git 워크플로로 팀 메모리를 공유합니다(pull로 수신, commit/push로 공유). Qwen이 대신 수행하도록 하려면 동기화를 활성화합니다:


{
  "memory": {
    "enableTeamMemory": true,
    "enableTeamMemorySync": true
  }
}

활성화하면, 세션 시작 시 Qwen이 .qwen/team-memory/ 디렉토리를 최선을 다해 동기화합니다: 공유 MEMORY.md 인덱스를 재빌드하고, 협업자의 업데이트를 먼저 fast-forward pull한 다음, 그 위에 팀 메모리 변경 사항을 커밋하고, 해당 동기화 커밋만 push합니다 (명시적 단일 브랜치 refspec 경유) — 로드하는 인덱스가 최신 상태를 반영합니다. 팀 디렉토리만 스테이징하며 (다른 작업 변경 사항은 커밋되지 않음), git 실패 시 세션을 차단하지 않습니다. 기본적으로 꺼져 있습니다. QWEN_CODE_MEMORY_TEAM_SYNC=1 / =0은 단일 실행에 대해 설정을 재정의합니다.

활성화하기 전에 두 가지를 알아두세요:

Fast-forward pull은 .qwen/team-memory/가 아닌 현재 브랜치 전체에 작용합니다 (git에는 경로 범위 pull이 없습니다). 따라서 동기화는 브랜치를 원격 팁으로 fast-forward합니다. 반면 push는 범위가 지정됩니다: 동기화가 방금 생성한 커밋만 게시하므로, 다른 미push 커밋은 절대 push하지 않습니다 — 브랜치가 이미 업스트림보다 앞서 있으면 로컬에 동기화 커밋만 하고 push를 건너뜁니다. Fast-forward pull이 괜찮은 브랜치에서 활성화하거나 전용 체크아웃에서 실행하세요.
분기된 브랜치는 변경되지 않습니다 (--ff-only는 절대 병합하지 않음). 이 경우 동기화는 해당 세션에서 아무것도 하지 않습니다; 분기를 해결(git pull)하면 재개됩니다. 업스트림이 없는 브랜치(추적 설정 없음)는 여전히 로컬에 커밋하지만 push는 건너뜁니다 — push할 곳이 없습니다.

명령어

`/memory`

Memory 패널을 엽니다. 여기에서 다음을 수행할 수 있습니다:

Auto-memory 저장 켜기/끄기
주기적 정리(dream) 켜기/끄기
개인 QWEN.md 열기 (~/.qwen/QWEN.md)
프로젝트 QWEN.md 열기
Auto-memory 폴더 탐색

`/init`

프로젝트의 초기 QWEN.md를 생성합니다. Qwen이 코드베이스를 읽고 빌드 명령어, 테스트 지침, 발견한 컨벤션을 채웁니다.

`/remember <text>`

Qwen이 자동으로 수집할 때까지 기다리지 않고 즉시 auto-memory에 저장합니다:


/remember always use snake_case for Python variable names
/remember the staging environment is at staging.example.com

`/forget <text>`

설명과 일치하는 auto-memory 항목을 제거합니다:


/forget old workaround for the login bug

`/dream`

자동 일정을 기다리지 않고 지금 메모리 정리를 실행합니다:


/dream

문제 해결

Qwen이 QWEN.md를 따르지 않습니다

/memory를 열어 어떤 파일이 로드되었는지 확인하세요. 파일이 목록에 없으면 Qwen이 볼 수 없습니다 — 프로젝트 루트 또는 ~/.qwen/에 있는지 확인하세요.

지시사항은 구체적일수록 더 잘 작동합니다:

✓ Use 2-space indentation for TypeScript files
✗ Format code nicely

충돌하는 지시사항이 있는 여러 QWEN.md 파일이 있으면 Qwen이 일관성 없이 동작할 수 있습니다. 검토하고 모순을 제거하세요.

Qwen이 저장한 내용을 보고 싶습니다

/memory를 실행하고 Open auto-memory folder를 선택하세요. 저장된 모든 메모리는 탐색, 편집, 삭제 가능한 마크다운 파일입니다.

Qwen이 자꾸 잊어버립니다

Auto-memory가 켜져 있지만 Qwen이 세션 간에 기억하지 못하는 것 같으면, /dream을 실행하여 정리 패스를 강제하세요. /memory에서 두 토글 모두 활성화되어 있는지도 확인하세요.

Qwen이 항상 기억해야 할 내용은 QWEN.md에 추가하세요 — auto-memory는 최선 노력이며, QWEN.md는 보장됩니다.