Memory

Mặc định, agent không nhớ gì giữa các tin nhắn — mỗi cuộc trò chuyện bắt đầu hoàn toàn mới. Memory thay đổi điều đó, giúp agent nhớ lại những gì đã nói trước đó, giống như một trợ lý thực sự.

Memory hoạt động như thế nào?

Mỗi khi bạn nhắn tin, tin nhắn được lưu lại. Lượt tiếp theo, agent đọc lại lịch sử đó trước khi trả lời — nên nó “nhớ” được bối cảnh.

Bạn:   "Tên tôi là Linh"
Agent: "Xin chào Linh!"

— lần sau —

Bạn:   "Tên tôi là gì?"
Agent: "Tên bạn là Linh."   ✓  (nhờ có memory)

Không có memory, agent sẽ trả lời: “Tôi không biết tên bạn.”

3 loại memory

🗂 KV — Nhớ ngắn hạn

Lưu lịch sử chat tạm thời. Tin nhắn tự xóa sau 24 giờ. Phù hợp cho thử nghiệm và các cuộc trò chuyện ngắn không cần lưu lâu.

Khi nào dùng: Demo, prototype, chatbot không cần nhớ qua ngày hôm sau.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'kv',
});

🗄 D1 — Nhớ lâu dài

Lưu lịch sử chat vĩnh viễn vào database. Agent nhớ được mọi cuộc trò chuyện, kể cả sau nhiều ngày hoặc nhiều tuần.

Khi nào dùng: Chatbot production, trợ lý cá nhân, bất kỳ ứng dụng nào cần nhớ lâu dài.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'd1',
  memoryTtl: 60 * 60 * 24 * 30,  // Tự xóa sau 30 ngày
});

🧠 Semantic — Nhớ theo ý nghĩa

Thay vì chỉ đọc N tin nhắn gần nhất, semantic memory tìm kiếm những ký ức liên quan đến câu hỏi hiện tại — dù chúng đã xảy ra từ rất lâu.

Ví dụ:

[2 tuần trước] Bạn:   "Tôi bị dị ứng với hải sản"

[Hôm nay]     Bạn:   "Gợi ý cho tôi một món ăn tối nay"
              Agent: "Vì bạn bị dị ứng hải sản, tôi sẽ không
                      gợi ý các món có tôm hoặc cá..."  ✓

Không có semantic memory, agent sẽ không biết thông tin từ 2 tuần trước dù nó đã được lưu.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'd1',
  memorySemantic: {
    enabled: true,
    topK: 5,              // Lấy tối đa 5 ký ức liên quan nhất
    scoreThreshold: 0.6,  // Chỉ dùng ký ức có độ liên quan ≥ 60%
  },
});

Tự động tóm tắt hội thoại dài (Compression)

Khi chat rất nhiều, danh sách tin nhắn ngày càng dài, làm chậm agent và tốn chi phí. Compression tự động tóm tắt các tin nhắn cũ thành một đoạn ngắn gọn.

Ví dụ:

TRƯỚC compression (80 tin nhắn):
  user:   "Tôi muốn học Python"
  agent:  "Python là ngôn ngữ lập trình..."
  user:   "Bắt đầu từ đâu?"
  agent:  "Bắt đầu với cú pháp cơ bản..."
  ... (80 tin nhắn)

SAU compression (2 tin nhắn):
  system: [Memory summary] Người dùng muốn học Python, đã thảo
           luận về cú pháp cơ bản, vòng lặp, hàm, đang học OOP...
  user:   "Hôm nay tôi muốn học về class"

Agent vẫn “nhớ” mọi thứ, nhưng gọn hơn rất nhiều.

const agent = new Agent({
  name: 'my-agent',
  model: { provider: 'groq', model: 'llama-3.3-70b-versatile' },
  memory: 'd1',          // Bắt buộc phải là D1
  maxMessages: 100,      // Giới hạn lịch sử tối đa
  memoryCompression: {
    threshold: 0.8,      // Compress khi đạt 80 tin nhắn (80% × 100)
    batchSize: 40,       // Mỗi lần tóm tắt 40 tin nhắn cũ nhất
  },
});

Cấu hình trong Dashboard

Bạn không cần sửa code — tất cả tham số memory có thể chỉnh trực tiếp trong tab Memory của mỗi agent trên Dashboard.

Phần Storage

Tham số	Ý nghĩa
Backend	Chọn KV, D1, hoặc None
Max messages	Số tin nhắn tối đa agent đọc mỗi lượt
TTL (days)	Sau bao nhiêu ngày thì xóa tin nhắn cũ. `0` = không xóa

Phần Compression (chỉ D1)

Tham số	Ý nghĩa
Compression toggle	Bật/tắt tự động tóm tắt
Threshold	Tóm tắt khi lịch sử đạt % này của Max messages
Batch size	Số tin nhắn được tóm tắt mỗi lần

Phần Semantic Memory

Tham số	Ý nghĩa
Semantic toggle	Bật/tắt tìm kiếm ký ức theo nội dung
Top-K recalls	Số ký ức liên quan tối đa được inject mỗi lượt
Score threshold	Ngưỡng độ liên quan tối thiểu (0–100%). Cao hơn = chính xác hơn

Thay đổi có hiệu lực ngay lập tức, không cần redeploy.

Nên chọn loại nào?

Tình huống	Gợi ý
Thử nghiệm / demo	KV
Chatbot đơn giản	D1, TTL 30 ngày
Trợ lý cá nhân	D1 + Compression + Semantic
Agent xử lý task độc lập	None

Cấu hình wrangler.toml

KV

[[kv_namespaces]]
binding = "KV"
id = "your-kv-namespace-id"

npx wrangler kv namespace create KV

D1

[[d1_databases]]
binding = "DB"
database_name = "my-agent-db"
database_id = "your-d1-id"

npx wrangler d1 create my-agent-db
npx wrangler d1 execute my-agent-db --file=node_modules/@moon-wave/memory/migrations/001_init.sql
npx wrangler d1 execute my-agent-db --file=node_modules/@moon-wave/memory/migrations/002_ttl.sql
npx wrangler d1 execute my-agent-db --file=node_modules/@moon-wave/memory/migrations/003_summary_scope.sql

Vectorize (Semantic Memory) {#cấu-hình-vectorize}

[[vectorize]]
binding = "VECTORIZE"
index_name = "my-agent-memory"

[ai]
binding = "AI"

npx wrangler vectorize create my-agent-memory --dimensions=768 --metric=cosine