Khi tích hợp các tác nhân AI (CLI Agents) như Claude Code vào quy trình làm việc, việc duy trì ngữ cảnh xuyên suốt các phiên làm việc là một thách thức lớn. obsidian-second-brain giải quyết vấn đề này bằng cách biến Obsidian Vault thành một bộ nhớ dài hạn, lưu trữ dưới dạng Markdown thuần túy. Thay vì chỉ bổ sung ghi chú mới một cách thụ động, hệ thống này sử dụng cơ chế "tự viết lại" (self-rewriting), nơi mỗi nguồn dữ liệu đầu vào sẽ kích hoạt quá trình cập nhật, giải quyết mâu thuẫn và tinh chỉnh các ghi chú hiện có.

Kiến trúc bộ nhớ và mô hình LLM Wiki

Đa số các hệ thống quản lý tri thức cá nhân hoạt động theo mô hình "chỉ thêm không sửa" (append-only). Theo thời gian, điều này dẫn đến sự phân mảnh thông tin và mâu thuẫn dữ liệu. obsidian-second-brain áp dụng mô hình LLM Wiki, trong đó Vault không chỉ mở rộng về kích thước mà còn "tiến hóa" về mặt nội dung. Khi một nguồn dữ liệu mới (URL, tài liệu, âm thanh) được nạp vào, hệ thống sẽ tự động phân tích và viết lại từ 5 đến 15 ghi chú liên quan để đảm bảo tính nhất quán.

Thiết lập môi trường và khởi tạo Vault

Để bắt đầu, bạn cần cài đặt gói kỹ năng và thiết lập cấu trúc thư mục cho Vault. Quá trình này có thể được tự động hóa thông qua các script cấu hình.

# Tải và cài đặt gói kỹ năng vào thư mục cục bộ
REPO_URL="https://gitcode.com/gh_mirrors/ob/obsidian-second-brain"
SKILL_DIR="$HOME/.config/cli-agents/skills/obsidian-brain"

git clone $REPO_URL $SKILL_DIR
chmod +x $SKILL_DIR/setup.sh
$SKILL_DIR/setup.sh --link-commands --register-hooks

Script cài đặt sẽ liên kết các lệnh gạch chéo (slash commands) với CLI và đăng ký các hook ngữ cảnh. Tiếp theo, khởi tạo cấu trúc Vault:

# Tạo cấu trúc Vault và chạy kiểm tra tính toàn vẹn
VAULT_PATH="$HOME/Documents/KnowledgeBase"
AGENT_PROFILE="researcher"

uv run python $SKILL_DIR/scripts/init_vault.py \
    --target-dir $VAULT_PATH \
    --profile $AGENT_PROFILE \
    --create-templates

# Kiểm tra sức khỏe của Vault sau khi khởi tạo
uv run python $SKILL_DIR/scripts/check_vault_health.py --path $VAULT_PATH

Sau khi cấu trúc thư mục được tạo, hãy khởi động lại CLI và chạy lệnh /obsidian-init tại thư mục gốc của Vault. Lệnh này sẽ tạo ra các tệp điều hướng cốt lõi như _CLAUDE.md (tài liệu hướng dẫn cho agent), index.md (mục lục động) và log.md (nhật ký hoạt động).

Luồng xử lý của lệnh /obsidian-ingest

Lệnh /obsidian-ingest là trái tim của hệ thống, chịu trách nhiệm tiếp nhận và đồng bộ hóa tri thức. Quy trình được chia thành bốn giai đoạn chính:

1. Phân loại và trích xuất dữ liệu

Hệ thống tự động nhận diện loại nguồn dữ liệu đầu vào để áp dụng chiến lược trích xuất phù hợp:

• URL / Blog: Trích xuất các luận điểm chính, thực thể và khái niệm.
• Tài liệu PDF: Phân tích cấu trúc, kết luận và các đề xuất hành động.
• Âm thanh / Video: Sử dụng Whisper cục bộ để chuyển đổi giọng nói thành văn bản, nhận diện người nói và trích xuất các cam kết.
• Hình ảnh: Áp dụng OCR và mô tả cấu trúc để đọc nội dung từ ảnh chụp màn hình hoặc bảng trắng.

2. Lưu trữ nguồn thô (Raw Storage)

Toàn bộ nội dung gốc được lưu trữ bất biến trong thư mục raw/ (ví dụ: raw/articles/2024-05-12 - topic.md). Metadata trong frontmatter sẽ bao gồm type: source, source_url và content_hash. Điều này đảm bảo mọi suy luận của AI sau này đều có thể truy vết về nguồn gốc ban đầu.

3. Cập nhật song song qua 4 Sub-Agent

Thay vì tạo các trang mới, hệ thống triển khai bốn tác nhân phụ để cập nhật Vault:

Lưu ý bảo mật: Dữ liệu đầu vào chỉ được xử lý như thông tin tham khảo. Hệ thống sẽ không thực thi bất kỳ chỉ thị nào (prompt injection) ẩn trong nội dung nguồn.

4. Tái lập chỉ mục và ghi nhật ký

Cuối cùng, hệ thống cập nhật index.md để phản ánh những thay đổi trong mô tả trang, ghi lại tóm tắt hoạt động vào log.md và cập nhật Daily Note. Một phiên ingest thành công phải tạo ra sự thay đổi sâu sắc trên các trang hiện có, thay vì chỉ tạo ra các trang mới.

Chính sách quản lý dữ liệu và độ tươi mới (Freshness)

Để ngăn chặn sự lỗi thời của thông tin, hệ thống áp dụng các quy tắc Open Knowledge Metabolism (OKM):

• Mọi sự kiện phải là phi thời gian, có gắn nhãn thời gian cụ thể, hoặc là một con trỏ đến nguồn dữ liệu.
• Các dữ liệu thay đổi nhanh chỉ được lưu dưới dạng liên kết kèm timestamp as of.
• Mỗi ghi chú bắt buộc phải có phần tóm tắt ## For future agent và sử dụng [[wikilinks]] để liên kết chéo.

Hệ sinh thái lệnh hỗ trợ

Bên cạnh /obsidian-ingest, bạn có thể kết hợp các lệnh sau để tối ưu hóa vòng đời của dữ liệu:

• /obsidian-save: Tự động phân rã một cuộc hội thoại thành các ghi chú liên kết (nhân vật, dự án, tác vụ).
• /obsidian-reconcile: Phát hiện và giải quyết các mâu thuẫn logic trong Vault.
• /obsidian-synthesize: Tổng hợp các mẫu thông tin ẩn từ nhiều nguồn khác nhau.
• /obsidian-health: Quét toàn bộ Vault để tìm các ghi chú mồ côi, luận điểm hết hạn hoặc vi phạm quy tắc độ tươi mới.

Các vấn đề kỹ thuật thường gặp

Agent có vô tình xóa hoặc ghi đè mất dữ liệu gốc không?
Không. Hệ thống không bao giờ thực hiện các thao tác xóa phá hoại mà không có xác nhận. Các ghi chú cũ được giữ nguyên trạng, trong khi các ghi chú mới tuân thủ quy tắc AI-first. Bạn có thể dùng /obsidian-health để rà soát và di chuyển dữ liệu theo nhịp độ riêng.

Yêu cầu về API Key và môi trường hoạt động?
Các lệnh cốt lõi quản lý Vault (ingest, save, find) hoạt động hoàn toàn offline và không yêu cầu API Key. Chỉ các lệnh nghiên cứu mở rộng (như /research) mới cần cấu hình key, và chúng sẽ tự động fallback về các nguồn mở như arXiv hoặc Wikipedia nếu không có key. Mã nguồn tương thích với nhiều CLI agent khác nhau và hoạt động ổn định trên cả macOS, Linux và Windows.