hindsight

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 20,039 Open GitHub ↗

Hindsight: Agent Memory That Learns

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Hindsight Banner](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/hindsight-github-banner.png)
[Documentation](https://hindsight.vectorize.io) • [Paper](https://arxiv.org/abs/2512.12818) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)
[![CI](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml/badge.svg)](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml)
[![Slack Community](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://join.slack.com/t/hindsight-space/shared\_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![PyPI - Downloads](https://img.shields.io/pypi/dm/hindsight-api?label=PyPI)
![NPM Downloads](https://img.shields.io/npm/dm/%40vectorize-io%2Fhindsight-client?logoColor=orange&label=NPM&color=blue&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40vectorize-io%2Fhindsight-client)
  
[![vectorize-io%2Fhindsight | Trendshift](https://trendshift.io/api/badge/repositories/15603)](https://trendshift.io/repositories/15603)

---
## What is Hindsight?
Hindsight™은 시간이 지남에 따라 학습하는 더 스마트한 에이전트를 만들기 위해 구축된 에이전트 메모리 시스템입니다. 대부분의 에이전트 메모리 시스템은 대화 기록을 회상하는 데 중점을 둡니다. 하지만 Hindsight는 단순히 기억하는 것을 넘어 학습하는 에이전트를 만드는 데 집중합니다.
[](https://github.com/user-attachments/assets/923b798d-3581-4897-bb62-9cfa5a931682)
RAG 및 지식 그래프와 같은 대체 기술의 단점을 없애고, 장기 메모리 작업에서 최고 수준(state-of-the-art)의 성능을 제공합니다.
## Memory Performance & Accuracy
Hindsight는 벤치마크 성능 측정 기준으로 지금까지 테스트된 에이전트 메모리 시스템 중 가장 정확합니다. 다양한 대화형 AI 시나리오 전반에서 메모리 시스템 성능을 평가하는 데 널리 사용되는 LongMemEval 벤치마크에서 최고 수준의 성능을 달성했습니다. 2026년 1월 기준 Hindsight 및 기타 에이전트 메모리 솔루션의 보고된 성능은 다음과 같습니다:
![Overview](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/hindsight-benchmarks.png)
Hindsight의 벤치마크 성능 데이터는 Virginia Tech의 [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) 및 The Washington Post의 연구 협력자들에 의해 독립적으로 재현되었습니다. 다른 점수들은 소프트웨어 공급업체가 자체 보고한 것입니다.
Hindsight는 포춘 500대 기업의 프로덕션 환경과 점점 더 늘어나는 AI 스타트업에서 사용되고 있습니다.
## Adding Hindsight to Your AI Agents
기존 에이전트에 Hindsight를 사용하는 가장 쉬운 방법은 LLM Wrapper를 활용하는 것입니다. 단 2줄의 코드로 에이전트에 메모리를 추가할 수 있습니다. 이를 통해 현재 사용 중인 LLM 클라이언트를 Hindsight 래퍼로 교체할 수 있습니다. 그 후에는 LLM을 호출할 때마다 메모리가 자동으로 저장되고 검색됩니다.
에이전트가 메모리를 저장하고 회상하는 방식과 시점을 더 세밀하게 제어해야 하는 경우, SDK를 사용하거나 HTTP를 통해 직접 연동할 수 있는 간단한 API도 제공됩니다.
![Hindsight Banner](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/migration-code.png)
---
> 🤖 \*\*코딩 에이전트를 사용하고 계신가요?\*\* Hindsight 문서 스킬을 설치하여 코딩하는 동안 즉시 문서를 확인하세요:
> ```bash
> npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
> ```
> Claude Code, Cursor 및 기타 AI 코딩 어시스턴트와 함께 작동합니다.
---
## Quick Start
### Docker (추천)
```bash
export OPENAI\_API\_KEY=sk-xxx
docker run -it --pull always --name hindsight --restart unless-stopped -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
>UI: http://localhost:9999
`HINDSIGHT\_API\_LLM\_PROVIDER`를 설정하여 LLM 제공자를 변경할 수 있습니다. 사용 가능한 옵션은 `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio`, `minimax`, 그리고 `atlas`([Atlas Cloud](https://www.atlascloud.ai/?utm\_source=github&utm\_medium=link&utm\_campaign=hindsight))입니다. [지원되는 모델](https://hindsight.vectorize.io/developer/models)에 대한 자세한 내용은 문서를 참조하세요.
### Docker (외부 PostgreSQL)
```bash
export OPENAI\_API\_KEY=sk-xxx
export HINDSIGHT\_DB\_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose up
```
> 완전한 기능 동등성을 갖춘 엔터프라이즈 배포를 위해 Oracle AI Database도 지원됩니다. 자세한 내용은 [스토리지 문서](https://hindsight.vectorize.io/developer/storage)를 참조하세요.
>API: http://localhost:8888
>UI: http://localhost:9999
### Client
```bash
pip install hindsight-client -U
# 또는
npm install @vectorize-io/hindsight-client
```
#### Python
```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: 성향 인식 결과 생성

esponse
client.reflect(bank\_id="my-bank", query="Tell me about Alice")
```
#### Node.js / TypeScript
```bash
npm install @vectorize-io/hindsight-client
```
```javascript
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 (서버 불필요)
```bash
pip install hindsight-all -U
```
Intel(x86\_64) 기반 Mac에서는 대신 `hindsight-all-slim`을 설치하세요. [지원되는 플랫폼](#supported-platforms)을 참고하세요.
```python
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?")
```
---
## 사용 사례 (Use Cases)
Hindsight는 대화형 AI 에이전트뿐만 아니라 자율적으로 작업을 수행하도록 설계된 에이전트를 지원하기 위해 만들어졌습니다. Hindsight의 이상적인 사용 사례는 개방형 작업을 처리하고, 사용자 피드백을 바탕으로 행동을 변경하며, 인간 수준에 가까운 업무 자동화를 위해 복잡한 작업을 수행하는 법을 학습해야 하는 AI 직원처럼 이러한 기능들의 조합이 필요한 에이전트입니다. Hindsight는 n8n 및 기타 유사한 도구로 구축된 것과 같은 간단한 AI 워크플로우와 함께 사용할 수도 있지만, 이러한 애플리케이션에는 과도할 수 있습니다.
### 사용자별 메모리 및 채팅 기록
Hindsight를 사용하는 비교적 간단한 사용 사례 중 하나는 개별 사용자와 연결된 메모리를 저장하고 리콜하여 AI 챗봇 및 기타 대화형 에이전트를 개인화하는 것입니다.
이 사용 사례의 요구 사항은 일반적으로 다음과 같습니다.
![Per-User Memories](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/per-user-memory-requirements.png)
[](https://github.com/user-attachments/assets/4805e8e1-e7d1-47c6-a4f8-2344a5ec8906)
Hindsight에서 이러한 요구 사항을 충족하는 것은 간단합니다. retain 작업을 사용하여 새로운 사용자 입력과 도구 호출을 Hindsight에 수집할 때, 커스텀 메타데이터를 사용하여 새로운 메모리를 보강할 수 있습니다. 메타데이터는 특정 사용자에게만 제한되어야 하는 메모리를 격리할 수 있는 편리한 방법을 제공합니다. 이러한 데이터가 retain 작업에 입력되면, 생성된 원시 메모리(raw memories) 및 멘탈 모델은 관련 메모리를 검색할 때 필터링될 수 있습니다.
![Per-User Memories](https://raw.githubusercontent.com/vectorize-io/hindsight-docs/main/hindsight-docs/static/img/per-user-memory-howto.png)
---
## 아키텍처 및 작업 (Architecture & Operations)
![Overview](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/hindsight-overview.webp)
대부분의 에이전트 메모리 구현은 기본 벡터 검색이나 지식 그래프(knowledge graph)를 사용합니다. Hindsight는 인간의 기억이 작동하는 방식과 유사하게 에이전트의 메모리를 조직하기 위해 생체 모방(biomimetic) 데이터 구조를 사용합니다.
- \*\*World (세계):\*\* 세계에 대한 사실들 ("스토브가 뜨거워진다")
- \*\*Experiences (경험):\*\* 에이전트 자신의 경험 ("스토브를 만졌고 정말 아팠다")
- \*\*Mental Models (멘탈 모델):\*\* 원시 메모리와 경험을 성찰하여 형성된 에이전트 세계에 대한 학습된 이해.
Hindsight의 메모리는 뱅크(즉, 메모리 뱅크)에 저장됩니다. 메모리가 Hindsight에 추가되면, 월드 팩트(세계 사실) 또는 경험 메모리 경로 중 하나로 푸시됩니다. 그런 이후 나중에 리콜을 돕기 위해 희소/밀집 벡터 표현(sparse/dense vector representations)과 결합된 엔티티, 관계, 시계열의 조합으로 표현됩니다.
Hindsight는 시스템과 상호작용하기 위한 세 가지 간단한 메서드를 제공합니다.
- \*\*Retain (보존):\*\* 기억하기 원하는 정보를 Hindsight에 제공합니다.
- \*\*Recall (리콜):\*\* Hindsight에서 메모리를 검색합니다.
- \*\*Reflect (성찰):\*\* 메모리에 대해 성찰합니다.

그리고 경험을 활용하여 기존 기억으로부터 새로운 관찰 결과와 통찰을 생성합니다.
### Retain
`retain` 작업은 Hindsight에 새로운 기억을 푸시하는 데 사용됩니다. 이는 Hindsight에 입력으로 전달한 정보를 \_retain\_(보관)하도록 지시합니다.
```python
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 및 reflect 작업에서 정확한 기억 검색을 수행할 수 있는 경로를 만들어 줍니다.
![Retain Operation](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/retain-operation.webp)
### Recall
recall 작업은 기억을 검색하는 데 사용됩니다. 이러한 기억은 모든 기억 유형(월드, 경험 등)에서 올 수 있습니다.
```python
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?")
```
Recall은 4가지 검색 전략을 병렬로 수행합니다.
- Semantic: 벡터 유사도
- Keyword: BM25 정확한 일치
- Graph: 엔티티/시간/인과 관계 링크
- Temporal: 시간 범위 필터링
![Recall Operation](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/recall-operation.webp)
검색에서 나온 개별 결과들이 병합된 후, 상호 순위 융합(Reciprocal Rank Fusion)과 크로스 인코더 재순위화(cross-encoder reranking) 모델을 사용하여 관련성 순으로 정렬됩니다.
최종 출력은 토큰 제한 내에 맞도록 필요에 따라 잘립니다.
### Reflect
reflect 작업은 기존 기억에 대해 더 철저한 분석을 수행하는 데 사용됩니다. 이를 통해 에이전트는 기억 간의 새로운 연결을 형성하고 자기가 속한 세계에 대해 더 깊이 있는 이해를 구축할 수 있습니다.
예를 들어, `reflect` 작업은 다음과 같은 유스케이스를 지원하는 데 사용할 수 있습니다.
- \*\*AI Project Manager\*\*가 프로젝트에서 어떤 리스크를 완화해야 하는지 성찰합니다.
- \*\*Sales Agent\*\*가 왜 특정 아웃리치 메시지는 응답을 받았고 다른 메시지는 그렇지 않았는지 성찰합니다.
- \*\*Support Agent\*\*가 현재 제품 문서로 답변되지 않는 고객의 질문이 있는 기회를 성찰합니다.
`reflect` 작업은 또한 더 깊은 사고가 필요한 온디맨드 질문 답변이나 분석을 처리하는 데에도 사용할 수 있습니다.
```python
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?")
```
![Reflect Operation](https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-docs/static/img/reflect-operation.webp)
---
## Resources
\*\*Documentation:\*\*
- [https://hindsight.vectorize.io](https://hindsight.vectorize.io)
\*\*Clients:\*\*
- [Python](http://hindsight.vectorize.io/sdks/python)
- [Node.js](http://hindsight.vectorize.io/sdks/nodejs)
- [REST API](https://hindsight.vectorize.io/api-reference)
- [CLI](https://hindsight.vectorize.io/sdks/cli)
\*\*Community:\*\*
- [Slack](https://join.slack.com/t/hindsight-space/shared\_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
- [GitHub Issues](https://github.com/vectorize-io/hindsight/issues)
---
## Star History
[![Star history](https://raw.githubusercontent.com/vectorize-io/hindsight/main/.github/star-history/chart.svg)](https://github.com/vectorize-io/hindsight/stargazers)
---
## Supported Platforms
| Platform | Docker | Bare Metal (pip) | Embedded DB (pg0) |
|----------|--------|------------------|--------------------

|
| \*\*Linux\*\* (x86\_64, ARM64) | ✅ | ✅ | ✅ |
| \*\*macOS\*\* (Apple Silicon / arm64) | ✅ | ✅ | ✅ |
| \*\*macOS\*\* (Intel / x86\_64) | ✅ | ⚠️ | ✅ |
| \*\*Windows\*\* (x86\_64) | ✅ | ✅ | ✅ |
⚠️ Intel Mac 사용 시: `hindsight-all-slim`을 사용하세요. 자세한 내용은 [설치 가이드](https://hindsight.vectorize.io/developer/installation#supported-platforms)를 참조하세요.
---
## 기여하기
[CONTRIBUTING.md](./CONTRIBUTING.md)를 참조하세요.
## 라이선스
MIT — [LICENSE](./LICENSE) 참조
---
제작: [Vectorize.io](https://vectorize.io)
![](https://umami-pixel.chris-latimer.workers.dev/?id=a8b043e6-6964-454d-80df-69b69d3f0d50&host=github.com&url=/vectorize-io/hindsight)

hindsight

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README