Claude Code 서브에이전트가 메모리를 공유하지 않는 이유와 해결 방법 (2026)

격리(Isolation)는 비용을 지불할 가치가 있는 핵심 기능입니다

먼저 서브에이전트의 목적부터 살펴보겠습니다. Claude Code 문서에서는 서브에이전트의 사용 사례를 메인 대화에 다시 참조하지 않을 검색 결과, 로그 또는 파일 내용이 넘쳐나지 않도록 방지하는 사이드 태스크로 설명합니다. 즉, "서브에이전트는 자체 컨텍스트 내에서 해당 작업을 수행하고 요약만 반환합니다." 각 서브에이전트는 "자체 커스텀 시스템 프롬프트, 특정 도구 액세스 권한 및 독립적인 권한을 가진 자체 컨텍스트 창에서 실행됩니다."

이는 매우 훌륭한 트레이드오프이며, 이를 되돌리고 싶지는 않을 것입니다. 10,000줄의 테스트 출력은 원래 있어야 할 곳에 머물고, 메인 대화는 단 세 줄의 문장만 받게 됩니다. 하지만 이 문장이 의미하는 바를 주목해야 합니다. 서브에이전트가 작업을 진행하면서 이해한 내용(에러 래퍼, 명명 규칙의 특이점, 두 모듈이 충돌한다는 사실 등)은 이제 사라진 컨텍스트 창 내에만 존재한다는 점입니다. 메인 대화로 돌아온 것은 요약뿐이며, 그 요약은 서브에이전트가 말할 가치가 있다고 판단한 내용에 불과합니다.

메인 대화의 메모리는 경계를 넘지 못합니다

Claude Code에는 기본적으로 활성화되어 있는 자동 메모리(auto memory) 기능이 있어, Claude가 작업을 진행하면서 빌드 명령어, 디버깅 인사이트, 발견한 선호 사항 등의 노트를 스스로 작성합니다. 이러한 정보는 리포지토리별로 ~/.claude/projects/<project>/memory/ 아래에 저장되며, 모든 대화가 시작될 때 MEMORY.md 인덱스가 로드됩니다.

하지만 서브에이전트의 대화는 예외입니다. 공식 문서에서는 이를 명확히 밝히고 있습니다. "메인 대화의 자동 메모리는 서브에이전트에 로드되지 않습니다." 유일한 예외는 부모 대화와 시스템 프롬프트를 그대로 상속받는 포크(fork)입니다. 따라서 지난주 화요일에 메인 세션이 이 리포지토리에 대해 학습한 내용은 오늘 여러분이 실행하는 서브에이전트에게 전달되지 않습니다.

각 서브에이전트의 메모리는 자체 디렉토리를 가집니다

서브에이전트는 자체 노트를 유지할 수 있으며, 이 기능은 활성화할 가치가 있습니다. 서브에이전트 정의에 memory 필드를 추가하면 대화가 끝나도 유지되는 영구 디렉토리가 생성됩니다. 문서에서는 이를 "코드베이스 패턴, 디버깅 인사이트, 아키텍처 결정 등 시간이 지남에 따라 지식을 축적하는" 공간으로 설명합니다. 사용할 수 있는 범위(scope)는 세 가지입니다. user는 ~/.claude/agent-memory/<name-of-agent>/에 쓰고, project는 .claude/agent-memory/<name-of-agent>/에 쓰며 버전 관리를 통해 공유할 수 있고, local은 .claude/agent-memory-local/<name-of-agent>/에 쓰며 git 관리 대상에서 제외됩니다.

이 경로들을 자세히 살펴보면 우리가 던진 질문의 답이 디렉토리 이름에 있음을 알 수 있습니다. 메모리 범위는 에이전트 이름별로 지정됩니다. 리뷰어의 누적된 지식은 리뷰어 폴더에 있고, 테스트 작성자는 자체 폴더를 가지며, 두 에이전트가 모두 읽을 수 있는 공유 폴더는 존재하지 않습니다. 또한 이 기능에는 두 가지 유용한 특징과 그에 따른 한계가 있습니다. 서브에이전트의 시스템 프롬프트에는 MEMORY.md 파일의 처음 200줄 또는 25KB 중 먼저 도달하는 기준까지만 포함되며, 전체 메커니즘이 자동 메모리의 일부로 작동하므로 autoMemoryEnabled 또는 CLAUDE_CODE_DISABLE_AUTO_MEMORY를 통해 자동 메모리를 비활성화하면 memory 필드는 아무런 효과가 없습니다.

두 가지 내장 서브에이전트는 CLAUDE.md도 건너뜁니다

사람들이 놀라는 또 다른 공백이 있으며, 이는 문서에도 명시되어 있습니다. "Explore 및 Plan은 빠르고 비용 효율적인 리서치를 위해 CLAUDE.md 파일과 부모 세션의 git 상태를 건너뜁니다. 그 외의 모든 내장 및 커스텀 서브에이전트는 두 가지를 모두 로드합니다."

Explore는 코드베이스를 읽고 분석하는 서브에이전트입니다. 개발 규칙을 가장 잘 알고 있어야 할 에이전트이지만, 의도적으로 이를 건너뛰도록 설계되었습니다. 이는 성능을 고려한 합리적인 결정이지만, 메인 대화에 제공되는 리서치 결과가 정작 개발 표준을 읽지 않은 에이전트에 의해 수행되었음을 의미합니다.

그리고 이 중 어떤 것도 로컬 머신을 벗어나지 않습니다

자동 메모리는 로컬 머신에 종속됩니다. 공식 문서는 명확합니다. 리포지토리의 모든 작업 트리(worktree)와 하위 디렉토리는 단일 디렉토리를 공유하며, "파일은 머신이나 클라우드 환경 간에 공유되지 않습니다." project 범위로 설정된 디렉토리를 커밋하지 않는 한, 에이전트별 디렉토리도 마찬가지입니다.

결국 에이전트 팀의 누적된 지식은 하나의 노트북 안에서 에이전트별 폴더에만 머물게 되며, 의도적으로 일부를 커밋하지 않는 한 다른 도구나 팀원들에게는 보이지 않습니다. 빌드 명령어 수준이라면 괜찮겠지만, 특정 모듈을 건드리면 안 되는 중요한 이유와 같은 정보라면 이야기가 달라집니다.

모든 내용을 `CLAUDE.md`에 넣기. 가장 먼저 시도해 볼 만한 올바른 조치이며, Explore와 Plan을 제외한 모든 서브에이전트에 전달됩니다. 한계는 크기입니다. 문서에서는 파일당 200줄 미만을 유지할 것을 권장하는데, 파일이 길어질수록 더 많은 컨텍스트를 소모하고 지침 준수율이 떨어지기 때문입니다. 서브에이전트 4개가 학습한 내용을 모두 담을 정도로 비대해진 CLAUDE.md는 아무도 따르지 않는 규칙 문서가 되어버립니다.

더 긴 서브에이전트 프롬프트 작성하기. 고정된 지침에는 효과가 있지만, 새로 발견된 사실에는 작동하지 않습니다. 에러 래퍼에 대해 알게 된 후 테스트 작성자에게 알려줄 수는 있지만, 핵심은 리뷰어는 알고 있었고 여러분은 몰랐다는 점입니다.

서브에이전트에게 파일 작성을 지시하기. "학습한 내용을 notes/review-findings.md에 저장해 줘." 효과적이며 본질적으로 메모리 기능을 수동으로 구현하는 방식입니다. 하지만 에이전트가 4개, 파일이 4개가 되고 누가 어떤 파일을 읽어야 하는지에 대한 규칙이 없어지기 전까지만 유효한 방법입니다.

대신 포크(fork) 사용하기. 포크는 부모 대화와 시스템 프롬프트를 상속받으므로 "우리가 논의한 내용을 모른다"는 문제를 확실히 해결해 줍니다. 하지만 그 대가로 원래 얻고자 했던 컨텍스트 절약 효과를 포기해야 합니다. 본인의 생각을 이어서 확장하는 데는 적합한 도구이지만, 노이즈가 많은 작업을 격리하는 데는 잘못된 도구입니다.

에이전트별 메모리를 활성화하고 충분하기를 바라기. 이 기능은 활성화하는 것이 좋습니다. 버전 관리를 통해 지식을 공유할 수 있도록 project 범위를 사용하는 것이 문서에서 권장하는 방식입니다. 다만 이를 '공유된 두뇌'로 기대해서는 안 됩니다. 이는 에이전트별 개별 노트일 뿐이며, 문서에서도 정확히 그렇게 설명하고 있습니다.

서브에이전트 실행 개수 줄이기. 세 번째 모순에 직면한 후 사람들이 결국 도달하는 결론입니다. 작동은 하겠지만 실질적인 손실입니다. 협업 공백을 피하기 위해 불필요한 컨텍스트 비용을 지불하는 셈이기 때문입니다.

격리 상태는 유지되어야 합니다. 변화가 필요한 부분은 현재 "격리된 컨텍스트"와 "격리된 지식"이 동일시되고 있다는 점이며, 이 둘은 반드시 같을 필요가 없습니다.

효과적인 구조는 메인 대화와 모든 서브에이전트가 읽고 쓸 수 있는 공유 저장소를 에이전트별 메모리와 병행하여 구축하는 것입니다. 단일 작업을 넘어 중요한 발견 사항(에러 래퍼, 결정 사항, 더 이상 사용되지 않는 헬퍼 등)은 이 공유 저장소에 기록되며, 모든 에이전트가 동일한 버전을 읽습니다. 에이전트별 메모리는 해당 에이전트의 전문 작업에 국한된 로컬 정보만 계속 유지합니다.

MemoryLake는 이를 위한 메모리 레이어입니다. 결정 사항, 개발 규칙, 소스 문서가 저장되는 단일 저장소로, MCP를 통해 Claude Code 및 서브에이전트, Codex에서 접근할 수 있으며 API를 통해 ChatGPT에서도 접근 가능합니다. 에이전트별로 또 다른 노트를 만드는 것이 아니라, 여러 독자가 공유하는 단일 기록을 구축하는 것입니다.

1단계: API 키 생성

키를 생성하고 약 30초 만에 첫 번째 요청을 보낼 수 있습니다. 세션에 직접 붙여넣는 대신 환경 변수나 시크릿 관리자에 안전하게 보관하세요.

2단계: 첫 번째 메모리 업로드

에이전트들이 계속해서 다시 찾아내야 하는 문서, 이미지, 파일들을 업로드하세요. 개발 규칙, 아키텍처 결정 사항, 규칙 제정의 배경이 된 장애 보고서, API 규격서, 이유가 첨부된 "수정 금지" 목록 등이 이에 해당합니다. 요약본 대신 원본 소스를 업로드하세요. 요약은 서브에이전트가 이미 제공하고 있으며, 정보의 과도한 압축이야말로 우리가 해결하려는 문제이기 때문입니다.

3단계: AI 및 에이전트 연결

Claude, Codex, OpenClaw 및 기타 AI 에이전트가 MCP 또는 API를 통해 메모리에 액세스할 수 있도록 설정합니다. Claude Code는 CLAUDE.md 파일과 함께 MCP를 통해 이를 읽으며, 서브에이전트별로 액세스 범위를 지정할 수 있습니다. 문서에 따르면 서브에이전트의 mcpServers 필드에 인라인으로 MCP 서버를 선언하면 도구 설명이 메인 대화의 컨텍스트에 전혀 포함되지 않습니다. 즉, 서브에이전트는 도구를 얻고 부모 대화는 이를 얻지 않습니다. 이 방식을 통해 부모 컨텍스트를 소모하지 않고도 리뷰어와 테스트 작성자에게 동일한 메모리를 제공할 수 있습니다.

첫 번째 차이점은 발견된 사실이 이를 생성한 작업보다 더 오래 지속된다는 것입니다. 리뷰어가 에러 래퍼를 감지하여 공유 저장소에 기록하면, 한 시간 후에 테스트 작성자가 이를 읽습니다. 서로를 볼 수 없는 두 에이전트 사이에서 여러분이 직접 메시지 버스 역할을 할 필요가 없어집니다.

두 번째는 CLAUDE.md 파일을 효과적으로 작동할 만큼 짧게 유지할 수 있다는 점입니다. 지침 준수율이 떨어질 정도로 파일 크기를 키우는 대신, 고정된 규칙만 파일에 남겨두고 누적된 세부 정보는 검색(retrieval) 영역으로 이동시킵니다. 이는 매 세션마다 코드베이스를 다시 읽는 에이전트의 비용이 많이 드는 이유와 같습니다. 지식은 존재하지만 에이전트가 찾는 위치에 없을 뿐입니다.

세 번째는 지식이 노트북을 넘어 보존된다는 점입니다. 자동 메모리와 에이전트별 메모리는 설계상 로컬 머신에 종속됩니다. 반면 공유 저장소를 사용하면 팀에 필요한 부분(결정 사항, 이유, 규칙)이 더 이상 한 개발자의 로컬 파일에 머물지 않게 됩니다. 동료가 "왜 이 부분을 건드리면 안 되나요?"라고 여러분에게 직접 묻는 대신 시스템에 물어볼 수 있게 되는 차이입니다.

또한 이는 Claude Code가 기본적으로 수행하는 작업과 충돌하지 않습니다. 자동 메모리는 리포지토리별로 빌드 명령어와 디버깅 노트를 계속 작성합니다. 에이전트별 메모리는 각 서브에이전트의 전문 작업 지식을 계속 축적합니다. 어느 쪽도 가장 적합하지 않은 역할인 '기준 시스템(system of record)'이 될 필요가 없으며, 이는 하나의 메모리를 공유하는 여러 에이전트 구조를 실현 가능하게 만드는 동일한 분업 방식입니다.

프로젝트 범위로 에이전트별 메모리 활성화하기

memory: project는 문서에서 권장하는 방식이며, 그 이유는 명확합니다. 디렉토리가 버전 관리에 포함되므로 서브에이전트의 누적된 지식이 홈 디렉토리에 갇히는 대신 팀원들이 검토할 수 있게 됩니다. 정말로 커밋해서는 안 되는 노트에만 local을 사용하세요.

명시적으로 메모리 읽기 및 쓰기 요청하기

문서에서는 정확히 이 방식을 제안합니다. 작업을 시작하기 전에 서브에이전트가 메모리를 참조하도록 프롬프트를 제공하고("이전에 보았던 패턴이 있는지 메모리를 확인해 줘"), 작업이 끝난 후 업데이트하도록 유도하세요("학습한 내용을 저장해 줘"). 더 좋은 방법은 이러한 지침을 서브에이전트 자체의 마크다운 본문에 포함하여 여러분이 기억하지 않아도 스스로 유지 관리하도록 만드는 것입니다.

MEMORY.md는 창고가 아닌 인덱스로 유지하기

MEMORY.md 파일의 처음 200줄 또는 25KB만 로드되며, 이를 초과하는 내용은 세션 시작 시 로드되지 않습니다. 항목당 한 줄만 유지하고 세부 정보는 Claude가 필요할 때 읽을 수 있도록 주제별 파일로 분리하세요. 인덱스가 자동으로 초과되어 누락되는 것은 짧은 것보다 나쁩니다. 컨텍스트에 포함되어 있다고 착각하기 쉽기 때문입니다.

Explore가 규칙을 읽지 않았다고 가정하기

Explore와 Plan은 설계상 CLAUDE.md를 건너뛰므로, 이들의 조사 결과를 규칙을 인지한 상태에서 도출된 것으로 취급해서는 안 됩니다. 리서치 결과에 따라 수정을 진행하려는 경우, 작업을 수행할 때 관련 규칙을 다시 언급해 주거나, Explore가 쿼리할 수 있는 공유 메모리를 제공하는 것이 더 지속 가능한 해결책입니다.

메모리를 강제 규정으로 혼동하지 않기

Claude Code 문서에 따르면 지침 파일과 자동 메모리는 "강제된 구성이 아닌 컨텍스트"일 뿐이며 엄격한 준수를 보장하지 않습니다. 생성된 파일을 절대 수정하지 않거나 항상 린터를 실행하는 등 매번 반드시 지켜야 하는 사항은 훅(hook)이나 CI 검사에 포함되어야 합니다. 메모리는 인지하기 위한 것이고, 훅은 보장하기 위한 것입니다. 메모리를 컴플라이언스(준수 보장) 수단으로 홍보하는 주장은 경계해야 합니다.

발견한 사실뿐만 아니라 이유도 함께 기록하기

"결제 모듈은 커스텀 에러 래퍼를 사용함"이라는 사실은 의문을 자아낼 수 있습니다. "업스트림 클라이언트가 상태 코드를 삼켜버리기 때문에 결제 모듈은 커스텀 에러 래퍼를 사용함 - 3월 장애 사건 참조"와 같이 기록하면 다음 에이전트나 다음 엔지니어가 의문을 제기하더라도 설득력을 유지할 수 있습니다.

Claude Code 서브에이전트가 메모리를 공유하지 않는 이유는 컨텍스트를 공유하지 않기 때문이며, 이러한 격리야말로 핵심 기능입니다. 각 에이전트는 자체 창에서 작동하고 요약만 반환합니다. 메모리 상황은 단순히 "메모리가 없다"고 말하기에는 더 미묘합니다. 에이전트별로 에이전트 이름을 딴 디렉토리에 user, project, local 범위의 영구 메모리를 가질 수 있습니다. 다만 공유되는 영역이 존재하지 않을 뿐입니다. 메인 대화의 자동 메모리는 서브에이전트에 로드되지 않고, 에이전트별 디렉토리는 서로를 읽지 못하며, Explore와 Plan은 CLAUDE.md를 완전히 건너뛰고, 이 모든 것은 단일 머신에만 머무릅니다.

소 격리 상태는 유지하되 공유 방식을 개선해야 합니다. 프로젝트 범위로 에이전트별 메모리를 활성화하고, MEMORY.md를 인덱스로 유지하며, Explore를 규칙을 모르는 상태로 취급하고, 여러 에이전트에게 중요한 지식은 모두가 읽을 수 있는 단일 저장소에 보관하세요. 그러면 두 번째 에이전트가 첫 번째 에이전트가 학습한 내용에서부터 작업을 시작할 수 있으며, 여러분이 직접 서브에이전트 간의 통합 레이어 역할을 할 필요가 없어집니다.