Naaalala ng iyong coding agent ang lahat. Wala nang paulit-ulit na pagpapaliwanag.
Nakabatay sa iii engine
Permanenteng memory para sa Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, at anumang MCP client.
Pinalalawak ng gist ang LLM Wiki pattern ni Karpathy gamit ang confidence scoring, lifecycle, knowledge graph, at hybrid search: ang agentmemory ang implementasyon nito.
---
## I-install
Mga Kinakailangan:
- Node.js 20 o mas bago, kasama ang npm at npx (`node -v`, `npm -v`, at `npx -v`).
- Kailangan din ng awtomatikong pag-install ng iii-engine sa macOS/Linux ang `curl`, isang POSIX `sh`, at `tar`. Posibleng wala ang mga ito sa mga minimal na image gaya ng `node:20-slim`.
- Kinakailangang i-install nang manu-mano ang pinned iii-engine v0.22.1 `iii.exe` sa native Windows. Ang WSL2 o Docker Desktop ang iba pang suportadong landas.
Standard na command para sa sariwang pag-install:
```bash
npx -y @agentmemory/agentmemory@latest
```
Ang unang pagpapatakbo ay isang interactive setup: pipiliin mo ang mga agent na i-wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pipili ka ng LLM provider o mananatiling keyless, at inilalagay nito ang config, sinisimulan ang memory server at ang pinned nitong iii engine, at nag-aalok na i-install nang global para gumana ang payak na `agentmemory` command kahit saan pagkatapos. Tinatanggap ng `-y` ang package prompt ng npx, at iniiwasan ng `@latest` ang isang lumang cached release. Pinagagana ng provider ang mga LLM feature, pero ang LLM-written na observation compression ay magsisimula lamang kapag naka-set din ang `AGENTMEMORY_AUTO_COMPRESS=true`.
Pinapatay ng keyless mode ang vector embeddings. Ginagamit ng `memory_recall` (ang `mem::search` path) ang BM25, habang ang `memory_smart_search` ay maaari ring pagsamahin ang structural graph matches kapag umiiral na ang graph data. Para sa libreng on-device semantic recall, i-set ang `EMBEDDING_PROVIDER=local` sa `~/.agentmemory/.env` at i-restart. Ang unang embedding request ay nag-download ng `Xenova/all-MiniLM-L6-v2`; tumatakbo na lokal ang inference pagkatapos ng unang pag-download na ito ng model.
Gumagamit ang local runtime ng apat na port: `3111` para sa REST/MCP HTTP, `3112` para sa iii streams, `3113` para sa viewer, at `49134` para sa iii worker WebSocket. Ang persistent iii state ay nakatira sa `~/Library/Application Support/agentmemory` sa macOS, `$XDG_DATA_HOME/agentmemory` o `~/.local/share/agentmemory` sa Linux, at `%APPDATA%\agentmemory` sa Windows. Gamitin ang `--data-dir ` o `AGENTMEMORY_DATA_DIR` para i-override ito, at gamitin ulit ang parehong value sa bawat restart. Para sa backward compatibility, ang umiiral na `./data/state_store.db` o `./data/iii-config.yaml` ay mananaig kaysa sa platform default para sa instance 0; mananalo pa rin ang explicit flag o environment override.
Pagkatapos, patunayan na gumagana ang recall at bigyan ang iyong agent ng mga skill nito:
```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
```
Dapat tumama ang mga keyword search sa default na keyless mode gamit ang BM25. Ang query ng demo na `database performance optimization` ay sadyang semantic at puwedeng magbalik ng zero hanggang hindi pa naka-configure ang isang embedding provider.
Mas gusto mo bang ipagawa lahat sa isang coding agent? Bigyan ito ng isang instruction:
> Kunin at sundin ang mga instruction sa: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
I-wire ang mas maraming agent anumang oras gamit ang `agentmemory connect ` — 20 adapter na nakalista sa [Gumagana sa Bawat Agent](#works-with-every-agent). Kumpletong command reference sa [Mabilisang Simula](#quick-start).
Windows
Ang pinakamadaling landas ay ang WSL2. Ang native Windows engine setup ay nangangailangan ng pag-download ng pinned v0.22.1 ZIP at manu-manong pag-extract ng `iii.exe`; hindi ito awtomatikong na-extract ng CLI. Suportado rin ang Docker Desktop. Tingnan ang [mga tala para sa Windows](#windows) para sa step-by-step na gabay.
Global na Pag-install / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
Ang npx command sa itaas ay nananatiling standard na landas para sa bagong pag-install at iniiwasan nito ang mga isyu sa global-prefix permission.
Lumang bersyon ang ibinibigay ng npx
Nag-cache ang npx ayon sa bersyon. Pilitin ang paggamit ng pinakabago gamit ang `npx -y @agentmemory/agentmemory@latest`, o burahin ang cache nang isang pagkakataon gamit ang `rm -rf ~/.npm/_npx` (macOS/Linux; sa Windows, burahin ang `%LOCALAPPDATA%\npm-cache\_npx`).
May sariling iii engine ka nang tumatakbo
Nagpipin ang agentmemory sa iii-engine v0.22.1 at hindi ito kakabit sa ibang bersyon (hindi kayang kausapin ng worker ang protocol ng ibang engine). Itigil ang ibang engine, pagkatapos patakbuhin ang `npx -y @agentmemory/agentmemory@latest`. Ito ay mag-install at magpapatakbo ng pinned v0.22.1 sa `~/.agentmemory/bin`, hindi gagalawin ang sarili mong `iii`.
---
Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST API. Ibinabahagi ng lahat ng agent ang parehong memory server.
Claude Code native plugin + 12 hook + MCP
Codex CLI native plugin + 6 hook + MCP
GitHub Copilot CLI MCP + plugin hook/skill
Cursor native plugin + 7 hook + MCP
OpenCode capture plugin + MCP
Devin 6 hook + skill + MCP
OpenClaw native plugin + MCP
Hermes native plugin + MCP
pi native plugin + MCP
OpenHuman native na Memory trait backend
Gemini CLI MCP server
Antigravity MCP + hook
Claude Desktop MCP server
Warp connect + MCP + skill
Zed MCP server
Cline MCP server
Continue MCP server
Droid MCP server
Kiro MCP server
Qwen Code MCP server
DeepSeek Harness MCP server
Roo Code MCP server
Kilo Code MCP server
Goose MCP server
Aider REST API
Gumagana sa anumang agent na nakikipag-usap gamit ang MCP o HTTP. Isang server, ibinabahagi ang mga memory sa lahat ng ito.
---
Ipinaliwanag mo ang parehong architecture sa bawat session. Natutuklasan mong muli ang parehong mga bug. Itinuturo mong muli ang parehong mga preference. Ang built-in memory (CLAUDE.md, .cursorrules) ay may limitasyong 200 linya at nauupos. Ayusin ito ng agentmemory. Tahimik nitong kinukuha ang ginagawa ng iyong agent, kino-compress ito sa searchable na memory, at itinuturok ang tamang context kapag nagsimula ang susunod na session. Isang command. Gumagana sa lahat ng agent.
**Ano ang nagbabago:** Sa Session 1, nag-set up ka ng JWT auth. Sa Session 2, humiling ka ng rate limiting. Alam na ng agent na ang auth mo ay gumagamit ng jose middleware sa `src/middleware/auth.ts`, sinasaklaw ng iyong mga test ang token validation, at pinili mo ang jose kaysa sa jsonwebtoken para sa Edge compatibility — walang muling pagpapaliwanag at walang copy-paste.
```bash
npx -y @agentmemory/agentmemory@latest
```
Bilang default, itinatago ng agentmemory ang iii-engine state sa labas ng repository kung saan ito sinimulan: `~/Library/Application Support/agentmemory` sa macOS, `$XDG_DATA_HOME/agentmemory` o `~/.local/share/agentmemory` sa Linux, at `%APPDATA%\agentmemory` sa Windows. Ang umiiral na legacy na `./data/state_store.db` o `./data/iii-config.yaml` ay ginagamit ulit para sa instance 0 bago ang platform default na iyon. Para tahasang pumili ng lokasyon, ipasa ang `--data-dir ` o i-set ang `AGENTMEMORY_DATA_DIR`; mananaig ang alinmang explicit setting kaysa sa legacy discovery:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
Ginagamit ng native at Docker launches ang parehong resolved host directory; Docker bind-mount ito sa `/data`. Idinadagdag ng `--instance 1` ang `instance-1` sa resolved directory at pinipili ang hiwalay na default port quartet na `3211/3212/3213/49234`.
Pinakabagong release notes: [CHANGELOG.md](../CHANGELOG.md).
---
### Katumpakan ng Retrieval
**coding-agent-life-v1** (in-house corpus, reproducible sa sandbox)
| Adapter | P@5 | R@5 | Top-5 hit rate | p50 latency |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
100% top-5 hit rate sa **P@5 math ceiling** para sa corpus na ito (0.240, tingnan ang scorecard). Nakukuha ng hybrid ang bawat gold session; nawawala sa grep ang 1 sa 2 gold sa multi-session temporal query. Ang lift ay sa **recall + temporal**, hindi sa aggregate precision. Maliit at gold-sparse ang benchmark na ito; mas mahusay na nagkakaiba ang mas malaking LongMemEval-S sa ibaba. Buong per-type breakdown + correction note: [`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 tanong)
| Sistema | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| BM25-only fallback | 86.2% | 94.6% | 71.5% |
### Pagtitipid sa Token
| Pamamaraan | Tokens/yr | Cost/yr |
|---|---|---|
| I-paste ang buong context | 19.5M+ | Imposible (lumalagpas sa window) |
| Pinaikli ng LLM | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
| agentmemory + local embeddings | ~170K | **$0** |
> Embedding model: `all-MiniLM-L6-v2` (lokal, libre, walang API key). Kumpletong mga ulat: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Paghambing sa kompetisyon: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) na sumasaklaw sa agentmemory laban sa mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
**I-reproduce nang lokal:** [`eval/README.md`](../eval/README.md), isang adapter-pluggable harness para sa LongMemEval `_s` (public 500-Q) + `coding-agent-life-v1` (in-house na 15-session corpus). Nag-iiskor ang mga grep / vector / agentmemory adapter nang tabi-tabi, NDJSON output, dumadapo ang mga published scorecard sa [`docs/benchmarks/`](../docs/benchmarks/).
**Umaangkop sa [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), at [Graphify](https://github.com/safishamsi/graphify).** Code-graph indexing, multi-agent build pipeline, at mas malawak na knowledge graph sa mga docs / PDF / imahe / video. Naaalala ng agentmemory ang ginawang trabaho; pinapaliwanag naman ng tatlong project na ito ang iba pang bahagi ng context layer. Mga recipe + question-routing table: [`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
Built-in (CLAUDE.md)
Uri
Memory engine + MCP server
Memory layer API
Buong agent runtime
Personal AI
Memory API + app
Team memory hub (LLM proxy)
Vector memory (OSS)
Memory engine (Oracle DB)
Sistema ng memory
Static file
Retrieval R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
N/A
Sariling ulat
PersonaMem 76% (sariling ulat)
~96.6% (sariling ulat)
94.4% (sariling ulat)
N/A
N/A (grep)
Auto-capture
12 hook (walang manu-manong pagsisikap)
Manual na add() call
Sariling pag-edit ng agent
Manual
API-side extraction
Proxy interception (pagpalit ng base-URL)
Manual
API extraction
Manual
Manual na pag-edit
Paghahanap
BM25 + Vector + Graph (RRF fusion)
Vector + Graph
Vector (archival)
Semantic
Vector + RAG
4 uri ng asset (Chat / Skill / Wiki / CodeGraph)
Vector lamang
Vector + semantic
Decay-weighted
Nilo-load ang lahat sa context
Multi-agent
MCP + REST + lease + signal
API (walang coordination)
Sa loob lamang ng Letta runtime
Hindi
Hindi
Mga tungkulin sa team + shared asset
Hindi
Scoped lamang
Shared sa multi-agent
Per-agent na file
Framework lock-in
Wala (kahit anong MCP client)
Wala
Mataas (kailangang gamitin ang Letta)
Standalone
Wala
Proxy sa harap ng bawat model call
Wala
Oracle Database
Wala
Per-agent na format
Panlabas na deps
Wala (SQLite + iii-engine)
Qdrant / pgvector
Postgres + vector DB
Marami
Managed cloud
Docker stack (Core + Hub + Proxy)
Vector store
Oracle AI Database
Wala
Wala
Memory lifecycle
4-tier consolidation + decay + auto-forget
Passive extraction
Pinamamahalaan ng agent
Manual
Auto-forget
Manual review; isinasagawa pa ang auto-routing
Wala
Hindi nakasaad
Decay + consolidation
Manual na pruning
Kahusayan ng Token
~1,900 tokens/session ($10/yr)
Depende sa integration
Core memory sa context
Depende
Cloud pricing
Hindi nakasaad
Walang token budget
LLM-backed (depende)
Depende
22K+ tokens sa 240 obs
Real-time viewer
Oo (port 3113)
Cloud dashboard
Cloud dashboard
Web UI
Cloud dashboard
Hub web UI
Hindi
Hindi
Hindi
Hindi
Self-hosted
Oo (default)
Opsyonal
Opsyonal
Oo
Hindi (cloud-only)
Oo (Docker)
Oo
Oo (Oracle DB)
Oo
Oo
Tala sa benchmark: ang R@5 lamang ng agentmemory ang aming sariling nasukat na resulta (LongMemEval-S, reproducible mula sa benchmark/COMPARISON.md). Ang mga figure ng mem0 at Letta ay ang kanilang mga pinublikang numero sa LoCoMo (ibang dataset); ang mga figure ng MemPalace, supermemory, TencentDB (PersonaMem), at oracleagentmemory ay mga claim na self-reported ng vendor na hindi namin independent na-reproduce (ang run ng oracleagentmemory ay gumamit ng GPT-5.5 laban sa isang Oracle AI Database). Ipinapakita nang tabi-tabi para sa ballpark estimate lamang, hindi isang head-to-head sa parehong data. Ang bilang ng star ay tinatantya at nagbabago sa paglipas ng panahon.
**Mga bagong entrant** na dapat malaman, inihambing nang detalyado sa [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| Sistema | ⭐ | Anggulo |
|--------|---|-------|
| Zep / Graphiti | 30K | Temporal knowledge graph; ang pinakamalakas na pinublikang resulta sa temporal-query (LongMemEval 63.8%), pero bumubuo ang graph nang asynchronous kaya maaaring mahuli ang mga bagong fact |
| Cognee | 30K | Document-to-knowledge-graph ingestion, Python lamang, ginawa para sa structured entity extraction sa halip na session capture |
Walang isa man sa mga ito ang gumagawa ng auto-capture mula sa coding-agent hooks, nag-ship ng local-first viewer, o tumatakbo nang keyless — ang kombinasyong ito ang pinagbatayan ng agentmemory.
---
Compatibility: tinatarget ng release na ito ang `iii-sdk` 0.22.1 at nagpipin sa iii-engine v0.22.1.
### Subukan sa 30 Segundo
```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
```
Nag-seed ang `demo` ng 3 makatotohanang session (JWT auth, N+1 query fix, rate limiting) at pinapatakbo ang mga search laban dito. Pinapatay ng keyless install ang vectors, kaya dapat tumama ang mga `mem::search` keyword query gamit ang BM25 habang puwedeng magbalik ng zero ang `database performance optimization`. Maaari pang ibalik ng `smart-search` ang structural graph matches kapag umiiral ang graph data. Para mahanap ng semantic query ang N+1 fix gamit ang vectors, i-set ang `EMBEDDING_PROVIDER=local`, i-restart, at hintaying matapos ang unang pag-download ng model.
Buksan ang `http://localhost:3113` para panoorin ang live na pagbuo ng memory.
### I-validate ang Bagong Install at ang Persistence ng Restart
Habang tumatakbo ang server, patunayan ang REST, health, ang viewer, at ang status ng iii-backed runtime:
```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
```
Isinasaalang-alang ng startup ready panel ang lahat ng apat na port: REST/MCP HTTP sa 3111, iii streams sa 3112, ang viewer sa 3113, at ang iii worker WebSocket sa 49134. Kinukumpirma ng `status` ang health ng agentmemory at ang aktibong provider/embedding mode. I-save ang isang probe at kumpirmahin na searchable ito:
```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}'
```
Pagkatapos, patakbuhin ang `npx -y @agentmemory/agentmemory@latest stop`, simulan ulit ang standard na command sa Terminal 1, hintayin ang `/agentmemory/livez`, at ulitin ang search. Dapat pa ring ibalik ang probe. Kung pumili ka ng custom na `--data-dir`, ipasa ang parehong directory sa restart.
### Mga Pang-araw-araw na Command
Ang install at setup ay nasa [I-install](#install) sa itaas (gagabayan ka ng unang pagpapatakbo). Sa pang-araw-araw:
```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 ng Session
Replayable ang bawat session na itinatala ng agentmemory. Buksan ang viewer, piliin ang tab na **Replay**, at mag-scrub sa timeline: ang mga prompt, tool call, tool result, at response ay nag-render bilang hiwalay na event na may play/pause, speed control (0.5x hanggang 4x), at keyboard shortcut (space para i-toggle, arrow para mag-step).
Para dalhin ang mga mas lumang Claude Code JSONL transcript:
```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
```
Lumalabas ang mga imported session sa Replay picker kasama ang mga native. Sa ilalim ng hood, dumadaan ang bawat entry sa `mem::replay::load`, `mem::replay::sessions`, at `mem::replay::import-jsonl` iii functions, walang side-channel server. Ang bawat imported transcript ay na-index para sa search, tinatakan ng origin channel na `import`, at hinuhukay para sa isang session crystal at mga lesson.
> **Paalala kung aasa ka sa `import-jsonl` bilang pangunahing capture path:** Awtomatikong binubura ng `cleanupPeriodDays` ng Claude Code (sa `~/.claude/settings.json`, default na **30**) ang mga JSONL transcript na mas matanda sa window na iyon mula sa `~/.claude/projects/`. Kung mag-install ka ng bagong agentmemory sa isang Claude Code history na may edad na ilang buwan, wala na ang anumang mas matanda sa 30 araw bago pa man ang unang import. Patakbuhin ang `import-jsonl` sa isang cron, itaas ang `cleanupPeriodDays` sa mas mataas, o i-wire ang auto-capture hooks (ang default na plugin install path) para makarating sa agentmemory ang bawat turn habang live ang session at hindi na mahalaga ang JSONL cleanup.
### Upgrade / Maintenance
Gamitin ang maintenance command kapag sinasadya mong i-update ang iyong local runtime:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Babala: binabago ng command na ito ang kasalukuyang workspace/runtime. Maaari nitong i-update ang mga JavaScript dependency at kunin ang pinned na `iiidev/iii:0.22.1` Docker image. Hinding-hindi ito mag-install ng unpinned o mas bagong iii engine.
Nasa `src/cli.ts` ang mga detalye ng implementation (tingnan ang `runUpgrade` sa paligid ng `src/cli.ts:544-595` na region).
### Claude Code (isang block, i-paste ito)
```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 nang walang plugin install (MCP-standalone path)
Kung i-wire mo ang MCP server ng agentmemory gamit ang `~/.claude.json` nang direkta sa halip na gamitin ang `/plugin install`, hindi kailanman nireresolba ng Claude Code ang `${CLAUDE_PLUGIN_ROOT}` at kailangan mong ituro ang hook scripts sa absolute paths sa `~/.claude/settings.json`. Karaniwang naka-embed sa mga path na ito ang bersyon ng agentmemory (hal. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), kaya tahimik na masisira ng susunod na upgrade ang bawat hook.
Workaround:
```bash
agentmemory connect claude-code --with-hooks
```
Pinagsasama nito ang parehong hook commands sa `~/.claude/settings.json` gamit ang absolute paths na nireresolba sa bundled `plugin/` directory ng kasalukuyang naka-install na `@agentmemory/agentmemory` package. Patakbuhin ulit ang command pagkatapos i-upgrade ang agentmemory para i-refresh ang mga path. Napapanatili ang mga entry ng user sa parehong file; ang mga nakaraang entry ng agentmemory lamang ang napapalitan. Ang paggamit ng `/plugin install` path ay nananatiling inirerekomendang paraan.
Para sa remote o protected deployment, patakbuhin ang Claude Code na naka-set ang `AGENTMEMORY_URL` at `AGENTMEMORY_SECRET`. Ipinapasa ng plugin ang dalawang value papunta sa bundled MCP server nito; kapag walang laman ang `AGENTMEMORY_URL`, gumagamit ang MCP shim ng `http://localhost:3111`.
### Codex CLI (Codex plugin platform)
```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
```
Ang Codex plugin ay nag-ship mula sa parehong `plugin/` directory ng Claude Code plugin. Irehistro nito ang:
- Isang bundled stdio MCP bridge sa tumatakbong daemon, walang npm download o fallback store. Tingnan ang [local Codex guide](../docs/plugins/codex-local.md) para subukan ang isang unreleased build.
- 6 lifecycle hook: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 invocable na skill: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, kasama ang 8 reference skill na nilo-load ng agent kapag kailangan (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, at ang skill-authoring guide)
Itinuturok ng hook engine ng Codex ang `CLAUDE_PLUGIN_ROOT` sa mga hook subprocess (ayon sa [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), kaya gumagana ang parehong hook script sa dalawang host nang walang duplication. Ang mga event na Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure ay Claude-Code-only lamang at hindi nirerehistro para sa Codex.
#### Trust at compatibility ng Codex hook
Na-verify ang native plugin hook dispatch gamit ang Codex CLI 0.150.1. I-trust ang plugin hooks bago asahan ang capture. Ang behavior ng Desktop ay depende sa bundled runtime nito; i-check ang `/hooks` at kumpirmahin ang isang na-capture na event bago paganahin ang isang workaround.
Kapag kailangan ng host mo ang global hooks, i-mirror ang mga command sa `~/.codex/hooks.json`. Kapag naka-wire na ang MCP, kailangan ng kasalukuyang connector ang `--force` para maabot ang hook installation:
```bash
agentmemory connect codex --with-hooks --force
```
Pinagsasama nito ang global hooks at isinusulat ulit ang agentmemory MCP entry, habang napapanatili ang mga entry na walang kaugnayan. Suriin ang anumang custom na agentmemory endpoint settings mo bago gamitin ang `--force`. Patakbuhin ulit pagkatapos i-upgrade para i-refresh ang mga script path. Paganahin ang isa sa dalawa: native plugin hooks o global copies, para iwasan ang duplicate capture.
### GitHub Copilot CLI
Para sa VS Code agent mode, gamitin ang [Copilot MCP at automatic-capture guide](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Hindi i-configure ng CLI connector na ito ang 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
```
Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory` sa `~/.copilot/mcp-config.json` (o `$COPILOT_HOME/mcp-config.json` kapag naka-set ang `COPILOT_HOME`) at pinapanatili ang mga umiiral na server. Sa native Windows, ito lamang ang awtomatikong `connect` adapter; i-configure nang manu-mano ang lahat ng iba pang native Windows agent. Suportado lamang ang WSL `connect` kapag naka-install din ang target agent sa parehong WSL environment. Kukunin ng Copilot ang MCP server sa susunod na launch o pagkatapos ng `/mcp`. I-install din ang plugin kapag gusto mo ang buong hook/skill na karanasan.
OpenClaw (i-paste ang prompt na ito)
```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`.
```
Kumpletong gabay: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (i-paste ang prompt na ito)
```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.
```
Kumpletong gabay: [`integrations/hermes/`](../integrations/hermes/)
### Iba Pang Agent
Simulan ang memory server: `npx -y @agentmemory/agentmemory@latest`
#### Native na skill gamit ang `npx skills add` (50+ agent)
Nag-ship ang agentmemory ng 17 skill sa Claude-Code-style na `/SKILL.md` format: 9 invocable na action skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) at 8 reference skill na nilo-load ng agent kapag kailangan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). May dala ang mga reference skill na data table na nabuo mula sa source, kaya hindi ito kailanman nadrift. Ang [`skills`](https://npmjs.com/package/skills) CLI ng vercel-labs ay awtomatikong nag-install nito sa native skill directory ng tumatawag na agent sa 50+ agent (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, at iba pa):
```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
```
Ito ay **komplementaryo** sa `agentmemory connect `:
- Isusulat ng `agentmemory connect ` ang MCP server config para magamit ang mga tool.
- I-install ng `npx skills add rohitg00/agentmemory` ang mga skill para malaman ng agent kung kailan ito tatawagin.
Para sa ilang agent na hindi pa saklaw ng skills CLI (Zed v1.3.x pababa), ilagay mo mismo ang 17 SKILL.md file sa ilalim ng native skill directory ng agent; gumagana ang parehong format kahit saan.
#### Standard na MCP Block
Ang entry ng agentmemory ay ang **parehong MCP server block** sa bawat host na gumagamit ng `mcpServers` shape (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}"
}
}
```
**I-merge ang entry na ito sa umiiral na `mcpServers` object** sa config file ng host; huwag palitan ang file. Kung may iba na ang file na mga server, idagdag ang `agentmemory` sa tabi nila bilang isa pang key sa loob ng `mcpServers`. Kung wala talaga ang `mcpServers`, i-paste ang block sa loob ng `{ "mcpServers": { ... } }`. Minana ng mga `${VAR}` placeholder ang `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` mula sa shell sa oras ng paglunsad ng MCP server; nagpapasa ng walang-lamang string ang mga unset var at babalik ang shim sa `http://localhost:3111`. Sapat ang isang wired na entry para sa local at remote (k8s / reverse-proxied) deployment.
| Agent | Config file | Mga Tala |
|---|---|---|
| **Cursor (MCP lamang)** | `~/.cursor/mcp.json` | I-merge sa `mcpServers`, o `agentmemory connect cursor`. May one-click deeplink din sa website. |
| **Cursor (buong plugin)** | `.cursor-plugin/` | Listing sa Cursor Marketplace (nasa review ang submission) o Cursor Settings → Plugins → local checkout. Nirerehistro ang 7 auto-capture hook (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + ang MCP server, na pinamamahalaan ang `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` sa plugin dashboard ng Cursor. Gumagana sa Cursor IDE at `cursor-agent` CLI; ang mga print-mode prompt ng CLI ay binackfill mula sa session transcript sa katapusan ng session. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | I-merge sa `mcpServers`. I-restart ang Claude Desktop pagkatapos i-edit. |
| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Parehong `mcpServers` block. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | Pinagsasama ng `agentmemory connect devin` ang MCP entry; idinadagdag ng `--with-hooks` ang anim na native na auto-capture hook (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) gamit ang lowercase na tool matcher ng Devin. Patunayan gamit ang `devin mcp list` at `/hooks` sa loob ng devin. |
| **Devin CLI (buong plugin)** | `plugin/.devin-plugin/` | Nirerehistro ng `devin plugins install ./plugin` mula sa isang checkout ang lahat ng 17 skill bilang `/agentmemory:` slash command kasama ang MCP server. Hindi kayang paandarin ng Devin plugin hooks ang `SessionStart`/`SessionEnd`, kaya ipares ito sa `connect devin --with-hooks` para sa buong session capture. |
| **Devin (cloud)** | Settings → Connections → MCP servers | Magdagdag ng custom na MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` na itinuturo sa isang network-reachable na agentmemory deployment kasama ang `AGENTMEMORY_SECRET` (hindi maaabot ng cloud session ang localhost — tingnan ang [`deploy/`](../deploy/)). Itago ang secret sa Devin Secrets, pagkatapos gamitin ang "Test listing tools" para patunayan na lumalabas ang lahat ng 54 tool. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (awtomatikong nag-merge). |
| **GitHub Copilot CLI (MCP lamang)** | `~/.copilot/mcp-config.json` | Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory`; kukunin ito ng Copilot sa susunod na launch o `/mcp`. |
| **GitHub Copilot CLI (buong plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` para sa plugin mula sa GitHub subdir. |
| **OpenClaw** | OpenClaw MCP config | Parehong `mcpServers` block. Mas malalim: angkin ng `openclaw plugins install ./integrations/openclaw` ang memory slot ng OpenClaw (awtomatikong lilipat mula sa `memory-core`); i-set ang `plugins.entries.agentmemory.hooks.allowConversationAccess=true` o tahimik na haharangin ang turn capture. Tingnan ang [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (MCP lamang)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, o idagdag ang `[mcp_servers.agentmemory]` nang manu-mano. |
| **Codex CLI (buong plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` pagkatapos `codex plugin add agentmemory@agentmemory`. Nirerehistro ang MCP + 6 lifecycle hook + 17 skill. I-trust ang hooks at i-verify ang capture sa host mo; tingnan ang [Codex setup at validation](../docs/plugins/codex-local.md). |
| **OpenCode (MCP lamang)** | `opencode.json` | Ibang shape: top-level na `mcp` key, command bilang array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (buong plugin)** | `plugin/opencode/` | 22 auto-capture hook na sumasaklaw sa session lifecycle, messages, tools, errors. Per-session ang project attribution, kaya ang isang OpenCode process na saklaw ang ilang repository ay nagtatala ng bawat session sa ilalim ng sarili nitong project. Dalawang slash command (`/recall`, `/remember`). Kopyahin ang `plugin/opencode/` sa iyong OpenCode workspace at idagdag ang plugin entry sa `opencode.json`. Tingnan ang [`plugin/opencode/README.md`](../plugin/opencode/README.md) para sa buong hook table + gap analysis. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | Ini-install ng `agentmemory connect pi` ang bundled extension sa auto-discovery directory ng pi (recall sa agent start, capture sa agent end, mga tool na `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). Kukunin ito ng `/reload` sa isang tumatakbong pi. [`integrations/pi`](../integrations/pi/) ay isa rin pi package (`pi install ./integrations/pi` mula sa isang checkout). |
| **Hermes Agent** | `~/.hermes/config.yaml` | Ang `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ay magbibigay ng 6-hook na memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block). Patunayan gamit ang `hermes plugins doctor` at `hermes memory status`. Tingnan ang [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | Isinusulat ng `agentmemory connect qwen` ang standard na `mcpServers` block. Field-compatible ang hook payload sa Claude Code, kaya gumagana ang umiiral na 12-hook scripts nang walang pagbabago; i-wire ito gamit ang `hooks` section sa parehong `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | Ini-install ng `agentmemory connect antigravity --with-hooks` ang MCP at capture hooks sa shared customization directory. Tingnan ang [setup at limitasyon ng Antigravity](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | Ginagamit ng `agentmemory connect antigravity-cli --with-hooks` ang parehong MCP at hook configuration ng kasalukuyang mga bersyon ng IDE. Dapat i-refresh ng mga umiiral na installation gamit ang `--force`; tingnan ang [upgrade notes](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | Isinusulat ng `agentmemory connect kiro` ang user-level config. Ang workspace override ay sa `.kiro/settings/mcp.json`, katabi ng iyong code. |
| **Warp** | `~/.warp/.mcp.json` | Isinusulat ng `agentmemory connect warp` ang standard na `mcpServers` block. Awtomatikong nadidiskubre din ng Warp ang mga skill mula sa `.claude/skills/`; kapag naka-install na ang Claude Code plugin, lumalabas nang native ang 8 agentmemory skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) sa slash-command palette ng Warp. |
| **Cline (CLI)** | `~/.cline/mcp.json` | Isinusulat ng `agentmemory connect cline` ang standard na `mcpServers` block. Para sa VS Code extension user: i-paste ang parehong block sa Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (preferred) o `config.json` (legacy) | Gumagawa ang `agentmemory connect continue` ng `config.yaml` mula sa simula kapag walang alinman, o binabago ang umiiral na `config.json`. **Kung may `config.yaml` ka na** ipi-print ng adapter ang eksaktong block na i-paste sa ilalim ng `mcpServers:`; hindi nito tahimik na isusulat ulit ang yaml mo dahil ang pagpapanatili ng comments at anchors nang ligtas ay nangangailangan ng YAML parser na hindi dala ng package. Gumagamit ang Continue ng array form (hindi object) para sa `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | Isinusulat ng `agentmemory connect zed` sa ilalim ng `context_servers` (ang key ng Zed, HINDI `mcpServers`). Maaaring i-wire ang remote MCP server gamit ang `{"url": "..."}` sa halip. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | Isinusulat ng `agentmemory connect droid` ang standard na `mcpServers` block. Ang project-scoped override ay sa `/.factory/mcp.json`. Ipasa ang `--with-hooks` para sa native auto-capture. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Idinadagdag ng `agentmemory connect dsh` ang isang `@deepseek-ai/dsh-mcp-client` row sa home-level patch layer na nilo-load ng bawat Harness profile; nagrerehistro ang mga tool bilang `mcp__agentmemory__*`. Ipasa ang `--with-hooks` para i-wire din ang auto-capture: tumatakbo ang bundled Claude Code hook scripts sa first-party na `@deepseek-ai/dsh-hooks-claude-code` bridge ng Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) gamit ang manifest na isinulat sa `$DSH_HOME/agentmemory.hooks.json`. Default sa `~/.dsh` kapag walang `DSH_HOME`. |
| **Goose** | Goose MCP settings UI | Parehong `mcpServers` block; gamitin ang `goose configure` → Add Extension → MCP. Suportado ang direktang YAML edit sa `~/.config/goose/config.yaml` pero ang schema ay gumagamit ng `extensions:` + `cmd` (hindi `mcpServers:` + `command`). |
| **Aider** | n/a | Kausapin ang REST API nang direkta: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Anumang agent (32+)** | n/a | Awtomatikong tinutuklas at pinagsasama ng `npx skillkit install agentmemory` ang host. |
**Mga sandboxed MCP client** (Flatpak / Snap / restrictive container) na hindi maabot ang `localhost` ng host: i-set din ang `"AGENTMEMORY_FORCE_PROXY": "1"` sa `env` block, at ituro ang `AGENTMEMORY_URL` sa isang route na talagang maabot ng sandbox (hal. ang LAN IP mo).
### Programmatic access (Python / Rust / Node)
Irehistro ng agentmemory ang mga core operation nito bilang iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Maaari silang tawagin nang direkta ng anumang wika na may iii SDK sa `ws://localhost:49134`, walang kailangang hiwalay na REST client bawat wika.
```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"},
})
```
Halimbawang gawa: [`examples/python/`](../examples/python/) (quickstart + observation/recall flow). Available pa rin ang REST sa `:3111` para sa mga host na walang iii runtime.
### Mula sa Source
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
Sinisimulan nito ang agentmemory gamit ang lokal na `iii-engine` kung naka-install na ang pinned binary, o gumagamit ng Docker Compose kapag ito ang pinili. Nagbibind ang REST, streams, at ang viewer sa `127.0.0.1` bilang default. Ang automatic na binary path sa macOS/Linux ay nangangailangan ng `curl`, isang POSIX `sh`, at `tar`.
I-install nang manu-mano ang `iii-engine`. **Nagpipin ang agentmemory sa kasalukuyan ang `iii-engine` sa `v0.22.1`**, kaparehong release ng dependency nitong `iii-sdk`; kinakausap ng worker ang wire protocol ng engine na iyon, at ni-reorganize ng 0.20.0 ang SDK surface, kaya magkasamang kumikilos ang dalawa sa mga release ng agentmemory. I-override gamit ang `AGENTMEMORY_III_VERSION=` kung may sariling engine ka at alam mong tugma ito.
- **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:** palitan ang `aarch64-apple-darwin` ng `x86_64-apple-darwin`
- **Linux x64:** palitan ng `x86_64-unknown-linux-gnu`
- **Linux arm64:** palitan ng `aarch64-unknown-linux-gnu`
- **Windows:** i-download ang `iii-x86_64-pc-windows-msvc.zip` mula sa [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) at i-extract ang `iii.exe` sa `%USERPROFILE%\.agentmemory\bin\iii.exe`
May kaparehong `.sha256` file ang bawat archive sa release page; kapag pinalitan mo ang platform, gamitin ang hash ng file na iyon sa check sa itaas (sa Windows: `Get-FileHash`). Pinned ng automatic installer sa `npx @agentmemory/agentmemory` ang mga hash na ito at tatanggihan ang anumang archive na hindi tumugma.
O gamitin ang Docker (ang bundled na `docker-compose.yml` ay kinukuha ang `iiidev/iii:0.22.1`). Kumpletong docs: [iii.dev/docs](https://iii.dev/docs).
### Windows
Tumatakbo ang agentmemory sa Windows 10/11, pero hindi sapat ang Node.js package lamang; kailangan mo rin ang pinned iii-engine v0.22.1 runtime bilang background process. Hindi awtomatikong nireextract ng CLI ang Windows ZIP, kaya ang mga native Windows user ay dapat i-install nang manu-mano ang `iii.exe`, gamitin ang WSL2, o piliin ang Docker Desktop.
Sinusuportahan lamang ng native Windows automated MCP wiring ang `agentmemory connect copilot-cli`. Para sa Claude Code, Codex, Cursor, at lahat ng iba pang native Windows agent, kopyahin ang manual na MCP block mula sa [Iba Pang Agent](#other-agents) papunta sa Windows config ng agent na iyon. Angkop lamang ang pagpapatakbo ng `connect` sa WSL kapag naka-install din ang target agent sa parehong WSL environment; hindi nito ina-edit ang config ng isang Windows-host agent.
**Opsyon A: prebuilt na Windows binary (inirerekomenda)**
```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
```
**Opsyon 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
```
**Opsyon C: standalone MCP lamang (walang engine).** Kung kailangan mo lamang ng mga MCP tool para sa iyong agent at hindi kailangan ang REST API, viewer, o cron job, laktawan nang buo ang engine:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Diagnostics para sa Windows:** kung nabigo ang `npx -y @agentmemory/agentmemory@latest`, patakbuhin ulit ito gamit ang `--verbose` para makita ang aktwal na engine stderr. Mga karaniwang mode ng pagkabigo:
| Sintoma | Fix |
|---|---|
| `The engine process started but the REST API never responded.` | Kumpirmahin na libre ang lahat ng apat na derived port, i-verify na buhay pa ang pinned na `iii.exe`, pagkatapos patakbuhin ulit gamit ang `--verbose` at suriin ang nakuhang engine stderr |
| `Could not start iii-engine` | Walang naka-install na `iii.exe` o Docker. Tingnan ang Opsyon A o B sa itaas |
| Port conflict | `netstat -ano \| findstr :3111` para makita ang nakabind, pagkatapos patayin ito o gamitin ang `--port ` |
| Nalaktawan ang Docker fallback kahit naka-install ang Docker | Siguraduhing talagang tumatakbo ang Docker Desktop (icon sa system tray) |
> Tala: ang **engine** ng iii ay isang prebuilt binary, hindi isang cargo crate, kaya huwag subukang `cargo install` ito. (Pinublika ang mga **SDK** ng iii sa crates.io, npm, at PyPI, pero hindi ito kailangan ng agentmemory.) Lahat ng supportadong paraan ng pag-install ng engine ay pinned sa v0.22.1: ang prebuilt binary sa itaas, ang macOS/Linux auto-install path ng agentmemory (kinakailangan ang `curl`, POSIX `sh`, at `tar`), at ang Docker image na `iiidev/iii:0.22.1`. Ang bare upstream na `install.sh | sh` ay nag-install ng pinakabagong engine, na hindi suportado ng agentmemory. Gamitin ang `npx -y @agentmemory/agentmemory@latest`; sa macOS/Linux kinukuha nito ang pinned engine papunta sa `~/.agentmemory/bin`.
---
Pag-deploy
Mga one-click template para sa managed host. Bawat isa ay nag-ship ng
self-contained na Dockerfile na kumukuha ng `@agentmemory/agentmemory` mula sa
npm at kinokopya ang iii engine binary mula sa opisyal na `iiidev/iii` Docker
Hub image; walang kailangang pre-built na agentmemory image. Nagbibind ang
persistent storage sa `/data`; ang first-boot entrypoint ay nag-o-override sa
npm-bundled na iii config (na nagbibind sa `127.0.0.1`) ng isang
deploy-tuned na config na nagbibind sa `0.0.0.0` at gumagamit ng absolute na
`/data` path, bumubuo ng HMAC secret, pagkatapos nagbababa ng privileges mula
sa `root` papuntang `node` gamit ang `gosu` bago i-exec ang agentmemory CLI.
Kinakailangan ng one-click deploy button ng Render ang `render.yaml` sa repository root, na sinadya naming panatilihing malinis. Gamitin ang Render Blueprint flow na nakadokumento sa [`deploy/render/`](.././deploy/render/README.md) para ituro nang manu-mano ang in-repo blueprint.
Nasa [`deploy/`](.././deploy/README.md) ang kumpletong detalye ng setup (HMAC capture, viewer SSH tunnel, rotation, backup, cost floor):
- [`deploy/fly`](.././deploy/fly/README.md): isang machine na may
`auto_stop_machines = "stop"`; pinakamura kapag idle.
- [`deploy/railway`](.././deploy/railway/README.md): Hobby plan na flat fee,
volume sa dashboard.
- [`deploy/render`](.././deploy/render/README.md): Blueprint flow,
awtomatikong disk snapshot sa mga paid plan.
- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted sa sariling
VPS mo gamit ang [Coolify](https://coolify.io/self-hosted); parehong Docker
Compose stack, ikaw ang may-ari ng host at ng data.
Port `3111` lamang ang pinublish. Nananatiling bound sa loopback sa loob ng
container ang viewer sa `3113`; nakadokumento sa README ng bawat template ang
SSH-tunnel pattern para maabot ito.
---
Nakakalimutan ng bawat coding agent ang lahat kapag natapos ang session, at ang bawat bagong session ay nagsisimula sa muling pagpapaliwanag mo ng iyong stack. Tumatakbo ang agentmemory sa background at aalisin ang hakbang na ito.
```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.
```
### Kumpara sa Built-in na Memory ng Agent
Nag-ship ang bawat AI coding agent na may built-in memory: may `MEMORY.md` ang Claude Code, may notepad ang Cursor, may memory bank ang Cline. Gumagana ang mga ito gaya ng sticky note. Ang agentmemory ang searchable database sa likod ng mga sticky note.
| | Built-in (CLAUDE.md) | agentmemory |
|---|---|---|
| Sukat | 200-linyang cap | Walang Limitasyon |
| Paghahanap | Nilo-load ang lahat sa context | BM25 + vector + graph (top-K lamang) |
| Gastos sa Token | 22K+ sa 240 obserbasyon | ~1,900 token (92% mas kaunti) |
| Cross-agent | Per-agent na file | MCP + REST (kahit anong agent) |
| Koordinasyon | Wala | Lease, signal, action, routine |
| Observability | Basahin ang mga file nang manu-mano | Real-time viewer sa :3113 |
---
### Memory Pipeline
```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
```
### 4-Tier Memory Consolidation
Hinubog batay sa paano pinoproseso ng utak ng tao ang memory, kasama ang sleep consolidation.
| Tier | Ano | Analohiya |
|------|------|---------|
| **Working** | Raw na obserbasyon mula sa paggamit ng tool | Panandaliang memory |
| **Episodic** | Pinaikling buod ng session | "Ano ang Nangyari" |
| **Semantic** | Mga nakuhang fact at pattern | "Ano ang Alam Ko" |
| **Procedural** | Mga workflow at decision pattern | "Paano Ito Gawin" |
Nauupos ang mga memory sa paglipas ng panahon (Ebbinghaus curve). Lumalakas ang mga madalas i-access na memory. Awtomatikong naaalis ang mga stale na memory. Nadidiskubre at naresolba ang mga kontradiksyon.
### Ano ang Nakukuha
| Hook | Nakukuha |
|------|----------|
| `SessionStart` | Project path, session ID |
| `UserPromptSubmit` | User prompt (privacy-filtered) |
| `PreToolUse` | File access pattern + enriched context |
| `PostToolUse` | Tool name, input, output |
| `PostToolUseFailure` | Error context |
| `PreCompact` | Itinuturok ulit ang memory bago ang compaction |
| `SubagentStart/Stop` | Sub-agent lifecycle |
| `Stop` | Buod sa katapusan ng session |
| `SessionEnd` | Marker ng kumpletong session |
### Mga Pangunahing Kakayahan
| Kakayahan | Paglalarawan |
|---|---|
| **Awtomatikong capture** | Naitatala ang bawat paggamit ng tool gamit ang hooks, walang manu-manong pagsisikap |
| **Semantic search** | BM25 + vector + knowledge graph na may RRF fusion |
| **Ebolusyon ng memory** | Versioning, supersession, relationship graph |
| **Recall hygiene** | Umaalis sa search index ang mga superseded na bersyon ng memory; pinapanatili ng version chain sa KV ang buong history |
| **Near-duplicate hint** | Nag-uulat ang mga save ng advisory na `similarTo` match kapag malapit na kahawig ng umiiral na memory ang bagong content |
| **Per-agent scoping** | Dumadaan ang `agentId` sa save at recall sa REST, MCP, at ang search index, sa shared o isolated mode |
| **Write-time provenance** | May dalang hindi-nababagong origin channel (user, agent, tool, import, o shared) ang bawat obserbasyon at memory, na tinatakan sa capture, save, at import |
| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction |
| **Privacy muna** | Tinatanggal ang mga API key, secret, `` tag bago ang storage |
| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring |
| **Claude bridge** | Bi-directional sync sa MEMORY.md |
| **Knowledge graph** | Entity extraction + BFS traversal |
| **Team memory** | Namespaced shared + private sa mga miyembro ng team |
| **Citation provenance** | Subaybayan ang anumang memory pabalik sa source observation |
| **Git snapshot** | I-version, i-rollback, at i-diff ang memory state |
---
Triple-stream retrieval na pinagsasama ang tatlong signal:
| Stream | Ano ang Ginagawa Nito | Kailan |
|---|---|---|
| **BM25** | Stemmed keyword matching na may synonym expansion | Palaging naka-on |
| **Vector** | Cosine similarity sa dense embeddings | Naka-configure ang embedding provider |
| **Graph** | Knowledge graph traversal gamit ang entity matching | May nadetektang entity sa query |
Pinagsasama gamit ang Reciprocal Rank Fusion (RRF, k=60) at session-diversified (max 3 resulta kada session).
Kapag napupuno ang isang vector index, ginagamit ng `mem::search` (sa likod ng `memory_recall`) ang hybrid na BM25 + vector ranker. Kapag walang embeddings, ginagamit nito ang BM25. Maaari pang pagsamahin ng `smart-search` ang structural graph matches kapag umiiral ang graph data, kasama na sa keyless mode. Tumatakbo ang lesson recall sa isang dedikadong in-memory BM25 index sa halip na i-scan ang buong corpus kada query. Hindi kasama sa bawat recall path ang mga superseded na bersyon ng memory; pinapanatili ng version chain ang kanilang history.
Nakaligtas ang mga vector sa isang crash o force-kill. Nasa-save ang vector index sa mga bucket sa pinakamadalas na bawat `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minuto). Bawat vector na idinagdag o inalis sa gitna ay agad na isinusulat din sa isang maliit na pending log sa state store, at ni-replay ito ng susunod na start nang hindi tinawag ang embedding provider. Ang bawat matagumpay na save ay nagwawalang-laman sa log. Ang mga documento na wala pa ring vector pagkatapos ng replay ay re-embedded sa background sa mga batch ng `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) hanggang maubos ang lahat, at ang backfill na natigil ay magpapatuloy sa susunod na start. Ipinapakita ng `/agentmemory/status` at ng viewer ang laki ng pending log at ang estado ng backfill. Walang isinusulat ang mga keyless install.
Tinotokenize ng BM25 ang Griyego, Cyrillic, Hebreo, Arabic, at accented Latin nang out of the box. Para sa mga memory sa Chinese / Japanese / Korean, i-install ang opsyonal na segmenter (`npm install @node-rs/jieba tiny-segmenter`) para hatiin ang mga CJK run sa word-level token; kung wala ito, soft-falls ang agentmemory sa whole-run tokenization at nagprint ng one-time hint sa stderr.
### Mga Embedding Provider
Pinapatay ng keyless install ang vector embeddings: ginagamit ng `mem::search` ang BM25, habang maaari pang gamitin ng `smart-search` ang umiiral na structural graph data. Para opt in sa libreng on-device semantic embeddings, idagdag ito sa `~/.agentmemory/.env` at i-restart ang agentmemory:
```env
EMBEDDING_PROVIDER=local
```
Kasama sa normal na npm install ang opsyonal na `@huggingface/transformers` runtime. Nag-download ang unang embedding request ng `Xenova/all-MiniLM-L6-v2`, kaya kailangan nito ng network access at maaaring tumagal; tumatakbo na on-device ang susunod na inference. Awtomatikong nadidiskubre ang mga remote provider mula sa kanilang keys maliban kung na-override ito ng `EMBEDDING_PROVIDER`.
| Provider | Model | Gastos | Mga Tala |
|---|---|---|---|
| **Local (inirerekomendang opt-in)** | `all-MiniLM-L6-v2` | Libre | On-device pagkatapos ng unang pag-download ng model, +8pp recall kaysa sa BM25-only |
| Gemini | `gemini-embedding-001` | Free tier | 100+ wika, 768/1536/3072 dims (MRL), 2048-token input. Pumalit sa `text-embedding-004` ([deprecated, magsasara noong Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | Pinakamataas na kalidad |
| Voyage AI | `voyage-code-3` | Bayad | Na-optimize para sa code |
| Cohere | `embed-english-v3.0` | Free trial | Pangkalahatang gamit |
| OpenRouter | Kahit anong model | Depende | Multi-model proxy |
---
54 na tool, 6 na resource, 3 na prompt, at 17 na skill.
> **MCP shim laban sa buong server:** ang pinublish na `@agentmemory/mcp` package ay isang manipis na shim. Ilalantad nito ang buong 54-tool surface **lamang kapag kaya nitong maabot ang isang tumatakbong agentmemory server** gamit ang `AGENTMEMORY_URL` (proxy mode). Kung walang maabot na server, babalik ang shim sa isang 7-tool na lokal na set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Ang `AGENTMEMORY_TOOLS=core|all` env var ay isang *server-side* na flag; walang epekto ang pag-set nito sa `env` block ng shim. Kung 7 tool lamang ang nakikita mo sa Cursor / OpenCode / Gemini CLI, simulan ang `npx -y @agentmemory/agentmemory@latest` (o ang Docker stack) at i-set ang `AGENTMEMORY_URL=http://localhost:3111`.
### 54 na Tool
Tatlong tool surface, mula sa pinakamaliit hanggang pinakamalaki: binabawasan ng `AGENTMEMORY_TOOLS=core` ang visibility sa 8 mahahalagang tool (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); ang base set sa ibaba ay ang 14 foundational tool ng registry; ang default (`AGENTMEMORY_TOOLS=all`) ay ilalantad ang lahat ng 54.
Base tool (14)
| Tool | Paglalarawan |
|------|-------------|
| `memory_recall` | Hanapin ang nakaraang obserbasyon |
| `memory_compress_file` | I-compress ang mga markdown file habang pinapanatili ang structure |
| `memory_save` | I-save ang isang insight, desisyon, o pattern |
| `memory_file_history` | Mga nakaraang obserbasyon tungkol sa partikular na file |
| `memory_patterns` | Tuklasin ang mga umuulit na pattern |
| `memory_sessions` | Ilista ang mga kamakailang session |
| `memory_smart_search` | Hybrid semantic + keyword search |
| `memory_vision_search` | Hanapin ang mga obserbasyon ng imahe |
| `memory_timeline` | Obserbasyon ayon sa pagkakasunod-sunod ng oras |
| `memory_profile` | Profile ng project (concept, file, pattern) |
| `memory_export` | I-export ang lahat ng memory data |
| `memory_relations` | Query ang relationship graph |
| `memory_commit_lookup` | Mga session sa likod ng isang git commit |
| `memory_commits` | Mga commit na naitala para sa isang session |
Extended tool (54 lahat, ang default surface)
| Tool | Paglalarawan |
|------|-------------|
| `memory_patterns` | Tuklasin ang mga umuulit na pattern |
| `memory_timeline` | Obserbasyon ayon sa pagkakasunod-sunod ng oras |
| `memory_relations` | Query ang relationship graph |
| `memory_graph_query` | Knowledge graph traversal |
| `memory_consolidate` | Patakbuhin ang 4-tier consolidation |
| `memory_claude_bridge_sync` | I-sync sa MEMORY.md |
| `memory_team_share` | Ibahagi sa mga miyembro ng team |
| `memory_team_feed` | Mga kamakailang ibinahaging item |
| `memory_audit` | Audit trail ng mga operation |
| `memory_governance_delete` | Burahin na may audit trail |
| `memory_snapshot_create` | Git-versioned na snapshot |
| `memory_action_create` | Gumawa ng work item na may dependency |
| `memory_action_update` | I-update ang status ng action |
| `memory_frontier` | Mga unblocked na action na naayos ayon sa priority |
| `memory_next` | Ang pinakamahalagang susunod na action |
| `memory_lease` | Exclusive na action lease (multi-agent) |
| `memory_routine_run` | I-instantiate ang mga workflow routine |
| `memory_signal_send` | Pagmemensahe sa pagitan ng agent |
| `memory_signal_read` | Basahin ang mga mensahe na may receipt |
| `memory_checkpoint` | Panlabas na condition gate |
| `memory_mesh_sync` | P2P sync sa pagitan ng instance |
| `memory_sentinel_create` | Event-driven na watcher |
| `memory_sentinel_trigger` | Patakbuhin ang mga sentinel mula sa labas |
| `memory_sketch_create` | Ephemeral na action graph |
| `memory_sketch_promote` | I-promote sa permanente |
| `memory_crystallize` | I-compact ang mga action chain |
| `memory_diagnose` | Health check |
| `memory_heal` | Awtomatikong ayusin ang stuck na state |
| `memory_facet_tag` | Dimension:value tag |
| `memory_facet_query` | Query ayon sa facet tag |
| `memory_verify` | Subaybayan ang provenance |
### 6 Resource · 3 Prompt · 17 Skill
| Type | Pangalan | Paglalarawan |
|------|------|-------------|
| Resource | `agentmemory://status` | Health, bilang ng session, bilang ng memory |
| Resource | `agentmemory://project/{name}/profile` | Per-project intelligence |
| Resource | `agentmemory://project/{name}/recent` | Mga kamakailang obserbasyon para sa isang project |
| Resource | `agentmemory://memories/latest` | Pinakabagong 10 aktibong memory |
| Resource | `agentmemory://graph/stats` | Statistics ng knowledge graph |
| Resource | `agentmemory://team/{id}/profile` | Shared na profile ng team |
| Prompt | `recall_context` | Maghanap + ibalik ang mga context message |
| Prompt | `session_handoff` | Handoff data sa pagitan ng agent |
| Prompt | `detect_patterns` | Suriin ang mga umuulit na pattern |
| Skill | `/recall` | Hanapin ang memory |
| Skill | `/remember` | I-save sa long-term memory |
| Skill | `/session-history` | Mga buod ng kamakailang session |
| Skill | `/forget` | Burahin ang mga obserbasyon/session |
Ipinapakita ng table ang apat na core skill. Ang buong set ay 9 invocable na skill kasama ang 8 reference skill; tingnan ang Native skills section sa itaas.
### Standalone MCP
Patakbuhin nang walang buong server, para sa kahit anong MCP client. Gumagana ang alinman sa mga ito:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
O idagdag sa MCP config ng iyong agent:
Karamihan sa mga agent (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
I-merge ang entry ng `agentmemory` sa umiiral na `mcpServers` object ng host sa halip na palitan ang file. Para sa mga sandboxed client na hindi maabot ang `localhost` ng host, idagdag ang `"AGENTMEMORY_FORCE_PROXY": "1"` sa env block at i-set ang `AGENTMEMORY_URL` sa isang route na maaabot ng sandbox.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Kopyahin ang plugin file mula sa repo:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
Awtomatikong nagsisimula sa port `3113`. Nag-load ang viewer ng isang snapshot kapag kumonekta ito (`GET /agentmemory/viewer/snapshot`) at pagkatapos ay ilalapat ang mga live stream event: lumalabas ang mga bagong memory, lesson, obserbasyon, audit entry, pagbabago sa graph, at health update nang walang polling o page reload. Ang iba lamang na request ay ang mga action na iyong kinliklik, ang mga "load more" page at search. Kapag nawala ang stream, ipinapakita ng viewer kung gaano na katanda ang mga numero nito, kumokonekta ulit nang may backoff at nireresync mula sa isang snapshot.
- **12 tab sa apat na grupo** na may live count, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), keyboard shortcut at isang mobile menu.
- **Memories:** server-side search, filter ayon sa project, agent, at type, isang detail panel na may version chain at word diff, provenance link, copy button para sa id, ang MCP call at isang curl command, edit (bagong bersyon), forget na may confirmation, bulk forget at JSON export.
- **Sessions:** inline na observation timeline na may nababasang tool input at output, filter at paging, at ang mga memory at lesson na nabuo ng bawat session.
- **Graph:** search, detalye ng node na may relation at source, isang legend na hindi umaasa sa kulay lamang, at zoom control.
- **Health:** ang live na bersyon ng `GET /agentmemory/status`. May kasamang fix ang bawat problema, kasama ang state backend, index save state, progress ng graph provenance compaction, at isang consolidation explainer na may tunay na threshold.
- Mga pahina ng **Audit, Activity, Profile, Replay, Lessons, Actions, at Crystals**, na bawat isa ay may empty state na nagsasabi kung ano ang section, bakit ito walang laman, at ang command na magpupuno nito, at isang `?` glossary tooltip sa bawat termino at numero.
```bash
open http://localhost:3113
```
Nagbibind ang viewer server sa `127.0.0.1` bilang default at idinadagdag nito ang server secret kapag ipinapasa ang mga request sa REST API, kaya walang kailangang i-setup. Sumusunod ang `/agentmemory/viewer` endpoint na naka-serve sa REST sa normal na bearer-token rules at nireredirect ang mga browser na walang token papunta sa viewer port. Gumagamit ang CSP headers ng per-response script nonce at pinapatay ang inline handler attributes (`script-src-attr 'none'`).
---
Ipinapakita ng viewer sa `:3113` ang **naalala** ng iyong agent. Ipinapakita ng [iii console](https://iii.dev/docs/console) ang **ginawa** ng iyong agent: bawat memory op bilang isang OpenTelemetry trace, bawat KV entry na maaaring i-edit, bawat function na maaaring i-invoke, bawat stream na maaaring tapp-in. Dalawang bintana sa parehong memory: isang product-shaped, isang engine-shaped.
Panoorin ang pagputok ng isang `memory_smart_search` at tingnan ang BM25 scan → embedding lookup → RRF fusion → reranker bilang isang waterfall. I-edit ang isang stuck na consolidation timer sa KV browser. I-replay ang isang `PostToolUse` hook na may tinweak na payload. I-pin ang WebSocket stream at panoorin ang mga obserbasyon na dumarating nang live.
Ibinibigay ito ng agentmemory nang libre dahil ang bawat function call at trigger ay dumadaan sa iii; walang custom, walang kailangang i-instrument.
Pahinang Workers: bawat kakonektang worker, kasama ang agentmemory mismo, na may PID, function count, runtime, at last-seen.
**Naka-install na.** Nag-ship ang console kasama ang pinned na `iii` engine (0.22+); walang hiwalay na i-install. Nag-download ang unang launch ng console binary sa tabi ng engine.
**Ilunsad kasabay ng agentmemory:**
```bash
agentmemory console
```
Pinapatakbo nito ang `iii console` ng pinned engine laban sa mga port na nireresolba ng agentmemory (REST, streams, bridge) at ipinapakita ito sa isang port sa itaas ng viewer, `http://localhost:3114` bilang default. Pumipili ang `--console-port N` ng ibang port; pinipili ng `--port` at `--instance` ang instance ng agentmemory sa parehong paraan tulad nila para sa `stop`; ipinapasa ang anumang ibang flag, halimbawa ang `--enable-flow` para sa experimental na architecture-graph page.
Ang parehong bagay nang manu-mano, kapaki-pakinabang kapag wala ang `agentmemory` sa PATH:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**Ang magagawa mo mula sa console:**
| Pahina | Gamitin Ito Para |
|------|-----------|
| **Workers** | Makita ang bawat kakonektang worker at ang live metrics nito, kasama ang agentmemory worker mismo. |
| **Functions** | I-invoke nang direkta ang alinman sa mga function ng agentmemory gamit ang isang JSON payload; kapaki-pakinabang para sa pag-test ng `memory.recall`, `memory.consolidate`, `graph.query` nang walang i-wire na client. |
| **Triggers** | I-replay ang HTTP, cron, event, at state trigger: patakbuhin nang manu-mano ang consolidation cron, ulitin ang isang HTTP route, maglabas ng state change. |
| **States** | KV browser na may full CRUD sa mga session, memory slot, lifecycle timer, at ang embeddings index; i-edit ang mga value sa lugar. |
| **Streams** | Live na WebSocket monitor para sa memory writes, hook event, at observation update habang dumadaloy sa mga iii stream. |
| **Queues** | Durable queue topic + dead-letter management. I-replay o i-drop ang mga nabigong embedding / compression job. |
| **Traces** | OpenTelemetry waterfall / flame / service-breakdown view. I-filter ayon sa `trace_id` para makita kung aling mga function, DB call, at embedding request mismo ang nabuo ng isang `memory.search`. |
| **Logs** | Structured OTEL log na na-filter at na-correlate sa trace/span ID. |
| **Config** | Runtime configuration: makita mismo kung aling mga worker, provider, at port ang tinatakbo ng iyong engine. |
| **Flow** | (Opsyonal, `--enable-flow`) Interactive na architecture graph ng bawat worker, trigger, at stream. |
Traces: waterfall / flame / service breakdown para sa bawat memory operation.
**Naka-on na ang Traces:**
Nag-ship ang `iii-config.yaml` na naka-enable na ang `iii-observability` worker (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Walang kailangang karagdagang config; sa sandaling magsimula ang agentmemory, nagpaparating ang bawat memory operation ng isang structured log na nababasa ng console, at isa sa sampung operation (`sampling_ratio: 0.1`) ang nagpaparating din ng trace span.
Kung gusto mo nang mag-export papunta sa Jaeger/Honeycomb/Grafana Tempo, palitan ang `exporter: memory` ng `exporter: otlp` at i-set ang collector endpoint ayon sa observability docs ng iii.
> **Paalala:** walang auth na ipinapatupad sa console mismo; panatilihin itong bound sa `127.0.0.1` (ang default) at huwag kailanman i-expose ito nang pampubliko.
---
Ang agentmemory ay **isa nang tumatakbong [iii](https://iii.dev) instance**. Tatlong primitive (worker, function, trigger) ang bumubuo sa runtime; nagmumula ang KV state, streams, at OTEL trace sa mga worker na iii-state, iii-stream, at iii-observability na kasama sa iii. Hindi ka nag-install ng Postgres, Redis, Express, pm2, o Prometheus, dahil pinapalitan ito ng iii.
Ibig sabihin, isa pang command ang kailangan para palawakin ang agentmemory ng isang buong bagong kakayahan.
### Palawakin ang agentmemory gamit ang Mas Maraming Worker
Ang mga builtin na kailangan ng agentmemory ay nasa `iii-config.yaml` na at nag-boot kasama nito: `iii-state` (KV), `iii-queue` (durable retry para sa mga event subscriber), `iii-pubsub`, `iii-cron`, `iii-stream`, at `iii-observability` (OTEL trace, metrics at logs sa bawat function). Kahit ano pang mula sa [iii worker registry](https://workers.iii.dev) ay maaaring i-plug sa parehong engine: kopyahin ang `iii-config.yaml` papunta sa `~/.agentmemory/iii-config.yaml` (mas pinipili ng CLI ang file na ito kaysa sa bundled at ire-render pa rin nito ang mga port at data path dito), idagdag ang entry, i-install nang isang pagkakataon ang worker runtime gamit ang `~/.agentmemory/bin/iii update worker`, at i-restart ang 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 | Ano ang Makukuha Mo Kasama ang agentmemory |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | SQL-backed na state adapter kapag nalampasan mo na ang in-memory KV default |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Tumatakbo sa loob ng isang throwaway VM, hindi sa shell mo, ang code na galing sa `memory_recall` |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Magtayo ng karagdagang MCP server sa tabi ng agentmemory's, ibahagi ang parehong engine |
Sa engine 0.22.x, panatilihin ang mga pangalang may `iii-` prefix para sa mga builtin sa itaas; ang mga unprefixed na entry na `http`, `state`, `queue`, `pubsub` at `cron` ay ang standalone na registry worker na lilipatan ng agentmemory sa 0.23 migration.
Kumpletong registry: [workers.iii.dev](https://workers.iii.dev). Bumubuo ang bawat worker dito gamit ang parehong primitive na ginagamit ng agentmemory, at ang agentmemory na nasa'yo na ay isa sa mga ito.
### Engine Config at Bind Address
Binabasa ng `agentmemory start` ang engine config mula sa unang file na umiiral: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` sa kasalukuyang directory, `~/.agentmemory/iii-config.yaml`, pagkatapos ang bundled na `iii-config.yaml`. Sa bawat start, ire-render nito ang file na iyon (data path, port, state backend) papunta sa `~/.agentmemory/data/iii-config.runtime.yaml` at ilulunsad ang engine gamit ang rendered copy, kaya i-edit ang source file, hindi ang rendered na isa. Pinapanatili ang mga value ng `host:` ng source file ayon sa pagkasulat.
Sinasadyang nagbibind ang bundled na `iii-config.yaml` sa `127.0.0.1`, at nalalapat din ang default na ito sa loob ng container. Ang isang CLI na sinimulan sa isang container ay nakikinig sa loopback ng container, kaya walang maaabot ang mga published port. Para maihain ang isang containerized na CLI sa mga published port, i-set ang `AGENTMEMORY_III_CONFIG` sa isang config na nagbibind sa `0.0.0.0`. Ang packaged na `iii-config.docker.yaml` ay isa sa mga ito: nagbibind ito ng `iii-http`, `iii-stream` at ang engine port sa `0.0.0.0` at itinatago ang state sa ilalim ng `/data`, kaya i-mount ang isang writable volume dito. Panatilihing naka-set ang `AGENTMEMORY_SECRET`, at i-publish lamang ang mga port na kailangan mo, sa `127.0.0.1` o sa likod ng isang proxy na pinagkakatiwalaan mo.
Hindi dumadaan sa config lookup ng CLI ang `docker-compose.yml` ng repo na ito: nag-mount ito ng `iii-config.docker.yaml` sa `/app/config.yaml`, at sinisimulan ang `iii-engine` container gamit ang `--config /app/config.yaml`. Isinusulat ng mga one-click [deploy template](../deploy/) ang sariling `0.0.0.0` config sa kanilang mga entrypoint.
### Storage Backend: file (default) laban sa redis
Nagde-default ang `iii-state` at `iii-stream` sa bundled na file-based KV store ng iii-engine: isang JSON file kada scope, nananatili sa memory ng engine process at isinusulat ulit sa disk sa isang timer. Ito ang tamang default para sa single-user na local install; mas mainam ang tunay na per-key write mula sa Redis para sa isang shared daemon na may ilang concurrent writer, sa gastos ng isang network round trip kada operation (nagsesiserialize pa rin ang bawat `state::*` call sa isang Redis connection, kaya ipinagpapalit nito ang lock ng file store para sa isang socket, hindi para sa parallelism).
I-set ang `AGENTMEMORY_STATE_BACKEND=redis` (kasama ang `AGENTMEMORY_REDIS_URL`) para ilipat ang dalawang worker sa built-in na `redis` adapter ng iii-engine, na itinatago ang bawat key bilang Redis hash field (`HSET`) sa halip na isulat ulit ang isang buong scope sa bawat sulat:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
Nagde-default ang `AGENTMEMORY_STATE_BACKEND` sa `file`; ang hindi pagse-set nito ay pananatilihin ang kasalukuyang behavior, at ang isang hindi kilalang value (anuman maliban sa `file` o `redis`) ay isang startup error sa halip na isang tahimik na fallback. Iniulat ng `/agentmemory/status` at ng Health page ng viewer (ang State store row) kung aling backend ang aktibo at kung ito ba sumasagot, hindi kailanman ang URL.
**Plain na `redis://` lamang.** Binubuo ng pinned engine (0.22.1) ang Redis client nito nang walang TLS support, kaya nabibigo kumonekta ang isang `rediss://` URL (karamihan sa mga managed Redis offering, gaya ng Upstash, Redis Cloud, at ElastiCache na may in-transit encryption, ay nagde-default sa TLS-only). Hindi encrypted ang connection, kaya tumatawid sa wire ang Redis password at ang bawat naka-store na memory sa clear text: ituro sa isang lokal na Redis o isa na nasa private network na pinagkakatiwalaan mo. Para sa ibang Redis, patakbuhin ang isang encrypted tunnel (stunnel, SSH, o VPN) sa agentmemory host, para manatili sa host na iyon ang plain na `redis://` hop at ma-encrypt at ma-authenticate ang upstream connection ng tunnel. Kung may single quote ang Redis password, percent-encode ito (`%27`); pinapalawak ng engine ang URL sa YAML config nito bago ito parse.
**Isang Redis server kada `--instance`.** Fixed ang mga Redis key prefix ng engine (`state:`, `stream::`), kaya dalawang agentmemory instance (`--instance 1`, `--instance 2`, ...) na itinuro sa parehong database ay magpapatungan sa data ng isa't isa. Pinapanatili ng isang hiwalay na database index (`redis://localhost:6379/1`) ang itinagong data, pero ni-relay ng engine ang live viewer events sa isang Redis pub/sub channel (`stream::events`), at hindi pinapansin ng Redis pub/sub ang database index, kaya ang viewer ng bawat instance ay ipapakita rin ang live events ng iba. Bigyan ang bawat instance ng sariling Redis server (o port) kapag mahigit sa isa ang pinapatakbo mo.
**Ano ang nananatili, at ano ang naiiba.** Gumagana sa Redis ang lahat ng feature ng agentmemory: sessions, obserbasyon, memory (remember, supersede, evolve, forget), search at ang mga index bucket, lesson, ang graph, ang audit log at ang monthly scopes nito, export at import, governance delete, consolidation status, ang viewer snapshot at ang live stream nito, at ang health monitor. Itinatago ng engine ang bawat scope bilang isang Redis hash (`HSET`/`HGET`/`HGETALL`) at pinapaputok ang parehong state trigger gaya ng file store. Tatlong pagkaiba ng engine ang hinahandle sa loob ng agentmemory:
- Ibinabalik ng Redis ang mga record ng isang scope nang walang fixed na order. Isinasaayos ng agentmemory ang mga ito mula sa pinakamatanda (ayon sa creation time sa record id, pagkatapos ang timestamp nito) para ang mga list, paging, at export chunk ay bumalik sa parehong order gaya ng sa file store.
- Ilalapat ng engine ang partial update sa Redis sa pamamagitan ng Lua script na gumagawa ng empty object mula sa empty array. Ilalapat mismo ng agentmemory ang mga update na iyon (read, change, write sa ilalim ng per-key lock) sa Redis, kaya nananatiling array ang mga field gaya ng `tags: []`.
- Babasahin ng legacy audit log check ang lumang scope mula sa Redis sa halip na hanapin ang file ng file store sa disk.
Isang pagkaiba ang nangangailangan ng aksyon mo: **pagkatapos mag-restart ang Redis, hihinto ang engine sa pag-relay ng live events** papunta sa viewer hanggang mag-restart ang agentmemory. Nananatiling naka-save at nababasa nang normal ang data. Nagpapadala ang health monitor ng isang test event sa Redis kada 30 segundo; kapag hindi ito bumalik, ipinapakita ng `/agentmemory/status` at ng Health page ng viewer ang "Live updates are not reaching the viewer" kasama ang fix: i-restart ang agentmemory. Kung down ang Redis, ipinapakita ng status report ang "The state store is not answering" at kung paano ito susuriin (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Babasahin ng isang listahan ng malaking scope ang buong hash sa isang `HGETALL`, parehong gastos ng file store na pinapanatili ito sa memory.
**Inirerekomendang Redis settings.** Ang default na `save 3600 1 300 100 60 10000` snapshot policy ay maaaring mawalan ng mga minutong write sa isang crash, mas malala kaysa sa 5s flush window ng file store. I-set ang `appendonly yes` para sa anumang bagay na ayaw mong mawala. I-set ang `maxmemory-policy noeviction`; tahimik na dinadroop ng `allkeys-lru` o katulad nito ang mga memory kapag naabot ng Redis ang memory limit nito.
Ang isang native (non-Docker) na start, at ang bawat one-click [deploy template](../deploy/) (nag-o-override sila ng bundled na `iii-config.yaml` at nagsisimula nang native), ay babasa ng `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` at ire-render ito sa inilunsad na `iii-config`. Hindi kailanman isinusulat ang URL mismo sa rendered na file na iyon, isang `${AGENTMEMORY_REDIS_URL}` reference lamang na pinapalawak ng engine process mula sa sariling environment nito sa boot. Ang sariling Docker Compose path ng repo na ito lamang (`AGENTMEMORY_USE_DOCKER=1`, o pagpapatuloy ng isang engine na nasimulan na sa paraang iyon) ay nag-mount ng `iii-config.docker.yaml` nang read-only at hindi kailanman nireder; nagbabala ang `agentmemory start` kapag natukoy nito ang kombinasyong iyon. Palitan ang file na iyon nang manu-mano, sinusundan ang parehong `name: redis` / `config: redis_url: ...` shape na ipinapakita sa [iii-state](https://workers.iii.dev/workers/iii-state) at [iii-stream](https://workers.iii.dev/workers/iii-stream) worker docs, at ituro ang `redis_url` sa isang Redis na maaabot mula sa container. Ipapasa ng `docker-compose.yml` ang `AGENTMEMORY_REDIS_URL` sa engine container, kaya gumagana roon ang `redis_url: '${AGENTMEMORY_REDIS_URL}'` at pinananatili ang URL sa labas ng mounted na file.
Pinananatili ng rendered config ang URL sa labas ng `~/.agentmemory/data/iii-config.runtime.yaml`, pero ang sariling configuration worker ng engine ay pinapanatili pa rin ang *pinalawak* na value sa `~/.agentmemory/config/iii-state.yaml` at `iii-stream.yaml` kapag ito ay boot (nangyayari ang `${VAR}` expansion ng iii-engine bago iseed ng worker na iyon ang seed nito, at ang resolved value ang itinatago nito, hindi ang reference). Ituring na may hawak na credential ang directory na iyon: `chmod 700 ~/.agentmemory` sa anumang shared host, at mas piliin ang isang Redis ACL user na scoped sa kailangan ng agentmemory kaysa sa admin credentials ng database.
**Hindi awtomatiko ang migration.** Ang pagpalit ng `AGENTMEMORY_STATE_BACKEND` ay nagsisimula mula sa walang-lamang store sa magkabilang panig; walang kumokopya ng umiiral na data mula sa file papunta sa Redis o pabalik. I-export mula sa backend na iniiwan mo at i-import papunta sa kinakalipat mo. Tumatakbo ito nang pareho sa bash at zsh (kasama ang `bash -u`). Ang isang array gaya ng `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` ay hindi: pinananatili ng zsh ang header bilang isang malformed na salita kung saan hinahati ito ng bash sa dalawa, kaya 401 ang dalawang request kapag naka-set ang `AGENTMEMORY_SECRET`:
```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
```
Tinatanggap din ng `/agentmemory/export` ang `?maxSessions=` at `?offset=` para sa chunking ng malaking corpus sa ilang call; ang `strategy` sa import ay `merge` (default-safe), `replace`, o `skip`.
### Ano ang Pinapalitan ng iii
| Traditional na Stack | Ginagamit ng agentmemory |
|---|---|
| Express.js / Fastify | iii HTTP Triggers |
| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
| SSE / Socket.io | iii Streams (WebSocket) |
| pm2 / systemd | iii engine worker supervision |
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom na plugin system | `iii worker add ` |
**219 na source file · ~52,000 LOC · 2,500+ na test · 311 na function · 60 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
---
### Mga LLM Provider
Awtomatikong tinutuklas ng agentmemory ang mga provider mula sa iyong environment. Pinagagana ng isang provider ang mga LLM-backed operation, pero ang configuration ng provider lamang ay hindi nagpapagana ng LLM-written na observation compression. Kailangan ng path na iyon ang parehong provider at `AGENTMEMORY_AUTO_COMPRESS=true`.
| Provider | Config | Mga Tala |
|----------|--------|-------|
| **No-op (default)** | Walang kailangang config | Naka-disable ang LLM-backed compress/summarize. Gumagana pa rin ang synthetic compression at BM25 recall. Tingnan ang `AGENTMEMORY_ALLOW_AGENT_SDK` sa ibaba kung dati kang umaasa sa Claude-subscription fallback. |
| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |
| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
| Gemini | `GEMINI_API_KEY` | Pinagagana din ang embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Kahit anong model |
| OpenAI API | `OPENAI_API_KEY` | Default `gpt-5.6-luna`, i-override gamit ang `OPENAI_MODEL` |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) o `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Anumang OpenAI-API-compatible. Zero cost, tumatakbo sa iyong hardware. Tingnan ang [Mga Local Model](#local-models-ollama--lm-studio--vllm) sa ibaba. |
| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in lamang. Nag-spawn ng mga `@anthropic-ai/claude-agent-sdk` session; dati itong nagdudulot ng unbounded Stop-hook recursion, kaya hindi na ito ang default. |
### Mga Local Model (Ollama / LM Studio / vLLM)
Kinakausap ng agentmemory ang anumang OpenAI-API-compatible na server, kaya gumagana nang walang pagbabago sa code ang anumang naglalantad ng `/v1/chat/completions`. Walang bayad na key, walang cloud, walang rate limit; tumatakbo nang buo sa iyong hardware.
**Ollama** (default port `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** (default port `1234`):
Buksan ang LM Studio → Local Server tab → Start Server. Piliin ang kahit anong chat model mula sa picker (Qwen 3, gpt-oss, DeepSeek R1, atbp.).
```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**: parehong shape. Ituro ang `OPENAI_BASE_URL` sa kung anumang URL na inilalantad ng iyong server at i-set ang `OPENAI_MODEL` sa isang pangalang tatanggapin ng iyong server.
**Pagpili ng model para sa memory work**: ang compression at summarization ay mga maikling task (<2K token papasok, <500 token palabas) kung saan sapat na ang isang 7B instruct model. Mga rekomendasyon:
| Model | Laki | Bakit |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | Balanced na default sa 16 GB machine; malakas sa extraction at tool-shaped na text |
| `qwen3:4b` | ~2.6 GB | Pinakamaliit na makatwirang opsyon; sapat para sa compression, mahina para sa graph extraction |
| `qwen3-coder:30b` | ~19 GB | Pinakamagandang local pick para sa code-shaped na session (30B MoE, 3.3B active) sa 24-32 GB hardware |
| `gpt-oss:20b` | ~14 GB | Malakas na general model na kasya sa 16 GB RAM |
| `deepseek-r1:8b` | ~5.2 GB | Reasoning distill; mas mabagal pero mas malinis ang extraction |
Nag-iisip ang mga Qwen 3 model bilang default at maaaring maubos ang buong token budget sa reasoning bago ang anumang output. I-set ang `AGENTMEMORY_LLM_NOTHINK=1` para idagdag ang `/no_think` sa mga graph-extraction prompt, at itaas ang `MAX_TOKENS` (gumagana ang 16384) kung nagbabalik na walang-lamang ang mga extraction.
Maaaring magbalik ang mga reasoning-class model (`o1`-style na may `` block) ng walang-lamang `content` na may `reasoning` field na posibleng hindi ilantad ng iyong local server. Kung nagbabalik na blangko ang mga extraction, lumipat muna sa isang non-reasoning na model. Maaari din i-disable ng env na `OPENAI_REASONING_EFFORT=none` ang thinking sa mga Ollama Cloud thinking model na sumasalamin sa OpenAI reasoning schema.
Nag-ship ang local embeddings bilang opsyonal na dependency pero hindi ito naka-enable bilang default. I-set ang `EMBEDDING_PROVIDER=local` para opt in sa `Xenova/all-MiniLM-L6-v2` (384-dim). Nag-download ng model ang unang embedding request; on-device na ang inference pagkatapos. Kung walang setting na iyon o remote embedding key, mananatiling naka-disable ang vectors, gagamit ang `mem::search` ng BM25, at maaari pa ring idagdag ng `smart-search` ang umiiral na graph matches.
### Cost-aware na Pagpili ng Model
Kapag naka-enable ang LLM-written na background compression gamit ang parehong provider at `AGENTMEMORY_AUTO_COMPRESS=true`, tumatakbo ito sa bawat obserbasyon, kaya makabuluhang nagbabago sa monthly spend ang pagpili ng model. Nakuhang workload data: 635 request / 888K token / 35 oras ng aktibong paggamit, pinatakbo laban sa tatlong OpenRouter model sa pricing noong 2026-05-23.
| Tier | Model | Input / 1M | Output / 1M | Gastos para sa nakuhang 35h | Mga Tala |
|------|-------|------------|-------------|---------------------------|-------|
| Inirerekomenda | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Pinakabagong DeepSeek; ang pinakamurang inirerekomendang pick para sa compression workload. |
| Inirerekomenda | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid na compression + summarization quality sa ~10× na mas mababang gastos kaysa sa Sonnet. |
| Inirerekomenda | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Malakas na code reasoning kung heavily code-shaped ang iyong mga session. |
| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Parehong list price ng nasukat na Sonnet 4.6 run; $2/$10 intro pricing hanggang 2026-08-31. |
| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flagship tier; mahal para sa always-on na background work. |
| Iwasan | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flagship-class na model; overspend para sa compression. |
Ang mga measured row ay mula sa nakuhang run; sinusukat ng mga (est.) row ang parehong token mix ayon sa list price ng bawat model.
Nagprint ng runtime warning ang agentmemory kapag tumutugma ang `OPENROUTER_MODEL` sa isang premium-tier pattern. I-set ang `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para patahimikin ito kapag nakagawa ka na ng informed choice.
Quality laban sa cost tradeoff para sa memory work: ang compression ay isang summarization task na may medyo maluwag na quality bar (binabasa ulit ng agent ang summary, hindi ng user). Napapalapit ang DeepSeek V4 Flash / V4 Pro / Qwen3-Coder sa rounding error ng Sonnet sa task na ito habang 10-70× na mas mura. Itago ang mga premium-tier model para sa mga query na direktang babasahin mo.
Mga Source: [OpenRouter pricing para sa Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
### Multi-agent na Memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
Sa multi-agent setup kung saan nagbabahagi ng isang agentmemory server ang ilang role (architect / developer / reviewer / researcher / support-agent), tinatakan ng `AGENT_ID` ang bawat sulat gamit ang role na gumawa nito. Kinokontrol ng `AGENTMEMORY_AGENT_SCOPE` kung mag-filter ang recall ayon sa tag na iyon.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
Dalawang mode:
| Mode | Tinatakan ang Sulat | Nag-filter ang Recall | Kailan Gagamitin |
|------|------------|---------------|-------------|
| `shared` (default) | oo | hindi | Cross-agent na context na may audit trail. Makikita ng architect ang naitala ng developer, pero itinatala ng bawat row kung sino ang nagsabi nito. |
| `isolated` | oo | oo | Mahigpit na paghihiwalay. Hindi kailanman makikita ng architect ang mga obserbasyon / memory / session ng developer. |
Ang natatakan kapag naka-set ang `AGENT_ID`: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Dumadaloy ang role mula sa `api::session::start` → `mem::observe` → `mem::compress` → KV.
Ang na-filter sa isolated mode: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Tinatanggap ng bawat endpoint ang `?agentId=` para i-override kada-request, at `?agentId=*` para lumabas nang buo sa env scope. Tinatanggap din ng `/memories` ang `?includeOrphans=true` para ilantad ang mga pre-AGENT_ID na memory na hindi defined ang `agentId`.
Per-call override sa SDK / REST layer: tinatanggap ng bawat mutating endpoint (`/session/start`, `/remember`) ang isang `agentId` field sa request body na nananaig kaysa sa env. Kapaki-pakinabang para sa mga runtime na nagruruta ng maraming role sa isang server process. Inilalantad ng MCP tool na `memory_save` ang parehong `agentId` field, ipinapasa ng standalone stdio server ang parehong `agentId` at `project`, at dala ng mga na-save na memory ang `agentId` papunta sa search index, kaya saklaw ng agent-scoped search ang mga memory gayundin ang mga obserbasyon.
Kapag hindi naka-set ang `AGENT_ID`, nananatiling unscoped ang memory (legacy behavior, walang tag, walang filter).
### Mga Port
Nagbibind ang agentmemory + iii-engine ng apat na port bilang default. Kung nabigo ang isang restart gamit ang `port in use`, sinasabi sa iyo ng table na ito kung aling process ang hahanapin.
| Port | Process | Layunin | Env override |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | Internal streams worker (ginagamit ng agentmemory + viewer) | `III_STREAM_PORT` (mas pinipili) o legacy `III_STREAMS_PORT` |
| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | `III_VIEWER_PORT` o `AGENTMEMORY_VIEWER_URL` para sa inireport na URL |
| `49134` | iii-engine | WebSocket; nagrerehistro rito ang mga worker, dumadaloy dito ang OTel telemetry | `III_ENGINE_PORT` o `III_ENGINE_URL` |
Binabago ng `--port ` ang REST anchor at kinukuha ang streams `N+1`, viewer `N+2`, at engine WebSocket `N+46023` lamang kung hindi naka-set ang kaukulang explicit port o URL sa itaas. Hindi ito gumagawa ng isolated na lifecycle namespace. Gamitin ang `--instance 1` para sa pangalawang daemon; ginagamit nito ang anchor 3211, nagde-default sa `3211/3212/3213/49234`, at nakatanggap ng hiwalay na `instance-1` data at lifecycle directory. Sinusunod ng Instance 1 hanggang 50 ang parehong pattern.
Sinisimulan ang pinned engine gamit ang `--no-update-check` (walang update o security-advisory lookup laban sa GitHub sa boot) at naka-off ang anonymous usage telemetry ng iii: itinatakda ng agentmemory ang `III_TELEMETRY_ENABLED=false` para sa engine na spawn nito maliban kung mismo mong i-export ang variable, at ganoon din ang bundled compose file.
Stale-process cleanup kapag nananatiling bound ang mga port pagkatapos ng isang crashed run:
```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
```
Malinis na kinukuha ng `agentmemory stop` ang worker at ang engine pidfile sa isang graceful native shutdown. Sa Docker mode, nag-flush ito ng native worker, itinitigil ang eksaktong validated na engine container, at pinapanatili ang parehong container at ang `/data` mount nito para sa isang lossless restart; ive-validate at ipagpapatuloy ng susunod na start ang parehong container. Kailangan ng Docker-backed na uninstall ang `agentmemory remove --keep-data`: tinatanggal nito ang shared na agentmemory-managed file habang pinapanatili ang validated na container, ang data mount nito, at ang lifecycle record na kailangan para mabawi ito. Sinadyang iniiwan sa operator ang destructive na Docker data deletion pagkatapos ng isang backup. Tumatanggi din ang CLI na angkinin o i-signal ang mga Docker o VM port holder (Docker backend, vpnkit, colima) bilang native engine maliban kung ipinasa ang `--force`. Ang manual na cleanup sa itaas ay para lamang sa post-crash na kaso kung saan walang natitirang alinmang pidfile.
### Config File
Ilagay ang runtime configuration ng agentmemory sa `~/.agentmemory/.env` sa halip na i-export ang mga variable sa bawat shell. Kung ipinapakita ng viewer ang isang setup hint gaya ng `export ANTHROPIC_API_KEY=...`, kopyahin ito sa file na ito bilang `ANTHROPIC_API_KEY=...` nang walang `export` prefix, pagkatapos i-restart ang agentmemory.
Gumagana pa rin ang process environment variable at mananaig ito kaysa sa mga value sa file.
Sa Windows, nasa `%USERPROFILE%\.agentmemory\.env` ang parehong file:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
Para magsubok gamit ang isang Claude Code Pro/Max subscription sa halip ng isang API key, opt in nang tahasan:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
Kailangan ng LLM-written na observation compression ang parehong linya: access sa isang LLM provider (kasama ang tahasang subscription fallback na ito) at `AGENTMEMORY_AUTO_COMPRESS=true`. Iiwanan ng provider mismo ang default na synthetic compression path.
Naka-on bilang default ang consolidation (graph node, lesson, crystal) sa tuwing naka-configure ang isang LLM provider. Tahasang opt out gamit ang `CONSOLIDATION_ENABLED=false` kung nais mo ng LLM-free operation. Hiwalay na flag ang graph extraction:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Mga Environment Variable
Gawin ang `~/.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 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer `, at kinakailangan ng mga mesh sync endpoint ang tahasang naka-set na `AGENTMEMORY_SECRET` sa dalawang peer.
**Naka-on ang Authentication bilang default.** Kapag hindi naka-set ang `AGENTMEMORY_SECRET` (sa shell o sa `~/.agentmemory/.env`), gumagawa ang server ng random na secret sa unang start at itinatago ito sa `~/.agentmemory/secret` na may mode `0600`. Babasahin ito mula roon ng bawat bundled na client kapag nakikipag-usap ito sa isang local server: ang CLI, ang viewer, ang hooks sa ilalim ng `plugin/scripts`, ang MCP server at ang `@agentmemory/mcp` shim, ang mga config na isinulat ng `agentmemory connect`, at ang bundled na OpenCode, Pi, OpenClaw, Hermes, at filesystem-watcher integrations. Ipinapadala lamang ang itinagong secret sa mga loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Palaging mananaig ang isang tahasang `AGENTMEMORY_SECRET`, at kailangan pa rin itong naka-set para sa mga remote client. Gumagawa at nag-export na ng sariling secret ang Docker at ang mga entrypoint ng `deploy/`. Para tawagin ang API nang manu-mano:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**Mga Tuntunin ng Request para sa Sulat.** Dapat magpadala ng `Content-Type: application/json` (okay ang isang `charset` parameter) ang mga request na `POST`, `PUT`, `PATCH` at `DELETE` papunta sa REST API at sa viewer sa tuwing may dala itong body, at ang isang `Origin` header, kapag naroroon, ay dapat isang loopback origin para sa naka-configure na REST o viewer port o nakalista sa `VIEWER_ALLOWED_ORIGINS` (comma-separated, hal. `https://memory.example.com`). Hindi apektado ang mga client na walang ipinapadalang `Origin` header (CLI, hooks, MCP, curl, server-to-server). Tinatanggap din ng viewer ang sariling origin nito.
**Mga File Path.** Ang mga endpoint na nagbabasa o nagsusulat ng file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) ay tumatanggap lamang ng mga path sa ilalim ng `~/.agentmemory`, ang instance data directory, o isang directory na nakalista sa `AGENTMEMORY_IMPORT_ROOT` (paghiwalayin ang ilan gamit ang `:`, o `;` sa Windows). Tinatanggap din ng `/replay/import-jsonl` ang default nitong `~/.claude/projects`. Nananatili ang `/obsidian/export` sa loob ng `AGENTMEMORY_EXPORT_ROOT` at ang `/migrate` sa loob ng `~/.agentmemory`. Nireresolba ang mga symlink bago ang bawat check.
**Secret Scrubbing.** Ang mga API key, bearer token, PEM private key block, at credential na naka-embed sa mga URL (`scheme://user:password@host`) ay nire-redact bago maitago ang text, sa bawat write path: obserbasyon, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, compression at summary output, crystal, at graph node.
Mga Pangunahing Endpoint
| Method | Path | Paglalarawan |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check (laging public) |
| `GET` | `/agentmemory/status` | Ano ang mali at paano ito aayusin (HTML para sa browser, JSON kung hindi) |
| `GET` | `/agentmemory/viewer/snapshot` | Lahat ng ipinapakita ng viewer, sa isang response |
| `POST` | `/agentmemory/session/start` | Simulan ang session + kunin ang context |
| `POST` | `/agentmemory/session/end` | Tapusin ang session |
| `POST` | `/agentmemory/observe` | Kunin ang obserbasyon (tingnan ang capture delivery sa ibaba) |
| `GET` | `/agentmemory/capture` | Capture inbox, dead letter, at offline spool |
| `POST` | `/agentmemory/capture/retry` | Ulitin ang mga dead-letter capture |
| `POST` | `/agentmemory/capture/drain` | Ipadala na ang local offline spool |
| `POST` | `/agentmemory/smart-search` | Hybrid search |
| `POST` | `/agentmemory/context` | Buuin ang context |
| `POST` | `/agentmemory/remember` | I-save sa long-term memory |
| `POST` | `/agentmemory/forget` | Burahin ang mga obserbasyon |
| `POST` | `/agentmemory/enrich` | File context + memory + bug |
| `GET` | `/agentmemory/profile` | Profile ng project |
| `GET` | `/agentmemory/export` | I-export ang lahat ng data |
| `POST` | `/agentmemory/import` | I-import mula sa JSON |
| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
| `POST` | `/agentmemory/graph/compact` | Putulin ang oversized na graph provenance |
| `POST` | `/agentmemory/team/share` | Ibahagi sa team |
| `GET` | `/agentmemory/audit` | Audit trail |
Kumpletong listahan ng endpoint: [`src/triggers/api.ts`](../src/triggers/api.ts)
**Capture Delivery.** Ipinapadala ng hooks ang bawat obserbasyon isang beses sa `POST /agentmemory/observe` na may `eventId`. Ito ang sariling id ng host para sa call kapag may isa ang payload (halimbawa ang `tool_use_id` ng Claude Code), kung hindi ay isang hash ng session, hook type, tool name, input, output, at host timestamp. Isusulat ng server ang event sa isang capture inbox sa state store, itinatago ang obserbasyon, pagkatapos tanggalin ang inbox entry. Sinasabi ng status code kung ano ang nangyari:
| Status | `status` field | Kahulugan |
|---|---|---|
| `201` | `accepted` | Naitago. Ang `observationId` ay ang bagong obserbasyon. |
| `202` | `accepted` (`state: "retrying"`) | Tinanggap, pero nabigo ang pag-store. Uulitin ito ng server, maging pagkatapos ng isang restart. |
| `200` | `duplicate` | Natanggap na dati ang `eventId` na ito. Ang `observationId` ay ang umiiral na obserbasyon; walang bagong naitago. |
| `400` / `422` | `rejected` | Hindi valid ang payload, o permanenteng nabigo ang pag-store (itinatago ang event bilang dead letter). |
| `503` | `rejected` (`retryable: true`) | Puno ang inbox (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Isinusulat ng hooks ang event sa spool at ipapadala ito mamaya. |
Uulitin ang mga nabigong event kada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) na may doubling backoff, hanggang `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Ang mga event na nananatiling nabigo ay nananatili sa inbox bilang dead letter, nililista sa `/agentmemory/status` at sa Health page ng viewer, at maaaring ulitin gamit ang `POST /agentmemory/capture/retry` (`{"eventId": "..."}` o `{"all": true}`). Naaalala ang mga tinanggap na event id sa loob ng `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 oras, pinakamarami na `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), kaya ang isang hook na nireplay pagkatapos ng isang timeout o isang restart ay naitatago isang beses lamang, habang dalawang hiwalay na tool call na may sariling host id ay naitatago nang dalawang beses kahit magkapareho ang nilalaman. Kapag nabura ang isang obserbasyon (forget, session delete, eviction, auto-forget, o isang import na pumapalit sa store), minamarkahan ang event nito bilang nabura bago matanggal ang obserbasyon, kaya ang isang replay ng event na iyon sa loob ng parehong window ay sinasagot bilang duplicate at walang itinatago. Isinusulat ng state store sa disk kada 2 segundo, kaya ang isang sinagot na event ay maaaring nasa memory lamang sandali. Para masaklaw ito, dala rin ng bawat `2xx` na sagot ang `bootId` ng server (bago sa bawat start), `acceptedAt`, at `durableAfterMs` (ang save interval kasama ang 1.5 s sa file store, 1.5 s sa redis, kung saan ang persistence ay setting ng operator). Itinatago ng hooks ang event sa local spool hanggang lumipas ang window na iyon at tinatanggal ito sa isang susunod na call nang walang karagdagang request. Kung nagbago na ang `bootId` sa oras na iyon, nag-restart ang server, kaya ipinapadala ulit ng hook ang event gamit ang parehong `eventId`; ang isang event na nakarating na sa disk ay hindi naitatago nang dalawang beses. Ipinapadala rin ng server mismo ang mga event na ito sa start at sa bawat retry interval, kaya walang mawawala sa isang restart kahit walang tumakbong hook pagkatapos. Hindi pinapansin ng mas lumang hooks ang mga extra field, at itinatapon ng mga bagong hooks laban sa isang mas lumang server ang event sa `2xx` gaya ng dati.
Kapag down ang server, hindi sumagot sa oras, o nagbalik ng 5xx, idinadagdag ng hook ang obserbasyon sa isang local spool file, `/capture-spool/-.jsonl` (i-override ang folder gamit ang `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Private sa iyong user ang file (mode 600), nire-redact ang mga secret sa parehong paraan na nire-redact ito ng server, hawak nito ang pinakamarami na `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) at itinatapon ang mga entry na mas matanda sa `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Kapag puno na, itinatapon at binibilang ang mga bagong entry, at iniulat ito ng `/agentmemory/status`. Nag-exit pa rin ng 0 ang hook sa loob ng time limit nito at hindi nagdadagdag ng request kapag healthy ang server. Ipinapadala ang spool sa susunod na start at ng unang hook na maabot ulit ang server, sa isang background process para hindi maghintay ang agent. Ginagawang ligtas ito ng event id: ang isang obserbasyon na nakarating na bago ang isang timeout ay hindi naitatago nang dalawang beses. Ipinapakita ng `npx @agentmemory/agentmemory capture` ang spool at ang inbox ng server, ipinapadala ng `--drain` ang spool ngayon, at ibinabalik ng `GET /agentmemory/capture` ang pareho bilang JSON. I-set ang `AGENTMEMORY_CAPTURE_SPOOL=false` para patayin ang spool.
**Compacting Graph Provenance.** Itinatago ng bawat knowledge graph node at edge ang mga id ng pinakabagong 32 obserbasyon na pinagmulan nito. Ang mga store na isinulat bago ang cap na iyon ay maaaring hawak ng libo-libong id kada hot node, na nagpapabagal sa graph search at sa viewer o nagpapabagsak sa worker. Mismong inaayos ito ng agentmemory: sa unang start pagkatapos ng upgrade, pinuputol nito ang bawat node, edge, superseded edge (ang temporal graph history) at ang cached snapshot pababa sa cap sa background, sa maliliit na slice na may pahinga sa pagitan, para patuloy na gumana ang search, capture, at viewer. Nagse-save ito ng progress nito, nagpapatuloy pagkatapos ng isang restart at hindi na tumatakbo ulit kapag natapos na. Ipinapakita ito ng `/agentmemory/status` at ng Health page ng viewer bilang pending, running (kasama ang kasalukuyang scope at posisyon), done, o failed. I-set ang `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` para patayin ito.
Para patakbuhin ito nang manu-mano, tawagin ang `POST /agentmemory/graph/compact`. Dumadaan ito sa name at edge-key indexes sa halip na ilista ang bawat node at edge, at ligtas itong patakbuhin ulit. Kapag pinuputol nito ang mga id, isinusulat nito ang isang `graph_compact` audit entry.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
```
Sa isang malaking store, o kapag nagbalik ng 504 ang call, patakbuhin ito sa mga slice. Ipadala ang `scope` (`nodes`, `edges` o `history`), `offset` at `limit`, pagkatapos tawagin ulit gamit ang ibinalik na `nextOffset` hanggang `null` ito. Gawin ito para sa `nodes`, `edges`, at `history`, at tapusin gamit ang isang `{"scope":"snapshot"}` call, dahil hindi ginagalaw ng isang sliced run ang cached snapshot.
```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)
```
**Mga Prerequisite:** Node.js >= 20 na may npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 o Docker. Kinakailangan din ng automatic na engine install sa macOS/Linux ang `curl`, isang POSIX `sh`, at `tar`; gumagamit ang native Windows ng manual na pinned `iii.exe`, WSL2, o Docker Desktop.
