Claude Managed Agents Memory 살펴보기: 세션 밖까지 이어지는 에이전트 메모리

Managed Agents의 에이전트는 세션이 끝나면 그 세션에서 배운 내용을 잃습니다. 사용자 선호, 프로젝트 규칙, 지난번 판단의 이유 같은 맥락이 끊기므로, 다음 세션에서 처음부터 다시 설명해야 합니다.

Anthropic이 공개한 Using agent memory ↗ 문서는 이 문제를 memory store로 해결합니다. 세션 밖에 남는 텍스트 저장소를 세션에 붙이고, 에이전트가 다음 세션에서도 같은 파일을 읽고 쓰게 합니다.

이 글은 작성 시점 2026-04-25의 공식 문서 managed-agents/memory 스냅숏을 기준으로 합니다. memory store는 대화 기록을 저장하지 않고, 에이전트가 다루는 파일 시스템에 영속 메모리를 마운트합니다. 이 글에서는 memory store가 무엇인지, 세션에 어떻게 붙는지, 무엇을 조심해야 하는지 정리합니다.

memory store는 무엇인가요?

문서 기준으로 memory store는 워크스페이스 범위의 텍스트 문서 모음입니다. 세션에 이 store를 붙이면 세션 컨테이너 안에 디렉터리로 마운트됩니다. 에이전트는 평소 쓰던 파일 도구로 이 디렉터리를 읽고 씁니다. (공식 문서 ↗)

에이전트는 별도 메모리 API를 쓰지 않습니다. memory store는 파일로 보이고, 파일처럼 다룹니다. 그래서 에이전트는 사용자 선호, 프로젝트 규칙, 과거 작업 메모를 문서 파일처럼 읽고 갱신합니다.

store 안의 각 memory는 path 기반으로 관리됩니다. /preferences/formatting.md 같은 개별 파일을 만들고, API나 Console에서 직접 읽고 수정할 수도 있습니다. (공식 문서 ↗)

세션이 바뀌어도 맥락이 이어집니다

Managed Agents 세션은 기본적으로 fresh context로 시작합니다. 세션이 끝나면 그 세션에서 배운 내용도 같이 사라집니다. Memory store를 붙이면 사용자 취향, 도메인 지식, 팀 규칙, 이전 실수를 다음 세션으로 이어갈 수 있습니다. (공식 문서 ↗)

Claude Code Memory도 같은 문제를 다룹니다. Claude Code Memory는 로컬과 프로젝트 문맥을 계층 구조로 관리합니다. memory store는 Managed Agents API에서 세션 리소스로 붙는 영속 저장소입니다.

flowchart TD
    A[세션 1] --> B["/mnt/memory/ store에 기록"]
    C[세션 2] --> B
    D[세션 3] --> B
    B --> E[사용자 선호]
    B --> F[프로젝트 규칙]
    B --> G[이전 실수와 맥락]

어떻게 만들고 붙이나요?

과정은 세 단계입니다.

1. memory store를 생성합니다.
2. 필요하면 초기 문서를 seed합니다.
3. 세션 생성 시 resources[]에 memory store를 붙입니다.

1) store 생성

store에는 name과 description이 들어갑니다. description은 에이전트에게 이 store가 무엇을 담는지 알려주는 설명으로도 쓰입니다. (공식 문서 ↗)

// from: https://platform.claude.com/docs/en/managed-agents/memory
const store = await client.beta.memoryStores.create({
  name: "User Preferences",
  description: "Per-user preferences and project context.",
});

2) 초기 문서 seed

세션을 실행하기 전에 포맷 규칙, 도메인 용어집, 팀 컨벤션 같은 참고 문서를 미리 넣어둘 수 있습니다. (공식 문서 ↗)

// from: https://platform.claude.com/docs/en/managed-agents/memory
await client.beta.memoryStores.memories.create(store.id, {
  path: "/formatting_standards.md",
  content: "All reports use GAAP formatting. Dates are ISO-8601...",
});

3) 세션 생성 시 attach

memory store는 세션 생성 시점에만 붙일 수 있습니다. 파일 리소스나 repository 리소스와 달리, 실행 중인 세션에 나중에 추가하거나 제거할 수 없습니다. (공식 문서 ↗)

// from: https://platform.claude.com/docs/en/managed-agents/memory
const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "memory_store",
      memory_store_id: store.id,
      access: "read_write",
      instructions:
        "User preferences and project context. Check before starting any task.",
    },
  ],
});

에이전트는 실제로 이 메모리를 어떻게 보나요?

붙은 memory store는 세션 컨테이너 안의 /mnt/memory/ 아래 디렉터리로 마운트됩니다. 마운트 경로, access mode, store description, 세션별 instructions는 system prompt에 자동으로 추가됩니다. 그래서 에이전트는 어디를 봐야 하는지 system prompt에서 확인합니다. (공식 문서 ↗)

memory store를 쓰려면 agent toolset이 켜져 있어야 합니다. memory store는 파일로 다뤄지므로, 도구 문서 ↗ 기준으로 agent_toolset_20260401 안의 read, write, edit 같은 기본 파일 도구가 필요합니다. Agent 생성 단계에서 tools를 너무 좁게 제한하면 memory store를 붙여도 에이전트가 읽거나 쓰지 못할 수 있습니다. (agent tools 문서 ↗, agent setup 문서 ↗)

읽기와 쓰기는 이벤트 스트림에서도 보입니다. 문서 기준으로 memory mount를 다루는 작업에는 전용 이벤트가 없습니다. 일반적인 agent.tool_use와 agent.tool_result 이벤트로 나타납니다. 모니터링할 때도 파일 작업의 한 종류로 추적합니다. (events and streaming 문서 ↗, memory 문서 ↗)

기본값 read_write는 prompt injection에 노출됩니다

문서는 보안 경고를 따로 둡니다. memory store는 기본적으로 read_write로 붙습니다. 이때 에이전트가 신뢰할 수 없는 입력을 다루면 문제가 생깁니다. 사용자 프롬프트, 웹에서 가져온 문서, 서드파티 도구 출력에 prompt injection이 숨어 있으면 그 내용이 store에 써질 수 있습니다. 그러면 이후 세션이 그 악성 내용을 “기억”으로 다시 읽습니다. (공식 문서 ↗)

prompt injection은 보통 현재 세션에만 영향을 줍니다. memory store가 있으면 오염이 세션 간 persistent contamination으로 번질 수 있습니다.

store는 성격별로 나눌 수 있습니다.

• 공유 규칙/지식 저장소: read_only
• 세션이나 사용자별 작업 메모: read_write
• 검수 전 수집 메모: 가능하면 분리 저장

문서도 이런 분리를 권합니다. 공용 reference material은 여러 세션에 read-only로 공유하고, 사용자별·팀별·프로젝트별 store는 따로 둡니다. (공식 문서 ↗)

versioning과 audit trail도 들어 있습니다

Memory store의 각 변경은 immutable한 memory version을 남깁니다. 에이전트가 무엇을 썼는지 이력으로 추적하고, 특정 시점으로 복구(point-in-time recovery)할 수 있습니다. (공식 문서 ↗)

에이전트가 장기 메모리를 직접 수정한다면, 무엇이 언제 어떻게 바뀌었는지 볼 수 있어야 운영할 수 있습니다. 잘못된 메모리가 들어가면 교정하고, 필요하면 이전 상태로 되돌려야 합니다.

memory를 켜면 메모리 품질 관리라는 운영 과제가 생깁니다. Managed Agents를 운영한다면 versioning으로 변경 이력을 검토하는 절차를 둡니다.

크기 제한과 구조화 팁

문서 기준으로 개별 memory는 100KB, 대략 25K tokens로 제한됩니다. 그래서 Anthropic은 큰 파일 몇 개보다 작고 집중된 파일 여러 개로 나누라고 권합니다. (공식 문서 ↗)

메모리를 하나의 큰 memory.md에 몰아넣지 않고 성격별로 나누면 읽기 쉽고 오염된 부분만 격리하기도 쉽습니다.

예를 들면 다음과 같이 나눕니다.

/preferences/
/project/
/mistakes/
/domain/

이렇게 나누면 에이전트는 필요한 부분만 읽고, 사람은 API로 해당 부분만 검토하거나 수정합니다.

몇 개까지 붙일 수 있나요?

세션당 최대 8개의 memory store를 붙일 수 있습니다. 문서는 여러 store를 붙이는 이유로 다음을 듭니다. (공식 문서 ↗)

• 공유 reference material과 개인 메모리를 분리하고 싶을 때
• 사용자, 팀, 프로젝트 구조에 맞춰 owner를 나누고 싶을 때
• 보존 주기나 archive 정책이 다른 메모리를 분리하고 싶을 때

store를 여러 개 붙이면 권한, 수명주기, 책임 경계를 store 단위로 나눌 수 있습니다.

flowchart TD
    A[세션 생성] --> B[공용 규칙 store]
    A --> C[사용자별 store]
    A --> D[프로젝트별 store]
    B --> E[read_only]
    C --> F[read_write]
    D --> G[read_write 또는 read_only]

이 기능을 어디에 쓰면 좋을까

memory store는 다음 경우에 맞습니다.

1) 사용자별 선호를 누적할 때

보고서 형식, 말투, 금지 표현, 선호 워크플로우를 사용자별 store에 두면 세션마다 반복해서 설명하지 않아도 됩니다.

2) 프로젝트 규칙을 살아있는 문서처럼 다룰 때

코드 스타일, 배포 체크리스트, 자주 실수하는 패턴을 프로젝트 store에 두고, 에이전트가 실행 중 갱신하게 할 수 있습니다.

3) 공용 지식과 개인 메모를 분리할 때

팀 공통 기준은 read-only store에, 세션이나 담당자별 학습 내용은 read-write store에 둡니다.

반대로 웹에서 가져온 내용이나 외부 입력을 검수 없이 장기 메모로 저장하면 위험합니다. 이 경우 memory store는 오래 남는 오염 저장소가 됩니다.

마무리

Claude Managed Agents의 memory store는 세션 밖에 남는 파일 기반 메모리를 컨테이너에 마운트합니다. 세션이 바뀌어도 사용자 선호, 프로젝트 규칙, 과거 맥락을 이어갈 수 있습니다. (공식 문서 ↗)

기본값이 read_write이므로, prompt injection이 store를 오염시키면 그 내용이 다음 세션의 기억으로 이어질 수 있습니다. memory store를 켜기 전에 무엇을 어떤 권한으로 어떤 구조에 저장할지 먼저 설계합니다.

Managed Agents를 실제 제품에 붙인다면 read-only와 read-write store를 나누고, 작은 파일로 구조화하고, versioning으로 검수 절차를 둡니다.

관련 글:

• Claude Code Memory 완벽 가이드
• Claude Code Agent Teams 완벽 가이드
• Claude Code Routines 살펴보기