Memory tool trong Claude API: cho agent nhớ qua nhiều phiên

Agent của bạn hỗ trợ khách hàng hôm nay học được rằng "khách Acme thích nhận email", nhưng ngày mai ở hội thoại mới nó quên sạch. Nhồi toàn bộ lịch sử vào prompt thì tốn token và loãng ngữ cảnh. Memory tool của Claude API cho Claude một thư mục file nhớ để tự ghi, đọc, sửa, xoá qua các phiên. Nó chỉ đọc lại khi cần (just-in-time), nên context luôn gọn.

Cơ chế: client-side

• Bạn thêm tool {"type": "memory_20250818", "name": "memory"} vào request; không cần định nghĩa schema.
• Claude chỉ yêu cầu thao tác file; ứng dụng của bạn thực thi và trả kết quả trong tool_result. Dữ liệu nằm ở hạ tầng bạn kiểm soát: file trên đĩa, database, cloud storage.
• Đường dẫn /memories chỉ là tiền tố; handler của bạn ánh xạ nó vào nơi lưu thật, ví dụ thư mục riêng cho từng người dùng.
• Khi có memory tool, API tự thêm chỉ dẫn vào system prompt: luôn xem thư mục memory trước khi làm, ghi tiến độ khi làm vì context có thể bị reset bất cứ lúc nào.

Sáu lệnh handler phải xử lý

SDK Python và TypeScript có sẵn BetaLocalFilesystemMemoryTool lưu trên ổ đĩa, kèm tool runner tự chạy vòng lặp:

from anthropic.tools import BetaLocalFilesystemMemoryTool
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5", max_tokens=1024, tools=[memory],
    messages=[{"role": "user", "content": "Nhớ là khách Acme thích nhận email."}])
print(runner.until_done().content)

Kết hợp với các công cụ quản lý context

• Context editing: xoá kết quả tool cũ phía client; memory giữ lại điều cần nhớ.
• Compaction: tóm tắt hội thoại phía server khi gần chạm giới hạn; memory giữ thông tin phải sống qua bản tóm tắt.
• Mẫu phát triển nhiều phiên: phiên đầu tạo nhật ký tiến độ và danh sách tính năng trong memory; phiên sau đọc chúng để tiếp tục, cuối phiên cập nhật lại.

Rủi ro bảo mật: trách nhiệm của bạn

• Path traversal: đường dẫn như /memories/../../secrets.env có thể thoát ra ngoài. Kiểm tra mọi đường dẫn bắt đầu bằng /memories, chuẩn hoá rồi xác nhận vẫn nằm trong thư mục, chặn cả chuỗi mã hoá URL như %2e%2e%2f.
• Dữ liệu nhạy cảm: Claude thường từ chối ghi thông tin nhạy cảm, nhưng nên thêm bước lọc trước khi ghi.
• Kích thước và hạn dùng: giới hạn dung lượng file, giới hạn số ký tự view trả về, định kỳ xoá file lâu không dùng.
• Tách theo người dùng: đừng để memory của người này lọt sang người khác.

Áp dụng thế nào?

• Dev: Bắt đầu với handler lưu file có sẵn của SDK, thêm kiểm tra đường dẫn trước khi lên production.
• Tech Lead: Thiết kế không gian memory theo tenant/người dùng; viết test cho các ca path traversal.
• PM: Tính năng "trợ lý nhớ sở thích khách hàng" làm được mà không cần lưu toàn bộ lịch sử hội thoại.