Memori persisten lintas sesi coding dan agen.
Memori persisten untuk Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, dan klien MCP apa pun.
Gist ini memperluas pola LLM Wiki milik Karpathy dengan confidence scoring, lifecycle, knowledge graph, dan hybrid search: agentmemory adalah implementasinya.
---
AgentMemory merekam sesi coding agar keputusan dan perbaikan bisa dicari kembali. Gunakan satu penyimpanan memori di berbagai alat, periksa data yang tersimpan, dan tentukan banyaknya konteks yang diterima model.
## Instalasi
Persyaratan:
- Node.js 20 atau lebih baru dengan npm dan npx (`node -v`, `npm -v`, dan `npx -v`).
- Setup otomatis di macOS/Linux memerlukan `curl`, POSIX `sh`, dan `tar`.
- Windows / WSL2: [Windows](#windows).
Perintah instalasi awal yang baku:
```bash
npx -y @agentmemory/agentmemory@latest
```
Pilih agen dan penyedia atau mode tanpa kunci. Setup menyimpan konfigurasi, menjalankan server memori, dan menawarkan instalasi global. `-y` menerima konfirmasi npm; `@latest` memilih rilis terbaru. Kompresi oleh LLM memerlukan penyedia serta `AGENTMEMORY_AUTO_COMPRESS=true`.
Mode tanpa kunci (keyless) menonaktifkan vector embedding. `memory_recall` (jalur `mem::search`) memakai BM25, sementara `memory_smart_search` juga bisa menggabungkan kecocokan graph struktural saat data graph sudah ada. Untuk recall semantik gratis di perangkat sendiri, set `EMBEDDING_PROVIDER=local` di `~/.agentmemory/.env` lalu restart. Permintaan embedding pertama mengunduh `Xenova/all-MiniLM-L6-v2`; inferensi berjalan lokal setelah unduhan model awal itu.
API tersedia di `http://localhost:3111` dan viewer langsung di `http://localhost:3113`. Keduanya memakai loopback secara default. Konfigurasi disimpan di `~/.agentmemory/.env`. [Penyimpanan data](#data-storage).
Lalu buktikan bahwa recall berfungsi dan beri agen Anda skill-nya:
```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
```
Pencarian kata kunci seharusnya berhasil di mode keyless default lewat BM25. Query `database performance optimization` pada demo sengaja dibuat semantik dan bisa menghasilkan nol sampai penyedia embedding dikonfigurasi.
Lebih suka membiarkan agen coding mengerjakan semuanya? Berikan satu instruksi ini:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Tambahkan agen dengan `agentmemory connect `. Lihat [integrasi yang didukung](#works-with-every-agent) dan [perintah sehari-hari](#everyday-commands).
Instalasi global / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
Perintah npx di atas tetap menjadi jalur instalasi awal yang baku dan menghindari masalah izin global-prefix.
npx menyajikan versi lama
npx melakukan cache per versi. Paksakan versi terbaru dengan `npx -y @agentmemory/agentmemory@latest`, atau bersihkan cache sekali dengan `rm -rf ~/.npm/_npx` (macOS/Linux; di Windows hapus `%LOCALAPPDATA%\npm-cache\_npx`).
---
agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API. Semua agen berbagi server memori yang sama.
Claude Code plugin native + 12 hook + MCP
Codex CLI plugin native + 6 hook + MCP
GitHub Copilot CLI MCP + hook/skill plugin
Cursor plugin native + hook lifecycle + MCP
OpenCode plugin capture + MCP
Devin 6 hook + skill + MCP
OpenClaw plugin native + MCP
Hermes plugin native + MCP
pi recall native + capture + skill
OpenHuman backend native Memory trait
Gemini CLI server MCP
Antigravity MCP + hook
Claude Desktop server MCP
Warp connect + MCP + skill
Zed server MCP
Cline server MCP
Continue server MCP
Droid server MCP
Kiro server MCP
Qwen Code server MCP
DeepSeek Harness capture native + MCP
Roo Code server MCP
Kilo Code server MCP
Goose server MCP
Aider REST API
Oh My Pi recall native + capture + skill + MCP opsional
Bekerja dengan agen apa pun yang memakai MCP atau HTTP. Satu server, memori dibagikan di antara semuanya.
---
### Penyimpanan data
Memori disimpan di luar repositori secara default. Instance 0 memakai kembali `./data/state_store.db` yang sudah ada. Pilih lokasi dengan `--data-dir ` atau `AGENTMEMORY_DATA_DIR`, lalu gunakan direktori yang sama saat restart dan upgrade.
| Platform | Direktori data |
|---|---|
| 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` memakai subdirektori `instance-1`, port API `3211`, dan viewer `3213`. Lihat [penyimpanan dan cadangan](../docs/reliability/state-storage.md) untuk Redis dan migrasi backend.
Catatan rilis terbaru: [CHANGELOG.md](../CHANGELOG.md).
---
Hasil penelusuran terkini, definisi metrik, dan langkah reproduksi:
[0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md).
---
### Coba dalam 30 detik
```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` menyemai (seed) 3 sesi realistis (autentikasi JWT, perbaikan query N+1, rate limiting) dan menjalankan pencarian terhadapnya. Instalasi tanpa kunci menonaktifkan vector, sehingga query kata kunci `mem::search` seharusnya berhasil lewat BM25 sementara `database performance optimization` bisa menghasilkan nol. `smart-search` bisa juga mengembalikan kecocokan graph struktural saat data graph ada. Agar query semantik menemukan perbaikan N+1 lewat vector, set `EMBEDDING_PROVIDER=local`, restart, dan biarkan unduhan model pertama selesai.
Buka `http://localhost:3113` untuk menyaksikan memori terbangun secara live.
### Validasi instalasi baru dan persistensi setelah restart
Dengan server berjalan, periksa kesehatan, viewer, dan statusnya.
```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` menampilkan kesehatan server, penyedia, mode embedding, pengiriman capture, dan pemulihan. Permintaan REST yang dilindungi memerlukan rahasia server. Gunakan `AGENTMEMORY_SECRET` yang dikonfigurasi atau baca rahasia lokal yang dibuat otomatis jika tidak disetel.
```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}'
```
Lalu jalankan `npx -y @agentmemory/agentmemory@latest stop`, jalankan lagi perintah baku di Terminal 1, tunggu `/agentmemory/livez`, dan ulangi pencariannya. Probe itu harus masih dikembalikan. Jika Anda memilih `--data-dir` custom, gunakan direktori yang sama saat restart.
### Perintah sehari-hari
Instalasi dan setup ada di [Instalasi](#install) di atas (jalankan pertama akan menuntun Anda melaluinya). Sehari-hari:
```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
```
### Replay Sesi
Setiap sesi yang direkam agentmemory bisa direplay. Buka viewer, pilih tab **Replay**, lalu scrub sepanjang timeline: prompt, tool call, hasil tool, dan respons dirender sebagai event diskret dengan play/pause, kontrol kecepatan (0.5x hingga 4x), dan shortcut keyboard (spasi untuk toggle, arrow untuk melangkah).
Untuk membawa masuk transkrip JSONL Claude Code yang lama:
```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
```
Sesi impor muncul bersama sesi native di Replay, diindeks untuk pencarian, dan ditandai dengan kanal asal `import`. Pemrosesan sesi juga dapat menghasilkan kristal dan pelajaran.
> **Perhatian jika Anda mengandalkan `import-jsonl` sebagai jalur capture utama:** `cleanupPeriodDays` milik Claude Code (di `~/.claude/settings.json`, default **30**) menghapus otomatis transkrip JSONL yang lebih tua dari window itu dari `~/.claude/projects/`. Jika Anda memasang agentmemory baru pada histori Claude Code yang sudah berbulan-bulan, apa pun yang lebih tua dari 30 hari sudah hilang sebelum impor pertama. Entah jalankan `import-jsonl` lewat cron, naikkan `cleanupPeriodDays` jadi lebih tinggi, atau sambungkan hook auto-capture (jalur instalasi plugin default) sehingga setiap giliran langsung masuk ke agentmemory selagi sesi berjalan dan pembersihan JSONL tidak lagi jadi masalah.
### Upgrade / Pemeliharaan
Gunakan perintah pemeliharaan saat Anda sengaja ingin memperbarui runtime lokal Anda:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Perintah ini memperbarui runtime lokal dan dapat memperbarui dependensi JavaScript dalam direktori kerja. Cadangkan data dan baca [panduan upgrade](../docs/upgrades/iii-0.25.md) sebelum memperbarui instalasi yang ada.
### Claude Code (satu blok, tempel saja)
```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 tanpa instalasi plugin (jalur MCP-standalone)
Jika Anda menyambungkan server MCP agentmemory lewat `~/.claude.json` (jalur default) secara langsung tanpa memakai `/plugin install`, Claude Code tidak pernah meresolusi `${CLAUDE_PLUGIN_ROOT}` dan Anda harus mengarahkan script hook ke path absolut di `~/.claude/settings.json` (jalur default). Path tersebut biasanya menyertakan versi agentmemory (misalnya `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), sehingga upgrade berikutnya diam-diam merusak setiap hook.
Solusinya:
```bash
agentmemory connect claude-code --with-hooks
```
Perintah ini mengonfigurasi server MCP dan menggabungkan hook bawaan ke konfigurasi pengguna Claude Code. Jika `CLAUDE_CONFIG_DIR` tidak diatur, kosong, atau hanya berisi whitespace, perintah ini menggunakan `~/.claude.json` untuk MCP dan `~/.claude/settings.json` untuk hook. Nilai direktori lainnya digunakan persis seperti yang diberikan, termasuk whitespace di awal dan akhir. Untuk direktori khusus, atur `CLAUDE_CONFIG_DIR` ke nilai tidak kosong yang sama untuk perintah ini dan Claude Code; file yang digunakan menjadi `$CLAUDE_CONFIG_DIR/.claude.json` dan `$CLAUDE_CONFIG_DIR/settings.json`, masing-masing. Claude Code harus menerima nilai ini di lingkungan saat dijalankan, meskipun konektor membacanya dari `.env` milik AgentMemory. Buat direktori khusus sebelum menjalankan perintah ini; jika tidak, konektor melewati Claude Code karena tidak terdeteksi. Jika nilai di shell hanya berisi whitespace, hapus `CLAUDE_CONFIG_DIR` dari lingkungan sebelum menjalankan Claude Code agar juga menggunakan profil default. Gunakan jalur absolut. Jalur relatif ditentukan berdasarkan direktori kerja, jadi kedua perintah harus dijalankan dari direktori yang sama.
Perintah hook menggunakan jalur absolut ke direktori `plugin/` bawaan paket yang terpasang. Jalankan ulang perintah ini setelah memperbarui agentmemory untuk menyegarkan jalur tersebut. Entri pengguna dalam file konfigurasi tetap dipertahankan; hanya entri agentmemory sebelumnya yang diganti. Penggunaan `/plugin install` tetap menjadi pendekatan yang disarankan.
Untuk deployment remote atau terlindungi, jalankan Claude Code dengan `AGENTMEMORY_URL` dan `AGENTMEMORY_SECRET` yang sudah diset. Plugin ini meneruskan kedua nilai itu ke server MCP bundelnya; ketika `AGENTMEMORY_URL` kosong, shim MCP memakai `http://localhost:3111`.
### Codex CLI (platform plugin 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 dikirim dari direktori `plugin/` yang sama dengan plugin Claude Code. Ia mendaftarkan:
- Bridge MCP stdio bundel ke daemon yang berjalan, tanpa unduhan npm atau fallback store. Lihat [panduan Codex lokal](../docs/plugins/codex-local.md) untuk menguji build yang belum dirilis.
- 6 hook lifecycle: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 skill yang bisa dipanggil: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, ditambah 8 skill referensi yang dimuat agen sesuai kebutuhan (disiplin memori, tool MCP, REST API, konfigurasi, agen, hook, arsitektur, dan panduan penulisan skill)
Engine hook Codex menyuntikkan `CLAUDE_PLUGIN_ROOT` ke subproses hook (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), sehingga script hook yang sama bekerja di kedua host tanpa duplikasi. Event Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure hanya berlaku untuk Claude Code dan tidak didaftarkan untuk Codex.
#### Trust dan kompatibilitas hook Codex
Dispatch hook plugin native sudah terverifikasi dengan Codex CLI 0.150.1. Percayai (trust) hook plugin sebelum mengharapkan capture. Perilaku Desktop bergantung pada runtime bundelnya; periksa `/hooks` dan pastikan ada event yang ter-capture sebelum mengaktifkan workaround.
Jika host Anda memerlukan hook global, cerminkan perintahnya ke `~/.codex/hooks.json`. Jika MCP sudah tersambung, connector saat ini memerlukan `--force` untuk mencapai instalasi hook:
```bash
agentmemory connect codex --with-hooks --force
```
Ini menggabungkan hook global dan menulis ulang entri MCP agentmemory, sambil mempertahankan entri lain yang tidak terkait. Tinjau kembali setelan endpoint agentmemory custom Anda sebelum memakai `--force`. Jalankan ulang setelah upgrade untuk menyegarkan path script. Aktifkan salah satu: hook plugin native atau salinan global, untuk menghindari capture ganda.
### GitHub Copilot CLI
Untuk mode agen VS Code, gunakan [panduan MCP dan automatic-capture Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Connector CLI ini tidak mengonfigurasi 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` menggabungkan `mcpServers.agentmemory` ke `~/.copilot/mcp-config.json` (atau `$COPILOT_HOME/mcp-config.json` saat `COPILOT_HOME` diset) dan mempertahankan server yang sudah ada. Di Windows native ini adalah satu-satunya adapter `connect` otomatis; konfigurasikan setiap agen Windows native lain secara manual. `connect` di WSL hanya tepat dipakai saat agen target juga terpasang di environment WSL yang sama. Copilot mengambil server MCP pada peluncuran berikutnya atau setelah `/mcp`. Pasang plugin-nya juga jika Anda menginginkan pengalaman hook/skill yang lengkap.
### Cursor
Atur MCP dengan `agentmemory connect cursor`. Di **Settings → Plugins → Add marketplace**, pilih checkout yang berisi `.cursor-plugin/plugin.json`, aktifkan agentmemory, lalu muat ulang. Plugin menyediakan capture lifecycle, atribusi workspace, skill, dan MCP. Aktifkan hanya hook plugin atau hook manual di `~/.cursor/hooks.json` agar capture tidak ganda.
[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
```
Pilih perintah untuk host Anda. Pi dan OMP memasang recall/capture native, replay offline, dan 17 skill; `--with-mcp` menambahkan semua alat. Jalankan `/reload` di Pi atau restart OMP, lalu periksa `/agentmemory-status`. DSH memasang MCP dan plugin capture bawaan; restart setelah terhubung.
Pi juga mendukung paket `@agentmemory/pi`. Lihat [panduan Pi](../integrations/pi/) untuk instalasi lokal dan ketersediaan npm. Gunakan satu metode instalasi per host.
[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (tempel prompt ini)
```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`.
```
Panduan lengkap: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (tempel prompt ini)
```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.
```
Panduan lengkap: [`integrations/hermes/`](../integrations/hermes/)
### Agen lainnya
Jalankan server memori: `npx -y @agentmemory/agentmemory@latest`
#### Native skill lewat `npx skills add`
agentmemory menyediakan 17 skill dalam format `/SKILL.md` ala Claude Code: 9 skill aksi yang bisa dipanggil (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) dan 8 skill referensi yang dimuat agen sesuai kebutuhan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Skill referensi membawa tabel data yang dihasilkan dari source, sehingga tidak pernah drift. CLI [`skills`](https://npmjs.com/package/skills) oleh vercel-labs memasangnya secara otomatis ke direktori skill native agen yang memanggilnya, di 50+ agen (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, dan lainnya):
```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
```
Ini **melengkapi** `agentmemory connect `:
Konektor Hermes, OpenClaw, Pi, dan Oh My Pi memasang integrasi native serta skill secara default; MCP bersifat opt-in lewat `--with-mcp`. Untuk host lain, pasang skill dengan `npx skills add rohitg00/agentmemory`.
Untuk sedikit agen yang belum dicakup CLI skills (Zed v1.3.x ke bawah), letakkan sendiri 17 file SKILL.md di bawah direktori skill native agen tersebut; format yang sama bekerja di mana saja.
#### Blok MCP standar
Entri agentmemory adalah **blok server MCP yang sama** di setiap host yang memakai bentuk `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}"
}
}
```
**Gabungkan entri ini ke dalam objek `mcpServers` yang sudah ada** di file konfigurasi host, jangan menggantikan seluruh file. Jika file itu sudah punya server lain, tambahkan `agentmemory` di sebelahnya sebagai key lain di dalam `mcpServers`. Jika `mcpServers` sama sekali belum ada, tempel bloknya di dalam `{ "mcpServers": { ... } }`. Placeholder `${VAR}` mewarisi `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` dari shell saat server MCP diluncurkan; variabel yang tidak diset meneruskan string kosong dan shim-nya fallback ke `http://localhost:3111`. Satu entri yang tersambung mencakup deployment lokal maupun remote (k8s / reverse-proxied).
| Agen | File konfigurasi | Catatan |
|---|---|---|
| **Cursor (MCP saja)** | `~/.cursor/mcp.json` | Gabungkan ke `mcpServers`, atau `agentmemory connect cursor`. Deeplink satu klik juga tersedia di website. |
| **Cursor (plugin lengkap)** | `.cursor-plugin/` | Cursor Marketplace atau Settings → Plugins → checkout lokal. Mendaftarkan hook lifecycle lewat adapter tipis yang memanggil `plugin/scripts/*.mjs` bersama, serta skill dan MCP. Adapter menentukan workspace yang tidak selalu dilaporkan Cursor dengan benar. Lihat [Cursor](#cursor). Bekerja di Cursor IDE dan CLI `cursor-agent`. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Gabungkan ke `mcpServers`. Restart Claude Desktop setelah mengedit. |
| **Cline / Roo Code / Kilo Code** | Setelan MCP Cline (Settings UI → MCP Servers → Edit) | Blok `mcpServers` yang sama. |
| **Devin CLI (MCP + hook)** | `~/.config/devin/config.json` | `agentmemory connect devin` menggabungkan entri MCP; `--with-hooks` menambahkan enam hook auto-capture native (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) dengan matcher tool huruf-kecil milik Devin. Verifikasi dengan `devin mcp list` dan `/hooks` di dalam devin. |
| **Devin CLI (plugin lengkap)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` dari sebuah checkout mendaftarkan semua 17 skill sebagai slash command `/agentmemory:` ditambah server MCP. Hook plugin Devin tidak bisa memicu `SessionStart`/`SessionEnd`, jadi pasangkan dengan `connect devin --with-hooks` untuk capture sesi yang lengkap. |
| **Devin (cloud)** | Settings → Connections → MCP servers | Tambahkan MCP custom (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` mengarah ke deployment agentmemory yang terjangkau lewat network ditambah `AGENTMEMORY_SECRET` (sesi cloud tidak bisa menjangkau localhost — lihat [`deploy/`](../deploy/)). Simpan secret di Devin Secrets, lalu pakai "Test listing tools" untuk memverifikasi semua 54 tool muncul. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merge). |
| **GitHub Copilot CLI (MCP saja)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` menggabungkan `mcpServers.agentmemory`; Copilot mengambilnya pada peluncuran berikutnya atau `/mcp`. |
| **GitHub Copilot CLI (plugin lengkap)** | Instalasi plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` untuk plugin dari subdir GitHub. |
| **OpenClaw** | Konfigurasi MCP OpenClaw | Blok `mcpServers` yang sama. Lebih dalam: `openclaw plugins install ./integrations/openclaw` mengklaim slot memori OpenClaw (auto-switch dari `memory-core`); set `plugins.entries.agentmemory.hooks.allowConversationAccess=true` atau capture-nya akan diam-diam diblokir. Lihat [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (MCP saja)** | `.codex/config.toml` | Bentuk TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, atau tambahkan `[mcp_servers.agentmemory]` secara manual. |
| **Codex CLI (plugin lengkap)** | Marketplace plugin Codex | `codex plugin marketplace add rohitg00/agentmemory` lalu `codex plugin add agentmemory@agentmemory`. Mendaftarkan MCP + 6 hook lifecycle + 17 skill. Percayai (trust) hook dan verifikasi capture di host Anda; lihat [setup dan validasi Codex](../docs/plugins/codex-local.md). |
| **OpenCode (MCP saja)** | `opencode.json` | Bentuk berbeda: key top-level `mcp`, command sebagai array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (plugin lengkap)** | `plugin/opencode/` | 22 hook auto-capture mencakup lifecycle sesi, message, tool, error. Atribusi proyek bersifat per-sesi, sehingga satu proses OpenCode yang membentang beberapa repository mencatat setiap sesi di bawah proyeknya sendiri. Dua slash command (`/recall`, `/remember`). Salin `plugin/opencode/` ke workspace OpenCode Anda dan tambahkan entri plugin ke `opencode.json`. Lihat [`plugin/opencode/README.md`](../plugin/opencode/README.md) untuk tabel hook lengkap + analisis gap. |
| **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` memberikan memory provider 6-hook (prefetch, turn capture, session end, pre-compress, mirroring MEMORY.md, blok system prompt). Validasi dengan `hermes plugins doctor` dan `hermes memory status`. Lihat [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` menulis blok `mcpServers` standar. Payload hook kompatibel secara field dengan Claude Code, sehingga 12 script hook yang sudah ada bekerja tanpa modifikasi; sambungkan lewat bagian `hooks` di `settings.json` yang sama. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` memasang MCP dan hook capture di direktori kustomisasi bersama. Lihat [pengaturan dan batasan Antigravity](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` memakai konfigurasi MCP dan hook yang sama dengan versi IDE saat ini. Instalasi yang sudah ada sebaiknya di-refresh dengan `--force`; lihat [catatan upgrade](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` menulis konfigurasi tingkat pengguna. Override workspace masuk di `.kiro/settings/mcp.json` di sebelah kode Anda. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` menulis blok `mcpServers` standar. Warp juga auto-discover skill dari `.claude/skills/`; setelah plugin Claude Code terpasang, 9 skill agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) muncul secara native di palet slash-command Warp. |
| **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` menulis blok `mcpServers` standar. Pengguna ekstensi VS Code: tempel blok yang sama lewat Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (disarankan) atau `config.json` (legacy) | `agentmemory connect continue` membuat `config.yaml` jika belum ada konfigurasi atau memperbarui `config.json` yang ada. YAML yang sudah ada dipertahankan agar komentar dan anchor tetap utuh; perintah mencetak blok untuk ditempel di bawah `mcpServers:`. Continue memakai bentuk array untuk `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` menulis di bawah `context_servers` (key milik Zed, BUKAN `mcpServers`). Server MCP remote bisa disambungkan lewat `{"url": "..."}` sebagai gantinya. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` menulis blok `mcpServers` standar. Override berbasis proyek masuk di `/.factory/mcp.json`. Tambahkan `--with-hooks` untuk auto-capture native. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` mengaktifkan alat MCP. Tambahkan `--with-hooks` untuk memuat plugin perekaman native yang disertakan dalam AgentMemory. Tidak perlu paket plugin terpisah. [DSH](../docs/dsh.md). |
| **Goose** | Settings UI MCP Goose | Blok `mcpServers` yang sama; gunakan `goose configure` → Add Extension → MCP. Edit YAML langsung di `~/.config/goose/config.yaml` juga didukung tapi skemanya memakai `extensions:` + `cmd` (bukan `mcpServers:` + `command`). |
| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **Agen yang didukung** | Hanya skill | `npx skills add rohitg00/agentmemory`; pilih skill dan agen tujuan pemasangannya. |
**Klien MCP yang di-sandbox** (Flatpak / Snap / kontainer restriktif) yang tidak bisa menjangkau `localhost` milik host: set juga `"AGENTMEMORY_FORCE_PROXY": "1"` di blok `env`, dan arahkan `AGENTMEMORY_URL` ke rute yang benar-benar bisa dijangkau sandbox (misalnya IP LAN Anda).
### Akses programatik
Gunakan [REST API](#api) dari bahasa apa pun atau [alat MCP](#mcp-server) dari agen. REST memakai JSON dan autentikasi Bearer; lihat [contoh simpan dan cari](#validate-a-fresh-install-and-restart-persistence). Integrasi langsung dengan runtime tersedia dalam [contoh Python](../examples/python/).
### Dari source
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
`npm start` menjalankan server lokal yang sama dengan CLI terpasang. Persyaratan ada di [Instalasi](#install); API dan viewer memakai `127.0.0.1`.
### Windows
agentmemory berjalan di Windows 10/11. WSL2 mengikuti jalur Linux dan dapat memasang engine yang dipatok secara otomatis. Pada Windows native, pasang biner iii-engine v0.25.1 yang dipatok secara manual: unduh arsip yang sesuai dari [halaman rilis iii v0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), verifikasi checksum, lalu letakkan `iii.exe` di `PATH` (misalnya `%USERPROFILE%\.local\bin\iii.exe`). CLI tidak mengekstrak ZIP Windows secara otomatis.
Wiring MCP otomatis di Windows native hanya mendukung `agentmemory connect copilot-cli`. Untuk agen Windows native lainnya, gunakan blok MCP manual dari [Agen lainnya](#other-agents). Jalankan `connect` di WSL hanya jika agen target juga dipasang di lingkungan WSL yang sama.
**MCP mandiri saja (tanpa engine).** Jika hanya memerlukan tool MCP dan tidak memerlukan REST API, viewer, atau layanan runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
```
Jalankan `agentmemory doctor` atau restart dengan `--verbose`. Jika port default terpakai, gunakan `--port ` atau `--instance `. Lihat [panduan upgrade](../docs/upgrades/iii-0.25.md) untuk kompatibilitas dan pemulihan.
---
Deploy
Host sendiri dengan Docker Compose atau templat platform di bawah. Memori dan kredensial tersimpan pada volume `/data`. Cadangkan dan gunakan kembali volume tersebut saat upgrade. Lihat [panduan deployment](../deploy/README.md) untuk autentikasi, jaringan, dan migrasi.
Tombol deploy satu klik milik Render membutuhkan `render.yaml` di root repository, yang dengan sengaja kami biarkan bersih. Gunakan flow Render Blueprint yang didokumentasikan di [`deploy/render/`](.././deploy/render/README.md) untuk mengarah ke blueprint in-repo secara manual.
Detail setup lengkap (capture HMAC, SSH tunnel viewer, rotasi, backup,
batas bawah biaya) ada di [`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): satu machine dengan
`auto_stop_machines = "stop"`; paling murah saat idle.
- [`deploy/railway`](.././deploy/railway/README.md): biaya flat plan Hobby,
volume di dashboard.
- [`deploy/render`](.././deploy/render/README.md): flow Blueprint,
snapshot disk otomatis di plan berbayar.
- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted di
VPS Anda sendiri lewat [Coolify](https://coolify.io/self-hosted); stack Docker
Compose yang sama, Anda memiliki host dan datanya.
REST memakai port `3111`; viewer memakai `3113`. Pertahankan akses privat atau lindungi dengan autentikasi dan TLS. Pengaturan akses tiap platform dan [migrasi Docker lama](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ada di panduan deployment.
---
Pengetahuan proyek sering tersebar di percakapan dan file instruksi. AgentMemory membuat keputusan, perbaikan, dan pelajaran terdahulu bisa dicari dari agen yang sedang Anda gunakan.
```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.
```
### vs memori bawaan agen
Setiap agen coding AI dilengkapi memori bawaan: Claude Code punya `MEMORY.md`, Cursor punya notepad, Cline punya memory bank. Ini bekerja seperti sticky note. agentmemory adalah database yang bisa dicari di balik sticky note itu.
| | Bawaan (CLAUDE.md) | agentmemory |
|---|---|---|
| Pemeliharaan | Instruksi yang dikelola manual | Riwayat sesi dan memori terindeks |
| Search | Memuat semuanya ke konteks | BM25 + vector + graph (hanya top-K) |
| Lintas agen | File per agen | MCP + REST (agen apa pun) |
| Koordinasi | Tidak ada | Lease, signal, action, routine |
| Observability | Baca file secara manual | Viewer real-time di :3113 |
---
### Pipeline Memori
```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
```
### Konsolidasi Memori 4-Tier
Dimodelkan dari cara otak manusia memproses memori, termasuk konsolidasi saat tidur.
| Tier | Apa | Analogi |
|------|------|---------|
| **Working** | Observasi mentah dari pemakaian tool | Memori jangka pendek |
| **Episodic** | Ringkasan sesi yang dikompres | "Apa yang terjadi" |
| **Semantic** | Fakta dan pola yang diekstraksi | "Apa yang saya tahu" |
| **Procedural** | Workflow dan pola keputusan | "Bagaimana melakukannya" |
Memori meluruh (decay) dari waktu ke waktu (kurva Ebbinghaus). Memori yang sering diakses menguat. Memori yang basi otomatis dievict. Kontradiksi dideteksi dan diselesaikan.
### Apa yang Ditangkap
Tabel berikut menjelaskan hook Claude Code. Integrasi lain merekam event yang disediakan host masing-masing. Injeksi konteks otomatis melalui hook bersama bersifat opt-in dengan `AGENTMEMORY_INJECT_CONTEXT=true`.
| Hook | Menangkap |
|------|----------|
| `SessionStart` | Path proyek, ID sesi |
| `UserPromptSubmit` | Prompt pengguna (disaring privasinya) |
| `PreToolUse` | Pola akses file + konteks yang diperkaya |
| `PostToolUse` | Nama tool, input, output |
| `PostToolUseFailure` | Konteks error |
| `PreCompact` | Menyuntikkan ulang memori sebelum compaction |
| `SubagentStart/Stop` | Lifecycle sub-agen |
| `Stop` | Ringkasan akhir sesi |
| `SessionEnd` | Marker sesi selesai |
### Kemampuan Utama
| Kemampuan | Deskripsi |
|---|---|
| **Capture otomatis** | Event sesi dan alat yang didukung direkam oleh integrasi native |
| **Semantic search** | BM25 + vector + knowledge graph dengan fusi RRF |
| **Evolusi memori** | Versioning, supersession, graph relasi |
| **Kebersihan recall** | Versi memori yang disupersede keluar dari index pencarian; rantai versi di KV menyimpan histori lengkap |
| **Petunjuk near-duplicate** | Saat menyimpan, muncul kecocokan advisory `similarTo` ketika konten baru sangat menyerupai memori yang sudah ada |
| **Scoping per agen** | `agentId` mengalir lewat save dan recall di REST, MCP, dan index pencarian, dalam mode shared atau isolated |
| **Provenance saat penulisan** | Setiap observasi dan memori membawa channel asal yang tak berubah (user, agent, tool, import, atau shared) yang dicap saat capture, save, dan import |
| **Auto-forgetting** | Kedaluwarsa TTL, deteksi kontradiksi, eviction berdasarkan importance |
| **Privacy first** | API key, secret, tag `` dihapus sebelum disimpan |
| **Self-healing** | Circuit breaker, rantai fallback provider, health monitoring |
| **Claude bridge** | Sinkronisasi dua arah dengan MEMORY.md |
| **Knowledge graph** | Ekstraksi entitas + traversal BFS |
| **Memori tim** | Namespace shared + private di antar anggota tim |
| **Citation provenance** | Lacak memori apa pun kembali ke observasi sumbernya |
| **Snapshot Git** | Versi, rollback, dan diff state memori |
---
Retrieval triple-stream yang mengombinasikan tiga sinyal:
| Stream | Yang dilakukan | Kapan |
|---|---|---|
| **BM25** | Pencocokan kata kunci yang di-stem dengan ekspansi sinonim | Selalu aktif |
| **Vector** | Cosine similarity pada dense embedding | Penyedia embedding dikonfigurasi |
| **Graph** | Traversal knowledge graph lewat pencocokan entitas | Entitas terdeteksi di query |
Difusikan dengan Reciprocal Rank Fusion (RRF, k=60) dan didiversifikasi per sesi (maksimum 3 hasil per sesi).
Saat index vector terisi, `mem::search` (di belakang `memory_recall`) memakai ranker hybrid BM25 + vector. Tanpa embedding ia memakai BM25. `smart-search` juga bisa menggabungkan kecocokan graph struktural saat data graph ada, termasuk di mode keyless. Recall lesson berjalan di index BM25 in-memory khusus bukan memindai seluruh korpus per query. Versi memori yang disupersede dikecualikan dari setiap jalur recall; rantai versi menyimpan histori mereka.
[0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md).
BM25 men-tokenisasi Yunani, Sirilik, Ibrani, Arab, dan Latin beraksen secara bawaan. Untuk memori Tionghoa / Jepang / Korea, pasang segmenter opsional (`npm install @node-rs/jieba tiny-segmenter`) untuk membelah runtun CJK menjadi token level-kata; tanpa itu, agentmemory soft-fallback ke tokenisasi seluruh runtun dan mencetak hint satu-kali di stderr.
### Penyedia embedding
Instalasi keyless menonaktifkan vector embedding: `mem::search` memakai BM25, sementara `smart-search` juga bisa memakai data graph struktural yang sudah ada. Untuk opt-in ke embedding semantik gratis di perangkat sendiri, tambahkan ini ke `~/.agentmemory/.env` dan restart agentmemory:
```env
EMBEDDING_PROVIDER=local
```
Instalasi npm normal menyertakan runtime opsional `@huggingface/transformers`. Permintaan embedding pertama mengunduh `Xenova/all-MiniLM-L6-v2`, sehingga membutuhkan akses network dan bisa lebih lama; inferensi berikutnya berjalan di perangkat sendiri. Penyedia remote terdeteksi otomatis dari key-nya kecuali `EMBEDDING_PROVIDER` meng-override-nya.
| Penyedia | Model | Biaya | Catatan |
|---|---|---|---|
| **Lokal (opt-in yang disarankan)** | `all-MiniLM-L6-v2` | Gratis | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) |
| Gemini | `gemini-embedding-001` | Free tier | 100+ bahasa, 768/1536/3072 dimensi (MRL), input 2048-token. Menggantikan `text-embedding-004` ([deprecated, shutdown 14 Jan 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` | Berbayar | Dioptimalkan untuk code |
| Cohere | `embed-english-v3.0` | Free trial | Tujuan umum |
| OpenRouter | Model apa pun | Bervariasi | Proxy multi-model |
---
54 tool, 6 resource, 3 prompt, dan 17 skill.
> **Shim MCP vs server lengkap:** paket `@agentmemory/mcp` yang dipublikasikan adalah shim tipis. Ia menampilkan permukaan 54-tool lengkap **hanya saat bisa menjangkau server agentmemory yang berjalan** lewat `AGENTMEMORY_URL` (mode proxy). Tanpa server yang terjangkau, shim ini fallback ke set 7-tool lokal (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Env var `AGENTMEMORY_TOOLS=core|all` adalah flag *sisi server*; mengesetnya di blok `env` shim tidak berefek. Jika Anda hanya melihat 7 tool di Cursor / OpenCode / Gemini CLI, jalankan `npx -y @agentmemory/agentmemory@latest` (atau stack Docker) dan set `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tool
Tiga permukaan tool, dari terkecil ke terbesar: `AGENTMEMORY_TOOLS=core` memangkas visibilitas menjadi 8 tool esensial (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); set dasar di bawah adalah 14 tool fundamental milik registry; default (`AGENTMEMORY_TOOLS=all`) menampilkan semua 54.
Tool dasar (14)
| Tool | Deskripsi |
|------|-------------|
| `memory_recall` | Mencari observasi lampau |
| `memory_compress_file` | Mengompres file markdown sambil mempertahankan struktur |
| `memory_save` | Menyimpan insight, keputusan, atau pola |
| `memory_file_history` | Observasi lampau tentang file tertentu |
| `memory_patterns` | Mendeteksi pola berulang |
| `memory_sessions` | Mendaftar sesi terbaru |
| `memory_smart_search` | Search hybrid semantik + kata kunci |
| `memory_vision_search` | Mencari observasi gambar |
| `memory_timeline` | Observasi kronologis |
| `memory_profile` | Profil proyek (konsep, file, pola) |
| `memory_export` | Mengekspor semua data memori |
| `memory_relations` | Query graph relasi |
| `memory_commit_lookup` | Sesi di balik sebuah commit git |
| `memory_commits` | Commit yang tercatat untuk sebuah sesi |
Tool extended (54 total, permukaan default)
| Tool | Deskripsi |
|------|-------------|
| `memory_patterns` | Mendeteksi pola berulang |
| `memory_timeline` | Observasi kronologis |
| `memory_relations` | Query graph relasi |
| `memory_graph_query` | Traversal knowledge graph |
| `memory_consolidate` | Menjalankan konsolidasi 4-tier |
| `memory_claude_bridge_sync` | Sinkronisasi dengan MEMORY.md |
| `memory_team_share` | Berbagi dengan anggota tim |
| `memory_team_feed` | Item terbaru yang dibagikan |
| `memory_audit` | Audit trail operasi |
| `memory_governance_delete` | Menghapus dengan audit trail |
| `memory_snapshot_create` | Snapshot bervesi-Git |
| `memory_action_create` | Membuat work item dengan dependensi |
| `memory_action_update` | Memperbarui status action |
| `memory_frontier` | Action yang tidak terblokir, diurutkan berdasar prioritas |
| `memory_next` | Satu action berikutnya yang paling penting |
| `memory_lease` | Lease action eksklusif (multi-agen) |
| `memory_routine_run` | Menjalankan routine workflow |
| `memory_signal_send` | Pesan antar-agen |
| `memory_signal_read` | Membaca pesan dengan receipt |
| `memory_checkpoint` | Gate kondisi eksternal |
| `memory_mesh_sync` | Sinkronisasi P2P antar instance |
| `memory_sentinel_create` | Watcher berbasis event |
| `memory_sentinel_trigger` | Memicu sentinel dari luar |
| `memory_sketch_create` | Graph action yang efemeral |
| `memory_sketch_promote` | Mempromosikan jadi permanen |
| `memory_crystallize` | Memadatkan rantai action |
| `memory_diagnose` | Health check |
| `memory_heal` | Auto-fix state yang stuck |
| `memory_facet_tag` | Tag dimension:value |
| `memory_facet_query` | Query berdasarkan facet tag |
| `memory_verify` | Melacak provenance |
### 6 Resource · 3 Prompt · 17 Skill
| Tipe | Nama | Deskripsi |
|------|------|-------------|
| Resource | `agentmemory://status` | Health, jumlah sesi, jumlah memori |
| Resource | `agentmemory://project/{name}/profile` | Intelijen per proyek |
| Resource | `agentmemory://project/{name}/recent` | Observasi terbaru untuk sebuah proyek |
| Resource | `agentmemory://memories/latest` | 10 memori aktif terbaru |
| Resource | `agentmemory://graph/stats` | Statistik knowledge graph |
| Resource | `agentmemory://team/{id}/profile` | Profil tim yang dibagikan |
| Prompt | `recall_context` | Mencari + mengembalikan message konteks |
| Prompt | `session_handoff` | Data handoff antar agen |
| Prompt | `detect_patterns` | Menganalisis pola berulang |
| Skill | `/recall` | Mencari memori |
| Skill | `/remember` | Menyimpan ke memori jangka panjang |
| Skill | `/session-history` | Ringkasan sesi terbaru |
| Skill | `/forget` | Menghapus observasi/sesi |
Tabel ini menampilkan empat skill inti. Set lengkapnya adalah 9 skill yang bisa dipanggil ditambah 8 skill referensi; lihat bagian Native skills di atas.
### MCP Standalone
Jalankan tanpa server lengkap, untuk klien MCP apa pun. Salah satu dari ini berfungsi:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Atau tambahkan ke konfigurasi MCP agen Anda:
Kebanyakan agen (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
Gabungkan entri `agentmemory` ke objek `mcpServers` yang sudah ada di host Anda, bukan menggantikan filenya. Untuk klien yang di-sandbox dan tidak bisa menjangkau `localhost` milik host, tambahkan `"AGENTMEMORY_FORCE_PROXY": "1"` ke blok env dan set `AGENTMEMORY_URL` ke rute yang bisa dijangkau sandbox.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Salin file plugin dari 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 otomatis mulai pada port `3113`. Saat tersambung, viewer memuat satu snapshot (`GET /agentmemory/viewer/snapshot`), lalu menerapkan event langsung melalui SSE pada `/agentmemory/viewer/events` di worker REST: memori, lesson, observasi, entri audit, perubahan graph, dan pembaruan health tampil tanpa polling atau memuat ulang halaman.
- **12 tab dalam empat grup** dengan hitungan live, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), shortcut keyboard, dan menu mobile.
- **Memories:** search sisi server, filter berdasarkan proyek, agen, dan tipe, panel detail dengan rantai versi dan word diff, link provenance, tombol copy untuk id, panggilan MCP, dan perintah curl, edit (versi baru), forget dengan konfirmasi, bulk forget, dan ekspor JSON.
- **Sessions:** timeline observasi inline dengan input dan output tool yang mudah dibaca, filter dan paging, serta memori dan lesson yang dihasilkan setiap sesi.
- **Graph:** search, detail node dengan relasi dan sumber, legenda yang tidak hanya mengandalkan warna, dan kontrol zoom.
- **Health:** versi live dari `GET /agentmemory/status`. Setiap masalah disertai perbaikannya, plus backend state, status penyimpanan index, progres kompaksi graph provenance, dan penjelas konsolidasi dengan threshold yang sesungguhnya.
- Halaman **Audit, Activity, Profile, Replay, Lessons, Actions, dan Crystals**, masing-masing dengan empty state yang menjelaskan apa bagian itu, mengapa kosong, dan perintah yang mengisinya, serta tooltip glosarium `?` di setiap istilah dan angka.
```bash
open http://localhost:3113
```
Server viewer terbind ke `127.0.0.1` secara default dan melampirkan secret server saat meneruskan permintaan ke REST API, sehingga tidak butuh setup. Endpoint `/agentmemory/viewer` yang disajikan REST mengikuti aturan bearer-token normal dan mengarahkan browser tanpa token ke port viewer. Header CSP memakai script nonce per-respons dan menonaktifkan atribut inline handler (`script-src-attr 'none'`).
---
### Penyedia LLM
agentmemory mendeteksi otomatis penyedia dari environment Anda. Penyedia membuat operasi berbasis LLM tersedia, tapi konfigurasi penyedia saja tidak mengaktifkan kompresi observasi yang ditulis LLM. Jalur itu membutuhkan baik penyedia maupun `AGENTMEMORY_AUTO_COMPRESS=true`.
| Penyedia | Konfigurasi | Catatan |
|----------|--------|-------|
| **No-op (default)** | Tidak perlu konfigurasi | Compress/summarize berbasis LLM dinonaktifkan. Kompresi sintetis dan recall BM25 tetap bekerja. Lihat `AGENTMEMORY_ALLOW_AGENT_SDK` di bawah jika Anda dulu mengandalkan fallback subscription Claude. |
| Anthropic API | `ANTHROPIC_API_KEY` | Billing per-token |
| MiniMax | `MINIMAX_API_KEY` | Kompatibel Anthropic |
| Gemini | `GEMINI_API_KEY` | Juga mengaktifkan embedding |
| OpenRouter | `OPENROUTER_API_KEY` | Model apa pun |
| OpenAI API | `OPENAI_API_KEY` | Default `gpt-5.6-luna`, override dengan `OPENAI_MODEL` |
| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) atau `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Apa pun yang kompatibel OpenAI-API. Biaya nol, berjalan di hardware Anda. Lihat [Model lokal](#local-models-ollama--lm-studio--vllm) di bawah. |
| Fallback subscription Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Hanya opt-in. Memunculkan sesi `@anthropic-ai/claude-agent-sdk`; dulu bisa menyebabkan rekursi Stop-hook tanpa batas, sehingga tidak lagi jadi default. |
### Model lokal (Ollama / LM Studio / vLLM)
agentmemory berbicara dengan server yang kompatibel OpenAI-API apa pun, sehingga apa pun yang mengekspos `/v1/chat/completions` bekerja tanpa perubahan kode. Tanpa key berbayar, tanpa cloud, tanpa rate limit; berjalan sepenuhnya di hardware Anda.
**Ollama** (port default `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 default `1234`):
Buka LM Studio → tab Local Server → Start Server. Pilih model chat apa pun dari picker-nya (Qwen 3, gpt-oss, DeepSeek R1, dll).
```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**: bentuk yang sama. Arahkan `OPENAI_BASE_URL` ke URL apa pun yang diekspos server Anda dan set `OPENAI_MODEL` ke nama yang akan diterima server Anda.
**Pilihan model untuk kerja memori**: kompresi dan summarization adalah task singkat (<2K token masuk, <500 token keluar) di mana model instruct 7B sudah lebih dari cukup. Rekomendasi:
| Model | Ukuran | Alasan |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | Default seimbang di mesin 16 GB; kuat untuk ekstraksi dan teks berbentuk tool |
| `qwen3:4b` | ~2.6 GB | Opsi paling kecil yang masih wajar; cocok untuk kompresi, lebih lemah untuk ekstraksi graph |
| `qwen3-coder:30b` | ~19 GB | Pilihan lokal terbaik untuk sesi berbentuk code (30B MoE, 3.3B active) di hardware 24-32 GB |
| `gpt-oss:20b` | ~14 GB | Model umum yang kuat dan cukup untuk RAM 16 GB |
| `deepseek-r1:8b` | ~5.2 GB | Distilasi reasoning; lebih lambat tapi ekstraksinya lebih bersih |
Model Qwen 3 berpikir secara default dan bisa menghabiskan seluruh budget token untuk reasoning sebelum ada output. Set `AGENTMEMORY_LLM_NOTHINK=1` untuk menambahkan `/no_think` ke prompt ekstraksi graph, dan naikkan `MAX_TOKENS` (16384 cukup) jika ekstraksi kembali kosong.
Model reasoning-class (bergaya `o1` dengan blok ``) bisa mengembalikan `content` kosong dengan field `reasoning` yang server lokal Anda mungkin tidak munculkan. Jika ekstraksi kembali kosong, ganti ke model non-reasoning dulu. Env `OPENAI_REASONING_EFFORT=none` juga bisa menonaktifkan thinking pada model thinking Ollama Cloud yang mencerminkan skema reasoning OpenAI.
Embedding lokal dikirim sebagai dependensi opsional tapi tidak aktif secara default. Set `EMBEDDING_PROVIDER=local` untuk opt-in ke `Xenova/all-MiniLM-L6-v2` (384-dim). Permintaan embedding pertama mengunduh modelnya; inferensi berikutnya di perangkat sendiri. Tanpa setelan itu atau key embedding remote, vector tetap nonaktif, `mem::search` memakai BM25, dan `smart-search` tetap bisa menambahkan kecocokan graph yang sudah ada.
### Pemilihan model yang sadar biaya
Mulai tanpa kunci untuk capture dan pencarian kata kunci. `EMBEDDING_PROVIDER=local` menyediakan pencarian semantik di perangkat setelah unduhan model pertama. Kompresi LLM memerlukan penyedia dan `AGENTMEMORY_AUTO_COMPRESS=true`, dan dapat membuat permintaan untuk setiap observasi; periksa harga penyedia saat ini.
`agentmemory status` / http://localhost:3113
### Memori multi-agen (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
Pada setup multi-agen di mana beberapa role berbagi satu server agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` menandai setiap penulisan dengan role yang membuatnya. `AGENTMEMORY_AGENT_SCOPE` mengontrol apakah recall memfilter berdasarkan tag itu.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
Dua mode:
| Mode | Tag penulisan | Filter recall | Kapan dipakai |
|------|------------|---------------|-------------|
| `shared` (default) | ya | tidak | Konteks lintas-agen dengan audit trail. Architect bisa melihat apa yang dicatat developer, tapi setiap baris mencatat siapa yang mengatakannya. |
| `isolated` | ya | ya | Pemisahan ketat. Architect tidak pernah melihat observasi / memori / sesi milik developer. |
Apa yang ditandai saat `AGENT_ID` diset: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Role-nya mengalir dari `api::session::start` → `mem::observe` → `mem::compress` → KV.
Apa yang difilter di mode isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Setiap endpoint menerima `?agentId=` untuk override per-permintaan, dan `?agentId=*` untuk keluar dari scope env sepenuhnya. `/memories` juga menerima `?includeOrphans=true` untuk menampilkan memori pra-AGENT_ID yang `agentId`-nya tidak terdefinisi.
Override per-panggilan di layer SDK / REST: setiap endpoint yang mengubah data (`/session/start`, `/remember`) menerima field `agentId` di body permintaan yang menang di atas env. Berguna untuk runtime yang merutekan banyak role lewat satu proses server. Tool MCP `memory_save` mengekspos field `agentId` yang sama, server stdio standalone meneruskan baik `agentId` maupun `project`, dan memori yang disimpan membawa `agentId` ke index pencarian, sehingga pencarian yang di-scope agen mencakup memori selain observasi.
Saat `AGENT_ID` tidak diset, memori tetap unscoped (perilaku legacy, tanpa tag, tanpa filter).
### Port
API dan viewer memakai loopback secara default.
| Port | API / Viewer | Env |
|---|---|---|
| `3111` | REST / MCP / SSE | `III_REST_PORT` |
| `3113` | Viewer | `III_VIEWER_PORT` |
`--port ` menentukan port API; viewer memakai `N+2` secara default. Gunakan `--instance N` untuk instance terpisah. Listener internal harus tetap privat. Ikuti panduan deployment untuk akses jarak jauh dan [migrasi Docker lama](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
### Backend penyimpanan: file (default) vs Redis
Tidak memerlukan layanan database terpisah. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. Mengganti backend tidak menyalin memori yang sudah ada secara otomatis. [Penyimpanan data](../docs/reliability/state-storage.md).
### File Konfigurasi
Letakkan konfigurasi runtime agentmemory di `~/.agentmemory/.env`, alih-alih mengekspor variabel di setiap shell. Jika viewer menampilkan petunjuk seperti `export ANTHROPIC_API_KEY=...`, salin ke file tanpa awalan `export`, lalu restart agentmemory. Set `AGENTMEMORY_ENV_FILE` untuk menggunakan path file env lain.
Variabel environment proses tetap berfungsi dan diprioritaskan di atas nilai di file itu.
Di Windows, file yang sama ada di `%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
Untuk mencoba dengan subscription Claude Code Pro/Max dibanding API key, opt-in secara eksplisit:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
Kompresi observasi yang ditulis LLM membutuhkan kedua baris itu: akses ke penyedia LLM (termasuk fallback subscription eksplisit ini) dan `AGENTMEMORY_AUTO_COMPRESS=true`. Penyedia saja membiarkan jalur kompresi sintetis default tetap berlaku.
Konsolidasi (node graph, lesson, crystal) aktif secara default kapan pun penyedia LLM dikonfigurasi. Opt-out secara eksplisit dengan `CONSOLIDATION_ENABLED=false` jika Anda ingin operasi tanpa LLM. Ekstraksi graph adalah flag terpisah:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Variabel Environment
`~/.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
```
Referensi lengkap ada di [`.env.example`](../.env.example), termasuk penyedia, filter capture, retensi, penyimpanan, dan lingkup tim. `AGENTMEMORY_ENV_FILE` memilih file lain. Restart setelah mengubah konfigurasi. Jangan commit `.env` yang berisi nilai nyata atau rahasia Bearer.
---
147 endpoint di port `3111`. REST API terbind ke `127.0.0.1` secara default. Endpoint yang terlindungi membutuhkan `Authorization: Bearer `, dan endpoint mesh sync membutuhkan `AGENTMEMORY_SECRET` yang diset secara eksplisit di kedua peer.
Autentikasi aktif secara default. Jika `AGENTMEMORY_SECRET` tidak disetel, CLI membuat rahasia acak saat pertama dijalankan di `~/.agentmemory/secret` dan menyalinnya ke `secret` dalam direktori data terpilih, dengan mode `0600`. Klien bawaan mengutamakan file kanonis ini untuk koneksi lokal dan hanya mengirim rahasia tersimpan ke URL loopback. `AGENTMEMORY_SECRET` eksplisit selalu diutamakan; klien remote harus mengaturnya melalui environment. Deployment Docker membuat rahasianya sendiri.
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**Aturan permintaan untuk penulisan.** Permintaan `POST`, `PUT`, `PATCH`, dan `DELETE` ke REST API dan viewer harus mengirim `Content-Type: application/json` (parameter `charset` boleh) kapan pun mereka membawa body, dan header `Origin`, jika ada, harus berupa origin loopback untuk port REST atau viewer yang dikonfigurasi, atau terdaftar di `VIEWER_ALLOWED_ORIGINS` (dipisah koma, misalnya `https://memory.example.com`). Klien yang tidak mengirim header `Origin` (CLI, hook, MCP, curl, server-ke-server) tidak terpengaruh. Viewer juga menerima origin-nya sendiri.
**Path file.** Endpoint yang membaca atau menulis file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) hanya menerima path di bawah `~/.agentmemory`, direktori data instance, atau direktori yang terdaftar di `AGENTMEMORY_IMPORT_ROOT` (pisahkan beberapa dengan `:`, atau `;` di Windows). `/replay/import-jsonl` juga menerima default-nya `~/.claude/projects`. `/obsidian/export` tetap di dalam `AGENTMEMORY_EXPORT_ROOT` dan `/migrate` di dalam `~/.agentmemory`. Symlink diresolusi sebelum setiap pengecekan.
**Scrubbing secret.** API key, bearer token, blok PEM private key, dan credential yang tertanam di URL (`scheme://user:password@host`) disamarkan sebelum teks disimpan, pada setiap jalur penulisan: observation, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, replay jsonl, mesh sync, team share, output kompresi dan summary, crystal, dan node graph.
Endpoint utama
| Method | Path | Deskripsi |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check (selalu publik) |
| `GET` | `/agentmemory/status` | Apa yang salah dan cara memperbaikinya (HTML untuk browser, JSON lainnya) |
| `GET` | `/agentmemory/viewer/snapshot` | Semua yang ditampilkan viewer, dalam satu respons |
| `POST` | `/agentmemory/session/start` | Mulai sesi + dapatkan konteks |
| `POST` | `/agentmemory/session/end` | Akhiri sesi |
| `POST` | `/agentmemory/observe` | Menangkap observasi (lihat capture delivery di bawah) |
| `GET` | `/agentmemory/capture` | Inbox capture, dead letter, dan spool offline |
| `POST` | `/agentmemory/capture/retry` | Retry capture dead-letter |
| `POST` | `/agentmemory/capture/drain` | Kirim spool offline lokal sekarang |
| `POST` | `/agentmemory/smart-search` | Search hybrid |
| `POST` | `/agentmemory/context` | Membuat konteks |
| `POST` | `/agentmemory/remember` | Simpan ke memori jangka panjang |
| `POST` | `/agentmemory/forget` | Hapus observasi |
| `POST` | `/agentmemory/enrich` | Konteks file + memori + bug |
| `GET` | `/agentmemory/profile` | Profil proyek |
| `GET` | `/agentmemory/export` | Ekspor semua data |
| `POST` | `/agentmemory/import` | Import dari JSON |
| `POST` | `/agentmemory/graph/query` | Query knowledge graph |
| `POST` | `/agentmemory/graph/compact` | Memangkas provenance graph yang berlebihan ukuran |
| `POST` | `/agentmemory/team/share` | Bagikan ke tim |
| `GET` | `/agentmemory/audit` | Audit trail |
Daftar endpoint lengkap: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Pengiriman capture.** Hook mengirim setiap observasi sekali ke `POST /agentmemory/observe` dengan sebuah `eventId`. Ini adalah id milik host sendiri untuk panggilan itu saat payload-nya punya satu (misalnya `tool_use_id` milik Claude Code), atau hash dari sesi, tipe hook, nama tool, input, output, dan timestamp host jika tidak. Server menulis event itu ke inbox capture di state store, menyimpan observasinya, lalu menghapus entri inbox-nya. Status code-nya memberitahu apa yang terjadi:
| Status | Field `status` | Makna |
|---|---|---|
| `201` | `accepted` | Tersimpan. `observationId` adalah observasi baru itu. |
| `202` | `accepted` (`state: "retrying"`) | Diterima, tapi penyimpanannya gagal. Server me-retry-nya, juga setelah restart. |
| `200` | `duplicate` | `eventId` ini sudah diterima sebelumnya. `observationId` adalah observasi yang sudah ada; tidak ada yang baru disimpan. |
| `400` / `422` | `rejected` | Payload tidak valid, atau penyimpanannya gagal permanen (event disimpan sebagai dead letter). |
| `503` | `rejected` (`retryable: true`) | Inbox penuh (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook men-spool event itu dan mengirimnya nanti. |
Event yang gagal di-retry setiap `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 d) dengan backoff yang berlipat ganda, hingga `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Event yang masih gagal tetap di inbox sebagai dead letter, terdaftar di `/agentmemory/status` dan halaman Health viewer, dan bisa di-retry dengan `POST /agentmemory/capture/retry` (`{"eventId": "..."}` atau `{"all": true}`). Id event yang diterima diingat selama `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 jam, paling banyak `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), sehingga hook yang di-replay setelah timeout atau restart disimpan sekali, sementara dua tool call terpisah dengan id host masing-masing disimpan dua kali meski kontennya identik. Saat sebuah observasi dihapus (forget, delete sesi, eviction, auto-forget, atau import yang mengganti store), event-nya ditandai terhapus sebelum observasinya dihapus, sehingga replay event itu dalam window yang sama dijawab sebagai duplicate dan tidak menyimpan apa pun. State store menulis ke disk setiap 2 detik, sehingga event yang sudah dijawab bisa saja masih hanya ada di memori untuk sesaat. Untuk mengatasi itu, setiap jawaban `2xx` juga membawa `bootId` server (baru di setiap start), `acceptedAt`, dan `durableAfterMs` (interval save ditambah 1.5 d di file store, 1.5 d di redis, di mana persistensi adalah setelan operator). Hook menyimpan event itu di spool lokal sampai window itu berlalu dan menghapusnya pada panggilan berikutnya tanpa permintaan lain. Jika `bootId` sudah berubah pada saat itu, server telah restart, sehingga hook mengirim event itu lagi dengan `eventId` yang sama; event yang memang sudah mencapai disk tidak disimpan dua kali. Server juga mengirim event semacam itu sendiri saat start dan setiap interval retry, sehingga restart tidak kehilangan apa pun bahkan saat tidak ada hook yang berjalan setelahnya. Hook lama mengabaikan field tambahan itu, dan hook baru terhadap server lama membuang event itu pada `2xx` seperti sebelumnya.
Saat server mati, tidak menjawab tepat waktu, atau mengembalikan 5xx, hook menambahkan observasi itu ke file spool lokal, `/capture-spool/-.jsonl` (ganti foldernya dengan `AGENTMEMORY_CAPTURE_SPOOL_DIR`). File itu privat untuk user Anda (mode 600), secret disamarkan dengan cara yang sama seperti server menyamarkannya, ia menampung paling banyak `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) dan membuang entri yang lebih tua dari `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Saat penuh, entri baru dibuang dan dihitung, dan `/agentmemory/status` melaporkannya. Hook tetap exit 0 dalam batas waktunya dan tidak menambah permintaan saat server sehat. Spool-nya dikirim pada start berikutnya dan oleh hook pertama yang menjangkau server lagi, dalam proses background sehingga agen tidak menunggu. Id event membuat ini aman: observasi yang memang tiba sebelum timeout tidak disimpan dua kali. `npx @agentmemory/agentmemory capture` menunjukkan spool dan inbox server, `--drain` mengirim spool itu sekarang, dan `GET /agentmemory/capture` mengembalikan hal yang sama sebagai JSON. Set `AGENTMEMORY_CAPTURE_SPOOL=false` untuk mematikan spool-nya.
**Memadatkan provenance graph.** Pemadatan provenance lama ditunda saat startup karena membaca seluruh scope lama. `/agentmemory/status` melaporkan `deferred`, atau `off` dengan `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Jalankan pemadatan manual di bawah saat pemeliharaan. Migrasi indeks pencarian terpisah: gunakan `agentmemory graph-index migrate --allow-legacy-scan` sesuai [panduan pemeliharaan](../docs/reliability/graph-index-migration.md).
Untuk menjalankannya secara manual, panggil `POST /agentmemory/graph/compact`. Ia menjelajahi index nama dan edge-key bukan mendaftar setiap node dan edge, dan aman untuk dijalankan ulang. Saat memangkas id, ia menulis entri audit `graph_compact`.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}'
```
Pada store yang besar, atau saat panggilannya mengembalikan 504, jalankan dalam potongan. Kirim `scope` (`nodes`, `edges`, atau `history`), `offset`, dan `limit`, lalu panggil lagi dengan `nextOffset` yang dikembalikan sampai nilainya `null`. Lakukan ini untuk `nodes`, `edges`, dan `history`, dan selesaikan dengan satu panggilan `{"scope":"snapshot"}`, karena run yang terpotong tidak menyentuh snapshot yang di-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"}'
```
---
```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)
```
Lihat [Instalasi](#install) untuk persyaratan serta [CONTRIBUTING.md](../CONTRIBUTING.md) untuk aturan kontribusi dan pemeriksaan rilis.