Bỏ qua tới nội dung
Ông T.vn

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

11 phút đọcCập nhật
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

Tóm tắt nhanh

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.

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.

Framework

vectorize-io/hindsight

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.

★ 61kPythonMIT
Xem repo trên GitHub

I.Hindsight làm được gì

A.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.
  • Recalltì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.
  • Reflectphâ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.

B.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.

C.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.

D.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.

E.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.

II.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.

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.

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

  1. Chuẩn bị khoá LLMLấy API key của nhà cung cấp, ví dụ OpenAI
  2. Chạy máy chủDùng Docker (khuyến nghị) hoặc pip
  3. Mở thử API và giao diệnVào cổng 8888 và 9999 trên máy
  4. Cài thư viện clientpip, npm, go hoặc CLI
  5. Gọi retain và recallLưu một ký ức, rồi hỏi lại

A.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.

Terminal
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.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:

Terminal
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.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:

Terminal
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:

Terminal
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.

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

Terminal
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.

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

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

Terminal
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ễ.

F.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.

G.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:

Terminal
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.

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

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

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.

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

A.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.

Terminal
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

B.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:

Terminal
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.

C.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à:

Code
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.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.

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

A.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.

B.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.

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.

D.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.

E.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.

VII.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.

3.9/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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.

Chuyển nhanh tới mục

  1. I.Hindsight làm được gì
    1. A.Ba thao tác cốt lõi
    2. B.Các loại ký ức
    3. C.Dùng được với nhiều LLM
    4. D.Tích hợp sẵn
    5. E.Giao diện quản lý
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Bước 1: Đặt khoá API vào biến môi trường
    2. B.Bước 2: Chạy máy chủ bằng Docker (khuyến nghị)
    3. C.Cách khác: Docker với PostgreSQL ngoài
    4. D.Cách khác: Cài bằng pip (không dùng Docker)
    5. E.Bước 3: Cài client để gọi từ code
    6. F.Bước 4: Lưu và tìm lại ký ức đầu tiên
    7. G.Tuỳ chọn: Chạy nhúng trong Python, không cần máy chủ riêng
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chatbot chăm sóc khách hàng nhớ từng người
    2. B.Dev muốn Claude Code nhớ dự án
    3. C.Tự động hoá bằng MCP với công cụ có sẵn
    4. D.Dùng ngay từ Node.js
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Docker báo cổng 8888 hoặc 9999 đã bị chiếm
    2. B.Máy chủ chạy nhưng retain báo lỗi hoặc không lưu được
    3. C.Code không kết nối được tới máy chủ
    4. D.Recall không trả về gì
    5. E.Cài pip trên Mac Intel bị lỗi
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.