agentmemory: memorie persistentă pentru agenți de programare AI

Memorie persistentă între sesiuni și agenți de programare.
Memorie persistentă pentru Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, 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

rohitg00/agentmemory | Trendshift

Document de design: 1.7k stele / 240 fork-uri pe gist

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.

versiune npm CI Licență Stele skills.sh installs

54 de instrumente MCP 12 hook-uri automate 0 baze de date externe 5,000+ teste trecute

demo agentmemory

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

--- AgentMemory captează evenimentele acceptate ale sesiunilor și face deciziile, remediile și lecțiile căutabile între agenți. Viewer-ul permite inspectarea, editarea, exportul și ștergerea memoriei. Căutarea după cuvinte cheie funcționează fără cheie API; embedding-urile adaugă căutare semantică. ## Instalare Cerințe: - Node.js 20 sau mai nou, cu npm și npx (`node -v`, `npm -v` și `npx -v`). - macOS/Linux au nevoie și de `curl`, un shell POSIX `sh` și `tar` pentru configurarea automată a mediului. - Pe Windows folosește WSL2 sau [instrucțiunile pentru Windows nativ](#windows). Comanda canonică pentru o instalare nouă: ```bash npx -y @agentmemory/agentmemory@latest ``` Alege agenții și un furnizor sau modul fără cheie. Configurarea salvează opțiunile, pornește serverul de memorie și oferă instalarea globală a comenzii `agentmemory`. `-y` acceptă solicitarea npm; `@latest` alege versiunea curentă. Compresia prin LLM necesită un furnizor și `AGENTMEMORY_AUTO_COMPRESS=true`. Modul keyless (fără cheie) dezactivează embedding-urile vectoriale. `memory_recall` (ruta `mem::search`) folosește BM25, în timp ce `memory_smart_search` poate combina și rezultate structurale din graf atunci când datele de graf există deja. Pentru reamintire semantică gratuită, pe dispozitiv, setează `EMBEDDING_PROVIDER=local` în `~/.agentmemory/.env` și repornește. Prima cerere de embedding descarcă `Xenova/all-MiniLM-L6-v2`; după această descărcare inițială a modelului, inferența rulează local. API-ul este la `http://localhost:3111`, iar viewer-ul la `http://localhost:3113`. Implicit, ambele ascultă doar local. Configurarea se află în `~/.agentmemory/.env`; [stocarea datelor](#data-storage) descrie directoarele și instanțele separate. 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ă alt agent cu `agentmemory connect `. Consultă [integrările](#works-with-every-agent) și [comenzile zilnice](#everyday-commands).
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`).
---

Funcționează cu orice agent

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
Claude Code
plugin nativ + 12 hook-uri + MCP
Codex CLI
Codex CLI
plugin nativ + 6 hook-uri + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + hook-uri/skill-uri de plugin
Cursor
Cursor
plugin nativ + hook-uri de ciclu de viață + MCP
OpenCode
OpenCode
plugin de captură + MCP
Devin
Devin
6 hook-uri + skill-uri + MCP
OpenClaw
OpenClaw
plugin nativ + MCP
Hermes
Hermes
plugin nativ + MCP
pi
pi
reamintire nativă + captură + skill-uri
OpenHuman
OpenHuman
backend nativ prin trait-ul Memory
Gemini CLI
Gemini CLI
server MCP
Antigravity
Antigravity
MCP + hook-uri
Claude Desktop
Claude Desktop
server MCP
Warp
Warp
connect + MCP + skill-uri
Zed
Zed
server MCP
Cline
Cline
server MCP
Continue
Continue
server MCP
Droid
Droid
server MCP
Kiro
Kiro
server MCP
Qwen Code
Qwen Code
server MCP
DeepSeek Harness
DeepSeek Harness
captură nativă + MCP
Roo Code
Roo Code
server MCP
Kilo Code
Kilo Code
server MCP
Goose
Goose
server MCP
Aider
Aider
REST API
Oh My Pi
reamintire nativă + captură + skill-uri + MCP opțional

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

--- ### Stocarea datelor Memoria se păstrează implicit în afara depozitului: | Platformă | Director de date | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | Instanța 0 reutilizează un `./data/state_store.db` existent. Alege alt director cu `--data-dir ` sau `AGENTMEMORY_DATA_DIR`. Păstrează același director la repornire și actualizare. ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` `--instance 1` folosește subdirectorul `instance-1`, portul API `3211` și viewer-ul `3213`. Redis și migrarea sunt descrise în [ghidul de stocare și backup](../docs/reliability/state-storage.md). Notele celei mai recente versiuni: [CHANGELOG.md](../CHANGELOG.md). ---

Benchmark-uri

Rezultatele actuale ale căutării, definițiile metricilor și pașii de reproducere: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

vs Competitori

Comparație actualizată a produselor și opțiunilor de implementare, cu surse: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

Început rapid

### Î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, verifică sănătatea, viewer-ul și starea: ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` `status` arată sănătatea serverului, furnizorii, modul de embedding, livrarea observațiilor și recuperarea. Cererile REST protejate necesită secretul serverului. Folosește propriul `AGENTMEMORY_SECRET` dacă este configurat; altfel încarcă secretul local generat: ```bash # Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead. read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret" curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}' curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"query":"restart persistence probe","limit":5}' ``` 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 status agentmemory capture agentmemory capture --drain 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 Replay alături de cele native. Transcrierile sunt indexate și marcate cu sursa `import`; procesarea poate produce și cristale de sesiune ș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 ``` Comanda actualizează mediul local și poate modifica dependențele JavaScript din spațiul de lucru curent. Fă backup datelor și citește [ghidul de actualizare](../docs/upgrades/iii-0.25.md). ### 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. 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` (cale implicită), î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` (cale implicită). 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 ``` Această comandă configurează serverul MCP și îmbină hook-urile incluse cu configurația de utilizator a Claude Code. Dacă `CLAUDE_CONFIG_DIR` nu este setată, este goală sau conține doar spații albe, folosește `~/.claude.json` pentru MCP și `~/.claude/settings.json` pentru hook-uri. Celelalte valori de director sunt folosite exact așa cum sunt furnizate, inclusiv spațiile albe de la început și de la sfârșit. Pentru un director personalizat, setați `CLAUDE_CONFIG_DIR` la aceeași valoare nevidă atât pentru această comandă, cât și pentru Claude Code; fișierele vor fi atunci `$CLAUDE_CONFIG_DIR/.claude.json` și, respectiv, `$CLAUDE_CONFIG_DIR/settings.json`. Claude Code trebuie să primească această valoare în mediul său de pornire, chiar dacă conectorul o citește din fișierul `.env` al AgentMemory. Creați directorul personalizat înainte de a rula această comandă; altfel, conectorul omite Claude Code deoarece nu îl detectează. Dacă valoarea din shell conține doar spații albe, eliminați `CLAUDE_CONFIG_DIR` din mediu înainte de a porni Claude Code, pentru ca și acesta să folosească profilul implicit. Folosește o cale absolută. Căile relative sunt interpretate pornind de la directorul de lucru, deci ambele comenzi trebuie executate din același director. Comenzile hook-urilor folosesc căi absolute către directorul `plugin/` inclus în pachetul instalat. Rulați din nou comanda după actualizarea agentmemory pentru a reîmprospăta aceste căi. Intrările utilizatorului din fișierele de configurare sunt păstrate; sunt înlocuite doar intrările anterioare ale agentmemory. Utilizarea `/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. ### Cursor ```bash agentmemory connect cursor ``` Apoi, în **Settings → Plugins → Add marketplace**, alege directorul agentmemory care conține `.cursor-plugin/plugin.json`, activează plugin-ul **agentmemory** și reîncarcă fereastra. Plugin-ul oferă captură a ciclului de viață, atribuirea proiectului după workspace, skill-uri și MCP. Activează fie hook-urile plugin-ului, fie cele manuale din `~/.cursor/hooks.json`, pentru a evita capturile duplicate. [Cursor](../integrations/cursor/) ### Pi, Oh My Pi, DeepSeek Harness ```bash agentmemory connect pi --with-mcp agentmemory connect omp --with-mcp agentmemory connect dsh --with-hooks ``` Alege comanda pentru gazda ta. Pi și OMP instalează reamintire nativă, captură, reluare offline și skill-uri; `--with-mcp` adaugă toate instrumentele. Rulează `/reload` în Pi sau repornește OMP, apoi verifică `/agentmemory-status`. DSH instalează MCP și plugin-ul de captură inclus; repornește DSH după conectare. Pi acceptă și pachetul instalabil `@agentmemory/pi`. Instalarea locală și disponibilitatea npm sunt descrise în [ghidul Pi](../integrations/pi/). Folosește o singură metodă de instalare pe gazdă. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
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 https://github.com/rohitg00/agentmemory 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` 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 de obicei configurația MCP. Hermes, OpenClaw, Pi și Oh My Pi instalează implicit integrarea nativă și skill-urile; MCP se activează cu `--with-mcp`. - `npx skills add rohitg00/agentmemory` instalează skill-uri pentru agenți fără skill-uri native incluse. Omite acest pas pentru Hermes, OpenClaw, Pi și Oh My Pi; conectorii lor le instalează deja. 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/` | Plugin-ul oferă hook-uri de ciclu de viață, identificarea workspace-ului, skill-uri și MCP în Cursor IDE și `cursor-agent`. Consultă [configurarea Cursor](#cursor). | | **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 --with-mcp`. reamintire nativă + captură + skill-uri. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). | | **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. reamintire nativă + captură + skill-uri. [Oh My Pi](../integrations/omp/). | | **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 9 skill-uri agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) apar nativ în paleta de comenzi slash a Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.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` când lipsește configurarea sau modifică `config.json` existent. Pentru YAML existent afișează blocul de adăugat la `mcpServers:`, păstrând comentariile și ancorele. Continue folosește o listă, nu un obiect. | | **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` activează instrumentele MCP. Adăugați `--with-hooks` pentru pluginul nativ de captură inclus în AgentMemory. Nu este necesar un pachet separat. [DSH](../docs/dsh.md). | | **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 | Folosește [exemplele REST autentificate](#validate-a-fresh-install-and-restart-persistence) pentru salvare și căutare din scripturi. | | **Agenți compatibili** | Doar skill-uri | `npx skills add rohitg00/agentmemory`; alege skill-urile de instalat și agenții țintă. | **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) Folosește [REST API](#api) din orice limbaj sau [instrumentele MCP](#mcp-server) dintr-un agent. REST utilizează JSON și autentificare bearer; vezi [exemplul de salvare și căutare](#validate-a-fresh-install-and-restart-persistence). Pentru integrarea directă a mediului, vezi [exemplele Python](../examples/python/). ### Din sursă ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` `npm start` pornește același server local ca CLI-ul instalat. Cerințele sunt la [Instalare](#install); API-ul și viewer-ul ascultă pe `127.0.0.1`. ### Windows agentmemory rulează pe Windows 10/11. WSL2 urmează calea Linux și poate instala automat engine-ul fixat. Windows nativ necesită instalarea manuală a binarului iii-engine v0.25.1 fixat; descarcă arhiva potrivită de pe [pagina de release iii v0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), verifică checksum-ul și pune `iii.exe` în `PATH` (de exemplu `%USERPROFILE%\.local\bin\iii.exe`). CLI-ul nu extrage automat arhiva ZIP pentru Windows. Conectarea MCP automatizată pe Windows nativ acceptă doar `agentmemory connect copilot-cli`. Pentru ceilalți agenți nativi Windows, folosește blocul MCP manual din [Alți agenți](#other-agents). Rulează `connect` în WSL doar când agentul țintă este instalat în același mediu WSL. **Doar MCP standalone (fără engine).** Dacă ai nevoie doar de instrumentele MCP și nu ai nevoie de REST API, vizualizator sau servicii runtime: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` Rulează `agentmemory doctor` sau repornește cu `--verbose`. Dacă porturile sunt ocupate, folosește `--port ` sau `--instance `. Compatibilitatea și recuperarea sunt în [ghidul de actualizare](../docs/upgrades/iii-0.25.md). ---

Implementare (Deploy)

Folosește Docker Compose sau șabloanele de mai jos pentru găzduire proprie. Memoria și credențialele sunt pe volumul `/data`; fă backup și reutilizează-l la actualizare. Autentificarea, rețeaua, backup-ul și migrarea sunt în [ghidul de implementare](../deploy/README.md).

Implementare pe fly.io Implementare pe Railway

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. REST folosește `3111`, iar viewer-ul `3113`. Păstrează-le private sau protejează-le prin autentificare și TLS. Setările platformelor și [migrarea Docker vechi](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) sunt în ghidul de implementare. ---

De ce agentmemory

Cunoștințele proiectului sunt răspândite între conversații și fișiere de instrucțiuni. AgentMemory permite căutarea deciziilor, remediilor și lecțiilor anterioare din agentul folosit acum. ### 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 | |---|---|---| | Întreținere | Instrucțiuni administrate manual | Istoric de sesiuni și memorie indexate | | Căutare | Încarcă totul în context | BM25 + vector + graf (doar top-K) | | Î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 | ---

Cum funcționează

### Pipeline-ul de memorie ```text PostToolUse hook fires -> Stable event ID / durable capture inbox / offline spool -> Privacy filter (strip secrets, API keys) -> Store raw observation -> Synthetic compression by default (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled Stop / SessionEnd hook fires -> Summarize session -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true) -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject context when enabled by the integration ``` ### 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ă Tabelul descrie hook-urile Claude Code. Celelalte integrări captează evenimentele oferite de gazdă. Injectarea automată a contextului prin hook-urile comune este opțională: `AGENTMEMORY_INJECT_CONTEXT=true`. | 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ă** | Evenimentele acceptate ale sesiunilor și instrumentelor, înregistrate prin integrări native | | **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. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). 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 | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | 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` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) | | Voyage AI | `voyage-code-3` | Plătit | Optimizat pentru cod | | Cohere | `embed-english-v3.0` | Perioadă de probă gratuită | Scop general | | OpenRouter | Orice model | Variabil | Proxy multi-model | ---

Server MCP

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 conectează-te la un server self-hosted) ș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/ ``` ---

Vizualizator în timp real

Pornește automat pe portul `3113`. Vizualizatorul încarcă un snapshot la conectare (`GET /agentmemory/viewer/snapshot`), apoi aplică evenimente live prin SSE la `/agentmemory/viewer/events`, pe worker-ul REST: memorii noi, lecții, observații, intrări de audit, schimbări în graf și actualizări de sănătate apar fără polling sau reîncărcarea paginii. Singurele alte cereri sunt acțiunile pe care dai clic, paginile „încarcă mai multe” și căutările. Când fluxul se întrerupe, vizualizatorul arată cât de vechi sunt numerele, se reconectează cu backoff și resincronizează dintr-un snapshot. - **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 când transmite cererile către API-ul REST. Pentru un bind non-loopback, shell-ul HTML rămâne public, dar fiecare cerere proxy necesită bearer; vizualizatorul îl solicită și îl stochează în session storage. Configurează allowlist-uri explicite de host/origini și TLS înainte de a expune un vizualizator. 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'`). ---

Configurare

### 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 Începe fără cheie pentru captură și căutare după cuvinte cheie. `EMBEDDING_PROVIDER=local` activează căutarea semantică locală după descărcarea modelului. Compresia LLM necesită un furnizor și `AGENTMEMORY_AUTO_COMPRESS=true`; poate trimite o cerere pentru fiecare observație, deci verifică prețurile actuale. Viewer-ul și `agentmemory status` arată furnizorii activi. ### 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 | Port | Scop | Variabilă de mediu | |---|---|---| | `3111` | REST API, MCP HTTP și evenimente live pentru viewer | `III_REST_PORT` | | `3113` | Interfața viewer-ului | `III_VIEWER_PORT` | `--port ` setează portul REST și implicit viewer-ul la `N+2`. `--instance N` creează un mediu separat. Porturile interne trebuie să rămână private; citește [ghidul de implementare](../deploy/README.md) înainte de accesul la distanță. ### Stocare: fișier sau Redis Stocarea implicită în fișiere nu necesită o bază de date separată. Redis este opțional prin `AGENTMEMORY_STATE_BACKEND=redis` și `AGENTMEMORY_REDIS_URL`. Schimbarea backend-ului nu copiază memoria existentă. Persistența, limitele Redis și exportul/importul autentificat sunt în [ghidul de stocare](../docs/reliability/state-storage.md). ### 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 precum `export ANTHROPIC_API_KEY=...`, copiază-l în acest fișier ca `ANTHROPIC_API_KEY=...`, fără prefixul `export`, apoi repornește agentmemory. Setează `AGENTMEMORY_ENV_FILE` pentru a folosi altă cale de fișier env. Variabilele de mediu ale procesului au prioritate față de fișier. Repornește serverul după schimbarea configurării. 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 Opțiuni uzuale pentru `~/.agentmemory/.env`. Injectarea contextului și compresia sunt opționale; compresia necesită și un furnizor. Modul `core` limitează instrumentele MCP vizibile: ```env EMBEDDING_PROVIDER=local # AGENTMEMORY_INJECT_CONTEXT=true # AGENTMEMORY_AUTO_COMPRESS=true # AGENTMEMORY_TOOLS=core # AUTO_FORGET_ENABLED=false # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` Referința completă [`.env.example`](../.env.example) include furnizori, filtre de captură, retenție, stocare, echipe și funcții opționale. `AGENTMEMORY_ENV_FILE` selectează alt fișier. Nu include niciodată un `.env` completat sau secretul bearer în commit-uri. ---

API

147 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.** Dacă `AGENTMEMORY_SECRET` nu este setat, CLI-ul generează la prima pornire un secret aleatoriu în `~/.agentmemory/secret`, cu permisiuni `0600`, și îl copiază și în directorul de date selectat. Toți clienții incluși îl citesc de acolo când comunică 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ță trebuie să seteze secretul în mediul lor. Implementările Docker self-host pornite din repository și entrypoint-urile `deploy/` își generează și exportă propriul secret. Pentru a apela API-ul manual: ```bash curl -H "Authorization: Bearer " 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: [Referința REST generată](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**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.** Compactarea provenienței vechi este amânată la pornire deoarece citește scope-urile vechi în întregime. `/agentmemory/status` raportează `deferred`, sau `off` cu `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Rulează compactarea manuală de mai jos în timpul mentenanței. Migrarea indexului de căutare este separată: folosește `agentmemory graph-index migrate --allow-legacy-scan` conform [ghidului de mentenanță](../docs/reliability/graph-index-migration.md). 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 "Authorization: Bearer " -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 "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

Dezvoltare

```bash npm run dev # Hot reload npm run build # Production build npm test # 5,000+ tests npm run test:integration # API tests (requires running services) ``` Cerințele sunt la [Instalare](#install). Regulile pentru contribuții și verificările de lansare sunt în [CONTRIBUTING.md](../CONTRIBUTING.md).

Licență

[Apache-2.0](../LICENSE)