Hindsight 프로바이더

Hindsight 는 AI 에이전트를 위한 영속 메모리(persistent memory) 서비스예요. @vectorize-io/hindsight-ai-sdk 패키지는 대화 간 장기 메모리를 에이전트에 제공하는 AI SDK 호환 도구 5가지를 제공해요.

기능은 다음과 같아요:

5가지 메모리 도구: retain, recall, reflect, getMentalModel, getDocument
generateText, streamText, ToolLoopAgent에서 동작
도구 생성 시 설정되는 인프라 옵션(예산, 태그, 비동기 모드) — 의미적 선택은 모델에 맡김
bankId를 통한 다중 사용자 메모리 격리
완전한 TypeScript 지원

출처: 문서

본문

설정 (Setup)

Hindsight는 Docker로 로컬에서 실행하거나 클라우드 서비스로 사용할 수 있어요.

자체 호스팅 (Docker)

export OPENAI_API_KEY=your-key
docker run --rm -it -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

API는 http://localhost:8888에서, UI는 http://localhost:9999에서 사용할 수 있어요.

클라우드 (Cloud)

Hindsight 대시보드에서 가입하고 API URL을 받으세요.

설치 (Installation)

도구 만들기 (Creating Tools)

HindsightClient를 초기화하고 메모리 저장소를 식별하는 bankId(보통 사용자 ID)와 함께 createHindsightTools에 전달해요:

import { HindsightClient } from '@vectorize-io/hindsight-client';
import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';

const client = new HindsightClient({ baseUrl: process.env.HINDSIGHT_API_URL });

const tools = createHindsightTools({
  client,
  bankId: 'user-123',
});

기본 사용법 (Basic Usage)

generateText

import { HindsightClient } from '@vectorize-io/hindsight-client';
import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';
import { generateText, isStepCount } from 'ai';
import { openai } from '@ai-sdk/openai';

const client = new HindsightClient({ baseUrl: process.env.HINDSIGHT_API_URL });
const tools = createHindsightTools({ client, bankId: 'user-123' });

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools,
  stopWhen: isStepCount(5),
  system: 'You are a helpful assistant with long-term memory.',
  prompt: 'Remember that I prefer dark mode and large fonts.',
});

ToolLoopAgent

import { ToolLoopAgent } from 'ai';
import { openai } from '@ai-sdk/openai';
import { HindsightClient } from '@vectorize-io/hindsight-client';
import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';

const client = new HindsightClient({ baseUrl: process.env.HINDSIGHT_API_URL });

const agent = new ToolLoopAgent({
  model: openai('gpt-4o'),
  tools: createHindsightTools({ client, bankId: 'user-123' }),
  instructions: 'You are a helpful assistant with long-term memory.',
});

const result = await agent.generate({
  prompt: 'Remember that my favorite editor is Neovim',
});

다중 사용자 메모리 (Multi-User Memory)

다중 사용자 애플리케이션에서는 각 요청이 인증된 사용자의 올바른 bankId를 사용하도록 요청 핸들러 안에서 도구를 만들어요:

// app/api/chat/route.ts
import {
  createUIMessageStreamResponse,
  streamText,
  isStepCount,
  convertToModelMessages,
  toUIMessageStream,
} from 'ai';
import { openai } from '@ai-sdk/openai';
import { HindsightClient } from '@vectorize-io/hindsight-client';
import { createHindsightTools } from '@vectorize-io/hindsight-ai-sdk';

const hindsightClient = new HindsightClient({
  baseUrl: process.env.HINDSIGHT_API_URL,
});

export async function POST(req: Request) {
  const { messages, userId } = await req.json();

  const tools = createHindsightTools({
    client: hindsightClient,
    bankId: userId,
  });

  const result = streamText({
    model: openai('gpt-4o'),
    tools,
    stopWhen: isStepCount(5),
    system: 'You are a helpful assistant with long-term memory.',
    messages: await convertToModelMessages(messages),
  });

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream }),
  });
}

HindsightClient 인스턴스는 공유되고(모듈 수준에서 한 번 생성), createHindsightTools는 현재 사용자 ID로 요청마다 호출돼요.

설정 (Configuration)

인프라 옵션은 도구 생성 시 설정되어, 비용·태깅·성능을 애플리케이션이 제어하면서 의미적 선택(무엇을 기억할지, 무엇을 검색할지)은 모델에 맡겨요.

const tools = createHindsightTools({
  client,
  bankId: userId,
  retain: {
    async: true,
    tags: ['env:prod', 'app:support'],
    metadata: { version: '2.0' },
  },
  recall: {
    budget: 'high',
    types: ['experience', 'world'],
    maxTokens: 2048,
    includeEntities: true,
  },
  reflect: {
    budget: 'mid',
  },
});

`retain` 옵션

파라미터	타입	기본값	설명
`async`	`boolean`	`false`	fire-and-forget 수집 모드
`tags`	`string[]`	—	유지된 모든 메모리에 적용되는 태그
`metadata`	`Record<string, string>`	—	유지된 모든 메모리에 적용되는 메타데이터
`description`	`string`	내장	기본 도구 설명 오버라이드

`recall` 옵션

파라미터	타입	기본값	설명
`budget`	`'low' \| 'mid' \| 'high'`	`'mid'`	검색 깊이와 지연 시간 트레이드오프
`types`	`('world' \| 'experience' \| 'observation')[]`	전체	특정 팩트 유형으로 결과 제한
`maxTokens`	`number`	API 기본값	반환되는 최대 총 토큰
`includeEntities`	`boolean`	`false`	결과에 엔티티 관찰 포함
`includeChunks`	`boolean`	`false`	결과에 원시 소스 청크 포함
`description`	`string`	내장	기본 도구 설명 오버라이드

`reflect` 옵션

파라미터	타입	기본값	설명
`budget`	`'low' \| 'mid' \| 'high'`	`'mid'`	종합 깊이와 지연 시간 트레이드오프
`maxTokens`	`number`	API 기본값	최대 응답 토큰
`description`	`string`	내장	기본 도구 설명 오버라이드

메모리 도구 (Memory Tools)

도구	설명
`retain`	메모리 뱅크에 정보 저장
`recall`	쿼리를 사용해 메모리 검색
`reflect`	저장된 메모리에서 통찰 합성
`getMentalModel`	구조화된 지식 모델 검색
`getDocument`	식별자로 저장된 문서 검색

더 알아보기 (Learn more)

전체 API 문서와 설정 옵션은 Hindsight 문서를 참고하세요.

커스텀 프로바이더 작성하기

전체 사이트맵

Hindsight 프로바이더