Build agent memory with NVIDIA NeMo Agent Toolkit and Amazon S3 Vectors

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

NVIDIA NeMo Agent Toolkit(NAT)에 Amazon S3 Vectors를 영구 메모리로 연결하는 구현을 설명하며, Amazon EKS 배포를 목표로 제시하지만 제공된 본문은 워크플로 설정 설명 중간에서 끝난다.

📌 핵심 요약

• NVIDIA NeMo Agent Toolkit(NAT)은 프레임워크에 종속되지 않는 오픈 소스 에이전트 프레임워크로, 오케스트레이션·프로파일링·평가·최적화를 제공한다. 글은 다중 에이전트 투자 리서치를 예제로 삼아 Amazon S3 Vectors를 영구 메모리로 연결하고 Amazon EKS에서 운영하는 구성을 소개한다.
• NAT의 메모리 백엔드는 MemoryEditor의 add_items(), search(), remove_items()를 구현한다. MemoryItem은 대화·태그·메타데이터·user_id·선택적 메모리 문자열을 담고, auto_memory_agent는 에이전트를 감싸 메모리 저장과 검색을 자동화한다.
• Amazon S3 Vectors는 의미 기반 검색, 메타데이터 필터링, 쓰기 직후 조회 가능한 강한 일관성, 인덱스당 최대 20억 개 벡터를 지원한다. 비용은 저장·쓰기·쿼리에 따라 부과되며 유휴 컴퓨팅 비용은 없고, 버킷·인덱스별 IAM 정책과 테넌트별 인덱스로 접근 통제와 격리를 구성할 수 있다.
• 구현은 벡터 버킷·인덱스 생성, 사용자 정의 MemoryEditor 플러그인 구현, NAT 워크플로 설정의 세 단계다. 예제는 Amazon Titan Text Embeddings V2의 1024차원 임베딩, float32, cosine 거리, 기본 검색 결과 5개를 사용하며, content를 필터 불가 메타데이터로 지정하고 저장 내용을 1024자로 제한한다.
• 검색은 agent_id·memory_type·ticker·team_id·user_id·is_shared 메타데이터 조건을 지원하고, 삭제는 키 목록으로 수행한다. YAML은 auto_memory_agent로 사용자·에이전트 메시지 저장과 매 응답의 메모리 검색을 활성화하며, anthropic.claude-sonnet-4-20250514와 temperature 0.3을 지정한다. 제공된 본문에는 실제 Amazon EKS 배포 절차나 검증 결과가 포함되어 있지 않다.

🧩 주요 포인트

1. MemoryEditor 플러그인과 auto_memory_agent의 결합 → 저장 백엔드 구현과 에이전트의 자동 기억 동작을 연결하는 확장 지점을 제공한다.
2. 강한 쓰기 일관성·메타데이터 필터·인덱스당 최대 20억 개 벡터 → 다중 에이전트의 기억 공유, 검색 범위 제한, 대규모 저장 요구에 대응하는 근거로 제시된다.
3. 차원 임베딩과 1024자 content 제한, Amazon EKS 배포 설명의 부재 → 구현 설정의 정합성과 검색으로 복원되는 정보의 범위를 확인할 수 있지만 운영 배포까지 검증된 것으로 볼 수는 없다.

🧠 상세 정리

1. 메모리 아키텍처에서 NAT 구현으로의 전환

글은 이전 글에서 메모리 엔지니어링을 프로덕션 다중 에이전트 시스템의 기반으로 설명했다는 배경에서 출발하며, 이번에는 Amazon S3 Vectors를 NVIDIA NeMo Agent Toolkit(NAT)에 연결하는 구현으로 논의를 옮긴다. 운영 환경으로는 완전한 운영 통제를 위한 Amazon EKS를 제시하고, 다중 에이전트 투자 리서치를 진행 예제로 삼겠다고 밝힌다. NAT은 오픈 소스이며 Strands Agents, LangChain, LlamaIndex, CrewAI와 사용자 정의 구현을 지원하는 프레임워크 비종속 도구다. 에이전트는 LLM·도구·프롬프트를 설정할 수 있는 조합 가능한 워크플로로 정의하며, nat run으로 로컬 실행하거나 nat serve로 지속 실행 서비스를 구성한다. 프로파일링은 토큰 사용량·지연·처리량·실행 시간을 추적하고, 평가는 답변 정확도·문맥 관련성·응답의 근거성·에이전트 수행 경로를 다룬다. 최적화는 temperature, top_p, max_tokens의 자동 조정을 통해 품질을 높이면서 비용과 지연을 줄이는 기능으로 소개된다.

2. NAT 메모리 모듈의 인터페이스와 확장 방식

NAT의 전용 메모리 모듈은 에이전트 호출 사이에 대화 이력, 사용자 선호, 장기 지식을 저장하고 검색하도록 설계되어 있다. 모든 백엔드는 추상 인터페이스인 MemoryEditor를 구현해야 하며, 필수 메서드는 add_items(), search(), remove_items()의 세 가지다. 기억 한 건을 표현하는 MemoryItem에는 대화 이력, 태그, 메타데이터, user_id와 선택적인 텍스트 메모리 필드가 포함된다. 사용자 정의 설정은 Pydantic 기반 MemoryBaseConfig를 확장하고, NAT은 YAML의 _type 필드로 해당 공급자를 찾는다. auto_memory_agent는 에이전트를 감싸 자동 저장과 검색을 수행하므로 LLM이 메모리 도구를 명시적으로 호출할 필요가 없다. 내장 공급자로 Mem0, MemMachine, Redis, Zep을 소개한 뒤, 탄력적인 벡터 저장과 강한 쓰기 일관성, 수십억 개 벡터까지의 비용 효율적인 확장이 필요한 경우에는 Amazon S3 Vectors 기반 사용자 정의 공급자가 적합하다고 주장한다.

3. Amazon S3 Vectors를 선택하는 근거

Amazon S3 Vectors는 Amazon S3의 기능으로, 에이전트 메모리에 필요한 의미 기반 검색과 풍부한 메타데이터, 강한 일관성, 탄력적인 규모 확장을 제공하는 저장 계층으로 제시된다. 벡터 유사도 검색에는 cosine과 euclidean 거리 지표를 설정할 수 있고, 문자열·숫자·불리언·목록 형태의 메타데이터로 검색 범위를 제한할 수 있다. 강한 쓰기 일관성은 삽입 직후 기억을 조회할 수 있다는 특성으로 설명되며, 여러 에이전트가 기억을 공유하는 요구와 연결된다. 규모 측면에서는 별도의 용량 계획 없이 인덱스당 최대 20억 개 벡터를 지원한다고 명시한다. 비용은 저장·쓰기·쿼리에 대해서만 지불하고 유휴 컴퓨팅 비용은 없다는 점을 근거로 든다. 접근 통제는 버킷과 인덱스별 AWS Identity and Access Management(IAM) 정책으로 구성하며, 테넌트별 인덱스는 강한 격리를 위한 선택지로 소개한다.

4. 실습 전제와 적용 범위

실습에는 Amazon S3 Vectors 리소스와 Amazon EKS 클러스터를 생성할 권한이 있는 AWS 계정이 필요하며, 별도로 기존 Amazon EKS 클러스터도 준비 조건으로 제시된다. NVIDIA NeMo Agent Toolkit은 설치되어 있어야 하고, 본문의 구현은 버전 1.6에서 시험했다고 밝힌다. Python 준비 버전은 3.11 또는 3.12이며, NAT 자체의 요구 범위는 3.11 이상·3.14 미만으로 구분해 적고 있다. 벡터 표현을 생성할 임베딩 모델도 필요하며, 이 글에서는 Amazon Titan Text Embeddings V2를 사용한다. 컨테이너와 클러스터 작업에는 kubectl과 Docker를 요구한다. 이러한 조건은 독자가 구현을 따라가기 위한 환경 전제이며, 제공된 본문만으로 Amazon EKS 클러스터 생성이나 전체 배포 과정까지 확인할 수 있는 것은 아니다.

5. 벡터 버킷과 인덱스 생성

구현의 첫 단계는 에이전트 메모리를 저장할 Amazon S3 Vectors 버킷과 인덱스를 생성하는 것이다. 예제는 us-west-2 리전에 boto3의 s3vectors 클라이언트를 만들고, 버킷 이름을 amzn-s3-demo-research-agent-memory, 인덱스 이름을 agent-long-term-memory로 지정한다. create_vector_bucket으로 버킷을 만든 다음 create_index로 인덱스를 생성하는 순서다. 인덱스의 데이터 형식은 float32이고 차원 수는 Amazon Titan Text Embeddings V2의 출력에 맞춘 1024이며, 거리 지표는 cosine으로 설정한다. 큰 내용 필드인 content는 nonFilterableMetadataKeys에 넣어 필터에 사용할 수 없는 메타데이터로 지정한다. 이 저장 구조를 만든 뒤에 해당 버킷과 인덱스를 읽고 쓰는 메모리 공급자를 구현하는 흐름으로 이어지며, 차원 설정은 뒤의 임베딩 생성 코드와 동일하게 맞춰져 있다.

6. 메모리 저장 플러그인과 메타데이터 구성

두 번째 단계에서는 S3VectorsMemoryConfig와 S3VectorsMemoryEditor를 정의하고, 설정에 버킷·인덱스·AWS 리전·기본 검색 결과 수를 둔다. 기본 리전은 us-west-2, default_top_k는 5이며, 편집기는 s3vectors와 bedrock-runtime 클라이언트를 생성한다. 임베딩은 amazon.titan-embed-text-v2:0을 호출해 1024차원으로 생성하고 normalize를 true로 설정한다. add_items()는 MemoryItem의 memory가 있으면 이를 사용하고, 없으면 conversation을 JSON 문자열로 변환해 임베딩하며, 키에는 user_id와 UUID 일부를 넣어 같은 초에 생성되는 키의 충돌을 방지하도록 구성한다. 메타데이터에는 user_id, memory_type, agent_id, team_id, task_id, confidence, 생성 시각, is_shared, source, content를 담고 ticker가 있으면 추가한다. 기본값은 memory_type이 episodic, confidence가 0.8, is_shared가 true, source가 agent이며, 메타데이터 값의 크기 제한을 고려해 content는 앞의 1024자만 저장하고 put_vectors로 기록한다.

7. 의미 검색, 삭제와 NAT 공급자 등록

search()는 검색 문자열을 저장 때와 같은 모델로 임베딩하고, 전달된 top_k 또는 기본값 5를 검색 결과 수로 사용한다. 메타데이터 조건은 agent_id, memory_type, ticker, team_id, user_id에 대한 동등 비교로 구성하며, is_shared의 불리언 조건도 지원한다. 이 조건을 query_vectors의 필터로 전달하고 returnMetadata를 true로 설정해 관련 기억의 메타데이터를 함께 가져온다. 반환된 벡터는 대화 이력이 비어 있는 MemoryItem으로 변환되며, memory_type은 태그로, content는 메모리 문자열로 복원된다. remove_items()는 전달된 keys 목록이 있을 때 delete_vectors를 호출하는 방식으로 삭제를 처리한다. 마지막으로 register_memory 데코레이터에 S3VectorsMemoryConfig를 연결하고 빌더 함수에서 편집기를 제공해 NAT이 공급자를 찾도록 하며, 본문은 이 플러그인이 임베딩 생성·범위 메타데이터 저장·검색 조건 변환을 담당한다고 정리한다.

8. 자동 메모리 워크플로 설정과 본문의 경계

세 번째 단계의 YAML은 agent_memory의 _type을 s3vectors_memory로 지정하고 앞서 만든 버킷·인덱스와 us-west-2 리전을 연결한다. 함수 설정에는 중요한 발견을 저장하는 add_memory와 조사 전에 기존 지식을 검색하는 get_memory를 두며, web_search와 financial_data_api도 함께 기재한다. 워크플로는 auto_memory_agent를 사용하고 inner_agent_name을 research_agent, memory_name을 agent_memory, llm_name을 bedrock_llm으로 지정한다. save_user_messages_to_memory, retrieve_memory_for_every_response, save_ai_messages_to_memory를 모두 true로 설정해 사용자 메시지와 에이전트 응답의 저장 및 매 응답의 기억 검색을 활성화한다. LLM 설정은 bedrock 유형에 anthropic.claude-sonnet-4-20250514 모델과 temperature 0.3을 사용한다. 제공된 본문은 자동 메모리 래퍼의 동작을 설명하다 문장 중간에서 끝나므로, research_agent의 상세 정의나 실제 Amazon EKS 배포 절차, 투자 리서치 실행 결과는 이 자료에서 확인되지 않는다.

🧾 핵심 주장 / 시사점

• MemoryEditor와 auto_memory_agent는 각각 저장 백엔드 확장과 자동 기억 동작을 맡아, Amazon S3 Vectors를 NAT의 기존 메모리 구조에 연결하는 방식을 보여준다.
• 메타데이터 필터는 기억의 검색 범위를 좁히고, IAM 정책과 테넌트별 인덱스는 접근 통제와 격리를 구성하는 수단으로 제시된다.
• 예제는 원문 전체를 임베딩하면서 반환할 content는 1024자로 제한하므로, 검색에 사용되는 텍스트와 검색 후 복원되는 텍스트의 길이가 달라질 수 있다.

✅ 액션 아이템

• MemoryEditor의 add_items(), search(), remove_items()와 auto_memory_agent를 연결하는 사용자 정의 메모리 공급자 구성을 검토한다.
• Amazon Titan Text Embeddings V2의 1024차원 설정과 인덱스 설정의 일치 여부, 1024자 content 제한이 기억 복원에 미치는 영향을 확인한다.
• auto_memory_agent의 메시지 저장·매 응답 검색 설정을 확인하고, 제공된 본문에 없는 Amazon EKS 배포 절차와 검증 결과를 추가로 확인한다.

❓ 열린 질문

• agent_id·team_id·user_id·is_shared 검색 조건은 다중 에이전트 투자 리서치에서 어떤 기억 공유 범위를 구성하는가?
• 1024자 content 제한은 검색된 기억을 복원할 때 필요한 정보의 범위에 어떤 영향을 미치는가?
• Amazon EKS에서 NAT과 Amazon S3 Vectors를 운영하기 위한 실제 배포 절차와 검증 결과는 무엇인가?