SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor · Cập nhật ngày 2026-08-26

Hướng dẫn cài đặt Memmy làm bộ nhớ chung cho AI agent

Cài đặt Memmy trên VPS để tạo kho lưu trữ bộ nhớ dùng chung cho các AI agent. Hướng dẫn build từ source, cấu hình service chạy tại port 18960 và quản lý dữ liệu local an toàn.

Verified Every command ran end-to-end on a fresh Ubuntu 24.04 server, July 31, 2026.

Memmy là gì và nó lưu trữ những gì

Memmy là một hub bộ nhớ cục bộ dành cho các AI agent, chạy trên VPS (virtual private server) của riêng bạn. Nó duy trì một cơ sở dữ liệu SQLite chứa những gì các agent đã học được, và mọi agent trên máy chủ đều đọc và ghi vào cùng một kho lưu trữ đó. Dự án này là memmy-agent từ MemTensor, được cấp phép theo MIT, phiên bản 1.0.4 tính đến tháng 7 năm 2026.

Chỉ một phần của nó là quan trọng trên máy chủ. Memmy cung cấp một dịch vụ bộ nhớ lắng nghe trên http://127.0.0.1:18960, một giao diện dòng lệnh (CLI) memmy-memory để giao tiếp với dịch vụ đó, và một workbench trên máy tính để bàn. Workbench chỉ được đóng gói cho macOS và Windows, vì vậy trên Linux VPS, bạn chỉ cần chạy dịch vụ và CLI. Điều đó là đủ để cung cấp bộ nhớ dùng chung cho Claude Code, Codex và Cursor.

Memmy sắp xếp những gì nó lưu trữ thành 4 lớp. L1 Trace là lượt tương tác thô: request, response và các lần gọi tool. L2 Policy là quy trình được suy ra từ những trace đã chứng minh được tính hữu ích. L3 World Model là kiến thức ổn định về một project hoặc một environment. Skill là quy trình có thể gọi, được kết tinh từ một policy. Service tự gán lớp khi ingest một lượt tương tác, nên bạn không cần tạo các lớp này thủ công. Nếu những phân biệt này vẫn có vẻ trừu tượng, memory là một trong các giai đoạn sau của lộ trình từng bước để học cách xây dựng agent, và các lớp sẽ dễ hiểu hơn sau khi bạn tự viết một agent loop đơn giản rồi quan sát nó quên mọi thứ giữa các lần chạy.

Hub bộ nhớ dùng chung thay đổi gì so với bộ nhớ riêng của từng công cụ

Mọi agent hiện nay đều tự quản lý bộ nhớ riêng. Claude Code lưu các file hướng dẫn trong repository. Cursor lưu các quy tắc trong cơ sở dữ liệu workspace. Codex lưu log phiên làm việc tại ~/.codex. Mỗi kho lưu trữ thuộc về một công cụ duy nhất, vì vậy một thông tin bạn đã cung cấp vào thứ Hai cho công cụ này sẽ không được công cụ khác biết đến vào thứ Ba. Bạn phải trả giá cho việc này hai lần: một lần bằng số token tốn kém để giải thích lại cùng một dự án, và một lần bằng kết quả công việc sai lệch khi agent hành động dựa trên một giả định mà bạn đã sửa ở nơi khác.

Một hub sẽ tách kho lưu trữ ra khỏi công cụ. Memmy cũng đọc các kho lưu trữ hiện có, vì vậy bạn không phải bắt đầu từ một cơ sở dữ liệu trống. Trình quét của nó nhận diện sáu nguồn: Claude Code tại ~/.claude/projects/**/*.jsonl, Codex tại ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl, OpenCode tại ~/.local/share/opencode/opencode.db, các file state.vscdb của Cursor, cơ sở dữ liệu SQLite của OpenClaw tại ~/.openclaw, và Hermes tại ~/.hermes. Bạn có thể thêm nguồn thủ công bằng cách cung cấp tên và đường dẫn cục bộ.

Các bộ đếm import sẽ không khớp nhau, và điều đó là bình thường. Trình quét nhóm các tin nhắn theo nguồn và hội thoại, sau đó ghi một bộ nhớ L1 cho mỗi lượt hoàn chỉnh. Một lượt được coi là hoàn chỉnh khi nó có nội dung người dùng không trống và kết thúc bằng một tin nhắn phản hồi không trống từ trợ lý, vì vậy một phiên làm việc bị gián đoạn sẽ không đóng góp gì. Các tin nhắn được loại bỏ trùng lặp bằng các điểm kiểm tra hội thoại và ID lượt ổn định. Số lượng được quét, số lượng tin nhắn được import và số lượng bộ nhớ mới sẽ khác nhau trong cùng một lần chạy.

Đây là phần kết hợp với cách Claude Code quản lý ngữ cảnh trong một phiên làm việc. Quản lý ngữ cảnh quyết định những gì vừa với một cửa sổ duy nhất. Hub bộ nhớ quyết định những gì còn tồn tại sau khi cửa sổ đó đóng lại.

Những gì bạn cần trên VPS

  • Node.js 22 hoặc mới hơn. Tài liệu của Memmy yêu cầu phiên bản này, trong khi Ubuntu 24.04 chỉ cung cấp Node 18.
  • git và một bộ công cụ build, vì better-sqlite3 là một module native có thể cần biên dịch trong quá trình cài đặt.
  • Khoảng 2 GB RAM. Quá trình cài đặt root sẽ tải về một workspace lớn và chuỗi build cho frontend.
  • Vài GB dung lượng đĩa trống cho node_modules và cơ sở dữ liệu.
sudo apt update
sudo apt install -y git build-essential python3 curl ca-certificates sqlite3
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

node --version sẽ hiển thị v22 hoặc cao hơn. Nếu v18 xuất hiện ở đây, nghĩa là bước cài đặt qua NodeSource chưa thành công, và quá trình cài đặt sau đó sẽ bị lỗi ở bước kiểm tra engine của dự án.

Cài đặt Memmy từ mã nguồn trên Ubuntu 24.04

git clone https://github.com/MemTensor/memmy-agent.git
cd memmy-agent
cp .env.example .env
npm install
npm run memory:build

npm run memory:build biên dịch workspace @memmy/memory thành Memory/dist. Không cần build bất kỳ thành phần nào khác trong cây thư mục cho một máy chủ headless. Kiểm tra xem module native đã được load chưa:

node -e "require('better-sqlite3'); console.log('better-sqlite3 loads')"

Nếu dòng lệnh đó báo lỗi thay vì in ra kết quả, nghĩa là module native không khớp với phiên bản Node của bạn. Hãy chạy npm rebuild better-sqlite3, đây chính xác là những gì script khởi động của dự án thực hiện trước khi chạy bất kỳ tiến trình nào.

Tài liệu README hướng dẫn dùng bash scripts/dev-start.sh như một lệnh khởi động nhanh. Đừng chạy lệnh này trên VPS headless. Nó khởi động Electron desktop shell và một Vite dev server trên cổng 19000 bên cạnh dịch vụ memory, và Electron cần một màn hình hiển thị. Do đó, trên máy chủ không có giao diện đồ họa, script sẽ bị treo hoặc thoát đột ngột.

Khởi động service bộ nhớ và kiểm tra phản hồi

npm run memory:serve:dev

Đây là cách được tài liệu hướng dẫn để chạy service bộ nhớ từ mã nguồn. Nó bind vào 127.0.0.1:18960, lưu database tại ~/.memmy/memory-service/memory.sqlite và đọc cấu hình từ ~/.memmy/config.yaml. File README cũng liệt kê các giá trị tương tự khi bạn muốn chỉ định rõ ràng:

npm run memory:serve:dev -- \
  --host 127.0.0.1 --port 18960 \
  --db ~/.memmy/memory-service/memory.sqlite \
  --config ~/.memmy/config.yaml

Từ một shell thứ hai, hãy kiểm tra xem service có đang hoạt động không:

curl -sS http://127.0.0.1:18960/api/v1/health

Health là endpoint duy nhất không yêu cầu token, vì vậy đây là probe phù hợp nhất. Nếu curl thoát với mã 7 và thông báo Failed to connect to 127.0.0.1 port 18960, nghĩa là không có tiến trình nào đang lắng nghe. Hãy đọc terminal đang chạy service, vì lỗi khi khởi động sẽ hiển thị tại đó; nguyên nhân thường gặp là module SQLite native không load được. ss -lntp | grep 18960 xác nhận socket sau khi service đã chạy.

Phần còn lại của HTTP API (giao diện lập trình ứng dụng) nằm dưới /api/v1.

  • POST /api/v1/memory/add ghi một bộ nhớ và POST /api/v1/memory/search truy vấn.
  • GET /api/v1/memory/:id và DELETE /api/v1/memory/:id đọc và xóa một mục.
  • POST /api/v1/sessions/open và POST /api/v1/sessions/:sessionId/close bao đóng một phiên làm việc của agent.
  • POST /api/v1/turns/start và POST /api/v1/turns/:turnId/complete ghi lại một lượt hội thoại.
  • GET /api/v1/panel/overview, /api/v1/panel/analysis và /api/v1/panel/items cung cấp dữ liệu cho dashboard.

Memmy sử dụng một dải cổng, và ở chế độ headless bạn chỉ dùng cổng đầu tiên: 18960 cho bộ nhớ, 18970 cho health của gateway, 18980 cho web UI và admin HTTP, 18990 cho API tương thích với OpenAI mà memmy serve khởi động, sau đó là 19000 và 19010 cho dev server của desktop frontend. Nếu một tiến trình nào đó trên máy của bạn đang chiếm một trong các cổng này, hãy kiểm tra danh sách trên để biết cần xử lý ở đâu.

Nguồn gốc thực sự của lệnh memmy-memory

Đây là bước mà quá trình cài đặt lần đầu thường gặp lỗi, vì vậy hãy đọc từ package thay vì đoán. Tên lệnh không liên quan gì đến tên repository. Nó đến từ trường bin của workspace định nghĩa nó:

node -p "JSON.stringify(require('./Memory/package.json').bin)"

Lệnh đó in ra {"memmy-memory":"./dist/src/cli/index.js"}. Do đó, entry point được build là Memory/dist/src/cli/index.js, và nó chỉ tồn tại sau khi chạy npm run memory:build, vì quá trình build chính là thứ tạo ra dist và cấp quyền thực thi cho file. Hãy chạy trực tiếp nó:

node Memory/dist/src/cli/index.js health

Nếu bạn muốn dùng tên ngắn trên PATH, hãy tạo link cho chính file đó:

sudo ln -s "$PWD/Memory/dist/src/cli/index.js" /usr/local/bin/memmy-memory
memmy-memory health

CLI mặc định sử dụng http://127.0.0.1:18960 và chấp nhận các tham số --url, --token, --config, --source và --user-id. Các subcommand của nó bao gồm init, health, search, add, get và delete, cộng với các lệnh gọi session và turn mà các agent sử dụng thay vì con người. memmy-memory search "deploy steps" và memmy-memory add "staging migrates on deploy" là hai lệnh mà một agent chạy thường xuyên nhất.

Làm thế nào để kết nối Claude Code với Memmy?

Claude Code không có giao diện plugin bộ nhớ, vì vậy Memmy không hook trực tiếp vào nó. Việc tích hợp đơn giản hơn thế. Claude Code chạy memmy-memory như một lệnh shell thông thường và một file hướng dẫn sẽ chỉ định khi nào cần thực hiện. Trình cài đặt được ghi lại của Memmy sẽ tạo file đó cho bạn: memmy-memory init --agent đặt một file hướng dẫn bộ nhớ vào thư mục quy tắc của agent mục tiêu.

Hãy tự viết hướng dẫn này một lần, vì khi đó bạn sẽ biết chính xác những gì agent đã được yêu cầu. Claude Code đọc CLAUDE.md từ thư mục gốc của dự án vào đầu mỗi phiên làm việc, vì vậy một phần như thế này chính là toàn bộ quá trình tích hợp:

## Memory

Before starting a task, run `memmy-memory search "<topic>"` and read what comes back.
When a task is done, run `memmy-memory add "<what you learned>"` for anything that will matter next session.

Hãy làm rõ những gì bạn nhận được từ việc này. Đây là tích hợp ở cấp độ hướng dẫn, vì vậy nó chỉ hoạt động khi model quyết định chạy lệnh, không phải lúc nào khác. Không có gì bắt buộc lệnh này phải được gọi. Nếu một phiên kết thúc mà không có add, sẽ không có dữ liệu nào được lưu và tín hiệu duy nhất là kết quả trống vào lần tiếp theo bạn tìm kiếm. Đây là sự đánh đổi tương tự như các file bộ nhớ của chính Claude Code, với một điểm khác biệt: kho lưu trữ được chia sẻ, vì vậy ghi chú cũng sẽ đến được với Codex và Cursor trên cùng một máy. Một bộ khung (harness) cung cấp giao diện plugin thực thụ sẽ thu hẹp khoảng cách này thay vì chỉ yêu cầu một cách lịch sự, đó là lý do tại sao bộ nhớ bền vững (durable memory) nằm cùng với các giới hạn ngân sách và quy tắc quyền hạn trong số các plugin DeepSeek Harness đáng cài đặt.

Chiều ngược lại không cần thiết lập gì cả. Trình quét của Memmy đã đọc ~/.claude/projects/**/*.jsonl, nơi Claude Code ghi lại các bản ghi phiên làm việc của nó. Hãy chạy Memmy trên cùng server nơi bạn chạy Claude Code bên trong một phiên tmux và công việc của ngày hôm qua sẽ trở thành bộ nhớ mà bạn không cần cấu hình bất cứ thứ gì.

Memmy có hoạt động như một MCP server cho Claude Code không?

Không, và việc biết rõ hướng hoạt động này sẽ giúp bạn tiết kiệm được cả buổi chiều. MCP (model context protocol) có các client và server. Memmy là một client. Nó kết nối ra các MCP server và cung cấp các công cụ của chúng cho runtime agent của chính nó. Nó không xuất bản một MCP endpoint mà claude mcp add có thể trỏ tới. Cầu nối MCP duy nhất trong repository thuộc về tích hợp Composio bên trong local API của desktop, và API đó bind một cổng ngẫu nhiên trên 127.0.0.1 phía sau header x-memmy-mcp-token của riêng nó.

Phía client được cấu hình trong ~/.memmy/config.yaml, file mà MEMMY_CONFIG trỏ tới, nằm dưới tools.mcpServers:

tools:
  mcpServers:
    example:
      type: stdio
      command: npx
      args:
        - "-y"
        - "your-mcp-server"
      toolTimeout: 30
      enabledTools:
        - "*"

type chấp nhận stdio, sse và streamableHttp. Một server stdio chạy như một tiến trình con của Memmy, nghĩa là lệnh của nó phải tồn tại trên cùng một máy và chạy dưới cùng một user. Nếu bạn đã duy trì các MCP server đang chạy trên một VPS, đó chính là những server cần liệt kê tại đây.

Giữ cho bộ nhớ lưu trữ ở chế độ riêng tư

Mọi thứ Memmy sở hữu đều nằm dưới ~/.memmy: config.yaml, không gian làm việc, memory-service/memory.sqlite và các file runtime. Việc quét và nạp dữ liệu diễn ra cục bộ, và các bộ nhớ được ghi vào file SQLite cục bộ đó, vì vậy trạng thái mặc định thực sự là cục bộ.

Có hai đường truyền kết nối ra mạng. MEMMY_CLOUD_SERVICE mặc định là https://memmy-api.memtensor.cn và hỗ trợ chế độ tài khoản với các token dùng thử, vì vậy chế độ API key không bao giờ gọi đến nó. Chương trình cải thiện bộ nhớ là một tùy chọn riêng trong cài đặt quyền riêng tư, mặc định tắt cho đến khi bạn bật nó lên.

Một đường truyền thứ ba dễ bị bỏ sót hơn. Nếu bạn cấu hình một nhà cung cấp embedding được host từ xa, nội dung của mọi bộ nhớ sẽ được gửi đến nhà cung cấp đó để chuyển đổi thành vector. Lưu trữ cục bộ không giúp ích gì trong trường hợp này. Một endpoint embedding do chính bạn host là cách duy nhất để đóng đường truyền đó.

Hãy giữ cổng 18960 ở địa chỉ loopback. Nó không cần rule firewall nào, vì một dịch vụ bind vào 127.0.0.1 hoàn toàn không thể truy cập được từ bên ngoài máy chủ. Thay vào đó, hãy truy cập nó từ laptop của bạn thông qua SSH:

ssh -N -L 18960:127.0.0.1:18960 you@your-vps

Nếu bạn bind nó rộng hơn, hãy thiết lập một token trước. Việc thiết lập storage.token trong file cấu hình, hoặc biến môi trường MEMMY_MEMORY_TOKEN hay MEMORY_SERVICE_TOKEN, sẽ khiến mọi endpoint ngoại trừ health đều yêu cầu một bearer token. Các giá trị cấu hình hỗ trợ tham chiếu ${ENV_NAME}, vì vậy token và các API key mô hình của bạn không nằm trong chính file đó. Đây cũng là thói quen tương tự như giữ bí mật không để lộ trong các AI agent ở mọi nơi khác, và chính sách ufw mặc định từ chối là chốt chặn an toàn nếu một phiên bản tương lai thay đổi địa chỉ bind mặc định của nó.

Sao lưu ~/.memmy trước khi tin tưởng nó

memory.sqlite là toàn bộ kho lưu trữ. Các vector nằm trong cùng file đó thông qua extension sqlite-vec, vì vậy chỉ cần sao lưu một file này là đủ. Việc copy nó bằng cp trong khi dịch vụ đang ghi dữ liệu có thể làm hỏng database. Hãy sử dụng lệnh sao lưu của chính SQLite:

mkdir -p ~/memmy-backup
sqlite3 ~/.memmy/memory-service/memory.sqlite ".backup '$HOME/memmy-backup/memory.sqlite'"

Lệnh này tạo ra một bản sao nhất quán trong khi dịch vụ vẫn đang chạy. Hãy đẩy bản sao này ra khỏi máy chủ theo lịch trình, đây là mục đích của restic đến lưu trữ ngoại vi. Mất config.yaml chỉ khiến bạn mất các thiết lập nhà cung cấp mà bạn có thể nhập lại. Mất memory.sqlite đồng nghĩa với việc mất toàn bộ bộ nhớ, và không có nơi nào khác trên máy lưu giữ bản sao thứ hai.

Chạy memory service dưới systemd

npm run memory:serve:dev trong shell sẽ bị tắt khi shell đóng. Một unit file giúp duy trì service sau khi reboot.

[Unit]
Description=Memmy memory service
After=network-online.target

[Service]
Type=simple
User=memmy
WorkingDirectory=/opt/memmy/memmy-agent
EnvironmentFile=/etc/memmy/memory.env
ExecStart=/usr/bin/npm run memory:serve:dev
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Không để token trong unit file. Hãy đặt nó vào /etc/memmy/memory.env, cấp quyền sở hữu cho root, mode 600:

MEMMY_CONFIG=/home/memmy/.memmy/config.yaml
MEMMY_MEMORY_TOKEN=replace-this-with-a-long-random-string
sudo systemctl daemon-reload
sudo systemctl enable --now memmy-memory
systemctl status memmy-memory --no-pager
curl -sS http://127.0.0.1:18960/api/v1/health

status=203/EXEC trong kết quả status nghĩa là systemd không thể chạy ExecStart, hãy kiểm tra which npm: nó là /usr/bin/npm trên bản cài đặt NodeSource và nằm trong thư mục home của user nếu dùng nvm, nơi mà systemd sẽ không tìm thấy. Một unit khởi động rồi thoát ngay lập tức nghĩa là lỗi xảy ra bên trong npm, và journalctl -u memmy-memory -n 50 sẽ in ra lý do. Cơ chế này tương tự như bất kỳ systemd service nào khác trên VPS.

Những tính năng Memmy chưa hỗ trợ

  • Chưa có bản build cho Linux desktop. Các script đóng gói hiện chỉ hỗ trợ macOS và Windows, vì vậy workbench, trình hướng dẫn thiết lập và bảng điều khiển bộ nhớ chưa khả dụng trực tiếp trên server.
  • memory:serve:dev chạy entry point TypeScript thông qua tsx, một đường dẫn dành cho phát triển. Repository cũng cung cấp memory:serve cho các output đã biên dịch. Chạy npm run không kèm tham số để xem các script thực tế mà bản checkout của bạn đang có.
  • Tính năng Retrieval xây dựng cửa sổ tìm kiếm từ 2,000 hàng vector mới nhất, sau đó áp dụng lựa chọn Top-K trong phạm vi đó. Với kho dữ liệu rất lớn, một bộ nhớ cũ có thể nằm ngoài phạm vi này.
  • Embedding diễn ra sau khi capture, và nếu thất bại, tác vụ sẽ được đưa vào hàng đợi retry thay vì chặn lượt xử lý của agent. Một bộ nhớ vừa được thêm vào có thể chưa tìm kiếm được ngay bằng vector search.
  • Một file SQLite tương ứng với một node. Không có tính năng clustering, vì vậy server thứ hai sẽ là một bộ nhớ riêng biệt hoàn toàn.

Phiên bản 1.0.4 với khoảng 329 sao tính đến tháng 7 năm 2026 cho thấy đây là một dự án còn mới. Các flag, đường dẫn và tên script có thể thay đổi giữa các bản release. Hãy đọc trường bin và output của npm run trong bản checkout của chính bạn thay vì tin tưởng vào các lệnh được sao chép từ bất kỳ đâu, kể cả tài liệu này.

FAQ

Tại sao health check trả về lỗi connection refused?

Không có tiến trình nào đang lắng nghe trên cổng 18960. Mã thoát 7 của curl kèm theo Failed to connect to 127.0.0.1 port 18960 nghĩa là memory service chưa chạy hoặc đã bị crash ngay khi khởi động, vì vậy hãy kiểm tra terminal hoặc journal nơi nó bắt đầu. Hai nguyên nhân phổ biến là better-sqlite3 native module không khớp với phiên bản Node của bạn, có thể sửa bằng npm rebuild better-sqlite3, và phiên bản Node thấp hơn 22. Xác nhận socket bằng ss -lntp | grep 18960 sau khi service đã chạy.

Lệnh memmy-memory đến từ đâu sau khi build từ source?

Nó đến từ trường bin của gói workspace @memmy/memory, không phải từ tên repository. Chạy node -p "JSON.stringify(require('./Memory/package.json').bin)" bên trong thư mục checkout và nó sẽ in ra {"memmy-memory":"./dist/src/cli/index.js"}. File đó chỉ tồn tại sau khi chạy npm run memory:build, vì quá trình build tạo ra dist và đánh dấu file đó là thực thi được. Chạy nó dưới dạng node Memory/dist/src/cli/index.js health, hoặc tạo symlink vào /usr/local/bin để dùng tên ngắn.

Tôi có thể thêm Memmy vào Claude Code bằng claude mcp add không?

Không. Memmy là một MCP client, không phải MCP server. Nó kết nối ra các server được liệt kê trong tools.mcpServers tại ~/.memmy/config.yaml và cung cấp các công cụ của chúng cho runtime của chính nó. Claude Code kết nối với Memmy theo chiều ngược lại, bằng cách chạy CLI memmy-memory như một lệnh shell, được hướng dẫn bởi một file chỉ dẫn mà memmy-memory init --agent ghi vào thư mục quy tắc của agent.

Việc chạy Memmy có gửi bộ nhớ của tôi lên dịch vụ đám mây không?

Quá trình quét và nạp dữ liệu diễn ra cục bộ, và các bộ nhớ được ghi vào ~/.memmy/memory-service/memory.sqlite trên ổ đĩa của bạn. MEMMY_CLOUD_SERVICE trỏ đến https://memmy-api.memtensor.cn cho chế độ tài khoản và các token dùng thử, và chương trình cải thiện bộ nhớ vẫn tắt cho đến khi bạn chủ động bật nó lên. Điểm cần lưu ý là nhà cung cấp embedding: một mô hình embedding được host sẽ nhận văn bản của mọi bộ nhớ mà nó chuyển đổi thành vector, vì vậy hãy sử dụng một endpoint do chính bạn vận hành nếu vấn đề này quan trọng.

#memmy#memory#ai-agents#mcp#self-hosted