vectorize-io/hindsight

Docker (외부 PostgreSQL)

export OPENAI_API_KEY=sk-xxx
export HINDSIGHT_DB_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose up

Oracle AI Database는 완전한 기능 패리티를 갖춘 엔터프라이즈 배포에도 지원됩니다. 자세한 내용은 스토리지 문서를 참조하세요.

>API: http://localhost:8888 >UI: http://localhost:9999

클라이언트

pip install hindsight-client -U
# or
npm install @vectorize-io/hindsight-client

Python

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.js / TypeScript

npm install @vectorize-io/hindsight-client

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();

Python Embedded (서버 불필요)

pip install hindsight-all -U

Intel (x86_64) Mac에서는 대신 hindsight-all-slim을 설치하세요. 지원 플랫폼을 참조하세요.

import os
from hindsight import HindsightServer, HindsightClient

with HindsightServer(
    llm_provider="openai",
    llm_model="gpt-5-mini",
    llm_api_key=os.environ["OPENAI_API_KEY"]
) as server:
    client = HindsightClient(base_url=server.url)
    client.retain(bank_id="my-bank", content="Alice works at Google")
    results = client.recall(bank_id="my-bank", query="Where does Alice work?")

사용 사례

Hindsight는 대화형 AI 에이전트와 자율적으로 작업을 수행하도록 설계된 에이전트를 모두 지원하도록 구축되었습니다. Hindsight의 이상적인 사용 사례는 개방형 작업을 처리하고, 사용자 피드백에 따라 동작을 변경하며, 인간 작업에 근접한 수준으로 작업을 자동화하기 위해 복잡한 작업을 수행하는 방법을 학습해야 하는 AI 직원과 같은 이러한 기능의 조합이 필요한 에이전트입니다. Hindsight는 n8n 및 기타 유사한 도구로 구축된 간단한 AI 워크플로와 함께 사용할 수 있지만 이러한 애플리케이션에는 과도할 수 있습니다.

사용자별 메모리 및 채팅 기록

Hindsight를 사용할 수 있는 더 간단한 사용 사례 중 하나는 개별 사용자와 관련된 메모리를 저장하고 검색하여 AI 챗봇 및 기타 대화형 에이전트를 개인화하는 것입니다.

이 사용 사례의 요구 사항은 일반적으로 다음과 같습니다.

Hindsight에서 이러한 요구 사항을 충족하는 것은 간단합니다. 새로운 사용자 입력과 도구 호출이 유지(retain) 작업을 사용하여 Hindsight에 수집될 때 사용자 정의 메타데이터를 사용하여 새로운 메모리를 보강할 수 있습니다. 메타데이터는 특정 사용자로 제한되어야 하는 메모리를 격리하는 편리한 방법을 제공합니다. 이것들이 유지 작업에 공급되면 관련 메모리를 검색할 때 생성된 원시 메모리와 정신 모델을 필터링할 수 있습니다.

아키텍처 및 작업

대부분의 에이전트 메모리 구현은 기본 벡터 검색에 의존하거나 때로는 지식 그래프를 사용합니다. Hindsight는 생체 모방 데이터 구조를 사용하여 에이전트 메모리를 인간의 기억 작동 방식과 더 유사하게 구성합니다.

• World: 세상에 대한 사실 ("스토브는 뜨겁다")
• Experiences: 에이전트 자신의 경험 ("스토브를 만졌는데 정말 아팠다")
• Mental Models: 원시 메모리와 경험을 반영하여 형성된 에이전트 세계에 대한 학습된 이해.

Hindsight의 메모리는 뱅크(즉, 메모리 뱅크)에 저장됩니다. 메모리가 Hindsight에 추가되면 세계 사실 또는 경험 메모리 경로 중 하나로 푸시됩니다. 그런 다음 엔터티, 관계 및 시계열의 조합으로 희소/밀집 벡터 표현과 함께 표현되어 이후 회상을 돕습니다.

Hindsight는 시스템과 상호 작용하는 세 가지 간단한 방법을 제공합니다.

• Retain: 기억하고 싶은 정보를 Hindsight에 제공합니다.
• Recall: Hindsight에서 메모리를 검색합니다.
• Reflect: 메모리와 경험을 반영하여 기존 메모리에서 새로운 관찰과 통찰력을 생성합니다.

Retain

retain 작업은 새로운 메모리를 Hindsight에 푸시하는 데 사용됩니다. 입력으로 전달하는 정보를 Hindsight에 유지하도록 지시합니다.

from hindsight_client import Hindsight

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

# Simple
client.retain(
    bank_id="my-bank",
    content="Alice works at Google as a software engineer"
)

# With context and timestamp
client.retain(
    bank_id="my-bank",
    content="Alice got promoted to senior engineer",
    context="career update",
    timestamp="2025-06-15T10:00:00Z"
)

내부적으로 retain 작업은 LLM을 사용하여 핵심 사실, 시간 데이터, 엔터티 및 관계를 추출합니다. 추출된 데이터를 정규화 프로세스를 통해 메타데이터와 함께 표준 엔터티, 시계열 및 검색 인덱스로 변환합니다. 이러한 표현은 회상 및 반영 작업에서 정확한 메모리 검색을 위한 경로를 만듭니다.

Recall

회상(recall) 작업은 메모리를 검색하는 데 사용됩니다. 이러한 메모리는 모든 메모리 유형(세계, 경험 등)에서 올 수 있습니다.

from hindsight_client import Hindsight

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

# Simple
client.recall(bank_id="my-bank", query="What does Alice do?")

# Temporal
client.recall(bank_id="my-bank", query="What happened in June?")

• Semantic: 벡터 유사성
• Keyword: BM25 정확 일치
• Graph: 엔터티/시간/인과 관계 링크
• Temporal: 시간 범위 필터링

Recall은 4가지 검색 전략을 병렬로 수행합니다.

검색의 개별 결과는 병합된 다음 상호 순위 융합(reciprocal rank fusion) 및 교차 인코더 재순위 모델을 사용하여 관련성별로 정렬됩니다.

최종 출력은 필요에 따라 토큰 제한에 맞게 잘립니다.

Reflect

반영(reflect) 작업은 기존 메모리에 대한 보다 철저한 분석을 수행하는 데 사용됩니다. 이를 통해 에이전트는 메모리 간의 새로운 연결을 형성하고 세계에 대한 보다 완전한 이해를 구축할 수 있습니다.

예를 들어, reflect 작업은 다음과 같은 사용 사례를 지원하는 데 사용될 수 있습니다.

• 프로젝트에서 완화해야 할 위험을 반영하는 AI 프로젝트 관리자.
• 특정 아웃리치 메시지가 응답을 받은 반면 다른 메시지는 받지 못한 이유를 반영하는 영업 에이전트.
• 현재 제품 문서로 답변되지 않은 질문이 고객에게 있는 기회를 반영하는 지원 에이전트.

reflect 작업은 더 깊은 사고가 필요한 주문형 질문 응답 또는 분석을 처리하는 데에도 사용할 수 있습니다.

from hindsight_client import Hindsight

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

client.reflect(bank_id="my-bank", query="What should I know about Alice?")

리소스

• https://hindsight.vectorize.io

문서:

• Python
• Node.js
• REST API
• CLI

클라이언트:

• Slack

커뮤니티: