기억하는 에이전트: AgentCore에서 단기 및 장기 메모리 구현하기

agentcore --version   # 0.31.1
aws configure get region   # us-east-1
aws sts get-caller-identity --query Account --output text
...

02-memory/
├── run.py                     # 모든 작업 수행; tests/와 agentcore로 포워딩
├── Makefile                   # run.py로 포워딩하며, 로직은 포함하지 않음
...

"memories": [{
  "name": "aia_uc02_mem",
  "eventExpiryDuration": 30,
...

def remember(self, actor, session_id, turns):
    # ... 실제 코드는 이를 try/except로 감싸고 실패 시 None을 반환합니다.
    event = self.client.create_event(
...

records = store.recall(actor, prompt) if store else []
agent = Agent(
    model=load_model(),
...

make doctor

toolchain
  ... 네 가지 검사: python 3.14.0, node v22.22.2, aws cli 2.15.6, uv 0.11.9 ...

...

make deploy

  배포 대상 로드 ............ 1 ms
  프로젝트 유효성 검사 .................. 682 ms
  CDK 종속성 동기화 ............. 2 ms
...

python3 run.py invoke --session b0b998ab-89ca-4387-99cb-fc01130e9108-ff3568e8 \
  --prompt "지금부터는 북중국 지역만 재배치합니다. 다른 모든 지역은 무시하세요."

명확한 지침에 따라, 저는 북중국 지역만 재배치할 것입니다.
북중국 지역에서는 세 곳의 매장에서 재배치가 필요합니다: 베이징 하이뎬(42개의 보온 텀블러), 톈진 훠핑(17개의 단열 머그컵), 그리고 스자좡 치아오시(8개의 도시락).
...```

두 번째 것은 새로운 세션이며 지역에 대해서는 아무것도 언급하지 않습니다:

두 기록 모두 잘려 있으며, `...`은 모든 잘린 부분을 표시합니다. 또한 스토어 라인에서 모델이 방출한 볼드 마커가 사라졌는데, 이 페이지에서는 볼드로 렌더링됩니다. 두 번째 세션에서는 북중국(North China)에 대한 문장을 본 적이 없었습니다. 출처일 수 있는 유일한 곳은 메모리 리소스였습니다.

[![Terminal capture: a preference written in one session and applied in the next](https://dev.to/images/agentcore-memory-that-remembers/S2-cross-session-recall.png)](/images/agentcore-memory-that-remembers/S2-cross-session-recall.png)

배포(deployment)에 대해 실행되는 검증(assertions):  

1.5초가 필요한 이유는 설명이 필요합니다. 해당 선호도(preference)는 이미 같은 리소스에 대해 이전 실행에서 추출되었기 때문입니다. 에피소드는 새것이었고, 959[ms]가 소요되었습니다.

[![Terminal capture: the three memory assertions and the independence check](https://dev.to/images/agentcore-memory-that-remembers/S3-verify.png)](/images/agentcore-memory-that-remembers/S3-verify.png)

테어다운(Teardown)은 두 단계이며, 두 번째 단계는 삭제합니다:

총 소요 시간(Total Duration)은 이 단계에서 기록되는 배포 로그(`evidence/18-down-deploy.txt`)에서 가져왔으며, 나머지는 콘솔 출력(`evidence/12-down-raw.txt`)입니다.

[![Terminal capture: remove all, the reconciling deploy, and both resources reporting Local only](https://dev.to/images/agentcore-memory-that-remembers/S4-teardown.png)](/images/agentcore-memory-that-remembers/S4-teardown.png)

삭제(Removal)는 로컬 계약(local contract)만 비울 뿐이며, 조정하는 배포(reconciling deploy)가 스택을 파괴합니다. 의도적으로 살아남는 한 가지 것이 있습니다: CDK 부트스트랩 스택과 그 에셋 버킷입니다. 메모리 리소스는 살아남지 않으므로, 재배포(re-deploy)는 비어 있는 상태에서 시작하여 모든 검증을 다시 획득합니다.

## 생성된 결과물

[![The memory resource as two halves: an event log and three namespaces keyed by actor id](https://dev.to/images/agentcore-memory-that-remembers/F1-memory-architecture.png)](/images/agentcore-memory-that-remembers/F1-memory-architecture.png)

측정된 루프, 액터 하나, 세션 두 개:

두 액터가 각각 `/users/store_manager_north/preferences`와 `/users/store_manager_south/preferences`에 기록했습니다. '이 매장 관리자가 어느 지역을 재주문하는지'라는 의미론적 쿼리는 하나에게는 북중국(North China)을, 다른 하나에게는 남중국(South China)을 반환했고, 모델에게 '이번 주 재주문 목록 초안 작성.'이라고 요청하자 남부 매니저에게는 남중국이 나왔습니다. 액터 ID가 키의 일부이기 때문에 잘못된 필터링은 없습니다.

세 번째 단언은 저에게 무언가를 가르쳐 주었습니다. 에피소드 추출(Episodic extraction)은 느립니다. 에피소드는 발생한 사건으로부터 약 15분 후에 작성되었습니다. 이것이 고장 난 전략은 아니며, 단지 더 느린 대기열일 뿐이며, 300초의 마감 시간은 그것에 의해 실패할 수밖에 없습니다.

`/episodes/store_manager_north/`에 대한 접두사 읽기는 두 가지 종류의 기록을 반환합니다: 해당 세션 아래에 파일된 `BASE` 에피소드와, 그 모든 것을 아우르는 한 단계 위에서 작성된 `REFLECTION`입니다. 이것이 하나의 템플릿에는 `{sessionId}`가 있고 다른 하나에는 없는 이유입니다:

한 번 추적된 호출에서 측정된 비용은, 두 모델 호출에 걸쳐 3,433개의 입력 토큰과 210개의 출력 토큰이었으며, 이는 각각 백만 토큰당 0.62달러와 1.85달러를 기준으로 0.0025달러입니다. 메모리 저장 및 추출 호출은 별도로 청구되므로, 저는 그 부분을 측정하지 않았습니다.

## 문제 해결 (Troubleshooting)

-   `Invalid length for parameter runtimeSessionId, value: 22, valid min length: 33`. 짧고 읽기 쉬운 세션 ID는 괜찮아 보이며 전송되기 전에 실패합니다. 이제 스모크 테스트는 두 개의 uuid4 절반으로 ID를 생성하는데, 이는 16진수(hex) uuid가 32자이므로 최소 길이보다 한 글자가 부족하기 때문입니다.
-   `no episodic record ... within 1500s`. 고장 난 전략이 아니라 단지 느린 대기열일 뿐입니다. 마감 시간을 관찰된 15분 이상으로 늘리고, 실제로 기다리는 시간이 얼마나 걸렸는지 출력하여 기사에 있는 숫자가 측정값임을 보여주세요.

## 주요 시사점 (Takeaways)

메모리(Memory)는 하나가 아니라 두 가지 메커니즘으로 구성됩니다. 직접 작성하는 이벤트 로그와 서비스 추출 기록입니다. 새 세션에서는 후자만 살아남습니다.

액터 ID를 네임스페이스 템플릿 안에 넣어주세요. 이렇게 하면 격리가 비용이 들지 않으며, 코드 경로에서 잊어버릴 염려가 없습니다.

추출(Extraction) 과정은 비동기적이고 느립니다. 에피소드당 15분 정도 걸립니다. 모든 단언(assertion)에는 마감 기한(deadline)이 필요하며, 이 마감 기한은 생각하는 것보다 길어야 합니다.

검색(Retrieval)은 모델 호출 전에 시스템 프롬프트에 포함되어야 하며, 모델이 선택할 수도 있고 아닐 수도 있는 도구(tool) 안에 넣으면 안 됩니다.

해체(Teardown)는 실제 과정입니다. `remove all`은 계약을 비우고, 그 뒤에 배포되는 것이 삭제를 수행합니다.