AI 에이전트 메모리, 네 가지 유형과 저장 방법

AI 에이전트 메모리는 에이전트가 한 단계에서, 혹은 한 세션에서 다음으로 무언가를 가져갈 수 있게 해 주는 요소입니다. 언어 모델은 혼자서는 호출 사이에 아무것도 기억하지 못합니다. 모델이 기억하는 것처럼 보이는 내용은 모두 여러분의 코드가 프롬프트에 다시 넣어 준 것입니다. 이 자료를 어떻게 저장하고 불러오느냐가 에이전트가 무엇을 얼마나 빨리, 한 턴에 어느 정도 비용으로 기억해 낼 수 있는지를 결정합니다.

요약. 에이전트에는 네 가지 메모리가 필요합니다. 짧은 대화 윈도우, 의미로 찾는 장기 사실, 진행 중인 작업을 위한 스크래치패드, 일어난 일의 기록입니다. 각각 형태, 수명, 조회 방식이 달라서 하나의 메모리 테이블로는 어느 것도 잘 맞지 않습니다. HotKV는 AMEM.* 명령어로 네 가지를 하나의 인메모리 엔진에 저장합니다. 저희가 벤치마크한 것은 HotKV의 캐싱과 벡터 검색이지 에이전트 메모리가 아니므로, 이 글은 설계를 설명할 뿐 속도 향상을 주장하지 않습니다.

컨텍스트 윈도우가 메모리가 아닌 이유

컨텍스트 윈도우는 요청마다 함께 보내는 텍스트입니다. 크기 제한이 있고, 그 안의 모든 내용에 대해 매 턴 입력 토큰 비용을 내며, 세션이 끝나면 사라집니다. 검색도 할 수 없습니다. 에이전트에 3주 전의 사실 하나가 필요할 때 전체 기록을 붙여 넣는 것은 해답이 아닙니다.

메모리는 다음에 윈도우에 무엇을 넣을지 결정하는 계층입니다. 최근 턴을 유지하고, 중요한 오래된 사실 몇 가지를 찾아냅니다. 현재 작업의 상태를 보관하고 에이전트가 한 일을 기록합니다. 연구자들도 에이전트를 비슷하게 설명합니다. Sumers, Yao, Narasimhan, Griffiths의 CoALA 프레임워크는 작업 메모리를 장기 에피소드, 시맨틱, 절차 메모리와 구분합니다.

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

HotKV의 네 가지 저장소는 같은 영역의 대부분을 다루되, 애플리케이션이 실제로 구축해야 하는 것에 맞게 조정되어 있습니다. 에이전트의 코드와 프롬프트에 담긴 노하우인 절차 메모리는 보통 저장소나 프롬프트 레지스트리에 있으므로 별도의 저장소가 아닙니다.

대화 메모리

한 세션의 단기 대화 기록입니다. 메시지에는 역할(시스템, 사용자, 어시스턴트, 도구)이 붙습니다. 메시지는 제한된 슬라이딩 윈도우에 담기므로 한도에 도달하면 가장 오래된 턴이 밀려납니다. 이 메모리는 하나의 질문에 답합니다. 최근에 무슨 말이 오갔는가? HotKV에서는 AMEM.CONV.CREATE, AMEM.CONV.APPEND, AMEM.CONV.WINDOW가 이에 해당합니다.

시맨틱 메모리

시맨틱 메모리는 임베딩 벡터와 함께 사실로 저장되는 장기 지식입니다. 에이전트는 키가 아니라 의미로 이를 불러옵니다. 벡터 검색을 구동하는 것과 같은 종류의 HNSW 벡터 인덱스가 뒷받침합니다. AMEM.SEM.STORE는 사실을 저장하고 AMEM.SEM.RECALL은 유사도 점수와 함께 상위 일치 항목을 반환합니다. 문서, 사용자 선호, 학습한 수정 사항이 여기에 속합니다.

작업 메모리

작업 메모리는 진행 중인 작업을 위한 스크래치패드로, 세션 범위의 평평한 키-값 집합입니다. 현재 단계, 처리 중인 티켓, 중간 결과를 담습니다. 작업이 끝나면 사라져야 합니다. AMEM.WORK.SET이 바로 그런 이유로 time to live(TTL)를 받습니다.

에피소드 메모리

에피소드 메모리는 수행한 동작, 관찰한 내용, 내린 결정 같은 타임스탬프가 찍힌 이벤트의 추가 전용 로그입니다. 에이전트나 이를 검토하는 사람이 무슨 일이 언제 있었는지 물을 수 있게 해 줍니다. AMEM.EPIS.LOG는 이벤트를 기록하고 AMEM.EPIS.QUERY는 유형과 시간 범위로 이벤트를 읽어 옵니다.

실무에서의 AI 에이전트 메모리

실무에서 중요한 것은 두 가지입니다. 메모리에 어떻게 쓰는가, 그리고 매 턴 무엇을 읽어 오는가입니다.

명령어로 메모리 저장하기

다음은 대화 하나를 처리하는 지원 에이전트입니다. 가상의 정책 텍스트와 숫자 세 개짜리 벡터는 설명을 위한 것일 뿐입니다. 실제 임베딩 모델은 768개 또는 1,536개 숫자로 된 벡터를 만들며, 네임스페이스도 그 차원으로 생성합니다.

AMEM.CONV.CREATE session-42 WINDOW 50 TTL 86400
AMEM.CONV.APPEND session-42 user "My invoice shows the wrong VAT number."
AMEM.WORK.SET session-42 ticket "INV-1932" TTL 3600
AMEM.EPIS.LOG agent-support action "Looked up invoice INV-1932"

AMEM.SEM.CREATE support-kb 3
AMEM.SEM.STORE support-kb vat-policy "VAT details can be corrected within 30 days." 0.1 0.2 0.3
AMEM.SEM.RECALL support-kb 3 0.1 0.2 0.3
AMEM.CONV.WINDOW session-42 10

각 턴에서 에이전트는 최근 윈도우를 읽고 질문과 일치하는 사실 몇 가지를 불러옵니다. 작업 메모를 확인하고 이 조각들로 프롬프트를 구성합니다. 동작을 마치면 이벤트를 기록합니다. 이 과정 어디에도 전체 기록은 필요하지 않습니다.

매 턴 메모리 읽기

메모리를 저장하는 일은 쉬운 절반입니다. 진짜 기술은 무엇을 다시 읽어 올지 정하는 것입니다. 읽은 내용은 모두 프롬프트에 들어가 입력 토큰 비용이 들기 때문입니다. 합리적인 루프는 정해진 순서로 소수의 항목을 읽습니다. 최근 턴이 먼저이고, 그다음 질문과 일치하는 사실 몇 가지, 그다음 작업 상태입니다. 다음은 공식 Python 클라이언트로 작성한 예이며, 임베딩 함수와 프롬프트 템플릿은 직접 준비해야 합니다.

import hotkv

r = hotkv.from_url("hotkv://localhost:6379")
MIN_SIMILARITY = 0.8          # 자신의 데이터에 맞게 조정

def start_session(session: str) -> None:
    r.amem_conv_create(session, window=50, ttl=86400)   # 첫 append 전에 한 번만 생성

def build_context(session: str, question: str) -> str:
    r.amem_conv_append(session, "user", question)
    turns = r.amem_conv_window(session, 10)
    facts = r.amem_sem_recall("support-kb", 3, embed(question))
    facts = [f for f in facts if f["similarity"] >= MIN_SIMILARITY]
    ticket = r.amem_work_get(session, "ticket")
    return render(turns, facts, ticket)      # 직접 만든 프롬프트 템플릿

def finish_turn(session: str, agent: str, reply: str) -> None:
    r.amem_conv_append(session, "assistant", reply)
    r.amem_epis_log(agent, "action", "Answered a billing question")
    r.amem_work_set(session, "last_step", "answered")

유사도 기준값은 직접 조정해야 합니다. 어떤 임베딩 모델과 사실 집합에 맞는 값이 다른 쪽에는 틀릴 수 있으므로, 답을 알고 있는 질문으로 재현율을 확인하십시오. 약한 일치 항목을 버리는 일은 생각보다 중요합니다. 프롬프트에 부실한 사실이 들어가는 것은 아무 사실도 없는 것보다 나쁘기 때문입니다.

이 프롬프트에서 시스템 지침 같은 변하지 않는 부분은 공급자 측 프롬프트 캐싱이 더 저렴하게 만들어 주는 부분이기도 합니다. 읽어 온 메모리는 변하지 않는 텍스트 뒤, 맨 끝에 두어서, 메모리가 바뀌어도 그 캐시가 무효화되지 않게 하십시오.

끝없이 길어지는 윈도우 대신 요약

윈도우는 오래된 턴을 완전히 버립니다. 가벼운 잡담에는 괜찮지만, 3번째 턴이 300번째 턴에서도 중요할 수 있는 긴 작업에는 좋지 않습니다. 일반적인 해법은 롤링 요약입니다. 대화가 한 구간 진행될 때마다 에이전트 또는 더 저렴한 모델이 알게 된 내용을 적어 두고, 그 요약이 프롬프트에서 오래된 턴을 대체합니다.

HotKV는 AMEM.SUMMARY.SET, AMEM.SUMMARY.APPEND, AMEM.SUMMARY.GET으로 에이전트마다 요약 하나를 보관합니다. SET은 텍스트를 교체하고 APPEND는 한 줄을 추가합니다. 갱신할 때마다 버전 번호가 올라가므로, 다른 구성 요소가 요약이 바뀌었다는 것과 그 시점을 저렴하게 알 수 있습니다.

요약은 손실이 있으며, 요약의 요약은 할 때마다 더 많은 것을 잃습니다. 식별자, 금액, 날짜 같은 정확한 값은 줄글에 넣지 말고 작업 메모리나 시맨틱 사실에 두어 살아남게 하십시오. 요약은 선호, 내려진 결정, 남은 일처럼 작업의 윤곽을 담는 데 쓰십시오.

설계 규칙과 보존

막지 않으면 메모리는 한없이 늘어납니다. 첫 쓰기 전에 한도를 정해 두십시오.

메모리를 쓸모 있게 유지하는 규칙

• 모든 것에 한도를 두십시오. 대화에는 WINDOW를, 세션과 작업 값에는 TTL을 설정하십시오. 대화, 작업 값, 사실에 대해 HotKV는 만료 시각을 추가 전용 파일과 복제본에 기록하므로, 만료된 항목이 재시작 후 파일을 재생할 때 되살아나지 않습니다.
• 대화 기록이 아니라 사실을 저장하십시오. 시맨틱 메모리에 쓰기 전에 요약하십시오. 사실은 대화 한 페이지보다 불러오기 쉽습니다.
• 에이전트를 분리하십시오. 에이전트마다, 테넌트마다 별도의 식별자나 네임스페이스를 사용하여 한 고객의 메모리가 다른 고객에게 불러와지는 일이 없게 하십시오.
• 많이가 아니라 몇 개만 불러오십시오. 상위 3~5개 일치 항목만 가져오고, 약한 항목은 유사도 점수로 걸러 낸 뒤 프롬프트에 넣으십시오.
• 비밀을 넣지 마십시오. 메모리는 프롬프트로 다시 읽히므로 비밀번호, 키, 모델에 보여 주고 싶지 않은 데이터는 절대 저장하지 마십시오.

유형별 보존 기간

이 수명은 기본값이 아니라 저희의 제안입니다. 기반이 되는 사실이 얼마나 빨리 바뀌는지, 무엇을 보관해도 되는지에 따라 정하십시오.

보존은 프라이버시 문제이기도 합니다. 메모리에 어떤 사람에 관한 내용이 들어 있다면, 선택한 수명은 그 사람에게 하는 약속의 일부이므로 문서로 남겨 두십시오.

에이전트 메모리가 잘못되는 경우

메모리 버그는 대부분 느리게 나타납니다. 에이전트가 일주일 동안은 잘 작동하다가 점점 나빠지기 시작합니다. 다음은 설계 단계에서 대비해야 할 실패 사례입니다.

흔한 실패

• 낡은 사실. 3월에는 참이었던 사실이 10월에 불러와집니다. 사실에 time to live를 주거나, 엔터티별로 키를 두어 새 값이 이전 값을 덮어쓰게 하십시오.
• 모순. 저장된 사실 두 개가 서로 어긋나면 에이전트가 무작위로 하나를 고릅니다. 기존 메모 옆에 새 메모를 덧붙이기보다 키 하나당 사실 하나를 권장합니다.
• 과도한 불러오기. 일치 항목이 너무 많으면 프롬프트가 관련성이 낮은 텍스트로 채워집니다. 적게 불러오고 약한 일치 항목은 버리십시오.
• 사용자 간 유출. 한 고객의 메모리가 다른 고객에게 불러와집니다. 모든 테넌트에 별도의 식별자나 네임스페이스를 사용하고, 매 읽기 전에 코드에서 검사하십시오.
• 무제한 증가. 아무것도 만료되지 않아 조회가 느려지고 비용이 슬금슬금 올라갑니다. 모든 유형에 수명이 필요합니다. 에피소드 로그처럼 HotKV에 time to live가 없는 곳에서는 삭제나 내보내기를 직접 예약하십시오.
• 요약 드리프트. 요약의 요약은 서서히 실제 일어난 일과 맞지 않게 됩니다. 이벤트 로그를 진실의 원천으로 유지하고 요약은 그로부터 다시 생성하십시오.

저장된 텍스트를 신뢰할 수 없는 것으로 취급하기

마지막 항목은 더 주의가 필요합니다. 에이전트가 메모리에 쓰는 것은 무엇이든 나중에 프롬프트로 읽힐 수 있습니다. 웹 페이지, 이메일, 사용자에게서 온 텍스트도 마찬가지입니다. 이것이 OWASP가 LLM01로 꼽은 프롬프트 인젝션의 간접 형태입니다. 사실마다 출처를 함께 저장하십시오. 외부 콘텐츠에서 기록된 메모리는 덜 신뢰하고, 불러온 메모가 시스템 프롬프트를 덮어쓰게 해서는 안 됩니다.

측정한 것과 측정하지 않은 것

HotKV가 공개한 벤치마크는 명령 처리량, 벡터 검색, 응답 캐싱의 토큰 절감을 다룹니다. 에이전트 메모리에는 아직 자체 벤치마크가 없습니다. 지연 시간이나 에이전트 품질을 얼마나 높이는지에 대해서는 어떤 주장도 하지 않습니다. 말씀드릴 수 있는 것은 구조에 관한 내용입니다. 네 가지 저장소는 캐시 및 벡터 인덱스와 같은 프로세스에서 실행됩니다. 메모리 조회는 이미 운영 중인 시스템에 대한 호출 한 번입니다.

측정된 부분은 토큰 절감 벤치마크와 프롬프트 캐싱과 시맨틱 캐싱 비교에서 확인할 수 있습니다. 에이전트 메모리 활용 사례에서는 전체 시나리오 속 명령어를 볼 수 있습니다.

Claude Code나 Cursor에서 에이전트 메모리 사용하기

Model Context Protocol을 지원하는 어시스턴트는 맞춤 코드 없이 이 메모리의 일부를 사용할 수 있습니다. 오픈소스 hotkv-mcp 서버는 대화 메모리, 작업 메모, 이벤트 로그, 롤링 요약을 도구로 노출합니다. 읽기 전용 모드와 에이전트를 가두는 네임스페이스가 있습니다. 시맨틱 메모리는 노출하지 않으며 이 서버의 도구로는 윈도우나 time to live를 설정할 수 없으므로, 그런 기능에는 클라이언트 라이브러리를 사용하십시오. 다음 글인 에이전트 메모리를 위한 MCP 서버에서 연결 방법과 안전장치가 다루는 범위를 설명합니다.

자주 묻는 질문