# Hindsight: bộ nhớ giúp AI agent học dần theo thời gian — hướng dẫn cài đặt và dùng

> Hindsight là hệ thống bộ nhớ dài hạn cho AI agent, giúp agent không chỉ nhớ lại hội thoại mà còn học từ chúng. Bạn chạy một máy chủ bằng Docker hoặc pip, rồi gọi ba thao tác retain, recall, reflect từ Python, Node.js, Go hoặc CLI. Cài bằng Docker khá đơn giản nếu bạn đã có Docker và một khoá API của nhà cung cấp LLM.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-03 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/hindsight-bo-nho-ai-agent-huong-dan-cai-dat

Hindsight là một hệ thống bộ nhớ dành cho AI agent. Nó lưu lại những gì agent đã gặp, tìm lại đúng thứ cần khi cần, và tổng hợp chúng thành hiểu biết có chứng cứ. Tác giả mô tả nó là bộ nhớ "học được", không chỉ là nơi cất lịch sử trò chuyện.

Nếu bạn từng làm chatbot hay agent và thấy nó "quên sạch" sau mỗi phiên, repo này dành cho bạn. Nó hợp với lập trình viên mới muốn thêm trí nhớ cho ứng dụng AI. Nó cũng hợp với người dùng Claude Code, Cursor hay Codex muốn agent nhớ dự án của mình lâu dài. Dân kinh doanh dùng n8n, Zapier hay Dify cũng có đường tích hợp riêng.

Điểm đáng giá nhất là bạn không phải tự dựng hạ tầng tìm kiếm. Chỉ cần một máy chủ và ba lệnh: lưu, tìm, suy ngẫm. Repo hiện có khoảng 60.710 sao và 7.356 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | vectorize-io/hindsight
- kind | Framework
- desc | Hindsight là hệ thống bộ nhớ cho AI agent: lưu, tìm lại và rút ra hiểu biết từ những gì agent đã gặp, chạy bằng Docker hoặc pip.
- stars | 61k
- lang | Python
- license | MIT
```

## Hindsight làm được gì

### Ba thao tác cốt lõi

Toàn bộ cách dùng xoay quanh ba thao tác:

- **Retain**: đẩy thông tin vào bộ nhớ. Hindsight dùng một mô hình ngôn ngữ (LLM) để rút ra sự kiện, thời gian, thực thể và quan hệ từ câu bạn đưa vào.
- **Recall**: tìm lại ký ức. Hệ thống chạy song song bốn cách tìm: theo ngữ nghĩa, theo từ khoá, theo đồ thị liên kết và theo khoảng thời gian. Sau đó nó gộp và xếp hạng kết quả. Bạn hỏi "Alice làm nghề gì?" hay "Tháng Sáu có chuyện gì?" đều được.
- **Reflect**: phân tích sâu hơn trên những gì đã nhớ, để nối các mảnh ký ức lại hoặc trả lời câu hỏi cần suy nghĩ chứ không chỉ tra cứu.

### Các loại ký ức

Hindsight chia ký ức thành bốn loại: sự thật về thế giới, trải nghiệm của chính agent, nhận định (observations) được tổng hợp từ nhiều ký ức, và mô hình tinh thần (mental models). Các ký ức nằm trong các "bank", bạn có thể hiểu là mỗi bank là một ngăn nhớ riêng, ví dụ một bank cho mỗi khách hàng hoặc mỗi dự án.

### Dùng được với nhiều LLM

Theo README, Hindsight chạy với hơn 25 nhà cung cấp LLM, chọn qua biến `HINDSIGHT_API_LLM_PROVIDER`. Có loại trên mạng (openai, anthropic, gemini, groq…), loại chạy trên máy bạn (ollama, lmstudio, llamacpp) và loại cổng trung gian như litellm. Một số gói thuê bao sẵn có như ChatGPT Plus/Pro hay Claude Pro/Max cũng được hỗ trợ mà không cần API key.

### Tích hợp sẵn

README nêu hơn 60 tích hợp, phần lớn không cần sửa code. Có công cụ lập trình (Claude Code, Cursor, Codex, Copilot…), framework agent (LangGraph, CrewAI, LlamaIndex…) và công cụ ít code (n8n, Zapier, Dify, Flowise). Máy chủ nào cũng có sẵn đầu nối MCP cho mỗi bank.

### Giao diện quản lý

Chạy bằng Docker, bạn có sẵn một giao diện web để xem bộ nhớ. Rất tiện cho người mới muốn nhìn tận mắt thứ mình đã lưu.

## Cần chuẩn bị gì

Theo README, bạn cần:

- **Hệ điều hành**: Linux (x86_64, ARM64), macOS (Apple Silicon và Intel) và Windows (x86_64). Docker chạy được trên tất cả. Cài bằng pip trên Mac Intel thì README khuyên dùng `hindsight-all-slim`.
- **Một nhà cung cấp LLM**: thường là một API key (ví dụ OpenAI). Hindsight cần LLM để trích xuất ký ức khi bạn retain.
- **Docker** nếu chọn cách khuyến nghị. Nếu chọn cách pip thì cần Python và pip.
- **Node.js** (có `npx`/`npm`) nếu bạn dùng gói cho coding agent hoặc client Node.js.

README không nêu yêu cầu GPU hay dung lượng RAM tối thiểu. Phần này bạn nên xem thêm trong hướng dẫn cài đặt chính thức của dự án.

```note
API key là chìa khoá tính tiền của bạn. Đừng dán nó vào file code rồi đẩy lên GitHub. Hãy đặt vào biến môi trường như trong hướng dẫn bên dưới. Mỗi lần retain, Hindsight gọi LLM nên bạn sẽ phát sinh chi phí theo nhà cung cấp bạn chọn.
```

## Cài đặt từng bước

```steps
- Chuẩn bị khoá LLM | Lấy API key của nhà cung cấp, ví dụ OpenAI
- Chạy máy chủ | Dùng Docker (khuyến nghị) hoặc pip
- Mở thử API và giao diện | Vào cổng 8888 và 9999 trên máy
- Cài thư viện client | pip, npm, go hoặc CLI
- Gọi retain và recall | Lưu một ký ức, rồi hỏi lại
```

### Bước 1: Đặt khoá API vào biến môi trường

Mở terminal (Terminal trên Mac/Linux, hoặc Git Bash/WSL trên Windows nếu bạn chép đúng lệnh `export` bên dưới). Thay `sk-xxx` bằng khoá thật của bạn.

```bash
export OPENAI_API_KEY=sk-xxx
```

Lệnh này chỉ có tác dụng trong cửa sổ terminal hiện tại. Đóng terminal là mất, mở lại thì phải đặt lại.

### Bước 2: Chạy máy chủ bằng Docker (khuyến nghị)

Bạn cần Docker đã bật. Chép nguyên lệnh sau từ README:

```bash
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
```

Lệnh này tải ảnh Hindsight về, mở hai cổng 8888 và 9999, truyền khoá API vào máy chủ. Nó cũng gắn một ổ lưu `hindsight-data` để ký ức không mất khi bạn khởi động lại container. Lần đầu có thể mất vài phút để tải về.

Chỗ người mới hay vấp: dấu `\` cuối dòng là nối dòng trong bash. Dùng PowerShell thì bạn nên gộp lệnh thành một dòng, hoặc chạy trong Git Bash/WSL.

Muốn dùng nhà cung cấp khác OpenAI, README cho biết đổi qua biến `HINDSIGHT_API_LLM_PROVIDER`. Tên các biến cấu hình có trong file `.env.example` của repo: `HINDSIGHT_API_LLM_PROVIDER`, `HINDSIGHT_API_LLM_API_KEY`, `HINDSIGHT_API_LLM_MODEL`, `HINDSIGHT_API_HOST`, `HINDSIGHT_API_PORT`, `HINDSIGHT_API_LOG_LEVEL`.

### Cách khác: Docker với PostgreSQL ngoài

Nếu bạn muốn dùng cơ sở dữ liệu PostgreSQL riêng, README đưa cách dùng docker compose:

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

Bạn cần tải repo về trước và chạy lệnh trong thư mục repo:

```bash
git clone https://github.com/vectorize-io/hindsight.git
cd hindsight
```

Hãy thay `choose-a-password` bằng mật khẩu do bạn tự chọn.

### Cách khác: Cài bằng pip (không dùng Docker)

```bash
pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx

hindsight-api
```

Dòng đầu cài máy chủ, dòng hai đặt khoá, dòng ba khởi động máy chủ. README còn có cách chạy bằng Kubernetes (Helm) và bản quản lý sẵn Hindsight Cloud. Chi tiết xem trong hướng dẫn cài đặt chính thức của dự án.

### Bước 3: Cài client để gọi từ code

Chọn đúng ngôn ngữ bạn dùng:

```bash
pip install hindsight-client -U                                  # Python
npm install @vectorize-io/hindsight-client                        # Node.js / TypeScript
go get github.com/vectorize-io/hindsight/hindsight-clients/go     # Go
curl -fsSL https://hindsight.vectorize.io/get-cli | bash          # CLI
```

Bạn chỉ cần dòng của ngôn ngữ mình dùng. Người mới nên chọn Python cho dễ.

### Bước 4: Lưu và tìm lại ký ức đầu tiên

Tạo một file Python, chép đoạn sau và chạy:

```python
from hindsight_client import Hindsight

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

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

# Recall: Search memories
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: Generate disposition-aware response
client.reflect(bank_id="my-bank", query="Tell me about Alice")
```

`bank_id` là tên ngăn nhớ, bạn đặt gì cũng được. `base_url` phải khớp địa chỉ máy chủ của bạn.

### Tuỳ chọn: Chạy nhúng trong Python, không cần máy chủ riêng

Nếu bạn không muốn tự chạy máy chủ, README có cách nhúng thẳng vào chương trình Python:

```bash
pip install hindsight-all -U
```

```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?")
```

Trên Mac Intel, README yêu cầu cài `hindsight-all-slim` thay cho `hindsight-all`.

## Kiểm tra đã chạy được chưa

Với cách Docker, README cho biết hai địa chỉ:

- API: http://localhost:8888
- Giao diện: http://localhost:9999

Mở trình duyệt vào địa chỉ giao diện. Thấy trang web của Hindsight hiện ra là máy chủ đã chạy. Terminal đang chạy lệnh `docker run` cũng nên hiển thị log của máy chủ mà không báo lỗi.

Sau đó chạy đoạn Python ở bước 4. Nếu lệnh `retain` và `recall` chạy xong mà không báo lỗi kết nối, và `recall` trả về kết quả nhắc tới Alice, bạn đã cài thành công. Bạn cũng có thể mở giao diện để xem bank `my-bank` vừa được tạo. README không nêu một lệnh kiểm tra sức khoẻ riêng nào, nên hai cách trên là cách an toàn nhất.

## Dùng vào việc thật

### Chatbot chăm sóc khách hàng nhớ từng người

**Bối cảnh:** bạn bán hàng online và có chatbot trả lời khách. Mỗi lần khách quay lại, bot lại hỏi từ đầu.

**Cách làm:** dùng LLM Wrapper của repo. Cài `hindsight-litellm`, bọc client OpenAI của bạn, và đặt mỗi khách một `bank_id` riêng.

```bash
pip install hindsight-litellm
```

```python
from openai import OpenAI
from hindsight_litellm import wrap_openai

# Wrap your existing LLM client and you're done.
# Defaults to Hindsight Cloud; pass hindsight_api_url for a self-hosted server.
client = wrap_openai(
    OpenAI(),
    bank_id="user-123",
    hindsight_api_url="http://localhost:8888",
)

# Hindsight recalls relevant memories before the call
# and retains the conversation after it.
response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "What do you know about me?"}],
)
```

**Kết quả:** mỗi lần gọi, Hindsight tự tìm ký ức liên quan trước khi trả lời và tự lưu cuộc trò chuyện sau đó. Bạn chỉ sửa đúng hai dòng.

> Agent chỉ nhớ thôi chưa đủ, nó phải học được từ những gì đã nhớ.
>
> — Ông T

### Dev muốn Claude Code nhớ dự án

**Bối cảnh:** bạn làm một repo lớn. Mỗi phiên mới với coding agent, bạn lại phải giải thích lại kiến trúc và quy ước.

**Cách làm:** README có một gói cài cho các coding agent. Lệnh sau cài cho mọi agent được phát hiện trên máy, hoặc chỉ riêng Claude Code:

```bash
npx @vectorize-io/hindsight-coding-agents install all          # every detected agent, wired natively
npx @vectorize-io/hindsight-coding-agents install claude-code  # or just one
```

**Kết quả:** theo README, gói này dựng một bank riêng cho mỗi repo từ lịch sử git và các phiên trước, rồi đưa vào agent khi nó bắt đầu làm việc. README nói việc nạp dữ liệu là tự động, không có lệnh cài đặt thêm.

### Tự động hoá bằng MCP với công cụ có sẵn

**Bối cảnh:** bạn dùng một ứng dụng AI hỗ trợ MCP và muốn nó có công cụ lưu và tra cứu ký ức.

**Cách làm:** máy chủ nào cũng có sẵn đầu nối MCP cho mỗi bank, bật mặc định. Với máy chủ cục bộ, địa chỉ là:

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

Thay `{bank_id}` bằng tên bank, rồi trỏ ứng dụng MCP của bạn tới địa chỉ này.

**Kết quả:** ứng dụng thấy được các công cụ retain, recall và reflect. Cách cấu hình cụ thể cho từng ứng dụng nằm trong tài liệu MCP của dự án.

### Dùng ngay từ Node.js

**Bối cảnh:** bạn viết backend bằng JavaScript và muốn lưu ghi chú về từng khách hàng.

**Cách làm:** sau khi `npm install @vectorize-io/hindsight-client`, chạy đoạn mã sau:

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

**Kết quả:** console in ra các ký ức liên quan tới sở thích của Alice.

## Lỗi hay gặp và cách xử lý

### Docker báo cổng 8888 hoặc 9999 đã bị chiếm

Có phần mềm khác đang dùng cổng đó, hoặc bạn đã chạy container Hindsight trước đó. Hãy tắt chương trình đang chiếm cổng. Cách khác là đổi số cổng phía máy bạn trong tham số `-p` (phần bên trái dấu hai chấm). Nếu đổi, nhớ sửa `base_url` trong code cho khớp.

### Máy chủ chạy nhưng retain báo lỗi hoặc không lưu được

Nguyên nhân hay gặp là thiếu hoặc sai khoá API. Hindsight cần LLM để trích xuất ký ức. Kiểm tra lại biến `OPENAI_API_KEY` đã được đặt trong đúng cửa sổ terminal trước khi chạy `docker run` chưa. Nếu dùng nhà cung cấp khác, kiểm tra `HINDSIGHT_API_LLM_PROVIDER` và `HINDSIGHT_API_LLM_MODEL`. Xem log trong terminal để biết lý do chính xác.

### Code không kết nối được tới máy chủ

Kiểm tra `base_url` có đúng `http://localhost:8888` không, và container còn đang chạy không. Tắt terminal chạy `docker run -it` có thể làm dừng container, tuỳ cách bạn tắt. Chạy lại lệnh hoặc xem trạng thái trong Docker Desktop.

### Recall không trả về gì

Hãy chắc rằng bạn dùng cùng một `bank_id` cho cả retain và recall. Mỗi bank là một ngăn nhớ riêng, gõ lệch tên là tìm không ra. Với retain, việc xử lý bằng LLM cần một chút thời gian, nên nếu bạn recall ngay lập tức thì kết quả có thể chưa đầy đủ. Hãy thử lại sau ít giây.

### Cài pip trên Mac Intel bị lỗi

README đánh dấu cảnh báo cho Mac Intel khi cài bằng pip. Hãy dùng `hindsight-all-slim` thay cho `hindsight-all`, hoặc chuyển sang cách chạy Docker.

## Có nên dùng không

**Điểm mạnh:**

- Một hệ thống trọn gói: lưu, tìm bốn kiểu song song, và tổng hợp hiểu biết. Bạn không phải ghép nhiều công cụ.
- Giấy phép MIT, tự chạy trên máy hoặc máy chủ của bạn.
- Nhiều đường vào: Docker, pip, Helm, nhúng trong Python, và bản đám mây.
- Tích hợp rộng với công cụ lập trình, framework agent và công cụ ít code.
- Theo README, kết quả trên bài đo LongMemEval được nhóm nghiên cứu độc lập tái lập. Đây là số liệu do tác giả công bố, bạn nên tự thử với dữ liệu của mình.

**Giới hạn:**

- Cần một LLM để hoạt động, nên có chi phí API hoặc phải tự chạy mô hình cục bộ.
- Khái niệm bank, observation, mental model cần thời gian làm quen.
- README chưa nêu yêu cầu phần cứng. Nếu bạn định chạy mô hình cục bộ, hãy kiểm tra thêm.
- Nếu bạn chỉ cần lưu vài ghi chú cố định, một file văn bản hay cơ sở dữ liệu đơn giản có thể đủ.

**Khi nên chọn cách khác:** bạn muốn kiểm soát hoàn toàn thời điểm lưu và đọc? Dùng thẳng SDK hoặc REST API, như README gợi ý. Bạn không muốn tự vận hành máy chủ? Cân nhắc bản Hindsight Cloud, với chi phí theo mức dùng.

Tóm lại, nếu bạn đang làm agent cần nhớ lâu và học dần, Hindsight đáng thử. Cứ bắt đầu với Docker và đoạn Python năm dòng ở trên.

## Câu hỏi thường gặp

### Hindsight có miễn phí không?

Mã nguồn dùng giấy phép MIT nên bạn tự chạy miễn phí. Tuy nhiên bạn vẫn cần một nhà cung cấp LLM và có thể phát sinh phí API. Bản Hindsight Cloud tính theo mức dùng và có tín dụng miễn phí ban đầu, theo README.

### Chạy trên Windows được không?

Được. README liệt kê Windows (x86_64) hỗ trợ cả Docker, pip và cơ sở dữ liệu nhúng. Cách dễ nhất vẫn là Docker.

### Có cần GPU không?

README không nêu yêu cầu GPU. Hindsight dùng LLM qua nhà cung cấp bạn chọn, nên nếu dùng dịch vụ trên mạng thì không thấy yêu cầu này. Nếu chạy mô hình cục bộ, hãy xem thêm tài liệu cài đặt.

### Dùng được với mô hình không phải OpenAI không?

Được. README nói Hindsight hỗ trợ hơn 25 nhà cung cấp LLM qua biến HINDSIGHT_API_LLM_PROVIDER, gồm anthropic, gemini, groq và cả loại chạy trên máy như ollama. Một số gói thuê bao như ChatGPT Plus/Pro hay Claude Pro/Max cũng dùng được mà không cần API key.

### Dữ liệu của tôi có an toàn không?

Khi tự chạy máy chủ, ký ức nằm trên máy hoặc hạ tầng của bạn. Nhưng nội dung bạn retain sẽ được gửi tới nhà cung cấp LLM bạn chọn để xử lý. README không bàn kỹ về bảo mật, nên hãy xem file SECURITY.md trong repo.

### Hindsight khác gì RAG thông thường?

README cho biết Hindsight nhắm tới việc agent học được, không chỉ nhớ lại lịch sử. Nó kết hợp bốn cách tìm song song và tổng hợp ký ức thành nhận định. Tác giả nói cách này khắc phục hạn chế của RAG và đồ thị tri thức thuần.

### Tôi dùng Claude Code hoặc Cursor thì làm sao?

README có gói riêng cho coding agent, cài bằng lệnh npx @vectorize-io/hindsight-coding-agents install. Bạn có thể cài cho mọi agent phát hiện được hoặc chỉ một agent như claude-code.
