Compartment: agent memory mã hóa offline trên máy bạn

Compartment khác ở điểm nào

Compartment là một kho lưu trữ memory của agent. Kho này mã hóa mọi bản ghi trên chính máy đã tạo bản ghi đó và không bao giờ kết nối đến network service. Có 2 điểm khiến nó khác với phần còn lại của hệ sinh thái agent memory. Vault là một file được niêm phong, chỉ passphrase của bạn mới mở được. Bước tạo embedding chạy cục bộ, nên nội dung của memory không bao giờ được gửi đi nơi khác để chuyển thành vector. Version 4.6.0 được phát hành vào 10 August 2026, giấy phép là Apache-2.0 và package được cài từ PyPI.

Đó là một tuyên bố về threat model, vì vậy guide này xem nó theo đúng cách đó. Mã hóa dữ liệu lưu trữ kết hợp với thiết kế offline bảo vệ một danh sách cụ thể. Chúng không bảo vệ được những yếu tố khác. Khoảng trống đó là nơi phát sinh các vấn đề khi vận hành sau ngày đầu tiên.

Guide này dựa trên tài liệu và release note của dự án, được đọc vào 11 August 2026. Compartment cung cấp desktop application, một mục trên menu bar của macOS và một biểu tượng trong notification area của Windows, bên cạnh CLI. Passphrase prompt không thể được điều khiển từ một container tự động. Hãy xem nội dung dưới đây là hành vi được tài liệu hóa, không phải hành vi đã được đo trong guide này. Hãy chạy nó trên một máy dự phòng trước khi giao phó dữ liệu thực tế.

Mã hóa dữ liệu khi lưu thực sự bảo vệ điều gì

Vault được bảo vệ bằng XChaCha20-Poly1305, một cipher AEAD (mã hóa có xác thực kèm dữ liệu liên kết). Các keyslot chứa master key được bọc bằng Argon2id, một hàm băm mật khẩu được thiết kế để chạy chậm và cần nhiều bộ nhớ. Có 2 hệ quả. Bản sao của file trên ổ đĩa bị đánh cắp, trong bản backup cũ hoặc được đính kèm trong ticket hỗ trợ chỉ còn là các byte, không có ý nghĩa gì. Nếu chỉ 1 bit bị thay đổi, quá trình xác thực sẽ thất bại khi mở file. Vì vậy, lỗi hỏng dữ liệu trở thành một lỗi rõ ràng thay vì tạo ra kết quả sai.

Các embedding vector cũng được mã hóa. Điều này quan trọng hơn vẻ ngoài của nó. Embedding không phải là hash. Nghiên cứu về việc đảo ngược embedding đã khôi phục được các đoạn văn bản gốc có thể đọc từ riêng vector đó. Vì vậy, để một vector index dạng plaintext nằm cạnh database đã mã hóa gần như tương đương với việc để database ở trạng thái mở. Compartment không ghi index dạng plaintext xuống disk.

Xóa là xóa thực sự. Mỗi record có key riêng, và compartment forget --shred hủy key đó. Vì vậy, không ai có thể giải mã ciphertext còn lại, kể cả bạn. So sánh với một row bị xóa khỏi file database: row này thường vẫn có thể đọc được trong các free page cho đến khi có dữ liệu khác ghi đè.

Offline là nửa còn lại. Không có dữ liệu nào được upload. Vì vậy, không có vendor account nào lưu giữ ký ức của bạn và không có API key nào có thể làm lộ chúng.

Compartment không bảo vệ được điều gì

Nhận định này chỉ đúng đến ranh giới của vault, và ranh giới đó gần hơn bạn tưởng.

Agent đọc plaintext. Recall giải mã memory rồi chuyển phần văn bản đó cho agent. Nếu agent là một model được host, memory sẽ đi đến nhà cung cấp model trong prompt tiếp theo, giống hệt mọi nội dung khác trong context window. Mã hóa khi lưu bảo vệ file. Nó không bảo vệ quá trình retrieval. Vì vậy, các quy tắc trong không đưa secret vào AI agent không được nới lỏng chỉ vì store đã được mã hóa: password được lưu dưới dạng memory là password mà bạn đã sắp xếp để tự động chèn vào prompt.

Vault đã unlock trên máy đang chạy thì đang mở. Ghi chú bảo mật của project nêu rõ điều này. Khi vault đã unlock, master key và working set nằm trong RAM, Python không thể đảm bảo buffer đã được xóa, còn swap hoặc hibernation image có thể ghi phần memory đó xuống disk. Malware chạy dưới user của bạn không cần phá cipher, vì nó có thể yêu cầu vault vốn đã unlock.

Danh tính của caller chỉ mang tính khai báo. Có thể giới hạn namespace theo từng caller, nhưng tên caller được truyền từ host process. Vì vậy, một host khai báo sai tên vẫn nhận được các quyền mà nó tự nhận. Namespace permission là cơ chế tổ chức, không phải security boundary chống lại local program độc hại.

Shredding không thể tác động đến các bản sao. forget --shred hủy key bên trong file hiện tại. Backup được tạo trước khi shredding vẫn chứa record đó và vẫn mở được bằng passphrase của ngày hôm đó.

Passphrase yếu khiến mọi biện pháp khác trở nên vô nghĩa. Argon2id làm cho mỗi lần đoán trở nên tốn kém. Nó không thể cứu một passphrase đã xuất hiện trong word list.

Cài Compartment từ bản phát hành đã ghim

Compartment cần Python 3.11 trở lên. Dự án phát triển nhanh, với 30 phiên bản trên PyPI tính đến ngày 10 tháng 8 năm 2026, vì vậy hãy ghim phiên bản thay vì cài bất kỳ phiên bản nào đang hiện hành tại thời điểm cài đặt.

python3 --version
pip install "compartment==4.6.0"
compartment --version
compartment init

compartment --version phải in ra phiên bản bạn đã ghim. Nếu shell trả về compartment: command not found, thư mục cài đặt chưa nằm trong PATH của bạn; trên hầu hết hệ thống, thư mục đó là ~/.local/bin. pipx install compartment==4.6.0 và uv tool install compartment==4.6.0 tự quản lý PATH nên không gặp vấn đề này.

compartment init yêu cầu nhập passphrase 2 lần và không hiển thị gì khi nhập. Passphrase đó là key duy nhất. Dự án không tạo password hay recovery phrase, và đây là chủ ý thiết kế: phần mềm không nắm giữ credential nào mà bạn không biết.

Kiểm tra kết quả trước khi kết nối bất kỳ thứ gì với nó.

compartment status

Vault hoạt động bình thường sẽ báo rằng nó đã được mở khóa. Nếu báo đang bị khóa, hãy chạy compartment unlock rồi nhập passphrase. Sau khi restart, vault sẽ bị khóa lại vì credential giữ cho vault mở phụ thuộc vào một per-boot secret. Trên macOS, compartment unlock --keychain cho phép credential này vẫn còn hiệu lực sau reboot bằng cách lưu nó vào system keychain.

Nơi dữ liệu thực sự nằm

Vault mặc định là ~/.compartment/memory.vault. Dùng --vault PATH trong bất kỳ lệnh nào để chỉ định vị trí khác, hoặc dùng biến môi trường COMPARTMENT_VAULT.

Một file đó là toàn bộ kho dữ liệu. File bắt đầu bằng header chứa phiên bản định dạng và các keyslot Argon2id, tiếp theo là payload đã được niêm phong, rồi đến các journal entry được nối thêm khi có memory mới. Mỗi journal entry có độ dài và CRC (cyclic redundancy check) của độ dài đó, nên thao tác ghi bị dừng giữa chừng do crash sẽ được nhận diện là entry bị cắt ngắn thay vì bị đọc như dữ liệu. Quá trình compaction serialize vault, ghi vào file tạm, gọi fsync, rồi rename file đó vào vị trí chính thức. Vì vậy, reader không bao giờ thấy vault chỉ được ghi một phần.

Hệ quả hữu ích là script backup chỉ cần copy đúng một path. Hệ quả bất tiện là bạn không thể dùng grep trên file này và cũng không thể sửa nó bằng text editor. Nếu muốn có memory mà bạn có thể đọc bằng cat và commit vào git, các file memory cục bộ dạng plain text của Memmy là lựa chọn theo hướng ngược lại. Cả hai đều hợp lý, tùy việc bạn lo laptop bị đánh cắp hay lo một tool bị hỏng.

compartment uninstall gỡ software nhưng giữ lại vault. Chỉ truyền --purge khi bạn thực sự muốn làm việc đó.

Kết nối vào agent

Một lệnh sẽ kết nối một client được hỗ trợ.

compartment integrate --list
compartment integrate claude

Với Claude Code, lệnh này tạo một mục server MCP (model context protocol) và một hook PostToolUse trong ~/.claude/settings.json, đồng thời sao lưu file trước. Lệnh cài một skill /compartmentalize trong ~/.claude/skills/ và thêm một managed block vào ~/.claude/CLAUDE.md để cho agent biết rằng Compartment thay thế cơ chế memory dựa trên file mà agent đang sử dụng. Xác nhận cả hai phần:

compartment hook status
compartment recent

Để tự đăng ký server bằng tay:

claude mcp add --scope user compartment -- \
    compartment --vault ~/.compartment/memory.vault --caller claude-code serve

Mọi host hỗ trợ MCP khác cũng dùng server này với tên caller riêng.

{ "mcpServers": { "compartment": {
    "command": "compartment",
    "args": ["--vault", "/path/to/memory.vault",
             "--caller", "your-agent-name", "serve"] } } }

Đặt giá trị --caller khác nhau cho từng host. Đây là nhãn được ghi vào audit log và là khóa dùng để ghi namespace grants, nên dùng chung một tên sẽ khiến cả hai mất tác dụng.

Nếu Claude Code đã ghi fact vào các file memory riêng, compartment import-claude --dry-run sẽ hiển thị những gì sẽ được chuyển trước khi thực hiện chuyển dữ liệu. Trước tiên, hãy đọc những gì Claude Code lưu trong các file memory của nó, vì nhập cả một năm ghi chú vào một vault mới là cách khiến memory store đầy những thứ không ai định giữ lại.

Kho local nhanh đến mức nào

Đây là các số liệu do dự án công bố cho một vault có kích thước phù hợp với sử dụng cá nhân. Các số liệu này lấy từ tài liệu của dự án, không phải từ một lần chạy thực tế ở đây.

[
  {
    "label": "Store one memory, end to end",
    "latency_ms": 40
  },
  {
    "label": "Embed one memory, bundled model",
    "latency_ms": 25
  },
  {
    "label": "Hybrid search, median",
    "latency_ms": 11.6
  },
  {
    "label": "Vector search at 20k records, p95",
    "latency_ms": 0.68
  }
]

Thời gian lưu một memory được công bố là 40 ms. Tìm kiếm vector trên hai mươi nghìn bản ghi có độ trễ 0.68 ms ở percentile 95. Lý do dự án đưa ra để giữ memory trên máy local là một phép tính đơn giản: một network round trip đến memory API được host thường tốn nhiều thời gian hơn mức median 11.6 ms của một lần hybrid search đầy đủ tại đây.

Hai chi tiết thiết kế giải thích các số liệu tìm kiếm này. Với dưới hai mươi nghìn bản ghi, Compartment so sánh query với mọi vector. Vì vậy recall là chính xác theo thiết kế, không phải kết quả xấp xỉ. Khi vượt quá ngưỡng đó, nó chuyển sang HNSW (hierarchical navigable small world), một index xấp xỉ đánh đổi một phần recall để lấy tốc độ. Vault cũng lưu hash SHA-256 của embedding model và từ chối mở bằng model khác. Lý do là vector từ hai model khác nhau vẫn có thể được so sánh mà không xuất hiện lỗi nào, trong khi các score trả về không còn có ý nghĩa.

Bản sao lưu và bản copy bạn vẫn có thể mở vào năm sau

Một vault đã khóa là một file độc lập, nên việc di chuyển nó chỉ là copy file.

compartment lock
scp ~/.compartment/memory.vault other-machine:
compartment --vault memory.vault unlock

Hãy khóa vault trước. Nếu copy trong khi agent đang ghi, bản copy có thể lấy phải một journal entry đang được append dở. Dù cơ chế framing bằng CRC cho phép reader bỏ qua phần fragment chưa hoàn chỉnh ở cuối file, phần memory nằm trong đó đã mất. compartment lock --sign đóng dấu file bằng manifest Ed25519, để máy nhận có thể xác minh bản copy đã đến nơi nguyên vẹn mà không cần giữ passphrase.

Vì file đã được đóng dấu, cloud storage thông thường là nơi lưu trữ chấp nhận được. Đây là lúc mã hóa at rest mang lại lợi ích trực tiếp: nơi nhận backup không bao giờ thấy memory.

Có 2 cảnh báo. Shredding không tác động đến các bản backup, nên một record bạn đã crypto shred hôm nay vẫn có thể đọc được trong bản copy của tuần trước bởi bất kỳ ai có passphrase của tuần trước. Và compartment export --plaintext ghi toàn bộ vault ở dạng không mã hóa. Đây là công cụ phù hợp để migrate sang hệ thống khác, nhưng không phù hợp để để lại trong ~/Downloads.

Chỉ giữ một số ít bản copy và ghi ngày cho từng bản. Một memory store trở thành rủi ro khi không ai dọn dẹp nó. Đây cũng là lý do được nêu trong vì sao memory cũ của agent âm thầm làm hỏng kết quả retrieval.

Xử lý key, xoay vòng và yếu tố thứ hai

compartment rekey
compartment 2fa enable
compartment 2fa status

rekey thay đổi passphrase bằng cách bọc lại master key trong keyslot của file hiện tại. Các bản sao cũ vẫn giữ passphrase cũ, vì các byte đó đã được niêm phong trước khi thay đổi và không có thao tác nào quay lại để sửa chúng. Hãy xoay vòng cả các bản sao, hoặc chấp nhận rằng passphrase đã loại bỏ vẫn mở được một số bản sao.

2fa enable thêm keyfile làm yếu tố thứ hai. Keyfile được kết hợp với passphrase trong quá trình dẫn xuất key, vì vậy cần cả hai để mở vault. Điều này cũng làm tăng gấp đôi số thứ bạn có thể làm mất. Không lưu keyfile trên máy đang chứa vault.

Đối với script và CI (continuous integration), passphrase có thể được truyền qua biến môi trường COMPARTMENT_PASSPHRASE, còn unlock --passphrase-stdin đọc passphrase từ pipe. Nên ưu tiên pipe. Các process khác do cùng user chạy có thể đọc biến môi trường, và biến này thường xuất hiện trong job log.

Lịch sử audit được liên kết bằng hash, còn compartment audit verify duyệt qua lịch sử đó và báo cáo liên kết đầu tiên bị hỏng. Hãy chạy lệnh này sau mỗi lần restore, vì đó là lúc file bị cắt ngầm mới lộ ra.

Điều gì xảy ra khi bạn mất passphrase

Không có gì xảy ra, và đó là thiết kế của hệ thống. Không có cơ chế reset, recovery phrase hay địa chỉ để ghi lại, vì không có bản sao nào của key tồn tại bên ngoài trí nhớ của bạn và keyfile tùy chọn. Vault vẫn chỉ là một file chứa các byte trông ngẫu nhiên.

Vì vậy, kế hoạch khôi phục không phải là kế hoạch cho vault. Đó là kế hoạch cho passphrase. Ghi passphrase vào password manager ngay trong ngày bạn chạy compartment init. Sau đó kiểm tra: khóa vault, mở khóa bằng đúng thông tin bạn đã ghi lại, rồi để một agent bắt đầu điền dữ liệu sau khi bước này thành công.

Compartment hay memory server

Compartment được thiết kế để chạy trên một máy duy nhất. Chia sẻ nghĩa là sao chép file đã khóa, hoặc export và import. Không có cơ chế ghi đồng thời, nên nếu laptop và workstation cùng trỏ đến một file, chúng sẽ ghi đè công việc của nhau.

Khi nhiều máy cần dùng cùng một memory tại cùng thời điểm, đó là bài toán server. Một Mem0 memory server tự host trên VPS giải quyết vấn đề này: một endpoint, nhiều client, và memory vẫn tồn tại ngay cả khi bạn không còn dùng laptop. Cần nói rõ về chi phí: server đó chạy một process có thể đọc dữ liệu mà nó lưu trữ. Vì vậy, threat model của bạn giờ bao gồm cả VPS và mọi người có thể truy cập API của server.

Hãy chọn dựa trên rủi ro mất mát mà bạn thực sự lo ngại. Nếu bạn lo laptop bị đánh cắp hoặc vendor đọc ghi chú của mình, encrypted local vault là lựa chọn mạnh hơn. Nếu bạn lo agent quên mọi thứ ngay khi bạn chuyển sang máy khác, hãy dùng server.

FAQ

Tính năng mã hóa của Compartment thực sự bảo vệ những gì?

Tính năng này bảo vệ file. Vault được niêm phong bằng XChaCha20-Poly1305, các keyslot được bọc bằng Argon2id và các embedding vector cũng được mã hóa. Vì vậy, disk bị đánh cắp hoặc backup cũ chỉ chứa các byte không có dữ liệu nào có thể đọc được. Tính năng này không bảo vệ vault đã mở khóa trên một máy đang chạy, vì master key nằm trong RAM khi vault đang mở. Tính năng này cũng không kiểm soát việc agent làm gì với memory sau khi nhận memory ở dạng plaintext từ thao tác recall.

Nếu Compartment offline, memory của tôi có riêng tư với nhà cung cấp model không?

Chỉ cho đến khi memory được recall. Việc lưu trữ và tìm kiếm diễn ra không cần network, còn embedding model chạy cục bộ, nên không có dữ liệu nào rời khỏi máy tại thời điểm ghi. Khi đọc, agent nhận plaintext. Nếu agent sử dụng hosted model, memory sẽ được đưa vào prompt và gửi đến nhà cung cấp giống như phần context window còn lại. Không bao giờ lưu credential dưới dạng memory.

Điều gì xảy ra nếu tôi mất passphrase của Compartment?

Vault sẽ không thể khôi phục, theo đúng thiết kế. Compartment không tạo seed hoặc recovery phrase, đồng thời không giữ credential nào mà bạn không tự giữ, nên không có gì để reset. Hãy lưu passphrase trong password manager, giữ keyfile 2FA ngoài máy đang lưu vault và xác nhận rằng bạn có thể unlock một bản sao trước khi vault chứa bất kỳ dữ liệu nào bạn không muốn mất.

Hai máy có thể dùng chung một vault Compartment không?

Không thể dùng đồng thời. Vault bị khóa là một file portable duy nhất. Quy trình được tài liệu hóa là lock vault, copy file, sau đó unlock file trên máy còn lại bằng --vault. Không có cơ chế truy cập đồng thời, nên nếu hai máy cùng ghi vào một file, các memory sẽ bị mất. Khi cần, hãy chạy memory server.