Rihpig

Posted on Apr 7 • Originally published at apidog.com

AI 에이전트 메모리 작동 방식 및 API 테스트 방법

TL;DR

AI 에이전트는 지능이 부족해서가 아니라 메모리를 잃어버려서 실패합니다. 네 가지 유형의 에이전트 메모리와 저장 방식, 그리고 이것이 API 동작에 미치는 영향을 이해하면 더 신뢰할 수 있는 에이전트를 만들고 프로덕션 이전에 버그를 잡을 수 있습니다.

오늘 Apidog을 사용해보세요

서론

대부분의 AI 에이전트가 실패하는 핵심 원인은 모델이 아니라 메모리 계층의 문제입니다.

세 번 전 대화를 기억하지 못하거나, 세션 간 사용자 컨텍스트를 잃거나, 답변 도중 스스로를 모순하는 에이전트는 모델 품질 문제가 아니라 메모리 아키텍처가 부실하거나 테스트되지 않았기 때문입니다.

최근 오픈소스 에이전트 메모리 시스템인 Hippo는 생물학에서 영감을 받아 단기, 장기, 에피소드 메모리를 별도로 모델링합니다. 이 프로젝트는 실제로 대부분의 개발자가 메모리 문제를 뒤늦게 발견한다는 점을 보여줍니다.

💡 팁: Apidog의 테스트 시나리오를 사용하면 상태를 유지하는 다중 턴 에이전트 대화를 서비스 적용 전 테스트할 수 있습니다. API 호출 간 세션 상태 유지, 컨텍스트 구조 단언, Smart Mock으로 메모리 오류 시뮬레이션이 가능합니다. 이 테스트 계층은 본문 후반부에서 다룹니다. 먼저 에이전트 메모리 내부 구조부터 살펴보겠습니다. 더 넓은 테스트 접근법은 [internal: api-testing-tutorial]을 참고하세요.

AI 에이전트 메모리란 무엇인가요?

에이전트 메모리는 AI가 현재 입력 외의 정보를 보존·활용할 수 있게 하는 모든 메커니즘입니다. 이게 없다면 모든 API 호출은 무상태로 동작합니다.

에이전트 메모리는 네 가지 유형이 있으며, 각각 목적이 다릅니다.

네 가지 유형의 에이전트 메모리

작업 메모리

작업 메모리는 에이전트의 활성 컨텍스트, 즉 현재 프롬프트에 포함된 모든 것입니다. LLM 기반 에이전트에서는 컨텍스트 윈도우가 여기에 해당합니다.

예시: GPT-4o (128K 토큰), Claude 3.5 Sonnet (200K), Gemini 1.5 Pro (1M)
특징: 빠르고 정확하지만 비용이 높고(토큰당 과금), 한도가 있습니다. 한도를 넘으면 가장 오래된 컨텍스트가 삭제됩니다. 장기 작업에서 버그의 주요 원인입니다.

에피소드 메모리

에피소드 메모리는 과거 상호작용, 결정, 관찰의 로그입니다.

실제 구현: 벡터 DB(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 사용은 컨텍스트 손실·섞임 유발.
요청 페이로드 크기: 프롬프트에 메모리 주입 시 대화가 길어질수록 본문이 커짐. 페이로드 제한을 초과하면 요청 실패 가능.
검색 지연: 벡터 저장소에서 검색 시 턴당 50~200ms 지연. 응답 시간 단언 시 주의.
실패 후 비일관 상태: 도구 호출 실패 시 에피소드 로그에 부분 액션 기록. 다음 턴에서 손상된 상태로 시작될 수 있으니, 상태 체크포인트 필요.

Apidog로 API를 통해 에이전트 메모리 테스트하는 방법

스테이트풀 에이전트 API 테스트는 단일 요청 단언만으로 충분하지 않습니다. 여러 호출에 걸쳐 컨텍스트가 유지되는지, 메모리 기반 응답이 정상적으로 동작하는지, 장애 상황에서 저하가 정상적으로 이루어지는지 확인해야 합니다.

테스트 1: 컨텍스트 유지

순서:

/agent/chat에 "내 프로젝트는 PostgreSQL 16을 사용합니다" 입력 (POST)
이어서 "/어떤 데이터베이스에 최적화해야 하나요?" 질문 입력 (POST)
2번 응답에 response.message.content가 "PostgreSQL"을 포함하는지 단언

의도: 에피소드/의미 메모리에서 사실을 검색해 응답에 반영되는지 확인.

테스트 2: 세션 격리

방법: 두 개의 서로 다른 session_id 값으로 위 시퀀스를 반복 실행. 두 번째 세션 응답에 첫 번째 세션 컨텍스트가 포함되지 않는지 단언.

목적: 세션 메모리 격리 및 다중 테넌트 안전성 검증.

테스트 3: 메모리 실패 저하

방법: Apidog Smart Mock으로 벡터 저장소 조회 엔드포인트가 503을 반환하도록 구성. 대화를 실행하고,

에이전트가 충돌 없이 정상 응답
"충분한 컨텍스트가 없습니다" 등 대체 메시지 포함
목 해제 후 세션 정상 재개

테스트 4: 컨텍스트 윈도우 오버플로

방법: 30개 이상 메시지를 연달아 보내 컨텍스트 한도 초과 유도.

context_length_exceeded 오류 없이 정상 동작
30번째 턴에서 에피소드 검색 결과로 올바른 응답
response.usage의 토큰 수가 예상 범위 내인지 단언

이 네 가지를 Apidog에서 하나의 테스트 시나리오로 구성할 수 있습니다. 세션 ID·응답 데이터 공유 변수 활용, 순차 연결로 API 레벨에서 메모리 동작을 검증하세요. 컨텍스트 윈도우 및 모델 동작에 대한 자세한 내용은 [internal: how-to-build-tiny-llm-from-scratch]를 참고하세요.

일반적인 메모리 실패 모드

자동 컨텍스트 잘림: 한도 초과로 오래된 메시지 무경고 삭제 → 불완전 기록 기반 답변. → response.usage.prompt_tokens 단언, 컨텍스트 한도 이하 유지 확인
세션 누수: 세션 네임스페이스 공유로 두 사용자 컨텍스트 섞임 → 세션 격리 테스트로 검증
오래된 의미 메모리: 과거 지식이 현재 사실과 모순, 잘못된 답변 → "현재 날짜" 단언 포함, 인용값 검증
임베딩 드리프트: 임베딩 모델 교체로 벡터 DB 손상, 검색 결과 오류 → 검색 컨텍스트 의미론적 연관성 단언 추가
메모리/프롬프트 주입: 악의적 입력으로 저장·검색 조작 → 적대적 입력 포함, 시스템 프롬프트 재정의 무시 여부 테스트

API 보안 테스트 가이드는 [internal: rest-api-best-practices] 참고.

결론

에이전트 메모리는 지능형 비서와 기억상실형 비서의 차이를 만듭니다. 작업, 에피소드, 의미, 절차 네 가지 메모리의 역할과 실제 저장·검색 방식을 이해하면 API 테스트에서 어디를 단언해야 할지 명확해집니다.

Hippo 등은 원칙적인 메모리 아키텍처로의 진화를 보여줍니다. 어떤 시스템을 쓰든 Apidog 테스트 시나리오로 대규모 환경에서만 드러나는 실패까지 사전 검증이 가능합니다.

FAQ

Q: 에이전트에 메모리를 추가하는 가장 간단한 방법은?

A: 대화 기록의 슬라이딩 윈도우(최근 N턴)를 프롬프트에 포함하는 방식이 가장 단순합니다. 장기 실행에는 벡터 저장소+의미 검색이 필요합니다.

Q: OpenAI Assistants API는 메모리를 어떻게 처리하나요?

A: 서버 측에서 대화 기록(스레드 객체)을 관리합니다. 도구(파일 검색, 코드 인터프리터) 연결 가능. 관리가 편한 대신 디버깅은 어려움.

Q: 에이전트 메모리에 적합한 벡터 DB는?

A: 로컬 개발엔 Chroma, 프로덕션엔 Qdrant(자체 호스팅) 또는 Pinecone(관리형). Hippo는 플러그형 백엔드 지원. 자세한 내용은 [internal: claude-code] 참고.

Q: 에이전트가 과거 상호작용을 환각하는 걸 방지하려면?

A: 상호작용 로그를 메타데이터(타임스탬프, 신뢰도 등)와 함께 구조화 저장하고, 검색 시 프롬프트에 명시적으로 인용:

"[날짜]의 대화에 따르면, 당신은 X를 언급했습니다."

이렇게 하면 환각을 줄일 수 있습니다.

Q: 실행 중인 에이전트 없이도 에이전트 메모리 테스트가 가능한가요?

A: 네. Apidog Smart Mock으로 세션 ID·본문에 따라 다른 목 응답을 정의하면, 실제 에이전트 없이도 메모리 동작 테스트가 가능합니다.

Q: 프로덕션에서 벡터 저장 비용은?

A: Pinecone 무료 티어는 10만 벡터/1인덱스, 대규모는 p1.x1 포드 기준 시간당 약 $0.096. Qdrant 자체 호스팅은 무료. 보통 더 큰 비용은 임베딩 생성입니다. MCP 서버 통합 등은 [internal: what-is-mcp-server] 참고.

Q: RAG와 에이전트 메모리의 차이점은?

A: RAG(검색증강)는 고정 문서에서 관련 정보 검색, 에이전트 메모리는 상호작용에 따라 성장·변화합니다. RAG는 "문서에 뭐라고 되어 있나요?", 에이전트 메모리는 "이 사용자에 대해 무엇을 알고 있나요?"에 답합니다.

DEV Community