Agen coding Anda mengingat segalanya. Tidak perlu menjelaskan ulang.
Dibangun di atas iii engine
Memori persisten untuk Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, 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.
---
## Instalasi
Persyaratan:
- Node.js 20 atau lebih baru dengan npm dan npx (`node -v`, `npm -v`, dan `npx -v`).
- Instalasi otomatis iii-engine di macOS/Linux juga membutuhkan `curl`, `sh` POSIX, dan `tar`. Image minimal seperti `node:20-slim` mungkin tidak menyertakannya.
- Windows native membutuhkan `iii.exe` iii-engine v0.22.1 yang dipin untuk dipasang secara manual. WSL2 atau Docker Desktop adalah jalur lain yang didukung.
Perintah instalasi awal yang baku:
```bash
npx -y @agentmemory/agentmemory@latest
```
Jalankan pertama adalah setup interaktif: pilih agen yang ingin disambungkan (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pilih penyedia LLM atau tetap tanpa kunci (keyless), lalu agentmemory menyiapkan konfigurasi, menjalankan server memori beserta iii engine yang dipin, dan menawarkan instalasi global agar perintah polos `agentmemory` berfungsi di mana saja setelahnya. `-y` menerima prompt paket dari npx dan `@latest` menghindari rilis cache yang basi. Penyedia LLM membuat fitur LLM tersedia, tetapi kompresi observasi yang ditulis LLM baru dimulai saat `AGENTMEMORY_AUTO_COMPRESS=true` juga diset.
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.
Runtime lokal memakai empat port: `3111` untuk REST/MCP HTTP, `3112` untuk stream iii, `3113` untuk viewer, dan `49134` untuk WebSocket worker iii. State iii yang persisten disimpan di `~/Library/Application Support/agentmemory` di macOS, `$XDG_DATA_HOME/agentmemory` atau `~/.local/share/agentmemory` di Linux, dan `%APPDATA%\agentmemory` di Windows. Gunakan `--data-dir ` atau `AGENTMEMORY_DATA_DIR` untuk menggantinya, dan pakai nilai yang sama setiap kali restart. Untuk kompatibilitas mundur, `./data/state_store.db` atau `./data/iii-config.yaml` yang sudah ada akan diprioritaskan di atas default platform untuk instance 0; flag eksplisit atau override environment tetap menang.
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
Sambungkan lebih banyak agen kapan saja dengan `agentmemory connect ` — 20 adapter terdaftar di [Bekerja dengan setiap agen](#works-with-every-agent). Referensi perintah lengkap ada di [Mulai Cepat](#quick-start).
Windows
Jalur tercepat adalah WSL2. Setup engine Windows native membutuhkan ZIP v0.22.1 yang dipin untuk diunduh dan `iii.exe` diekstrak secara manual; CLI tidak mengekstraknya secara otomatis. Docker Desktop juga didukung. Lihat [catatan Windows](#windows) untuk langkah demi langkahnya.
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`).
Sudah menjalankan iii engine sendiri
agentmemory mem-pin iii-engine v0.22.1 dan tidak akan menyambung ke versi lain (worker tidak bisa berbicara dengan protokol engine lain). Hentikan engine lain itu, lalu jalankan `npx -y @agentmemory/agentmemory@latest`. Ini akan memasang dan menjalankan v0.22.1 yang dipin di `~/.agentmemory/bin`, tanpa mengganggu `iii` milik Anda sendiri.
---
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 + 7 hook + MCP
OpenCode plugin capture + MCP
Devin 6 hook + skill + MCP
OpenClaw plugin native + MCP
Hermes plugin native + MCP
pi plugin native + MCP
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 server MCP
Roo Code server MCP
Kilo Code server MCP
Goose server MCP
Aider REST API
Bekerja dengan agen apa pun yang memakai MCP atau HTTP. Satu server, memori dibagikan di antara semuanya.
---
Anda menjelaskan arsitektur yang sama setiap sesi. Anda menemukan ulang bug yang sama. Anda mengajarkan ulang preferensi yang sama. Memori bawaan (CLAUDE.md, .cursorrules) terbatas pada 200 baris dan jadi basi. agentmemory memperbaiki ini. Secara diam-diam, agentmemory menangkap apa yang dilakukan agen Anda, mengompresnya menjadi memori yang bisa dicari, dan menyuntikkan konteks yang tepat saat sesi berikutnya dimulai. Satu perintah. Bekerja lintas agen.
**Yang berubah:** Sesi 1 Anda menyiapkan autentikasi JWT. Sesi 2 Anda minta rate limiting. Agen sudah tahu bahwa autentikasi Anda memakai middleware jose di `src/middleware/auth.ts`, test Anda mencakup validasi token, dan Anda memilih jose dibanding jsonwebtoken untuk kompatibilitas Edge, tanpa harus menjelaskan ulang dan tanpa copy-paste.
```bash
npx -y @agentmemory/agentmemory@latest
```
Secara default, agentmemory menyimpan state iii-engine di luar repository tempat Anda menjalankannya: `~/Library/Application Support/agentmemory` di macOS, `$XDG_DATA_HOME/agentmemory` atau `~/.local/share/agentmemory` di Linux, dan `%APPDATA%\agentmemory` di Windows. `./data/state_store.db` atau `./data/iii-config.yaml` versi lama yang sudah ada akan dipakai ulang untuk instance 0 sebelum default platform tersebut. Untuk memilih lokasi secara eksplisit, gunakan `--data-dir ` atau set `AGENTMEMORY_DATA_DIR`; kedua setelan eksplisit ini diprioritaskan di atas penemuan lokasi lama:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
Peluncuran native dan Docker memakai direktori host hasil resolusi yang sama; Docker bind-mount direktori itu di `/data`. `--instance 1` menambahkan `instance-1` ke direktori hasil resolusi dan memilih kuartet port default yang terpisah `3211/3212/3213/49234`.
Catatan rilis terbaru: [CHANGELOG.md](../CHANGELOG.md).
---
### Akurasi Retrieval
**coding-agent-life-v1** (korpus in-house, bisa direproduksi di sandbox)
| Adapter | P@5 | R@5 | Top-5 hit rate | Latensi p50 |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
Top-5 hit rate 100% pada **batas matematis P@5** untuk korpus ini (0.240, lihat scorecard). Hybrid me-retrieve setiap sesi gold; grep melewatkan 1 dari 2 gold pada query temporal multi-sesi. Peningkatannya ada pada **recall + temporal**, bukan presisi agregat. Benchmark ini kecil dan gold-nya jarang; LongMemEval-S yang lebih besar di bawah memberi pembeda yang lebih baik. Rincian lengkap per tipe + catatan koreksi: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
**LongMemEval-S** (ICLR 2025, 500 pertanyaan)
| Sistem | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| Fallback BM25-only | 86.2% | 94.6% | 71.5% |
> Model embedding: `all-MiniLM-L6-v2` (lokal, gratis, tanpa API key). Laporan lengkap: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Perbandingan kompetitor: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) mencakup agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
**Reproduksi secara lokal:** [`eval/README.md`](../eval/README.md), harness yang adapternya bisa dipasang-cabut untuk LongMemEval `_s` (500-Q publik) + `coding-agent-life-v1` (korpus in-house 15 sesi). Adapter grep / vector / agentmemory dinilai berdampingan, output NDJSON, scorecard yang dipublikasikan mendarat di [`docs/benchmarks/`](../docs/benchmarks/).
**Berpasangan dengan [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), dan [Graphify](https://github.com/safishamsi/graphify).** Code-graph indexing, pipeline build multi-agen, dan knowledge graph yang lebih luas lintas dokumen / PDF / gambar / video. agentmemory mengingat pekerjaannya; ketiga proyek itu menghidupkan sisa layer konteksnya. Resep + tabel perutean pertanyaan: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
agentmemory
mem0 (63K ⭐)
Letta / MemGPT (24K ⭐)
Khoj (36K ⭐)
supermemory (29K ⭐)
TencentDB Agent Memory (22K ⭐)
MemPalace (54K ⭐)
oracleagentmemory
Hippo
Bawaan (CLAUDE.md)
Tipe
Memory engine + server MCP
API memory layer
Runtime agen lengkap
AI pribadi
API memori + app
Hub memori tim (proxy LLM)
Vector memory (OSS)
Memory engine (Oracle DB)
Sistem memori
File statis
Retrieval R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
N/A
Self-reported
PersonaMem 76% (self-reported)
~96.6% (self-reported)
94.4% (self-reported)
N/A
N/A (grep)
Auto-capture
12 hook (tanpa effort manual)
Panggilan add() manual
Self-edit oleh agen
Manual
Ekstraksi di sisi API
Intersepsi proxy (swap base-URL)
Manual
Ekstraksi API
Manual
Edit manual
Search
BM25 + Vector + Graph (fusi RRF)
Vector + Graph
Vector (archival)
Semantik
Vector + RAG
4 tipe aset (Chat / Skill / Wiki / CodeGraph)
Vector-only
Vector + semantik
Decay-weighted
Memuat semuanya ke konteks
Multi-agen
MCP + REST + lease + signal
API (tanpa koordinasi)
Hanya dalam runtime Letta
Tidak
Tidak
Role tim + aset bersama
Tidak
Hanya terbatas (scoped)
Multi-agen bersama
File per agen
Framework lock-in
Tidak ada (klien MCP apa pun)
Tidak ada
Tinggi (harus pakai Letta)
Standalone
Tidak ada
Proxy mengarahkan setiap panggilan model
Tidak ada
Oracle Database
Tidak ada
Format per agen
Dependensi eksternal
Tidak ada (SQLite + iii-engine)
Qdrant / pgvector
Postgres + vector DB
Multipel
Cloud terkelola
Stack Docker (Core + Hub + Proxy)
Vector store
Oracle AI Database
Tidak ada
Tidak ada
Siklus hidup memori
Konsolidasi 4-tier + decay + auto-forget
Ekstraksi pasif
Dikelola agen
Manual
Auto-forget
Review manual; auto-routing sedang dikerjakan
Tidak ada
Tidak disebutkan
Decay + konsolidasi
Pruning manual
Efisiensi token
~1.900 token/sesi ($10/thn)
Bervariasi menurut integrasi
Core memory di konteks
Bervariasi
Harga cloud
Tidak disebutkan
Tanpa budget token
Didukung LLM (bervariasi)
Bervariasi
22K+ token pada 240 observasi
Viewer real-time
Ya (port 3113)
Dashboard cloud
Dashboard cloud
Web UI
Dashboard cloud
Web UI Hub
Tidak
Tidak
Tidak
Tidak
Self-hosted
Ya (default)
Opsional
Opsional
Ya
Tidak (cloud-only)
Ya (Docker)
Ya
Ya (Oracle DB)
Ya
Ya
Catatan benchmark: hanya R@5 agentmemory yang merupakan hasil pengukuran kami sendiri (LongMemEval-S, bisa direproduksi dari benchmark/COMPARISON.md). Angka mem0 dan Letta adalah angka LoCoMo yang mereka publikasikan sendiri (dataset yang berbeda); angka MemPalace, supermemory, TencentDB (PersonaMem), dan oracleagentmemory adalah klaim self-reported vendor yang belum kami reproduksi secara independen (run oracleagentmemory memakai GPT-5.5 terhadap Oracle AI Database). Ditampilkan berdampingan hanya sebagai perkiraan kasar, bukan head-to-head pada data yang identik. Jumlah star bersifat perkiraan dan bisa berubah seiring waktu.
**Pemain baru** yang layak diketahui, dibahas lebih dalam di [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| Sistem | ⭐ | Sudut pandang |
|--------|---|-------|
| Zep / Graphiti | 30K | Knowledge graph temporal; hasil query temporal terpublikasi terkuat (LongMemEval 63.8%), tapi graph dibangun secara asinkron sehingga fakta baru bisa tertinggal |
| Cognee | 30K | Ingestion dokumen-ke-knowledge-graph, Python-only, dibangun untuk ekstraksi entitas terstruktur bukan capture sesi |
Tidak satu pun dari ini yang auto-capture dari hook agen coding, menyediakan viewer local-first, atau berjalan tanpa kunci (keyless) — kombinasi yang menjadi fondasi agentmemory.
---
Kompatibilitas: rilis ini menyasar `iii-sdk` 0.22.1 dan mem-pin iii-engine v0.22.1.
### 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, validasi REST, health, viewer, dan status runtime yang didukung iii:
```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
```
Panel ready saat startup memperhitungkan keempat port: REST/MCP HTTP di 3111, stream iii di 3112, viewer di 3113, dan WebSocket worker iii di 49134. `status` mengonfirmasi kesehatan agentmemory dan mode provider/embedding yang aktif. Simpan sebuah probe dan konfirmasi bisa dicari:
```bash
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-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 '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 connect # wire 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 yang diimpor muncul di picker Replay bersama sesi native. Di balik layar setiap entri melewati fungsi iii `mem::replay::load`, `mem::replay::sessions`, dan `mem::replay::import-jsonl`, tanpa server side-channel. Setiap transkrip yang diimpor diindeks untuk pencarian, dicap dengan channel asal `import`, dan ditambang untuk crystal sesi dan lesson.
> **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
```
Peringatan: perintah ini mengubah workspace/runtime saat ini. Ia bisa memperbarui dependensi JavaScript dan menarik image Docker `iiidev/iii:0.22.1` yang dipin. Ia tidak akan pernah memasang iii engine yang tidak dipin atau lebih baru.
Detail implementasi ada di `src/cli.ts` (lihat `runUpgrade` di sekitar region `src/cli.ts:544-595`).
### Claude Code (satu blok, tempel saja)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. 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` 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`. 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
```
Ini menggabungkan perintah hook yang sama ke `~/.claude/settings.json` dengan path absolut yang diresolusi ke direktori `plugin/` bundel dari paket `@agentmemory/agentmemory` yang sedang terpasang. Jalankan ulang perintah ini setelah upgrade agentmemory untuk menyegarkan path-nya. Entri pengguna di file yang sama tetap dipertahankan; hanya entri agentmemory sebelumnya yang diganti. Jalur `/plugin install` tetap menjadi pendekatan yang direkomendasikan.
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.
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 the agentmemory repo 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` (50+ agen)
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 `:
- `agentmemory connect ` menulis konfigurasi server MCP sehingga tool-nya tersedia.
- `npx skills add rohitg00/agentmemory` memasang skill-nya sehingga agen tahu kapan harus memanggilnya.
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/` | Listing Cursor Marketplace (submission sedang direview) atau Cursor Settings → Plugins → checkout lokal. Mendaftarkan 7 hook auto-capture (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + server MCP, dengan `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` dikelola di dashboard plugin Cursor. Bekerja di Cursor IDE dan CLI `cursor-agent`; prompt mode-print CLI di-backfill dari transkrip sesi saat sesi berakhir. |
| **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/extensions/agentmemory` | `agentmemory connect pi` memasang extension bundel ke direktori auto-discovery milik pi (recall saat agen start, capture saat agen end, tool `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` pada pi yang berjalan akan mengambilnya. [`integrations/pi`](../integrations/pi/) juga adalah paket pi (`pi install ./integrations/pi` dari sebuah checkout). |
| **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, 8 skill agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) muncul secara native di palet slash-command Warp. |
| **Cline (CLI)** | `~/.cline/mcp.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` dari awal saat keduanya belum ada, atau memodifikasi `config.json` yang sudah ada. **Jika Anda sudah punya `config.yaml`**, adapter ini mencetak blok persis untuk ditempel di bawah `mcpServers:`; ia tidak akan diam-diam menulis ulang yaml Anda karena mempertahankan komentar dan anchor dengan aman membutuhkan parser YAML yang tidak disertakan paket ini. Continue memakai bentuk array (bukan objek) 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` menambahkan baris `@deepseek-ai/dsh-mcp-client` ke layer patch tingkat home yang dimuat setiap profil Harness; tool terdaftar sebagai `mcp__agentmemory__*`. Tambahkan `--with-hooks` untuk juga menyambungkan auto-capture: script hook Claude Code bundel berjalan lewat bridge first-party Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) lewat manifest yang ditulis ke `$DSH_HOME/agentmemory.hooks.json`. Default ke `~/.dsh` saat `DSH_HOME` tidak diset. |
| **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 | Bicara langsung dengan REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Agen apa pun (32+)** | n/a | `npx skillkit install agentmemory` auto-detect host dan menggabungkannya. |
**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 (Python / Rust / Node)
agentmemory mendaftarkan operasi intinya sebagai fungsi iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Bahasa apa pun yang punya SDK iii bisa memanggilnya langsung lewat `ws://localhost:49134`, tanpa klien REST terpisah per bahasa.
```bash
pip install iii-sdk # Python
cargo add iii-sdk # Rust
npm install iii-sdk # Node
```
```python
from iii import register_worker
iii = register_worker("ws://localhost:49134")
iii.connect()
iii.trigger({
"function_id": "mem::smart-search",
"payload": {"project": "demo", "query": "how do tokens refresh"},
})
```
Contoh kerja: [`examples/python/`](../examples/python/) (quickstart + flow observasi/recall). REST di `:3111` tetap tersedia untuk host tanpa runtime iii.
### Dari source
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
Ini menjalankan agentmemory dengan `iii-engine` lokal jika binary yang dipin sudah terpasang, atau memakai Docker Compose saat dipilih. REST, stream, dan viewer terbind ke `127.0.0.1` secara default. Jalur binary otomatis macOS/Linux membutuhkan `curl`, `sh` POSIX, dan `tar`.
Pasang `iii-engine` secara manual. **agentmemory saat ini mem-pin `iii-engine` ke `v0.22.1`**, rilis yang sama dengan dependensi `iii-sdk`-nya; worker berbicara dengan wire protocol engine itu, dan 0.20.0 menata ulang permukaan SDK, sehingga keduanya bergerak bersama di rilis agentmemory. Override dengan `AGENTMEMORY_III_VERSION=` jika Anda menjalankan engine sendiri dan tahu itu cocok.
- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** ganti `aarch64-apple-darwin` dengan `x86_64-apple-darwin`
- **Linux x64:** ganti dengan `x86_64-unknown-linux-gnu`
- **Linux arm64:** ganti dengan `aarch64-unknown-linux-gnu`
- **Windows:** unduh `iii-x86_64-pc-windows-msvc.zip` dari [rilis iii-hq/iii v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) dan ekstrak `iii.exe` ke `%USERPROFILE%\.agentmemory\bin\iii.exe`
Setiap arsip punya file `.sha256` yang cocok di halaman rilis; saat Anda mengganti platform, pakai hash dari file itu pada pengecekan di atas (di Windows: `Get-FileHash`). Installer otomatis di `npx @agentmemory/agentmemory` mem-pin hash-hash ini dan menolak arsip yang tidak cocok.
Atau pakai Docker (`docker-compose.yml` bundel menarik `iiidev/iii:0.22.1`). Dokumentasi lengkap: [iii.dev/docs](https://iii.dev/docs).
### Windows
agentmemory berjalan di Windows 10/11, tapi paket Node.js saja tidak cukup; Anda juga membutuhkan runtime iii-engine v0.22.1 yang dipin sebagai proses background. CLI tidak mengekstrak ZIP Windows secara otomatis, sehingga pengguna Windows native harus memasang `iii.exe` secara manual, memakai WSL2, atau memilih Docker Desktop.
Penyambungan MCP otomatis di Windows native hanya mendukung `agentmemory connect copilot-cli`. Untuk Claude Code, Codex, Cursor, dan setiap agen Windows native lainnya, salin blok MCP manual dari [Agen lainnya](#other-agents) ke konfigurasi Windows agen tersebut. Menjalankan `connect` di WSL hanya tepat saat agen target juga terpasang di environment WSL yang sama; itu tidak mengedit konfigurasi agen pada host Windows.
**Opsi A: binary Windows prebuilt (disarankan)**
```powershell
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
# (agentmemory pins the engine to the same release as its iii-sdk;
# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe to agentmemory's private engine directory:
New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
& "$HOME\.agentmemory\bin\iii.exe" --version
# Should print: 0.22.1
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory@latest
```
**Opsi B: Docker Desktop**
```powershell
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Select Docker explicitly and run agentmemory:
$env:AGENTMEMORY_USE_DOCKER = "1"
npx -y @agentmemory/agentmemory@latest
```
**Opsi C: hanya MCP standalone (tanpa engine).** Jika Anda hanya butuh tool MCP untuk agen Anda dan tidak membutuhkan REST API, viewer, atau cron job, lewati engine-nya sama sekali:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Diagnostik untuk Windows:** jika `npx -y @agentmemory/agentmemory@latest` gagal, jalankan ulang dengan `--verbose` untuk melihat stderr engine yang sebenarnya. Mode kegagalan umum:
| Simptom | Perbaikan |
|---|---|
| `The engine process started but the REST API never responded.` | Pastikan keempat port hasil derivasi bebas, verifikasi `iii.exe` yang dipin tetap hidup, lalu jalankan ulang dengan `--verbose` dan periksa stderr engine yang tertangkap |
| `Could not start iii-engine` | Baik `iii.exe` maupun Docker tidak terpasang. Lihat Opsi A atau B di atas |
| Konflik port | `netstat -ano \| findstr :3111` untuk melihat apa yang terbind, lalu matikan atau pakai `--port ` |
| Fallback Docker dilewati walau Docker terpasang | Pastikan Docker Desktop benar-benar berjalan (ikon system tray) |
> Catatan: **engine** iii adalah binary prebuilt, bukan crate cargo, jadi jangan coba `cargo install`. (**SDK** iii dipublikasikan di crates.io, npm, dan PyPI, tapi agentmemory tidak membutuhkannya.) Metode instalasi engine yang didukung semuanya dipin ke v0.22.1: binary prebuilt di atas, jalur auto-install macOS/Linux milik agentmemory (`curl`, `sh` POSIX, dan `tar` dibutuhkan), dan image Docker `iiidev/iii:0.22.1`. `install.sh | sh` upstream yang polos memasang engine terbaru, yang tidak didukung agentmemory. Gunakan `npx -y @agentmemory/agentmemory@latest`; di macOS/Linux ia mengambil engine yang dipin ke `~/.agentmemory/bin`.
---
Deploy
Template satu klik untuk host terkelola. Masing-masing menyediakan
Dockerfile mandiri yang menarik `@agentmemory/agentmemory` dari npm dan
menyalin binary engine iii dari image Docker Hub resmi `iiidev/iii`;
tidak perlu image agentmemory prebuilt. Storage persisten
termount di `/data`; entrypoint first-boot menimpa
konfigurasi iii bawaan npm (yang terbind ke `127.0.0.1`) dengan
konfigurasi yang disetel untuk deployment, yang terbind ke `0.0.0.0` dan
memakai path `/data` absolut, membuat secret HMAC, lalu
melepas privilese dari `root` ke `node` lewat
`gosu` sebelum exec ke CLI agentmemory.
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.
Hanya port `3111` yang dipublikasikan. Viewer di `3113` tetap
terbind ke loopback di dalam kontainer; README setiap template
mendokumentasikan pola SSH-tunnel untuk menjangkaunya.
---
Setiap agen coding melupakan segalanya saat sesi berakhir, dan setiap sesi baru dimulai dengan Anda menjelaskan ulang stack Anda. agentmemory berjalan di background dan menghilangkan langkah itu.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
agentmemory silently captures every tool use
Session ends -> observations compressed into structured memory
Session 2: "Now add rate limiting"
Agent already knows:
- 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
Zero re-explaining. Starts working immediately.
```
### 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 |
|---|---|---|
| Skala | Batas 200 baris | Tak terbatas |
| Search | Memuat semuanya ke konteks | BM25 + vector + graph (hanya top-K) |
| Biaya token | 22K+ pada 240 observasi | ~1.900 token (92% lebih sedikit) |
| 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
-> SHA-256 dedup (5min window)
-> 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 SLOT_REFLECT_ENABLED=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject into conversation
```
### 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
| 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** | Setiap pemakaian tool direkam lewat hook, tanpa effort manual |
| **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.
Vector tetap bertahan dari crash atau force-kill. Index vector disimpan dalam bucket paling lambat setiap `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 menit). Setiap vector yang ditambahkan atau dihapus di antaranya juga langsung ditulis ke log pending kecil di state store, dan start berikutnya me-replay-nya tanpa memanggil penyedia embedding. Setiap save yang berhasil mengosongkan log itu. Dokumen yang masih belum punya vector setelah replay di-embed ulang di background dalam batch `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) sampai tidak ada yang tersisa, dan backfill yang terhenti dilanjutkan pada start berikutnya. `/agentmemory/status` dan viewer menunjukkan ukuran log pending dan state backfill. Instalasi keyless tidak menulis apa pun.
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 | Di perangkat sendiri setelah unduhan model pertama, +8pp recall dibanding BM25-only |
| 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` | $0.02/1M | Kualitas tertinggi |
| 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/
```
---
Auto-start di port `3113`. Viewer memuat satu snapshot saat terhubung (`GET /agentmemory/viewer/snapshot`) lalu menerapkan event stream live: memori baru, lesson, observasi, entri audit, perubahan graph, dan update health muncul tanpa polling atau reload halaman. Satu-satunya permintaan lain adalah aksi yang Anda klik, halaman "load more", dan pencarian. Saat stream putus, viewer menunjukkan seberapa basi angkanya, menyambung ulang dengan backoff, dan resync dari satu snapshot.
- **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'`).
---
Viewer di `:3113` menunjukkan apa yang **diingat** oleh agen Anda. [iii console](https://iii.dev/docs/console) menunjukkan apa yang **dilakukan** agen Anda: setiap operasi memori sebagai trace OpenTelemetry, setiap entri KV bisa diedit, setiap fungsi bisa dipanggil, setiap stream bisa disadap. Dua jendela pada memori yang sama: satu berbentuk produk, satu berbentuk engine.
Lihat `memory_smart_search` dipicu dan saksikan scan BM25 → lookup embedding → fusi RRF → reranker sebagai waterfall. Edit timer konsolidasi yang stuck di KV browser. Replay hook `PostToolUse` dengan payload yang diubah. Pin stream WebSocket dan saksikan observasi mendarat secara live.
agentmemory menyediakan ini secara gratis karena setiap panggilan fungsi dan trigger dipicu lewat iii; tidak ada yang custom, tidak ada yang perlu diinstrumentasi.
Halaman Workers: setiap worker yang terhubung, termasuk agentmemory sendiri, dengan PID, jumlah fungsi, runtime, dan last-seen.
**Sudah terpasang.** Console dikirim bersama engine `iii` yang dipin (0.22+); tidak ada yang perlu dipasang terpisah. Peluncuran pertama mengunduh binary console di sebelah engine.
**Jalankan bersama agentmemory:**
```bash
agentmemory console
```
Ini menjalankan `iii console` dari engine yang dipin terhadap port hasil resolusi agentmemory (REST, stream, bridge) dan menyajikannya satu port di atas viewer, `http://localhost:3114` secara default. `--console-port N` memilih port lain; `--port` dan `--instance` memilih instance agentmemory dengan cara yang sama seperti untuk `stop`; flag lain apa pun diteruskan, misalnya `--enable-flow` untuk halaman architecture-graph eksperimental.
Hal yang sama secara manual, berguna saat `agentmemory` tidak ada di PATH:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**Apa yang bisa Anda lakukan dari console:**
| Halaman | Gunakan untuk |
|------|-----------|
| **Workers** | Melihat setiap worker yang terhubung dan metrik live-nya, termasuk worker agentmemory sendiri. |
| **Functions** | Memanggil langsung fungsi apa pun milik agentmemory dengan payload JSON; berguna untuk menguji `memory.recall`, `memory.consolidate`, `graph.query` tanpa menyambungkan klien. |
| **Triggers** | Me-replay trigger HTTP, cron, event, dan state: memicu cron konsolidasi secara manual, retry rute HTTP, memancarkan perubahan state. |
| **States** | Browser KV dengan CRUD penuh atas sesi, slot memori, timer lifecycle, dan index embedding; edit nilai di tempat. |
| **Streams** | Monitor WebSocket live untuk penulisan memori, event hook, dan update observasi saat mengalir lewat stream iii. |
| **Queues** | Topik queue durable + manajemen dead-letter. Replay atau drop job embedding / kompresi yang gagal. |
| **Traces** | Tampilan waterfall / flame / service-breakdown OpenTelemetry. Filter berdasarkan `trace_id` untuk melihat persis fungsi, panggilan DB, dan permintaan embedding apa yang dihasilkan satu `memory.search`. |
| **Logs** | Log OTEL terstruktur yang difilter dan dikorelasikan ke trace/span ID. |
| **Config** | Konfigurasi runtime: lihat persis worker, provider, dan port apa yang dipakai engine Anda. |
| **Flow** | (Opsional, `--enable-flow`) Graph arsitektur interaktif untuk setiap worker, trigger, dan stream. |
Traces: breakdown waterfall / flame / service untuk setiap operasi memori.
**Trace sudah aktif:**
`iii-config.yaml` dikirim dengan worker `iii-observability` sudah aktif (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Tidak perlu konfigurasi tambahan; begitu agentmemory start, setiap operasi memori memancarkan log terstruktur yang bisa dibaca console, dan satu dari sepuluh operasi (`sampling_ratio: 0.1`) juga memancarkan span trace.
Jika Anda ingin mengekspor ke Jaeger/Honeycomb/Grafana Tempo sebagai gantinya, ubah `exporter: memory` jadi `exporter: otlp` dan set endpoint collector sesuai dokumentasi observability iii.
> **Perhatian:** tidak ada autentikasi yang diberlakukan pada console itu sendiri; tetap terbind ke `127.0.0.1` (default) dan jangan pernah mengeksposnya secara publik.
---
agentmemory **sudah menjadi instance [iii](https://iii.dev) yang berjalan**. Tiga primitif (worker, function, trigger) menyusun runtime-nya; state KV, stream, dan trace OTEL datang dari worker iii-state, iii-stream, dan iii-observability yang dikirim bersama iii. Anda tidak memasang Postgres, Redis, Express, pm2, atau Prometheus, karena iii menggantikan semuanya.
Artinya satu perintah lagi memperluas agentmemory dengan kemampuan baru yang sepenuhnya baru.
### Perluas agentmemory dengan worker lain
Builtin yang dibutuhkan agentmemory sudah ada di `iii-config.yaml` dan boot bersamanya: `iii-state` (KV), `iii-queue` (retry durable untuk event subscriber), `iii-pubsub`, `iii-cron`, `iii-stream`, dan `iii-observability` (trace, metrics, dan logs OTEL pada setiap fungsi). Apa pun yang lain dari [registry worker iii](https://workers.iii.dev) terpasang ke engine yang sama: salin `iii-config.yaml` ke `~/.agentmemory/iii-config.yaml` (CLI memprioritaskan file itu di atas yang bundel dan tetap merender port serta path data ke dalamnya), tambahkan entrinya, pasang runtime worker sekali dengan `~/.agentmemory/bin/iii update worker`, lalu restart agentmemory.
```yaml
workers:
# ...the bundled entries...
- name: database # SQL-backed state adapter when you outgrow the KV defaults
- name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
- name: mcp # extra MCP servers next to agentmemory's, same engine
```
| Worker | Yang Anda dapat di atas agentmemory |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | Adapter state berbasis SQL saat Anda melampaui default KV in-memory |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code yang keluar dari `memory_recall` berjalan di dalam VM sekali pakai, bukan di shell Anda |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Mendirikan server MCP tambahan di sebelah milik agentmemory, berbagi engine yang sama |
Di engine 0.22.x, pertahankan nama berprefiks `iii-` untuk builtin di atas; entri tanpa prefiks `http`, `state`, `queue`, `pubsub`, dan `cron` adalah worker registry standalone yang agentmemory pindah ke sana dengan migrasi 0.23.
Registry lengkap: [workers.iii.dev](https://workers.iii.dev). Setiap worker di sana menyusun lewat primitif yang sama yang dipakai agentmemory, dan agentmemory yang Anda sudah punya adalah salah satunya.
### Konfigurasi engine dan bind address
`agentmemory start` membaca konfigurasi engine dari file pertama yang ada: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` di direktori saat ini, `~/.agentmemory/iii-config.yaml`, lalu `iii-config.yaml` bundel. Pada setiap start, ia merender file itu (path data, port, backend state) ke `~/.agentmemory/data/iii-config.runtime.yaml` dan meluncurkan engine dengan salinan hasil render itu, jadi edit file source-nya, bukan yang hasil render. Nilai `host:` pada file source dipertahankan sebagaimana tertulis.
`iii-config.yaml` bundel sengaja terbind ke `127.0.0.1`, dan default itu juga berlaku di dalam kontainer. CLI yang dijalankan di dalam kontainer listen di loopback milik kontainer itu, sehingga port yang dipublikasikan tidak menjangkau apa pun. Untuk menyajikan CLI yang di-kontainerisasi lewat port yang dipublikasikan, set `AGENTMEMORY_III_CONFIG` ke konfigurasi yang terbind ke `0.0.0.0`. `iii-config.docker.yaml` yang dipaketkan adalah salah satunya: ia membind `iii-http`, `iii-stream`, dan port engine ke `0.0.0.0` dan menyimpan state di bawah `/data`, jadi mount volume yang bisa ditulis di sana. Tetap set `AGENTMEMORY_SECRET`, dan publikasikan hanya port yang Anda butuhkan, di `127.0.0.1` atau di belakang proxy yang Anda percaya.
`docker-compose.yml` repo ini tidak melewati pencarian konfigurasi CLI: ia mount `iii-config.docker.yaml` di `/app/config.yaml`, dan kontainer `iii-engine` start dengan `--config /app/config.yaml`. Template [deploy](../deploy/) satu-klik menulis konfigurasi `0.0.0.0` mereka sendiri di entrypoint-nya.
### Storage backend: file (default) vs redis
`iii-state` dan `iii-stream` secara default memakai KV store berbasis file bundel iii-engine: satu file JSON per scope, dipegang di memori proses engine dan ditulis ulang ke disk secara berkala. Itu adalah default yang tepat untuk instalasi lokal satu pengguna; daemon bersama dengan beberapa penulis konkuren mendapat penulisan per-key yang sesungguhnya dari Redis sebagai gantinya, dengan biaya satu network round trip per operasi (setiap panggilan `state::*` tetap diserialisasi pada satu koneksi Redis, sehingga ini menukar lock file store dengan socket, bukan untuk paralelisme).
Set `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) untuk mengalihkan kedua worker ke adapter `redis` bawaan iii-engine, yang menyimpan setiap key sebagai field hash Redis (`HSET`) bukan menulis ulang seluruh scope pada setiap penulisan:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
`AGENTMEMORY_STATE_BACKEND` defaultnya `file`; membiarkannya tidak diset menjaga perilaku hari ini tidak berubah, dan nilai yang tidak dikenal (apa pun selain `file` atau `redis`) adalah error saat startup bukan fallback senyap. `/agentmemory/status` dan halaman Health viewer (baris State store) melaporkan backend mana yang aktif dan apakah ia merespons, tidak pernah URL-nya.
**Hanya `redis://` polos.** Engine yang dipin (0.22.1) membangun klien Redis-nya tanpa dukungan TLS, sehingga URL `rediss://` (kebanyakan layanan Redis terkelola, seperti Upstash, Redis Cloud, dan ElastiCache dengan enkripsi in-transit, defaultnya TLS-only) gagal terhubung. Koneksinya tidak terenkripsi, sehingga password Redis dan setiap memori yang tersimpan melintasi kabel dalam teks jelas: arahkan ke Redis lokal atau yang berada di network privat yang Anda percaya. Untuk Redis lainnya, jalankan tunnel terenkripsi (stunnel, SSH, atau VPN) di host agentmemory, sehingga hop `redis://` polos itu tetap di host tersebut dan koneksi upstream tunnel-nya terenkripsi dan terautentikasi. Jika password Redis memuat tanda kutip tunggal, percent-encode-lah (`%27`); engine mengekspansi URL ke konfigurasi YAML-nya sebelum mem-parse-nya.
**Satu server Redis per `--instance`.** Prefiks key Redis milik engine (`state:`, `stream::`) sudah tetap, sehingga dua instance agentmemory (`--instance 1`, `--instance 2`, ...) yang mengarah ke database yang sama akan saling menimpa datanya. Index database yang terpisah (`redis://localhost:6379/1`) menjaga data tersimpan terpisah, tapi engine meneruskan event viewer live lewat satu channel pub/sub Redis (`stream::events`), dan pub/sub Redis mengabaikan index database, sehingga viewer setiap instance tetap akan menunjukkan event live milik instance lain. Beri setiap instance server Redis-nya sendiri (atau port-nya sendiri) saat Anda menjalankan lebih dari satu.
**Apa yang tetap sama, dan apa yang berbeda.** Setiap fitur agentmemory bekerja di Redis: session, observation, memory (remember, supersede, evolve, forget), search dan bucket index-nya, lesson, graph, audit log dan scope bulanannya, export dan import, governance delete, status konsolidasi, snapshot viewer dan stream live-nya, dan health monitor. Engine menyimpan setiap scope sebagai satu hash Redis (`HSET`/`HGET`/`HGETALL`) dan memicu state trigger yang sama seperti file store. Tiga perbedaan engine ditangani di dalam agentmemory:
- Redis mengembalikan record sebuah scope tanpa urutan yang tetap. agentmemory mengurutkannya dari yang paling lama (berdasarkan waktu pembuatan di id record, lalu timestamp-nya) sehingga list, paging, dan chunk export kembali dalam urutan yang sama seperti di file store.
- Engine menerapkan update parsial di Redis lewat skrip Lua yang mengubah array kosong jadi objek kosong. agentmemory menerapkan update itu sendiri (baca, ubah, tulis di bawah lock per-key) di Redis, sehingga field seperti `tags: []` tetap array.
- Pengecekan audit log legacy membaca scope lama dari Redis bukan mencari file file store di disk.
Satu perbedaan membutuhkan tindakan Anda: **setelah Redis restart, engine berhenti meneruskan event live** ke viewer sampai agentmemory restart. Data tetap tersimpan dan terbaca normal. Health monitor mengirim event tes lewat Redis setiap 30 detik; saat tidak kembali, `/agentmemory/status` dan halaman Health viewer menunjukkan "Live updates are not reaching the viewer" dengan perbaikannya: restart agentmemory. Jika Redis mati, laporan status menunjukkan "The state store is not answering" dan cara mengeceknya (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Mendaftar scope yang sangat besar membaca seluruh hash dalam satu `HGETALL`, biaya yang sama seperti file store yang menyimpannya di memori.
**Setelan Redis yang direkomendasikan.** Policy snapshot default `save 3600 1 300 100 60 10000` bisa kehilangan beberapa menit penulisan saat crash, lebih buruk dari window flush 5 detik milik file store. Set `appendonly yes` untuk apa pun yang Anda sayang kehilangan. Set `maxmemory-policy noeviction`; `allkeys-lru` atau sejenisnya diam-diam membuang memori begitu Redis mencapai batas memorinya.
Start native (non-Docker), dan setiap template [deploy](../deploy/) satu-klik (mereka menimpa `iii-config.yaml` bundel dan start secara native), membaca `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` dan merendernya ke `iii-config` yang diluncurkan. URL itu sendiri tidak pernah ditulis ke file hasil render itu, hanya referensi `${AGENTMEMORY_REDIS_URL}` yang diekspansi proses engine dari environment-nya sendiri saat boot. Hanya jalur Docker Compose milik repo ini sendiri (`AGENTMEMORY_USE_DOCKER=1`, atau melanjutkan engine yang sudah distart begitu) yang mount `iii-config.docker.yaml` secara read-only dan tidak pernah merender; `agentmemory start` memperingatkan saat mendeteksi kombinasi itu. Ubah file itu secara manual, mengikuti bentuk `name: redis` / `config: redis_url: ...` yang sama yang ditunjukkan di dokumentasi worker [iii-state](https://workers.iii.dev/workers/iii-state) dan [iii-stream](https://workers.iii.dev/workers/iii-stream), dan arahkan `redis_url` ke Redis yang terjangkau dari kontainer. `docker-compose.yml` meneruskan `AGENTMEMORY_REDIS_URL` ke kontainer engine, sehingga `redis_url: '${AGENTMEMORY_REDIS_URL}'` bekerja di sana dan menjaga URL-nya di luar file yang di-mount.
Konfigurasi hasil render menjaga URL-nya di luar `~/.agentmemory/data/iii-config.runtime.yaml`, tapi worker konfigurasi milik engine sendiri tetap mempersistenkan nilai yang *terekspansi* ke `~/.agentmemory/config/iii-state.yaml` dan `iii-stream.yaml` begitu ia boot (ekspansi `${VAR}` milik iii-engine terjadi sebelum worker itu menyimpan seed-nya, dan ia menyimpan nilai yang sudah diresolusi, bukan referensinya). Perlakukan direktori itu sebagai penyimpan credential: `chmod 700 ~/.agentmemory` di host bersama mana pun, dan pilih user ACL Redis yang di-scope untuk kebutuhan agentmemory dibanding credential admin database.
**Migrasi tidak otomatis.** Beralih `AGENTMEMORY_STATE_BACKEND` mulai dari store kosong di kedua sisi; tidak ada yang menyalin data yang sudah ada dari file ke Redis atau sebaliknya. Export dari backend yang Anda tinggalkan dan import ke yang Anda tuju. Ini berjalan identik di bash dan zsh (termasuk `bash -u`). Array seperti `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` tidak: zsh menjaga header sebagai satu word yang malformed sementara bash membelahnya jadi dua, sehingga kedua permintaan 401 setiap kali `AGENTMEMORY_SECRET` diset:
```bash
# 0. Use the generated secret when none is exported:
AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
# 1. On the old backend, while agentmemory is still running on it:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
else
curl -fsS http://localhost:3111/agentmemory/export > backup.json
fi
# 2. Confirm backup.json is a usable export before switching backends:
jq -e '.version and .exportedAt' backup.json > /dev/null || {
echo "backup.json is not a valid export; do not switch backends" >&2
exit 1
}
# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
# restart agentmemory against the new backend, then:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
else
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
fi
```
`/agentmemory/export` juga menerima `?maxSessions=` dan `?offset=` untuk memecah korpus besar lewat beberapa panggilan; `strategy` pada import adalah `merge` (default-safe), `replace`, atau `skip`.
### Apa yang digantikan iii
| Stack tradisional | agentmemory memakai |
|---|---|
| Express.js / Fastify | iii HTTP Trigger |
| SQLite / Postgres + pgvector | iii KV State + index vector in-memory |
| SSE / Socket.io | iii Stream (WebSocket) |
| pm2 / systemd | Supervisi worker engine iii |
| Prometheus / Grafana | iii OTEL + health monitor |
| Sistem plugin custom | `iii worker add ` |
**219 file sumber · ~52,000 LOC · 2,500+ pengujian · 311 fungsi · 60 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
---
### 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
Saat kompresi background yang ditulis LLM diaktifkan dengan baik penyedia maupun `AGENTMEMORY_AUTO_COMPRESS=true`, ia berjalan pada setiap observasi, sehingga pilihan model secara berarti mengubah pengeluaran bulanan. Data workload yang tertangkap: 635 permintaan / 888K token / 35 jam pemakaian aktif, dijalankan terhadap tiga model OpenRouter dengan harga per 2026-05-23.
| Tier | Model | Input / 1M | Output / 1M | Biaya untuk 35j yang tertangkap | Catatan |
|------|-------|------------|-------------|---------------------------|-------|
| Direkomendasikan | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | DeepSeek terbaru; pilihan termurah yang direkomendasikan untuk workload kompresi. |
| Direkomendasikan | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Kualitas kompresi + summarization yang solid dengan biaya ~10× lebih rendah dari Sonnet. |
| Direkomendasikan | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Reasoning code yang kuat jika sesi Anda sangat berbentuk code. |
| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Harga list sama dengan run Sonnet 4.6 yang terukur; harga intro $2/$10 hingga 2026-08-31. |
| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Tier flagship; mahal untuk kerja background yang always-on. |
| Hindari | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Model kelas flagship; overspend untuk kompresi. |
Baris yang terukur berasal dari run yang tertangkap; baris (est.) menskalakan campuran token yang sama dengan harga list setiap model.
agentmemory mencetak peringatan runtime saat `OPENROUTER_MODEL` cocok dengan pola tier premium. Set `AGENTMEMORY_SUPPRESS_COST_WARNING=1` untuk membisukannya setelah Anda membuat pilihan yang terinformasi.
Tradeoff kualitas vs biaya untuk kerja memori: kompresi adalah task summarization dengan bar kualitas yang relatif longgar (agen membaca ulang ringkasannya, bukan penggunanya). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder mendarat dalam margin kesalahan yang sama dengan Sonnet pada task ini sambil berbiaya 10-70× lebih murah. Simpan model tier premium untuk query yang Anda baca langsung.
Sumber: [harga OpenRouter untuk Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [catatan harga DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
### 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
agentmemory + iii-engine membind empat port secara default. Jika restart gagal dengan `port in use`, tabel ini memberitahu proses mana yang harus dicari.
| Port | Proses | Tujuan | Override env |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | Worker stream internal (dikonsumsi agentmemory + viewer) | `III_STREAM_PORT` (disarankan) atau legacy `III_STREAMS_PORT` |
| `3113` | agentmemory | Viewer real-time (`http://localhost:3113`) | `III_VIEWER_PORT` atau `AGENTMEMORY_VIEWER_URL` untuk URL yang dilaporkan |
| `49134` | iii-engine | WebSocket; worker mendaftar di sini, telemetri OTel mengalir lewatnya | `III_ENGINE_PORT` atau `III_ENGINE_URL` |
`--port ` mengubah anchor REST dan menurunkan stream `N+1`, viewer `N+2`, dan WebSocket engine `N+46023` hanya saat port eksplisit atau URL terkait di atas belum diset. Ini tidak membuat namespace lifecycle yang terisolasi. Gunakan `--instance 1` untuk daemon kedua; ia memakai anchor 3211, default ke `3211/3212/3213/49234`, dan menerima direktori data dan lifecycle `instance-1` yang terpisah. Instance 1 hingga 50 mengikuti pola yang sama.
Engine yang dipin start dengan `--no-update-check` (tanpa pengecekan update atau security-advisory ke GitHub saat boot) dan dengan telemetri pemakaian anonim iii nonaktif: agentmemory set `III_TELEMETRY_ENABLED=false` untuk engine yang dimunculkannya kecuali Anda mengekspor variabel itu sendiri, dan file compose bundel melakukan hal yang sama.
Pembersihan proses basi saat port tetap terbind setelah run yang crash:
```bash
# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true
# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
`agentmemory stop` membersihkan baik pidfile worker maupun engine secara bersih saat shutdown native yang graceful. Di mode Docker, ia menguras worker native, menghentikan tepat kontainer engine yang tervalidasi, dan mempertahankan baik kontainer maupun mount `/data`-nya untuk restart tanpa kehilangan data; start berikutnya memvalidasi dan melanjutkan kontainer yang sama itu. Uninstall yang didukung Docker membutuhkan `agentmemory remove --keep-data`: ia menghapus file bersama yang dikelola agentmemory sambil mempertahankan kontainer yang tervalidasi, mount datanya, dan record lifecycle yang dibutuhkan untuk memulihkannya. Penghapusan data Docker yang destruktif dengan sengaja dibiarkan ke operator setelah backup. CLI juga menolak mengadopsi atau mengirim sinyal ke pemegang port Docker atau VM (backend Docker, vpnkit, colima) sebagai engine native kecuali `--force` diberikan. Pembersihan manual di atas hanya untuk kasus pasca-crash saat tidak ada pidfile yang tersisa.
### File Konfigurasi
Letakkan konfigurasi runtime agentmemory di `~/.agentmemory/.env` daripada mengekspor variabel di setiap shell. Jika viewer menunjukkan hint setup seperti `export ANTHROPIC_API_KEY=...`, salin itu ke file ini sebagai `ANTHROPIC_API_KEY=...` tanpa prefiks `export`, lalu restart agentmemory.
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
Buat `~/.agentmemory/.env`:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
# # OpenAI LLM provider (here) AND the OpenAI
# # embedding provider (further below). Set
# # OPENAI_API_KEY_FOR_LLM=false to scope it
# # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
# # Azure: https://.openai.azure.com/openai/deployments/
# # Auto-detected from `.openai.azure.com` hostname; uses
# # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
# # for back-compat with v0.9.17. New configs should
# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
# # Honored only by OpenAI's reasoning models (o1, o3,
# # gpt-*-reasoning) and providers that mirror that
# # schema (Ollama Cloud thinking models). Standard
# # chat models reject this field with 400. Set to
# # "none" for thinking models that return reasoning
# # but no content.
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
# raw-fetch provider (Gemini, OpenRouter, MiniMax,
# OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
# embedding). For the OpenAI LLM path, the
# OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
# takes precedence when set, for back-compat
# with v0.9.17.
# Increase for slow networks or large batch calls;
# decrease to fail-fast on rate-limit holds.
# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
# Features
# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
# provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
# token spend on active sessions.
# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
# memory slots — persona,
# user_preferences, tool_guidelines,
# project_context, guidance,
# pending_items, session_patterns,
# self_notes. Size-limited; agent
# edits via memory_slot_* tools.
# Pinned slots addressable for
# SessionStart injection.
# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
# Stop hook fires mem::slot-reflect:
# scans recent observations, auto-
# appends TODOs to pending_items,
# counts patterns in
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
# (this is what actually reaches
# the model — Claude Code treats
# SessionStart stdout as context)
# - PreToolUse fires /agentmemory/enrich
# on every file-touching tool call
# (resource cleanup, not a token
# fix — PreToolUse stdout is debug
# log only per Claude Code docs)
# Observations are still captured via
# PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
# Storage and durability
# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
# A hard kill loses at most this window.
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
# shutdown and deletes still save at once.
# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
# provenance; false skips it
# Sessions
# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
# the threshold as abandoned. Deletes nothing;
# new activity makes the session active again.
# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
# Capture filters (hooks)
# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
# when set, only these tools are captured
# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
# defaults: memory_*, toolsearch,
# listmcpresources, fetchmcpresource
# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
# Audit log
# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
# rows (debugging only)
# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private
# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
# AGENTMEMORY_TOOLS=core
```
---
138 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.** Saat `AGENTMEMORY_SECRET` tidak diset (di shell atau di `~/.agentmemory/.env`), server menghasilkan secret acak pada start pertama dan menyimpannya di `~/.agentmemory/secret` dengan mode `0600`. Setiap klien bundel membacanya dari sana saat berbicara dengan server lokal: CLI, viewer, hook di bawah `plugin/scripts`, server MCP dan shim `@agentmemory/mcp`, konfigurasi yang ditulis `agentmemory connect`, serta integrasi OpenCode, Pi, OpenClaw, Hermes, dan filesystem-watcher bundel. Secret yang tersimpan hanya dikirim ke URL loopback (`localhost`, `127.0.0.0/8`, `::1`). `AGENTMEMORY_SECRET` eksplisit selalu menang, dan klien remote tetap membutuhkannya diset. Docker dan entrypoint `deploy/` sudah menghasilkan dan mengekspor secret-nya sendiri. Untuk memanggil API secara manual:
```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: [`src/triggers/api.ts`](../src/triggers/api.ts)
**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.** Setiap node dan edge knowledge graph menyimpan id dari 32 observasi terbaru asal-usulnya. Store yang ditulis sebelum batas itu bisa menyimpan ribuan id per node yang panas, yang membuat search graph dan viewer jadi lambat atau menjatuhkan worker-nya. agentmemory memperbaiki ini sendiri: pada start pertama setelah upgrade, ia memangkas setiap node, edge, edge yang disupersede (histori temporal graph), dan snapshot yang di-cache ke batas itu di background, dalam potongan kecil dengan jeda di antaranya, sehingga search, capture, dan viewer tetap bekerja. Ia menyimpan progresnya, melanjutkan setelah restart, dan tidak pernah berjalan lagi setelah selesai. `/agentmemory/status` dan halaman Health viewer menunjukkannya sebagai pending, running (dengan scope dan posisi saat ini), done, atau failed. Set `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` untuk mematikannya.
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 "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 "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 2,500+ tests
npm run test:integration # API tests (requires running services)
```
**Prasyarat:** Node.js >= 20 dengan npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 atau Docker. Instalasi engine otomatis macOS/Linux juga membutuhkan `curl`, `sh` POSIX, dan `tar`; Windows native memakai `iii.exe` manual yang dipin, WSL2, atau Docker Desktop.
