vibe-history

Hộp đen cho mọi phiên làm việc với AI — tự ghi, tự xếp theo dự án, tra lại trong tích tắc.

Câu chuyện 60 giây

Mỗi phiên làm việc với AI là một chuyến bay. Khi máy bay hạ cánh, một hộp đen lặng lẽ ghi lại toàn bộ hành trình rồi cất vào kho hồ sơ theo từng tuyến (dự án) — không bao giờ làm gián đoạn chuyến bay. Muốn nhớ sâu, một điều tra viên đọc trọn hộp đen và viết bản tóm tắt. Về sau, khi bạn hỏi "hồi đó làm việc này ở đâu?", bàn tra cứu lật đúng hồ sơ trong tích tắc. Nhờ vậy bạn không bao giờ mất lại trí nhớ nghề đã tích cóp.

Bản đồ tĩnh — 5 khu chức năng, 8 thành phần. Bấm vào bất kỳ ô nào để xem chi tiết.
Kích hoạt Thu nhận Xử lý Lưu trữ Tra cứu 1 🛎️ Bộ kích hoạt ghi SessionEnd · /done 2 📼 Dữ liệu bay thô transcript JSONL 3 🏷️ Gắn số hiệu chuyến git common-dir 4 ⚙️ Máy giải mã hộp đen 1 file .md / phiên 5 🔎 Điều tra viên enrich (tùy chọn) 6 🗄️ Kho hồ sơ chuyến bay ~1.1k file · ~106 dự án 7 📇 Mục lục kho (qmd) BM25 · vector 8 🔦 Bàn tra cứu search · vsearch · query
Điều khiển
Thu nhận
Xử lý
Lưu trữ
Một chuyến bay đi qua hệ thống: kích hoạt → ghi thô → giải mã → lưu → mục lục → tra cứu.
phiên xong transcript digest .md enrich gắn nhãn index hỏi 1 🛎️ Bộ kích hoạt ghi SessionEnd · /done 2 📼 Dữ liệu bay thô transcript JSONL 3 🏷️ Gắn số hiệu chuyến git common-dir 4 ⚙️ Máy giải mã hộp đen 1 file .md / phiên 5 🔎 Điều tra viên enrich (tùy chọn) 6 🗄️ Kho hồ sơ chuyến bay ~1.1k file · ~106 dự án 7 📇 Mục lục kho (qmd) BM25 · vector 8 🔦 Bàn tra cứu search · vsearch · query
luồng chính
tùy chọn (enrich)
tham chiếu (gắn nhãn)

Click vào bất kỳ thành phần nào để xem chi tiết.

Có gì · Không có gì

Ranh giới của hệ thống — biết trước để khỏi kỳ vọng sai

✅ Có

  • Tự động ghi mọi phiên — Claude và Codex đều có hộp đen riêng (cài độc lập), không phải nhớ bấm.
  • Xếp theo dự án, và phiên chạy trong git worktree được quy về repo gốc.
  • 1 file / phiên, ghi đè tại chỗ — không nhân bản snapshot.
  • Fail-open: lỗi hook không bao giờ làm hỏng /clear, /exit, /compact.
  • Tra cứu 3 kiểu: từ khóa (BM25), ngữ nghĩa (vector), lai + rerank.
  • Enrich an toàn: chỉ sửa frontmatter, body giữ nguyên byte, có backup.

⛔ Không có

  • Không lọc bí mật — ghi nguyên xi (chủ đích: kho local, không scrub).
  • Không tự cập nhật mục lục — phải chạy index/embed bằng tay.
  • Không tự enrich — bước tóm tắt sâu là thủ công, tốn token.
  • Không realtime — chỉ ghi lúc phiên kết thúc hoặc nén ngữ cảnh.
  • Không chia sẻ cross-máy/cloud — history lưu local, không commit vào repo, không đồng bộ.

Nên dùng khi · Không nên khi

Ai và lúc nào thì hộp đen này phát huy giá trị

👍 Nên dùng

  • Muốn nhớ "hồi trước mình xử lý X thế nào" — tìm lại phiên cũ.
  • Cần lật lại quyết định / bài học rải rác across nhiều dự án.
  • Trước khi làm lại một việc — tra xem đã từng làm chưa.
  • Onboard chính mình vào một dự án lâu không đụng.

👎 Không nên / đừng kỳ vọng

  • Đừng coi là nơi an toàn cho secret (không scrub).
  • Đừng kỳ vọng thấy phiên mới nếu chưa chạy index lại.
  • Đừng dùng để chia sẻ lịch sử cho đồng đội / máy khác.
  • Đừng dùng như log realtime theo dõi phiên đang chạy.

Cách setup

Cài từ package chia sẻ github.com/quynhfruby/vibe-history (repo chỉ chứa engine; history lưu riêng, không commit)

  1. Tải engine & chạy trình cài 1 bước. Cần Node trên PATH. Hỗ trợ Claude và Codex độc lập — có cái nào cài cái đó.# macOS: double-click install.command — hoặc: ./install.sh # Windows: double-click install.cmd — hoặc: powershell -ExecutionPolicy Bypass -File install.ps1Trình cài hỏi thư mục lưu history, tự dò ~/.claude + ~/.codex rồi wire hook tương ứng, backup trước khi sửa, không xoá gì mà không hỏi. Giữ nguyên vị trí folder sau khi cài (wiring trỏ vào đường dẫn này).
  2. Cấu hình (tùy chọn). Config ở đường dẫn per-user, độc lập vị trí repo: macOS/Linux ~/.config/vibe-history/config.json, Windows %APPDATA%\vibe-history\config.json.{ "historyRoot": "/path/to/vibe-history", "enabled": true, "timezone": "Asia/Ho_Chi_Minh" }Hoặc env: $VIBE_HISTORY_ROOT / $VIBE_HISTORY_ENABLED / $VIBE_HISTORY_TZ (env thắng config). Mặc định kho: ~/Documents/vibe-history.
  3. Cài công cụ tra cứu (qmd) — lớp recall tùy chọn.npm i -g @tobilu/qmd # lỗi native: npm rebuild better-sqlite3 -g
  4. Lập mục lục (BM25 — dùng được ngay). <base> = thư mục repo đã cài.node <base>/core/vibe-history-qmd-cli.cjs index
  5. (Tùy chọn) tìm theo ngữ nghĩa — tải model ~330MB lần đầu.node <base>/core/vibe-history-qmd-cli.cjs embed
  6. Tra cứu. search tức thì; vsearch/query cần đã embed.node <base>/core/vibe-history-qmd-cli.cjs search "flashsale countdown" -n 5

Bỏ qua installer? Wire tay: Claude đăng ký SessionEnd+PreCompact chạy <base>/claude/vibe-history-capture.cjs; Codex set notify trong ~/.codex/config.toml trỏ <base>/codex/codex-vibe-history-notify.cjs. Skill vibe-history-enrich/-search đặt trong ~/.claude/skills/. Muốn recall sắc hơn: chạy enrich rồi index lại.

Tra cứu hoạt động thế nào

Hai lớp mục lục — index (từ khoá) và embed (ý nghĩa) — quyết định bạn tìm được gì

LệnhCần embed?Cơ chếVí dụ
search (BM25)KhôngKhớp từ khoá trùng nhau — tức thì, không cần modeltìm "flashsale" → file có chữ "flashsale"
vsearch (vector)CóKhớp ý nghĩa gần nhau"đếm ngược khuyến mãi" → vẫn ra "flash sale countdown"
query (hybrid)CóLai BM25 + vector rồi xếp hạng lại (rerank) → chất nhấtcâu hỏi mơ hồ, cần kết quả sát ý nhất

📇 index — mục lục từ khoá

  • Bắt buộc để tra cứu. Dựng chỉ mục BM25, sẵn sàng ngay, không tải gì.
  • Là thứ tối thiểu để search chạy được.

🧠 embed — mục lục ý nghĩa

  • Tùy chọn. Biến từng đoạn văn thành vector (dãy số biểu diễn ý nghĩa) để so khớp theo nghĩa, không chỉ theo chữ.
  • Lần đầu tải model embedding ~330MB (bản đang dùng: embeddinggemma-300M); chỉ tải một lần.
  • Mở khoá cho vsearch và query — không chạy thì hai lệnh này không có dữ liệu để so.

⚠️ Mục lục không tự cập nhật

  • Cả index lẫn embed chạy tay — không có tiến trình nền tự reindex (chủ đích, tránh tốn máy).
  • Sau nhiều phiên mới, muốn tìm thấy chúng phải chạy lại index (và embed nếu dùng tìm theo nghĩa).
  • Hệ quả thực tế: nếu mục lục cũ (vd 11 ngày), các phiên gần đây chưa được nhúng nên vsearch/query không trả ra — không phải mất dữ liệu, chỉ là chưa đánh chỉ mục.

Bảng thuật ngữ

Ẩn dụ hộp đen ↔ hệ thống thật ↔ thuật ngữ ngành

Trong câu chuyệnLà gì trong hệ thốngThuật ngữ
Chuyến bayMột phiên làm việc với AIsession
Bộ kích hoạt ghiHook chạy lúc phiên kết thúc / nénSessionEnd · PreCompact
Băng ghi thôTranscript gốc của phiênJSONL transcript
Số hiệu tuyếnDự án phiên thuộc vềgit --git-common-dir
Máy giải mãDựng digest Markdown + nhãn tự độngmarkdown-builder
Hồ sơ chuyến bayFile .md, 1 file mỗi phiênper-session .md
Điều tra viênĐiền tóm tắt/quyết định/bài họcenrich (semantic frontmatter)
Kho hồ sơThư mục lưu, chia theo dự ánVIBE_HISTORY_ROOT
Mục lục khoChỉ mục từ khóa + ngữ nghĩaqmd index · embed
Bàn tra cứuTìm theo từ khóa / ý nghĩa / laisearch · vsearch · query