agentmemory: bộ nhớ bền vững cho các coding agent AI

Bộ nhớ bền vững xuyên suốt các phiên lập trình và agent.
Bộ nhớ bền vững cho Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode và bất kỳ MCP client nào.

🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog

rohitg00/agentmemory | Trendshift

Tài liệu thiết kế: 1.7k stars / 240 forks trên gist

Gist này mở rộng mẫu LLM Wiki của Karpathy với confidence scoring, lifecycle, knowledge graph và tìm kiếm hybrid: agentmemory chính là phần triển khai đó.

npm version CI License Stars skills.sh installs

54 MCP tools 12 auto hooks 0 external DBs 5,000+ tests passing

Demo agentmemory

Cài đặt • Bắt đầu nhanh • Benchmark • So sánh đối thủ • Agent • Cách hoạt động • MCP • Viewer • Cấu hình • API

--- AgentMemory ghi lại phiên lập trình để bạn tìm lại các quyết định và cách sửa lỗi. Dùng chung một kho bộ nhớ giữa các công cụ, kiểm tra nội dung đã lưu và chọn lượng ngữ cảnh đưa vào mô hình. ## Cài đặt Yêu cầu: - Node.js 20 hoặc mới hơn kèm npm và npx (`node -v`, `npm -v`, và `npx -v`). - Thiết lập tự động trên macOS/Linux cần `curl`, POSIX `sh` và `tar`. Windows native cần cài thủ công `iii.exe` của iii v0.25.1 đã pin; WSL2 dùng trình cài tự động cho macOS/Linux Lệnh cài mới chuẩn (canonical): ```bash npx -y @agentmemory/agentmemory@latest ``` Chọn agent và nhà cung cấp hoặc chế độ không cần khóa. Thiết lập lưu cấu hình, khởi động máy chủ bộ nhớ và đề nghị cài đặt toàn cục. `-y` chấp nhận xác nhận npm; `@latest` chọn bản mới nhất. Nén bằng LLM cần cả nhà cung cấp và `AGENTMEMORY_AUTO_COMPRESS=true`. Chế độ keyless tắt vector embedding. `memory_recall` (đường dẫn `mem::search`) dùng BM25, trong khi `memory_smart_search` cũng có thể kết hợp (fuse) các kết quả khớp từ graph cấu trúc khi dữ liệu graph đã tồn tại. Để có recall ngữ nghĩa (semantic) miễn phí ngay trên máy (on-device), đặt `EMBEDDING_PROVIDER=local` trong `~/.agentmemory/.env` và khởi động lại. Request embedding đầu tiên sẽ tải `Xenova/all-MiniLM-L6-v2`; sau lần tải model đầu tiên đó, việc suy luận chạy hoàn toàn cục bộ. API ở `http://localhost:3111`, trình xem trực tiếp ở `http://localhost:3113`. Cả hai mặc định chỉ lắng nghe trên loopback. Cấu hình nằm trong `~/.agentmemory/.env`. [Lưu trữ dữ liệu](#data-storage). Sau đó hãy xác nhận recall hoạt động và trang bị skill cho agent của bạn: ```bash npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory ``` Các truy vấn theo từ khóa sẽ cho kết quả đúng ở chế độ keyless mặc định thông qua BM25. Câu truy vấn `database performance optimization` trong demo mang tính ngữ nghĩa (semantic) có chủ đích và có thể trả về rỗng cho tới khi một embedding provider được cấu hình. Muốn để một coding agent tự làm hết mọi việc? Hãy đưa cho nó một chỉ dẫn duy nhất: > Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md Thêm agent bằng `agentmemory connect `. Xem [các tích hợp](#works-with-every-agent) và [lệnh thường dùng](#everyday-commands).
Cài đặt toàn cục / EACCES ```bash npm install -g @agentmemory/agentmemory@latest ``` Lệnh npx ở trên vẫn là cách cài mới chuẩn và tránh được các vấn đề về quyền global-prefix.
npx trả về phiên bản cũ npx cache theo từng phiên bản. Buộc dùng bản mới nhất với `npx -y @agentmemory/agentmemory@latest`, hoặc xóa cache một lần với `rm -rf ~/.npm/_npx` (macOS/Linux; trên Windows, xóa `%LOCALAPPDATA%\npm-cache\_npx`).
---

Hoạt động với mọi agent

agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, hoặc REST API. Tất cả agent đều dùng chung một memory server.
Claude Code
Claude Code
native plugin + 12 hooks + MCP
Codex CLI
Codex CLI
native plugin + 6 hooks + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + plugin hooks/skills
Cursor
Cursor
plugin native + hook vòng đời + MCP
OpenCode
OpenCode
capture plugin + MCP
Devin
Devin
6 hooks + skills + MCP
OpenClaw
OpenClaw
native plugin + MCP
Hermes
Hermes
native plugin + MCP
pi
pi
recall native + capture + skill
OpenHuman
OpenHuman
native Memory trait backend
Gemini CLI
Gemini CLI
MCP server
Antigravity
Antigravity
MCP + hooks
Claude Desktop
Claude Desktop
MCP server
Warp
Warp
connect + MCP + skills
Zed
Zed
MCP server
Cline
Cline
MCP server
Continue
Continue
MCP server
Droid
Droid
MCP server
Kiro
Kiro
MCP server
Qwen Code
Qwen Code
MCP server
DeepSeek Harness
DeepSeek Harness
capture native + MCP
Roo Code
Roo Code
MCP server
Kilo Code
Kilo Code
MCP server
Goose
Goose
MCP server
Aider
Aider
REST API
Oh My Pi
recall native + capture + skill + MCP tùy chọn

Hoạt động với bất kỳ agent nào nói MCP hoặc HTTP. Một server duy nhất, bộ nhớ được chia sẻ cho tất cả.

--- ### Lưu trữ dữ liệu Bộ nhớ mặc định nằm ngoài kho mã. Instance 0 dùng lại `./data/state_store.db` có sẵn. Chọn thư mục bằng `--data-dir ` hoặc `AGENTMEMORY_DATA_DIR` và giữ nguyên khi khởi động lại hay nâng cấp. | Nền tảng | Thư mục dữ liệu | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` `--instance 1` dùng thư mục con `instance-1`, cổng API `3211` và trình xem `3213`. Xem [lưu trữ và sao lưu](../docs/reliability/state-storage.md) để dùng Redis hoặc chuyển backend. Ghi chú phát hành mới nhất: [CHANGELOG.md](../CHANGELOG.md). ---

Benchmark

Kết quả truy xuất hiện tại, định nghĩa chỉ số và các bước tái lập: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

So sánh đối thủ

So sánh cập nhật về sản phẩm và phương án triển khai, kèm nguồn: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

Bắt đầu nhanh

### Thử trong 30 giây ```bash # Terminal 1: start the server npx -y @agentmemory/agentmemory@latest # Terminal 2: seed sample data and see recall in action npx -y @agentmemory/agentmemory@latest demo ``` `demo` khởi tạo 3 session thực tế (JWT auth, sửa lỗi N+1 query, rate limiting) và chạy các tìm kiếm trên đó. Bản cài keyless tắt vector, nên các truy vấn từ khóa `mem::search` sẽ cho kết quả đúng qua BM25 trong khi `database performance optimization` có thể trả về rỗng. `smart-search` có thể trả thêm các kết quả khớp từ graph cấu trúc khi dữ liệu graph tồn tại. Để truy vấn ngữ nghĩa tìm được bản sửa N+1 qua vector, hãy đặt `EMBEDDING_PROVIDER=local`, khởi động lại, và chờ lần tải model đầu tiên hoàn tất. Mở `http://localhost:3113` để xem bộ nhớ được xây dựng theo thời gian thực. ### Kiểm tra một bản cài mới và độ bền sau khi khởi động lại Khi máy chủ đang chạy, kiểm tra sức khỏe, trình xem và trạng thái. ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` `status` hiển thị sức khỏe máy chủ, nhà cung cấp, chế độ embedding, chuyển giao capture và phục hồi. REST được bảo vệ cần bí mật của máy chủ. Dùng `AGENTMEMORY_SECRET` đã cấu hình hoặc đọc bí mật cục bộ được tạo nếu chưa đặt. ```bash # Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead. read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret" curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}' curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"query":"restart persistence probe","limit":5}' ``` Sau đó chạy `npx -y @agentmemory/agentmemory@latest stop`, khởi động lại lệnh canonical ở Terminal 1, chờ `/agentmemory/livez`, và lặp lại tìm kiếm. Probe đó vẫn phải được trả về. Nếu bạn đã chọn một `--data-dir` tùy chỉnh, hãy truyền cùng thư mục đó khi khởi động lại. ### Các lệnh dùng hàng ngày Cài đặt và thiết lập nằm ở phần [Cài đặt](#install) ở trên (lần chạy đầu tiên sẽ dẫn bạn qua từng bước). Hàng ngày: ```bash agentmemory # start the server agentmemory stop # stop it cleanly agentmemory status # health, providers and recovery state agentmemory capture # inspect capture inbox and offline spool agentmemory capture --drain # replay queued observations agentmemory connect # connect another agent agentmemory doctor # interactive diagnostics + fix prompts agentmemory remove # uninstall everything we created ``` ### Phát lại Session Mọi session mà agentmemory ghi lại đều có thể phát lại (replay). Mở viewer, chọn tab **Replay**, và kéo qua timeline: prompt, tool call, kết quả tool, và response được hiển thị như các event rời rạc với play/pause, điều khiển tốc độ (0.5x đến 4x), và phím tắt bàn phím (space để toggle, mũi tên để bước qua từng event). Để đưa vào các transcript JSONL cũ của Claude Code: ```bash # Import everything under the default ~/.claude/projects npx -y @agentmemory/agentmemory@latest import-jsonl # Or import a single file npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl ``` Phiên nhập hiện cùng phiên native trong Replay, được lập chỉ mục tìm kiếm và đánh dấu kênh nguồn `import`. Xử lý phiên cũng có thể tạo crystal và bài học. > **Lưu ý nếu bạn dựa vào `import-jsonl` như đường capture chính:** `cleanupPeriodDays` của Claude Code (trong `~/.claude/settings.json`, mặc định **30**) tự động xóa các transcript JSONL cũ hơn khoảng thời gian đó khỏi `~/.claude/projects/`. Nếu bạn cài agentmemory mới trên một lịch sử Claude Code đã vài tháng tuổi, bất cứ thứ gì cũ hơn 30 ngày đã mất trước lần import đầu tiên. Hãy chạy `import-jsonl` theo cron, tăng `cleanupPeriodDays` lên một giá trị cao hơn, hoặc kết nối các hook auto-capture (đường cài plugin mặc định) để mỗi turn đi vào agentmemory ngay khi session còn sống, và việc dọn JSONL không còn quan trọng nữa. ### Nâng cấp / Bảo trì Dùng lệnh bảo trì khi bạn chủ động muốn cập nhật runtime cục bộ của mình: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` Lệnh cập nhật runtime cục bộ và có thể cập nhật phụ thuộc JavaScript trong thư mục làm việc. Sao lưu dữ liệu và đọc [hướng dẫn nâng cấp](../docs/upgrades/iii-0.25.md) trước khi cập nhật bản cài hiện có. ### Claude Code (một block, dán vào) ```text Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall. ``` #### Claude Code không cài plugin (đường MCP độc lập) Nếu bạn kết nối MCP server của agentmemory qua `~/.claude.json` (đường dẫn mặc định) trực tiếp thay vì dùng `/plugin install`, Claude Code sẽ không bao giờ resolve `${CLAUDE_PLUGIN_ROOT}` và bạn phải chỉ các hook script tới đường dẫn tuyệt đối trong `~/.claude/settings.json` (đường dẫn mặc định). Các đường dẫn đó thường nhúng cả phiên bản agentmemory (ví dụ `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), nên lần nâng cấp kế tiếp sẽ lặng lẽ làm hỏng mọi hook. Cách khắc phục tạm: ```bash agentmemory connect claude-code --with-hooks ``` Lệnh này cấu hình máy chủ MCP và gộp các hook đi kèm vào cấu hình người dùng của Claude Code. Nếu `CLAUDE_CONFIG_DIR` chưa được đặt, rỗng hoặc chỉ chứa khoảng trắng, lệnh dùng `~/.claude.json` cho MCP và `~/.claude/settings.json` cho các hook. Các giá trị thư mục khác được dùng đúng như đã cung cấp, kể cả khoảng trắng ở đầu và cuối. Để dùng thư mục tùy chỉnh, hãy đặt `CLAUDE_CONFIG_DIR` thành cùng một giá trị không rỗng cho cả lệnh này và Claude Code; khi đó, các tệp lần lượt là `$CLAUDE_CONFIG_DIR/.claude.json` và `$CLAUDE_CONFIG_DIR/settings.json`. Claude Code phải nhận giá trị này trong môi trường khởi chạy của chính nó, ngay cả khi trình kết nối đọc giá trị từ tệp `.env` của AgentMemory. Tạo thư mục tùy chỉnh trước khi chạy lệnh này; nếu thư mục chưa tồn tại, trình kết nối sẽ bỏ qua Claude Code vì không phát hiện được. Nếu giá trị trong shell chỉ chứa khoảng trắng, hãy xóa `CLAUDE_CONFIG_DIR` khỏi môi trường trước khi khởi chạy Claude Code để nó cũng dùng cấu hình mặc định. Hãy dùng đường dẫn tuyệt đối. Đường dẫn tương đối được xác định theo thư mục làm việc, nên cả hai lệnh phải được chạy từ cùng một thư mục. Các lệnh hook dùng đường dẫn tuyệt đối đến thư mục `plugin/` đi kèm trong gói đã cài đặt. Chạy lại lệnh sau khi nâng cấp agentmemory để cập nhật các đường dẫn này. Các mục của người dùng trong tệp cấu hình được giữ nguyên; chỉ các mục agentmemory trước đó bị thay thế. Dùng `/plugin install` vẫn là cách được khuyến nghị. Với các deployment từ xa hoặc được bảo vệ, hãy khởi chạy Claude Code với `AGENTMEMORY_URL` và `AGENTMEMORY_SECRET` đã được đặt. Plugin sẽ truyền cả hai giá trị này xuống MCP server đi kèm của nó; khi `AGENTMEMORY_URL` để trống, MCP shim dùng `http://localhost:3111`. ### Codex CLI (nền tảng plugin của Codex) ```bash # 1. start the memory server in a separate terminal npx -y @agentmemory/agentmemory@latest # 2. register the agentmemory marketplace and install the plugin codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` Plugin Codex được phát hành từ cùng thư mục `plugin/` như plugin Claude Code. Nó đăng ký: - Một cầu nối MCP qua stdio được đóng gói sẵn tới daemon đang chạy, không cần tải npm hay fallback store. Xem [hướng dẫn Codex local](../docs/plugins/codex-local.md) để test một build chưa được release. - 6 hook lifecycle: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 9 skill có thể gọi (invocable): `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, cùng 8 skill tham chiếu mà agent nạp theo nhu cầu (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, và hướng dẫn viết skill) Hook engine của Codex tiêm `CLAUDE_PLUGIN_ROOT` vào các subprocess hook (theo [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), nên cùng các hook script này hoạt động trên cả hai host mà không cần trùng lặp. Các event Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure chỉ dành riêng cho Claude Code và không được đăng ký cho Codex. #### Trust và tính tương thích của hook Codex Dispatch hook plugin gốc đã được verify với Codex CLI 0.150.1. Hãy trust các hook plugin trước khi kỳ vọng capture. Hành vi của Desktop phụ thuộc vào runtime đi kèm của nó; kiểm tra `/hooks` và xác nhận có một event được capture trước khi bật một cách khắc phục tạm. Nếu host của bạn cần global hook, hãy sao chép các command vào `~/.codex/hooks.json`. Khi MCP đã được kết nối sẵn, connector hiện tại cần `--force` để tiến tới bước cài hook: ```bash agentmemory connect codex --with-hooks --force ``` Lệnh này gộp các global hook và viết lại entry MCP của agentmemory, trong khi vẫn giữ nguyên các entry không liên quan. Hãy xem lại mọi cấu hình endpoint agentmemory tùy chỉnh trước khi dùng `--force`. Chạy lại sau khi nâng cấp để làm mới các đường dẫn script. Chỉ nên bật một trong hai: hook plugin gốc hoặc các bản sao global, để tránh capture trùng lặp. ### GitHub Copilot CLI Đối với VS Code agent mode, hãy dùng [hướng dẫn MCP và automatic-capture của Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Connector CLI này không cấu hình VS Code. ```bash # MCP-only wiring agentmemory connect copilot-cli # Alternatively, full hooks/skills plugin from the GitHub subdir copilot plugin install rohitg00/agentmemory:plugin ``` `agentmemory connect copilot-cli` gộp `mcpServers.agentmemory` vào `~/.copilot/mcp-config.json` (hoặc `$COPILOT_HOME/mcp-config.json` khi `COPILOT_HOME` được đặt) và giữ lại các server đã có. Trên Windows gốc, đây là adapter `connect` tự động duy nhất; mọi agent Windows gốc khác phải cấu hình thủ công. `connect` trong WSL chỉ được hỗ trợ khi agent đích cũng được cài trong cùng môi trường WSL đó. Copilot sẽ nhận MCP server ở lần khởi chạy kế tiếp hoặc sau `/mcp`. Cài thêm plugin nếu bạn muốn có đầy đủ trải nghiệm hook/skill. ### Cursor Cấu hình MCP bằng `agentmemory connect cursor`. Trong **Settings → Plugins → Add marketplace**, chọn checkout chứa `.cursor-plugin/plugin.json`, bật agentmemory và tải lại. Plugin cung cấp capture vòng đời, xác định workspace, skill và MCP. Chỉ bật hook của plugin hoặc hook thủ công trong `~/.cursor/hooks.json` để tránh ghi nhận trùng. [Cursor](../integrations/cursor/) ### Pi / Oh My Pi / DeepSeek Harness ```bash agentmemory connect pi --with-mcp agentmemory connect omp --with-mcp agentmemory connect dsh --with-hooks ``` Chọn lệnh cho host của bạn. Pi và OMP cài recall/capture native, phát lại ngoại tuyến và 17 skill; `--with-mcp` thêm toàn bộ công cụ. Chạy `/reload` trong Pi hoặc khởi động lại OMP, rồi kiểm tra `/agentmemory-status`. DSH cài MCP và plugin capture đi kèm; hãy khởi động lại sau khi kết nối. Pi cũng hỗ trợ gói `@agentmemory/pi`. Xem [hướng dẫn Pi](../integrations/pi/) về cài đặt cục bộ và tình trạng phát hành npm. Mỗi host chỉ dùng một cách cài đặt. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (dán prompt này) ```text Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`. ``` Hướng dẫn đầy đủ: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (dán prompt này) ```text Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: command: npx args: ["-y", "@agentmemory/mcp"] memory: provider: agentmemory Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from https://github.com/rohitg00/agentmemory to ~/.hermes/plugins/agentmemory. ``` Hướng dẫn đầy đủ: [`integrations/hermes/`](../integrations/hermes/)
### Các agent khác Khởi động memory server: `npx -y @agentmemory/agentmemory@latest` #### Skill gốc qua `npx skills add` agentmemory đi kèm 17 skill theo định dạng `/SKILL.md` kiểu Claude Code: 9 skill hành động có thể gọi (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) và 8 skill tham chiếu mà agent nạp theo nhu cầu (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Các skill tham chiếu mang theo bảng dữ liệu được sinh ra từ source, nên chúng không bao giờ lệch (drift). CLI [`skills`](https://npmjs.com/package/skills) của vercel-labs tự cài chúng vào thư mục skill gốc của agent gọi nó, trên hơn 50 agent (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, và nhiều hơn nữa): ```bash npx skills add rohitg00/agentmemory -y # auto-detects the calling agent npx skills add rohitg00/agentmemory -y -a warp # explicit agent npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent ``` Điều này **bổ sung** cho `agentmemory connect `: Connector Hermes, OpenClaw, Pi và Oh My Pi mặc định cài tích hợp native cùng skill; MCP là tùy chọn qua `--with-mcp`. Với host khác, cài skill bằng `npx skills add rohitg00/agentmemory`. Với một số ít agent mà CLI skills chưa hỗ trợ (Zed v1.3.x và thấp hơn), hãy tự đặt 17 file SKILL.md vào thư mục skill gốc của agent đó; cùng một định dạng hoạt động ở mọi nơi. #### Block MCP chuẩn Entry của agentmemory là **cùng một block MCP server** trên mọi host dùng hình thái `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw): ```json "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}" } } ``` **Gộp entry này vào object `mcpServers` đã có** trong file config của host; không thay thế toàn bộ file. Nếu file đã có server khác, hãy thêm `agentmemory` cạnh chúng như một key khác trong `mcpServers`. Nếu `mcpServers` hoàn toàn chưa có, dán block này vào trong `{ "mcpServers": { ... } }`. Các placeholder `${VAR}` kế thừa `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` từ shell tại thời điểm khởi chạy MCP server; biến chưa đặt sẽ truyền chuỗi rỗng và shim sẽ fallback về `http://localhost:3111`. Một entry đã kết nối có thể dùng cho cả deployment local và remote (k8s / sau reverse-proxy). | Agent | File config | Ghi chú | |---|---|---| | **Cursor (chỉ MCP)** | `~/.cursor/mcp.json` | Gộp vào `mcpServers`, hoặc dùng `agentmemory connect cursor`. Cũng có deeplink one-click trên website. | | **Cursor (plugin đầy đủ)** | `.cursor-plugin/` | Cài qua Cursor Marketplace hoặc Settings → Plugins → checkout cục bộ. Adapter mỏng gọi các script chung `plugin/scripts/*.mjs` để đăng ký hook vòng đời, cùng skill và MCP. Adapter xác định workspace mà Cursor không luôn báo chính xác. Xem [Cursor](#cursor). Hoạt động trong Cursor IDE và CLI `cursor-agent`. | | **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Gộp vào `mcpServers`. Khởi động lại Claude Desktop sau khi sửa. | | **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Cùng block `mcpServers`. | | **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` gộp entry MCP; `--with-hooks` thêm sáu hook auto-capture gốc (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) với các tool matcher chữ thường của Devin. Kiểm tra bằng `devin mcp list` và `/hooks` trong devin. | | **Devin CLI (plugin đầy đủ)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` từ một checkout đăng ký toàn bộ 17 skill dưới dạng slash command `/agentmemory:` cùng với MCP server. Hook plugin của Devin không thể bắn `SessionStart`/`SessionEnd`, nên hãy kết hợp với `connect devin --with-hooks` để capture session đầy đủ. | | **Devin (cloud)** | Settings → Connections → MCP servers | Thêm một MCP tùy chỉnh (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` chỉ tới một deployment agentmemory có thể truy cập qua network cùng `AGENTMEMORY_SECRET` (các session cloud không thể chạm tới localhost — xem [`../deploy/`](../deploy/)). Lưu secret trong Devin Secrets, sau đó dùng "Test listing tools" để xác nhận cả 54 tool đều xuất hiện. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (tự gộp). | | **GitHub Copilot CLI (chỉ MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` gộp `mcpServers.agentmemory`; Copilot sẽ nhận ở lần khởi chạy kế tiếp hoặc `/mcp`. | | **GitHub Copilot CLI (plugin đầy đủ)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` để lấy plugin từ subdir GitHub. | | **OpenClaw** | OpenClaw MCP config | Cùng block `mcpServers`. Sâu hơn: `openclaw plugins install ./integrations/openclaw` chiếm memory slot của OpenClaw (tự chuyển từ `memory-core`); đặt `plugins.entries.agentmemory.hooks.allowConversationAccess=true` nếu không turn capture sẽ bị chặn một cách im lặng. Xem [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (chỉ MCP)** | `.codex/config.toml` | Hình thái TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, hoặc thêm `[mcp_servers.agentmemory]` thủ công. | | **Codex CLI (plugin đầy đủ)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` sau đó `codex plugin add agentmemory@agentmemory`. Đăng ký MCP + 6 hook lifecycle + 17 skill. Hãy trust các hook và verify việc capture trên host của bạn; xem [hướng dẫn setup và validation Codex](../docs/plugins/codex-local.md). | | **OpenCode (chỉ MCP)** | `opencode.json` | Hình thái khác: key `mcp` ở cấp cao nhất, command là một array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (plugin đầy đủ)** | `plugin/opencode/` | 22 hook auto-capture bao phủ lifecycle session, message, tool, lỗi. Attribution project theo từng session, nên một process OpenCode trải trên nhiều repository sẽ ghi mỗi session dưới đúng project của nó. Hai slash command (`/recall`, `/remember`). Copy `plugin/opencode/` vào workspace OpenCode của bạn và thêm entry plugin vào `opencode.json`. Xem [`plugin/opencode/README.md`](../plugin/opencode/README.md) để biết bảng hook đầy đủ + phân tích phần còn thiếu. | | **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · recall native + capture + skill. [Pi](../integrations/pi/) | | **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · recall native + capture + skill. [Oh My Pi](../integrations/omp/) | | **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` cho bạn memory provider 6-hook (prefetch, turn capture, session end, pre-compress, mirror MEMORY.md, system prompt block). Kiểm tra bằng `hermes plugins doctor` và `hermes memory status`. Xem [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` viết block `mcpServers` chuẩn. Payload hook tương thích field với Claude Code, nên các script 12-hook hiện có hoạt động không cần sửa đổi; kết nối chúng qua phần `hooks` trong cùng `settings.json`. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` cài MCP và capture hook vào thư mục customization chung. Xem [thiết lập và giới hạn của Antigravity](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` dùng cùng cấu hình MCP và hook như các phiên bản IDE hiện tại. Các bản cài đặt sẵn có nên refresh bằng `--force`; xem [ghi chú upgrade](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` viết config ở cấp user. Các override ở cấp workspace nằm trong `.kiro/settings/mcp.json` cạnh code của bạn. | | **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` viết block `mcpServers` chuẩn. Warp cũng tự phát hiện skill từ `.claude/skills/`; khi plugin Claude Code được cài, 9 skill agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) sẽ xuất hiện một cách tự nhiên trong bảng slash-command của Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` viết block `mcpServers` chuẩn. Người dùng extension VS Code: dán cùng block này qua Cline Settings → MCP Servers → Edit JSON. | | **Continue.dev** | `~/.continue/config.yaml` (ưu tiên) hoặc `config.json` (legacy) | `agentmemory connect continue` tạo `config.yaml` nếu chưa có cấu hình hoặc cập nhật `config.json` hiện có. YAML có sẵn được giữ nguyên để bảo toàn chú thích và anchor; lệnh in khối để dán dưới `mcpServers:`. Continue dùng dạng mảng cho `mcpServers`. | | **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` viết dưới `context_servers` (key riêng của Zed, KHÔNG phải `mcpServers`). Các MCP server remote có thể được kết nối qua `{"url": "..."}` thay thế. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` viết block `mcpServers` chuẩn. Các override theo project nằm trong `/.factory/mcp.json`. Truyền `--with-hooks` để có auto-capture gốc. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` bật các công cụ MCP. Thêm `--with-hooks` để tải plugin ghi nhận sự kiện gốc đi kèm AgentMemory. Không cần gói plugin riêng. [DSH](../docs/dsh.md). | | **Goose** | Goose MCP settings UI | Cùng block `mcpServers`; dùng `goose configure` → Add Extension → MCP. Sửa YAML trực tiếp tại `~/.config/goose/config.yaml` cũng được hỗ trợ nhưng schema dùng `extensions:` + `cmd` (không phải `mcpServers:` + `command`). | | **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) | | **Các agent được hỗ trợ** | Chỉ cài skills | `npx skills add rohitg00/agentmemory`; chọn skills cần cài và các agent đích. | **Các MCP client chạy trong sandbox** (Flatpak / Snap / container hạn chế) không thể chạm tới `localhost` của host: hãy đặt thêm `"AGENTMEMORY_FORCE_PROXY": "1"` trong block `env`, và chỉ `AGENTMEMORY_URL` tới một route mà sandbox thực sự chạm tới được (ví dụ IP LAN của bạn). ### Truy cập theo chương trình Dùng [REST API](#api) từ bất kỳ ngôn ngữ nào hoặc [công cụ MCP](#mcp-server) từ agent. REST dùng JSON và xác thực Bearer; xem [ví dụ lưu và tìm kiếm](#validate-a-fresh-install-and-restart-persistence). Tích hợp trực tiếp với runtime có trong [ví dụ Python](../examples/python/). ### Từ source ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` `npm start` chạy cùng máy chủ cục bộ như CLI đã cài. Yêu cầu nằm ở [Cài đặt](#install); API và trình xem lắng nghe trên `127.0.0.1`. ### Windows agentmemory chạy trên Windows 10/11; WSL2 có thể tự cài engine theo quy trình Linux. Windows native cần cài thủ công iii-engine v0.25.1: tải archive từ [trang phát hành iii v0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), xác minh checksum và đặt `iii.exe` trong `PATH`. CLI không tự giải nén ZIP Windows Cấu hình MCP tự động trên Windows native chỉ hỗ trợ `agentmemory connect copilot-cli`; agent khác dùng khối MCP thủ công trong [Other agents](#other-agents). Chỉ chạy `connect` trong WSL nếu agent đích cũng cài trong cùng môi trường WSL **Chỉ dùng MCP độc lập, không có engine.** Nếu không cần REST API, viewer hoặc dịch vụ runtime: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` Chạy `agentmemory doctor` hoặc khởi động lại với `--verbose`. Nếu cổng mặc định đang được dùng, chọn `--port ` hoặc `--instance `. Xem [hướng dẫn nâng cấp](../docs/upgrades/iii-0.25.md) về tương thích và phục hồi. ---

Triển khai

Tự triển khai bằng Docker Compose hoặc mẫu nền tảng bên dưới. Bộ nhớ và thông tin xác thực nằm trên volume `/data`. Sao lưu và dùng lại volume khi nâng cấp. Xem [hướng dẫn triển khai](../deploy/README.md) về xác thực, mạng và di chuyển dữ liệu.

Triển khai lên fly.io Triển khai lên Railway

Nút one-click deploy của Render yêu cầu `render.yaml` ở gốc repository, và chúng tôi chủ đích giữ nó sạch. Hãy dùng luồng Render Blueprint được ghi lại trong [`../deploy/render/`](.././deploy/render/README.md) để chỉ tới blueprint trong repo một cách thủ công. Chi tiết thiết lập đầy đủ (capture HMAC, SSH tunnel cho viewer, xoay, backup, mức chi phí sàn) nằm trong [`../deploy/`](.././deploy/README.md): - [`../deploy/fly`](.././deploy/fly/README.md): một máy đơn với `auto_stop_machines = "stop"`; rẻ nhất khi idle. - [`../deploy/railway`](.././deploy/railway/README.md): phí cố định của Hobby plan, volume trong dashboard. - [`../deploy/render`](.././deploy/render/README.md): luồng Blueprint, tự động snapshot disk trên các plan trả phí. - [`../deploy/coolify`](.././deploy/coolify/README.md): self-hosted trên VPS riêng của bạn qua [Coolify](https://coolify.io/self-hosted); cùng Docker Compose stack, bạn sở hữu cả host và dữ liệu. REST dùng cổng `3111`; trình xem dùng `3113`. Giữ truy cập riêng tư hoặc bảo vệ bằng xác thực và TLS. Xem cấu hình truy cập của từng nền tảng và [chuyển từ Docker cũ](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) trong hướng dẫn triển khai. ---

Tại sao chọn agentmemory

Kiến thức dự án thường nằm rải rác trong hội thoại và tệp chỉ dẫn. AgentMemory giúp agent bạn đang dùng tìm lại các quyết định, cách sửa lỗi và bài học trước đây. ```text Session 1: "Add auth to the API" Agent writes code, runs tests, fixes bugs Connected hooks capture supported tool events Observations become searchable project history Session 2: "Now add rate limiting" Agent recalls: - Auth uses JWT middleware in src/middleware/auth.ts - Tests in test/auth.test.ts cover token validation - You chose jose over jsonwebtoken for Edge compatibility Continues with the earlier decisions in context. ``` ### So với bộ nhớ tích hợp sẵn của agent Mọi AI coding agent đều đi kèm bộ nhớ tích hợp sẵn: Claude Code có `MEMORY.md`, Cursor có notepad, Cline có memory bank. Những thứ này hoạt động như giấy nhớ (sticky note). agentmemory là cơ sở dữ liệu có thể tìm kiếm đứng sau những tờ giấy nhớ đó. | | Tích hợp sẵn (CLAUDE.md) | agentmemory | |---|---|---| | Bảo trì | Chỉ dẫn được quản lý thủ công | Lịch sử phiên và bộ nhớ đã lập chỉ mục | | Tìm kiếm | Nạp tất cả vào context | BM25 + vector + graph (chỉ top-K) | | Đa agent | File theo từng agent | MCP + REST (mọi agent) | | Điều phối | Không có | Lease, signal, action, routine | | Observability | Đọc file thủ công | Viewer real-time trên :3113 | ---

Cách hoạt động

### Pipeline bộ nhớ ```text PostToolUse hook fires -> Stable event ID / durable capture inbox / offline spool -> Privacy filter (strip secrets, API keys) -> Store raw observation -> Synthetic compression by default (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled Stop / SessionEnd hook fires -> Summarize session -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true) -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject context when enabled by the integration ``` ### Hợp nhất bộ nhớ 4 tầng Lấy cảm hứng từ cách não người xử lý bộ nhớ, kể cả quá trình hợp nhất trong khi ngủ. | Tầng | Là gì | Tương tự | |------|------|---------| | **Working** | Observation thô từ việc dùng tool | Bộ nhớ ngắn hạn | | **Episodic** | Tóm tắt session đã nén | "Điều gì đã xảy ra" | | **Semantic** | Fact và pattern đã trích xuất | "Những gì tôi biết" | | **Procedural** | Workflow và pattern ra quyết định | "Cách làm việc đó" | Bộ nhớ suy giảm theo thời gian (đường cong Ebbinghaus). Bộ nhớ được truy cập thường xuyên sẽ mạnh lên. Bộ nhớ cũ sẽ tự bị loại bỏ. Các mâu thuẫn được phát hiện và giải quyết. ### Những gì được capture Bảng dưới mô tả hook của Claude Code. Các tích hợp khác ghi nhận sự kiện mà host cung cấp. Chèn ngữ cảnh tự động qua hook dùng chung là tùy chọn với `AGENTMEMORY_INJECT_CONTEXT=true`. | Hook | Capture gì | |------|----------| | `SessionStart` | Đường dẫn project, session ID | | `UserPromptSubmit` | Prompt của người dùng (đã lọc privacy) | | `PreToolUse` | Pattern truy cập file + context đã làm giàu | | `PostToolUse` | Tên tool, input, output | | `PostToolUseFailure` | Context lỗi | | `PreCompact` | Tiêm lại bộ nhớ trước khi compact | | `SubagentStart/Stop` | Lifecycle của sub-agent | | `Stop` | Tóm tắt cuối session | | `SessionEnd` | Dấu hiệu session hoàn tất | ### Khả năng chính | Khả năng | Mô tả | |---|---| | **Capture tự động** | Tích hợp native ghi nhận các sự kiện phiên và công cụ được hỗ trợ | | **Tìm kiếm ngữ nghĩa** | BM25 + vector + knowledge graph với RRF fusion | | **Tiến hóa bộ nhớ** | Versioning, supersession, relationship graph | | **Vệ sinh recall** | Các phiên bản bộ nhớ đã bị supersede rời khỏi search index; chuỗi version trong KV giữ lại toàn bộ lịch sử | | **Gợi ý near-duplicate** | Khi lưu, hệ thống báo một match tư vấn `similarTo` khi nội dung mới gần giống một bộ nhớ đã có | | **Scoping theo từng agent** | `agentId` xuyên suốt qua save và recall trên REST, MCP, và search index, ở chế độ shared hoặc isolated | | **Provenance tại thời điểm ghi** | Mọi observation và memory đều mang một origin channel bất biến (user, agent, tool, import, hoặc shared) được đóng dấu lúc capture, save, và import | | **Tự quên** | Hết hạn TTL, phát hiện mâu thuẫn, loại bỏ theo độ quan trọng | | **Privacy là ưu tiên** | API key, secret, tag `` bị loại bỏ trước khi lưu trữ | | **Tự phục hồi** | Circuit breaker, chuỗi fallback provider, health monitoring | | **Claude bridge** | Đồng bộ hai chiều với MEMORY.md | | **Knowledge graph** | Trích xuất entity + duyệt BFS | | **Bộ nhớ nhóm** | Namespace chia sẻ + riêng tư giữa các thành viên trong team | | **Provenance trích dẫn** | Truy lại bất kỳ memory nào về đúng observation nguồn | | **Snapshot Git** | Version, rollback, và diff trạng thái bộ nhớ | --- Retrieval ba luồng (triple-stream) kết hợp ba tín hiệu: | Luồng | Làm gì | Khi nào | |---|---|---| | **BM25** | Khớp từ khóa đã stem với mở rộng từ đồng nghĩa | Luôn bật | | **Vector** | Cosine similarity trên dense embedding | Khi embedding provider được cấu hình | | **Graph** | Duyệt knowledge graph qua khớp entity | Khi entity được phát hiện trong truy vấn | Được fuse bằng Reciprocal Rank Fusion (RRF, k=60) và đa dạng hóa theo session (tối đa 3 kết quả mỗi session). Khi vector index đã có dữ liệu, `mem::search` (đứng sau `memory_recall`) dùng ranker hybrid BM25 + vector. Khi không có embedding, nó dùng BM25. `smart-search` còn có thể fuse thêm các kết quả khớp từ graph cấu trúc khi dữ liệu graph tồn tại, kể cả ở chế độ keyless. Recall cho lesson chạy trên một BM25 index riêng trong memory thay vì quét toàn bộ corpus cho mỗi truy vấn. Các phiên bản memory đã bị supersede bị loại khỏi mọi đường recall; chuỗi version vẫn giữ lại lịch sử của chúng. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). BM25 tokenize được tiếng Hy Lạp, Cyrillic, Hebrew, Ả Rập, và Latin có dấu ngay từ đầu. Với bộ nhớ tiếng Trung / Nhật / Hàn, hãy cài thêm các segmenter tùy chọn (`npm install @node-rs/jieba tiny-segmenter`) để chia các đoạn CJK thành token ở mức từ; nếu không có chúng, agentmemory sẽ lùi nhẹ về tokenize theo cả đoạn và in ra một gợi ý một lần trên stderr. ### Embedding provider Bản cài keyless tắt vector embedding: `mem::search` dùng BM25, trong khi `smart-search` cũng có thể dùng dữ liệu graph cấu trúc đã có. Để chủ động dùng embedding ngữ nghĩa miễn phí ngay trên máy, hãy thêm dòng này vào `~/.agentmemory/.env` và khởi động lại agentmemory: ```env EMBEDDING_PROVIDER=local ``` Lần cài npm thông thường đã bao gồm runtime tùy chọn `@huggingface/transformers`. Request embedding đầu tiên sẽ tải `Xenova/all-MiniLM-L6-v2`, nên nó cần truy cập network và có thể mất lâu hơn; các lần inference sau đó chạy ngay trên máy. Các provider remote được tự phát hiện từ key của chúng trừ khi `EMBEDDING_PROVIDER` ghi đè lên. | Provider | Model | Chi phí | Ghi chú | |---|---|---|---| | **Local (khuyến nghị opt-in)** | `all-MiniLM-L6-v2` | Miễn phí | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | Gemini | `gemini-embedding-001` | Free tier | 100+ ngôn ngữ, 768/1536/3072 chiều (MRL), input 2048 token. Thay thế `text-embedding-004` ([đã deprecated, shutdown 14/01/2026](https://ai.google.dev/gemini-api/docs/deprecations)) | | OpenAI | `text-embedding-3-small` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) | | Voyage AI | `voyage-code-3` | Trả phí | Tối ưu cho code | | Cohere | `embed-english-v3.0` | Free trial | Dùng chung (general purpose) | | OpenRouter | Bất kỳ model nào | Thay đổi | Proxy đa model | ---

MCP Server

54 tool, 6 resource, 3 prompt, và 17 skill. > **MCP shim so với server đầy đủ:** package `@agentmemory/mcp` đã publish là một shim mỏng. Nó chỉ phơi ra toàn bộ 54 tool **khi nó có thể chạm tới một agentmemory server đang chạy** qua `AGENTMEMORY_URL` (chế độ proxy). Khi không có server nào tiếp cận được, shim sẽ lùi về một bộ 7 tool cục bộ (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Biến môi trường `AGENTMEMORY_TOOLS=core|all` là một flag *phía server*; đặt nó trong block `env` của shim không có tác dụng gì. Nếu bạn chỉ thấy 7 tool trong Cursor / OpenCode / Gemini CLI, hãy khởi động `npx -y @agentmemory/agentmemory@latest` (hoặc Docker stack) và đặt `AGENTMEMORY_URL=http://localhost:3111`. ### 54 Tool Ba mức hiển thị tool, từ nhỏ tới lớn: `AGENTMEMORY_TOOLS=core` thu hẹp hiển thị xuống 8 tool thiết yếu (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); bộ cơ bản dưới đây là 14 tool nền tảng của registry; mặc định (`AGENTMEMORY_TOOLS=all`) phơi ra toàn bộ 54 tool.
Tool cơ bản (14) | Tool | Mô tả | |------|-------------| | `memory_recall` | Tìm kiếm các observation trước đây | | `memory_compress_file` | Nén file markdown mà vẫn giữ nguyên cấu trúc | | `memory_save` | Lưu một insight, quyết định, hoặc pattern | | `memory_file_history` | Các observation trước đây về file cụ thể | | `memory_patterns` | Phát hiện pattern lặp lại | | `memory_sessions` | Liệt kê session gần đây | | `memory_smart_search` | Tìm kiếm hybrid semantic + từ khóa | | `memory_vision_search` | Tìm kiếm observation dạng ảnh | | `memory_timeline` | Observation theo trình tự thời gian | | `memory_profile` | Hồ sơ project (concept, file, pattern) | | `memory_export` | Export toàn bộ dữ liệu memory | | `memory_relations` | Truy vấn relationship graph | | `memory_commit_lookup` | Các session đứng sau một git commit | | `memory_commits` | Các commit được ghi lại cho một session |
Tool mở rộng (tổng 54, mức hiển thị mặc định) | Tool | Mô tả | |------|-------------| | `memory_patterns` | Phát hiện pattern lặp lại | | `memory_timeline` | Observation theo trình tự thời gian | | `memory_relations` | Truy vấn relationship graph | | `memory_graph_query` | Duyệt knowledge graph | | `memory_consolidate` | Chạy hợp nhất 4 tầng | | `memory_claude_bridge_sync` | Đồng bộ với MEMORY.md | | `memory_team_share` | Chia sẻ với thành viên team | | `memory_team_feed` | Các item đã chia sẻ gần đây | | `memory_audit` | Audit trail các operation | | `memory_governance_delete` | Xóa có kèm audit trail | | `memory_snapshot_create` | Snapshot có version Git | | `memory_action_create` | Tạo work item kèm dependency | | `memory_action_update` | Cập nhật trạng thái action | | `memory_frontier` | Các action chưa bị block, xếp theo độ ưu tiên | | `memory_next` | Action kế tiếp quan trọng nhất | | `memory_lease` | Lease độc quyền cho action (đa agent) | | `memory_routine_run` | Khởi tạo instance cho workflow routine | | `memory_signal_send` | Gửi message giữa các agent | | `memory_signal_read` | Đọc message kèm receipt | | `memory_checkpoint` | Gate theo điều kiện bên ngoài | | `memory_mesh_sync` | Đồng bộ P2P giữa các instance | | `memory_sentinel_create` | Watcher theo event | | `memory_sentinel_trigger` | Kích hoạt sentinel từ bên ngoài | | `memory_sketch_create` | Action graph tạm (ephemeral) | | `memory_sketch_promote` | Nâng lên vĩnh viễn | | `memory_crystallize` | Nén các action chain | | `memory_diagnose` | Kiểm tra sức khỏe | | `memory_heal` | Tự sửa trạng thái bị kẹt | | `memory_facet_tag` | Tag dạng dimension:value | | `memory_facet_query` | Truy vấn theo facet tag | | `memory_verify` | Truy lại provenance |
### 6 Resource · 3 Prompt · 17 Skill | Loại | Tên | Mô tả | |------|------|-------------| | Resource | `agentmemory://status` | Health, số session, số memory | | Resource | `agentmemory://project/{name}/profile` | Intelligence theo từng project | | Resource | `agentmemory://project/{name}/recent` | Observation gần đây cho một project | | Resource | `agentmemory://memories/latest` | 10 memory active mới nhất | | Resource | `agentmemory://graph/stats` | Thống kê knowledge graph | | Resource | `agentmemory://team/{id}/profile` | Hồ sơ team được chia sẻ | | Prompt | `recall_context` | Tìm kiếm + trả về các context message | | Prompt | `session_handoff` | Dữ liệu handoff giữa các agent | | Prompt | `detect_patterns` | Phân tích pattern lặp lại | | Skill | `/recall` | Tìm kiếm memory | | Skill | `/remember` | Lưu vào bộ nhớ dài hạn | | Skill | `/session-history` | Tóm tắt các session gần đây | | Skill | `/forget` | Xóa observation/session | Bảng này chỉ hiển thị 4 skill cốt lõi. Bộ đầy đủ gồm 9 skill có thể gọi cộng 8 skill tham chiếu; xem phần Skill gốc ở trên. ### MCP độc lập Chạy mà không cần server đầy đủ, cho bất kỳ MCP client nào. Một trong hai cách này đều được: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` Hoặc thêm vào config MCP của agent của bạn: Hầu hết các agent (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` Gộp entry `agentmemory` vào object `mcpServers` đã có của host thay vì thay thế toàn bộ file. Với các client chạy sandbox không chạm tới `localhost` của host, thêm `"AGENTMEMORY_FORCE_PROXY": "1"` vào block env và đặt `AGENTMEMORY_URL` tới một route mà sandbox chạm tới được. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` Copy file plugin từ repo: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

Viewer Real-Time

Tự khởi động trên port `3113`. Viewer nạp một snapshot khi nó kết nối (`GET /agentmemory/viewer/snapshot`) rồi áp các event từ live stream: memory mới, lesson, observation, audit entry, thay đổi graph và cập nhật health xuất hiện mà không cần polling hay reload trang. Các request khác duy nhất là những action bạn click, các trang "load more" và tìm kiếm. Khi stream rớt, viewer hiển thị số liệu của nó đã cũ bao lâu, kết nối lại với backoff và resync từ một snapshot. - **12 tab trong bốn nhóm** với số liệu live, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), phím tắt và menu cho mobile. - **Memories:** tìm kiếm phía server, filter theo project, agent và type, một panel chi tiết với chuỗi version và word diff, link provenance, nút copy cho id, lệnh gọi MCP và một lệnh curl, edit (tạo version mới), forget có xác nhận, forget theo lô và export JSON. - **Sessions:** một timeline observation nội tuyến với input/output tool dễ đọc, filter và phân trang, cùng các memory và lesson mà mỗi session tạo ra. - **Graph:** tìm kiếm, chi tiết node với relation và nguồn, một legend không chỉ dựa vào màu sắc, và điều khiển zoom. - **Health:** phiên bản live của `GET /agentmemory/status`. Mỗi vấn đề đều kèm cách khắc phục, cộng với state backend, trạng thái lưu index, tiến độ compact provenance của graph và một phần giải thích consolidation với các ngưỡng thực tế. - Các trang **Audit, Activity, Profile, Replay, Lessons, Actions và Crystals**, mỗi trang có một empty state nói rõ phần đó là gì, vì sao nó đang rỗng và lệnh nào sẽ lấp đầy nó, cùng một tooltip glossary `?` trên mỗi thuật ngữ và số liệu. ```bash open http://localhost:3113 ``` Viewer server bind vào `127.0.0.1` theo mặc định và gắn kèm server secret khi nó forward request tới REST API, nên nó không cần setup gì thêm. Endpoint `/agentmemory/viewer` được REST phục vụ tuân theo quy tắc bearer-token bình thường và redirect các browser không có token tới port của viewer. Header CSP dùng một script nonce theo từng response và tắt các inline handler attribute (`script-src-attr 'none'`). ---

Cấu hình

### LLM Provider agentmemory tự phát hiện provider từ environment của bạn. Một provider làm cho các operation dựa trên LLM khả dụng, nhưng chỉ cấu hình provider thôi không kích hoạt việc nén observation do LLM viết. Đường đó cần cả provider và `AGENTMEMORY_AUTO_COMPRESS=true`. | Provider | Config | Ghi chú | |----------|--------|-------| | **No-op (mặc định)** | Không cần config | Compress/summarize dựa trên LLM bị tắt. Nén synthetic và recall BM25 vẫn hoạt động. Xem `AGENTMEMORY_ALLOW_AGENT_SDK` dưới đây nếu bạn từng dựa vào fallback Claude-subscription. | | Anthropic API | `ANTHROPIC_API_KEY` | Tính phí theo token | | MiniMax | `MINIMAX_API_KEY` | Tương thích Anthropic | | Gemini | `GEMINI_API_KEY` | Cũng kích hoạt embedding | | OpenRouter | `OPENROUTER_API_KEY` | Bất kỳ model nào | | OpenAI API | `OPENAI_API_KEY` | Mặc định `gpt-5.6-luna`, ghi đè bằng `OPENAI_MODEL` | | **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) hoặc `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Bất cứ gì tương thích OpenAI-API. Không tốn phí, chạy trên hardware của bạn. Xem [Model cục bộ](#local-models-ollama--lm-studio--vllm) dưới đây. | | Fallback Claude subscription | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Chỉ opt-in. Spawn các session `@anthropic-ai/claude-agent-sdk`; trước đây nó từng gây ra đệ quy Stop-hook không giới hạn, nên nó không còn là mặc định. | ### Model cục bộ (Ollama / LM Studio / vLLM) agentmemory nói chuyện với bất kỳ server tương thích OpenAI-API nào, nên bất cứ gì phơi ra `/v1/chat/completions` đều hoạt động mà không cần sửa code. Không key trả phí, không cloud, không rate limit; chạy hoàn toàn trên hardware của bạn. **Ollama** (port mặc định `11434`): ```bash ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc. ollama serve ``` ```env # ~/.agentmemory/.env OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=qwen3:8b ``` **LM Studio** (port mặc định `1234`): Mở LM Studio → tab Local Server → Start Server. Chọn bất kỳ chat model nào trong bộ chọn (Qwen 3, gpt-oss, DeepSeek R1, v.v.). ```env # ~/.agentmemory/.env OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it OPENAI_BASE_URL=http://localhost:1234/v1 OPENAI_MODEL=qwen3-8b # match the model name from LM Studio ``` **vLLM / llama.cpp / Text Generation Inference**: cùng hình thái. Chỉ `OPENAI_BASE_URL` tới bất kỳ URL mà server của bạn phơi ra và đặt `OPENAI_MODEL` thành một tên mà server của bạn chấp nhận. **Chọn model cho công việc memory**: compression và summarization là các task ngắn (<2K token vào, <500 token ra) nơi một model instruct 7B là đủ dư. Khuyến nghị: | Model | Size | Vì sao | |-------|------|-----| | `qwen3:8b` | ~5.2 GB | Mặc định cân bằng trên máy 16 GB; mạnh ở extraction và text dạng tool | | `qwen3:4b` | ~2.6 GB | Lựa chọn nhỏ nhất còn hợp lý; ổn cho compression, yếu hơn ở graph extraction | | `qwen3-coder:30b` | ~19 GB | Lựa chọn local tốt nhất cho session dạng code (30B MoE, 3.3B active) trên hardware 24-32 GB | | `gpt-oss:20b` | ~14 GB | Model tổng quát mạnh, vừa với 16 GB RAM | | `deepseek-r1:8b` | ~5.2 GB | Reasoning distill; chậm hơn nhưng extraction sạch hơn | Các model Qwen 3 mặc định có suy nghĩ (think) và có thể đốt hết toàn bộ token budget vào reasoning trước khi có bất kỳ output nào. Đặt `AGENTMEMORY_LLM_NOTHINK=1` để thêm `/no_think` vào các prompt graph-extraction, và tăng `MAX_TOKENS` (16384 là ổn) nếu extraction trả về rỗng. Các model dạng reasoning (kiểu `o1` với block ``) có thể trả về `content` rỗng cùng một field `reasoning` mà server local của bạn có thể không phơi ra. Nếu extraction trả về trống, hãy chuyển sang một model non-reasoning trước. Biến env `OPENAI_REASONING_EFFORT=none` cũng có thể tắt thinking trên các model thinking của Ollama Cloud vốn mirror schema reasoning của OpenAI. Embedding cục bộ đi kèm như một dependency tùy chọn nhưng không được bật theo mặc định. Đặt `EMBEDDING_PROVIDER=local` để chủ động dùng `Xenova/all-MiniLM-L6-v2` (384 chiều). Request embedding đầu tiên sẽ tải model; inference chạy trên máy sau đó. Nếu không có setting đó hoặc một key embedding remote, vector vẫn bị tắt, `mem::search` dùng BM25, và `smart-search` vẫn có thể thêm các kết quả khớp graph đã có. ### Chọn model theo chi phí Bắt đầu không cần khóa để ghi nhận và tìm theo từ khóa. `EMBEDDING_PROVIDER=local` cung cấp tìm kiếm ngữ nghĩa trên máy sau lần tải mô hình đầu tiên. Nén LLM cần nhà cung cấp và `AGENTMEMORY_AUTO_COMPRESS=true`, có thể gửi yêu cầu cho từng quan sát; hãy kiểm tra giá hiện hành. `agentmemory status` / http://localhost:3113 ### Bộ nhớ đa agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) Trong các thiết lập đa agent nơi nhiều role chia sẻ một agentmemory server (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` gắn tag cho mỗi lần write với role đã tạo ra nó. `AGENTMEMORY_AGENT_SCOPE` kiểm soát việc recall có filter theo tag đó hay không. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` Hai chế độ: | Chế độ | Tag write | Filter recall | Khi nào dùng | |------|------------|---------------|-------------| | `shared` (mặc định) | có | không | Context chia sẻ giữa các agent kèm audit trail. Architect có thể thấy những gì developer ghi chú, nhưng mỗi row đều ghi lại ai đã nói điều đó. | | `isolated` | có | có | Tách biệt nghiêm ngặt. Architect không bao giờ thấy observation / memory / session của developer. | Những gì bị tag khi `AGENT_ID` được đặt: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Role này chảy từ `api::session::start` → `mem::observe` → `mem::compress` → KV. Những gì bị filter ở chế độ isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Mỗi endpoint nhận `?agentId=` để ghi đè theo từng request, và `?agentId=*` để bỏ qua scope env hoàn toàn. `/memories` cũng nhận `?includeOrphans=true` để lấy ra các memory từ trước khi có AGENT_ID, có `agentId` là undefined. Ghi đè theo từng lệnh gọi ở tầng SDK / REST: mọi endpoint mutating (`/session/start`, `/remember`) nhận một field `agentId` trong request body, field này thắng env. Hữu ích cho các runtime định tuyến nhiều role qua một process server. Tool MCP `memory_save` phơi ra cùng field `agentId`, standalone stdio server forward cả `agentId` và `project`, và các memory đã lưu mang `agentId` vào search index, nên search theo scope agent bao phủ cả memory cũng như observation. Khi `AGENT_ID` chưa được đặt, memory vẫn không có scope (hành vi legacy, không tag, không filter). ### Port API và trình xem mặc định chỉ lắng nghe trên loopback. | Port | API / Trình xem | Env | |---|---|---| | `3111` | REST / MCP / SSE | `III_REST_PORT` | | `3113` | Trình xem | `III_VIEWER_PORT` | `--port ` đặt cổng API; trình xem mặc định dùng `N+2`. Dùng `--instance N` cho instance riêng. Giữ các listener nội bộ riêng tư; xem hướng dẫn triển khai để truy cập từ xa và [chuyển từ Docker cũ](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode). ### Storage backend: file (mặc định) so với redis Không cần dịch vụ cơ sở dữ liệu riêng. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. Đổi backend không tự sao chép bộ nhớ hiện có. [Lưu trữ dữ liệu](../docs/reliability/state-storage.md). ### File Config Đặt runtime config trong `~/.agentmemory/.env` thay vì export biến ở mọi shell. Dùng `AGENTMEMORY_ENV_FILE` để chọn env-file khác. Biến môi trường của process được ưu tiên hơn giá trị trong file. Worker Compose do CLI tạo truyền Redis setting tới worker `state`. ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` Để test với một subscription Claude Code Pro/Max thay vì một API key, hãy opt-in rõ ràng: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` Nén observation do LLM viết cần cả hai dòng: quyền truy cập tới một LLM provider (kể cả fallback subscription rõ ràng này) và `AGENTMEMORY_AUTO_COMPRESS=true`. Chỉ riêng một provider sẽ để đường nén synthetic mặc định nguyên tại chỗ. Consolidation (node graph, lesson, crystal) được bật theo mặc định bất cứ khi nào một LLM provider được cấu hình. Opt-out rõ ràng bằng `CONSOLIDATION_ENABLED=false` nếu bạn muốn hoạt động không-LLM. Graph extraction là một flag riêng: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### Biến Môi trường `~/.agentmemory/.env`: ```env EMBEDDING_PROVIDER=local # AGENTMEMORY_INJECT_CONTEXT=true # AGENTMEMORY_AUTO_COMPRESS=true # AGENTMEMORY_TOOLS=core # AUTO_FORGET_ENABLED=false # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` Tham chiếu đầy đủ ở [`.env.example`](../.env.example), gồm nhà cung cấp, bộ lọc capture, lưu giữ, kho lưu trữ và phạm vi nhóm. `AGENTMEMORY_ENV_FILE` chọn tệp khác. Khởi động lại sau khi thay đổi cấu hình. Không commit `.env` đã điền giá trị thật hay bí mật Bearer. ---

API

147 endpoint trên port `3111`. REST API bind vào `127.0.0.1` theo mặc định. Các endpoint được bảo vệ cần `Authorization: Bearer `, và các endpoint mesh sync cần `AGENTMEMORY_SECRET` được đặt rõ ràng trên cả hai phía. Xác thực bật mặc định. Nếu chưa đặt `AGENTMEMORY_SECRET`, CLI tạo bí mật ngẫu nhiên lần đầu tại `~/.agentmemory/secret` và sao chép vào `secret` trong thư mục dữ liệu đã chọn, với quyền `0600`. Client đi kèm ưu tiên tệp chính này khi kết nối cục bộ và chỉ gửi bí mật đã lưu đến URL loopback. `AGENTMEMORY_SECRET` đặt tường minh luôn được ưu tiên; client từ xa phải đặt qua biến môi trường. Triển khai Docker tạo bí mật riêng. ```bash curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health ``` **Quy tắc request cho các lệnh write.** Các request `POST`, `PUT`, `PATCH` và `DELETE` tới REST API và viewer phải gửi `Content-Type: application/json` (một tham số `charset` thì vẫn ổn) bất cứ khi nào chúng mang theo body, và một header `Origin`, nếu có, phải là một origin loopback cho port REST hoặc viewer đã cấu hình hoặc được liệt kê trong `VIEWER_ALLOWED_ORIGINS` (phân tách bằng dấu phẩy, ví dụ `https://memory.example.com`). Các client không gửi header `Origin` (CLI, hook, MCP, curl, server-to-server) không bị ảnh hưởng. Viewer cũng chấp nhận origin của chính nó. **Đường dẫn file.** Các endpoint đọc hoặc viết file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) chỉ nhận đường dẫn nằm dưới `~/.agentmemory`, thư mục data của instance, hoặc một thư mục được liệt kê trong `AGENTMEMORY_IMPORT_ROOT` (tách nhiều thư mục bằng `:`, hoặc `;` trên Windows). `/replay/import-jsonl` cũng nhận mặc định `~/.claude/projects` của nó. `/obsidian/export` ở trong `AGENTMEMORY_EXPORT_ROOT` và `/migrate` ở trong `~/.agentmemory`. Symlink được resolve trước mỗi lần kiểm tra. **Scrub secret.** API key, bearer token, block PEM private key và credential nhúng trong URL (`scheme://user:password@host`) đều bị redact trước khi text được lưu, trên mọi đường write: observation, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, output compression và summary, crystal và node graph.
Các endpoint chính | Method | Path | Mô tả | |--------|------|-------------| | `GET` | `/agentmemory/health` | Health check (luôn public) | | `GET` | `/agentmemory/status` | Cái gì đang sai và cách sửa nó (HTML cho browser, JSON cho trường hợp khác) | | `GET` | `/agentmemory/viewer/snapshot` | Mọi thứ viewer hiển thị, trong một response | | `POST` | `/agentmemory/session/start` | Bắt đầu session + lấy context | | `POST` | `/agentmemory/session/end` | Kết thúc session | | `POST` | `/agentmemory/observe` | Capture observation (xem phần capture delivery dưới đây) | | `GET` | `/agentmemory/capture` | Capture inbox, dead letter và offline spool | | `POST` | `/agentmemory/capture/retry` | Retry các capture dead-letter | | `POST` | `/agentmemory/capture/drain` | Gửi offline spool cục bộ ngay | | `POST` | `/agentmemory/smart-search` | Tìm kiếm hybrid | | `POST` | `/agentmemory/context` | Sinh context | | `POST` | `/agentmemory/remember` | Lưu vào bộ nhớ dài hạn | | `POST` | `/agentmemory/forget` | Xóa observation | | `POST` | `/agentmemory/enrich` | Context file + memory + bug | | `GET` | `/agentmemory/profile` | Hồ sơ project | | `GET` | `/agentmemory/export` | Export toàn bộ dữ liệu | | `POST` | `/agentmemory/import` | Import từ JSON | | `POST` | `/agentmemory/graph/query` | Truy vấn knowledge graph | | `POST` | `/agentmemory/graph/compact` | Cắt gọn provenance graph quá lớn | | `POST` | `/agentmemory/team/share` | Chia sẻ với team | | `GET` | `/agentmemory/audit` | Audit trail | Danh sách endpoint đầy đủ: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Capture delivery.** Hook gửi mỗi observation một lần tới `POST /agentmemory/observe` kèm một `eventId`. Đó là id riêng của host cho lệnh gọi này khi payload có sẵn một id (ví dụ `tool_use_id` của Claude Code), nếu không thì là một hash của session, loại hook, tên tool, input, output và timestamp của host. Server viết event vào một capture inbox trong state store, lưu observation, rồi xóa entry trong inbox. Status code nói lên điều gì đã xảy ra: | Status | Field `status` | Ý nghĩa | |---|---|---| | `201` | `accepted` | Đã lưu. `observationId` là observation mới. | | `202` | `accepted` (`state: "retrying"`) | Đã accept, nhưng lưu thất bại. Server sẽ retry, cả sau một lần restart. | | `200` | `duplicate` | `eventId` này đã được accept trước đó. `observationId` là observation đã có; không có gì mới được lưu. | | `400` / `422` | `rejected` | Payload không hợp lệ, hoặc lưu thất bại hẳn (event được giữ lại như một dead letter). | | `503` | `rejected` (`retryable: true`) | Inbox đã đầy (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook sẽ spool event lại và gửi sau. | Các event thất bại được retry mỗi `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 giây) với backoff tăng dần, tối đa `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Các event vẫn thất bại sẽ nằm lại trong inbox như dead letter, được liệt kê trên `/agentmemory/status` và trang Health của viewer, và có thể retry bằng `POST /agentmemory/capture/retry` (`{"eventId": "..."}` hoặc `{"all": true}`). Các event id đã accept được ghi nhớ trong `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 giờ, tối đa `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), nên một hook được replay sau một timeout hay một restart chỉ được lưu một lần, trong khi hai lệnh gọi tool riêng biệt với id host riêng của chúng được lưu hai lần dù nội dung giống nhau. Khi một observation bị xóa (forget, xóa session, eviction, auto-forget hoặc một import thay thế store), event của nó được đánh dấu đã xóa trước khi observation bị gỡ, nên một lần replay của event đó trong cùng window được trả lời như một duplicate và không lưu gì cả. State store viết ra disk mỗi 2 giây, nên một event đã được trả lời vẫn có thể chỉ nằm trong memory một khoảnh khắc. Để bù cho điều đó, mỗi câu trả lời `2xx` cũng mang theo `bootId` của server (mới ở mỗi lần khởi động), `acceptedAt` và `durableAfterMs` (interval save cộng 1.5 giây trên file store, 1.5 giây trên redis, nơi độ bền là setting của người vận hành). Hook giữ event trong spool cục bộ cho tới khi window đó trôi qua và xóa nó ở một lệnh gọi sau mà không cần một request khác. Nếu `bootId` đã thay đổi vào lúc đó, server đã restart, nên hook gửi lại event với cùng `eventId`; một event đã chạm tới disk không bị lưu hai lần. Server cũng tự gửi các event như vậy lúc khởi động và ở mỗi retry interval, nên một lần restart không mất gì cả dù không có hook nào chạy sau đó. Các hook cũ bỏ qua các field thêm này, và các hook mới chạy với một server cũ sẽ drop event khi nhận `2xx` như trước. Khi server down, không trả lời kịp hoặc trả về 5xx, hook sẽ append observation vào một file spool cục bộ, `/capture-spool/-.jsonl` (ghi đè thư mục bằng `AGENTMEMORY_CAPTURE_SPOOL_DIR`). File này riêng tư cho user của bạn (mode 600), secret được redact theo đúng cách server redact chúng, nó giữ tối đa `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) và drop các entry cũ hơn `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Khi nó đầy, các entry mới bị drop và được đếm, và `/agentmemory/status` sẽ báo cáo điều đó. Hook vẫn exit 0 trong giới hạn thời gian của nó và không thêm request nào khi server khỏe mạnh. Spool được gửi ở lần khởi động kế tiếp và bởi hook đầu tiên chạm tới server trở lại, trong một process nền để agent không phải chờ. Event id làm cho điều này an toàn: một observation đã đến trước một timeout không bị lưu hai lần. `npx @agentmemory/agentmemory capture` hiển thị spool và inbox của server, `--drain` gửi spool ngay, và `GET /agentmemory/capture` trả về cùng dữ liệu đó dưới dạng JSON. Đặt `AGENTMEMORY_CAPTURE_SPOOL=false` để tắt spool. **Compact provenance của graph.** Việc compact provenance cũ được hoãn khi khởi động vì phải đọc toàn bộ các scope cũ. `/agentmemory/status` báo `deferred`, hoặc `off` khi đặt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Chạy compact thủ công bên dưới trong thời gian bảo trì. Di chuyển chỉ mục truy xuất là thao tác riêng: dùng `agentmemory graph-index migrate --allow-legacy-scan` theo [hướng dẫn bảo trì](../docs/reliability/graph-index-migration.md). Để chạy nó bằng tay, gọi `POST /agentmemory/graph/compact`. Nó duyệt qua các index tên và edge-key thay vì liệt kê mọi node và edge, và an toàn để chạy lại. Khi nó cắt gọn id, nó viết một audit entry `graph_compact`. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}' ``` Trên một store lớn, hoặc khi lệnh gọi trả về 504, hãy chạy nó theo slice. Gửi `scope` (`nodes`, `edges` hoặc `history`), `offset` và `limit`, rồi gọi lại với `nextOffset` được trả về cho tới khi nó là `null`. Làm điều này cho `nodes`, `edges` và `history`, và kết thúc với một lệnh gọi `{"scope":"snapshot"}`, vì một lần chạy theo slice không chạm tới snapshot đã cache. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

Phát triển

```bash npm run dev # Hot reload npm run build # Production build npm test # 5,000+ tests npm run test:integration # API tests (requires running services) ``` Xem [Cài đặt](#install) về yêu cầu và [CONTRIBUTING.md](../CONTRIBUTING.md) về quy tắc đóng góp cùng kiểm tra phát hành.

Giấy phép

[Apache-2.0](../LICENSE)