TL;DR

Phần này hướng dẫn toàn bộ quá trình cài đặt Agentmemory - từ server, Claude Code, Codex CLI, đến Cursor và Cline. Sau đó là 3 action cơ bản (lưu, tìm, tự động compress) và 3 pattern workflow thực tế cho người dùng nhiều tool AI cùng lúc. Toàn bộ setup mất dưới 3 phút nếu Node.js đã có sẵn.

Trước khi bắt đầu

Yêu cầu duy nhất: Node.js >= 20. Agentmemory chạy được trên Mac, Linux, và Windows 10/11.

Một lưu ý quan trọng trước khi cài: Agentmemory phụ thuộc vào iii-engine v0.11.2 - một binary riêng biệt. Phiên bản này phải chính xác, không tương thích với v0.11.6 (chưa refactor xong). Cài sai version là lỗi phổ biến nhất khi setup.

Bước 1: Cài iii-engine (bắt buộc làm trước)

Cài iii-engine theo hệ điều hành:

# macOS arm64 (M1/M2/M3/M4)
mkdir -p ~/.local/bin
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz \
  | tar -xz -C ~/.local/bin
chmod +x ~/.local/bin/iii

# macOS x64 (Intel)
# Thay aarch64-apple-darwin bằng x86_64-apple-darwin

# Linux x64
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-x86_64-unknown-linux-gnu.tar.gz \
  | tar -xz -C ~/.local/bin

# Kiểm tra - phải ra v0.11.2
iii --version

Nếu ra bất kỳ version nào khác ngoài v0.11.2, hooks sẽ không hoạt động và bạn sẽ mất nhiều thời gian debug sau này. Làm bước này trước, làm đúng.

Bước 2: Khởi động Memory Server

# Khuyến nghị: cài global để dùng dễ hơn
npm install -g @agentmemory/agentmemory

# Hoặc dùng npx (lưu ý: npx cache theo version)
npx -y @agentmemory/agentmemory@latest

# Khởi động
agentmemory

Server chạy trên http://localhost:3111. Viewer trực quan chạy trên http://localhost:3113 - bạn có thể mở browser và xem memory build live.

Kiểm tra server đang chạy:

curl http://localhost:3111/agentmemory/health
# -> {"status":"ok","version":"0.9.24"}

Để xem demo ngay với dữ liệu mẫu (JWT auth, N+1 query fix, rate limiting):

agentmemory demo

Mở http://localhost:3113 - bạn sẽ thấy Agentmemory tìm "N+1 query fix" khi search "database performance optimization" mà không cần từ khóa giống hệt.

Bước 3: Tích hợp vào Claude Code

Đây là cách đơn giản nhất - dùng plugin marketplace của Claude Code:

# Trong Claude Code session
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

Hai lệnh này tự động đăng ký:

  • 12 hooks bao phủ toàn bộ lifecycle (SessionStart, PostToolUse, Stop, v.v.)
  • 4 skills: /recall, /remember, /session-history, /forget
  • 53 MCP tools (core 15 mặc định, bật all bằng AGENTMEMORY_TOOLS=all)

Lưu ý quan trọng: Phải dùng /plugin install, KHÔNG wire trực tiếp vào ~/.claude.json. Nếu dùng cách thủ công, hook paths sẽ embed version number cụ thể và tự động break sau mỗi lần upgrade.

Bước 4: Tích hợp vào Codex CLI

codex plugin marketplace add rohitg00/agentmemory
codex plugin install agentmemory

Codex sẽ tự set AGENTMEMORY_URL=http://localhost:3111. Một khác biệt cần lưu ý: Codex nghiêm khắc hơn Claude Code về MCP synchronicity - nếu server Agentmemory chưa chạy, Codex báo lỗi ngay. Luôn khởi động server trước khi mở Codex.

Vấn đề với Codex Desktop: Hiện tại (bug openai/codex#16430), Codex Desktop builds không dispatch plugin-local hooks. MCP tools vẫn hoạt động nhưng hooks lifecycle không ghi observations. Workaround: mirror hook commands vào global ~/.codex/hooks.json thủ công bằng lệnh agentmemory connect codex --global.

Bước 5: Cursor, Cline, và các tool khác

Cursor và các editor hỗ trợ MCP dùng cách configure qua file JSON:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": { "AGENTMEMORY_URL": "http://localhost:3111" }
    }
  }
}

Cline, Hermes, và bất kỳ MCP client nào dùng pattern tương tự - chỉ khác đường dẫn config file.

Một cách tự động cho Cursor:

agentmemory connect cursor

Lệnh này merge config vào ~/.cursor/mcp.json mà không ghi đè các server khác đang có.

Bước 6: Health check sau setup

3 kiểm tra bắt buộc sau khi setup xong:

# 1. Server đang chạy
curl http://localhost:3111/agentmemory/health

# 2. iii-engine đúng version
iii --version  # phải ra v0.11.2

# 3. Viewer có observations
open http://localhost:3113

Nếu viewer ở bước 3 hiển thị "no observations" sau khi đã chạy Claude Code một lúc - đó là dấu hiệu hooks không hoạt động. Kiểm tra lại bước 1 (iii-engine version) trước tiên.

3 action cơ bản: lưu, tìm, tự động compress

Action 1: Lưu (tự động là chủ yếu)

Khác với Mem0 hay Letta cần gọi memory_add() thủ công, Agentmemory capture mọi thứ qua hooks. Mỗi tool call, mỗi file edit, mỗi error đều được ghi lại tự động.

Bạn vẫn có thể lưu thủ công khi muốn đánh dấu "cái này quan trọng":

# Trong Claude Code
/remember "Quyết định dùng jose thay jsonwebtoken vì Edge compatibility"

# Hoặc qua REST API
curl -X POST http://localhost:3111/agentmemory/remember \
  -H "Content-Type: application/json" \
  -d '{"content": "Auth dùng jose middleware trong src/middleware/auth.ts"}'

Action 2: Tìm kiếm (hybrid search)

Tìm kiếm có thể dùng slash command hoặc REST API:

# Slash command
/recall "supabase auth fix"

# REST API
curl -X POST http://localhost:3111/agentmemory/search \
  -H "Content-Type: application/json" \
  -d '{"query": "supabase auth fix", "limit": 5}'

Hệ thống trả về kết quả từ BM25, vector, và graph được hợp nhất qua RRF. P50 latency: 14ms. Kết quả được session-diversified - không bị dominated bởi một session duy nhất.

Các MCP tools tìm kiếm khác:

  • memory_smart_search - full hybrid search
  • memory_timeline - xem theo chronological order
  • memory_file_history - lịch sử của một file cụ thể
  • memory_relations - graph traversal theo entities

Action 3: Tự động compress (4-tier consolidation)

Mỗi khi session kết thúc (Stop hook), pipeline compress chạy theo 3 bước:

  1. Working → Episodic: raw tool logs → session summary
  2. Episodic → Semantic: nhiều session summaries → extracted knowledge/patterns
  3. Semantic → Procedural: repeated patterns → automated workflows

Bộ nhớ hay được truy cập thì được củng cố. Bộ nhớ không dùng thì decay và tự xóa. Không cần bạn "dọn dẹp" CLAUDE.md thủ công định kỳ nữa.

Workflow thực tế - 3 pattern

Pattern 1: Cá nhân - quy trình 1 ngày

Để server Agentmemory chạy nền cùng với máy. Khi mở Claude Code buổi sáng, SessionStart hook tự load Episodic memory từ hôm qua. Bạn không cần gõ "tiếp tục từ hôm qua" nữa - agent đã biết bạn đang debug cái gì, đã quyết định gì.

Trong ngày: PostToolUse hooks ghi mọi thứ vào SQLite. Tối đóng session: Stop hook compress Working → Episodic. Sáng hôm sau: cycle lại.

Pattern 2: Nhiều project song song

Agentmemory tách bộ nhớ theo 3 scope:

  • user: global, áp dụng cho tất cả projects (coding style, preferences)
  • project: per-project, SQLite file riêng biệt
  • local: chỉ trên máy này, không sync ra ngoài

Chuyển project bằng cách set environment variable:

export AGENTMEMORY_PROJECT=foo-app
# Agentmemory tự dùng SQLite file của foo-app, không bị lẫn với project khác

Với CLAUDE.md, quyết định thiết kế của project A hay lẫn vào discussion của project B. Với Agentmemory, hai project được physical isolation hoàn toàn.

Pattern 3: Team - shared memory server

Một use case ít được nhắc đến: nhiều developer dùng chung một Agentmemory server qua VPN nội bộ.

# Khởi động server ở chế độ collaborative
AGENTMEMORY_COLLAB=true agentmemory --bind 0.0.0.0

Với AGENTMEMORY_AGENT_SCOPE=shared, architect có thể thấy những gì developer ghi chú (với audit trail rõ ai ghi cái gì). Với AGENTMEMORY_AGENT_SCOPE=isolated, mỗi role có memory riêng biệt hoàn toàn.

Lưu ý quan trọng khi dùng team mode: cài .agentmemoryignore để tránh API keys hay credentials của member A bị sync sang toàn bộ team:

echo ".env" >> .agentmemoryignore
echo ".env.local" >> .agentmemoryignore
echo "**/*.key" >> .agentmemoryignore

Kết - Phần 2

Setup xong, bạn đã có persistent memory chạy cross-agent: Claude Code, Codex, Cursor dùng chung một "bộ não". Mỗi quyết định thiết kế, mỗi bug fix, mỗi pattern được compile dần theo thời gian.

Phần 3: So sánh chi tiết với Mem0 và Letta, cách đọc benchmark không bị mislead, và 5 bẫy thường gặp với fix cụ thể.