Hindsight 쓰는 법

Hindsight(vectorize-io/hindsight)는 Vectorize가 만든 오픈소스 에이전트 메모리다. 대화 기록을 그대로 쌓아 두는 수준을 넘어, 에이전트가 시간이 지나며 배우고 판단이 쌓이도록 설계됐다. 라이선스 MIT, PyPI hindsight-api·hindsight-client·hindsight-all 최신 0.10.1(작성 시점), GitHub 약 3.7만 스타. 문서: hindsight.vectorize.io.

이 글은 “Hindsight 쓰는 법”만 다룬다. Docker로 서버를 띄우고, 클라이언트로 retain·recall·reflect를 쓰고, 필요하면 코딩 에이전트·MCP까지 연결하는 경로를 공식 README·설치 문서 기준으로만 적는다.

핵심 요약 (TL;DR)

• 무엇인가: 에이전트용 장기 메모리 서버. 기억 단위는 bank(뱅크, 사용자·에이전트·프로젝트별로 격리된 메모리 저장소)다.
• 세 연산: retain(기억 넣기) → recall(관련 기억 찾기) → reflect(기억을 깊게 묶어 답·판단 만들기).
• 추천 시작: Docker 이미지 ghcr.io/vectorize-io/hindsight:latest. API http://localhost:8888, UI http://localhost:9999.
• 필수 환경: LLM API 키. 보통 HINDSIGHT_API_LLM_API_KEY와(선택) HINDSIGHT_API_LLM_PROVIDER.
• 클라이언트: pip install hindsight-client 또는 npm install @vectorize-io/hindsight-client (둘 다 작성 시점 0.10.1).
• 코딩 에이전트(선택): npx @vectorize-io/hindsight-coding-agents install … (npm 패키지 최신 0.7.0).
• MCP(선택): http://localhost:8888/mcp/{bank_id}/ — bank마다 Model Context Protocol 엔드포인트가 기본으로 열린다.

할 수 있는 일

먼저 용어만 짧게 풀어 둔다.

• 에이전트 메모리: AI 에이전트가 세션이 바뀌어도 사실·경험·선호를 남겨 두고, 다음에 꺼내 쓰는 저장·검색 계층. 단순 채팅 로그 백업과는 다르다.
• bank(뱅크): 한 사용자·한 에이전트·한 프로젝트용으로 나뉜 격리된 메모리 공간. bank끼리 기억이 섞이지 않는다.
• retain / recall / reflect: 각각 “넣기 / 찾기 / 깊게 생각하기”. Hindsight의 핵심 세 연산이다.
• MCP(Model Context Protocol): 에이전트·IDE가 외부 도구를 같은 방식으로 붙이는 프로토콜. Hindsight는 bank별 MCP URL을 제공한다.
• 하네스(harness): 코딩 에이전트를 감싸 메모리·도구·규칙을 주입하는 실행 껍데기. (한글로는 하네스라고 쓴다.)

공식 README·docs 기준으로 바로 할 수 있는 일은 대략 이렇다.

• 대화·이벤트를 기억으로 남기기: retain으로 텍스트를 넣으면 사실·엔티티·시간 정보가 추출·정규화된다.
• 관련 기억 검색: recall이 의미·키워드·그래프·시간 검색을 병렬로 돌린 뒤 합친다.
• 깊은 답·판단: reflect로 “이 사용자에 대해 무엇을 알아야 하지?”처럼 조회가 아닌 종합이 필요할 때 쓴다.
• 웹 UI로 bank 탐색: Control Plane(:9999)에서 bank·엔티티·쿼리를 눈으로 확인.
• 코딩 에이전트에 장기 메모리 붙이기: Claude Code·Codex·Cursor CLI 등에 hindsight-coding-agents로 네이티브 연동.
• MCP 도구로 노출: retain/recall/reflect를 MCP 클라이언트가 호출.
• 임베디드 모드: 별도 서버 없이 Python에서 pip install hindsight-all로 프로세스 안에 서버를 띄울 수도 있다.

필요한 것

링크: GitHub · 문서 · Installation · MCP · PyPI hindsight-api · npm client.

단계

1) Docker로 서버 띄우기 (권장)

가장 빠른 경로다. OpenAI 키가 있으면 아래처럼 바로 올린다. 다른 제공자를 쓰려면 HINDSIGHT_API_LLM_PROVIDER를 함께 넣는다.

export OPENAI_API_KEY=sk-xxx

docker run -it --pull always --name hindsight --restart unless-stopped --shm-size=1g \
  -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v hindsight-data:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

• API: http://localhost:8888
• Control Plane(UI): http://localhost:9999

데이터는 named volume hindsight-data에 남는다. 호스트 디렉터리를 바인드 마운트할 때는 UID 1000 소유가 필요하다(설치 문서 경고).

더 가벼운 이미지: ghcr.io/vectorize-io/hindsight:latest-slim — 임베딩·리랭커를 외부로 빼는 대신 이미지 크기가 훨씬 작다(문서 기준 AMD64/ARM64 약 500MB).

2) 클라이언트로 retain / recall / reflect

# Python
pip install hindsight-client -U

# Node.js / TypeScript
npm install @vectorize-io/hindsight-client

Python 예시(README Quick Start와 동일 패턴):

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

# Retain: 정보 저장
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# Recall: 관련 기억 검색
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: 기억을 묶어 더 깊은 답 생성
client.reflect(bank_id="my-bank", query="Tell me about Alice")

Node 예시:

const { HindsightClient } = require('@vectorize-io/hindsight-client');

const main = async () => {
  const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
  await client.retain('my-bank', 'Alice loves hiking in Yosemite');
  const results = await client.recall('my-bank', 'What does Alice like?');
  console.log(results);
};

main();

3) (선택) 코딩 에이전트에 붙이기

레포·세션 기억을 코딩 에이전트에 자동 주입하려면:

npx @vectorize-io/hindsight-coding-agents install all
# 또는 하나만
npx @vectorize-io/hindsight-coding-agents install claude-code

문서 스킬만 먼저 넣고 싶다면 README의:

npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs

4) (선택) MCP로 연결

서버가 떠 있으면 bank마다 MCP URL이 기본 활성화된다.

http://localhost:8888/mcp/{bank_id}/

예: bank_id가 my-bank이면 http://localhost:8888/mcp/my-bank/. MCP 클라이언트에 이 URL을 등록하면 retain·recall·reflect가 도구로 노출된다. 자세한 설정은 MCP server 문서.

5) (대안) pip 단독 / 임베디드

# Bare metal API
pip install hindsight-api
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
hindsight-api   # 기본 http://localhost:8888

# UI만 따로
npx @vectorize-io/hindsight-control-plane --api-url http://localhost:8888

# 서버 없이 Python 프로세스 안에
pip install hindsight-all -U

임베디드 예시는 README의 HindsightServer + HindsightClient 패턴을 따르면 된다. Intel Mac은 hindsight-all-slim을 쓰라는 플랫폼 표가 있다.

막히는 지점

마치며

Hindsight는 “어제 대화 로그를 다시 읽기”가 아니라, bank에 사실·경험을 쌓고 recall·reflect로 다음에 더 똑똑하게 쓰게 만드는 에이전트 메모리에 가깝다. 로컬에서는 Docker 한 줄로 API·UI를 올리고, Python/Node 클라이언트로 세 연산을 확인한 뒤, 필요하면 코딩 에이전트나 MCP로 확장하면 된다. 버전·포트·환경 변수는 시간이 지나면 바뀔 수 있으니, 설치 직전 Installation과 PyPI/npm latest를 한 번 더 확인하자.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.