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

Managed Agents를 보다 보면 금방 드는 생각이 있습니다. 한 세션 안에서는 꽤 똑똑한데, 세션이 끝나면 배운 걸 다 놓쳐버린다는 점입니다. 사용자 선호, 프로젝트 규칙, 지난번에 왜 그런 판단을 했는지 같은 맥락이 끊기면 결국 다음 세션에서 또 처음부터 설명해야 하죠.

Anthropic이 공개한 Using agent memory ↗ 문서는 이 지점을 memory store로 풉니다. 세션 밖에 남는 텍스트 저장소를 붙여서, 에이전트가 다음 세션에서도 같은 파일을 읽고 쓰게 하는 방식입니다.

작성 시점 2026-04-25 · 공식 문서 managed-agents/memory 스냅숏 기준으로 보면, 이 기능은 단순한 “대화 기록 저장”보다 에이전트가 다루는 파일 시스템에 영속 메모리를 마운트하는 구조에 더 가깝습니다. 이 글에서는 memory store가 정확히 무엇인지, 세션에 어떻게 붙는지, 그리고 어디를 특히 조심해서 봐야 하는지 정리해보겠습니다.

memory store는 무엇인가요?

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

즉 핵심은 “Claude가 특별한 메모리 API만 따로 쓴다”가 아닙니다. 오히려 파일처럼 보이고, 파일처럼 다룬다는 쪽에 가깝습니다. 그래서 에이전트는 사용자 선호, 프로젝트 규칙, 과거 작업 메모를 그냥 문서 파일 다루듯이 읽고 갱신할 수 있습니다.

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

왜 이 방식이 중요한가요?

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

이건 예전에 정리했던 Claude Code Memory와 닮은 문제를 Managed Agents 쪽에서 푸는 방식이라고 볼 수 있습니다. 다만 Claude Code Memory가 로컬과 프로젝트 문맥의 계층 구조에 가까웠다면, 이번 memory store는 Managed Agents API에서 세션 리소스로 붙는 영속 저장소라는 점이 다릅니다. 더 넓게 보면 Claude Code Agent Teams나 Claude Code Routines처럼, 에이전트를 일회성 채팅이 아니라 누적 학습 가능한 작업 단위로 다루려는 흐름과도 이어집니다.

flowchart LR
    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에 자동으로 추가됩니다. 즉 에이전트는 “어디를 봐야 하는지”를 시스템 레벨에서 안내받습니다. (공식 문서 ↗)

여기서 중요한 전제는 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 기본값은 편하지만, 꽤 위험합니다

이 문서에서 가장 눈에 띄는 대목 중 하나는 보안 경고입니다. 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) 관점에서 추적할 수 있습니다. (공식 문서 ↗)

이건 단순 편의 기능 이상입니다. 에이전트가 장기 메모리를 직접 수정하는 구조에서는, “무엇이 언제 어떻게 바뀌었는지”를 볼 수 있어야 운영이 됩니다. 잘못된 메모리가 들어갔을 때 교정하고, 필요하면 이전 상태로 되돌리는 장치가 있어야 하니까요.

Managed Agents를 진지하게 운영한다면 이 versioning은 사실상 필수에 가깝습니다. memory를 켜는 순간 편의성과 함께 메모리 품질 관리라는 새로운 운영 과제가 생기기 때문입니다.

크기 제한과 구조화 팁

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

이건 꽤 중요한 팁입니다. 메모리를 무작정 하나의 거대한 memory.md에 몰아넣기보다, 성격별로 쪼개는 편이 읽기 쉽고 오염 격리도 쉽습니다.

예를 들면 이런 구조가 더 자연스럽습니다.

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

이렇게 해두면 에이전트도 필요한 부분만 읽기 쉽고, 사람이 API로 검토하거나 수정할 때도 훨씬 다루기 편합니다.

몇 개까지 붙일 수 있나요?

세션당 최대 8개의 memory store를 붙일 수 있습니다. 문서가 제안하는 대표적인 이유도 꽤 실무적입니다. (공식 문서 ↗)

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

즉 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를 오염시키면 그게 다음 세션의 기억처럼 이어질 수 있기 때문입니다. 그래서 이 기능의 핵심은 메모리를 “많이 저장하는 것”보다 무엇을 어떤 권한으로 어떤 구조에 저장할지 설계하는 것에 있다고 봅니다.

Managed Agents를 실제 제품에 붙일 생각이라면, memory store는 거의 필수에 가깝습니다. 다만 그만큼 운영 감각도 같이 필요합니다. 특히 read-only와 read-write를 나누고, 작은 파일로 구조화하고, versioning을 활용해 검수 루프를 두는 쪽이 훨씬 안정적으로 보입니다.

관련 글도 같이 보면 흐름이 이어집니다.

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