Agentul tău de programare își amintește totul. Nu mai trebuie să re-explici. Construit pe iii engine
Memorie persistentă pentru Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode și orice client MCP.

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

Gist-ul extinde modelul LLM Wiki al lui Karpathy cu scorarea încrederii, ciclu de viață, grafuri de cunoștințe și căutare hibridă: agentmemory este implementarea.

Instalare • Început rapid • Benchmark-uri • vs Competitori • Agenți • Cum funcționează • MCP • Vizualizator • Susținut de iii • Config • API

` sau `AGENTMEMORY_DATA_DIR` pentru a o suprascrie și reutilizează aceeași valoare la fiecare repornire. Pentru compatibilitate retroactivă, un `./data/state_store.db` sau `./data/iii-config.yaml` existent are prioritate față de valoarea implicită a platformei pentru instanța 0; o setare explicită prin flag sau variabilă de mediu are însă întotdeauna prioritate. Apoi demonstrează că reamintirea funcționează și oferă-i agentului tău skill-urile sale: ```bash npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory ``` Căutările pe cuvinte cheie ar trebui să găsească rezultate în modul implicit keyless, prin BM25. Interogarea `database performance optimization` din demo este intenționat semantică și poate returna zero rezultate până când este configurat un furnizor de embedding. Preferi să lași un agent de programare să facă totul? Dă-i o singură instrucțiune: > Preia și urmează instrucțiunile de la: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md Conectează oricând mai mulți agenți cu `agentmemory connect ` — 20 de adaptoare listate la [Funcționează cu orice agent](#works-with-every-agent). Referința completă a comenzilor este la [Început rapid](#quick-start).

Windows

Calea rapidă este WSL2. Configurarea motorului pe Windows nativ necesită descărcarea arhivei ZIP v0.22.1 fixate și extragerea manuală a `iii.exe`; CLI-ul nu o extrage automat. Docker Desktop este, de asemenea, suportat. Vezi [notele pentru Windows](#windows) pentru pașii detaliați.

Instalare globală / EACCES

```bash npm install -g @agentmemory/agentmemory@latest ``` Comanda npx de mai sus rămâne calea canonică pentru o instalare nouă și evită problemele de permisiuni legate de prefixul global.

npx servește o versiune veche

npx face cache pe versiune. Forțează cea mai recentă versiune cu `npx -y @agentmemory/agentmemory@latest`, sau șterge cache-ul o singură dată cu `rm -rf ~/.npm/_npx` (macOS/Linux; pe Windows șterge `%LOCALAPPDATA%\npm-cache\_npx`).

Rulezi deja propriul tău motor iii

agentmemory fixează versiunea iii-engine la `v0.22.1` și nu se va conecta la o versiune diferită (worker-ul nu poate vorbi protocolul altui motor). Oprește celălalt motor, apoi rulează `npx -y @agentmemory/agentmemory@latest`. Acesta instalează și rulează versiunea fixată v0.22.1 în `~/.agentmemory/bin`, lăsând neschimbat propriul tău `iii`.

---

agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST API. Toți agenții partajează același server de memorie.

Claude Code plugin nativ + 12 hook-uri + MCP	Codex CLI plugin nativ + 6 hook-uri + MCP	GitHub Copilot CLI MCP + hook-uri/skill-uri de plugin	Cursor plugin nativ + 7 hook-uri + MCP	OpenCode plugin de captură + MCP
Devin 6 hook-uri + skill-uri + MCP	OpenClaw plugin nativ + MCP	Hermes plugin nativ + MCP	pi plugin nativ + MCP	OpenHuman backend nativ prin trait-ul Memory
Gemini CLI server MCP	Antigravity MCP + hook-uri	Claude Desktop server MCP	Warp connect + MCP + skill-uri	Zed server MCP
Cline server MCP	Continue server MCP	Droid server MCP	Kiro server MCP	Qwen Code server MCP
DeepSeek Harness server MCP	Roo Code server MCP	Kilo Code server MCP	Goose server MCP	Aider REST API

_{Funcționează cu orice agent care vorbește MCP sau HTTP. Un singur server, memorii partajate între toți.}

--- Explici aceeași arhitectură la fiecare sesiune. Redescoperi aceleași bug-uri. Reînveți agentul cu aceleași preferințe. Memoria încorporată (CLAUDE.md, .cursorrules) se plafonează la 200 de linii și devine rapid depășită. agentmemory rezolvă asta. Captează discret tot ce face agentul tău, comprimă totul într-o memorie căutabilă și injectează contextul potrivit la începutul următoarei sesiuni. O singură comandă. Funcționează cu toți agenții. **Ce se schimbă:** În sesiunea 1 configurezi autentificarea JWT. În sesiunea 2 ceri limitare de rată (rate limiting). Agentul știe deja că autentificarea ta folosește middleware-ul jose din `src/middleware/auth.ts`, că testele tale verifică validarea token-urilor și că ai ales jose în locul lui jsonwebtoken pentru compatibilitate cu Edge — fără nicio re-explicare și fără copy-paste. ```bash npx -y @agentmemory/agentmemory@latest ``` Implicit, agentmemory salvează starea iii-engine în afara repository-ului din care este pornit: `~/Library/Application Support/agentmemory` pe macOS, `$XDG_DATA_HOME/agentmemory` sau `~/.local/share/agentmemory` pe Linux și `%APPDATA%\agentmemory` pe Windows. Un `./data/state_store.db` sau `./data/iii-config.yaml` vechi (legacy), dacă există, este reutilizat pentru instanța 0, înaintea valorii implicite a platformei. Pentru a alege explicit o locație, folosește `--data-dir ` sau setează `AGENTMEMORY_DATA_DIR`; orice setare explicită are prioritate față de detectarea automată a fișierelor legacy: ```bash npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest ``` Pornirile native și cele prin Docker folosesc același director rezolvat pe host; Docker îl montează (bind-mount) la `/data`. `--instance 1` adaugă `instance-1` la directorul rezolvat și selectează cvartetul separat de porturi implicite `3211/3212/3213/49234`. Notele celei mai recente versiuni: [CHANGELOG.md](../CHANGELOG.md). ---

### Acuratețea regăsirii **coding-agent-life-v1** (corpus intern, reproductibil în sandbox) | Adaptor | P@5 | R@5 | Rata de succes Top-5 | Latență p50 | |---|---|---|---|---| | **agentmemory hibrid** | **0.240** | **1.000** | **15 / 15** | 14 ms | | grep (referință) | 0.227 | 0.967 | 15 / 15 | 0 ms | Rată de succes Top-5 de 100% la **plafonul matematic P@5** pentru acest corpus (0.240, vezi scorecard-ul). Modul hibrid regăsește fiecare sesiune de referință (gold); grep ratează 1 din 2 sesiuni de referință la interogarea temporală pe mai multe sesiuni. Avantajul este pe **recall + temporal**, nu pe precizia agregată. Acest benchmark este mic și are puține exemple de referință; LongMemEval-S, mai amplu, de mai jos diferențiază mai bine. Detalierea completă pe tipuri + nota de corecție: [`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 de întrebări) | Sistem | R@5 | R@10 | MRR | |---|---|---|---| | **agentmemory** | **95.2%** | **98.6%** | **88.2%** | | Doar BM25 (fallback) | 86.2% | 94.6% | 71.5% |

### Economii de tokeni | Abordare | Tokeni/an | Cost/an | |---|---|---| | Lipire context complet | 19.5M+ | Imposibil (depășește fereastra de context) | | Rezumat de LLM | ~650K | ~$500 | | **agentmemory** | **~170K** | **~$10** | | agentmemory + embeddings locale | ~170K | **$0** |

> Model de embedding: `all-MiniLM-L6-v2` (local, gratuit, fără cheie API). Rapoarte complete: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparație cu competitorii: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), care acoperă agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo. **Reproduce local:** [`eval/README.md`](../eval/README.md), un harness cu adaptoare interschimbabile pentru LongMemEval `_s` (500 de întrebări publice) + `coding-agent-life-v1` (corpus intern de 15 sesiuni). Adaptoarele grep / vector / agentmemory sunt scorate în paralel, cu output NDJSON; scorecard-urile publicate ajung în [`docs/benchmarks/`](../docs/benchmarks/). **Se combină bine cu [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) și [Graphify](https://github.com/safishamsi/graphify).** Indexare code-graph, pipeline-uri de build multi-agent și grafuri de cunoștințe mai ample pe documente / PDF-uri / imagini / videoclipuri. agentmemory reține munca; aceste trei proiecte iluminează restul stratului de context. Rețete + tabel de direcționare a întrebărilor: [`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	Încorporat (CLAUDE.md)
Tip	Motor de memorie + server MCP	API strat de memorie	Runtime complet de agent	AI personal	API de memorie + aplicație	Hub de memorie de echipă (proxy LLM)	Memorie vectorială (OSS)	Motor de memorie (Oracle DB)	Sistem de memorie	Fișier static
Regăsire R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	N/A	Auto-raportat	PersonaMem 76% (auto-raportat)	~96.6% (auto-raportat)	94.4% (auto-raportat)	N/A	N/A (grep)
Captare automată	12 hook-uri (fără efort manual)	Apeluri manuale add()	Auto-editare de către agent	Manual	Extracție pe partea de API	Interceptare prin proxy (schimbare base-URL)	Manual	Extracție API	Manual	Editare manuală
Căutare	BM25 + Vector + Graf (fuziune RRF)	Vector + Graf	Vector (arhivă)	Semantică	Vector + RAG	4 tipuri de active (Chat / Skill / Wiki / CodeGraph)	Doar vector	Vector + semantică	Ponderată prin declin (decay)	Încarcă totul în context
Multi-agent	MCP + REST + lease-uri + semnale	API (fără coordonare)	Doar în interiorul runtime-ului Letta	Nu	Nu	Roluri de echipă + active partajate	Nu	Doar cu scope limitat	Partajat multi-agent	Fișiere per agent
Dependență de framework	Niciuna (orice client MCP)	Niciuna	Ridicată (trebuie folosit Letta)	Independent (standalone)	Niciuna	Proxy-ul intermediază fiecare apel de model	Niciuna	Oracle Database	Niciuna	Format per agent
Dependențe externe	Niciuna (SQLite + iii-engine)	Qdrant / pgvector	Postgres + bază de date vectorială	Multiple	Cloud administrat	Stivă Docker (Core + Hub + Proxy)	Magazin vectorial	Oracle AI Database	Niciuna	Niciuna
Ciclul de viață al memoriei	Consolidare pe 4 niveluri + declin + uitare automată	Extracție pasivă	Gestionat de agent	Manual	Uitare automată	Revizuire manuală; direcționare automată în lucru	Niciuna	Nespecificat	Declin + consolidare	Curățare manuală
Eficiența tokenilor	~1,900 tokeni/sesiune ($10/an)	Variază în funcție de integrare	Memorie de bază (core) în context	Variază	Preț cloud	Nespecificat	Fără buget de tokeni	Susținut de LLM (variază)	Variază	22K+ tokeni la 240 observații
Vizualizator în timp real	Da (port 3113)	Dashboard cloud	Dashboard cloud	Interfață web	Dashboard cloud	Interfață web Hub	Nu	Nu	Nu	Nu
Auto-hostat	Da (implicit)	Opțional	Opțional	Da	Nu (doar cloud)	Da (Docker)	Da	Da (Oracle DB)	Da	Da

_{Notă despre benchmark: doar R@5 pentru agentmemory este un rezultat măsurat de noi înșine (LongMemEval-S, reproductibil din benchmark/COMPARISON.md). Cifrele pentru mem0 și Letta sunt numerele lor publicate pe LoCoMo (un set de date diferit); cifrele pentru MemPalace, supermemory, TencentDB (PersonaMem) și oracleagentmemory sunt afirmații auto-raportate de furnizori, pe care nu le-am reprodus independent (rularea oracleagentmemory a folosit GPT-5.5 împotriva unei Oracle AI Database). Prezentate una lângă alta doar orientativ, nu ca o comparație directă pe date identice. Numărul de stele este aproximativ și variază în timp.} **Jucători mai noi** merită cunoscuți, comparați în detaliu în [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md): | Sistem | ⭐ | Unghi | |--------|---|-------| | Zep / Graphiti | 30K | Graf de cunoștințe temporal; cele mai bune rezultate publicate pentru interogări temporale (LongMemEval 63.8%), dar graful se construiește asincron, așa că faptele noi pot întârzia | | Cognee | 30K | Ingestie document-în-graf-de-cunoștințe, doar Python, construit pentru extracție structurată de entități, nu pentru captarea sesiunilor | Niciunul dintre acestea nu captează automat din hook-urile agenților de programare, nu oferă un vizualizator local-first și nu rulează în mod keyless — combinația pe care este construit agentmemory. ---

Compatibilitate: această versiune are ca țintă `iii-sdk` 0.22.1 și fixează iii-engine la v0.22.1. ### Încearcă-l în 30 de secunde ```bash # Terminal 1: start the server npx -y @agentmemory/agentmemory@latest # Terminal 2: seed sample data and see recall in action npx -y @agentmemory/agentmemory@latest demo ``` `demo` inițializează 3 sesiuni realiste (autentificare JWT, corectarea unei interogări N+1, limitare de rată) și rulează căutări pe acestea. Instalările keyless dezactivează vectorii, astfel încât interogările pe cuvinte cheie `mem::search` ar trebui să găsească rezultate prin BM25, în timp ce `database performance optimization` poate returna zero. `smart-search` poate returna, în plus, rezultate structurale din graf, atunci când există date de graf. Pentru ca interogarea semantică să găsească corectarea N+1 prin vectori, setează `EMBEDDING_PROVIDER=local`, repornește și lasă prima descărcare a modelului să se finalizeze. Deschide `http://localhost:3113` pentru a urmări memoria construindu-se în timp real. ### Validează o instalare nouă și persistența la repornire Cu serverul pornit, validează REST, health, vizualizatorul și starea runtime-ului susținut de iii: ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` Panelul de pregătire de la pornire ține cont de toate cele patru porturi: REST/MCP HTTP pe 3111, stream-urile iii pe 3112, vizualizatorul pe 3113 și WebSocket-ul worker-ului iii pe 49134. `status` confirmă starea de sănătate (health) a agentmemory și furnizorul activ / modul de embedding. Salvează o probă și confirmă că este căutabilă: ```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}' ``` Apoi rulează `npx -y @agentmemory/agentmemory@latest stop`, pornește din nou comanda canonică în Terminalul 1, așteaptă `/agentmemory/livez` și repetă căutarea. Proba trebuie să fie returnată tot. Dacă ai ales un `--data-dir` personalizat, transmite același director și la repornire. ### Comenzi zilnice Instalarea și configurarea se află în [Instalare](#install) mai sus (prima rulare te ghidează prin ea). De zi cu zi: ```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 ``` ### Reluarea sesiunii (Session Replay) Fiecare sesiune înregistrată de agentmemory poate fi reluată. Deschide vizualizatorul, alege tab-ul **Replay** și derulează pe linia temporală: prompturile, apelurile de instrumente, rezultatele acestora și răspunsurile sunt redate ca evenimente discrete, cu play/pause, control al vitezei (0.5x–4x) și scurtături de tastatură (spațiu pentru comutare, săgeți pentru a avansa pas cu pas). Pentru a prelua transcrieri JSONL mai vechi din Claude Code: ```bash # Import everything under the default ~/.claude/projects npx -y @agentmemory/agentmemory@latest import-jsonl # Or import a single file npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl ``` Sesiunile importate apar în selectorul Replay alături de cele native. Sub capotă, fiecare înregistrare trece prin funcțiile iii `mem::replay::load`, `mem::replay::sessions` și `mem::replay::import-jsonl`, fără servere pe canale secundare. Fiecare transcriere importată este indexată pentru căutare, marcată cu canalul de origine `import` și minată pentru un cristal de sesiune (session crystal) și lecții. > **Atenție dacă te bazezi pe `import-jsonl` ca metodă principală de captare:** `cleanupPeriodDays` din Claude Code (în `~/.claude/settings.json`, implicit **30**) șterge automat transcrierile JSONL mai vechi decât această fereastră din `~/.claude/projects/`. Dacă instalezi agentmemory de la zero peste un istoric Claude Code de luni de zile, orice e mai vechi de 30 de zile a dispărut deja înainte de primul import. Fie rulează `import-jsonl` printr-un cron, fie crește `cleanupPeriodDays` la o valoare mai mare, fie conectează hook-urile de captare automată (calea implicită de instalare a plugin-ului), astfel încât fiecare tură să ajungă în agentmemory cât timp sesiunea este activă, iar curățarea JSONL nu mai contează. ### Actualizare / Întreținere Folosește comanda de întreținere atunci când vrei, în mod intenționat, să actualizezi runtime-ul local: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` Atenție: această comandă modifică workspace-ul/runtime-ul curent. Poate actualiza dependențele JavaScript și poate descărca imaginea Docker fixată `iiidev/iii:0.22.1`. Nu instalează niciodată un motor iii nefixat sau mai nou. Detaliile de implementare se află în `src/cli.ts` (vezi `runUpgrade`, în jurul zonei `src/cli.ts:544-595`). ### Claude Code (un singur bloc, lipește-l) ```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 fără instalarea plugin-ului (cale MCP independentă) Dacă conectezi serverul MCP al agentmemory direct prin `~/.claude.json`, în loc să folosești `/plugin install`, Claude Code nu rezolvă niciodată `${CLAUDE_PLUGIN_ROOT}` și trebuie să indici scripturile de hook prin căi absolute în `~/.claude/settings.json`. Aceste căi includ de obicei versiunea agentmemory (de ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), astfel încât următoarea actualizare rupe silențios fiecare hook. Soluție alternativă: ```bash agentmemory connect claude-code --with-hooks ``` Aceasta îmbină aceleași comenzi de hook în `~/.claude/settings.json`, cu căi absolute rezolvate către directorul `plugin/` inclus în pachetul `@agentmemory/agentmemory` instalat curent. Rulează din nou comanda după actualizarea agentmemory, pentru a reîmprospăta căile. Intrările proprii ale utilizatorului din același fișier sunt păstrate; sunt înlocuite doar intrările anterioare ale agentmemory. Folosirea căii `/plugin install` rămâne abordarea recomandată. Pentru deployment-uri la distanță sau protejate, pornește Claude Code cu `AGENTMEMORY_URL` și `AGENTMEMORY_SECRET` setate. Plugin-ul transmite ambele valori către serverul MCP inclus; când `AGENTMEMORY_URL` este gol, shim-ul MCP folosește `http://localhost:3111`. ### Codex CLI (platforma de plugin-uri Codex) ```bash # 1. start the memory server in a separate terminal npx -y @agentmemory/agentmemory@latest # 2. register the agentmemory marketplace and install the plugin codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` Plugin-ul Codex este livrat din același director `plugin/` ca plugin-ul Claude Code. Acesta înregistrează: - Un bridge MCP stdio inclus către daemonul în execuție, fără descărcare prin npm sau store de fallback. Vezi [ghidul local pentru Codex](../docs/plugins/codex-local.md) pentru a testa un build nepublicat. - 6 hook-uri de ciclu de viață: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 9 skill-uri invocabile: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 skill-uri de referință pe care agentul le încarcă la cerere (disciplina memoriei, instrumente MCP, API REST, configurare, agenți, hook-uri, arhitectură și ghidul de scriere a skill-urilor) Motorul de hook-uri al lui Codex injectează `CLAUDE_PLUGIN_ROOT` în subprocesele de hook (conform [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), astfel încât aceleași scripturi de hook funcționează pe ambele platforme (hosts), fără duplicare. Evenimentele Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure sunt specifice doar Claude Code și nu sunt înregistrate pentru Codex. #### Încrederea și compatibilitatea hook-urilor Codex Declanșarea nativă a hook-urilor de plugin este verificată cu Codex CLI 0.150.1. Acordă încredere (trust) hook-urilor de plugin înainte de a te aștepta la captare. Comportamentul Codex Desktop depinde de runtime-ul său inclus; verifică `/hooks` și confirmă un eveniment captat înainte de a activa o soluție alternativă. Dacă host-ul tău necesită hook-uri globale, oglindește comenzile în `~/.codex/hooks.json`. Când MCP este deja conectat, conectorul actual are nevoie de `--force` pentru a ajunge la instalarea hook-urilor: ```bash agentmemory connect codex --with-hooks --force ``` Aceasta îmbină hook-urile globale și rescrie intrarea MCP a agentmemory, păstrând intrările fără legătură. Verifică orice setări personalizate ale endpoint-ului agentmemory înainte de a folosi `--force`. Rulează din nou după actualizare, pentru a reîmprospăta căile scripturilor. Activează fie hook-urile native de plugin, fie copiile globale, pentru a evita captarea duplicată. ### GitHub Copilot CLI Pentru modul agent din VS Code, folosește [ghidul MCP și captare automată pentru Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Conectorul CLI nu configurează VS Code. ```bash # MCP-only wiring agentmemory connect copilot-cli # Alternatively, full hooks/skills plugin from the GitHub subdir copilot plugin install rohitg00/agentmemory:plugin ``` `agentmemory connect copilot-cli` îmbină `mcpServers.agentmemory` în `~/.copilot/mcp-config.json` (sau `$COPILOT_HOME/mcp-config.json`, când `COPILOT_HOME` este setat) și păstrează serverele existente. Pe Windows nativ, acesta este singurul adaptor `connect` automatizat; configurează manual orice alt agent nativ pe Windows. `connect` în WSL este suportat doar atunci când agentul țintă este instalat în același mediu WSL. Copilot detectează serverul MCP la următoarea pornire sau după `/mcp`. Instalează și plugin-ul atunci când vrei experiența completă de hook-uri/skill-uri.

OpenClaw (lipește acest prompt)

```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`. ``` Ghid complet: [`integrations/openclaw/`](../integrations/openclaw/)

Hermes Agent (lipește acest prompt)

```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. ``` Ghid complet: [`integrations/hermes/`](../integrations/hermes/)

### Alți agenți Pornește serverul de memorie: `npx -y @agentmemory/agentmemory@latest` #### Skill-uri native prin `npx skills add` (50+ agenți) agentmemory vine cu 17 skill-uri în formatul `/SKILL.md`, în stilul Claude Code: 9 skill-uri de acțiune invocabile (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) și 8 skill-uri de referință pe care agentul le încarcă la cerere (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Skill-urile de referință conțin tabele de date generate din sursă, așa că nu devin niciodată desincronizate. CLI-ul [`skills`](https://npmjs.com/package/skills) de la vercel-labs le instalează automat în directorul nativ de skill-uri al agentului apelant, pe 50+ agenți (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf și altele): ```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 ``` Aceasta este **complementară** cu `agentmemory connect `: - `agentmemory connect ` scrie configurația serverului MCP, astfel încât instrumentele să fie disponibile. - `npx skills add rohitg00/agentmemory` instalează skill-urile, astfel încât agentul să știe când să le apeleze. Pentru puținii agenți pe care CLI-ul skills nu îi acoperă încă (Zed v1.3.x și versiuni mai vechi), plasează tu însuți cele 17 fișiere SKILL.md în directorul nativ de skill-uri al agentului; același format funcționează pretutindeni. #### Bloc MCP standard Intrarea agentmemory este **același bloc de server MCP** pe fiecare host care folosește forma `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw): ```json "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}" } } ``` **Îmbină această intrare în obiectul `mcpServers` existent** din fișierul de configurare al host-ului; nu înlocui fișierul. Dacă fișierul are deja alte servere, adaugă `agentmemory` alături de ele, ca o altă cheie în interiorul `mcpServers`. Dacă `mcpServers` lipsește complet, lipește blocul în interiorul `{ "mcpServers": { ... } }`. Placeholder-ele `${VAR}` preiau `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` din shell la pornirea serverului MCP; variabilele nesetate transmit șiruri vide, iar shim-ul trece la `http://localhost:3111`. O singură intrare conectată acoperă atât deployment-urile locale, cât și cele la distanță (k8s / cu reverse-proxy). | Agent | Fișier de configurare | Note | |---|---|---| | **Cursor (doar MCP)** | `~/.cursor/mcp.json` | Îmbină în `mcpServers`, sau `agentmemory connect cursor`. Este disponibil și un deeplink cu un singur clic pe site. | | **Cursor (plugin complet)** | `.cursor-plugin/` | Listare în Cursor Marketplace (trimiterea este în curs de revizuire) sau Cursor Settings → Plugins → checkout local. Înregistrează 7 hook-uri de captare automată (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill-uri + serverul MCP, cu `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` gestionate în dashboard-ul de plugin-uri al Cursor. Funcționează în IDE-ul Cursor și în CLI-ul `cursor-agent`; prompturile din modul print al CLI-ului sunt completate retroactiv din transcrierea sesiunii, la finalul sesiunii. | | **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Îmbină în `mcpServers`. Repornește Claude Desktop după editare. | | **Cline / Roo Code / Kilo Code** | Setările MCP din Cline (interfața de Settings → MCP Servers → Edit) | Același bloc `mcpServers`. | | **Devin CLI (MCP + hook-uri)** | `~/.config/devin/config.json` | `agentmemory connect devin` îmbină intrarea MCP; `--with-hooks` adaugă șase hook-uri native de captare automată (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd), cu matcher-ele de instrumente scrise cu litere mici specifice lui Devin. Verifică cu `devin mcp list` și `/hooks` în interiorul devin. | | **Devin CLI (plugin complet)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin`, rulat dintr-un checkout, înregistrează toate cele 17 skill-uri ca comenzi slash `/agentmemory:`, plus serverul MCP. Hook-urile de plugin din Devin nu pot declanșa `SessionStart`/`SessionEnd`, așa că asociază-l cu `connect devin --with-hooks` pentru captarea completă a sesiunii. | | **Devin (cloud)** | Settings → Connections → MCP servers | Adaugă un MCP personalizat (STDIO): comanda `npx`, argumente `-y @agentmemory/mcp@latest`, variabila de mediu `AGENTMEMORY_URL` care indică un deployment agentmemory accesibil din rețea, plus `AGENTMEMORY_SECRET` (sesiunile din cloud nu pot accesa localhost — vezi [`deploy/`](../deploy/)). Stochează secretul în Devin Secrets, apoi folosește „Test listing tools” pentru a verifica că apar toate cele 54 de instrumente. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (se îmbină automat). | | **GitHub Copilot CLI (doar MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` îmbină `mcpServers.agentmemory`; Copilot îl detectează la următoarea pornire sau după `/mcp`. | | **GitHub Copilot CLI (plugin complet)** | Instalare plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` pentru plugin-ul din subdirectorul GitHub. | | **OpenClaw** | Configurația MCP OpenClaw | Același bloc `mcpServers`. Mai în profunzime: `openclaw plugins install ./integrations/openclaw` ocupă slotul de memorie al OpenClaw (comută automat de la `memory-core`); setează `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, altfel captarea turei este blocată silențios. Vezi [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (doar MCP)** | `.codex/config.toml` | Formă TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, sau adaugă manual `[mcp_servers.agentmemory]`. | | **Codex CLI (plugin complet)** | Marketplace-ul de plugin-uri Codex | `codex plugin marketplace add rohitg00/agentmemory`, apoi `codex plugin add agentmemory@agentmemory`. Înregistrează MCP + 6 hook-uri de ciclu de viață + 17 skill-uri. Acordă încredere hook-urilor și verifică captarea pe host-ul tău; vezi [configurarea și validarea Codex](../docs/plugins/codex-local.md). | | **OpenCode (doar MCP)** | `opencode.json` | Formă diferită: cheia `mcp` la nivel superior, comanda ca array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (plugin complet)** | `plugin/opencode/` | 22 de hook-uri de captare automată, care acoperă ciclul de viață al sesiunii, mesajele, instrumentele și erorile. Atribuirea proiectului se face per sesiune, astfel încât un proces OpenCode care se întinde pe mai multe repository-uri înregistrează fiecare sesiune sub propriul ei proiect. Două comenzi slash (`/recall`, `/remember`). Copiază `plugin/opencode/` în workspace-ul tău OpenCode și adaugă intrarea plugin-ului în `opencode.json`. Vezi [`plugin/opencode/README.md`](../plugin/opencode/README.md) pentru tabelul complet de hook-uri + analiza lacunelor. | | **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instalează extensia inclusă în directorul de auto-detectare al pi (reamintire la pornirea agentului, captare la finalul agentului, instrumentele `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` într-un pi care rulează deja o detectează. [`integrations/pi`](../integrations/pi/) este, de asemenea, un pachet pi (`pi install ./integrations/pi` dintr-un checkout). | | **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` oferă furnizorul de memorie cu 6 hook-uri (prefetch, captarea turei, final de sesiune, pre-compresie, oglindirea MEMORY.md, bloc de system prompt). Validează cu `hermes plugins doctor` și `hermes memory status`. Vezi [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` scrie blocul standard `mcpServers`. Payload-ul hook-ului este compatibil la nivel de câmpuri cu Claude Code, astfel încât scripturile existente cu 12 hook-uri funcționează fără modificări; conectează-le prin secțiunea `hooks` din același `settings.json`. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instalează MCP și hook-urile de captare în directorul partajat de personalizare. Vezi [configurarea și limitele Antigravity](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` folosește aceeași configurație MCP și de hook-uri ca versiunile IDE actuale. Instalările existente ar trebui să se reîmprospăteze cu `--force`; vezi [notele de actualizare](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` scrie configurația la nivel de utilizator. Suprascrierile la nivel de workspace se pun în `.kiro/settings/mcp.json`, alături de codul tău. | | **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` scrie blocul standard `mcpServers`. Warp detectează automat și skill-urile din `.claude/skills/`; odată instalat plugin-ul Claude Code, cele 8 skill-uri agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) apar nativ în paleta de comenzi slash a Warp. | | **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` scrie blocul standard `mcpServers`. Utilizatorii extensiei VS Code: lipește același bloc prin Cline Settings → MCP Servers → Edit JSON. | | **Continue.dev** | `~/.continue/config.yaml` (preferat) sau `config.json` (vechi/legacy) | `agentmemory connect continue` creează `config.yaml` de la zero când niciunul dintre cele două nu există, sau modifică `config.json`-ul existent. **Dacă ai deja `config.yaml`**, adaptorul afișează exact blocul de lipit sub `mcpServers:`; nu îți rescrie silențios yaml-ul, pentru că păstrarea sigură a comentariilor și a ancorelor necesită un parser YAML pe care pachetul nu îl include. Continue folosește forma de array (nu obiect) pentru `mcpServers`. | | **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` scrie sub `context_servers` (cheia specifică Zed, NU `mcpServers`). Serverele MCP la distanță pot fi conectate, în schimb, prin `{"url": "..."}`. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` scrie blocul standard `mcpServers`. Suprascrierile la nivel de proiect se pun în `/.factory/mcp.json`. Transmite `--with-hooks` pentru captare automată nativă. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` adaugă un rând `@deepseek-ai/dsh-mcp-client` în stratul de patch la nivel de home, pe care îl încarcă fiecare profil Harness; instrumentele se înregistrează ca `mcp__agentmemory__*`. Transmite `--with-hooks` pentru a conecta și captarea automată: scripturile de hook Claude Code incluse rulează prin bridge-ul oficial `@deepseek-ai/dsh-hooks-claude-code` al lui Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), printr-un manifest scris în `$DSH_HOME/agentmemory.hooks.json`. Implicit `~/.dsh`, când `DSH_HOME` nu este setat. | | **Goose** | Interfața de setări MCP din Goose | Același bloc `mcpServers`; folosește `goose configure` → Add Extension → MCP. Editarea directă a YAML-ului la `~/.config/goose/config.yaml` este suportată, dar schema folosește `extensions:` + `cmd` (nu `mcpServers:` + `command`). | | **Aider** | n/a | Vorbește direct cu API-ul REST: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. | | **Orice agent (32+)** | n/a | `npx skillkit install agentmemory` detectează automat host-ul și îmbină configurația. | **Clienții MCP sandbox-izați** (Flatpak / Snap / containere restrictive) care nu pot accesa `localhost`-ul host-ului: setează și `"AGENTMEMORY_FORCE_PROXY": "1"` în blocul `env` și direcționează `AGENTMEMORY_URL` către o rută pe care sandbox-ul o poate accesa efectiv (de ex. IP-ul tău din rețeaua locală). ### Acces programatic (Python / Rust / Node) agentmemory își înregistrează operațiile de bază ca funcții iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Orice limbaj care are un SDK iii le poate apela direct prin `ws://localhost:49134`, fără a avea nevoie de un client REST separat pentru fiecare limbaj. ```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"}, }) ``` Exemplu funcțional: [`examples/python/`](../examples/python/) (început rapid + flux de observație/reamintire). REST pe `:3111` rămâne disponibil pentru host-urile fără runtime iii. ### Din sursă ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` Aceasta pornește agentmemory cu un `iii-engine` local, dacă binarul fixat este deja instalat, sau folosește Docker Compose, când este selectat. REST, stream-urile și vizualizatorul se leagă (bind) implicit la `127.0.0.1`. Calea automată pentru binarul pe macOS/Linux necesită `curl`, un `sh` POSIX și `tar`. Instalează manual `iii-engine`. **agentmemory fixează momentan `iii-engine` la `v0.22.1`**, aceeași versiune ca dependența sa `iii-sdk`; worker-ul vorbește protocolul de rețea al acelui motor, iar 0.20.0 a reorganizat suprafața SDK-ului, așa că cele două avansează împreună în versiunile agentmemory. Suprascrie cu `AGENTMEMORY_III_VERSION=`, dacă rulezi propriul tău motor și știi că se potrivește. - **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:** înlocuiește `aarch64-apple-darwin` cu `x86_64-apple-darwin` - **Linux x64:** înlocuiește cu `x86_64-unknown-linux-gnu` - **Linux arm64:** înlocuiește cu `aarch64-unknown-linux-gnu` - **Windows:** descarcă `iii-x86_64-pc-windows-msvc.zip` de la [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) și extrage `iii.exe` în `%USERPROFILE%\.agentmemory\bin\iii.exe` Fiecare arhivă are un fișier `.sha256` corespunzător pe pagina de release; când schimbi platforma, folosește hash-ul din acel fișier în verificarea de mai sus (pe Windows: `Get-FileHash`). Installer-ul automat din `npx @agentmemory/agentmemory` fixează aceste hash-uri și refuză o arhivă care nu se potrivește. Sau folosește Docker (`docker-compose.yml`-ul inclus descarcă `iiidev/iii:0.22.1`). Documentație completă: [iii.dev/docs](https://iii.dev/docs). ### Windows agentmemory rulează pe Windows 10/11, dar pachetul Node.js, de unul singur, nu este suficient; ai nevoie și de runtime-ul iii-engine v0.22.1 fixat, ca proces în fundal. CLI-ul nu extrage automat arhiva ZIP pentru Windows, așa că utilizatorii Windows nativ trebuie să instaleze manual `iii.exe`, să folosească WSL2 sau să aleagă Docker Desktop. Conectarea MCP automatizată pe Windows nativ suportă doar `agentmemory connect copilot-cli`. Pentru Claude Code, Codex, Cursor și orice alt agent nativ pe Windows, copiază blocul MCP manual din [Alți agenți](#other-agents) în configurația Windows a acelui agent. Rularea `connect` în WSL este potrivită doar atunci când agentul țintă este instalat și el în același mediu WSL; aceasta nu editează configurația unui agent de pe host-ul Windows. **Opțiunea A: binar Windows precompilat (recomandat)** ```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 ``` **Opțiunea 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 ``` **Opțiunea C: doar MCP independent (fără motor).** Dacă ai nevoie doar de instrumentele MCP pentru agentul tău și nu ai nevoie de API-ul REST, de vizualizator sau de job-uri cron, poți sări complet peste motor: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or via the shim package: npx -y @agentmemory/mcp ``` **Diagnosticare pentru Windows:** dacă `npx -y @agentmemory/agentmemory@latest` eșuează, rulează-o din nou cu `--verbose` pentru a vedea stderr-ul real al motorului. Moduri de eșec frecvente: | Simptom | Remediere | |---|---| | `The engine process started but the REST API never responded.` | Confirmă că toate cele patru porturi derivate sunt libere, verifică dacă `iii.exe`-ul fixat a rămas activ, apoi rulează din nou cu `--verbose` și inspectează stderr-ul capturat al motorului | | `Could not start iii-engine` | Nici `iii.exe`, nici Docker nu sunt instalate. Vezi Opțiunea A sau B de mai sus | | Conflict de port | `netstat -ano \| findstr :3111` pentru a vedea ce este ocupat, apoi termină procesul sau folosește `--port ` | | Trecerea la Docker este omisă, deși Docker este instalat | Asigură-te că Docker Desktop rulează efectiv (iconița din system tray) | > Notă: **motorul** iii este un binar precompilat, nu un cargo crate, așa că nu încerca să îl instalezi cu `cargo install`. (**SDK-urile** iii sunt publicate pe crates.io, npm și PyPI, dar agentmemory nu are nevoie de ele.) Toate metodele suportate de instalare a motorului sunt fixate la v0.22.1: binarul precompilat de mai sus, calea de auto-instalare macOS/Linux a agentmemory (necesită `curl`, `sh` POSIX și `tar`) și imaginea Docker `iiidev/iii:0.22.1`. Un simplu `install.sh | sh` din upstream instalează cel mai recent motor, pe care agentmemory nu îl suportă. Folosește `npx -y @agentmemory/agentmemory@latest`; pe macOS/Linux, aceasta preia motorul fixat în `~/.agentmemory/bin`. ---

Implementare (Deploy)

Șabloane cu un singur clic pentru hosting administrat. Fiecare șablon include un Dockerfile de sine stătător, care descarcă `@agentmemory/agentmemory` de pe npm și copiază binarul motorului iii din imaginea oficială `iiidev/iii` de pe Docker Hub; nu este necesară o imagine agentmemory precompilată. Stocarea persistentă este montată la `/data`; entrypoint-ul de la prima pornire suprascrie configurația iii inclusă în pachetul npm (care se leagă la `127.0.0.1`) cu una ajustată pentru deployment, care se leagă la `0.0.0.0` și folosește căi `/data` absolute, generează secretul HMAC, apoi reduce privilegiile de la `root` la `node`, prin `gosu`, înainte de a executa (exec) CLI-ul agentmemory.

Butonul de implementare cu un singur clic al Render necesită `render.yaml` în rădăcina repository-ului, pe care îl păstrăm intenționat curat (gol). Folosește fluxul Render Blueprint documentat în [`deploy/render/`](.././deploy/render/README.md) pentru a indica manual blueprint-ul din repository. Detaliile complete de configurare (capturarea HMAC, tunel SSH pentru vizualizator, rotație, backup, costuri minime) se află în [`deploy/`](.././deploy/README.md): - [`deploy/fly`](.././deploy/fly/README.md): o singură mașină, cu `auto_stop_machines = "stop"`; cel mai ieftin în repaus (idle). - [`deploy/railway`](.././deploy/railway/README.md): tarif fix pentru planul Hobby, volum în dashboard. - [`deploy/render`](.././deploy/render/README.md): flux Blueprint, instantanee (snapshots) automate de disc pe planurile plătite. - [`deploy/coolify`](.././deploy/coolify/README.md): auto-hostat pe propriul tău VPS, prin [Coolify](https://coolify.io/self-hosted); aceeași stivă Docker Compose, tu deții host-ul și datele. Este publicat doar portul `3111`. Vizualizatorul de pe `3113` rămâne legat la loopback în interiorul containerului; README-ul fiecărui șablon documentează modelul de tunel SSH pentru a-l accesa. ---

Fiecare agent de programare uită totul când sesiunea se termină, iar fiecare sesiune nouă începe cu tine re-explicând stack-ul tău. agentmemory rulează în fundal și elimină acest pas. ```text Session 1: "Add auth to the API" Agent writes code, runs tests, fixes bugs agentmemory silently captures every tool use Session ends -> observations compressed into structured memory Session 2: "Now add rate limiting" Agent already knows: - Auth uses JWT middleware in src/middleware/auth.ts - Tests in test/auth.test.ts cover token validation - You chose jose over jsonwebtoken for Edge compatibility Zero re-explaining. Starts working immediately. ``` ### vs memoria încorporată a agentului Fiecare agent de programare AI vine cu memorie încorporată: Claude Code are `MEMORY.md`, Cursor are notepad-uri, Cline are memory bank. Acestea funcționează ca niște bilețele adezive (sticky notes). agentmemory este baza de date căutabilă din spatele bilețelelor adezive. | | Încorporat (CLAUDE.md) | agentmemory | |---|---|---| | Scalare | Plafon de 200 de linii | Nelimitat | | Căutare | Încarcă totul în context | BM25 + vector + graf (doar top-K) | | Cost în tokeni | 22K+ la 240 de observații | ~1,900 tokeni (92% mai puțin) | | Între agenți | Fișiere per agent | MCP + REST (orice agent) | | Coordonare | Niciuna | Lease-uri, semnale, acțiuni, rutine | | Observabilitate | Citire manuală a fișierelor | Vizualizator în timp real pe :3113 | ---

### Pipeline-ul de memorie ```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 ``` ### Consolidarea memoriei pe 4 niveluri Modelată după modul în care creierul uman procesează memoria, inclusiv consolidarea prin somn. | Nivel | Ce reprezintă | Analogie | |------|------|---------| | **Working (de lucru)** | Observații brute din folosirea instrumentelor | Memorie pe termen scurt | | **Episodic** | Rezumate comprimate ale sesiunilor | „Ce s-a întâmplat” | | **Semantic** | Fapte și modele extrase | „Ce știu” | | **Procedural** | Fluxuri de lucru și modele de decizie | „Cum se face” | Memoriile se degradează în timp (curba lui Ebbinghaus). Memoriile accesate frecvent se întăresc. Memoriile vechi/inactive sunt eliminate automat. Contradicțiile sunt detectate și rezolvate. ### Ce se captează | Hook | Captează | |------|----------| | `SessionStart` | Calea proiectului, ID-ul sesiunii | | `UserPromptSubmit` | Prompturile utilizatorului (filtrate pentru confidențialitate) | | `PreToolUse` | Modele de acces la fișiere + context îmbogățit | | `PostToolUse` | Numele instrumentului, input, output | | `PostToolUseFailure` | Contextul erorii | | `PreCompact` | Reinjectează memoria înainte de compactare | | `SubagentStart/Stop` | Ciclul de viață al sub-agentului | | `Stop` | Rezumat de final de sesiune | | `SessionEnd` | Marcator de sesiune finalizată | ### Capabilități esențiale | Capabilitate | Descriere | |---|---| | **Captare automată** | Fiecare folosire a unui instrument este înregistrată prin hook-uri, fără efort manual | | **Căutare semantică** | BM25 + vector + graf de cunoștințe, cu fuziune RRF | | **Evoluția memoriei** | Versionare, suprascriere (supersession), grafuri de relații | | **Igiena reamintirii** | Versiunile de memorie suprascrise sunt eliminate din indecșii de căutare; lanțul de versiuni din KV păstrează istoricul complet | | **Indicii de aproape-duplicat** | Salvările raportează o potrivire consultativă `similarTo`, atunci când conținutul nou se aseamănă foarte mult cu o memorie existentă | | **Scopare per agent** | `agentId` traversează salvarea și reamintirea pe REST, MCP și indexul de căutare, în mod partajat sau izolat | | **Proveniență la momentul scrierii** | Fiecare observație și memorie poartă un canal de origine imuabil (user, agent, tool, import sau shared), marcat la captare, salvare și import | | **Uitare automată** | Expirare TTL, detectarea contradicțiilor, eliminare pe baza importanței | | **Confidențialitate înainte de toate** | Cheile API, secretele, etichetele `` sunt eliminate înainte de stocare | | **Auto-reparare** | Circuit breaker, lanț de fallback între furnizori, monitorizarea stării de sănătate | | **Punte Claude** | Sincronizare bidirecțională cu MEMORY.md | | **Graf de cunoștințe** | Extracția entităților + traversare BFS | | **Memorie de echipă** | Partajată și privată, separată pe namespace-uri, între membrii echipei | | **Proveniența citărilor** | Urmărește orice memorie înapoi la observațiile sursă | | **Instantanee Git** | Versionează, revino (rollback) și compară (diff) starea memoriei | ---

Regăsire triplu-flux, care combină trei semnale: | Flux | Ce face | Când | |---|---|---| | **BM25** | Potrivire pe cuvinte cheie cu stemming și expansiune de sinonime | Mereu activ | | **Vector** | Similaritate cosinus pe embeddings dense | Furnizor de embedding configurat | | **Graf** | Traversarea grafului de cunoștințe prin potrivirea entităților | Entități detectate în interogare | Fuzionate prin Reciprocal Rank Fusion (RRF, k=60) și diversificate pe sesiune (maximum 3 rezultate per sesiune). Când indexul vectorial este populat, `mem::search` (din spatele lui `memory_recall`) folosește clasificatorul hibrid BM25 + vector. Fără embeddings, folosește BM25. `smart-search` poate fuziona, în plus, potriviri structurale din graf, atunci când există date de graf, inclusiv în modul keyless. Reamintirea lecțiilor rulează pe un index BM25 dedicat, în memorie, în loc să scaneze întregul corpus la fiecare interogare. Versiunile de memorie suprascrise sunt excluse din fiecare rută de reamintire; lanțul de versiuni le păstrează istoricul. Vectorii supraviețuiesc unui crash sau unei terminări forțate (force-kill). Indexul vectorial este salvat pe loturi (buckets) cel mult o dată la fiecare `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minute). Fiecare vector adăugat sau eliminat între timp este scris imediat și într-un mic jurnal de așteptare (pending log) din state store, iar următoarea pornire îl reaplică fără a apela furnizorul de embedding. Fiecare salvare reușită golește jurnalul. Documentele care încă nu au un vector după reaplicare sunt reîncorporate (re-embedded) în fundal, pe loturi de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), până când nu mai rămâne niciunul, iar o reumplere (backfill) întreruptă continuă la următoarea pornire. `/agentmemory/status` și vizualizatorul arată dimensiunea jurnalului de așteptare și starea reumplerii. Instalările keyless nu scriu nimic. BM25 tokenizează, din oficiu, greaca, chirilica, ebraica, araba și latina cu diacritice. Pentru memorii în chineză / japoneză / coreeană, instalează segmentatoarele opționale (`npm install @node-rs/jieba tiny-segmenter`) pentru a împărți secvențele CJK în tokeni la nivel de cuvânt; fără ele, agentmemory trece ușor la tokenizarea întregii secvențe și afișează o singură dată un indiciu pe stderr. ### Furnizori de embedding Instalările keyless dezactivează embeddings vectoriale: `mem::search` folosește BM25, în timp ce `smart-search` poate folosi și datele structurale existente din graf. Pentru a opta pentru embeddings semantice gratuite, pe dispozitiv, adaugă următoarele în `~/.agentmemory/.env` și repornește agentmemory: ```env EMBEDDING_PROVIDER=local ``` Instalarea npm normală include runtime-ul opțional `@huggingface/transformers`. Prima cerere de embedding descarcă `Xenova/all-MiniLM-L6-v2`, așa că necesită acces la rețea și poate dura mai mult; inferența următoare rulează pe dispozitiv. Furnizorii la distanță sunt detectați automat după cheile lor, cu excepția cazului în care `EMBEDDING_PROVIDER` îi suprascrie. | Furnizor | Model | Cost | Note | |---|---|---|---| | **Local (opțiune recomandată)** | `all-MiniLM-L6-v2` | Gratuit | Pe dispozitiv, după prima descărcare a modelului; +8pp recall față de doar-BM25 | | Gemini | `gemini-embedding-001` | Nivel gratuit | 100+ limbi, 768/1536/3072 dimensiuni (MRL), input de 2048 de tokeni. Înlocuiește `text-embedding-004` ([depreciat, dezactivat 14 ian. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) | | OpenAI | `text-embedding-3-small` | $0.02/1M | Cea mai bună calitate | | Voyage AI | `voyage-code-3` | Plătit | Optimizat pentru cod | | Cohere | `embed-english-v3.0` | Perioadă de probă gratuită | Scop general | | OpenRouter | Orice model | Variabil | Proxy multi-model | ---

54 de instrumente, 6 resurse, 3 prompturi și 17 skill-uri. > **Shim MCP vs server complet:** pachetul publicat `@agentmemory/mcp` este un shim minimal. Expune suprafața completă de 54 de instrumente **doar atunci când poate accesa un server agentmemory în funcțiune**, prin `AGENTMEMORY_URL` (mod proxy). Când niciun server nu este accesibil, shim-ul trece la un set local de 7 instrumente (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Variabila de mediu `AGENTMEMORY_TOOLS=core|all` este un flag *pe partea de server*; setarea ei în blocul `env` al shim-ului nu are niciun efect. Dacă vezi doar 7 instrumente în Cursor / OpenCode / Gemini CLI, pornește `npx -y @agentmemory/agentmemory@latest` (sau stiva Docker) și setează `AGENTMEMORY_URL=http://localhost:3111`. ### 54 de instrumente Trei suprafețe de instrumente, de la cea mai mică la cea mai mare: `AGENTMEMORY_TOOLS=core` reduce vizibilitatea la 8 instrumente esențiale (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); setul de bază de mai jos reprezintă cele 14 instrumente fundamentale ale registrului; implicit (`AGENTMEMORY_TOOLS=all`) sunt expuse toate cele 54.

Instrumente de bază (14)

| Instrument | Descriere | |------|-------------| | `memory_recall` | Caută observații anterioare | | `memory_compress_file` | Comprimă fișiere markdown, păstrând structura | | `memory_save` | Salvează o observație (insight), o decizie sau un model | | `memory_file_history` | Observații anterioare despre fișiere specifice | | `memory_patterns` | Detectează modele recurente | | `memory_sessions` | Listează sesiunile recente | | `memory_smart_search` | Căutare hibridă, semantică + cuvinte cheie | | `memory_vision_search` | Caută observații pe bază de imagine | | `memory_timeline` | Observații în ordine cronologică | | `memory_profile` | Profilul proiectului (concepte, fișiere, modele) | | `memory_export` | Exportă toate datele de memorie | | `memory_relations` | Interoghează graful de relații | | `memory_commit_lookup` | Sesiunile din spatele unui commit git | | `memory_commits` | Commit-urile înregistrate pentru o sesiune |

Instrumente extinse (54 în total, suprafața implicită)

| Instrument | Descriere | |------|-------------| | `memory_patterns` | Detectează modele recurente | | `memory_timeline` | Observații în ordine cronologică | | `memory_relations` | Interoghează graful de relații | | `memory_graph_query` | Traversarea grafului de cunoștințe | | `memory_consolidate` | Rulează consolidarea pe 4 niveluri | | `memory_claude_bridge_sync` | Sincronizare cu MEMORY.md | | `memory_team_share` | Partajează cu membrii echipei | | `memory_team_feed` | Elementele partajate recent | | `memory_audit` | Traseul de audit al operațiilor | | `memory_governance_delete` | Șterge, cu traseu de audit | | `memory_snapshot_create` | Instantaneu versionat în Git | | `memory_action_create` | Creează elemente de lucru cu dependențe | | `memory_action_update` | Actualizează starea unei acțiuni | | `memory_frontier` | Acțiuni nedeblocate, clasate după prioritate | | `memory_next` | Următoarea acțiune, cea mai importantă | | `memory_lease` | Lease-uri exclusive de acțiune (multi-agent) | | `memory_routine_run` | Instanțiază rutine de flux de lucru | | `memory_signal_send` | Mesagerie între agenți | | `memory_signal_read` | Citește mesaje, cu confirmări de primire | | `memory_checkpoint` | Porți de condiții externe | | `memory_mesh_sync` | Sincronizare P2P între instanțe | | `memory_sentinel_create` | Observatori declanșați de evenimente | | `memory_sentinel_trigger` | Declanșează sentinelele din exterior | | `memory_sketch_create` | Grafuri de acțiuni efemere | | `memory_sketch_promote` | Promovează la permanent | | `memory_crystallize` | Compactează lanțuri de acțiuni | | `memory_diagnose` | Verificări de sănătate | | `memory_heal` | Remediază automat o stare blocată | | `memory_facet_tag` | Etichete dimensiune:valoare | | `memory_facet_query` | Interoghează după etichete de fațetă | | `memory_verify` | Urmărește proveniența |

### 6 resurse · 3 prompturi · 17 skill-uri | Tip | Nume | Descriere | |------|------|-------------| | Resursă | `agentmemory://status` | Stare de sănătate, numărul de sesiuni, numărul de memorii | | Resursă | `agentmemory://project/{name}/profile` | Informații specifice proiectului | | Resursă | `agentmemory://project/{name}/recent` | Observații recente pentru un proiect | | Resursă | `agentmemory://memories/latest` | Ultimele 10 memorii active | | Resursă | `agentmemory://graph/stats` | Statisticile grafului de cunoștințe | | Resursă | `agentmemory://team/{id}/profile` | Profilul partajat al echipei | | Prompt | `recall_context` | Caută și returnează mesaje de context | | Prompt | `session_handoff` | Date de predare (handoff) între agenți | | Prompt | `detect_patterns` | Analizează modele recurente | | Skill | `/recall` | Caută în memorie | | Skill | `/remember` | Salvează în memoria pe termen lung | | Skill | `/session-history` | Rezumate ale sesiunilor recente | | Skill | `/forget` | Șterge observații/sesiuni | Tabelul arată cele patru skill-uri de bază. Setul complet este de 9 skill-uri invocabile, plus 8 skill-uri de referință; vezi secțiunea Skill-uri native de mai sus. ### MCP independent Rulează fără serverul complet, pentru orice client MCP. Funcționează orice dintre acestea: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` Sau adaugă în configurația MCP a agentului tău: Majoritatea agenților (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` Îmbină intrarea `agentmemory` în obiectul `mcpServers` existent al host-ului tău, în loc să înlocuiești fișierul. Pentru clienții sandbox-izați care nu pot accesa `localhost`-ul host-ului, adaugă `"AGENTMEMORY_FORCE_PROXY": "1"` în blocul env și setează `AGENTMEMORY_URL` la o rută pe care sandbox-ul o poate accesa. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` Copiază fișierul plugin-ului din repository: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

Pornește automat pe portul `3113`. Vizualizatorul încarcă un instantaneu (snapshot) la conectare (`GET /agentmemory/viewer/snapshot`) și apoi aplică evenimentele din stream-ul live: memorii noi, lecții, observații, intrări de audit, modificări ale grafului și actualizări de stare apar fără polling sau reîncărcarea paginii. Singurele alte cereri sunt acțiunile pe care le apeși, paginile de tip „încarcă mai multe” și căutările. Când stream-ul se întrerupe, vizualizatorul arată cât de vechi sunt datele, se reconectează cu backoff și se resincronizează dintr-un instantaneu. - **12 tab-uri în patru grupuri**, cu numărători live, deep link-uri (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), scurtături de tastatură și un meniu mobil. - **Memories:** căutare pe server, filtre după proiect, agent și tip, un panou de detalii cu lanțul de versiuni și un diff pe cuvinte, link-uri de proveniență, butoane de copiere pentru id, apelul MCP și o comandă curl, editare (o versiune nouă), ștergere (forget) cu confirmare, ștergere în masă și export JSON. - **Sessions:** o linie temporală de observații inline, cu input și output lizibile ale instrumentelor, filtre și paginare, plus memoriile și lecțiile produse de fiecare sesiune. - **Graph:** căutare, detalii de nod cu relații și surse, o legendă care nu se bazează doar pe culoare și controale de zoom. - **Health:** versiunea live a `GET /agentmemory/status`. Fiecare problemă vine cu remedierea ei, plus backend-ul de stare, starea de salvare a indexului, progresul compactării provenienței grafului și o explicație a consolidării, cu pragurile reale. - Paginile **Audit, Activity, Profile, Replay, Lessons, Actions și Crystals**, fiecare cu o stare goală care spune ce reprezintă secțiunea, de ce este goală și comanda care o populează, plus un tooltip de glosar `?` pentru fiecare termen și număr. ```bash open http://localhost:3113 ``` Serverul vizualizatorului se leagă implicit la `127.0.0.1` și atașează secretul serverului atunci când transmite cererile către API-ul REST, așa că nu necesită nicio configurare. Endpoint-ul `/agentmemory/viewer`, servit prin REST, respectă regulile normale de bearer-token și redirecționează browserele fără token către portul vizualizatorului. Header-ele CSP folosesc un nonce de script per răspuns și dezactivează atributele de handler inline (`script-src-attr 'none'`). ---

Vizualizatorul de pe `:3113` arată ce **și-a amintit** agentul tău. [Consola iii](https://iii.dev/docs/console) arată ce **a făcut** agentul tău: fiecare operație de memorie, ca trasare OpenTelemetry, fiecare intrare KV editabilă, fiecare funcție invocabilă, fiecare stream accesibil (tappable). Două ferestre către aceeași memorie: una modelată ca produs, una modelată ca motor. Urmărește un `memory_smart_search` declanșându-se și vezi scanarea BM25 → căutarea embedding-ului → fuziunea RRF → reranker-ul, ca o cascadă (waterfall). Editează un timer de consolidare blocat, în browser-ul de KV. Reluează un hook `PostToolUse` cu un payload ajustat. Fixează (pin) stream-ul WebSocket și urmărește observațiile ajungând în timp real. agentmemory oferă toate acestea gratuit, pentru că fiecare apel de funcție și fiecare trigger trece prin iii; nimic personalizat, nimic de instrumentat.

Pagina Workers: fiecare worker conectat, inclusiv agentmemory însuși, cu PID, numărul de funcții, runtime și ultima activitate (last-seen).

**Deja instalată.** Consola vine odată cu motorul `iii` fixat (0.22+); nu este nimic separat de instalat. Prima pornire descarcă binarul consolei alături de motor. **Pornește-o alături de agentmemory:** ```bash agentmemory console ``` Aceasta rulează `iii console` din motorul fixat, pe porturile rezolvate de agentmemory (REST, stream-uri, bridge), și o servește pe un port deasupra vizualizatorului, implicit `http://localhost:3114`. `--console-port N` alege un alt port; `--port` și `--instance` selectează instanța agentmemory, la fel cum fac pentru `stop`; orice alt flag este transmis mai departe, de exemplu `--enable-flow` pentru pagina experimentală de graf al arhitecturii. Același lucru, manual, util când `agentmemory` nu este în PATH: ```bash ~/.agentmemory/bin/iii console --port 3114 \ --engine-port 3111 \ --ws-port 3112 \ --bridge-port 49134 ``` **Ce poți face din consolă:** | Pagină | Folosește-o pentru | |------|-----------| | **Workers** | A vedea fiecare worker conectat și metricile sale live, inclusiv worker-ul agentmemory însuși. | | **Functions** | A invoca direct orice funcție a agentmemory, cu un payload JSON; util pentru a testa `memory.recall`, `memory.consolidate`, `graph.query`, fără a conecta un client. | | **Triggers** | A relua trigger-e HTTP, cron, de evenimente și de stare: a declanșa manual cron-ul de consolidare, a reîncerca o rută HTTP, a emite o schimbare de stare. | | **States** | Un browser KV cu CRUD complet pentru sesiuni, sloturi de memorie, timere de ciclu de viață și indexul de embeddings; editează valorile direct. | | **Streams** | Un monitor WebSocket live pentru scrierile de memorie, evenimentele de hook și actualizările de observații, pe măsură ce trec prin stream-urile iii. | | **Queues** | Topicuri de coadă durabile + gestionarea dead-letter. Reia sau elimină job-urile de embedding / compresie care au eșuat. | | **Traces** | Vizualizări OpenTelemetry de tip waterfall / flame / defalcare pe servicii. Filtrează după `trace_id`, pentru a vedea exact ce funcții, apeluri DB și cereri de embedding a produs o singură `memory.search`. | | **Logs** | Log-uri OTEL structurate, filtrate și corelate cu ID-urile de trace/span. | | **Config** | Configurația runtime: vezi exact cu ce worker-i, furnizori și porturi rulează motorul tău. | | **Flow** | (Opțional, `--enable-flow`) Graf interactiv de arhitectură, cu fiecare worker, trigger și stream. |

Traces: waterfall / flame / defalcare pe servicii, pentru fiecare operație de memorie.

**Trasarea este deja activă:** `iii-config.yaml` vine cu worker-ul `iii-observability` activat (`exporter: memory`, `sampling_ratio: 0.1`, metrici + log-uri). Nu este nevoie de nicio configurare suplimentară; în momentul în care agentmemory pornește, fiecare operație de memorie emite un log structurat pe care consola îl poate citi, iar una din zece (`sampling_ratio: 0.1`) emite și un span de trace. Dacă vrei să exporți către Jaeger/Honeycomb/Grafana Tempo, în schimb, schimbă `exporter: memory` în `exporter: otlp` și setează endpoint-ul colectorului conform documentației de observabilitate a iii. > **Atenție:** consola în sine nu impune autentificare; păstreaz-o legată la `127.0.0.1` (valoarea implicită) și nu o expune niciodată public. ---

agentmemory este **deja o instanță [iii](https://iii.dev) în funcțiune**. Trei primitive (worker, funcție, trigger) compun runtime-ul; starea KV, stream-urile și trasele OTEL vin de la worker-ii iii-state, iii-stream și iii-observability, incluși în iii. Nu ai instalat Postgres, Redis, Express, pm2 sau Prometheus, pentru că iii le înlocuiește. Asta înseamnă că o singură comandă suplimentară extinde agentmemory cu o capabilitate complet nouă. ### Extinde agentmemory cu mai mulți worker-i Componentele încorporate (builtins) de care are nevoie agentmemory sunt deja în `iii-config.yaml` și pornesc odată cu el: `iii-state` (KV), `iii-queue` (reîncercări durabile pentru abonații la evenimente), `iii-pubsub`, `iii-cron`, `iii-stream` și `iii-observability` (trase OTEL, metrici și log-uri pentru fiecare funcție). Orice altceva din [registrul de worker-i iii](https://workers.iii.dev) se conectează la același motor: copiază `iii-config.yaml` în `~/.agentmemory/iii-config.yaml` (CLI-ul preferă acel fișier în locul celui inclus și îi randează în continuare porturile și căile de date), adaugă intrarea, instalează runtime-ul worker-ului o singură dată, cu `~/.agentmemory/bin/iii update worker`, și repornește 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 | Ce obții, în plus față de agentmemory | |---|---| | [`database`](https://workers.iii.dev/workers/database) | Adaptor de stare pe bază de SQL, pentru când crești peste valorile implicite ale KV-ului în memorie | | [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Codul rezultat din `memory_recall` rulează într-un VM de unică folosință, nu în shell-ul tău | | [`mcp`](https://workers.iii.dev/workers/mcp) | Pornește servere MCP suplimentare, alături de cel al agentmemory, pe același motor | Pe motorul 0.22.x, păstrează numele cu prefixul `iii-` pentru componentele încorporate de mai sus; intrările fără prefix `http`, `state`, `queue`, `pubsub` și `cron` sunt worker-ii independenți din registru, către care agentmemory trece odată cu migrarea la 0.23. Registrul complet: [workers.iii.dev](https://workers.iii.dev). Fiecare worker de acolo se compune prin aceleași primitive pe care le folosește agentmemory, iar agentmemory-ul pe care îl ai deja este unul dintre ei. ### Configurația motorului și adresa de bind `agentmemory start` citește configurația motorului din primul fișier care există: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` în directorul curent, `~/.agentmemory/iii-config.yaml`, apoi `iii-config.yaml`-ul inclus. La fiecare pornire, randează acel fișier (căi de date, porturi, backend de stare) în `~/.agentmemory/data/iii-config.runtime.yaml` și pornește motorul cu copia randată, așa că editează fișierul sursă, nu pe cel randat. Valorile `host:` din fișierul sursă sunt păstrate așa cum sunt scrise. `iii-config.yaml`-ul inclus se leagă intenționat la `127.0.0.1`, și această valoare implicită se aplică și în interiorul unui container. Un CLI pornit într-un container ascultă pe loopback-ul containerului, astfel încât porturile publicate nu ajung nicăieri. Pentru a servi un CLI containerizat prin porturi publicate, setează `AGENTMEMORY_III_CONFIG` la o configurație care se leagă la `0.0.0.0`. `iii-config.docker.yaml`-ul inclus în pachet este una dintre acestea: leagă `iii-http`, `iii-stream` și portul motorului la `0.0.0.0` și stochează starea sub `/data`, așa că montează acolo un volum scriibil. Păstrează `AGENTMEMORY_SECRET` setat și publică doar porturile de care ai nevoie, pe `127.0.0.1` sau în spatele unui proxy în care ai încredere. `docker-compose.yml`-ul acestui repository nu trece prin căutarea de configurație a CLI-ului: montează `iii-config.docker.yaml` la `/app/config.yaml`, iar containerul `iii-engine` pornește cu `--config /app/config.yaml`. [Șabloanele de implementare](../deploy/) cu un singur clic își scriu propria configurație `0.0.0.0` în entrypoint-urile lor. ### Backend de stocare: file (implicit) vs redis `iii-state` și `iii-stream` folosesc implicit magazinul KV bazat pe fișiere, inclus în iii-engine: un fișier JSON per scope, ținut în memoria procesului motorului și rescris pe disc la un interval. Aceasta este valoarea implicită potrivită pentru o instalare locală cu un singur utilizator; un daemon partajat cu mai mulți scriitori concurenți obține, în schimb, scrieri reale per cheie, de la Redis, cu costul unui round-trip de rețea per operație (fiecare apel `state::*` se serializează tot pe o singură conexiune Redis, așa că aceasta schimbă lock-ul magazinului de fișiere cu un socket, nu cu paralelism). Setează `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) pentru a comuta ambii worker-i la adaptorul `redis` încorporat în iii-engine, care stochează fiecare cheie ca un câmp de hash Redis (`HSET`), în loc să rescrie un scope întreg la fiecare scriere: ```env # ~/.agentmemory/.env AGENTMEMORY_STATE_BACKEND=redis AGENTMEMORY_REDIS_URL=redis://localhost:6379 ``` `AGENTMEMORY_STATE_BACKEND` are implicit valoarea `file`; lăsat nesetat, comportamentul de astăzi rămâne neschimbat, iar o valoare nerecunoscută (orice altceva decât `file` sau `redis`) este o eroare de pornire, nu o trecere silențioasă la o valoare de rezervă. `/agentmemory/status` și pagina Health a vizualizatorului (rândul State store) raportează care backend este activ și dacă răspunde, niciodată URL-ul. **Doar `redis://` simplu.** Motorul fixat (0.22.1) își construiește clientul Redis fără suport TLS, așa că un URL `rediss://` (majoritatea ofertelor Redis administrate, precum Upstash, Redis Cloud și ElastiCache cu criptare în tranzit, sunt implicit doar-TLS) nu se poate conecta. Conexiunea este necriptată, așa că parola Redis și fiecare memorie stocată circulă pe fir în text clar: direcționează-te către un Redis local sau unul dintr-o rețea privată în care ai încredere. Pentru orice alt Redis, rulează un tunel criptat (stunnel, SSH sau un VPN) pe host-ul agentmemory, astfel încât saltul `redis://` simplu rămâne pe acel host, iar conexiunea din amonte a tunelului este criptată și autentificată. Dacă o parolă Redis conține un apostrof, codifică-l percent (`%27`); motorul expandează URL-ul în configurația YAML, înainte de a-l analiza (parse). **Un server Redis per `--instance`.** Prefixele de chei Redis ale motorului (`state:`, `stream::`) sunt fixe, așa că două instanțe agentmemory (`--instance 1`, `--instance 2`, ...) direcționate către aceeași bază de date își suprascriu reciproc datele. Un index de bază de date separat (`redis://localhost:6379/1`) ține datele stocate separate, dar motorul retransmite evenimentele live ale vizualizatorului pe un singur canal Redis pub/sub (`stream::events`), iar Redis pub/sub ignoră indexul bazei de date, așa că vizualizatorul fiecărei instanțe ar arăta totuși evenimentele live ale celeilalte. Dă fiecărei instanțe propriul server Redis (sau port), atunci când rulezi mai multe. **Ce rămâne la fel și ce diferă.** Fiecare funcționalitate a agentmemory funcționează pe Redis: sesiuni, observații, memorii (remember, supersede, evolve, forget), căutarea și loturile indexului, lecții, graful, log-ul de audit și scope-urile sale lunare, export și import, ștergerile de guvernanță, starea consolidării, instantaneul vizualizatorului și stream-ul său live, și monitorul de sănătate. Motorul stochează fiecare scope ca un singur hash Redis (`HSET`/`HGET`/`HGETALL`) și declanșează aceleași trigger-e de stare ca magazinul de fișiere. Trei diferențe ale motorului sunt gestionate în interiorul agentmemory: - Redis returnează înregistrările unui scope într-o ordine nefixată. agentmemory le sortează de la cele mai vechi (după timpul de creare din id-ul înregistrării, apoi după timestamp-ul ei), astfel încât listele, paginarea și fragmentele de export vin înapoi în aceeași ordine ca pe magazinul de fișiere. - Motorul aplică actualizările parțiale pe Redis într-un script Lua care transformă array-urile vide în obiecte vide. agentmemory aplică el însuși aceste actualizări (citire, modificare, scriere, sub un lock per cheie) pe Redis, astfel încât câmpuri precum `tags: []` rămân array-uri. - Verificarea veche a log-ului de audit citește scope-ul vechi din Redis, în loc să caute fișierul de pe disc al magazinului de fișiere. O diferență are nevoie de tine: **după ce Redis repornește, motorul oprește retransmiterea evenimentelor live** către vizualizator, până când agentmemory repornește. Datele sunt totuși salvate și citite normal. Monitorul de sănătate trimite un eveniment de test prin Redis la fiecare 30 de secunde; când acesta nu se întoarce, `/agentmemory/status` și pagina Health a vizualizatorului arată „Actualizările live nu ajung la vizualizator”, cu remedierea: repornește agentmemory. Dacă Redis este căzut, raportul de stare arată „Magazinul de stare nu răspunde” și cum să verifici asta (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listarea unui scope foarte mare citește întregul hash într-un singur `HGETALL`, același cost ca atunci când magazinul de fișiere îl ține în memorie. **Setări Redis recomandate.** Politica implicită de instantanee `save 3600 1 300 100 60 10000` poate pierde minute de scrieri la un crash, mai rău decât fereastra de 5 secunde de flush a magazinului de fișiere. Setează `appendonly yes` pentru orice ți-ar părea rău să pierzi. Setează `maxmemory-policy noeviction`; `allkeys-lru` sau similare elimină silențios memorii, de îndată ce Redis atinge limita sa de memorie. O pornire nativă (non-Docker) și fiecare [șablon de implementare](../deploy/) cu un singur clic (acestea suprascriu `iii-config.yaml`-ul inclus și pornesc nativ) citesc `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` și le randează în `iii-config`-ul lansat. URL-ul în sine nu este niciodată scris în acel fișier randat, doar o referință `${AGENTMEMORY_REDIS_URL}`, pe care procesul motorului o expandează din propriul mediu, la pornire. Doar calea Docker Compose a acestui repository (`AGENTMEMORY_USE_DOCKER=1`, sau reluarea unui motor pornit deja în acest fel) montează `iii-config.docker.yaml` doar-pentru-citire și nu randează niciodată; `agentmemory start` avertizează când detectează această combinație. Schimbă acel fișier manual, urmând aceeași formă `name: redis` / `config: redis_url: ...` arătată în documentația worker-ilor [iii-state](https://workers.iii.dev/workers/iii-state) și [iii-stream](https://workers.iii.dev/workers/iii-stream), și direcționează `redis_url` către un Redis accesibil din container. `docker-compose.yml` transmite `AGENTMEMORY_REDIS_URL` în containerul motorului, așa că `redis_url: '${AGENTMEMORY_REDIS_URL}'` funcționează acolo și ține URL-ul în afara fișierului montat. Configurația randată ține URL-ul în afara `~/.agentmemory/data/iii-config.runtime.yaml`, dar worker-ul propriu de configurare al motorului persistă totuși valoarea *expandată* în `~/.agentmemory/config/iii-state.yaml` și `iii-stream.yaml`, odată ce pornește (expandarea `${VAR}` a iii-engine se întâmplă înainte ca acel worker să își stocheze seed-ul, iar el stochează valoarea rezolvată, nu referința). Tratează acel director ca ținând o credențială: `chmod 700 ~/.agentmemory` pe orice host partajat și preferă un utilizator ACL Redis cu scope limitat la ce are nevoie agentmemory, în locul credențialelor de administrator ale bazei de date. **Migrarea nu este automată.** Comutarea `AGENTMEMORY_STATE_BACKEND` începe de la un magazin gol pe fiecare parte; nimic nu copiază datele existente din file în Redis sau invers. Exportă din backend-ul pe care îl lași și importă în cel către care te muți. Acest lucru rulează identic sub bash și zsh (inclusiv `bash -u`). Un array precum `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` nu rulează identic: zsh păstrează header-ul ca un singur cuvânt malformat, unde bash îl împarte în două, așa că ambele cereri primesc 401, de câte ori `AGENTMEMORY_SECRET` este setat: ```bash # 0. Use the generated secret when none is exported: AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}" # 1. On the old backend, while agentmemory is still running on it: if [ -n "${AGENTMEMORY_SECRET:-}" ]; then curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json else curl -fsS http://localhost:3111/agentmemory/export > backup.json fi # 2. Confirm backup.json is a usable export before switching backends: jq -e '.version and .exportedAt' backup.json > /dev/null || { echo "backup.json is not a valid export; do not switch backends" >&2 exit 1 } # 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed), # restart agentmemory against the new backend, then: if [ -n "${AGENTMEMORY_SECRET:-}" ]; then jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \ -H 'Content-Type: application/json' -d @- else jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \ curl -fsS -X POST http://localhost:3111/agentmemory/import \ -H 'Content-Type: application/json' -d @- fi ``` `/agentmemory/export` acceptă și `?maxSessions=` și `?offset=`, pentru a fragmenta un corpus mare pe mai multe apeluri; `strategy` la import este `merge` (sigur implicit), `replace` sau `skip`. ### Ce înlocuiește iii | Stivă tradițională | agentmemory folosește | |---|---| | Express.js / Fastify | Trigger-e HTTP iii | | SQLite / Postgres + pgvector | Stare KV iii + index vectorial în memorie | | SSE / Socket.io | Stream-uri iii (WebSocket) | | pm2 / systemd | Supervizarea worker-ilor de către motorul iii | | Prometheus / Grafana | iii OTEL + monitor de sănătate | | Sisteme de plugin-uri personalizate | `iii worker add ` | **219 fișiere sursă · ~52,000 LOC · 2,500+ teste · 311 funcții · 60 domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii. ---

### Furnizori LLM agentmemory detectează automat furnizorii din mediul tău. Un furnizor face disponibile operațiile susținute de LLM, dar configurarea furnizorului, de una singură, nu activează compresia observațiilor scrisă de LLM. Acea cale necesită atât un furnizor, cât și `AGENTMEMORY_AUTO_COMPRESS=true`. | Furnizor | Configurare | Note | |----------|--------|-------| | **No-op (implicit)** | Nu necesită configurare | Compresia/rezumarea susținută de LLM este dezactivată. Compresia sintetică și reamintirea prin BM25 funcționează în continuare. Vezi `AGENTMEMORY_ALLOW_AGENT_SDK` mai jos, dacă te bazai anterior pe fallback-ul prin abonamentul Claude. | | API Anthropic | `ANTHROPIC_API_KEY` | Facturare per token | | MiniMax | `MINIMAX_API_KEY` | Compatibil Anthropic | | Gemini | `GEMINI_API_KEY` | Activează și embeddings | | OpenRouter | `OPENROUTER_API_KEY` | Orice model | | API OpenAI | `OPENAI_API_KEY` | Implicit `gpt-5.6-luna`, suprascrie cu `OPENAI_MODEL` | | **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) sau `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Orice e compatibil cu API-ul OpenAI. Cost zero, rulează pe hardware-ul tău. Vezi [Modele locale](#local-models-ollama--lm-studio--vllm) mai jos. | | Fallback prin abonamentul Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Doar opt-in. Lansează sesiuni `@anthropic-ai/claude-agent-sdk`; obișnuia să cauzeze o recursivitate nelimitată a hook-ului Stop, așa că nu mai este implicit. | ### Modele locale (Ollama / LM Studio / vLLM) agentmemory comunică cu orice server compatibil cu API-ul OpenAI, așa că orice expune `/v1/chat/completions` funcționează fără modificări de cod. Fără chei plătite, fără cloud, fără limite de rată (rate limits); rulează integral pe hardware-ul tău. **Ollama** (port implicit `11434`): ```bash ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc. ollama serve ``` ```env # ~/.agentmemory/.env OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=qwen3:8b ``` **LM Studio** (port implicit `1234`): Deschide LM Studio → tab-ul Local Server → Start Server. Alege orice model de chat din selector (Qwen 3, gpt-oss, DeepSeek R1 etc.). ```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**: aceeași formă. Direcționează `OPENAI_BASE_URL` către orice URL expune serverul tău și setează `OPENAI_MODEL` la un nume pe care serverul tău îl va accepta. **Alegeri de model pentru munca de memorie**: compresia și rezumarea sunt sarcini scurte (<2K tokeni la intrare, <500 tokeni la ieșire), unde un model instruct de 7B este suficient. Recomandări: | Model | Dimensiune | De ce | |-------|------|-----| | `qwen3:8b` | ~5.2 GB | Opțiune implicită echilibrată pe o mașină cu 16 GB; puternic la extracție și text în formă de instrument | | `qwen3:4b` | ~2.6 GB | Cea mai mică opțiune rezonabilă; bun pentru compresie, mai slab la extracția de graf | | `qwen3-coder:30b` | ~19 GB | Cea mai bună alegere locală pentru sesiuni centrate pe cod (30B MoE, 3.3B active) pe hardware de 24-32 GB | | `gpt-oss:20b` | ~14 GB | Model general puternic, care se încadrează în 16 GB RAM | | `deepseek-r1:8b` | ~5.2 GB | Distilare de raționament; mai lent, dar cu extracții mai clare | Modelele Qwen 3 „gândesc” implicit și pot consuma întregul buget de tokeni pe raționament, înainte de orice output. Setează `AGENTMEMORY_LLM_NOTHINK=1` pentru a adăuga `/no_think` la prompturile de extracție din graf și crește `MAX_TOKENS` (16384 funcționează), dacă extracțiile se întorc vide. Modelele din clasa de raționament (în stil `o1`, cu blocuri ``) pot returna un `content` vid, cu un câmp `reasoning` pe care serverul tău local poate să nu îl expună. Dacă extracțiile se întorc vide, treci întâi la un model fără raționament. Variabila de mediu `OPENAI_REASONING_EFFORT=none` poate, de asemenea, să dezactiveze „gândirea” pe modelele de tip thinking din Ollama Cloud, care oglindesc schema de raționament a OpenAI. Embeddings locale vin ca o dependență opțională, dar nu sunt activate implicit. Setează `EMBEDDING_PROVIDER=local` pentru a opta pentru `Xenova/all-MiniLM-L6-v2` (384 dimensiuni). Prima cerere de embedding descarcă modelul; inferența este pe dispozitiv după aceea. Fără această setare sau o cheie de embedding la distanță, vectorii rămân dezactivați, `mem::search` folosește BM25, iar `smart-search` poate adăuga în continuare potriviri existente din graf. ### Selecția modelului în funcție de cost Când compresia în fundal, scrisă de LLM, este activată, cu atât un furnizor, cât și `AGENTMEMORY_AUTO_COMPRESS=true`, aceasta rulează la fiecare observație, așa că alegerea modelului schimbă semnificativ cheltuiala lunară. Date de workload capturate: 635 de cereri / 888K tokeni / 35 de ore de utilizare activă, rulate pe trei modele OpenRouter, la prețurile din 2026-05-23. | Nivel | Model | Input / 1M | Output / 1M | Cost pentru cele 35h capturate | Note | |------|-------|------------|-------------|---------------------------|-------| | Recomandat | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Cel mai recent DeepSeek; cea mai ieftină alegere recomandată pentru workload-uri de compresie. | | Recomandat | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Calitate solidă de compresie + rezumare, la un cost de ~10× mai mic decât Sonnet. | | Recomandat | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Raționament puternic pe cod, dacă sesiunile tale sunt puternic centrate pe cod. | | Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Același preț de listă ca rularea măsurată Sonnet 4.6; preț introductiv de $2/$10 până la 2026-08-31. | | Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Nivel de top (flagship); costisitor pentru muncă de fundal permanent activă. | | Evită | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Model din clasa de top (flagship); cheltuială excesivă pentru compresie. | Rândurile măsurate provin din rularea capturată; rândurile (est.) scalează același mix de tokeni după prețul de listă al fiecărui model. agentmemory afișează un avertisment la runtime, când `OPENROUTER_MODEL` se potrivește cu un model de nivel premium. Setează `AGENTMEMORY_SUPPRESS_COST_WARNING=1` pentru a-l dezactiva, odată ce ai făcut o alegere informată. Compromisul calitate vs cost pentru munca de memorie: compresia este o sarcină de rezumare, cu bare de calitate relativ permisive (agentul re-citește rezumatul, nu utilizatorul). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ajung, pe această sarcină, la o diferență neglijabilă față de Sonnet, costând totodată de 10-70× mai puțin. Păstrează modelele de nivel premium pentru interogările pe care le citești direct. Surse: [Prețurile OpenRouter pentru Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [Notele de preț DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/). ### Memorie multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) În configurațiile multi-agent, unde mai multe roluri partajează un singur server agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` etichetează fiecare scriere cu rolul care a făcut-o. `AGENTMEMORY_AGENT_SCOPE` controlează dacă reamintirea filtrează după acea etichetă. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` Două moduri: | Mod | Etichetează scrierile | Filtrează reamintirea | Când să-l folosești | |------|------------|---------------|--------------| | `shared` (implicit) | da | nu | Context între agenți, cu traseu de audit. Architect poate vedea ce a notat developer, dar fiecare rând înregistrează cine a spus-o. | | `isolated` | da | da | Separare strictă. Architect nu vede niciodată observațiile / memoriile / sesiunile lui developer. | Ce se etichetează, când `AGENT_ID` este setat: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rolul circulă de la `api::session::start` → `mem::observe` → `mem::compress` → KV. Ce se filtrează în modul isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Fiecare endpoint acceptă `?agentId=`, pentru a suprascrie per cerere, și `?agentId=*`, pentru a renunța complet la scope-ul din mediu. `/memories` acceptă și `?includeOrphans=true`, pentru a scoate la suprafață memoriile dinainte de AGENT_ID, al căror `agentId` este nedefinit. Suprascriere per apel, la nivelul SDK / REST: fiecare endpoint care modifică date (`/session/start`, `/remember`) acceptă un câmp `agentId` în corpul cererii, care are prioritate față de mediu. Util pentru runtime-uri care direcționează multe roluri printr-un singur proces de server. Instrumentul MCP `memory_save` expune același câmp `agentId`, serverul stdio independent transmite atât `agentId`, cât și `project`, iar memoriile salvate duc `agentId` în indexul de căutare, astfel încât căutarea scopată pe agent acoperă atât memoriile, cât și observațiile. Când `AGENT_ID` nu este setat, memoria rămâne fără scope (comportament legacy, fără etichete, fără filtre). ### Porturi agentmemory + iii-engine se leagă implicit la patru porturi. Dacă o repornire eșuează cu `port in use`, acest tabel îți spune ce proces să cauți. | Port | Proces | Scop | Suprascriere prin variabilă de mediu | |------|---------|---------|--------------| | `3111` | agentmemory | API REST + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` | | `3112` | iii-engine | Worker intern de stream-uri (consumat de agentmemory + vizualizator) | `III_STREAM_PORT` (preferat) sau `III_STREAMS_PORT` (vechi/legacy) | | `3113` | agentmemory | Vizualizator în timp real (`http://localhost:3113`) | `III_VIEWER_PORT` sau `AGENTMEMORY_VIEWER_URL` pentru URL-ul raportat | | `49134` | iii-engine | WebSocket; worker-ii se înregistrează aici, telemetria OTel circulă prin el | `III_ENGINE_PORT` sau `III_ENGINE_URL` | `--port ` schimbă ancora REST și derivă stream-urile `N+1`, vizualizatorul `N+2` și WebSocket-ul motorului `N+46023`, doar unde portul sau URL-ul explicit corespunzător de mai sus nu este setat. Nu creează un namespace de ciclu de viață izolat. Folosește `--instance 1` pentru un al doilea daemon; acesta folosește ancora 3211, implicit `3211/3212/3213/49234`, și primește un director separat de date și ciclu de viață, `instance-1`. Instanțele 1 până la 50 urmează același model. Motorul fixat pornește cu `--no-update-check` (fără verificări de actualizare sau de avertismente de securitate față de GitHub, la pornire) și cu telemetria anonimă de utilizare a iii dezactivată: agentmemory setează `III_TELEMETRY_ENABLED=false` pentru motorul pe care îl lansează, cu excepția cazului în care exporți tu însuți variabila, iar fișierul compose inclus face același lucru. Curățarea proceselor rămase, când porturile rămân legate după o rulare care s-a prăbușit (crash): ```bash # macOS / Linux — find whatever is on each port and kill it lsof -i :3111,3112,3113,49134 pkill -f agentmemory || true pkill -f 'iii ' || true # Windows netstat -ano | findstr ":3111 :3112 :3113 :49134" taskkill /F /PID ``` `agentmemory stop` încheie curat atât worker-ul, cât și pidfile-ul motorului, la o oprire nativă controlată (graceful). În modul Docker, golește (flush) worker-ul nativ, oprește exact containerul de motor validat și păstrează atât containerul, cât și montarea sa `/data`, pentru o repornire fără pierderi; următoarea pornire validează și reia același container. Dezinstalarea susținută de Docker necesită `agentmemory remove --keep-data`: aceasta elimină fișierele partajate gestionate de agentmemory, păstrând în același timp containerul validat, montarea sa de date și înregistrarea de ciclu de viață necesară pentru a le recupera. Ștergerea distructivă a datelor Docker este lăsată intenționat în sarcina operatorului, după un backup. CLI-ul refuză, de asemenea, să adopte sau să semnaleze deținătorii de porturi Docker sau VM (backend-ul Docker, vpnkit, colima) ca motor nativ, cu excepția cazului în care este transmis `--force`. Curățarea manuală de mai sus este doar pentru cazul post-crash, în care nu rămâne niciun pidfile. ### Fișierul de configurare Pune configurația de runtime a agentmemory în `~/.agentmemory/.env`, în loc să exporți variabile în fiecare shell. Dacă vizualizatorul arată un indiciu de configurare, precum `export ANTHROPIC_API_KEY=...`, copiază-l în acest fișier ca `ANTHROPIC_API_KEY=...`, fără prefixul `export`, apoi repornește agentmemory. Variabilele de mediu ale procesului funcționează în continuare și au prioritate față de valorile din fișier. Pe Windows, același fișier se află la `%USERPROFILE%\.agentmemory\.env`: ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` Pentru a testa cu un abonament Claude Code Pro/Max, în loc de o cheie API, optează explicit: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` Compresia observațiilor scrisă de LLM necesită ambele linii: acces la un furnizor LLM (inclusiv acest fallback explicit prin abonament) și `AGENTMEMORY_AUTO_COMPRESS=true`. Un furnizor, de unul singur, lasă în vigoare calea implicită de compresie sintetică. Consolidarea (noduri de graf, lecții, cristale) este activă implicit, de câte ori este configurat un furnizor LLM. Renunță explicit cu `CONSOLIDATION_ENABLED=false`, dacă vrei o funcționare fără LLM. Extracția din graf este un flag separat: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### Variabile de mediu Creează `~/.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 de endpoint-uri pe portul `3111`. API-ul REST se leagă implicit la `127.0.0.1`. Endpoint-urile protejate necesită `Authorization: Bearer `, iar endpoint-urile de sincronizare mesh necesită un `AGENTMEMORY_SECRET` setat explicit pe ambii parteneri (peers). **Autentificarea este activată implicit.** Când `AGENTMEMORY_SECRET` nu este setat (în shell sau în `~/.agentmemory/.env`), serverul generează un secret aleatoriu la prima pornire și îl stochează în `~/.agentmemory/secret`, cu modul `0600`. Fiecare client inclus îl citește de acolo, când vorbește cu un server local: CLI-ul, vizualizatorul, hook-urile din `plugin/scripts`, serverul MCP și shim-ul `@agentmemory/mcp`, configurațiile scrise de `agentmemory connect`, și integrările incluse OpenCode, Pi, OpenClaw, Hermes și filesystem-watcher. Secretul stocat este trimis doar către URL-uri loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explicit are întotdeauna prioritate, iar clienții la distanță au nevoie, în continuare, să îl aibă setat. Docker și entrypoint-urile din `deploy/` își generează și exportă deja propriul secret. Pentru a apela API-ul manual: ```bash curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health ``` **Regulile de cerere pentru scrieri.** Cererile `POST`, `PUT`, `PATCH` și `DELETE` către API-ul REST și vizualizator trebuie să trimită `Content-Type: application/json` (un parametru `charset` este acceptabil), de câte ori au un corp, și un header `Origin`, atunci când este prezent, trebuie să fie o origine loopback pentru portul REST sau vizualizator configurat, sau să fie listat în `VIEWER_ALLOWED_ORIGINS` (separate prin virgulă, de ex. `https://memory.example.com`). Clienții care nu trimit niciun header `Origin` (CLI, hook-uri, MCP, curl, server-la-server) nu sunt afectați. Vizualizatorul acceptă și propria sa origine. **Căi de fișiere.** Endpoint-urile care citesc sau scriu fișiere (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) acceptă doar căi aflate sub `~/.agentmemory`, directorul de date al instanței, sau un director listat în `AGENTMEMORY_IMPORT_ROOT` (separă mai multe cu `:`, sau `;` pe Windows). `/replay/import-jsonl` acceptă și valoarea sa implicită, `~/.claude/projects`. `/obsidian/export` rămâne în interiorul `AGENTMEMORY_EXPORT_ROOT`, iar `/migrate` în interiorul `~/.agentmemory`. Symlink-urile sunt rezolvate înainte de fiecare verificare. **Eliminarea secretelor.** Cheile API, token-urile bearer, blocurile de chei private PEM și credențialele încorporate în URL-uri (`scheme://user:password@host`) sunt redactate înainte ca textul să fie stocat, pe fiecare cale de scriere: observații, remember, evolve, sloturi, lecții, acțiuni, sketch-uri, semnale, checkpoint-uri, importuri, reluare jsonl, sincronizare mesh, partajări de echipă, output de compresie și rezumat, cristale și noduri de graf.

Endpoint-uri cheie

| Metodă | Cale | Descriere | |--------|------|-------------| | `GET` | `/agentmemory/health` | Verificare de sănătate (mereu publică) | | `GET` | `/agentmemory/status` | Ce nu este în regulă și cum se remediază (HTML pentru browsere, JSON altfel) | | `GET` | `/agentmemory/viewer/snapshot` | Tot ce arată vizualizatorul, într-un singur răspuns | | `POST` | `/agentmemory/session/start` | Pornește sesiunea + obține context | | `POST` | `/agentmemory/session/end` | Termină sesiunea | | `POST` | `/agentmemory/observe` | Captează o observație (vezi livrarea capturii mai jos) | | `GET` | `/agentmemory/capture` | Inbox-ul de captare, dead letters și coada offline (spool) | | `POST` | `/agentmemory/capture/retry` | Reîncearcă captările dead-letter | | `POST` | `/agentmemory/capture/drain` | Trimite acum coada offline locală | | `POST` | `/agentmemory/smart-search` | Căutare hibridă | | `POST` | `/agentmemory/context` | Generează context | | `POST` | `/agentmemory/remember` | Salvează în memoria pe termen lung | | `POST` | `/agentmemory/forget` | Șterge observații | | `POST` | `/agentmemory/enrich` | Context de fișier + memorii + bug-uri | | `GET` | `/agentmemory/profile` | Profilul proiectului | | `GET` | `/agentmemory/export` | Exportă toate datele | | `POST` | `/agentmemory/import` | Importă din JSON | | `POST` | `/agentmemory/graph/query` | Interogarea grafului de cunoștințe | | `POST` | `/agentmemory/graph/compact` | Trimite la o dimensiune mai mică proveniența supradimensionată a grafului | | `POST` | `/agentmemory/team/share` | Partajează cu echipa | | `GET` | `/agentmemory/audit` | Traseul de audit | Lista completă a endpoint-urilor: [`src/triggers/api.ts`](../src/triggers/api.ts)

**Livrarea capturii.** Hook-urile trimit fiecare observație o singură dată către `POST /agentmemory/observe`, cu un `eventId`. Acesta este propriul id al host-ului pentru apel, atunci când payload-ul are unul (de exemplu `tool_use_id` al lui Claude Code), altfel un hash al sesiunii, tipului de hook, numelui instrumentului, input-ului, output-ului și timestamp-ului host-ului. Serverul scrie evenimentul într-un inbox de captare din state store, stochează observația, apoi elimină intrarea din inbox. Codul de stare spune ce s-a întâmplat: | Status | Câmpul `status` | Semnificație | |---|---|---| | `201` | `accepted` | Stocat. `observationId` este noua observație. | | `202` | `accepted` (`state: "retrying"`) | Acceptat, dar stocarea a eșuat. Serverul reîncearcă, inclusiv după o repornire. | | `200` | `duplicate` | Acest `eventId` a fost deja acceptat. `observationId` este observația existentă; nu se stochează nimic nou. | | `400` / `422` | `rejected` | Payload invalid, sau stocarea a eșuat definitiv (evenimentul este păstrat ca dead letter). | | `503` | `rejected` (`retryable: true`) | Inbox-ul este plin (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook-urile pun evenimentul în coadă (spool) și îl trimit mai târziu. | Evenimentele care eșuează sunt reîncercate la fiecare `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s), cu backoff dublat, până la `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Evenimentele care încă eșuează rămân în inbox ca dead letters, sunt listate pe `/agentmemory/status` și pe pagina Health a vizualizatorului, și pot fi reîncercate cu `POST /agentmemory/capture/retry` (`{"eventId": "..."}` sau `{"all": true}`). ID-urile evenimentelor acceptate sunt reținute timp de `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 de ore, cel mult `AGENTMEMORY_CAPTURE_EVENTS_MAX` id-uri), astfel încât un hook reluat după un timeout sau o repornire este stocat o singură dată, în timp ce două apeluri de instrument separate, cu propriile lor id-uri de host, sunt stocate de două ori, chiar dacă conținutul lor este identic. Când o observație este ștearsă (forget, ștergerea sesiunii, eviction, uitare automată sau un import care înlocuiește magazinul), evenimentul ei este marcat ca șters înainte ca observația să fie eliminată, astfel încât o reluare a acelui eveniment în aceeași fereastră este tratată ca un duplicat și nu stochează nimic. State store-ul scrie pe disc la fiecare 2 secunde, așa că un eveniment confirmat poate fi încă doar în memorie, pentru o clipă. Pentru a acoperi acest lucru, fiecare răspuns `2xx` poartă și `bootId`-ul serverului (nou la fiecare pornire), `acceptedAt` și `durableAfterMs` (intervalul de salvare plus 1.5 s pe magazinul de fișiere, 1.5 s pe redis, unde persistența este setarea operatorului). Hook-urile păstrează evenimentul în coada locală (spool), până trece acea fereastră, și îl șterg la un apel ulterior, fără o altă cerere. Dacă `bootId`-ul s-a schimbat până atunci, serverul a repornit, așa că hook-ul trimite din nou evenimentul, cu același `eventId`; un eveniment care a ajuns deja pe disc nu este stocat de două ori. Serverul trimite el însuși astfel de evenimente, la pornire și la fiecare interval de reîncercare, așa că o repornire nu pierde nimic, chiar dacă niciun hook nu mai rulează după aceea. Hook-urile mai vechi ignoră câmpurile suplimentare, iar hook-urile noi, în fața unui server mai vechi, elimină evenimentul la `2xx`, ca înainte. Când serverul este căzut, nu răspunde la timp sau returnează un 5xx, hook-ul adaugă observația într-un fișier local de coadă (spool), `/capture-spool/-.jsonl` (suprascrie directorul cu `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Fișierul este privat pentru utilizatorul tău (mod 600), secretele sunt redactate la fel cum le redactează serverul, ține cel mult `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) și elimină intrările mai vechi de `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Când este plin, intrările noi sunt eliminate și contorizate, iar `/agentmemory/status` raportează asta. Hook-ul tot iese cu 0, în limita sa de timp, și nu adaugă nicio cerere, când serverul este sănătos. Coada este trimisă la următoarea pornire și de către primul hook care ajunge din nou la server, într-un proces de fundal, astfel încât agentul nu așteaptă. ID-urile de eveniment fac acest lucru sigur: o observație care a ajuns deja înainte de un timeout nu este stocată de două ori. `npx @agentmemory/agentmemory capture` arată coada și inbox-ul serverului, `--drain` trimite coada acum, iar `GET /agentmemory/capture` returnează aceleași date, ca JSON. Setează `AGENTMEMORY_CAPTURE_SPOOL=false` pentru a dezactiva coada. **Compactarea provenienței grafului.** Fiecare nod și muchie din graful de cunoștințe ține id-urile celor mai recente 32 de observații din care provine. Magazinele scrise înainte de acel plafon pot ține mii de id-uri per nod „fierbinte” (hot), ceea ce face căutarea în graf și vizualizatorul lente, sau blochează worker-ul. agentmemory remediază asta de la sine: la prima pornire de după actualizare, trimite fiecare nod, muchie, muchie suprascrisă (istoricul temporal al grafului) și instantaneul din cache la plafon, în fundal, în felii mici, cu o pauză între ele, astfel încât căutarea, captarea și vizualizatorul continuă să funcționeze. Își salvează progresul, reia după o repornire și nu mai rulează niciodată, odată terminat. `/agentmemory/status` și pagina Health a vizualizatorului îl arată ca în așteptare (pending), în curs (running) (cu scope-ul și poziția curente), finalizat (done) sau eșuat (failed). Setează `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` pentru a-l dezactiva. Pentru a-l rula manual, apelează `POST /agentmemory/graph/compact`. Acesta traversează indecșii de nume și de chei de muchie, în loc să listeze fiecare nod și muchie, și este sigur de rulat din nou. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}' ``` Pe un magazin mare, sau când apelul returnează 504, rulează-l în felii. Trimite `scope` (`nodes`, `edges` sau `history`), `offset` și `limit`, apoi apelează din nou cu `nextOffset`-ul returnat, până devine `null`. Fă asta pentru `nodes`, `edges` și `history`, și termină cu un singur apel `{"scope":"snapshot"}`, pentru că o rulare pe felii nu atinge instantaneul din cache. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

```bash npm run dev # Hot reload npm run build # Production build npm test # 2,500+ tests npm run test:integration # API tests (requires running services) ``` **Cerințe preliminare:** Node.js >= 20, cu npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 sau Docker. Instalarea automată a motorului pe macOS/Linux necesită, de asemenea, `curl`, un `sh` POSIX și `tar`; Windows nativ folosește `iii.exe`-ul fixat manual, WSL2 sau Docker Desktop.

[Apache-2.0](../LICENSE)