Hindsight: 에이전트 기억을 저장하고 찾고 활용하기

에이전트가 세션 너머로 배우도록 기억을 구조화한 오픈소스 기억 시스템. 네 기억 종류와 저장·검색·추론, RAG와의 분업, 미실행 최소 예시로 정리했다.

고친 내용: 4판: recall 그림 끝 두 단계를 예산·순위 매긴 구조화 사실로 바로잡고(S14), 큰 흐름도의 자동 되돌아쓰기 화살표를 지워 세 API를 별개 갈래로 그렸으며, 기억 종류 표의 지금 문서 이름과 논문 옛 표현 opinion을 구분했다.

Hindsight란 무엇인가

Hindsight는 AI 에이전트가 대화가 끝난 뒤에도 기억을 이어가도록 만든 오픈소스 장기 기억 시스템이다. Vectorize가 MIT 허가서로 공개했으며, 대표 논문은 2026년 7월 전산언어학회(ACL) 시스템 데모 부문에 실렸고, 그 전에 2025년 12월 14일 arXiv 사전 공개판이 먼저 나왔다. 문서는 그 뒤로 바뀌었을 수 있으니, 실행 전에는 반드시 최신 공식 문서를 다시 확인한다.

핵심 주장은 기억을 추론의 1급 재료로 취급하자는 것이다. 기억을 처음부터 구조화된 형태로 쌓고, 객관적 사실과 주관적 믿음을 나눠 둔다. 그래서 개발자는 에이전트가 무엇을 아는지와 무엇을 믿는지를 따로 들여다볼 수 있다. 이 글의 해석으로, 목표는 오래 기억하는 것 자체가 아니라 근거와 추론의 경계가 드러나는 기억이다.

기억은 문서 0.10 개요 기준으로 네 종류에 나눠 둔다. 세계 사실(World Fact)은 세상에 대한 객관적 사실을, 경험 사실(Experience Fact)은 에이전트가 겪은 일을, 관찰(Observation)은 개체별로 종합한 요약을, 멘탈 모델(Mental Model)은 자주 쓰는 지식을 다듬어 둔 것이다. 논문 쪽 표현 opinion(변하는 믿음)은 옛 이름이므로, 지금의 네 칸과 같은 층이라고 묶어 부르지 않는다. 기억을 한 통에 섞지 않고 쓰임새별로 나눠, 답의 근거를 물을 때 출처를 추적할 수 있게 한다는 것이 요지다.

언제 Hindsight를 쓰는가

잘 맞는 쓰임은 기억이 쌓이고 진화해야 하는 일이다. 대화를 넘어 상대를 기억해야 하는 비서, 누가 무엇을 맡았는지 따라가야 하는 협업 도우미, 지난 분기나 작년 같은 시간 질의가 잦은 기록 도우미, 답의 결이 흔들리면 안 되는 응대 창구가 예다. 이 용도 구분은 공식 비교 페이지의 권장을 옮긴 것이다.

반대로 자료가 고정되고 시간 조건이 없으면 검색 증강 생성 쪽이 간결할 수 있다. 정적 말뭉치에 대한 문서 질의응답이 예다. Hindsight를 들이면 서버와 데이터베이스, 거대언어모델 키의 운영비를 함께 들이게 되므로, 기억이 필요 없는 질의까지 기억 시스템으로 풀 필요는 없다. 무엇을 쓸지는 자료가 정적인지, 시간이 중요한지, 상대에 대한 이해가 쌓여야 하는지에 따라 가른다는 것이 이 글의 정리다.

RAG와의 관계: 대체가 아니라 분업

공식 비교 페이지는 Hindsight를 단순화된 의미 유사도 검색 중심의 RAG 기준선과 견준다. 이 대조는 모든 RAG가 그렇다는 뜻이 아니다. 실제 RAG 시스템도 혼합 검색, 그래프, 시간 거르기, 여러 단계 추론을 갖출 수 있다. 비교표는 특정 기준선에 대한 제작사의 설명으로만 읽는다.

페이지가 그리는 용도 구분은 분명하다. 변하지 않는 말뭉치에 대한 문서 질의응답이나 시간 조건이 없는 검색에는 RAG 쪽을, 여러 세션에 걸친 비서의 지속 기억과 개체 추적, 일관된 성향, 시간 질의에는 Hindsight 쪽을 권한다. 검색 전략·여러 단계 추론·시간 질의·개체 이해·지식 종합·성향의 여섯 갈래에서 차이를 설명한다.

이 글의 해석은 그래서 분업이다. 근거 문서를 읽고 답하는 일은 RAG의 강점이고, 시간을 넘나들며 상대를 알아가고 믿음을 다듬는 일은 기억 시스템의 강점이다. Hindsight는 RAG를 보완하는 이웃 기술이지, 모든 검색을 갈아치우는 보편 대체품이 아니다.

핵심 동작: 저장·검색·추론

기억에 대한 연산은 세 가지로, 셋은 각자 부르는 별개의 API다. 저장(retain)은 정보를 들여오는 일, 검색(recall)은 꺼내는 일, 추론(reflect)은 그 위에서 답을 빚는 일이다. 대화의 흐름은 시간 인식 기억 층을 거쳐 구조화된 질의 가능한 메모리 뱅크로 쌓이고, 추론은 그 뱅크에서 안에서 찾아 읽은 기억을 바탕으로 답을 짓는다. 이 글은 추론이 답할 때마다 뱅크를 자동으로 되돌아쓴다고 주장하지 않는다.

검색은 벡터 검색, 키워드 매칭, 그래프 탐색, 시간 거르기를 함께 쓰고, 바탕에는 PostgreSQL과 pgvector가 있다. 질의에서 시간 표현과 개체를 먼저 뽑고, 여러 갈래의 검색 결과를 합친 뒤 순서를 다시 매기고, 달라는 예산에 맞춰 순위 매긴 구조화 사실을 돌려준다. 검색은 답을 짓지 않으며, 답을 짓는 일은 추론의 몫이다. 질의 사이에도 상태가 남아 다음에 이어진다는 점이 한 번의 검색으로 끝내는 흐름과의 차이다.

메모리 뱅크는 기억의 이름공간이다. 사용자 하나, 에이전트 하나, 프로젝트 하나가 각자의 뱅크를 갖는다는 비유가 공식 설명이다. 뱅크마다 배경 맥락과 세 기질(회의·직설·공감)의 설명이 실려 있어, 추론이 답을 지을 때 이를 참고한다. 이름공간 분리와 접근 통제는 별개이므로, 격리가 필요하다면 인증·인가 설정을 따로 갖추고 검증해야 한다. 이 글은 뱅크만으로 샐 틈이 없다고 주장하지 않는다.

뱅크 안의 지식은 층을 이룬다. 맨 아래는 들여온 사실들이고, 그 위에서 관찰이 자동으로 종합되며, 그 위에서 멘탈 모델과 지식 페이지가 자주 쓰는 지식을 다듬는다. 추론은 멘탈 모델, 관찰, 날것의 사실 순으로 출처를 살핀다. 자주 묻는 것은 다듬어진 답부터, 낯선 것은 밑바탕까지 내려가 살핀다는 정리다.

설치와 서버 실행

아래 절차와 예시는 공식 Quick Start의 흐름을 옮겨 적은 것으로, 마탑 환경에서 직접 실행하지 않은 미실행 예시다. 문서 판 0.10을 2026년 9월 28일에 확인했으며, 버전이 오르면 절차가 바뀔 수 있다. 예시 코드는 공식 저장소의 MIT 허가 공개 패턴을 각색한 것으로, 식별자와 문장은 이 글용으로 바꿨다.

파이썬으로 직접 띄우는 길은 세 단계다. hindsight-api 꾸러미와 hindsight-client 꾸러미를 설치하고, 거대언어모델 키를 환경 변수(HINDSIGHT_API_LLM_API_KEY)로 비공개로 설정한 뒤, hindsight-api 명령으로 서버를 실행한다. 서버가 뜨면 API는 로컬 8888번에서 응답한다. Docker로 같은 환경 변수를 주고 공식 이미지를 실행하는 길과, 서버 없이 쓰는 매니지드 선택지도 문서에 있다. 공통 전제는 구조화 출력을 지원하는 거대언어모델이 필요하다는 점이다.

pip install hindsight-api hindsight-client
export HINDSIGHT_API_LLM_API_KEY="..."  # 실제 키는 비공개로 설정
hindsight-api
# API: http://localhost:8888

최소 사용 예시

서버가 떴다는 전제 아래, 클라이언트는 같은 뱅크 이름으로 세 연산을 각자 부른다. 아래 예시는 탑 읽기 모임이라는 가상의 이름공간에 모임 장소를 저장했다가 찾는 흐름이다. 실행하지 않은 예시이므로 정확한 반환값은 적지 않는다. 저장 단계는 들여온 기록의 확인 정보를, 검색 단계는 질의에 맞는 순위 매긴 기억 후보들을, 추론 단계는 안에서 찾아 읽은 기억들을 바탕으로 지은 답을 돌려주는 역할이다. 검색만 따로 불러 쓸 수도 있고, 검색 결과를 추론에 넘겨 부를 수도 있다.

Node.js·Go·명령줄 클라이언트도 같은 세 연산을 제공한다. 운영으로 가져갈 때는 작업자 식별자를 고정해 재시작해도 같은 일꾼으로 인식되게 하고, 데이터가 담기는 볼륨을 잘 둔다. 외부 PostgreSQL 같은 선택지는 공식 문서를 따른다.

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")
bank = "tower-reading-group"

client.retain(bank_id=bank, content="탑 읽기 모임은 6층 서가에서 열린다.")
found = client.recall(bank_id=bank, query="읽기 모임은 어디에서 열리나?")
answer = client.reflect(bank_id=bank, query="이번 주 모임 장소를 알려줘.")

한계와 다음 읽기

한계도 분명히 적는다. 첫째, 기억의 품질은 들여온 사실과 종합 과정의 품질에 묶인다. 엉뚱한 사실을 저장하면 그럴듯한 오답의 재료가 늘어날 뿐이다. 둘째, 사실과 믿음을 나눈다고 해서 믿음이 저절로 옳아지지 않는다. 믿음이 다듬어지는 과정은 관찰되는 흐름이지 정답의 보증이 아니다. 셋째, 문서 판 0.10 기준의 젊은 프로젝트라 인터페이스와 동작이 바뀔 수 있다. 넷째, 기억의 충돌 해소·삭제·보존 기간·개인정보 취급은 도입자가 설계해야 할 운영의 몫이다.

이 글은 벤치마크 수치를 인용하지 않는다. 수치는 모델과 설정에 묶인 스냅샷이며, 이 서가의 판형을 넘는 주장이기 때문이다. 다음 읽기로는 AI의 기억과 컨텍스트, 검색 증강 생성과 검색, 에이전트와 도구 사용 주제 글을 권한다. 기억의 확장사인 발전 과정 글과 함께 읽으면 지형이 보인다.