Memory MCP với Claude Code CLI and VS Code

Claude Code là nơi Memory MCP phát huy giá trị rõ nhất, vì đây là công cụ bạn dùng liên tục nhiều giờ mỗi ngày, trải qua rất nhiều session ngắn nối tiếp nhau. Không có memory, mỗi lần mở terminal mới hoặc mở lại VS Code, bạn lại phải nhắc agent về convention dự án, quyết định kiến trúc, hoặc lý do vì sao một đoạn code "trông kỳ lạ" nhưng thực ra là chủ đích. Bài này hướng dẫn cài đặt Memory MCP cho cả Claude Code CLI và extension Claude Code trong VS Code, thiết kế schema memory hợp lý cho một dự án thực tế, và cách phân định rõ ràng giữa Memory MCP với file CLAUDE.md — hai công cụ dễ bị dùng chồng lấn, gây trùng lặp thông tin nếu không hiểu đúng vai trò của từng bên.

Cài Đặt Và Kết Nối Memory MCP Với Claude Code

Claude Code hỗ trợ quản lý MCP server ngay từ CLI bằng subcommand claude mcp. Cách nhanh nhất để thêm Memory MCP ở phạm vi project:

claude mcp add memory --scope project \
  -- npx -y @modelcontextprotocol/server-memory

Lệnh trên tạo entry trong file cấu hình MCP của project (.mcp.json ở root repo). Muốn kiểm soát vị trí lưu file memory, set thêm biến môi trường:

claude mcp add memory --scope project \
  --env MEMORY_FILE_PATH=.claude/memory.jsonl \
  -- npx -y @modelcontextprotocol/server-memory

Sau khi thêm, kiểm tra server đã kết nối chưa bằng lệnh:

claude mcp list

Kết quả mong đợi hiển thị memory với trạng thái connected. Nếu bạn dùng flag --scope project, file .mcp.json sinh ra có dạng:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": ".claude/memory.jsonl"
      }
    }
  }
}

Với VS Code, nếu bạn dùng extension Claude Code, extension sẽ đọc đúng file .mcp.json này — không cần cấu hình riêng thêm. Nếu bạn muốn cấu hình MCP theo chuẩn chung của VS Code (dùng được cho cả GitHub Copilot Chat và các extension khác hỗ trợ MCP), tạo thêm file .vscode/mcp.json:

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "${workspaceFolder}/.claude/memory.jsonl"
      }
    }
  }
}

Sau khi lưu file, VS Code sẽ hiện icon "Start server" ngay trong file mcp.json (CodeLens) — bấm vào để khởi động, hoặc reload lại window. Xác nhận bằng cách mở Command Palette → MCP: List Servers.

Mẹo: Nên thêm .claude/memory.jsonl vào .gitignore nếu memory chứa thông tin riêng của bạn cá nhân, hoặc ngược lại commit nó vào repo nếu team muốn share chung một knowledge graph dự án — đây là quyết định team cần thống nhất từ đầu, đừng để mỗi người tự quyết dẫn đến file bị merge conflict liên tục.

Thiết Kế Memory Schema Cho Convention Và Quyết Định Kỹ Thuật Của Dự Án

Trước khi để agent tự do ghi memory theo cảm tính, hãy định nghĩa trước một schema tối giản bằng cách chốt danh sách entityType sẽ dùng cho dự án. Ví dụ với một dự án backend Django:

• convention — quy tắc coding, naming, structure.
• decision — architecture decision record, kèm ngày và lý do.
• component — mô-tả một module/service cụ thể trong hệ thống.
• gotcha — cạm bẫy, hành vi không hiển nhiên cần nhớ để tránh lặp lại lỗi cũ.

Bạn khởi tạo schema này bằng một prompt duy nhất đầu dự án:

Tạo trong memory 4 entity với entityType tương ứng: "convention", "decision",
"component", "gotcha". Mỗi entity đặt tên theo format
"<type>-<slug>", ví dụ "convention-api-response-format".
Bắt đầu với entity "convention-api-response-format" có observation:
"Mọi REST endpoint trả JSON theo format { data, error, meta }, không bao giờ
trả raw array ở top-level."

Agent sẽ gọi create_entities tương ứng:

{
  "tool": "create_entities",
  "arguments": {
    "entities": [
      {
        "name": "convention-api-response-format",
        "entityType": "convention",
        "observations": [
          "Mọi REST endpoint trả JSON theo format { data, error, meta }, không bao giờ trả raw array ở top-level."
        ]
      }
    ]
  }
}

Khi có quyết định kiến trúc mới, tạo relation nối decision với component bị ảnh hưởng, ví dụ decision "chuyển sang async task queue" affects component "order-service":

Ghi vào memory: chúng ta quyết định chuyển xử lý gửi email sang Celery task
queue vì gọi đồng bộ làm request timeout khi SMTP chậm. Tạo entity decision
tên "decision-async-email" và relation "affects" tới component
"component-order-service".

Mẹo: Đừng để agent tự đặt tên entity tự do — luôn ép theo convention <type>-<slug> ngay từ prompt đầu tiên. Nếu không, sau vài tuần bạn sẽ có hàng loạt entity trùng ý nghĩa nhưng tên khác nhau (api-format, apiResponseFormat, response-convention...), khiến search_nodes bỏ lỡ kết quả liên quan.

Ghi Và Truy Xuất Memory Trong Các Session Làm Việc Dài

Trong một ngày làm việc thực tế với Claude Code, memory phát huy tác dụng nhất ở hai thời điểm: đầu session (recall) và cuối một task lớn (capture).

Đầu session, thay vì mở đầu bằng việc paste lại brief dự án, dùng prompt ngắn:

Trước khi bắt đầu, hãy search memory cho các convention và gotcha liên quan
đến module "payment", rồi tóm tắt lại cho tôi trong 5 dòng.

Agent gọi search_nodes với query "payment", lấy về các entity liên quan, và tóm tắt — quá trình này chỉ tốn vài trăm token so với việc bạn phải giải thích lại toàn bộ ngữ cảnh.

Cuối một task lớn (ví dụ vừa hoàn tất một refactor, vừa fix một bug khó), chốt lại bằng prompt capture:

Tổng kết task vừa làm: chúng ta đã đổi cách tính phí giao dịch từ flat-fee
sang tiered-fee theo volume tháng. Ghi lại decision này vào memory, kèm lý do
và ảnh hưởng tới component "billing-service". Đồng thời ghi một gotcha: hàm
`calculate_fee()` cũ vẫn còn được gọi ở cron job legacy, chưa migrate.

Đây là thời điểm quan trọng nhất để dùng memory — ngay lúc kiến thức còn "nóng" trong đầu bạn và agent, capture lại trước khi nó biến mất theo session.

Mẹo: Tạo một custom slash command (ví dụ /wrap-up) trong Claude Code chỉ để thực hiện đúng việc "tóm tắt task vừa làm và ghi vào memory" — biến việc capture thành một thói quen một-lệnh, thay vì phải nhớ viết prompt dài mỗi lần.

Memory MCP So Với CLAUDE.md: Khi Nào Dùng Cái Nào

Nhiều người mới dùng Claude Code nhầm lẫn giữa hai cơ chế lưu ngữ cảnh này vì cả hai đều nhằm mục đích "giúp agent nhớ". Sự khác biệt nằm ở bản chất dữ liệu và cách nó được nạp vào context:

Nguyên tắc thực dụng: những gì luôn đúng và luôn cần, cho vào CLAUDE.md. Những gì phát sinh dần, số lượng lớn, chỉ cần tra khi liên quan, cho vào Memory MCP. Ví dụ, quy tắc "luôn dùng [English] prefix cho commit message của module này" nên nằm trong CLAUDE.md vì áp dụng cho mọi commit không ngoại lệ. Ngược lại, "lý do vì sao endpoint /v2/orders bị deprecated" chỉ cần khi ai đó chạm vào endpoint đó — phù hợp với Memory MCP hơn.

Trong thực tế, hai cơ chế này bổ trợ cho nhau: CLAUDE.md có thể có một dòng ngắn nhắc agent "luôn search memory trước khi bắt đầu task liên quan tới billing" — biến CLAUDE.md thành lớp rule cố định, còn Memory MCP là lớp kiến thức động phía sau.

Mẹo: Nếu CLAUDE.md của bạn đang dài hơn 200 dòng và có nhiều đoạn kiểu "lịch sử vì sao chúng ta chọn X thay Y", đó là dấu hiệu bạn nên chuyển phần lịch sử/lý do đó sang Memory MCP và giữ CLAUDE.md chỉ chứa rule hành động ngắn gọn.

Mẹo Hay Khi Dùng Memory MCP Với Claude Code

• Dùng claude mcp list thường xuyên để kiểm tra server memory còn kết nối — nếu path MEMORY_FILE_PATH bị đổi do di chuyển thư mục dự án, server sẽ start nhưng đọc nhầm file rỗng mà bạn không hề nhận ra.
• Với team dùng cả CLI và VS Code, đảm bảo cả .mcp.json và .vscode/mcp.json (nếu có) trỏ tới cùng một MEMORY_FILE_PATH — trỏ lệch sẽ tạo ra hai graph riêng biệt âm thầm, gây tình trạng "sao agent trong VS Code không biết điều tôi vừa dặn ở terminal".
• Review file .claude/memory.jsonl bằng git diff sau mỗi session dài — vì nó là JSON Lines, diff theo dòng rất dễ đọc và dễ phát hiện observation sai lệch trước khi commit.

Mẹo: Kết hợp Memory MCP với review theo lịch cố định (ví dụ mỗi thứ Sáu, 10 phút) để dọn observation lỗi thời — một memory graph không được chăm sóc sẽ dần mất giá trị giống một wiki nội bộ bị bỏ quên.