Hệ thống trí nhớ 3 tầng của OpenClaw: Giúp agent nhớ mọi thứ

Vấn đề kinh điển: Agent quên sạch mỗi sáng thức dậy

Bạn dành 30 phút giải thích cho agent về dự án, cách đặt tên biến, convention của team. Agent làm tốt cả ngày. Sáng hôm sau? Quên sạch. Bắt đầu lại từ đầu.

Đây là giới hạn cơ bản của LLM — mỗi phiên chat là một cuộc hội thoại mới, không có liên kết gì với phiên trước. OpenClaw giải quyết vấn đề này bằng hệ thống trí nhớ 3 tầng, mô phỏng cách con người nhớ: có thứ luôn nhớ, có thứ nhớ gần đây, và có thứ cần “lục lại” mới nhớ.

Tầng 1: MEMORY.md — Trí nhớ dài hạn (luôn được load)

MEMORY.md là file được đọc vào context mỗi phiên trò chuyện riêng tư (private session). Bất cứ thứ gì nằm trong file này, agent sẽ “nhớ” ngay khi bắt đầu chat.

Nên đặt gì trong MEMORY.md?

Những thông tin quan trọng nhất, dùng thường xuyên, và ít thay đổi:

# Memory

## Quyết định quan trọng
- 2026-03-15: Chuyển từ REST sang GraphQL cho internal API
- 2026-04-01: Dùng Resend thay SendGrid cho email
- 2026-04-10: Chọn VietinBank qua SePay cho payment gateway

## Convention đã thống nhất
- Commit message: conventional commits (feat:, fix:, docs:)
- Branch naming: feature/TASK-xxx-mô-tả-ngắn
- API response: { success: true, data: {} }

## Bài học rút ra
- Không mock database trong integration test (đã bị lỗi production)
- Luôn test email template trước khi deploy
- VPS provisioning cần timeout 120s, không phải 30s mặc định

Quy tắc vàng: Giữ MEMORY.md dưới 100 dòng. File này được load mỗi phiên, nên mỗi dòng đều tốn token. Chỉ giữ lại những gì thực sự quan trọng — phần còn lại để ở tầng 2 hoặc tầng 3.

Bảo mật: MEMORY.md chỉ được load trong phiên riêng tư (chat trực tiếp với bạn), không bao giờ load trong group chat. Điều này bảo vệ thông tin nhạy cảm của bạn.

Tầng 2: Daily Notes — Ngữ cảnh gần đây

Tầng 2 là các file ghi chú theo ngày trong thư mục memory/, theo format YYYY-MM-DD.md. OpenClaw tự động load file hôm nay và hôm qua vào context.

memory/
├── 2026-04-10.md
├── 2026-04-11.md   ← hôm qua, tự động load
└── 2026-04-12.md   ← hôm nay, tự động load

Đây là nơi agent ghi lại những gì xảy ra trong ngày — giống như cuốn sổ tay công việc. Khi bạn nói “nhớ cái này nhé”, agent sẽ ghi vào file daily note.

Ví dụ nội dung daily note:

# 2026-04-12

## Buổi sáng
- Deploy thành công v2.3.1 lên production
- Phát hiện bug pagination ở /admin/users (chưa fix)
- Khách hàng @minh_dev hỏi về API rate limit — đã trả lời qua Telegram

## Buổi chiều  
- Fix bug pagination — nguyên nhân: offset tính sai khi page > 10
- Commit: fix: correct pagination offset for admin users list
- Team lead nói tuần sau sẽ làm tính năng auto-deploy

Tại sao chỉ load 2 ngày? Vì context window có giới hạn. Load quá nhiều ngày sẽ tốn token và làm chậm response. Hai ngày gần nhất thường đủ cho phần lớn ngữ cảnh cần thiết. Thông tin cũ hơn? Đó là việc của tầng 3.

Tầng 3: Semantic Search — Tìm kiếm sâu trong trí nhớ

Tầng 3 là phần mạnh nhất và khác biệt nhất. Khi agent cần thông tin không có trong MEMORY.md hay daily notes gần đây, nó sẽ tìm kiếm trong toàn bộ thư mục memory bằng semantic search.

Cách hoạt động:

1. Tất cả file markdown trong workspace được chia thành các đoạn nhỏ (~400 token)
2. Mỗi đoạn được chuyển thành vector embedding
3. Vector được lưu trong SQLite (file .sqlite cục bộ)
4. Khi cần tìm, agent gửi câu hỏi → chuyển thành vector → tìm đoạn liên quan nhất

Ví dụ: bạn hỏi “lần trước mình xử lý lỗi SSL certificate thế nào?” Agent sẽ tìm trong tất cả daily notes và trả về đoạn ghi chú từ 2 tuần trước khi bạn fix lỗi đó — dù file đó không nằm trong context hiện tại.

Cấu hình semantic search:

Trong openclaw.json, phần agents.defaults.memorySearch:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "backend": "qmd",
        "maxResults": 6,
        "paths": ["memory/", "MEMORY.md", "AGENTS.md"]
      }
    }
  }
}

Hybrid search: OpenClaw dùng kết hợp vector search (70%) và keyword search (30%). Nghĩa là nó vừa hiểu ngữ nghĩa (“lỗi chứng chỉ bảo mật” khớp với “SSL certificate error”), vừa tìm chính xác từ khoá (hữu ích cho tên biến, ID, mã lỗi).

Tổ chức thư mục memory nâng cao

Ngoài daily notes, bạn có thể tổ chức memory theo chủ đề:

memory/
├── people/
│   ├── khach-hang-a.md    # Thông tin và lịch sử với khách hàng A
│   └── doi-tac-b.md       # Ghi chú về đối tác B
├── projects/
│   ├── onmay.md           # Ngữ cảnh dự án OnMay
│   └── side-project.md    # Dự án phụ
├── topics/
│   ├── devops.md           # Kiến thức DevOps đã học
│   └── nextjs-tips.md      # Mẹo Next.js phát hiện được
├── decisions/
│   └── payment-gateway.md  # Tại sao chọn SePay thay Stripe
└── 2026-04-12.md           # Daily note hôm nay

Semantic search tìm trong tất cả file này. Nghĩa là khi bạn hỏi “khách hàng A muốn gì?”, agent sẽ tìm đúng file people/khach-hang-a.md mà không cần bạn chỉ đường.

Embedding Provider — Cần gì để semantic search hoạt động?

Semantic search cần embedding provider để chuyển text thành vector. OpenClaw tự động phát hiện provider từ API key bạn đã cấu hình:

• OpenAI → text-embedding-3-small
• Google Gemini → embedding model
• Voyage AI → voyage-3
• Mistral → mistral-embed

Nếu bạn đã có API key của bất kỳ provider nào ở trên, semantic search sẽ tự bật — không cần cấu hình thêm.

Chạy trên VPS OnMay: VPS đã cài sẵn OpenClaw với cấu hình cơ bản. Bạn chỉ cần thêm API key (Anthropic hoặc OpenAI) và memory search sẽ sẵn sàng.

Mẹo tối ưu trí nhớ

Viết ghi chú có cấu trúc. Dùng heading rõ ràng trong memory file. Semantic search chia text theo chunk ~400 token — heading giúp mỗi chunk có ngữ cảnh đầy đủ hơn.

## Bug fix: Pagination offset sai ở admin users
- Ngày: 2026-04-12
- File: app/admin/users/page.tsx  
- Nguyên nhân: offset = page * limit thay vì (page - 1) * limit
- Fix: commit abc123

Đoạn ghi chú trên có đầy đủ ngữ cảnh trong một chunk — agent tìm thấy sẽ hiểu ngay.

Cross-reference giữa các file. Khi một concept liên quan đến nhiều file, thêm link hoặc ghi chú chéo:

## Quyết định dùng SePay
Xem chi tiết tại: decisions/payment-gateway.md
Liên quan: khách hàng yêu cầu bank transfer (people/khach-hang-a.md)

Dọn dẹp định kỳ. Mỗi tháng, dành 15 phút:

• Chuyển thông tin quan trọng từ daily notes vào MEMORY.md hoặc file chuyên đề
• Xoá daily notes cũ hơn 30 ngày (đã được index, xoá file không mất vector)
• Review MEMORY.md — bỏ những gì không còn đúng

Đừng nhồi nhét MEMORY.md. Nhiều người có xu hướng đưa mọi thứ vào MEMORY.md “cho chắc”. Sai lầm. 100 dòng memory curated tốt hơn 500 dòng memory lộn xộn. Thông tin ít dùng nên ở tầng 3 (semantic search) — agent sẽ tìm khi cần.

Kiểm tra memory đang hoạt động

Muốn biết agent đang “nhớ” gì? Thử các câu hỏi:

• “Bạn nhớ gì về dự án hiện tại?” → Test MEMORY.md
• “Hôm qua mình làm gì?” → Test daily notes
• “Lần trước fix bug X như thế nào?” → Test semantic search

Nếu agent không nhớ thứ bạn mong đợi, kiểm tra:

1. Thông tin đã được ghi vào file markdown chưa?
2. File có nằm trong path được cấu hình cho memorySearch không?
3. Embedding provider đã được thiết lập chưa? (cần API key)

Tổng kết

Hệ thống trí nhớ 3 tầng của OpenClaw giải quyết vấn đề lớn nhất của AI agent: tính liên tục giữa các phiên làm việc. MEMORY.md cho những gì luôn cần nhớ, daily notes cho ngữ cảnh gần đây, và semantic search cho kho kiến thức sâu.

Chìa khoá không phải nhớ nhiều — mà là nhớ đúng thứ, đúng lúc. Đầu tư thời gian tổ chức memory tốt, agent của bạn sẽ ngày càng thông minh hơn theo thời gian.