Tento gist rozšiřuje Karpathyho vzor LLM Wiki o hodnocení spolehlivosti, životní cyklus, znalostní grafy a hybridní vyhledávání: agentmemory je jeho implementací.
---
AgentMemory zachycuje podporované události sessions, umožňuje vyhledávat rozhodnutí a opravy a sdílí projektovou paměť mezi agenty. Prohlížejte, upravujte, exportujte a mažte vzpomínky ve vieweru. Vyhledávání podle klíčových slov funguje bez API klíče; embeddingy přidávají sémantické vyhledávání.
## Instalace
Požadavky:
- Node.js 20 nebo novější s npm a npx (`node -v`, `npm -v` a `npx -v`).
- macOS/Linux také potřebují `curl`, POSIX `sh` a `tar` pro automatické nastavení běhového prostředí.
- Ve Windows použijte WSL2 nebo [návod pro nativní Windows](#windows).
Kanonický příkaz pro čistou instalaci:
```bash
npx -y @agentmemory/agentmemory@latest
```
Vyberte agenty a poskytovatele, nebo režim bez klíče. Průvodce zapíše konfiguraci, spustí paměťový server a nabídne globální instalaci příkazu `agentmemory`. `-y` potvrdí výzvu npm; `@latest` vybere aktuální vydání. Komprese pomocí LLM vyžaduje poskytovatele a `AGENTMEMORY_AUTO_COMPRESS=true`.
Režim bez klíče (keyless) vypíná vektorová embeddingy. `memory_recall` (cesta `mem::search`) používá BM25, zatímco `memory_smart_search` může navíc kombinovat strukturální shody ze znalostního grafu, pokud už grafová data existují. Pro bezplatné sémantické vyhledávání přímo na zařízení nastavte `EMBEDDING_PROVIDER=local` v `~/.agentmemory/.env` a restartujte. První požadavek na embedding stáhne `Xenova/all-MiniLM-L6-v2`; po tomto prvním stažení modelu běží inference lokálně.
API běží na `http://localhost:3111` a živý viewer na `http://localhost:3113`. Oba standardně naslouchají pouze lokálně. Konfigurace je v `~/.agentmemory/.env`; umístění paměti a samostatné instance popisuje [ukládání dat](#data-storage).
Pak ověřte, že vyhledávání funguje, a dejte svému agentovi jeho skills:
```bash
npx -y @agentmemory/agentmemory@latest demo # naseje ukázkové sessions + vyzkouší vyhledávání
npx skills add rohitg00/agentmemory -y # 17 nativních skills, aby agent věděl, kdy sáhnout po paměti
```
Hledání klíčových slov by mělo fungovat ve výchozím režimu bez klíče přes BM25. Dotaz dema `database performance optimization` je záměrně sémantický a dokud není nakonfigurován poskytovatel embeddingů, může vracet nulu výsledků.
Chcete, aby celou věc provedl kódovací agent? Dejte mu jedinou instrukci:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Dalšího agenta připojte pomocí `agentmemory connect `. Viz [podporované integrace](#works-with-every-agent) a [běžné příkazy](#everyday-commands).
Globální instalace / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
Výše uvedený příkaz npx zůstává kanonickou cestou pro čistou instalaci a vyhne se problémům s oprávněními globálního prefixu.
npx vrací starou verzi
npx cachuje podle verze. Vynuťte nejnovější verzi pomocí `npx -y @agentmemory/agentmemory@latest`, nebo jednou vymažte cache pomocí `rm -rf ~/.npm/_npx` (macOS/Linux; na Windows smažte `%LOCALAPPDATA%\npm-cache\_npx`).
---
agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST API. Všichni agenti sdílejí stejný server paměti.
Claude Code nativní plugin + 12 hooks + MCP
Codex CLI nativní plugin + 6 hooks + MCP
GitHub Copilot CLI MCP + hooks/skills pluginu
Cursor nativní plugin + hooks životního cyklu + MCP
OpenCode capture plugin + MCP
Devin 6 hooks + skills + MCP
OpenClaw nativní plugin + MCP
Hermes nativní plugin + MCP
pi nativní recall + zachycení + skills
OpenHuman nativní backend přes Memory trait
Gemini CLI server MCP
Antigravity MCP + hooks
Claude Desktop server MCP
Warp connect + MCP + skills
Zed server MCP
Cline server MCP
Continue server MCP
Droid server MCP
Kiro server MCP
Qwen Code server MCP
DeepSeek Harness nativní zachycení + MCP
Roo Code server MCP
Kilo Code server MCP
Goose server MCP
Aider REST API
Oh My Pi nativní recall + zachycení + skills + volitelné MCP
Funguje s jakýmkoli agentem, který mluví MCP nebo HTTP. Jeden server, paměti sdílené mezi všemi z nich.
---
### Ukládání dat
Vzpomínky se standardně ukládají mimo repozitář:
| Platforma | Adresář dat |
|---|---|
| macOS | `~/Library/Application Support/agentmemory` |
| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
| Windows | `%APPDATA%\agentmemory` |
Instance 0 znovu použije existující `./data/state_store.db`. Jiné umístění nastavíte pomocí `--data-dir ` nebo `AGENTMEMORY_DATA_DIR`. Při restartu a aktualizaci zachovejte stejný adresář.
```bash
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
```
`--instance 1` používá podadresář `instance-1`, API port `3211` a viewer port `3213`. Redis a migraci backendu popisuje [průvodce úložištěm a zálohami](../docs/reliability/state-storage.md).
Nejnovější poznámky k vydání: [CHANGELOG.md](../CHANGELOG.md).
---
Aktuální výsledky vyhledávání, definice metrik a postup reprodukce:
[0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md).
---
Aktuální srovnání produktů a možností nasazení se zdroji:
[AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28.
---
### Vyzkoušejte to za 30 sekund
```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` naseje 3 realistické sessions (JWT autentizace, oprava N+1 dotazu, rate limiting) a spustí proti nim vyhledávání. Instalace bez klíče vypínají vektory, takže klíčové dotazy `mem::search` by měly fungovat přes BM25, zatímco `database performance optimization` může vrátit nulu. `smart-search` může navíc vrátit strukturální shody z grafu, pokud grafová data existují. Aby sémantický dotaz našel opravu N+1 přes vektory, nastavte `EMBEDDING_PROVIDER=local`, restartujte a počkejte, až se dokončí první stažení modelu.
Otevřete `http://localhost:3113` a sledujte, jak se paměť živě staví.
### Ověření čisté instalace a persistence po restartu
Se spuštěným serverem ověřte zdraví, viewer a stav:
```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` ukazuje zdraví serveru, poskytovatele, režim embeddingů, doručování záznamů a obnovu. Chráněné REST požadavky vyžadují secret serveru. Pokud používáte vlastní `AGENTMEMORY_SECRET`, použijte stejnou hodnotu; jinak načtěte automaticky vygenerovaný lokální secret:
```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}'
```
Pak spusťte `npx -y @agentmemory/agentmemory@latest stop`, znovu spusťte kanonický příkaz v terminálu 1, počkejte na `/agentmemory/livez` a vyhledávání zopakujte. Sonda musí být stále vrácena. Pokud jste zvolili vlastní `--data-dir`, použijte při restartu stejný adresář.
### Běžné příkazy
Instalace a nastavení jsou popsány výše v sekci [Instalace](#install) (první spuštění vás jimi provede). Den za dnem:
```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
```
### Replay session
Každou session, kterou agentmemory zaznamená, lze přehrát. Otevřete viewer, zvolte záložku **Replay** a projděte se časovou osou: prompty, volání nástrojů, výsledky nástrojů a odpovědi se vykreslují jako samostatné události s play/pause, řízením rychlosti (0.5x až 4x) a klávesovými zkratkami (mezerník pro přepnutí, šipky pro krokování).
Pro import starších JSONL transkriptů z 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
```
Importované sessions se objeví v Replay vedle nativních. Transkripty jsou indexovány pro vyhledávání a označeny kanálem `import`; zpracování sessions může vytvořit také krystaly a lessons.
> **Upozornění, pokud se spoléháte na `import-jsonl` jako hlavní cestu zachycení:** `cleanupPeriodDays` v Claude Code (v `~/.claude/settings.json`, výchozí **30**) automaticky maže JSONL transkripty starší než toto okno z `~/.claude/projects/`. Pokud instalujete agentmemory nově na měsíce starou historii Claude Code, vše starší než 30 dní je už pryč před prvním importem. Buď spouštějte `import-jsonl` na cronu, zvyšte `cleanupPeriodDays` na vyšší hodnotu, nebo zapojte hooks pro automatické zachycení (výchozí cesta instalace pluginu), aby se každý tah ukládal do agentmemory už za běhu session a čištění JSONL přestalo hrát roli.
### Upgrade / údržba
Příkaz pro údržbu použijte, když chcete úmyslně aktualizovat svůj lokální runtime:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Příkaz aktualizuje místní běhové prostředí a může změnit JavaScriptové závislosti v aktuálním workspace. Zálohujte data a před aktualizací si přečtěte [průvodce upgradem](../docs/upgrades/iii-0.25.md).
### Claude Code (jeden blok, vložte ho)
```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 bez instalace pluginu (cesta MCP-standalone)
Pokud zapojíte server MCP agentmemory přímo přes `~/.claude.json` (výchozí cesta) místo použití `/plugin install`, Claude Code nikdy nevyřeší `${CLAUDE_PLUGIN_ROOT}` a musíte nasměrovat skripty hooks na absolutní cesty v `~/.claude/settings.json` (výchozí cesta). Tyto cesty typicky obsahují verzi agentmemory (např. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), takže další upgrade tiše rozbije všechny hooks.
Řešení:
```bash
agentmemory connect claude-code --with-hooks
```
Tento příkaz nastaví server MCP a sloučí přibalené hooky do uživatelské konfigurace Claude Code. Pokud `CLAUDE_CONFIG_DIR` není nastavena, je prázdná nebo obsahuje pouze bílé znaky, použije pro MCP soubor `~/.claude.json` a pro hooky `~/.claude/settings.json`. Ostatní hodnoty adresáře se používají přesně tak, jak byly zadány, včetně úvodních a koncových bílých znaků. Chcete-li použít vlastní adresář, nastavte pro tento příkaz i Claude Code stejnou neprázdnou hodnotu `CLAUDE_CONFIG_DIR`; MCP pak použije `$CLAUDE_CONFIG_DIR/.claude.json` a hooky `$CLAUDE_CONFIG_DIR/settings.json`. Claude Code musí tuto hodnotu obdržet ve svém spouštěcím prostředí, i když ji konektor načítá ze souboru `.env` AgentMemory. Vlastní adresář vytvořte před spuštěním tohoto příkazu; jinak konektor Claude Code nerozpozná a přeskočí jej. Pokud hodnota v shellu obsahuje pouze bílé znaky, před spuštěním Claude Code zrušte nastavení `CLAUDE_CONFIG_DIR`, aby také použil výchozí profil. Použijte absolutní cestu. Relativní cesty se vyhodnocují vůči pracovnímu adresáři, takže oba příkazy musí být spuštěny ze stejného adresáře.
Příkazy hooků používají absolutní cesty do adresáře `plugin/` přibaleného v nainstalovaném balíčku. Po aktualizaci agentmemory spusťte příkaz znovu, aby se tyto cesty obnovily. Uživatelské položky v konfiguračních souborech zůstanou zachovány; nahradí se pouze předchozí položky agentmemory. Doporučeným postupem zůstává `/plugin install`.
Pro vzdálená nebo chráněná nasazení spusťte Claude Code s nastaveným `AGENTMEMORY_URL` a `AGENTMEMORY_SECRET`. Plugin obě hodnoty předá svému zabalenému serveru MCP; když je `AGENTMEMORY_URL` prázdné, shim MCP použije `http://localhost:3111`.
### Codex CLI (platforma pluginů Codex)
```bash
# 1. start the memory server in a separate terminal
npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```
Plugin pro Codex se dodává ze stejného adresáře `plugin/` jako plugin pro Claude Code. Registruje:
- Zabalený stdio MCP most k běžícímu daemonu, bez stažení přes npm nebo fallback úložiště. Viz [lokální průvodce Codexem](../docs/plugins/codex-local.md) pro testování nevydaného buildu.
- 6 hooks životního cyklu: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 vyvolatelných skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 referenčních skills, které agent načítá podle potřeby (disciplína paměti, nástroje MCP, REST API, konfigurace, agenti, hooks, architektura a průvodce psaním skills)
Enginový hook Codexu vkládá `CLAUDE_PLUGIN_ROOT` do subprocesů hooks (podle [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), takže stejné skripty hooks fungují na obou hostitelích bez duplikace. Události Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure jsou pouze pro Claude Code a pro Codex se neregistrují.
#### Důvěra a kompatibilita hooků Codexu
Nativní vyvolávání hooků pluginu je ověřeno s Codex CLI 0.150.1. Před očekáváním zachycení udělte hookům pluginu důvěru (trust). Chování Codex Desktop závisí na jeho zabaleném runtime; zkontrolujte `/hooks` a potvrďte zachycenou událost, než povolíte náhradní řešení.
Pokud váš hostitel vyžaduje globální hooky, zrcadlete příkazy do `~/.codex/hooks.json`. Když je MCP již zapojené, současný konektor potřebuje `--force`, aby se dostal k instalaci hooků:
```bash
agentmemory connect codex --with-hooks --force
```
Tohle sloučí globální hooky a přepíše záznam MCP agentmemory, při zachování nesouvisejících položek. Před použitím `--force` zkontrolujte veškerá vlastní nastavení endpointu agentmemory. Po upgradu spusťte znovu, abyste obnovili cesty ke skriptům. Povolte buď nativní hooky pluginu, nebo globální kopie, abyste se vyhnuli duplicitnímu zachycení.
### GitHub Copilot CLI
Pro agentní režim VS Code použijte [průvodce MCP a automatickým zachycením pro Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Konektor CLI nekonfiguruje 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` sloučí `mcpServers.agentmemory` do `~/.copilot/mcp-config.json` (nebo `$COPILOT_HOME/mcp-config.json`, pokud je nastaveno `COPILOT_HOME`) a zachová existující servery. Na nativním Windows je to jediný automatizovaný adaptér `connect`; každého dalšího nativního agenta na Windows nakonfigurujte manuálně. `connect` ve WSL je podporován pouze tehdy, když je cílový agent nainstalován ve stejném prostředí WSL. Copilot si server MCP vyzvedne při dalším spuštění nebo po `/mcp`. Pro plný zážitek s hooks/skills nainstalujte i plugin.
### Cursor
```bash
agentmemory connect cursor
```
Potom v **Settings → Plugins → Add marketplace** vyberte checkout agentmemory obsahující `.cursor-plugin/plugin.json`, povolte plugin **agentmemory** a znovu načtěte okno. Plugin poskytuje zachycení životního cyklu, přiřazení projektu podle workspace, skills a MCP. Zapněte buď hooks pluginu, nebo manuální hooks v `~/.cursor/hooks.json`, abyste nezaznamenávali události dvakrát.
[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
```
Vyberte příkaz pro svého hostitele. Pi a OMP instalují nativní recall, zachycení, offline replay a skills; `--with-mcp` přidá úplnou sadu nástrojů. V Pi spusťte `/reload`, OMP restartujte a ověřte `/agentmemory-status`. DSH instaluje MCP a přibalený plugin pro zachycení; po připojení DSH restartujte.
Pi podporuje také instalovatelný balíček `@agentmemory/pi`. Lokální instalaci a dostupnost na npm popisuje [průvodce Pi](../integrations/pi/). Pro každého hostitele používejte jen jeden způsob instalace.
[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (vložte tento 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`.
```
Úplný návod: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (vložte tento 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.
```
Úplný návod: [`integrations/hermes/`](../integrations/hermes/)
### Další agenti
Spusťte server paměti: `npx -y @agentmemory/agentmemory@latest`
#### Nativní skills přes `npx skills add`
agentmemory dodává 17 skills ve formátu `/SKILL.md` ve stylu Claude Code: 9 vyvolatelných akčních skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) a 8 referenčních skills, které agent načítá podle potřeby (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referenční skills obsahují datové tabulky generované ze zdroje, takže se nikdy neliší. CLI [`skills`](https://npmjs.com/package/skills) od vercel-labs je automaticky instaluje do nativního adresáře skills volajícího agenta napříč 50+ agenty (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf a dalšími):
```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
```
Toto je **doplňkové** k `agentmemory connect `:
- `agentmemory connect ` obvykle zapisuje konfiguraci MCP. Hermes, OpenClaw, Pi a Oh My Pi standardně instalují nativní integraci a skills; MCP zapnete pomocí `--with-mcp`.
- `npx skills add rohitg00/agentmemory` instaluje skills pro agenty bez přibalených nativních skills. U Hermes, OpenClaw, Pi a Oh My Pi tento krok vynechte; skills už instaluje jejich konektor.
Pro těch několik agentů, které CLI skills ještě nepokrývá (Zed v1.3.x a nižší), vložte 17 souborů SKILL.md do nativního adresáře skills agenta sami; stejný formát funguje všude.
#### Standardní blok MCP
Položka agentmemory je **stejný blok serveru MCP** na všech hostitelích, kteří používají tvar `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}"
}
}
```
**Sloučte tuto položku do existujícího objektu `mcpServers`** v konfiguračním souboru hostitele; soubor nenahrazujte. Pokud soubor už má jiné servery, přidejte `agentmemory` vedle nich jako další klíč uvnitř `mcpServers`. Pokud `mcpServers` zcela chybí, vložte blok do `{ "mcpServers": { ... } }`. Zástupné symboly `${VAR}` zdědí `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` ze shellu při spuštění serveru MCP; nenastavené proměnné předají prázdné řetězce a shim se vrátí na `http://localhost:3111`. Jeden zapojený záznam pokrývá lokální i vzdálená (k8s / za reverzní proxy) nasazení.
| Agent | Konfigurační soubor | Poznámky |
|---|---|---|
| **Cursor (pouze MCP)** | `~/.cursor/mcp.json` | Sloučte do `mcpServers`, nebo použijte `agentmemory connect cursor`. Na webu je k dispozici i deeplink na jedno kliknutí. |
| **Cursor (plný plugin)** | `.cursor-plugin/` | Plugin poskytuje hooks životního cyklu, rozpoznání workspace, skills a MCP v Cursor IDE i `cursor-agent`. Viz [nastavení Cursoru](#cursor). |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Sloučte do `mcpServers`. Po úpravě Claude Desktop restartujte. |
| **Cline / Roo Code / Kilo Code** | nastavení MCP v Cline (Settings UI → MCP Servers → Edit) | Stejný blok `mcpServers`. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` sloučí položku MCP; `--with-hooks` přidá šest nativních hooks pro automatické zachycení (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) s malými písmeny v maticích nástrojů Devin. Ověřte pomocí `devin mcp list` a `/hooks` uvnitř devin. |
| **Devin CLI (plný plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` z checkoutu zaregistruje všech 17 skills jako slash příkazy `/agentmemory:` plus server MCP. Hooks pluginu Devin neumí vyvolat `SessionStart`/`SessionEnd`, takže ho pro plné zachycení session kombinujte s `connect devin --with-hooks`. |
| **Devin (cloud)** | Settings → Connections → MCP servers | Přidejte vlastní MCP (STDIO): příkaz `npx`, argumenty `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` ukazující na síťově dostupné nasazení agentmemory plus `AGENTMEMORY_SECRET` (cloudové sessions se nedostanou na localhost — viz [`deploy/`](../deploy/)). Uložte secret do Devin Secrets a pomocí „Test listing tools“ ověřte, že se objeví všech 54 nástrojů. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (sloučí se automaticky). |
| **GitHub Copilot CLI (pouze MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` sloučí `mcpServers.agentmemory`; Copilot si ji vyzvedne při dalším spuštění nebo po `/mcp`. |
| **GitHub Copilot CLI (plný plugin)** | instalace pluginu Copilot | `copilot plugin install rohitg00/agentmemory:plugin` pro plugin z podadresáře GitHub. |
| **OpenClaw** | konfigurace MCP OpenClaw | Stejný blok `mcpServers`. Hlouběji: `openclaw plugins install ./integrations/openclaw` obsadí paměťový slot OpenClaw (automaticky přepne z `memory-core`); nastavte `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, jinak je zachycení tahů tiše blokováno. Viz [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (pouze MCP)** | `.codex/config.toml` | Tvar TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, nebo manuálně přidejte `[mcp_servers.agentmemory]`. |
| **Codex CLI (plný plugin)** | marketplace pluginů Codex | `codex plugin marketplace add rohitg00/agentmemory`, pak `codex plugin add agentmemory@agentmemory`. Registruje MCP + 6 hooks životního cyklu + 17 skills. Důvěřujte hookům a ověřte zachycení ve svém hostiteli; viz [nastavení a validace Codexu](../docs/plugins/codex-local.md). |
| **OpenCode (pouze MCP)** | `opencode.json` | Jiný tvar: klíč `mcp` na nejvyšší úrovni, příkaz jako pole: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (plný plugin)** | `plugin/opencode/` | 22 hooks pro automatické zachycení pokrývajících životní cyklus session, zprávy, nástroje a chyby. Přiřazení k projektu je po jednotlivých sessions, takže jeden proces OpenCode pokrývající více repozitářů zařadí každou session pod její vlastní projekt. Dva slash příkazy (`/recall`, `/remember`). Zkopírujte `plugin/opencode/` do svého workspace OpenCode a doplňte položku pluginu do `opencode.json`. Úplnou tabulku hooks + analýzu mezer najdete v [`plugin/opencode/README.md`](../plugin/opencode/README.md). |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. nativní recall + zachycení + skills. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. nativní recall + zachycení + skills. [Oh My Pi](../integrations/omp/). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` dá poskytovatele paměti se 6 hooks (prefetch, zachycení tahu, konec session, pre-compress, zrcadlení MEMORY.md, blok systémového promptu). Ověřte pomocí `hermes plugins doctor` a `hermes memory status`. Viz [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` zapíše standardní blok `mcpServers`. Payload hooks je polově kompatibilní s Claude Code, takže existující skripty pro 12 hooks fungují bez úprav; zapojte je přes sekci `hooks` ve stejném `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` nainstaluje MCP a hooky pro zachycení do sdíleného adresáře přizpůsobení. Viz [nastavení a limity Antigravity](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` používá stejnou konfiguraci MCP a hooků jako aktuální verze IDE. Stávající instalace by měly provést refresh pomocí `--force`; viz [poznámky k upgradu](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` zapíše konfiguraci na úrovni uživatele. Přepisy na úrovni workspace patří do `.kiro/settings/mcp.json` vedle vašeho kódu. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` zapíše standardní blok `mcpServers`. Warp také automaticky vyhledává skills z `.claude/skills/`; po instalaci pluginu Claude Code se 9 skills agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) objeví nativně v paletě slash příkazů Warp. |
| **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` zapíše standardní blok `mcpServers`. Uživatelé rozšíření VS Code: vložte stejný blok přes Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (preferované) nebo `config.json` (starší) | `agentmemory connect continue` vytvoří `config.yaml`, pokud konfigurace chybí, nebo upraví existující `config.json`. U existujícího YAML vypíše blok k vložení pod `mcpServers:`, aby zachoval komentáře a kotvy. Continue používá pole, nikoli objekt. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` zapíše pod `context_servers` (klíč Zed, NE `mcpServers`). Vzdálené servery MCP lze zapojit místo toho přes `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` zapíše standardní blok `mcpServers`. Přepisy na úrovni projektu patří do `/.factory/mcp.json`. Pro nativní automatické zachycení přidejte `--with-hooks`. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` zapne nástroje MCP. Přidejte `--with-hooks` pro nativní zachytávání zahrnuté v AgentMemory. Samostatný balíček pluginu není potřeba. [DSH](../docs/dsh.md). |
| **Goose** | UI nastavení MCP v Goose | Stejný blok `mcpServers`; použijte `goose configure` → Add Extension → MCP. Přímá úprava YAML v `~/.config/goose/config.yaml` je podporována, ale schéma používá `extensions:` + `cmd` (ne `mcpServers:` + `command`). |
| **Aider** | n/a | Použijte [autentizované REST příklady](#validate-a-fresh-install-and-restart-persistence) pro ukládání a vyhledávání ze skriptů. |
| **Podporovaní agenti** | Pouze skills | `npx skills add rohitg00/agentmemory`; vyberte skills a agenty, pro které je chcete nainstalovat. |
**Sandboxovaní klienti MCP** (Flatpak / Snap / omezující kontejnery), kteří se nedostanou na `localhost` hostitele: navíc nastavte `"AGENTMEMORY_FORCE_PROXY": "1"` v bloku `env` a nasměrujte `AGENTMEMORY_URL` na cestu, na kterou se sandbox skutečně dostane (např. vaši LAN IP adresu).
### Programový přístup (Python / Rust / Node)
Použijte [REST API](#api) z libovolného jazyka nebo [MCP nástroje](#mcp-server) z agenta. REST používá JSON a bearer autentizaci; viz [příklad ukládání a vyhledávání](#validate-a-fresh-install-and-restart-persistence). Přímou integraci běhového prostředí ukazují [příklady v Pythonu](../examples/python/).
### Ze zdroje
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
`npm start` spustí stejný lokální server jako nainstalované CLI. Požadavky jsou v sekci [Instalace](#install); API a viewer naslouchají na `127.0.0.1`.
### Windows
agentmemory běží na Windows 10/11. WSL2 používá cestu pro Linux a může pinned engine nainstalovat automaticky. Nativní Windows vyžaduje ručně nainstalovanou binárku iii-engine v0.25.1; stáhněte odpovídající archiv ze [stránky vydání iii v0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), ověřte kontrolní součet a umístěte `iii.exe` do `PATH` (například `%USERPROFILE%\.local\bin\iii.exe`). CLI ZIP pro Windows automaticky nerozbaluje.
Automatizované zapojení MCP na nativním Windows podporuje pouze `agentmemory connect copilot-cli`. U ostatních nativních agentů použijte manuální blok MCP ze sekce [Další agenti](#other-agents). `connect` ve WSL spouštějte pouze tehdy, pokud je cílový agent nainstalován ve stejném prostředí WSL.
**Pouze samostatné MCP (bez enginu).** Pokud potřebujete jen nástroje MCP a nikoli REST API, viewer nebo služby runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
```
Spusťte `agentmemory doctor` nebo restartujte s `--verbose`. Jsou-li výchozí porty obsazené, použijte `--port ` nebo `--instance `. Kompatibilitu a obnovu popisuje [průvodce upgradem](../docs/upgrades/iii-0.25.md).
---
Nasazení
Pro vlastní hosting použijte Docker Compose nebo šablony níže. Paměť a přihlašovací údaje jsou na svazku `/data`; při aktualizaci ho zálohujte a znovu použijte. Autentizaci, síťový přístup, zálohy a migraci popisuje [průvodce nasazením](../deploy/README.md).
Tlačítko pro nasazení na jedno kliknutí od Renderu vyžaduje `render.yaml` v kořeni repozitáře, který záměrně udržujeme čistý. Pro manuální nasměrování na blueprint v repozitáři použijte postup Render Blueprint popsaný v [`deploy/render/`](.././deploy/render/README.md).
Úplné detaily nastavení (zachycení HMAC, SSH tunel pro viewer, rotace, zálohy,
spodní hranice nákladů) jsou v [`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): jeden stroj s
`auto_stop_machines = "stop"`; nejlevnější v nečinnosti.
- [`deploy/railway`](.././deploy/railway/README.md): pevný poplatek plánu Hobby,
volume v dashboardu.
- [`deploy/render`](.././deploy/render/README.md): postup Blueprint,
automatické snímky disku na placených plánech.
- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted na vlastním
VPS přes [Coolify](https://coolify.io/self-hosted); stejný Docker
Compose stack, host i data vlastníte vy.
REST používá `3111`, viewer `3113`. Ponechte je v privátní síti, nebo je chraňte autentizací a TLS. Nastavení platforem a [migraci starého Dockeru](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) popisuje průvodce nasazením.
---
Znalosti o projektu se rozptylují mezi chaty a soubory instrukcí. AgentMemory umožňuje najít dřívější rozhodnutí, opravy a lessons z právě používaného agenta.
### vs vestavěná paměť agenta
Každý AI kódovací agent se dodává s vestavěnou pamětí: Claude Code má `MEMORY.md`, Cursor má poznámkové bloky, Cline má memory bank. Ty funguji jako lístečky na ledničku. agentmemory je prohledávatelná databáze za těmi lístečky.
| | Vestavěné (CLAUDE.md) | agentmemory |
|---|---|---|
| Údržba | Ručně spravované instrukce | Indexovaná historie sessions a vzpomínky |
| Vyhledávání | načte vše do kontextu | BM25 + vektor + graf (pouze top-K) |
| Napříč agenty | soubory po agentech | MCP + REST (jakýkoli agent) |
| Koordinace | žádná | leases, signály, akce, routiny |
| Observabilita | manuální čtení souborů | viewer v reálném čase na :3113 |
---
### Pipeline paměti
```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
```
### 4úrovňová konsolidace paměti
Vzor podle toho, jak lidský mozek zpracovává paměť, včetně konsolidace během spánku.
| Úroveň | Co | Analogie |
|------|------|---------|
| **Pracovní** | Syrová pozorování z použití nástrojů | Krátkodobá paměť |
| **Epizodická** | Komprimovaná shrnutí sessions | „Co se stalo" |
| **Sémantická** | Extrahovaná fakta a vzory | „Co vím" |
| **Procedurální** | Workflows a rozhodovací vzory | „Jak to udělat" |
Paměti v čase slábnou (Ebbinghausova křivka). Často navštěvované paměti se zesilují. Zastaralé paměti se automaticky odstraňují. Rozpory se detekují a řeší.
### Co se zachycuje
Tabulka popisuje hooks Claude Code. Ostatní integrace zachycují události poskytované svým hostitelem. Automatické vkládání kontextu přes sdílené hooks je volitelné: `AGENTMEMORY_INJECT_CONTEXT=true`.
| Hook | Zachycuje |
|------|----------|
| `SessionStart` | cestu k projektu, ID session |
| `UserPromptSubmit` | uživatelské prompty (filtrované na soukromí) |
| `PreToolUse` | vzory přístupu k souborům + obohacený kontext |
| `PostToolUse` | název nástroje, vstup, výstup |
| `PostToolUseFailure` | kontext chyby |
| `PreCompact` | znovu vloží paměť před kompakcí |
| `SubagentStart/Stop` | životní cyklus sub-agenta |
| `Stop` | shrnutí na konci session |
| `SessionEnd` | značka dokončení session |
### Klíčové schopnosti
| Schopnost | Popis |
|---|---|
| **Automatické zachycení** | Podporované události sessions a nástrojů zaznamenané nativními integracemi |
| **Sémantické vyhledávání** | BM25 + vektor + znalostní graf s fúzí RRF |
| **Evoluce paměti** | verzování, nahrazování (supersession), grafy vztahů |
| **Hygiena vyhledávání** | nahrazené verze paměti opustí vyhledávací indexy; řetězec verzí v KV si uchovává úplnou historii |
| **Náznaky téměř-duplikátů** | ukládání nahlásí orientační shodu `similarTo`, když se nový obsah silně podobá existující paměti |
| **Rozsah po agentech** | `agentId` prochází ukládáním a vyhledáváním přes REST, MCP i vyhledávací index, v režimu sdíleném nebo izolovaném |
| **Původ v okamžiku zápisu** | každé pozorování a paměť nese neměnný kanál původu (user, agent, tool, import nebo shared) otištěný při zachycení, uložení a importu |
| **Automatické zapomínání** | expirace TTL, detekce rozporů, odstranění podle důležitosti |
| **Soukromí na prvním místě** | API klíče, secrets a značky `` se před uložením odstraní |
| **Samoopravné chování** | circuit breaker, záložní řetězec poskytovatelů, monitorování zdraví |
| **Most do Claude** | obousměrná synchronizace s MEMORY.md |
| **Znalostní graf** | extrakce entit + BFS průchod |
| **Týmová paměť** | sdílená i privátní, s namespacy mezi členy týmu |
| **Původ citací** | dohledání jakékoli paměti zpět k výchozím pozorováním |
| **Git snapshoty** | verzování, rollback a diff stavu paměti |
---
Trojproudové vyhledávání kombinující tři signály:
| Proud | Co dělá | Kdy |
|---|---|---|
| **BM25** | shoda klíčových slov se stemmingem a rozšířením synonym | vždy zapnuto |
| **Vector** | kosinová podobnost nad hustými embeddingy | nakonfigurován poskytovatel embeddingů |
| **Graph** | průchod znalostním grafem přes shodu entit | v dotazu byly detekovány entity |
Sloučeno pomocí Reciprocal Rank Fusion (RRF, k=60) a diverzifikováno po sessions (max 3 výsledky na session).
Když je vektorový index naplněný, `mem::search` (za `memory_recall`) používá hybridní řadič BM25 + vektor. Bez embeddingů používá BM25. `smart-search` může navíc sloučit strukturální shody z grafu, pokud grafová data existují, včetně režimu bez klíče. Vyhledávání lessons běží na vyhrazeném in-memory indexu BM25 místo skenování celého korpusu při každém dotazu. Nahrazené verze paměti jsou vyloučeny z každé cesty vyhledávání; řetězec verzí uchovává jejich historii.
[0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md).
BM25 standardně tokenizuje řečtinu, cyrilici, hebrejštinu, arabštinu a akcentovanou latinku. Pro paměti v čínštině / japonštině / korejštině nainstalujte volitelné segmentery (`npm install @node-rs/jieba tiny-segmenter`), aby se běhy CJK rozdělily na tokeny na úrovni slov; bez nich agentmemory měkce spadne na tokenizaci celého běhu a jednou vypíše nápovědu na stderr.
### Poskytovatelé embeddingů
Instalace bez klíče vypínají vektorové embeddingy: `mem::search` používá BM25, zatímco `smart-search` může navíc použít existující strukturální grafová data. Pro bezplatné sémantické embeddingy přímo na zařízení přidejte toto do `~/.agentmemory/.env` a restartujte agentmemory:
```env
EMBEDDING_PROVIDER=local
```
Běžná instalace npm obsahuje volitelný runtime `@huggingface/transformers`. První požadavek na embedding stáhne `Xenova/all-MiniLM-L6-v2`, takže potřebuje síťový přístup a může trvat déle; následná inference běží na zařízení. Vzdálení poskytovatelé jsou automaticky detekováni podle svých klíčů, pokud je nepřepíše `EMBEDDING_PROVIDER`.
| Poskytovatel | Model | Náklady | Poznámky |
|---|---|---|---|
| **Lokální (doporučeno jako opt-in)** | `all-MiniLM-L6-v2` | zdarma | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) |
| Gemini | `gemini-embedding-001` | bezplatný tier | 100+ jazyků, rozměry 768/1536/3072 (MRL), vstup 2048 tokenů. Nahrazuje `text-embedding-004` ([deprecated, ukončení 14. 1. 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` | placené | optimalizováno pro kód |
| Cohere | `embed-english-v3.0` | bezplatná zkouška | univerzální použití |
| OpenRouter | jakýkoli model | liší se | proxy pro více modelů |
---
54 nástrojů, 6 resources, 3 prompty a 17 skills.
> **Shim MCP vs plný server:** publikovaný balíček `@agentmemory/mcp` je tenký shim. Celý povrch 54 nástrojů zpřístupní **pouze když se dostane k běžícímu serveru agentmemory** přes `AGENTMEMORY_URL` (proxy režim). Když žádný server není dostupný, shim se vrátí na lokální sadu 7 nástrojů (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Proměnná prostředí `AGENTMEMORY_TOOLS=core|all` je příznak *na straně serveru*; nastavení v bloku `env` shimu nemá žádný efekt. Pokud v Cursor / OpenCode / Gemini CLI vidíte jen 7 nástrojů, spusťte `npx -y @agentmemory/agentmemory@latest` nebo se připojte k self-hostovanému serveru a nastavte `AGENTMEMORY_URL=http://localhost:3111`.
### 54 nástrojů
Tři povrchy nástrojů, od nejmenšího k největšímu: `AGENTMEMORY_TOOLS=core` omezí viditelnost na 8 nezbytných (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); základní sada níže je 14 základních nástrojů registru; výchozí nastavení (`AGENTMEMORY_TOOLS=all`) zpřístupní všech 54.
Základní nástroje (14)
| Nástroj | Popis |
|------|-------------|
| `memory_recall` | vyhledá minulá pozorování |
| `memory_compress_file` | komprimuje soubory markdown při zachování struktury |
| `memory_save` | uloží poznatek, rozhodnutí nebo vzor |
| `memory_file_history` | minulá pozorování o konkrétních souborech |
| `memory_patterns` | detekuje opakující se vzory |
| `memory_sessions` | vypíše nedávné sessions |
| `memory_smart_search` | hybridní sémantické + klíčové vyhledávání |
| `memory_vision_search` | vyhledává pozorování z obrázků |
| `memory_timeline` | chronologická pozorování |
| `memory_profile` | profil projektu (koncepty, soubory, vzory) |
| `memory_export` | exportuje všechna data paměti |
| `memory_relations` | dotaz na graf vztahů |
| `memory_commit_lookup` | sessions za konkrétním git commitem |
| `memory_commits` | commity zaznamenané pro session |
Rozšířené nástroje (celkem 54, výchozí povrch)
| Nástroj | Popis |
|------|-------------|
| `memory_patterns` | detekuje opakující se vzory |
| `memory_timeline` | chronologická pozorování |
| `memory_relations` | dotaz na graf vztahů |
| `memory_graph_query` | průchod znalostním grafem |
| `memory_consolidate` | spustí 4úrovňovou konsolidaci |
| `memory_claude_bridge_sync` | synchronizace s MEMORY.md |
| `memory_team_share` | sdílení s členy týmu |
| `memory_team_feed` | nedávné sdílené položky |
| `memory_audit` | audit trail operací |
| `memory_governance_delete` | smazání s audit trail |
| `memory_snapshot_create` | snapshot verzovaný v gitu |
| `memory_action_create` | vytvoří pracovní položky se závislostmi |
| `memory_action_update` | aktualizuje stav akce |
| `memory_frontier` | nezablokované akce seřazené podle priority |
| `memory_next` | jediná nejdůležitější další akce |
| `memory_lease` | exkluzivní leases akcí (multi-agent) |
| `memory_routine_run` | instanciuje workflow routiny |
| `memory_signal_send` | zprávy mezi agenty |
| `memory_signal_read` | čte zprávy s potvrzením o přijetí |
| `memory_checkpoint` | brány na externí podmínky |
| `memory_mesh_sync` | P2P synchronizace mezi instancemi |
| `memory_sentinel_create` | hlídače řízené událostmi |
| `memory_sentinel_trigger` | vyvolá sentinely externě |
| `memory_sketch_create` | efemérní grafy akcí |
| `memory_sketch_promote` | povýší na trvalé |
| `memory_crystallize` | zhuští řetězce akcí |
| `memory_diagnose` | kontroly zdraví |
| `memory_heal` | automatická oprava zaseknutého stavu |
| `memory_facet_tag` | značky dimenze:hodnota |
| `memory_facet_query` | dotaz podle facetových značek |
| `memory_verify` | dohledá původ |
### 6 resources · 3 prompty · 17 skills
| Typ | Název | Popis |
|------|------|-------------|
| Resource | `agentmemory://status` | zdraví, počet sessions, počet pamětí |
| Resource | `agentmemory://project/{name}/profile` | inteligence pro konkrétní projekt |
| Resource | `agentmemory://project/{name}/recent` | nedávná pozorování pro projekt |
| Resource | `agentmemory://memories/latest` | posledních 10 aktivních pamětí |
| Resource | `agentmemory://graph/stats` | statistiky znalostního grafu |
| Resource | `agentmemory://team/{id}/profile` | sdílený profil týmu |
| Prompt | `recall_context` | vyhledá + vrátí kontextové zprávy |
| Prompt | `session_handoff` | data pro předání mezi agenty |
| Prompt | `detect_patterns` | analyzuje opakující se vzory |
| Skill | `/recall` | vyhledá v paměti |
| Skill | `/remember` | uloží do dlouhodobé paměti |
| Skill | `/session-history` | nedávná shrnutí sessions |
| Skill | `/forget` | smaže pozorování/sessions |
Tabulka zobrazuje čtyři klíčové skills. Celá sada je 9 vyvolatelných skills plus 8 referenčních skills; viz sekce Nativní skills výše.
### Samostatné MCP
Spuštění bez plného serveru, pro jakéhokoli klienta MCP. Funguje kterékoli z tohoto:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Nebo přidejte do konfigurace MCP svého agenta:
Většina agentů (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
Sloučte položku `agentmemory` do existujícího objektu `mcpServers` vašeho hostitele, místo nahrazení celého souboru. Pro sandboxované klienty, kteří se nedostanou na `localhost` hostitele, přidejte do bloku env `"AGENTMEMORY_FORCE_PROXY": "1"` a nastavte `AGENTMEMORY_URL` na cestu, na kterou se sandbox dostane.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Zkopírujte soubor pluginu z repozitáře:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
Automaticky se spouští na portu `3113`. Viewer při připojení načte jeden snapshot (`GET /agentmemory/viewer/snapshot`) a pak aplikuje živé události přes SSE na `/agentmemory/viewer/events` workeru REST: nové paměti, lessons, pozorování, audit záznamy, změny grafu a aktualizace zdraví se zobrazují bez pollingu nebo obnovení stránky. Další požadavky vznikají jen při akcích, které provedete, načtení dalších stránek nebo vyhledávání. Při výpadku streamu viewer ukáže stáří údajů, znovu se připojí s odstupňovaným prodlením a synchronizuje se z nového snapshotu.
- **12 záložek ve čtyřech skupinách** s živými počty, deep linky (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), klávesovými zkratkami a mobilním menu.
- **Memories:** vyhledávání na straně serveru, filtry podle projektu, agenta a typu, detailní panel s řetězcem verzí a diffem slov, odkazy na původ, tlačítka pro kopírování id, volání MCP a příkazu curl, úprava (nová verze), forget s potvrzením, hromadný forget a export JSON.
- **Sessions:** vložená časová osa pozorování s čitelným vstupem a výstupem nástrojů, filtry a stránkování, a paměti i lessons, které každá session vyprodukovala.
- **Graph:** vyhledávání, detail uzlu se vztahy a zdroji, legenda, která se nespoléhá jen na barvu, a ovládání zoomu.
- **Health:** živá verze `GET /agentmemory/status`. Každý problém má svou opravu, plus backend state, stav uložení indexu, průběh komprese provenience grafu a vysvětlení konsolidace se skutečnými prahovými hodnotami.
- **Stránky Audit, Activity, Profile, Replay, Lessons, Actions a Crystals**, každá s prázdným stavem, který říká, co daná sekce je, proč je prázdná a jaký příkaz ji naplní, a tooltip se slovníčkem `?` u každého termínu a čísla.
```bash
open http://localhost:3113
```
Server vieweru se ve výchozím stavu váže na `127.0.0.1` a při předávání požadavků na REST API přikládá server secret. Při bindu mimo loopback zůstává HTML shell veřejný, ale každý proxy požadavek vyžaduje bearer token; viewer si o něj řekne a uloží jej do session storage. Před vystavením vieweru nakonfigurujte výslovné povolené hostitele/originy a TLS. REST endpoint `/agentmemory/viewer` podléhá běžným pravidlům bearer tokenu a prohlížeče bez tokenu přesměruje na port vieweru. Hlavičky CSP používají nonce skriptu pro každou odpověď a zakazují inline atributy handlerů (`script-src-attr 'none'`).
---
### Poskytovatelé LLM
agentmemory automaticky detekuje poskytovatele z vašeho prostředí. Poskytovatel zpřístupní operace založené na LLM, ale samotná konfigurace poskytovatele nezapíná kompresi pozorování psanou LLM. Tato cesta vyžaduje jak poskytovatele, tak `AGENTMEMORY_AUTO_COMPRESS=true`.
| Poskytovatel | Konfigurace | Poznámky |
|----------|--------|-------|
| **No-op (výchozí)** | konfigurace není potřeba | komprese/shrnutí přes LLM je vypnuto. Syntetická komprese a vyhledávání přes BM25 fungují i tak. Pokud jste se dříve spoléhali na záložní řešení přes předplatné Claude, viz `AGENTMEMORY_ALLOW_AGENT_SDK` níže. |
| Anthropic API | `ANTHROPIC_API_KEY` | fakturace za token |
| MiniMax | `MINIMAX_API_KEY` | kompatibilní s Anthropic |
| Gemini | `GEMINI_API_KEY` | zapíná i embeddingy |
| OpenRouter | `OPENROUTER_API_KEY` | jakýkoli model |
| OpenAI API | `OPENAI_API_KEY` | výchozí `gpt-5.6-luna`, přepište pomocí `OPENAI_MODEL` |
| **Lokální (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) nebo `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | cokoli kompatibilní s OpenAI API. Nulové náklady, běží na vašem hardwaru. Viz [Lokální modely](#local-models-ollama--lm-studio--vllm) níže. |
| Záložní řešení přes předplatné Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | pouze opt-in. Spouští sessions `@anthropic-ai/claude-agent-sdk`; dříve to způsobovalo neomezenou rekurzi Stop-hook, takže už to není výchozí nastavení. |
### Lokální modely (Ollama / LM Studio / vLLM)
agentmemory komunikuje s jakýmkoli serverem kompatibilním s OpenAI API, takže cokoli, co zpřístupňuje `/v1/chat/completions`, funguje beze změn kódu. Žádné placené klíče, žádný cloud, žádné rate limity; běží čistě na vašem hardwaru.
**Ollama** (výchozí port `11434`):
```bash
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
```
```env
# ~/.agentmemory/.env
OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b
```
**LM Studio** (výchozí port `1234`):
Otevřete LM Studio → záložku Local Server → Start Server. V nabídce vyberte libovolný chat model (Qwen 3, gpt-oss, DeepSeek R1 atd.).
```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**: stejný tvar. Nasměrujte `OPENAI_BASE_URL` na URL, kterou zpřístupňuje váš server, a nastavte `OPENAI_MODEL` na název, který váš server přijme.
**Výběr modelu pro práci s pamětí**: komprese a shrnutí jsou krátké úlohy (<2K tokenů na vstupu, <500 tokenů na výstupu), kde plně postačí 7B instruct model. Doporučení:
| Model | Velikost | Proč |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | vyvážená výchozí volba na stroji s 16 GB; silný v extrakci a textu ve tvaru nástrojů |
| `qwen3:4b` | ~2.6 GB | nejmenší rozumná volba; v pořádku pro kompresi, slabší pro extrakci grafu |
| `qwen3-coder:30b` | ~19 GB | nejlepší lokální volba pro sessions ve tvaru kódu (30B MoE, 3.3B aktivních) na hardwaru 24-32 GB |
| `gpt-oss:20b` | ~14 GB | silný obecný model, který se vejde do 16 GB RAM |
| `deepseek-r1:8b` | ~5.2 GB | reasoning distill; pomalejší, ale čistší extrakce |
Modely Qwen 3 ve výchozím stavu „myslí" a mohou spálit celý rozpočet tokenů na uvažování ještě před jakýmkoli výstupem. Nastavte `AGENTMEMORY_LLM_NOTHINK=1`, aby se k promptům pro extrakci grafu přidalo `/no_think`, a zvyšte `MAX_TOKENS` (16384 funguje), pokud se extrakce vrací prázdné.
Modely třídy reasoning (ve stylu `o1` s bloky ``) mohou vracet prázdný `content` s polem `reasoning`, které váš lokální server nemusí zpřístupnit. Pokud se extrakce vrací prázdné, nejprve přepněte na model bez reasoning. Proměnná prostředí `OPENAI_REASONING_EFFORT=none` může také vypnout myšlení u thinking modelů Ollama Cloud, které zrcadlí schéma reasoning od OpenAI.
Lokální embeddingy se dodávají jako volitelná závislost, ale ve výchozím stavu nejsou zapnuté. Nastavte `EMBEDDING_PROVIDER=local`, abyste zapnuli `Xenova/all-MiniLM-L6-v2` (384 dimenzí). První požadavek na embedding stáhne model; inference pak běží na zařízení. Bez tohoto nastavení nebo vzdáleného klíče pro embeddingy zůstávají vektory vypnuté, `mem::search` používá BM25 a `smart-search` může i tak přidat existující shody z grafu.
### Výběr modelu s ohledem na náklady
Začněte bez klíče pro zachycení a vyhledávání podle klíčových slov. `EMBEDDING_PROVIDER=local` zapne lokální sémantické vyhledávání po prvním stažení modelu. Komprese pomocí LLM vyžaduje poskytovatele a `AGENTMEMORY_AUTO_COMPRESS=true`; může odeslat požadavek pro každé pozorování, proto ověřte aktuální ceny poskytovatele. Aktivní poskytovatele ukazuje viewer a `agentmemory status`.
### Paměť pro víc agentů (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
V multi-agentních nastaveních, kde si několik rolí sdílí jeden server agentmemory (architekt / vývojář / reviewer / researcher / support agent), `AGENT_ID` oznamuje každý zápis rolí, která ho vytvořila. `AGENTMEMORY_AGENT_SCOPE` řídí, zda vyhledávání podle této značky filtruje.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
Dva režimy:
| Režim | Značí zápisy | Filtruje vyhledávání | Kdy použít |
|------|------------|---------------|-------------|
| `shared` (výchozí) | ano | ne | kontext napříč agenty s audit trail. Architekt vidí, co zaznamenal vývojář, ale každý řádek zaznamená, kdo to řekl. |
| `isolated` | ano | ano | striktní oddělení. Architekt nikdy nevidí pozorování / paměti / sessions vývojáře. |
Co se značí, když je `AGENT_ID` nastaveno: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Role prochází od `api::session::start` → `mem::observe` → `mem::compress` → KV.
Co se filtruje v izolovaném režimu: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Každý endpoint přijímá `?agentId=` pro přepsání na úrovni jednotlivého požadavku a `?agentId=*` pro úplné odhlášení z rozsahu dle env. `/memories` také přijímá `?includeOrphans=true`, aby se zobrazily paměti z doby před AGENT_ID, jejichž `agentId` je nedefinované.
Přepsání na úrovni jednotlivého volání ve vrstvě SDK / REST: každý měnící endpoint (`/session/start`, `/remember`) přijímá pole `agentId` v těle požadavku, které má přednost před env. Užitečné pro runtime, které směrují mnoho rolí přes jeden proces serveru. Nástroj MCP `memory_save` zpřístupňuje stejné pole `agentId`, samostatný stdio server předává jak `agentId`, tak `project`, a uložené paměti nesou `agentId` do vyhledávacího indexu, takže vyhledávání v rozsahu agenta pokrývá jak paměti, tak pozorování.
Když `AGENT_ID` není nastaveno, paměť zůstává bez rozsahu (starší chování, žádné značky, žádné filtry).
### Porty
| Port | Účel | Proměnná prostředí |
|---|---|---|
| `3111` | REST API, MCP HTTP a živé události vieweru | `III_REST_PORT` |
| `3113` | Rozhraní vieweru | `III_VIEWER_PORT` |
`--port ` nastaví REST port a výchozí port vieweru na `N+2`. `--instance N` vytvoří samostatné prostředí. Interní porty musí zůstat privátní; před vzdáleným zpřístupněním si přečtěte [průvodce nasazením](../deploy/README.md).
### Úložiště: soubor nebo Redis
Výchozí souborové úložiště nepotřebuje samostatnou databázi. Redis je volitelný přes `AGENTMEMORY_STATE_BACKEND=redis` a `AGENTMEMORY_REDIS_URL`. Změna backendu nepřenese existující paměť. Nastavení persistence, omezení Redis a autentizovaný export/import jsou v [průvodci úložištěm](../docs/reliability/state-storage.md).
### Konfigurační soubor
Dejte runtime konfiguraci agentmemory do `~/.agentmemory/.env`, místo exportování proměnných v každém shellu. Pokud viewer zobrazí instalační nápovědu jako `export ANTHROPIC_API_KEY=...`, zkopírujte ji do tohoto souboru jako `ANTHROPIC_API_KEY=...` bez prefixu `export`, pak agentmemory restartujte. Pro výběr jiného souboru env nastavte `AGENTMEMORY_ENV_FILE`.
Proměnné prostředí procesu mají přednost před souborem. Po změně konfigurace server restartujte.
Na Windows žije stejný soubor na `%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
Pro test s předplatným Claude Code Pro/Max místo API klíče se přihlaste explicitně:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
Komprese pozorování psaná LLM vyžaduje obě řádky: přístup k poskytovateli LLM (včetně tohoto explicitního záložního řešení přes předplatné) a `AGENTMEMORY_AUTO_COMPRESS=true`. Samotný poskytovatel nechá na místě výchozí syntetickou cestu komprese.
Konsolidace (uzly grafu, lessons, crystals) je ve výchozím stavu zapnutá, kdykoli je nakonfigurován poskytovatel LLM. Explicitně se z ní odhlaste pomocí `CONSOLIDATION_ENABLED=false`, pokud chcete provoz bez LLM. Extrakce grafu je samostatný příznak:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Proměnné prostředí
Běžné volby pro `~/.agentmemory/.env`. Vkládání kontextu a komprese jsou volitelné; komprese navíc vyžaduje poskytovatele. Režim `core` omezuje viditelné nástroje MCP:
```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
```
Úplný přehled je v [`.env.example`](../.env.example): přihlašovací údaje poskytovatelů, filtry zachycení, retence, úložiště, týmové scope a volitelné funkce. `AGENTMEMORY_ENV_FILE` vybere jiný soubor. Vyplněný `.env` ani bearer secret nikdy necommitujte.
---
147 endpointů na portu `3111`. REST API se ve výchozím stavu váže na `127.0.0.1`. Chráněné endpointy vyžadují `Authorization: Bearer `, a endpointy pro mesh sync vyžadují explicitně nastavené `AGENTMEMORY_SECRET` na obou stranách.
**Autentizace je ve výchozím stavu zapnutá.** Pokud `AGENTMEMORY_SECRET` není nastaveno, CLI při prvním spuštění vygeneruje náhodný secret v `~/.agentmemory/secret` s oprávněním `0600` a zkopíruje jej také do vybraného datového adresáře. Všichni zabalení klienti jej načítají odtud při komunikaci s lokálním serverem: CLI, viewer, hooks v `plugin/scripts`, server MCP a shim `@agentmemory/mcp`, konfigurace zapsané pomocí `agentmemory connect` a zabalené integrace OpenCode, Pi, OpenClaw, Hermes a filesystem-watcher. Uložený secret se odesílá pouze na loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Výslovně nastavená `AGENTMEMORY_SECRET` má vždy přednost a vzdálení klienti ji musí mít ve svém prostředí. Self-host nasazení Dockeru z repozitáře a entrypointy `deploy/` generují a exportují vlastní secret. Pro ruční volání API:
```bash
curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health
```
**Pravidla požadavků pro zápisy.** Požadavky `POST`, `PUT`, `PATCH` a `DELETE` na REST API a viewer musí poslat `Content-Type: application/json` (parametr `charset` je v pořádku), kdykoli nesou tělo, a hlavička `Origin`, pokud je přítomná, musí být loopback origin pro nakonfigurovaný port REST nebo vieweru, nebo musí být uvedena v `VIEWER_ALLOWED_ORIGINS` (odděleno čárkami, např. `https://memory.example.com`). Klienty, které žádnou hlavičku `Origin` neposílají (CLI, hooks, MCP, curl, server-server), se to nijak nedotýká. Viewer navíc akceptuje svůj vlastní origin.
**Cesty k souborům.** Endpointy, které čtou nebo zapisují soubory (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), přijímají jen cesty pod `~/.agentmemory`, adresářem dat instance, nebo adresářem uvedeným v `AGENTMEMORY_IMPORT_ROOT` (víc jich oddělte pomocí `:`, na Windows pomocí `;`). `/replay/import-jsonl` navíc přijímá svou výchozí `~/.claude/projects`. `/obsidian/export` zůstává uvnitř `AGENTMEMORY_EXPORT_ROOT` a `/migrate` uvnitř `~/.agentmemory`. Symlinky se vyřeší před každou kontrolou.
**Odstraňování secrets.** API klíče, bearer tokeny, bloky privátních klíčů PEM a přihlašovací údaje vložené v URL (`scheme://user:password@host`) se před uložením textu odstraní, na každé cestě zápisu: pozorování, remember, evolve, slots, lessons, actions, sketches, signály, checkpoints, importy, jsonl replay, mesh sync, sdílení s týmem, výstup komprese a shrnutí, crystals a uzly grafu.
Klíčové endpointy
| Metoda | Cesta | Popis |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | kontrola zdraví (vždy veřejná) |
| `GET` | `/agentmemory/status` | co je špatně a jak to opravit (HTML pro prohlížeče, jinak JSON) |
| `GET` | `/agentmemory/viewer/snapshot` | vše, co viewer zobrazuje, v jedné odpovědi |
| `POST` | `/agentmemory/session/start` | spustí session + vrátí kontext |
| `POST` | `/agentmemory/session/end` | ukončí session |
| `POST` | `/agentmemory/observe` | zachytí pozorování (viz doručení zachycení níže) |
| `GET` | `/agentmemory/capture` | inbox zachycení, dead letters a offline spool |
| `POST` | `/agentmemory/capture/retry` | zopakuje zachycení v dead letters |
| `POST` | `/agentmemory/capture/drain` | hned odešle lokální offline spool |
| `POST` | `/agentmemory/smart-search` | hybridní vyhledávání |
| `POST` | `/agentmemory/context` | vygeneruje kontext |
| `POST` | `/agentmemory/remember` | uloží do dlouhodobé paměti |
| `POST` | `/agentmemory/forget` | smaže pozorování |
| `POST` | `/agentmemory/enrich` | kontext souboru + paměti + bugy |
| `GET` | `/agentmemory/profile` | profil projektu |
| `GET` | `/agentmemory/export` | exportuje všechna data |
| `POST` | `/agentmemory/import` | import z JSON |
| `POST` | `/agentmemory/graph/query` | dotaz na znalostní graf |
| `POST` | `/agentmemory/graph/compact` | zmenší nadměrnou provenienci grafu |
| `POST` | `/agentmemory/team/share` | sdílí s týmem |
| `GET` | `/agentmemory/audit` | audit trail |
Úplný seznam endpointů: [Generovaný přehled REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Doručení zachycení.** Hooks poslají každé pozorování jednou na `POST /agentmemory/observe` s `eventId`. Je to vlastní id hostitele pro to volání, pokud ho payload má (například `tool_use_id` z Claude Code), jinak hash session, typu hooku, názvu nástroje, vstupu, výstupu a timestampu hostitele. Server zapíše událost do inboxu zachycení ve state store, uloží pozorování, pak odstraní položku z inboxu. Status kód říká, co se stalo:
| Status | pole `status` | Význam |
|---|---|---|
| `201` | `accepted` | uloženo. `observationId` je nové pozorování. |
| `202` | `accepted` (`state: "retrying"`) | přijato, ale uložení selhalo. Server to zopakuje, i po restartu. |
| `200` | `duplicate` | toto `eventId` už bylo přijato. `observationId` je existující pozorování; nic nového se neuloží. |
| `400` / `422` | `rejected` | neplatný payload, nebo uložení definitivně selhalo (událost se uchová jako dead letter). |
| `503` | `rejected` (`retryable: true`) | inbox je plný (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks událost uloží do spoolu a pošlou později. |
Neúspěšné události se opakují každých `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) se zdvojnásobujícím se zpomalením, až do `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Události, které stále selhávají, zůstávají v inboxu jako dead letters, jsou uvedeny na `/agentmemory/status` a na stránce Health vieweru, a lze je zopakovat pomocí `POST /agentmemory/capture/retry` (`{"eventId": "..."}` nebo `{"all": true}`). Přijatá id událostí se pamatují po `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 hodin, nejvýš `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), takže hook přehraný po timeoutu nebo restartu se uloží jednou, zatímco dvě samostatná volání nástroje s vlastními id hostitele se uloží dvakrát, i když je jejich obsah identický. Když je pozorování smazáno (forget, smazání session, eviction, auto-forget nebo import, který nahrazuje úložiště), jeho událost se označí jako smazaná ještě před odstraněním pozorování, takže přehrání této události ve stejném okně se zodpoví jako duplikát a nic se neuloží. State store zapisuje na disk každé 2 sekundy, takže zodpovězená událost může ještě chvíli existovat jen v paměti. Aby to bylo ošetřeno, každá odpověď `2xx` nese i `bootId` serveru (nové při každém startu), `acceptedAt` a `durableAfterMs` (interval ukládání plus 1,5 s na souborovém úložišti, 1,5 s na redis, kde je trvalost na nastavení operátora). Hooks uchovávají událost v lokálním spoolu, dokud toto okno neuplyne, a smažou ji při pozdějším volání bez dalšího požadavku. Pokud se `bootId` do té doby změnil, server se restartoval, takže hook pošle událost znovu se stejným `eventId`; událost, která se na disk dostala, se neuloží dvakrát. Server takové události posílá i sám při startu a při každém intervalu opakování, takže restart nic neztratí, i když potom žádný hook neběží. Starší hooks ignorují extra pole a nové hooks proti staršímu serveru zahodí událost na `2xx` jako dřív.
Když je server mimo provoz, neodpoví včas nebo vrátí 5xx, hook připojí pozorování do lokálního souboru spoolu, `/capture-spool/-.jsonl` (adresář přepište pomocí `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Soubor je privátní pro vašeho uživatele (režim 600), secrets jsou odstraněny stejně jako je odstraňuje server, pojme nejvýš `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) a zahazuje záznamy starší než `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Když je plný, nové záznamy se zahodí a započítají, a `/agentmemory/status` to nahlásí. Hook stále skončí s kódem 0 ve svém časovém limitu a nepřidá žádný požadavek, když je server zdravý. Spool se odešle při dalším startu a prvním hookem, který se znovu dostane k serveru, v procesu na pozadí, aby agent nečekal. Id událostí to dělají bezpečným: pozorování, které dorazilo před timeoutem, se neuloží dvakrát. `npx @agentmemory/agentmemory capture` zobrazí spool i inbox serveru, `--drain` hned odešle spool a `GET /agentmemory/capture` vrátí totéž jako JSON. Nastavte `AGENTMEMORY_CAPTURE_SPOOL=false`, abyste spool vypnuli.
**Komprimace provenience grafu.** Komprimace starší provenience se při spuštění odkládá, protože načítá celé starší rozsahy. `/agentmemory/status` hlásí `deferred`, nebo `off` při `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Níže uvedenou ruční komprimaci spusťte během údržby. Migrace vyhledávacího indexu je samostatná: použijte `agentmemory graph-index migrate --allow-legacy-scan` podle [průvodce údržbou](../docs/reliability/graph-index-migration.md).
Pro manuální spuštění zavolejte `POST /agentmemory/graph/compact`. Prochází indexy názvů a klíčů hran místo výpisu každého uzlu a hrany, a je bezpečné ho spustit znovu. Když zmenší id, zapíše audit záznam `graph_compact`.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}'
```
Na velkém úložišti, nebo když volání vrátí 504, spusťte ho po dávkách. Pošlete `scope` (`nodes`, `edges` nebo `history`), `offset` a `limit`, pak volejte znovu s vráceným `nextOffset`, dokud není `null`. Udělejte to pro `nodes`, `edges` a `history`, a zakončete jedním voláním `{"scope":"snapshot"}`, protože dávkový běh se cachovaného snapshotu nedotýká.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 5,000+ tests
npm run test:integration # API tests (requires running services)
```
Požadavky jsou v sekci [Instalace](#install). Pravidla přispívání a kontroly vydání najdete v [CONTRIBUTING.md](../CONTRIBUTING.md).