TL;DR
AI 에이전트는 지능이 부족해서가 아니라 잊어버리기 때문에 실패합니다. 네 가지 유형의 에이전트 메모리, 저장 방식, 그리고 API 동작에 미치는 영향을 이해하면 더 신뢰할 수 있는 에이전트를 구축하고 프로덕션에 출시되기 전에 버그를 잡을 수 있습니다.
서론
대부분의 AI 에이전트 실패의 지저분한 비밀은 이렇습니다: 모델은 괜찮습니다. 메모리 계층이 고장난 것입니다.
세 번의 턴 전에 일어난 일을 기억하지 못하거나, 세션 간 사용자 컨텍스트를 잃거나, 작업 중에 스스로를 모순하는 에이전트는 모델 품질 때문에 환각을 일으키는 것이 아닙니다. 메모리 아키텍처가 신중하게 설계되지 않았거나 전혀 테스트되지 않았기 때문에 실패하는 것입니다.
최근에 유행한 오픈소스 에이전트 메모리 시스템인 Hippo는 생물학적으로 영감을 받은 접근 방식을 취합니다: 인간의 기억이 작동하는 방식과 동일하게 단기, 장기, 에피소드 기억을 별도로 모델링합니다. 이 프로젝트는 실제 격차를 드러냈습니다: 대부분의 개발자들은 에이전트 메모리를 나중에 생각하고, 프로덕션에서야 고장 났다는 것을 발견합니다.
AI 에이전트 메모리란 무엇인가요?
에이전트 메모리는 AI 시스템이 현재 입력 외의 정보에 접근하거나 보존할 수 있도록 하는 모든 메커니즘입니다. 이것이 없으면 모든 API 호출은 무상태입니다: 모델은 프롬프트를 받고, 응답을 반환하며, 아무것도 기억하지 못합니다.
네 가지 고유한 메모리 유형은 서로 다른 목적을 수행합니다.
네 가지 유형의 에이전트 메모리
작업 메모리
작업 메모리는 에이전트의 활성 컨텍스트입니다: 현재 프롬프트에 있는 모든 것. 대부분의 LLM 기반 에이전트의 경우, 이는 컨텍스트 윈도우입니다. GPT-4o는 128K 토큰 컨텍스트 윈도우를 가지고 있습니다. Claude 3.5 Sonnet은 200K를 지원합니다. Gemini 1.5 Pro는 1M을 지원합니다.
작업 메모리는 빠르고 정확하지만 비용이 많이 들고(토큰당 지불) 경계가 있습니다. 일단 한도에 도달하면 가장 오래된 컨텍스트는 조용히 삭제됩니다. 이것이 장기 실행 작업에서 에이전트 버그의 가장 흔한 원인입니다.
에피소드 메모리
에피소드 메모리는 일어난 일을 저장합니다: 과거 상호작용, 결정, 관찰의 로그. 에이전트의 일기라고 생각하십시오.
실제로는 일반적으로 벡터 데이터베이스(Chroma, Pinecone, Qdrant) 또는 구조화된 이벤트 로그입니다. 에이전트는 응답을 생성하기 전에 의미론적 검색을 통해 관련 과거 에피소드를 검색합니다. Hippo의 접근 방식은 타임스탬프와 감쇠 가중치를 사용하여 상호작용 시퀀스를 저장하므로 최근 상호작용이 더 높은 검색 우선순위를 얻습니다.
의미 메모리
의미 메모리는 에이전트가 아는 것을 저장합니다: 사실, 도메인 지식, 사용자 선호도 및 안정적인 세계 지식. 에피소드 메모리와 달리 시간 순서가 아닙니다.
이는 미리 로드되거나(사용자 프로필 데이터가 포함된 시스템 프롬프트), 동적으로 구축되거나(과거 대화에서 추출되어 지식 그래프에 저장된 사실), 또는 외부에서 소싱될 수 있습니다(문서 저장소에 대한 RAG).
절차 메모리
절차 메모리는 일을 하는 방법을 저장합니다: 액션 시퀀스, 도구 사용 패턴, 에이전트가 학습한 기술. 이것은 구축하기 가장 어렵고 프로덕션 시스템에서는 종종 건너뛰어집니다.
실제로는 시스템 프롬프트에 포함된 몇 가지 예제 또는 에이전트가 검색하고 적용할 수 있는 저장된 액션 계획 라이브러리로 나타납니다.
실제 시스템에서 메모리가 저장되는 방식
네 가지 유형이 네 개의 개별 저장소에 깔끔하게 매핑되는 경우는 거의 없습니다. 실제 설정은 다음과 같습니다:
컨텍스트 윈도우 (작업): 활성 프롬프트의 모든 것. 에이전트 프레임워크에 의해 관리됩니다. 대화가 끝나면 만료됩니다.
외부 벡터 저장소 (에피소드 + 의미): Chroma, Pinecone 또는 Qdrant는 과거 상호작용 및 지식 덩어리의 임베딩을 저장합니다. 에이전트는 각 턴에서 이를 쿼리하고 관련 덩어리를 프롬프트에 주입합니다.
구조화된 DB (의미 + 절차): 사용자 선호도, 계정 상태 또는 학습된 액션 템플릿을 위한 PostgreSQL 또는 SQLite. 도구 호출을 통해 쿼리됩니다.
인-메모리 캐시 (작업 오버플로): 임베딩 검색이 필요 없는 최근 컨텍스트에 대한 빠른 접근을 위한 Redis 또는 간단한 딕셔너리.
Hippo는 명시적인 핸드오프 로직을 사용하여 3계층 메모리 시스템을 특별히 모델링합니다: 최근에 접근되지 않은 작업 메모리 항목은 에피소드 메모리로 통합되고, 결국 의미 메모리로 요약됩니다. 이는 수면 중 인간의 기억 통합이 작동하는 방식과 유사합니다 (이 프로젝트에는 통합을 트리거하는 "수면" 명령도 있습니다).
에이전트 메모리가 API 동작에 미치는 영향
여기서부터 실질적으로 중요해집니다. 에이전트 API를 구축하거나 사용하고 있다면, 메모리가 API 호출의 모습과 발생할 수 있는 문제에 직접적인 영향을 미칩니다.
세션 ID: 대부분의 에이전트 API는 호출 간에 메모리를 연관시키기 위해 세션 또는 스레드 ID를 사용합니다. OpenAI Assistants API는 thread_id를 사용합니다. 누락되거나 재사용된 스레드 ID는 에이전트가 컨텍스트를 잃거나 두 사용자의 세션을 혼합하게 합니다.
요청 페이로드의 컨텍스트 크기: 메모리를 프롬프트에 주입하는 에이전트는 시간이 지남에 따라 더 큰 요청 본문을 생성합니다. 2KB로 시작한 에이전트 대화는 20턴 후 40KB로 증가할 수 있습니다. HTTP 클라이언트에 페이로드 크기 제한이 있는 경우 요청이 조용히 실패합니다.
검색 지연 시간: 벡터 저장소 조회는 턴당 50-200ms를 추가합니다. API 응답 시간을 단언하고 있다면 메모리 검색이 실제 기여자입니다.
실패 후 일관되지 않은 상태: 에이전트의 도구 호출이 작업 도중에 실패하면 에피소드 로그에 부분적인 액션이 기록될 수 있습니다. 다음 턴은 손상된 상태에서 시작됩니다. 좋은 에이전트는 도구 사용 전후에 상태를 체크포인트합니다.
Apidog로 API를 통해 에이전트 메모리를 테스트하는 방법
스테이트풀 에이전트 API 테스트는 단일 요청 단언 이상의 것을 필요로 합니다. 여러 호출에 걸쳐 컨텍스트가 유지되는지, 메모리 기반 응답이 예상대로 변경되는지, 메모리를 사용할 수 없을 때 시스템이 정상적으로 저하되는지 확인해야 합니다.
Apidog 테스트 시나리오가 바로 이것을 처리합니다. 에이전트 API에 대해 설정하는 방법은 다음과 같습니다.
테스트 1: 컨텍스트 유지
세 가지 순차적 단계로 시나리오를 만듭니다:
- 사실을 소개하는 메시지와 함께
/agent/chatPOST ("내 프로젝트는 PostgreSQL 16을 사용합니다") - 해당 사실을 기억해야 하는 후속 질문과 함께
/agent/chatPOST ("어떤 데이터베이스에 최적화해야 하나요?") - 단계 2의 응답을 단언합니다:
response.message.content는 "PostgreSQL"을 포함해야 합니다
에이전트의 메모리 계층이 작동하면 단계 2는 에피소드 또는 의미 메모리에서 사실을 검색하여 응답에 사용합니다. 그렇지 않으면 일반적인 답변을 받게 됩니다.
테스트 2: 세션 격리
두 단계 시퀀스를 다른 session_id 값으로 두 번 실행합니다. 두 번째 세션의 응답이 첫 번째 세션의 컨텍스트를 포함하지 않는다고 단언합니다. 이는 공유 메모리 버그를 잡아냅니다: 다중 테넌트 에이전트 배포에서 가장 흔하고 디버깅하기 어려운 문제 중 하나입니다.
테스트 3: 메모리 실패 저하
Apidog의 Smart Mock을 사용하여 메모리 백엔드 실패를 시뮬레이션합니다. 목을 구성하여 벡터 저장소 조회 엔드포인트에서 503을 반환하도록 합니다. 그런 다음 에이전트 대화를 실행하고 다음을 단언합니다: - 에이전트가 충돌 없이 응답합니다 - 응답에 정상적인 대체 메시지("그 질문에 답할 충분한 컨텍스트가 없습니다")가 포함됩니다 - 목이 제거된 후에도 세션을 재개할 수 있습니다
테스트 4: 컨텍스트 윈도우 오버플로
작업 메모리가 컨텍스트 한도를 초과하도록 30개 이상의 메시지를 빠르게 연속으로 보냅니다. 다음을 단언합니다: - 에이전트가 context_length_exceeded 오류를 발생시키지 않습니다 (정상적으로 잘려야 합니다) - 30번째 턴의 응답이 에피소드 검색을 사용하여 여전히 올바르게 답변합니다 - response.usage의 토큰 수가 예상 범위 내에 유지됩니다
Apidog에서 이 네 가지를 단일 테스트 시나리오로 실행하여 세션 ID 및 응답 데이터에 대한 공유 변수를 사용하여 순차적으로 연결할 수 있습니다. 컨텍스트 윈도우가 모델 수준에서 작동하는 방식에 대한 배경 지식은 [internal: how-to-build-tiny-llm-from-scratch]를 참조하십시오.
일반적인 메모리 실패 모드
자동 컨텍스트 잘림: 컨텍스트 윈도우가 가득 차고 오래된 메시지가 경고 없이 사라집니다. 에이전트가 불완전한 기록을 기반으로 답변합니다. response.usage.prompt_tokens를 단언하고 모델의 컨텍스트 한도 미만으로 유지되는지 확인하여 이를 파악합니다.
세션 누수: 두 사용자의 세션이 메모리 네임스페이스를 공유합니다. 세션 격리 테스트로 이를 파악합니다.
오래된 의미 메모리: 몇 주 전에 저장된 지식이 현재 사실과 모순됩니다. 에이전트가 자신 있게 잘못된 정보를 제공합니다. 테스트에 "현재 날짜" 단언을 포함하여 이를 파악합니다: 에이전트가 가격이나 버전 번호를 인용하면, 테스트 컨텍스트에 로드된 값과 일치하는지 단언합니다.
임베딩 드리프트: 한 임베딩 모델로 구축된 벡터 저장소가 다른 모델로 전환될 때 손상됩니다. 검색된 모든 문서가 의미론적으로 잘못됩니다. API를 통해 직접 테스트할 수는 없지만, 검색된 컨텍스트가 쿼리와 의미론적으로 관련이 있는지 확인하는 단언을 추가할 수 있습니다.
메모리 주입 프롬프트 주입: 저장되고 검색되는 것을 조작하는 악의적인 사용자 입력. 테스트 스위트에 적대적 입력을 포함합니다: 시스템 프롬프트 재정의가 포함된 "사용자 선호도"를 저장하고 에이전트가 이를 무시하는지 확인합니다. 더 넓은 API 보안 테스트 지침은 [internal: rest-api-best-practices]를 참조하십시오.
결론
에이전트 메모리는 지능적으로 느껴지는 비서와 기억 상실증처럼 느껴지는 비서의 차이점입니다. 작업, 에피소드, 의미, 절차라는 네 가지 유형은 각각 고유한 역할을 합니다. 실제 시스템에서 이러한 메모리가 저장되고 검색되는 방식을 이해하면 버그가 숨어 있을 수 있는 곳과 API 테스트에서 단언해야 할 사항을 정확히 알 수 있습니다.
Hippo와 같은 도구는 원칙적인 메모리 아키텍처를 향한 분야의 움직임을 보여줍니다. 어떤 메모리 시스템을 구축하든 Apidog 테스트 시나리오는 예상대로 작동하는지, 특히 대규모에서만 나타나는 실패 사례를 확인하는 테스트 계층을 제공합니다.
FAQ
에이전트에 메모리를 추가하는 가장 간단한 방법은 무엇인가요?가장 간단한 접근 방식은 대화 기록에 대한 슬라이딩 윈도우입니다: 마지막 N턴을 프롬프트에 유지합니다. 에피소드 메모리는 아니지만 짧은 작업에는 유용합니다. 장기 실행 에이전트의 경우 벡터 저장소와 의미 검색을 추가합니다.
OpenAI Assistants API는 메모리를 어떻게 처리하나요?Assistants API는 서버 측에서 대화 기록을 저장하는 스레드 객체를 관리합니다. 에이전트가 외부 지식에 접근할 수 있도록 파일 검색 및 코드 인터프리터 도구를 연결할 수도 있습니다. 메모리 관리가 추상화되어 있어 편리하지만 디버깅을 더 어렵게 만듭니다.
에이전트 메모리를 위한 최고의 벡터 데이터베이스는 무엇인가요?로컬 개발의 경우: Chroma (인프라 필요 없음). 프로덕션의 경우: 자체 호스팅 또는 관리형 필요 여부에 따라 Qdrant 또는 Pinecone. Hippo 라이브러리는 플러그형 저장소 백엔드를 지원합니다. Claude Code가 자체 메모리 계층을 사용하는 방법에 대한 자세한 내용은 [internal: claude-code]를 참조하십시오.
에이전트가 과거 상호작용을 환각하는 것을 어떻게 방지하나요?메타데이터(타임스탬프, 신뢰도, 출처)와 함께 상호작용 로그를 구조화된 형식으로 저장합니다. 과거 컨텍스트를 검색할 때, 메타데이터를 프롬프트에 포함합니다: " [날짜]의 대화에 따르면, 당신은 X를 언급했습니다." 명시적인 인용은 자신감 있는 환각을 줄입니다.
실행 중인 에이전트 없이 에이전트 메모리를 테스트할 수 있나요?네. Apidog의 Smart Mock을 사용하여 메모리 기반 응답을 포함하여 에이전트의 API 응답을 시뮬레이션합니다. 세션 ID 또는 요청 본문의 내용에 따라 변경되는 목 응답을 정의합니다. 이를 통해 라이브 에이전트 없이 프론트엔드 또는 통합 계층의 메모리 동작 처리를 테스트할 수 있습니다.
프로덕션에서 벡터 저장 비용은 얼마나 드나요?Pinecone의 무료 티어는 10만 개의 벡터를 가진 1개의 인덱스를 지원합니다. 대규모에서는 Pinecone이 p1.x1 포드(1백만 개의 768차원 벡터)에 대해 시간당 약 $0.096를 청구합니다. Qdrant 자체 호스팅은 무료입니다. 대부분의 에이전트의 경우 더 큰 비용은 임베딩 생성이지 저장 비용이 아닙니다. MCP 서버 통합이 에이전트 메모리 시스템과 상호작용하는 방식에 대한 자세한 내용은 [internal: what-is-mcp-server]를 참조하십시오.
RAG와 에이전트 메모리의 차이점은 무엇인가요?RAG(검색 증강 생성)는 쿼리 시 고정된 지식 기반에서 관련 문서를 검색합니다. 에이전트 메모리는 동적입니다: 에이전트가 상호작용함에 따라 성장하고 변화합니다. RAG 시스템은 "문서에 X에 대해 뭐라고 되어 있나요?"라고 답변합니다. 에이전트 메모리 시스템은 "이 사용자에 대해 무엇을 알고 있고 그들과 함께 무엇을 했나요?"라고 답변합니다.