AgentMemory: Lớp bộ nhớ dai dẳng cho AI coding agent - cài một lần, dùng với mọi agent

Tóm tắt nhanh

AgentMemory là một memory server mã nguồn mở chạy local, cung cấp persistent memory cho gần như mọi AI coding agent: Claude Code, Cursor, Codex CLI, Gemini CLI, OpenCode, Cline, Goose, Aider, Windsurf, Roo Code, OpenHuman, Hermes, OpenClaw, pi…

Cài đặt một dòng lệnh duy nhất (npm install -g @agentmemory/agentmemory hoặc npx), không cần Docker, không cần Postgres/Pinecone/Redis – mọi thứ chạy trên SQLite + embeddings local.

Hiệu năng đo trên benchmark LongMemEval-S (ICLR 2025): R@5 = 95.2%, R@10 = 98.6%, MRR = 88.2% – vượt xa BM25 fallback.

Tiết kiệm token cực mạnh: ước tính giảm từ ~650K token/năm (LLM-summarized) xuống còn ~170K token/năm, chi phí xuống còn khoảng 10 USD/năm (hoặc 0 USD nếu dùng local embeddings).

Hỗ trợ 53 MCP tools, 12 auto hooks với Claude Code, 22 hooks với OpenCode, và REST API cho các agent khác.

Một memory server duy nhất – memory được chia sẻ giữa tất cả các agent, không bị silo theo từng tool.

License MIT, dựa trên iii engine, mở rộng từ pattern LLM Wiki của Andrej Karpathy bằng confidence scoring, knowledge graph và hybrid search.

Vấn đề mà AgentMemory giải quyết

Bất kỳ ai làm việc dài hạn với Claude Code, Cursor hay Codex CLI đều đã từng trải qua tình huống quen thuộc: mỗi session mới, agent lại quên sạch những gì bạn đã giải thích ở session trước. Bạn lại phải copy cùng một sơ đồ kiến trúc, paste cùng một file middleware, nhắc lại cùng một quy ước đặt tên. Các giải pháp built-in như CLAUDE.md hay .cursorrules thì cap ở khoảng 200 dòng, nhanh chóng lỗi thời và phải sửa thủ công.

AgentMemory tiếp cận theo hướng khác hẳn: nó âm thầm bắt mọi thứ agent đang làm (file đã đọc, lệnh đã chạy, quyết định kiến trúc, lỗi đã sửa), nén thành memory có thể search được, và inject đúng context vào prompt khi session mới bắt đầu.

Kết quả là: Session 1 bạn dựng xong JWT auth. Session 2 bạn yêu cầu rate limiting. Agent đã biết bạn dùng jose middleware trong src/middleware/auth.ts, biết test coverage ở đâu, và biết tại sao bạn chọn jose thay vì jsonwebtoken (vì Edge compatibility). Không phải giải thích lại bất cứ điều gì.

Những điểm mạnh cốt lõi của AgentMemory

Một server, mọi agent đều dùng được

Đây là điểm khác biệt lớn nhất so với các giải pháp memory chuyên biệt (như memory của riêng Cursor hay riêng Claude). AgentMemory mở server trên cổng 3111 và cung cấp ba giao diện tiếp xúc: MCP (Model Context Protocol), hooks native cho các agent có hook system, và REST API cho phần còn lại.

Tài liệu chính thức liệt kê hỗ trợ cho Claude Code (native plugin + 12 hooks + MCP), Codex CLI (native plugin + 6 hooks + MCP), OpenCode (22 hooks + MCP + plugin), cùng MCP server cho Cursor, Gemini CLI, Cline, Goose, Kilo Code, Claude Desktop, Windsurf, Roo Code. Aider dùng qua REST API. Và OpenHuman dùng AgentMemory như native Memory trait backend.

Điều quan trọng: dù bạn switch giữa Claude Code và Cursor trong cùng một dự án, memory được chia sẻ chung. Không còn cảnh memory bị “fragmented” theo từng tool.

Không cần database ngoài

Hầu hết các solution memory khác đều yêu cầu bạn dựng Postgres + pgvector, hoặc Pinecone account, hoặc Redis + Qdrant. AgentMemory dùng SQLite kết hợp embedding model all-MiniLM-L6-v2 chạy local. Không API key, không billing, không infra cần maintain. Repo thậm chí tự hào in lên banner: 0 external DBs.

Hybrid search với benchmark có thể tái lập

Trên corpus nội bộ coding-agent-life-v1, AgentMemory đạt Top-5 hit rate 15/15 với p50 latency 14ms – so với baseline grep (cũng đạt top-5 hit rate đầy đủ nhưng precision chỉ bằng phân nửa). Trên benchmark học thuật LongMemEval-S (ICLR 2025) với 500 câu hỏi, hệ thống đạt R@5 = 95.2%, vượt xa BM25 fallback (86.2%). Toàn bộ script benchmark đều có trong repo, có thể chạy lại sandbox để kiểm tra.

Tiết kiệm token rõ rệt

Đối với một developer làm việc đều đặn, việc “paste full context” mỗi session có thể tiêu tốn hơn 19,5 triệu token mỗi năm – vốn vượt cả context window của hầu hết LLM. Cách tiếp cận summarize bằng LLM giảm xuống còn ~650K token/năm nhưng vẫn tốn ~500 USD chi phí API. AgentMemory đẩy con số này xuống còn ~170K token/năm, chi phí khoảng 10 USD, và 0 USD nếu dùng local embeddings.

Hướng dẫn cài đặt AgentMemory

Yêu cầu

Node.js (khuyến nghị bản LTS gần nhất).
npm hoặc dùng npx để không cần cài global.

Cài đặt qua npm (khuyến nghị)

npm install -g @agentmemory/agentmemory
agentmemory

Trên macOS/Linux nếu gặp lỗi EACCES, retry với sudo:

sudo npm install -g @agentmemory/agentmemory

Sau khi cài, server sẽ chạy trên port 3111. Bạn có thể seed dữ liệu demo và kiểm chứng recall ngay:

agentmemory demo

Cài qua npx (không cần install)

npx @agentmemory/agentmemory

Lưu ý: npx cache theo version. Nếu thấy bare npx @agentmemory/agentmemory lại serve bản cũ, force latest bằng:
npx -y @agentmemory/agentmemory@latest

Hoặc clear cache: rm -rf ~/.npm/_npx (macOS/Linux), trên Windows xóa %LOCALAPPDATA%\npm-cache\_npx. Từ v0.9.16+, lần đầu chạy npx sẽ prompt cài global inline để bare command agentmemory luôn dùng được.

Kết nối AgentMemory với agent của bạn

Sau khi server chạy, mỗi agent có một cách wire-up riêng nhưng đều cực ngắn gọn.

Claude Code

agentmemory connect claude-code

Lệnh trên tự động cài plugin native, đăng ký 12 auto hooks (PreCompact, SessionStart, UserPromptSubmit, PostToolUse…) và mount MCP server. Lần sau khi bạn khởi động Claude Code, memory được inject vào prompt tự động.

Codex CLI, Cursor, Gemini CLI

Cú pháp tương tự:

agentmemory connect codex
agentmemory connect cursor
agentmemory connect gemini-cli

Cursor và Gemini CLI dùng qua MCP – lệnh connect sẽ chỉnh sửa config file MCP của bạn để add server agentmemory với URL http://localhost:3111/mcp.

Các agent khác (Cline, Goose, Windsurf, Roo Code, Aider…)

Cách phổ thông nhất là thêm vào MCP config:

{
  "mcpServers": {
    "agentmemory": {
      "url": "http://localhost:3111/mcp"
    }
  }
}

Hoặc với Aider không hỗ trợ MCP, bạn dùng REST API: POST /memories/search với JSON body chứa query và top_k.

Sử dụng hằng ngày: Workflow điển hình

Bước 1: Khởi động server cùng OS

Trên macOS dùng launchd, trên Linux dùng systemd, trên Windows dùng Task Scheduler để auto-start agentmemory khi đăng nhập. Server cực nhẹ, không ảnh hưởng đáng kể tài nguyên.

Bước 2: Để agent làm việc bình thường

Bạn không cần thay đổi cách dùng Claude Code hay Cursor. Hooks và MCP đã wire sẵn – mỗi khi agent đọc file, chạy test, hay đưa ra quyết định, hệ thống tự động extract memory entry và lưu vào SQLite local.

Bước 3: Quan sát qua Real-time Viewer

AgentMemory ship kèm web viewer ngay tại http://localhost:3111. Bạn có thể xem các memory mới được ghi nhận, search trực quan, edit/delete entry, và inspect knowledge graph. Đây là cách nhanh nhất để hiểu agent đang “nhớ” gì.

Bước 4: Dùng iii Console cho tác vụ nâng cao

Vì AgentMemory được xây trên iii engine, bạn có quyền truy cập console iii để chạy query cấp thấp, debug retrieval pipeline, hay thay đổi confidence threshold. Phù hợp cho power user muốn tinh chỉnh.

Một số mẹo và lưu ý quan trọng

Đối với những ai làm việc trên codebase nhạy cảm (proprietary), việc AgentMemory chạy hoàn toàn local + embeddings không gọi cloud là một điểm cộng tuyệt đối về bảo mật. Tuy nhiên hãy kiểm tra xem agent của bạn (Claude Code, Cursor) có gửi context kèm theo prompt lên cloud LLM hay không – đó vẫn là một channel data leak khác.

Nếu bạn dùng nhiều project song song, hãy tận dụng namespace memory. AgentMemory hỗ trợ tagging theo session và project ID, giúp tránh tình trạng memory của project A “leak” sang project B.

Khi memory grow lớn (sau vài tháng dùng), thỉnh thoảng nên chạy lifecycle policy để decay các entry cũ ít được truy cập. Repo có sẵn audit policy codified – mỗi delete path đều được log.

Nếu bạn đang nghiêm túc về việc dùng AI coding agent lâu dài, AgentMemory gần như là infrastructure layer bắt buộc chứ không còn là tùy chọn. Việc cài đặt chỉ tốn một dòng lệnh, không cần Docker hay database ngoài, lại làm việc xuyên suốt mọi agent bạn đang dùng – đây là kiểu công cụ “set once, forget forever” hiếm gặp trong ecosystem AI hiện nay.

Duy Nghiện

Hãy làm khán giả, đừng làm nhân vật chính :)