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
Bài này là một góc nhìn khác về vectorize-io/hindsight — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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ớ mã nguồn mở cho AI agent, giúp agent nhớ lâu và học dần từ những gì đã trải qua, không chỉ lưu lại lịch sử chat. Bạn chạy một máy chủ (cách dễ nhất là Docker), rồi gọi ba thao tác retain, recall, reflect qua Python, Node.js, Go, CLI hoặc REST API. Cài bằng Docker chỉ cần một lệnh và một API key của nhà cung cấp LLM.
Hindsight là một hệ thống bộ nhớ cho AI agent, mã nguồn mở, giấy phép MIT. Tác giả mô tả ngắn gọn: bộ nhớ giúp agent học được, chứ không chỉ nhớ lại. Bạn chạy Hindsight như một máy chủ nhỏ, rồi cho agent của bạn lưu thông tin vào đó và hỏi lại khi cần.
Vấn đề nó giải quyết rất quen thuộc: AI mỗi lần trò chuyện lại "quên sạch", hoặc chỉ nhớ được một đoạn chat gần nhất. Hindsight đứng giữa, giữ lại sự việc, con người, mốc thời gian, rồi gom thành những hiểu biết cô đọng hơn. Repo hiện có khoảng 60.710 sao và 7.356 fork, vẫn được cập nhật trong vài tháng gần đây.
Người nên đọc bài này: lập trình viên mới muốn làm chatbot hay agent có trí nhớ, người làm tự động hoá (n8n, Zapier, Dify, Flowise đều có tích hợp), và ai dùng trợ lý lập trình như Claude Code, Cursor, Codex muốn công cụ đó nhớ dự án. Điểm đáng giá nhất: bạn có thể thêm bộ nhớ chỉ bằng vài dòng code, hoặc một lệnh cài cho các trợ lý lập trình.
vectorize-io/hindsight
Hindsight là hệ thống bộ nhớ cho AI agent: lưu thông tin, tìm lại và rút ra hiểu biết mới, chạy bằng Docker hoặc pip, có SDK Python, Node.js, Go.
I.Hindsight làm được gì
A.Ba thao tác cốt lõi: retain, recall, reflect
Toàn bộ cách dùng xoay quanh ba động từ. Retain là cất thông tin vào bộ nhớ. Recall là tìm lại thông tin liên quan. Reflect là suy nghĩ sâu hơn trên những gì đã nhớ để trả lời một câu hỏi khó. Nhờ vậy bạn không phải tự viết cơ sở dữ liệu hay logic tìm kiếm.
B.Bộ nhớ được tổ chức như trí nhớ con người
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, các quan sát (niềm tin được tổng hợp từ nhiều ký ức, có bằng chứng đi kèm) và mô hình tinh thần (hiểu biết tổng hợp về thế giới của agent). Lợi ích thực tế: agent không chỉ nhắc lại câu bạn từng nói, mà dần hình thành hiểu biết như "khách này hay hỏi về vận chuyển".
C.Tìm kiếm bằng bốn cách cùng lúc
Khi recall, Hindsight chạy song song bốn chiến lược: tìm theo nghĩa (vector), tìm theo từ khoá (BM25), tìm theo liên kết giữa các thực thể, và lọc theo khoảng thời gian. Kết quả được gộp, xếp hạng lại và cắt cho vừa giới hạn token. Bạn hỏi "tháng Sáu có chuyện gì?" vẫn ra kết quả theo thời gian.
D.Gắn vào agent có sẵn gần như không phải sửa code
README nói có hơn 60 tích hợp: trợ lý lập trình (Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider...), framework agent (LangGraph, LlamaIndex, CrewAI, Pydantic AI, OpenAI Agents SDK...), công cụ no-code (n8n, Zapier, Dify, Flowise) và một số ứng dụng như Obsidian. Ngoài ra có LLM Wrapper bọc client OpenAI hoặc Anthropic để mỗi lần gọi đều tự lưu và tự nhớ.
E.Nhiều nhà cung cấp LLM, kể cả chạy máy cá nhân
Hindsight hỗ trợ hơn 25 nhà cung cấp LLM qua biến HINDSIGHT_API_LLM_PROVIDER: OpenAI, Anthropic, Gemini, Groq, Bedrock... và cả loại chạy cục bộ như ollama, lmstudio, llamacpp. Một số gói đăng ký có sẵn (ChatGPT Plus/Pro, Claude Pro/Max, Cursor, GitHub Copilot) được README ghi là không cần API key.
F.Máy chủ MCP có sẵn
Mỗi máy chủ có sẵn một đầu cuối MCP cho từng "bank" (kho nhớ), mặc định bật. Chỉ cần trỏ ứng dụng hỗ trợ MCP tới địa chỉ đó là có các công cụ retain, recall, reflect.
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), Windows (x86_64). Docker chạy được trên tất cả. Cài bằng pip trên Mac Intel có dấu cảnh báo: README bảo dùng
hindsight-all-slim. - Docker nếu chọn cách khuyến nghị. Với cách pip thì cần Python và pip (README không nêu số phiên bản cụ thể trong phần đã có).
- Một API key của nhà cung cấp LLM, ví dụ OpenAI. Hindsight dùng LLM để trích sự việc, thực thể, thời gian từ nội dung bạn lưu. Gói đăng ký có sẵn thì README nói không cần key.
- Cổng 8888 (API) và 9999 (giao diện web) còn trống.
- Phần cứng: README không nêu yêu cầu GPU hay RAM tối thiểu. Mình chưa có thông tin nên không khẳng định.
API key là chìa khoá tính tiền của bạn. Đừng dán thẳng vào file code rồi đưa lên GitHub. Hãy đặt qua biến môi trường như README làm, và nhớ rằng mỗi lần lưu ký ức, Hindsight sẽ gọi LLM nên có phát sinh chi phí theo nhà cung cấp bạn chọn.
III.Cài đặt từng bước
- Mở terminalDùng Terminal, Git Bash hoặc PowerShell có sẵn Docker
- Chạy máy chủDùng một lệnh docker run kèm API key
- Mở giao diệnVào cổng 8888 (API) và 9999 (UI) kiểm tra
- Cài clientCài thư viện Python, Node.js, Go hoặc CLI
- Thử retain và recallLưu một câu rồi hỏi lại
A.Bước 1: Chạy máy chủ bằng Docker (cách README khuyến nghị)
Mở terminal ở bất kỳ thư mục nào (không cần tải repo về). Lệnh dưới là nguyên văn README, viết cho Linux/macOS hoặc Git Bash trên Windows:
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Ý nghĩa: dòng export đặt key vào biến môi trường (thay sk-xxx bằng key thật của bạn). Lệnh docker run tải và chạy image Hindsight, mở cổng 8888 và 9999, truyền key vào biến HINDSIGHT_API_LLM_API_KEY, và gắn một volume tên hindsight-data để dữ liệu không mất khi khởi động lại container.
Người mới hay vấp: export và dấu \ xuống dòng không chạy trong PowerShell thuần. Nếu dùng PowerShell, bạn có thể làm tương tự như sau (đây là cách viết PowerShell phổ thông, README không ghi sẵn):
$env: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=$env:OPENAI_API_KEY -v hindsight-data:/home/hindsight/.pg0 ghcr.io/vectorize-io/hindsight:latestMặc định biến HINDSIGHT_API_LLM_PROVIDER chưa được đặt trong lệnh trên. Nếu bạn dùng nhà cung cấp khác OpenAI, hãy xem danh sách mô hình hỗ trợ trong tài liệu và đặt biến này cho đúng.
B.Bước 2: Mở giao diện kiểm tra
Khi máy chủ chạy, README ghi hai địa chỉ: API ở http://localhost:8888 và giao diện web ở http://localhost:9999. Mở địa chỉ thứ hai trên trình duyệt.
C.Các cách chạy máy chủ khác
Nếu bạn đã có PostgreSQL riêng, README có bản Docker Compose:
export OPENAI_API_KEY=sk-xxx
export HINDSIGHT_DB_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose upLệnh cd này chạy trong thư mục repo, nên bạn cần tải repo trước: git clone https://github.com/vectorize-io/hindsight.git rồi cd hindsight.
Nếu không dùng Docker, có cách cài bằng pip:
pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx
hindsight-apiVới Kubernetes dùng Helm:
helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
--set api.llm.provider=openai \
--set api.llm.apiKey=sk-xxx \
--set postgresql.enabled=trueCòn nếu không muốn tự dựng máy chủ, README nhắc tới Hindsight Cloud, bản dịch vụ có sẵn, tính phí theo mức dùng và có tín dụng miễn phí ban đầu. Khi đó bạn trỏ client tới https://api.hindsight.vectorize.io cùng API key của bạn.
D.Bước 3: Cài thư viện client
Máy chủ chỉ là nơi chứa bộ nhớ. Để gọi nó từ code, bạn cài client theo ngôn ngữ mình dùng. Nguyên văn README:
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 # CLIChỉ chạy dòng nào hợp với bạn. Người mới dùng Python thì chạy dòng đầu là đủ.
E.Bước 4: Chạy thử một lần retain và recall
Lưu file thu.py với nội dung sau (README nguyên văn):
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 của kho nhớ. Bạn đặt tên tuỳ ý, ví dụ mỗi khách hàng hoặc mỗi dự án một bank.
F.Không muốn chạy máy chủ riêng: chế độ nhúng cho Python
README có gói hindsight-all chạy ngay trong chương trình Python, không cần máy chủ riêng:
pip install hindsight-all -Uimport 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 bảo cài hindsight-all-slim thay thế.
IV.Kiểm tra đã chạy được chưa
Có ba dấu hiệu theo tư liệu:
- Terminal chạy Docker không báo lỗi và giữ nguyên (vì có cờ
-it), tên container làhindsight. - Trình duyệt mở được
http://localhost:9999(giao diện) và địa chỉ APIhttp://localhost:8888có phản hồi. - Chạy
thu.pyở bước 4 không báo lỗi kết nối. Lệnhrecallvới câu hỏiWhat does Alice do?nên trả về ký ức có nhắc tới Alice là kỹ sư phần mềm ở Google.
Nếu cả ba đều ổn, bạn đã có bộ nhớ chạy được. Muốn xem chi tiết kết quả trả về, hãy in biến kết quả ra màn hình trong code của bạn.
V.Dùng vào việc thật
A.Chatbot chăm sóc khách của chủ shop
Bạn làm chatbot trả lời khách bằng OpenAI. Muốn bot nhớ khách đã mua gì, hay hỏi gì. Dùng LLM Wrapper của README, mỗi khách một bank_id:
pip install hindsight-litellmfrom 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ả: trước mỗi lần gọi, Hindsight tìm ký ức liên quan; sau đó nó lưu lại cuộc trò chuyện. Bot trả lời có ngữ cảnh mà bạn không phải tự quản lý lịch sử.
Agent giỏi không phải agent nhớ nhiều nhất, mà là agent biết rút ra điều gì đáng nhớ.
Ông T
B.Lập trình viên muốn trợ lý code nhớ dự án
Bạn hay dùng Claude Code hoặc Cursor và mệt vì mỗi phiên lại phải giải thích lại cấu trúc dự án. README có một gói cho việc này:
npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
npx @vectorize-io/hindsight-coding-agents install claude-code # or just oneLệnh đầu cài cho mọi trợ lý được phát hiện trên máy, lệnh sau chỉ cài cho Claude Code. Theo README, mỗi repo có một kho nhớ tự dựng từ lịch sử git và các phiên trước, được đưa vào agent khi nó bắt đầu làm việc. README ghi là không có lệnh thiết lập riêng, việc nạp dữ liệu là tự động.
C.Người làm tài liệu: để trợ lý đọc tài liệu Hindsight ngay khi code
Nếu bạn tích hợp Hindsight vào dự án và không muốn tra web liên tục, README gợi ý cài skill tài liệu cho trợ lý lập trình:
npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docsSau đó trợ lý như Claude Code hay Cursor có thể tra tài liệu của Hindsight giúp bạn khi viết code.
D.Nhân viên văn phòng dùng công cụ no-code
Bạn không biết code nhưng đang làm quy trình trên n8n hay Dify. README liệt kê các công cụ này trong nhóm tích hợp no-code. Hướng đi thực tế: mở trang tích hợp tương ứng trong tài liệu (địa chỉ trong mục Integrations của trang chủ dự án), làm theo hướng dẫn riêng, rồi kết nối với máy chủ Hindsight bạn vừa dựng ở trên. Phần README mình có chưa mô tả từng bước cho các công cụ này nên mình không viết chi tiết thêm.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh export hoặc dấu \ báo lỗi trên Windows
Đây là cú pháp của bash. Hãy dùng Git Bash, hoặc dùng bản PowerShell ở trên, hoặc gõ cả lệnh docker run trên một dòng.
B.Cổng 8888 hoặc 9999 đã có chương trình khác dùng
Docker báo cổng đang bận. Hãy tắt chương trình đang chiếm cổng đó. Nếu đã chạy lệnh trước đó, container tên hindsight còn tồn tại và lệnh chạy lại sẽ báo trùng tên, bạn cần xoá hoặc khởi động lại container cũ (docker rm hindsight rồi chạy lại, hoặc docker start hindsight). Lưu ý dữ liệu nằm trong volume hindsight-data nên xoá container không mất ký ức.
C.Retain báo lỗi hoặc không lưu được vì key sai
Retain dùng LLM để trích thông tin, nên key sai, hết hạn hay hết tiền sẽ làm thao tác thất bại. Kiểm tra lại giá trị HINDSIGHT_API_LLM_API_KEY, và nếu dùng nhà cung cấp khác OpenAI thì đặt đúng HINDSIGHT_API_LLM_PROVIDER và HINDSIGHT_API_LLM_MODEL (các biến này có trong file .env.example của repo).
D.Client không kết nối được tới máy chủ
Kiểm tra container còn chạy không, và base_url trong code có đúng http://localhost:8888 không. Nếu máy chủ chạy ở máy khác hoặc Kubernetes, địa chỉ sẽ khác.
E.Cài pip trên Mac Intel bị lỗi
README đánh dấu cảnh báo cho trường hợp này. Hãy dùng hindsight-all-slim, hoặc chạy bằng Docker.
VII.Có nên dùng không
Điểm mạnh. Mã nguồn mở MIT, cài bằng một lệnh Docker, có nhiều SDK (Python, Node.js, Go, CLI, REST), nhiều tích hợp sẵn và hỗ trợ cả LLM chạy cục bộ. README cho biết Hindsight đạt kết quả hàng đầu trên bộ đánh giá LongMemEval và được các nhóm nghiên cứu độc lập tái lập. Đây là lời tác giả nêu, bạn nên tự thử trên dữ liệu của mình.
Giới hạn. Bạn phải vận hành một máy chủ (hoặc trả tiền cho bản Cloud). Mỗi lần lưu đều gọi LLM nên có chi phí và độ trễ. Khái niệm như bank, observation, mental model cần thời gian làm quen. Phần README mình có chưa nói rõ yêu cầu phần cứng.
Khi nào chọn cách khác. Nếu bạn chỉ cần một agent nhớ vài ghi chú, một file văn bản hay cơ sở dữ liệu đơn giản có thể đủ. Nếu muốn bộ nhớ chạy hoàn toàn trong máy và không gửi dữ liệu ra ngoài, hãy dùng nhà cung cấp LLM cục bộ như ollama. README liệt kê hướng này nhưng mình chưa có thông tin chi tiết về chất lượng của 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 máy chủ miễn phí. Tuy nhiên bạn vẫn trả tiền cho nhà cung cấp LLM bạn chọn, vì Hindsight gọi LLM khi lưu ký ức. Bản Hindsight Cloud tính phí theo mức dùng, có tín dụng miễn phí ban đầu.
Hindsight có cần GPU không?
Phần README có trong tư liệu không nêu yêu cầu GPU hay RAM. Nếu bạn dùng LLM của nhà cung cấp trên mạng như OpenAI thì phần suy luận chạy ở phía họ. Với mô hình chạy cục bộ, mình chưa có thông tin cụ thể.
Hindsight chạy được trên Windows không?
Có. README ghi Windows (x86_64) hỗ trợ cả Docker, pip và cơ sở dữ liệu nhúng pg0. Lưu ý các lệnh mẫu viết theo cú pháp bash, nên trên Windows hãy dùng Git Bash hoặc đổi sang cú pháp PowerShell.
Dữ liệu của mình có an toàn không?
Nếu tự chạy máy chủ, dữ liệu nằm trong volume Docker hoặc PostgreSQL của bạn. Nhưng nội dung vẫn được gửi tới nhà cung cấp LLM bạn chọn để xử lý, trừ khi bạn dùng LLM chạy cục bộ. Repo có file SECURITY.md, bạn nên đọc thêm; tư liệu mình có chưa mô tả chi tiết về bảo mật.
Hindsight khác gì RAG hay knowledge graph thông thường?
Theo tác giả, nhiều hệ thống nhớ chỉ dựa vào tìm kiếm vector hoặc đồ thị tri thức. Hindsight tổ chức ký ức thành sự thật, trải nghiệm, quan sát và mô hình tinh thần, đồng thời tìm bằng bốn chiến lược chạy song song. Tác giả nói cách này khắc phục các nhược điểm của RAG và knowledge graph; bạn nên tự đánh giá trên bài toán của mình.
Có dùng được với Claude Code hoặc Cursor không?
Có. README có gói hindsight-coding-agents cài bằng lệnh npx, hỗ trợ Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, opencode, Cline CLI và một số công cụ khác. Mỗi repo có kho nhớ riêng dựng từ lịch sử git và các phiên làm việc trước.
Có cần tự dựng máy chủ không?
Không bắt buộc. Bạn có thể dùng chế độ nhúng cho Python (gói hindsight-all) chạy ngay trong chương trình, hoặc dùng Hindsight Cloud rồi trỏ client tới địa chỉ API của họ. Cách Docker được README khuyến nghị cho người tự vận hành.


