Trwała pamięć między sesjami i agentami kodującymi.
Trwała pamięć dla Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode i każdego klienta MCP.
---
AgentMemory zapisuje obsługiwane zdarzenia sesji i pozwala wyszukiwać decyzje, poprawki oraz wnioski między agentami. Podgląd umożliwia przeglądanie, edytowanie, eksportowanie i usuwanie wspomnień. Wyszukiwanie słów kluczowych działa bez klucza API; embeddingi dodają wyszukiwanie semantyczne.
## Install
Wymagania:
- Node.js 20 lub nowszy wraz z npm i npx (`node -v`, `npm -v` i `npx -v`).
- macOS/Linux wymagają też `curl`, powłoki POSIX `sh` i `tar` do automatycznej konfiguracji środowiska.
- W Windows użyj WSL2 lub [instrukcji natywnej instalacji](#windows).
Kanoniczna komenda do świeżej instalacji:
```bash
npx -y @agentmemory/agentmemory@latest
```
Wybierz agentów oraz dostawcę lub tryb bez klucza. Konfigurator zapisuje ustawienia, uruchamia serwer pamięci i proponuje globalną instalację komendy `agentmemory`. `-y` akceptuje monit npm, a `@latest` wybiera bieżące wydanie. Kompresja przez LLM wymaga dostawcy i `AGENTMEMORY_AUTO_COMPRESS=true`.
Tryb bez klucza wyłącza wektorowe embeddingi. `memory_recall` (ścieżka `mem::search`) korzysta z BM25, natomiast `memory_smart_search` może dodatkowo łączyć strukturalne dopasowania z grafu, jeśli dane grafu już istnieją. Aby bezpłatnie włączyć semantyczne przywołanie lokalnie na urządzeniu, ustaw `EMBEDDING_PROVIDER=local` w `~/.agentmemory/.env` i zrestartuj. Pierwsze żądanie embeddingu pobiera `Xenova/all-MiniLM-L6-v2`; po tym początkowym pobraniu modelu wnioskowanie działa już lokalnie.
API działa pod `http://localhost:3111`, a podgląd pod `http://localhost:3113`. Domyślnie oba nasłuchują tylko lokalnie. Konfiguracja jest w `~/.agentmemory/.env`; [przechowywanie danych](#data-storage) opisuje lokalizacje pamięci i osobne instancje.
Następnie udowodnij, że przywołanie działa, i daj swojemu agentowi jego skille:
```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
```
Wyszukiwania po słowach kluczowych powinny trafiać w domyślnym trybie bez klucza za pomocą BM25. Zapytanie demo `database performance optimization` jest celowo semantyczne i może zwrócić zero wyników, dopóki nie skonfigurujesz dostawcy embeddingów.
Chcesz, aby całą robotę wykonał agent kodujący? Podaj mu jedną instrukcję:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Podłącz kolejnego agenta przez `agentmemory connect `. Zobacz [integracje](#works-with-every-agent) i [codzienne komendy](#everyday-commands).
Instalacja globalna / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
Powyższa komenda npx pozostaje kanoniczną ścieżką świeżej instalacji i pozwala uniknąć problemów z uprawnieniami do globalnego prefiksu.
npx serwuje starą wersję
npx buforuje dane w podziale na wersje. Wymuś najnowszą wersję za pomocą `npx -y @agentmemory/agentmemory@latest` albo wyczyść pamięć podręczną jednorazowo komendą `rm -rf ~/.npm/_npx` (macOS/Linux; na Windows usuń `%LOCALAPPDATA%\npm-cache\_npx`).
---
agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST API. Wszyscy agenci współdzielą ten sam serwer pamięci.
Claude Code plugin natywny + 12 hooków + MCP
Codex CLI plugin natywny + 6 hooków + MCP
GitHub Copilot CLI MCP + hooki/skille pluginu
Cursor plugin natywny + hooki cyklu życia + MCP
OpenCode plugin przechwytujący + MCP
Devin 6 hooków + skille + MCP
OpenClaw plugin natywny + MCP
Hermes plugin natywny + MCP
pi natywne przywoływanie + przechwytywanie + skille
OpenHuman natywny backend oparty na trait Memory
Gemini CLI serwer MCP
Antigravity MCP + hooki
Claude Desktop serwer MCP
Warp connect + MCP + skille
Zed serwer MCP
Cline serwer MCP
Continue serwer MCP
Droid serwer MCP
Kiro serwer MCP
Qwen Code serwer MCP
DeepSeek Harness natywne przechwytywanie + MCP
Roo Code serwer MCP
Kilo Code serwer MCP
Goose serwer MCP
Aider REST API
Oh My Pi natywne przywoływanie + przechwytywanie + skille + opcjonalne MCP
Współpracuje z każdym agentem mówiącym w MCP lub HTTP. Jeden serwer, wspomnienia współdzielone między wszystkimi.
---
### Przechowywanie danych
Wspomnienia domyślnie trafiają poza repozytorium:
| Platforma | Katalog danych |
|---|---|
| macOS | `~/Library/Application Support/agentmemory` |
| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
| Windows | `%APPDATA%\agentmemory` |
Instancja 0 wykorzystuje istniejący `./data/state_store.db`. Wybierz inny katalog przez `--data-dir ` lub `AGENTMEMORY_DATA_DIR`. Przy restarcie i aktualizacji zachowaj ten sam katalog.
```bash
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
```
`--instance 1` używa podkatalogu `instance-1`, portu API `3211` i podglądu `3213`. Redis i migrację opisuje [przewodnik przechowywania i kopii zapasowych](../docs/reliability/state-storage.md).
Najnowsze informacje o wydaniach: [CHANGELOG.md](../CHANGELOG.md).
---
Aktualne wyniki wyszukiwania, definicje metryk i kroki odtworzenia testu:
[0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md).
---
Aktualne porównanie produktów i opcji wdrożenia wraz ze źródłami:
[AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28.
---
### Wypróbuj w 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` tworzy 3 realistyczne sesje (autoryzacja JWT, naprawa zapytania N+1, rate limiting) i wykonuje na nich wyszukiwania. Instalacje bez klucza wyłączają wektory, więc zapytania słowno-kluczowe `mem::search` powinny trafiać przez BM25, podczas gdy `database performance optimization` może zwrócić zero wyników. `smart-search` może dodatkowo zwracać strukturalne dopasowania z grafu, jeśli dane grafu istnieją. Aby zapytanie semantyczne znalazło naprawę N+1 za pomocą wektorów, ustaw `EMBEDDING_PROVIDER=local`, zrestartuj i pozwól, aby pierwsze pobranie modelu się zakończyło.
Otwórz `http://localhost:3113`, aby na żywo obserwować budowanie pamięci.
### Zweryfikuj świeżą instalację i trwałość po restarcie
Gdy serwer działa, sprawdź stan i podgląd:
```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` pokazuje stan serwera, dostawców, tryb embeddingów, dostarczanie obserwacji i odzyskiwanie. Chronione żądania REST wymagają sekretu serwera. Użyj własnego `AGENTMEMORY_SECRET`, jeśli jest ustawiony; w przeciwnym razie odczytaj wygenerowany lokalny sekret:
```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}'
```
Następnie uruchom `npx -y @agentmemory/agentmemory@latest stop`, ponownie uruchom kanoniczną komendę w Terminalu 1, zaczekaj na `/agentmemory/livez` i powtórz wyszukiwanie. Sonda musi wciąż zostać zwrócona. Jeśli wybrałeś własny `--data-dir`, podaj ten sam katalog przy restarcie.
### Codzienne komendy
Instalacja i konfiguracja są opisane w sekcji [Install](#install) powyżej (pierwsze uruchomienie przeprowadzi cię przez ten proces). Na co dzień:
```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 sesji
Każdą sesję zapisaną przez agentmemory można odtworzyć. Otwórz podgląd, wybierz zakładkę **Replay** i przewijaj osię czasu: prompty, wywołania narzędzi, wyniki narzędzi i odpowiedzi renderują się jako osobne zdarzenia z odtwarzaniem/pauzą, kontrolą prędkości (0.5x do 4x) i skrótami klawiszowymi (spacja do przełączania, strzałki do kroku po kroku).
Aby zaimportować starsze transkrypty JSONL 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
```
Importowane sesje pojawiają się w Replay obok natywnych. Transkrypty są indeksowane i oznaczane kanałem `import`; przetwarzanie sesji może też tworzyć kryształy i lekcje.
> **Uwaga, jeśli `import-jsonl` jest twoją główną ścieżką przechwytywania:** `cleanupPeriodDays` w Claude Code (w `~/.claude/settings.json`, domyślnie **30**) automatycznie usuwa transkrypty JSONL starsze niż to okno z `~/.claude/projects/`. Jeśli instalujesz agentmemory od zera na historii Claude Code mającej kilka miesięcy, wszystko starsze niż 30 dni jest już usunięte przed pierwszym importem. Albo uruchamiaj `import-jsonl` w cronie, albo zwiększ `cleanupPeriodDays`, albo podłącz hooki automatycznego przechwytywania (domyślna ścieżka instalacji pluginu), aby każda tura trafiała do agentmemory, gdy sesja jest jeszcze aktywna, dzięki czemu czyszczenie JSONL przestaje mieć znaczenie.
### Aktualizacja / utrzymanie
Użyj komendy utrzymania, gdy chcesz celowo zaktualizować swoje lokalne środowisko wykonawcze:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Komenda aktualizuje lokalne środowisko i może zmienić zależności JavaScript w bieżącym katalogu roboczym. Zrób kopię danych i przeczytaj [przewodnik aktualizacji](../docs/upgrades/iii-0.25.md).
### Claude Code (jeden blok, wklej go)
```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 instalacji pluginu (ścieżka samodzielnego MCP)
Jeśli podłączasz serwer MCP agentmemory bezpośrednio przez `~/.claude.json` (domyślna ścieżka) zamiast używać `/plugin install`, Claude Code nigdy nie rozwiąże `${CLAUDE_PLUGIN_ROOT}` i musisz wskazać skryptom hooków bezwzględne ścieżki w `~/.claude/settings.json` (domyślna ścieżka). Te ścieżki zwykle zawierają w sobie wersję agentmemory (np. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), więc kolejna aktualizacja po cichu psuje każdy hook.
Rozwiązanie zastępcze:
```bash
agentmemory connect claude-code --with-hooks
```
Ta komenda konfiguruje serwer MCP i scala dołączone hooki z konfiguracją użytkownika Claude Code. Jeśli `CLAUDE_CONFIG_DIR` nie jest ustawiona, jest pusta lub zawiera tylko białe znaki, używa `~/.claude.json` dla MCP i `~/.claude/settings.json` dla hooków. Pozostałe wartości katalogu są używane dokładnie w podanej postaci, łącznie z białymi znakami na początku i końcu. Aby użyć własnego katalogu, ustaw `CLAUDE_CONFIG_DIR` na tę samą niepustą wartość dla tej komendy i Claude Code; pliki będą wtedy miały ścieżki odpowiednio `$CLAUDE_CONFIG_DIR/.claude.json` i `$CLAUDE_CONFIG_DIR/settings.json`. Claude Code musi otrzymać tę wartość w swoim środowisku uruchomieniowym, nawet jeśli konektor odczytuje ją z pliku `.env` AgentMemory. Utwórz własny katalog przed uruchomieniem tej komendy; w przeciwnym razie konektor pominie Claude Code jako niewykryty. Jeśli wartość w powłoce zawiera tylko białe znaki, usuń `CLAUDE_CONFIG_DIR` ze środowiska przed uruchomieniem Claude Code, aby również używał profilu domyślnego. Użyj ścieżki bezwzględnej. Ścieżki względne są rozwiązywane względem katalogu roboczego, więc oba polecenia muszą być uruchamiane z tego samego katalogu.
Komendy hooków używają bezwzględnych ścieżek do katalogu `plugin/` dołączonego do zainstalowanego pakietu. Po aktualizacji agentmemory uruchom komendę ponownie, aby odświeżyć te ścieżki. Wpisy użytkownika w plikach konfiguracyjnych są zachowywane; zastępowane są tylko poprzednie wpisy agentmemory. Zalecanym sposobem pozostaje użycie `/plugin install`.
Dla zdalnych lub chronionych wdrożeń uruchom Claude Code z ustawionymi `AGENTMEMORY_URL` i `AGENTMEMORY_SECRET`. Plugin przekazuje obie wartości dalej do swojego dołączonego serwera MCP; gdy `AGENTMEMORY_URL` jest puste, shim MCP używa `http://localhost:3111`.
### Codex CLI (platforma pluginów Codex)
```bash
# 1. start the memory server in a separate terminal
npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```
Plugin Codex jest dostarczany z tego samego katalogu `plugin/` co plugin Claude Code. Rejestruje:
- Dołączony mostek stdio MCP do działającego daemona, bez pobierania z npm i bez magazynu fallback. Zobacz [lokalny przewodnik po Codex](../docs/plugins/codex-local.md), aby przetestować niewydany build.
- 6 hooków cyklu życia: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 wywoływalnych skilli: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 skilli referencyjnych wczytywanych przez agenta na żądanie (dyscyplina pamięci, narzędzia MCP, REST API, konfiguracja, agenci, hooki, architektura oraz przewodnik tworzenia skilli)
Silnik hooków Codex wstrzykuje `CLAUDE_PLUGIN_ROOT` do podprocesów hooków (zgodnie z [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), dzięki czemu te same skrypty hooków działają w obu hostach bez duplikacji. Zdarzenia Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure są dostępne tylko w Claude Code i nie są rejestrowane dla Codex.
#### Hooki Codex: zaufanie i kompatybilność
Natywne wywoływanie hooków pluginu jest zweryfikowane w Codex CLI 0.150.1. Zaufaj hookom pluginu, zanim oczekujesz przechwytywania. Zachowanie Codex Desktop zależy od dołączonego runtime; sprawdź `/hooks` i potwierdź przechwycone zdarzenie, zanim włączysz rozwiązanie zastępcze.
Jeśli twój host wymaga globalnych hooków, zduplikuj komendy do globalnego `~/.codex/hooks.json`. Gdy MCP jest już podłączone, aktualny adapter `connect` potrzebuje `--force`, aby dotrzeć do instalacji hooków:
```bash
agentmemory connect codex --with-hooks --force
```
To scala globalne hooki i przepisuje wpis MCP agentmemory, zachowując niepowiązane wpisy. Sprawdź własne ustawienia endpointu agentmemory przed użyciem `--force`. Uruchom ponownie po aktualizacji, aby odświeżyć ścieżki skryptów. Włącz albo natywne hooki pluginu, albo globalne kopie, aby uniknąć podwójnego przechwytywania.
### GitHub Copilot CLI
Dla trybu agenta VS Code użyj [przewodnika MCP i auto-przechwytywania Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Konektor CLI nie konfiguruje 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` scala `mcpServers.agentmemory` do `~/.copilot/mcp-config.json` (lub `$COPILOT_HOME/mcp-config.json`, gdy ustawiono `COPILOT_HOME`) i zachowuje istniejące serwery. Na natywnym Windows jest to jedyny zautomatyzowany adapter `connect`; każdego innego natywnego agenta Windows skonfiguruj ręcznie. `connect` w WSL jest wspierane tylko wtedy, gdy docelowy agent jest zainstalowany w tym samym środowisku WSL. Copilot podchwytuje serwer MCP przy następnym uruchomieniu lub po `/mcp`. Zainstaluj też plugin, jeśli chcesz pełne doświadczenie hooków/skilli.
### Cursor
```bash
agentmemory connect cursor
```
Następnie w **Settings → Plugins → Add marketplace** wybierz katalog agentmemory zawierający `.cursor-plugin/plugin.json`, włącz plugin **agentmemory** i przeładuj okno. Plugin udostępnia przechwytywanie cyklu życia, przypisanie projektu na podstawie workspace, skille i MCP. Włącz hooki pluginu albo ręczne hooki w `~/.cursor/hooks.json`, aby uniknąć podwójnego zapisu.
[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
```
Wybierz komendę dla swojego hosta. Pi i OMP instalują natywne przywoływanie, przechwytywanie, odtwarzanie offline i skille; `--with-mcp` dodaje pełny zestaw narzędzi. W Pi uruchom `/reload`, OMP zrestartuj, a potem sprawdź `/agentmemory-status`. DSH instaluje MCP i dołączony plugin przechwytujący; po podłączeniu zrestartuj DSH.
Pi obsługuje też instalowalny pakiet `@agentmemory/pi`. Instalację lokalną i dostępność npm opisuje [przewodnik Pi](../integrations/pi/). Używaj jednej metody instalacji na hosta.
[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (wklej ten 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`.
```
Pełny przewodnik: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (wklej ten 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.
```
Pełny przewodnik: [`integrations/hermes/`](../integrations/hermes/)
### Inni agenci
Uruchom serwer pamięci: `npx -y @agentmemory/agentmemory@latest`
#### Natywne skille przez `npx skills add`
agentmemory dostarcza 17 skilli w formacie `/SKILL.md` w stylu Claude Code: 9 wywoływalnych skilli akcji (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) oraz 8 skilli referencyjnych wczytywanych przez agenta na żądanie (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Skille referencyjne zawierają tabele danych generowane ze źródła, więc nigdy się nie rozjeżdżają. CLI [`skills`](https://npmjs.com/package/skills) od vercel-labs automatycznie instaluje je w natywnym katalogu skilli wywołującego agenta, obejmując ponad 50 agentów (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf i inne):
```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
```
Jest to **uzupełnienie** dla `agentmemory connect `:
- `agentmemory connect ` zwykle zapisuje konfigurację MCP. Hermes, OpenClaw, Pi i Oh My Pi domyślnie instalują natywną integrację i skille; MCP włącza `--with-mcp`.
- `npx skills add rohitg00/agentmemory` instaluje skille dla agentów bez dołączonych natywnych skilli. Pomiń ten krok dla Hermes, OpenClaw, Pi i Oh My Pi; ich konektory już instalują skille.
Dla tej niewielkiej liczby agentów, których CLI `skills` jeszcze nie obsługuje (Zed v1.3.x i starsze), umieść 17 plików SKILL.md w natywnym katalogu skilli agenta samodzielnie; ten sam format działa wszędzie.
#### Standardowy blok MCP
Wpis agentmemory to **ten sam blok serwera MCP** we wszystkich hostach, które używają struktury `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}"
}
}
```
**Scal ten wpis z istniejącym obiektem `mcpServers`** w pliku konfiguracyjnym hosta; nie zastępuj całego pliku. Jeśli plik już ma inne serwery, dodaj `agentmemory` obok nich jako kolejny klucz wewnątrz `mcpServers`. Jeśli `mcpServers` całkowicie nie istnieje, wklej ten blok wewnątrz `{ "mcpServers": { ... } }`. Placeholdery `${VAR}` dziedziczą `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` z shella w momencie uruchamiania serwera MCP; nieustawione zmienne przekazują puste ciągi i shim wraca do `http://localhost:3111`. Jeden podłączony wpis obsługuje zarówno wdrożenia lokalne, jak i zdalne (k8s / za reverse-proxy).
| Agent | Plik konfiguracyjny | Uwagi |
|---|---|---|
| **Cursor (tylko MCP)** | `~/.cursor/mcp.json` | Scal z `mcpServers`, albo użyj `agentmemory connect cursor`. Na stronie dostępny jest też deeplink jednym kliknięciem. |
| **Cursor (pełny plugin)** | `.cursor-plugin/` | Plugin zapewnia hooki cyklu życia, rozpoznawanie workspace, skille i MCP w Cursor IDE oraz `cursor-agent`. Zobacz [konfigurację Cursor](#cursor). |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Scal z `mcpServers`. Zrestartuj Claude Desktop po edycji. |
| **Cline / Roo Code / Kilo Code** | Ustawienia MCP w Cline (Settings UI → MCP Servers → Edit) | Ten sam blok `mcpServers`. |
| **Devin CLI (MCP + hooki)** | `~/.config/devin/config.json` | `agentmemory connect devin` scala wpis MCP; `--with-hooks` dodaje sześć natywnych hooków auto-przechwytywania (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) z pisanymi małymi literami matcherami narzędzi Devin. Zweryfikuj za pomocą `devin mcp list` oraz `/hooks` wewnątrz devin. |
| **Devin CLI (pełny plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` z checkoutu rejestruje wszystkie 17 skilli jako komendy ukośnikowe `/agentmemory:` oraz serwer MCP. Hooki pluginu Devin nie mogą wywołać `SessionStart`/`SessionEnd`, więc połącz to z `connect devin --with-hooks`, aby uzyskać pełne przechwytywanie sesji. |
| **Devin (cloud)** | Settings → Connections → MCP servers | Dodaj niestandardowy MCP (STDIO): komenda `npx`, argumenty `-y @agentmemory/mcp@latest`, zmienna środowiskowa `AGENTMEMORY_URL` wskazująca na wdrożenie agentmemory dostępne w sieci, plus `AGENTMEMORY_SECRET` (sesje w chmurze nie mają dostępu do localhost — zobacz [`deploy/`](../deploy/)). Zapisz sekret w Devin Secrets, a następnie użyj „Test listing tools”, aby zweryfikować, że pojawia się wszystkich 54 narzędzi. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (scala automatycznie). |
| **GitHub Copilot CLI (tylko MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` scala `mcpServers.agentmemory`; Copilot podchwytuje to przy następnym uruchomieniu lub po `/mcp`. |
| **GitHub Copilot CLI (pełny plugin)** | Instalacja pluginu Copilot | `copilot plugin install rohitg00/agentmemory:plugin`, aby zainstalować plugin z podkatalogu GitHub. |
| **OpenClaw** | Konfiguracja MCP OpenClaw | Ten sam blok `mcpServers`. Głębsza integracja: `openclaw plugins install ./integrations/openclaw` zajmuje slot pamięci OpenClaw (automatycznie przełącza z `memory-core`); ustaw `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, inaczej przechwytywanie tury jest po cichu blokowane. Zobacz [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (tylko MCP)** | `.codex/config.toml` | Struktura TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, albo dodaj `[mcp_servers.agentmemory]` ręcznie. |
| **Codex CLI (pełny plugin)** | Marketplace pluginów Codex | `codex plugin marketplace add rohitg00/agentmemory`, a następnie `codex plugin add agentmemory@agentmemory`. Rejestruje MCP + 6 hooków cyklu życia + 17 skilli. Zaufaj hookom i zweryfikuj przechwytywanie w swoim hoście; zobacz [Konfiguracja i walidacja Codex](../docs/plugins/codex-local.md). |
| **OpenCode (tylko MCP)** | `opencode.json` | Inna struktura: klucz `mcp` na najwyższym poziomie, komenda jako tablica: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (pełny plugin)** | `plugin/opencode/` | 22 hooki auto-przechwytywania obejmujące cykl życia sesji, wiadomości, narzędzia i błędy. Przypisanie do projektu jest per sesja, więc jeden proces OpenCode obejmujący kilka repozytoriów zapisuje każdą sesję pod jej własnym projektem. Dwie komendy ukośnikowe (`/recall`, `/remember`). Skopiuj `plugin/opencode/` do swojego workspace OpenCode i dodaj wpis pluginu do `opencode.json`. Zobacz [`plugin/opencode/README.md`](../plugin/opencode/README.md), aby zobaczyć pełną tabelę hooków i analizę braków. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. natywne przywoływanie + przechwytywanie + skille. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. natywne przywoływanie + przechwytywanie + skille. [Oh My Pi](../integrations/omp/). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` daje dostawcę pamięci z 6 hookami (prefetch, przechwytywanie tury, koniec sesji, pre-compress, odzwierciedlanie MEMORY.md, blok system prompt). Zweryfikuj za pomocą `hermes plugins doctor` i `hermes memory status`. Zobacz [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` zapisuje standardowy blok `mcpServers`. Payload hooków jest kompatybilny co do pól z Claude Code, więc istniejące skrypty 12 hooków działają bez modyfikacji; podłącz je przez sekcję `hooks` w tym samym `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instaluje MCP i hooki przechwytywania we współdzielonym katalogu personalizacji. Zobacz [Konfiguracja i ograniczenia Antigravity](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` używa tej samej konfiguracji MCP i hooków, jak aktualne wersje IDE. Istniejące instalacje powinny odświeżyć się za pomocą `--force`; zobacz [uwagi dotyczące aktualizacji](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` zapisuje konfigurację na poziomie użytkownika. Nadpisania na poziomie workspace idą do `.kiro/settings/mcp.json` obok twojego kodu. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` zapisuje standardowy blok `mcpServers`. Warp automatycznie wykrywa też skille z `.claude/skills/`; gdy zainstalowany jest plugin Claude Code, 9 skilli agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) pojawia się natywnie w palecie komend ukośnikowych Warp. |
| **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` zapisuje standardowy blok `mcpServers`. Użytkownicy rozszerzenia VS Code: wklej ten sam blok przez Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (preferowane) lub `config.json` (starsze) | `agentmemory connect continue` tworzy `config.yaml`, jeśli konfiguracji nie ma, lub modyfikuje istniejący `config.json`. Dla istniejącego YAML wypisuje blok do wklejenia pod `mcpServers:`, zachowując komentarze i kotwice. Continue używa tablicy, nie obiektu. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` zapisuje pod `context_servers` (klucz Zed, a NIE `mcpServers`). Zdalne serwery MCP można podłączyć zamiast tego przez `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` zapisuje standardowy blok `mcpServers`. Nadpisania w zakresie projektu idą do `/.factory/mcp.json`. Podaj `--with-hooks`, aby uzyskać natywne auto-przechwytywanie. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` włącza narzędzia MCP. Dodaj `--with-hooks`, aby załadować natywną wtyczkę rejestrowania dołączoną do AgentMemory. Osobny pakiet wtyczki nie jest potrzebny. [DSH](../docs/dsh.md). |
| **Goose** | Interfejs ustawień MCP w Goose | Ten sam blok `mcpServers`; użyj `goose configure` → Add Extension → MCP. Bezpośrednia edycja YAML w `~/.config/goose/config.yaml` jest wspierana, ale schemat używa `extensions:` + `cmd` (nie `mcpServers:` + `command`). |
| **Aider** | n/d | Do zapisu i wyszukiwania ze skryptów użyj [uwierzytelnionych przykładów REST](#validate-a-fresh-install-and-restart-persistence). |
| **Obsługiwani agenci** | Tylko skille | `npx skills add rohitg00/agentmemory`; wybierz skille do zainstalowania oraz docelowych agentów. |
**Klienci MCP w sandboksie** (Flatpak / Snap / restrykcyjne kontenery), które nie mają dostępu do `localhost` hosta: ustaw dodatkowo `"AGENTMEMORY_FORCE_PROXY": "1"` w bloku `env` i wskaż `AGENTMEMORY_URL` na trasę, do której sandbox faktycznie ma dostęp (np. twój adres IP w sieci LAN).
### Dostęp programistyczny (Python / Rust / Node)
Korzystaj z [REST API](#api) w dowolnym języku lub z [narzędzi MCP](#mcp-server) w agencie. REST używa JSON i uwierzytelniania bearer; zobacz [przykład zapisu i wyszukiwania](#validate-a-fresh-install-and-restart-persistence). Bezpośrednią integrację środowiska pokazują [przykłady Python](../examples/python/).
### Ze źródeł
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
`npm start` uruchamia ten sam lokalny serwer co zainstalowane CLI. Wymagania są w sekcji [Instalacja](#install); API i podgląd nasłuchują na `127.0.0.1`.
### Windows
agentmemory działa w Windows 10/11. WSL2 korzysta ze ścieżki linuksowej i może automatycznie zainstalować przypięty silnik. Natywny Windows wymaga ręcznie zainstalowanego przypiętego pliku binarnego iii-engine v0.25.1; pobierz pasujące archiwum ze [strony wydania iii 0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), zweryfikuj sumę kontrolną i umieść `iii.exe` w `PATH` (na przykład `%USERPROFILE%\.local\bin\iii.exe`). CLI nie wypakowuje automatycznie archiwum ZIP dla Windows.
Zautomatyzowane podłączanie MCP w natywnym Windows obsługuje tylko `agentmemory connect copilot-cli`. Dla pozostałych natywnych agentów Windows użyj ręcznego bloku MCP z sekcji [Inni agenci](#other-agents). Uruchamiaj `connect` w WSL tylko wtedy, gdy docelowy agent jest zainstalowany w tym samym środowisku WSL.
**Tylko samodzielny MCP (bez silnika).** Jeśli potrzebujesz wyłącznie narzędzi MCP, bez REST API, podglądu ani usług runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
```
Uruchom `agentmemory doctor` lub zrestartuj z `--verbose`. Gdy porty są zajęte, użyj `--port ` albo `--instance `. Zgodność i odzyskiwanie opisuje [przewodnik aktualizacji](../docs/upgrades/iii-0.25.md).
---
Wdrożenie
Własne wdrożenie uruchom przez Docker Compose lub poniższe szablony. Pamięć i dane uwierzytelniające są na wolumenie `/data`; wykonaj kopię i użyj go ponownie przy aktualizacji. Uwierzytelnianie, sieć, kopie i migrację opisuje [przewodnik wdrożenia](../deploy/README.md).
Przycisk jednoklikowego wdrożenia Render wymaga `render.yaml` w katalogu głównym repozytorium, który celowo zostawiamy czysty. Użyj przepływu Render Blueprint opisanego w [`deploy/render/`](.././deploy/render/README.md), aby ręcznie wskazać blueprint znajdujący się w repozytorium.
Pełne szczegóły konfiguracji (przechwytywanie HMAC, tunel SSH do podglądu, rotacja, backup,
minimalne koszty) znajdują się w [`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): pojedyncza maszyna z
`auto_stop_machines = "stop"`; najtańsza opcja w stanie bezczynności.
- [`deploy/railway`](.././deploy/railway/README.md): stała opłata w planie Hobby,
wolumin w panelu.
- [`deploy/render`](.././deploy/render/README.md): przepływ Blueprint,
automatyczne migawki dysku w planach płatnych.
- [`deploy/coolify`](.././deploy/coolify/README.md): hostowane samodzielnie na
własnym VPS za pomocą [Coolify](https://coolify.io/self-hosted); ten sam
stos Docker Compose, host i dane należą do ciebie.
REST używa `3111`, a podgląd `3113`. Zachowaj je w sieci prywatnej lub zabezpiecz uwierzytelnianiem i TLS. Ustawienia platform i [migrację starszego Dockera](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) opisuje przewodnik wdrożenia.
---
Wiedza o projekcie rozprasza się między rozmowami i plikami instrukcji. AgentMemory pozwala wyszukiwać wcześniejsze decyzje, poprawki i lekcje w aktualnie używanym agencie.
### agentmemory kontra wbudowana pamięć agenta
Każdy kodujący agent AI ma wbudowaną pamięć: Claude Code ma `MEMORY.md`, Cursor ma notepady, Cline ma memory bank. Działają jak karteczki samoprzylepne. agentmemory to przeszukiwalna baza danych stojąca za tymi karteczkami.
| | Wbudowana (CLAUDE.md) | agentmemory |
|---|---|---|
| Utrzymanie | Ręcznie zarządzane instrukcje | Indeksowana historia sesji i wspomnienia |
| Wyszukiwanie | Wczytuje wszystko do kontekstu | BM25 + wektor + graf (tylko top-K) |
| Między agentami | Pliki per agent | MCP + REST (każdy agent) |
| Koordynacja | Brak | Leasy, sygnały, akcje, rutyny |
| Obserwowalność | Ręczne czytanie plików | Podgląd w czasie rzeczywistym na :3113 |
---
### Potok pamięci
```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-poziomowa konsolidacja pamięci
Wzorowane na tym, jak ludzki mózg przetwarza pamięć, włącznie z konsolidacją podczas snu.
| Poziom | Co | Analogia |
|------|------|---------|
| **Working (robocza)** | Surowe obserwacje z użycia narzędzi | Pamięć krótkotrwała |
| **Episodic (epizodyczna)** | Skompresowane podsumowania sesji | „Co się wydarzyło” |
| **Semantic (semantyczna)** | Wyodrębnione fakty i wzorce | „Co wiem” |
| **Procedural (proceduralna)** | Przepływy pracy i wzorce decyzyjne | „Jak to zrobić” |
Wspomnienia zanikają z czasem (krzywa Ebbinghausa). Często używane wspomnienia wzmacniają się. Nieaktualne wspomnienia są automatycznie usuwane. Sprzeczności są wykrywane i rozwiązywane.
### Co jest przechwytywane
Tabela opisuje hooki Claude Code. Pozostałe integracje przechwytują zdarzenia udostępniane przez hosta. Automatyczne wstrzykiwanie kontekstu przez wspólne hooki jest opcjonalne: `AGENTMEMORY_INJECT_CONTEXT=true`.
| Hook | Przechwytuje |
|------|----------|
| `SessionStart` | Ścieżkę projektu, ID sesji |
| `UserPromptSubmit` | Prompty użytkownika (filtrowane pod kątem prywatności) |
| `PreToolUse` | Wzorce dostępu do plików + wzbogacony kontekst |
| `PostToolUse` | Nazwę narzędzia, wejście, wyjście |
| `PostToolUseFailure` | Kontekst błędu |
| `PreCompact` | Ponownie wstrzykuje pamięć przed kompaktowaniem |
| `SubagentStart/Stop` | Cykl życia subagenta |
| `Stop` | Podsumowanie końca sesji |
| `SessionEnd` | Znacznik zakończenia sesji |
### Kluczowe możliwości
| Możliwość | Opis |
|---|---|
| **Automatyczne przechwytywanie** | Obsługiwane zdarzenia sesji i narzędzi zapisywane przez natywne integracje |
| **Wyszukiwanie semantyczne** | BM25 + wektor + graf wiedzy z fuzją RRF |
| **Ewolucja pamięci** | Wersjonowanie, zastępowanie (supersession), grafy relacji |
| **Higiena przywołania** | Zastąpione wersje pamięci opuszczają indeksy wyszukiwania; łańcuch wersji w KV zachowuje pełną historię |
| **Wskazówki o bliskich duplikatach** | Zapisy zgłaszają poglądowe dopasowanie `similarTo`, gdy nowa treść jest bliska istniejącemu wspomnieniu |
| **Zakresowanie per agent** | `agentId` przechodzi przez zapis i przywołanie w REST, MCP i indeksie wyszukiwania, w trybie shared lub isolated |
| **Pochodzenie w momencie zapisu** | Każda obserwacja i każde wspomnienie niesie niezmienny kanał pochodzenia (user, agent, tool, import lub shared), oznaczony przy przechwyceniu, zapisie i imporcie |
| **Auto-zapominanie** | Wygasanie TTL, wykrywanie sprzeczności, usuwanie na podstawie ważności |
| **Prywatność na pierwszym miejscu** | Klucze API, sekrety, tagi `` są usuwane przed zapisem |
| **Samonaprawa** | Circuit breaker, łańcuch fallback dostawców, monitorowanie stanu |
| **Mostek Claude** | Dwustronna synchronizacja z MEMORY.md |
| **Graf wiedzy** | Ekstrakcja encji + przeszukiwanie BFS |
| **Pamięć zespołowa** | Współdzielona i prywatna, podzielona na przestrzenie nazw między członkami zespołu |
| **Pochodzenie cytowań** | Śledzenie każdego wspomnienia z powrotem do źródłowych obserwacji |
| **Migawki Git** | Wersjonowanie, rollback i diff stanu pamięci |
---
Wyszukiwanie w trzech strumieniach, łączące trzy sygnały:
| Strumień | Co robi | Kiedy |
|---|---|---|
| **BM25** | Dopasowywanie słów kluczowych ze stemmingiem i rozszerzaniem synonimów | Zawsze włączone |
| **Wektor** | Podobieństwo kosinusowe na gęstych embeddingach | Gdy skonfigurowano dostawcę embeddingów |
| **Graf** | Przeszukiwanie grafu wiedzy przez dopasowywanie encji | Gdy w zapytaniu wykryto encje |
Łączone za pomocą Reciprocal Rank Fusion (RRF, k=60) i zróżnicowane pod względem sesji (maks. 3 wyniki na sesję).
Gdy indeks wektorowy jest wypełniony, `mem::search` (stojące za `memory_recall`) używa hybrydowego rankera BM25 + wektor. Bez embeddingów używa BM25. `smart-search` może dodatkowo łączyć strukturalne dopasowania z grafu, gdy dane grafu istnieją, również w trybie bez klucza. Przywołanie lekcji działa na dedykowanym indeksie BM25 w pamięci, zamiast skanować cały korpus przy każdym zapytaniu. Zastąpione wersje pamięci są wykluczone z każdej ścieżki przywołania; łańcuch wersji zachowuje ich historię.
[0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md).
BM25 od razu tokenizuje grekę, cyrylicę, hebrajski, arabski i akcentowaną łacinę. Dla wspomnień w chińskim / japońskim / koreańskim zainstaluj opcjonalne segmentery (`npm install @node-rs/jieba tiny-segmenter`), aby dzielić ciągi CJK na tokeny na poziomie słów; bez nich agentmemory łagodnie przechodzi na tokenizację całych ciągów i jednorazowo wypisuje wskazówkę na stderr.
### Dostawcy embeddingów
Instalacje bez klucza wyłączają wektorowe embeddingi: `mem::search` używa BM25, natomiast `smart-search` może też użyć istniejących strukturalnych danych grafu. Aby włączyć bezpłatne, lokalne (on-device) embeddingi semantyczne, dodaj to do `~/.agentmemory/.env` i zrestartuj agentmemory:
```env
EMBEDDING_PROVIDER=local
```
Zwykła instalacja npm zawiera opcjonalne środowisko uruchomieniowe `@huggingface/transformers`. Pierwsze żądanie embeddingu pobiera `Xenova/all-MiniLM-L6-v2`, więc potrzebuje dostępu do sieci i może potrwać dłużej; kolejne wnioskowanie działa lokalnie. Zdalni dostawcy są automatycznie wykrywani na podstawie ich kluczy, o ile `EMBEDDING_PROVIDER` nie nadpisuje tego wyboru.
| Dostawca | Model | Koszt | Uwagi |
|---|---|---|---|
| **Lokalny (zalecany opt-in)** | `all-MiniLM-L6-v2` | Bezpłatny | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) |
| Gemini | `gemini-embedding-001` | Darmowy poziom | 100+ języków, wymiary 768/1536/3072 (MRL), wejście do 2048 tokenów. Zastępuje `text-embedding-004` ([przestarzały, wyłączenie 14 stycznia 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` | Płatny | Zoptymalizowany pod kod |
| Cohere | `embed-english-v3.0` | Darmowy okres próbny | Ogólnego przeznaczenia |
| OpenRouter | Każdy model | Zależnie | Proxy dla wielu modeli |
---
54 narzędzia, 6 zasobów, 3 prompty i 17 skilli.
> **Shim MCP a pełny serwer:** opublikowany pakiet `@agentmemory/mcp` to cienki shim. Udostępnia pełną powierzchnię 54 narzędzi **tylko wtedy, gdy może dotrzeć do działającego serwera agentmemory** przez `AGENTMEMORY_URL` (tryb proxy). Gdy żaden serwer nie jest dostępny, shim wraca do lokalnego zestawu 7 narzędzi (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Zmienna środowiskowa `AGENTMEMORY_TOOLS=core|all` jest flagą *po stronie serwera*; ustawienie jej w bloku `env` shimu nie ma żadnego efektu. Jeśli widzisz tylko 7 narzędzi w Cursor / OpenCode / Gemini CLI, uruchom `npx -y @agentmemory/agentmemory@latest` (albo stos Docker) i ustaw `AGENTMEMORY_URL=http://localhost:3111`.
### 54 narzędzia
Trzy powierzchnie narzędzi, od najmniejszej do największej: `AGENTMEMORY_TOOLS=core` ogranicza widoczność do 8 niezbędnych narzędzi (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); poniższy podstawowy zestaw to 14 podstawowych narzędzi z rejestru; wartość domyślna (`AGENTMEMORY_TOOLS=all`) udostępnia wszystkie 54.
Narzędzia podstawowe (14)
| Narzędzie | Opis |
|------|-------------|
| `memory_recall` | Wyszukuje wcześniejsze obserwacje |
| `memory_compress_file` | Kompresuje pliki markdown, zachowując strukturę |
| `memory_save` | Zapisuje wgląd, decyzję lub wzorzec |
| `memory_file_history` | Wcześniejsze obserwacje dotyczące konkretnych plików |
| `memory_patterns` | Wykrywa powtarzające się wzorce |
| `memory_sessions` | Listuje ostatnie sesje |
| `memory_smart_search` | Hybrydowe wyszukiwanie semantyczne + słowno-kluczowe |
| `memory_vision_search` | Wyszukuje obserwacje obrazów |
| `memory_timeline` | Chronologiczne obserwacje |
| `memory_profile` | Profil projektu (koncepcje, pliki, wzorce) |
| `memory_export` | Eksportuje wszystkie dane pamięci |
| `memory_relations` | Odpytuje graf relacji |
| `memory_commit_lookup` | Sesje stojące za commitem git |
| `memory_commits` | Commity zapisane dla sesji |
Narzędzia rozszerzone (54 łącznie, domyślna powierzchnia)
| Narzędzie | Opis |
|------|-------------|
| `memory_patterns` | Wykrywa powtarzające się wzorce |
| `memory_timeline` | Chronologiczne obserwacje |
| `memory_relations` | Odpytuje graf relacji |
| `memory_graph_query` | Przeszukiwanie grafu wiedzy |
| `memory_consolidate` | Uruchamia 4-poziomową konsolidację |
| `memory_claude_bridge_sync` | Synchronizuje z MEMORY.md |
| `memory_team_share` | Udostępnia członkom zespołu |
| `memory_team_feed` | Ostatnio udostępnione elementy |
| `memory_audit` | Ścieżka audytu operacji |
| `memory_governance_delete` | Usuwa ze ścieżką audytu |
| `memory_snapshot_create` | Migawka wersjonowana w Git |
| `memory_action_create` | Tworzy zadania z zależnościami |
| `memory_action_update` | Aktualizuje status akcji |
| `memory_frontier` | Odblokowane akcje uszeregowane według priorytetu |
| `memory_next` | Jedna najważniejsza następna akcja |
| `memory_lease` | Wyłączne leasy akcji (wiele agentów) |
| `memory_routine_run` | Tworzy instancje rutyn przepływu pracy |
| `memory_signal_send` | Komunikacja między agentami |
| `memory_signal_read` | Odczytuje wiadomości z potwierdzeniami odbioru |
| `memory_checkpoint` | Bramki warunków zewnętrznych |
| `memory_mesh_sync` | Synchronizacja P2P między instancjami |
| `memory_sentinel_create` | Obserwatory kierowane zdarzeniami |
| `memory_sentinel_trigger` | Wyzwala wartowników (sentinels) z zewnątrz |
| `memory_sketch_create` | Efemeryczne grafy akcji |
| `memory_sketch_promote` | Awansuje do stałego |
| `memory_crystallize` | Kompaktuje łańcuchy akcji |
| `memory_diagnose` | Kontrole stanu |
| `memory_heal` | Automatycznie naprawia zablokowany stan |
| `memory_facet_tag` | Tagi wymiar:wartość |
| `memory_facet_query` | Odpytywanie po tagach fasetowych |
| `memory_verify` | Śledzi pochodzenie |
### 6 zasobów · 3 prompty · 17 skilli
| Typ | Nazwa | Opis |
|------|------|-------------|
| Zasób | `agentmemory://status` | Stan, liczba sesji, liczba wspomnień |
| Zasób | `agentmemory://project/{name}/profile` | Inteligencja per projekt |
| Zasób | `agentmemory://project/{name}/recent` | Ostatnie obserwacje dla projektu |
| Zasób | `agentmemory://memories/latest` | Ostatnie 10 aktywnych wspomnień |
| Zasób | `agentmemory://graph/stats` | Statystyki grafu wiedzy |
| Zasób | `agentmemory://team/{id}/profile` | Współdzielony profil zespołu |
| Prompt | `recall_context` | Wyszukuje i zwraca wiadomości kontekstowe |
| Prompt | `session_handoff` | Dane przekazania między agentami |
| Prompt | `detect_patterns` | Analizuje powtarzające się wzorce |
| Skill | `/recall` | Przeszukuje pamięć |
| Skill | `/remember` | Zapisuje do pamięci długotrwałej |
| Skill | `/session-history` | Podsumowania ostatnich sesji |
| Skill | `/forget` | Usuwa obserwacje/sesje |
Tabela pokazuje cztery podstawowe skille. Pełny zestaw to 9 wywoływalnych skilli plus 8 skilli referencyjnych; zobacz sekcję Native skills powyżej.
### Samodzielny MCP
Działa bez pełnego serwera, dla każdego klienta MCP. Działa jedno z poniższych:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Albo dodaj do konfiguracji MCP swojego agenta:
Większość agentów (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
Scal wpis `agentmemory` z istniejącym obiektem `mcpServers` twojego hosta, zamiast zastępować cały plik. Dla klientów w sandboksie, które nie mają dostępu do `localhost` hosta, dodaj `"AGENTMEMORY_FORCE_PROXY": "1"` do bloku env i ustaw `AGENTMEMORY_URL` na trasę, do której sandbox ma dostęp.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Skopiuj plik pluginu z repozytorium:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
Uruchamia się automatycznie na porcie `3113`. Podgląd wczytuje jedną migawkę po połączeniu (`GET /agentmemory/viewer/snapshot`), a następnie stosuje zdarzenia na żywo przesyłane przez SSE pod `/agentmemory/viewer/events` przez workera REST: nowe wspomnienia, lekcje, obserwacje, wpisy audytu, zmiany grafu i aktualizacje stanu pojawiają się bez odpytywania (polling) ani przeładowywania strony. Pozostałe żądania dotyczą klikniętych działań, stron „wczytaj więcej” i wyszukiwania. Po zerwaniu strumienia podgląd pokazuje wiek danych, ponawia połączenie z narastającym odstępem (backoff) i synchronizuje stan na podstawie migawki.
- **12 zakładek w czterech grupach** z licznikami na żywo, głębokimi linkami (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), skrótami klawiszowymi i menu mobilnym.
- **Wspomnienia:** wyszukiwanie po stronie serwera, filtry po projekcie, agencie i typie, panel szczegółów z łańcuchem wersji i diffem słów, linki pochodzenia, przyciski kopiowania dla id, wywołania MCP i komendy curl, edycja (nowa wersja), zapominanie z potwierdzeniem, masowe zapominanie i eksport JSON.
- **Sesje:** wbudowana osią czasu obserwacji z czytelnym wejściem i wyjściem narzędzi, filtry i paginacja, a także wspomnienia i lekcje wyprodukowane przez każdą sesję.
- **Graf:** wyszukiwanie, szczegóły węzła z relacjami i źródłami, legenda niezależna wyłącznie od kolorów oraz kontrolki powiększenia.
- **Stan (Health):** żywa wersja `GET /agentmemory/status`. Każdy problem ma podany sposób naprawy, a do tego backend stanu, stan zapisu indeksu, postęp kompaktowania pochodzenia grafu oraz objaśnienie konsolidacji z rzeczywistymi progami.
- **Strony Audyt, Aktywność, Profil, Replay, Lekcje, Akcje i Kryształy**, każda z pustym stanem opisującym, czym jest ta sekcja, czemu jest pusta i jaka komenda ją wypełni, a także podpowiedź słownikowa `?` przy każdym terminie i liczbie.
```bash
open http://localhost:3113
```
Serwer podglądu domyślnie wiąże się z `127.0.0.1` i dołącza sekret serwera, gdy przekazuje żądania do REST API. Przy nasłuchiwaniu poza loopbackiem powłoka HTML pozostaje publiczna, ale każde żądanie proxy wymaga bearer tokenu; podgląd prosi o token i przechowuje go w pamięci sesji przeglądarki. Przed udostępnieniem podglądu skonfiguruj jawne listy dozwolonych hostów i originów oraz TLS. Endpoint REST `/agentmemory/viewer` nadal stosuje zwykłe zasady tokenu bearer i przekierowuje przeglądarki bez tokenu na port podglądu. Nagłówki CSP używają nonce skryptu dla każdej odpowiedzi i wyłączają atrybuty handlerów inline (`script-src-attr 'none'`).
---
### Dostawcy LLM
agentmemory automatycznie wykrywa dostawców na podstawie twojego środowiska. Dostawca udostępnia operacje oparte na LLM, ale samo skonfigurowanie dostawcy nie włącza kompresji obserwacji pisanej przez LLM. Ta ścieżka wymaga zarówno dostawcy, jak i `AGENTMEMORY_AUTO_COMPRESS=true`.
| Dostawca | Konfiguracja | Uwagi |
|----------|--------|-------|
| **No-op (domyślny)** | Konfiguracja niepotrzebna | Kompresja/podsumowywanie oparte na LLM jest wyłączone. Kompresja syntetyczna i przywołanie przez BM25 wciąż działają. Zobacz `AGENTMEMORY_ALLOW_AGENT_SDK` poniżej, jeśli wcześniej korzystałeś z fallbacku na subskrypcję Claude. |
| Anthropic API | `ANTHROPIC_API_KEY` | Rozliczanie per token |
| MiniMax | `MINIMAX_API_KEY` | Kompatybilny z Anthropic |
| Gemini | `GEMINI_API_KEY` | Włącza też embeddingi |
| OpenRouter | `OPENROUTER_API_KEY` | Każdy model |
| OpenAI API | `OPENAI_API_KEY` | Domyślnie `gpt-5.6-luna`, nadpisz za pomocą `OPENAI_MODEL` |
| **Lokalny (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) albo `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Wszystko kompatybilne z API OpenAI. Zerowy koszt, działa na twoim sprzęcie. Zobacz [Modele lokalne](#local-models-ollama--lm-studio--vllm) poniżej. |
| Fallback na subskrypcję Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Tylko opt-in. Tworzy sesje `@anthropic-ai/claude-agent-sdk`; wcześniej powodowało to nieograniczoną rekursję hooka Stop, więc nie jest to już wartość domyślna. |
### Modele lokalne (Ollama / LM Studio / vLLM)
agentmemory rozmawia z każdym serwerem kompatybilnym z API OpenAI, więc wszystko, co wystawia `/v1/chat/completions`, działa bez zmian w kodzie. Bez płatnych kluczy, bez chmury, bez limitów zapytań; działa całkowicie na twoim sprzęcie.
**Ollama** (domyślny 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** (domyślny port `1234`):
Otwórz LM Studio → zakładka Local Server → Start Server. Wybierz jakikolwiek model czatu z listy (Qwen 3, gpt-oss, DeepSeek R1 itd.).
```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**: ta sama struktura. Wskaż `OPENAI_BASE_URL` na URL wystawiany przez twój serwer i ustaw `OPENAI_MODEL` na nazwę, którą twój serwer zaakceptuje.
**Wybór modelu do pracy z pamięcią**: kompresja i podsumowywanie to krótkie zadania (<2K tokenów na wejściu, <500 tokenów na wyjściu), do których w pełni wystarczy model instrukcyjny 7B. Zalecenia:
| Model | Rozmiar | Dlaczego |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | Zbalansowana wartość domyślna na maszynie z 16 GB; silny w ekstrakcji i tekście w formie narzędziowej |
| `qwen3:4b` | ~2.6 GB | Najmniejsza sensowna opcja; dobra do kompresji, słabsza do ekstrakcji grafu |
| `qwen3-coder:30b` | ~19 GB | Najlepszy lokalny wybór dla sesji o profilu kodu (30B MoE, 3.3B aktywne) na sprzęcie 24-32 GB |
| `gpt-oss:20b` | ~14 GB | Silny model ogólny, który mieści się w 16 GB RAM |
| `deepseek-r1:8b` | ~5.2 GB | Dystylat rozumowania; wolniejszy, ale czystsze ekstrakcje |
Modele Qwen 3 domyślnie myślą i mogą spalić cały budżet tokenów na rozumowanie, zanim pojawi się jakiekolwiek wyjście. Ustaw `AGENTMEMORY_LLM_NOTHINK=1`, aby dołączyć `/no_think` do promptów ekstrakcji grafu, i zwiększ `MAX_TOKENS` (16384 działa dobrze), jeśli ekstrakcje wracają puste.
Modele klasy reasoning (w stylu `o1`, z blokami ``) mogą zwracać puste `content` z polem `reasoning`, którego twój lokalny serwer może nie udostępniać. Jeśli ekstrakcje wracają puste, najpierw przełącz się na model bez reasoning. Zmienna środowiskowa `OPENAI_REASONING_EFFORT=none` może też wyłączyć myślenie na modelach myślących Ollama Cloud, które odwzorowują schemat reasoning OpenAI.
Lokalne embeddingi są dostarczane jako opcjonalna zależność, ale nie są włączone domyślnie. Ustaw `EMBEDDING_PROVIDER=local`, aby włączyć `Xenova/all-MiniLM-L6-v2` (384 wymiary). Pierwsze żądanie embeddingu pobiera model; wnioskowanie działa potem lokalnie. Bez tego ustawienia albo zdalnego klucza embeddingów wektory pozostają wyłączone, `mem::search` używa BM25, a `smart-search` może wciąż dodawać istniejące dopasowania z grafu.
### Dobór modelu z uwzględnieniem kosztów
Zacznij bez klucza do przechwytywania i wyszukiwania słów kluczowych. `EMBEDDING_PROVIDER=local` uruchamia lokalne wyszukiwanie semantyczne po pobraniu modelu. Kompresja LLM wymaga dostawcy i `AGENTMEMORY_AUTO_COMPRESS=true`; może wysyłać żądanie dla każdej obserwacji, więc sprawdź aktualne ceny dostawcy. Aktywnych dostawców pokazują podgląd i `agentmemory status`.
### Pamięć wieloagentowa (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
W konfiguracjach wieloagentowych, gdzie kilka ról współdzieli jeden serwer agentmemory (architekt / developer / reviewer / researcher / support-agent), `AGENT_ID` tagguje każdy zapis rolą, która go wykonała. `AGENTMEMORY_AGENT_SCOPE` kontroluje, czy przywołanie filtruje po tym tagu.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
Dwa tryby:
| Tryb | Taguje zapisy | Filtruje przywołanie | Kiedy używać |
|------|------------|---------------|-------------|
| `shared` (domyślny) | tak | nie | Kontekst między agentami ze ścieżką audytu. Architekt widzi, co zanotował developer, ale każdy wiersz zapisuje, kto to powiedział. |
| `isolated` | tak | tak | Ścisłe rozdzielenie. Architekt nigdy nie widzi obserwacji / wspomnień / sesji developera. |
Co jest tagowane, gdy ustawiono `AGENT_ID`: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rola przepływa od `api::session::start` → `mem::observe` → `mem::compress` → KV.
Co jest filtrowane w trybie isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Każdy endpoint przyjmuje `?agentId=`, aby nadpisać to per żądanie, i `?agentId=*`, aby całkowicie zrezygnować z zakresu ze zmiennych środowiskowych. `/memories` przyjmuje też `?includeOrphans=true`, aby ujawnić wspomnienia sprzed `AGENT_ID`, których `agentId` jest niezdefiniowane.
Nadpisanie per wywołanie na poziomie SDK / REST: każdy mutujący endpoint (`/session/start`, `/remember`) przyjmuje w treści żądania pole `agentId`, które wygrywa nad zmienną środowiskową. Przydatne dla środowisk uruchomieniowych routujących wiele ról przez jeden proces serwera. Narzędzie MCP `memory_save` udostępnia to samo pole `agentId`, samodzielny serwer stdio przekazuje dalej zarówno `agentId`, jak i `project`, a zapisane wspomnienia niosą `agentId` do indeksu wyszukiwania, więc wyszukiwanie w zakresie agenta obejmuje zarówno wspomnienia, jak i obserwacje.
Gdy `AGENT_ID` nie jest ustawione, pamięć pozostaje bez zakresu (zachowanie historyczne, brak tagów, brak filtrów).
### Porty
| Port | Przeznaczenie | Zmienna środowiskowa |
|---|---|---|
| `3111` | REST API, MCP HTTP i zdarzenia podglądu na żywo | `III_REST_PORT` |
| `3113` | Interfejs podglądu | `III_VIEWER_PORT` |
`--port ` ustawia port REST, a domyślny port podglądu na `N+2`. `--instance N` tworzy osobne środowisko. Wewnętrzne porty muszą pozostać prywatne; przed udostępnieniem przeczytaj [przewodnik wdrożenia](../deploy/README.md).
### Magazyn: plik lub Redis
Domyślny magazyn plikowy nie wymaga osobnej bazy. Redis jest opcjonalny przez `AGENTMEMORY_STATE_BACKEND=redis` i `AGENTMEMORY_REDIS_URL`. Zmiana backendu nie przenosi pamięci. Trwałość, ograniczenia Redis i uwierzytelniony eksport/import opisuje [przewodnik przechowywania](../docs/reliability/state-storage.md).
### Plik konfiguracyjny
Umieść konfigurację runtime agentmemory w `~/.agentmemory/.env`, zamiast eksportować zmienne w każdym shellu. Jeśli podgląd pokazuje wskazówkę konfiguracyjną, taką jak `export ANTHROPIC_API_KEY=...`, skopiuj ją do tego pliku jako `ANTHROPIC_API_KEY=...` bez prefiksu `export`, a następnie zrestartuj agentmemory. Ustaw `AGENTMEMORY_ENV_FILE`, aby wskazać inną ścieżkę pliku env.
Zmienne środowiska procesu mają pierwszeństwo przed plikiem. Po zmianie konfiguracji zrestartuj serwer.
Na Windows ten sam plik znajduje się w `%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
Aby testować z subskrypcją Claude Code Pro/Max zamiast klucza API, zdecyduj się na to wyraźnie:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
Kompresja obserwacji pisana przez LLM wymaga obu linii: dostępu do dostawcy LLM (włącznie z tym wyraźnym fallbackiem na subskrypcję) oraz `AGENTMEMORY_AUTO_COMPRESS=true`. Sam dostawca pozostawia domyślną ścieżkę kompresji syntetycznej.
Konsolidacja (węzły grafu, lekcje, kryształy) jest domyślnie włączona, gdy skonfigurowano dostawcę LLM. Wyraźnie zrezygnuj za pomocą `CONSOLIDATION_ENABLED=false`, jeśli chcesz działania bez LLM. Ekstrakcja grafu to osobna flaga:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Zmienne środowiskowe
Typowe opcje w `~/.agentmemory/.env`. Wstrzykiwanie kontekstu i kompresja są opcjonalne; kompresja wymaga też dostawcy. Tryb `core` ogranicza widoczne narzędzia 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
```
Pełny opis w [`.env.example`](../.env.example) obejmuje dostawców, filtry przechwytywania, retencję, magazyn, zakres zespołu i opcjonalne funkcje. `AGENTMEMORY_ENV_FILE` wybiera inny plik. Nigdy nie commituj wypełnionego `.env` ani sekretu bearer.
---
147 endpointów na porcie `3111`. REST API domyślnie wiąże się z `127.0.0.1`. Chronione endpointy wymagają `Authorization: Bearer `, a endpointy synchronizacji mesh wymagają wyraźnie ustawionego `AGENTMEMORY_SECRET` na obu peerach.
**Autoryzacja jest domyślnie włączona.** Gdy `AGENTMEMORY_SECRET` nie jest ustawiony, CLI przy pierwszym uruchomieniu generuje losowy sekret w `~/.agentmemory/secret` z uprawnieniami `0600` i kopiuje go także do wybranego katalogu danych. Wszystkie dołączone klienty odczytują go stamtąd, gdy łączą się z lokalnym serwerem: CLI, podgląd, hooki w `plugin/scripts`, serwer MCP i shim `@agentmemory/mcp`, konfiguracje tworzone przez `agentmemory connect` oraz dołączone integracje OpenCode, Pi, OpenClaw, Hermes i obserwator systemu plików. Zapisany sekret jest wysyłany tylko na adresy loopback (`localhost`, `127.0.0.0/8`, `::1`). Jawnie ustawione `AGENTMEMORY_SECRET` ma zawsze pierwszeństwo, a zdalni klienci muszą mieć sekret w swoim środowisku. Wdrożenia self-hosted Docker oparte na repozytorium i punkty wejścia `deploy/` generują i eksportują własny sekret. Aby ręcznie wywołać API:
```bash
curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health
```
**Zasady żądań dla zapisów.** Żądania `POST`, `PUT`, `PATCH` i `DELETE` do REST API i podglądu muszą wysyłać `Content-Type: application/json` (parametr `charset` jest w porządku), kiedy niosą treść, a nagłówek `Origin`, jeśli jest obecny, musi być originem loopback dla skonfigurowanego portu REST albo podglądu, albo być wymieniony w `VIEWER_ALLOWED_ORIGINS` (lista rozdzielona przecinkami, np. `https://memory.example.com`). Klienci, które nie wysyłają nagłówka `Origin` (CLI, hooki, MCP, curl, serwer-do-serwera), nie są tym objęci. Podgląd akceptuje też swój własny origin.
**Ścieżki plików.** Endpointy, które czytają lub zapisują pliki (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), przyjmują tylko ścieżki pod `~/.agentmemory`, katalogiem danych instancji albo katalogiem wymienionym w `AGENTMEMORY_IMPORT_ROOT` (rozdzielaj kilka za pomocą `:`, albo `;` na Windows). `/replay/import-jsonl` przyjmuje też swój domyślny `~/.claude/projects`. `/obsidian/export` zostaje wewnątrz `AGENTMEMORY_EXPORT_ROOT`, a `/migrate` wewnątrz `~/.agentmemory`. Linki symboliczne są rozwiązywane przed każdym sprawdzeniem.
**Czyszczenie sekretów.** Klucze API, tokeny bearer, bloki prywatnych kluczy PEM i dane uwierzytelniające wbudowane w adresy URL (`scheme://user:password@host`) są redagowane (usuwane) przed zapisaniem tekstu, na każdej ścieżce zapisu: obserwacjach, remember, evolve, slotach, lekcjach, akcjach, sketchach, sygnałach, checkpointach, importach, replayu jsonl, synchronizacji mesh, udostępnieniach zespołowych, wyjściu kompresji i podsumowań, kryształach i węzłach grafu.
Kluczowe endpointy
| Metoda | Ścieżka | Opis |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Kontrola stanu (zawsze publiczna) |
| `GET` | `/agentmemory/status` | Co jest nie tak i jak to naprawić (HTML dla przeglądarek, w innym wypadku JSON) |
| `GET` | `/agentmemory/viewer/snapshot` | Wszystko, co pokazuje podgląd, w jednej odpowiedzi |
| `POST` | `/agentmemory/session/start` | Rozpoczyna sesję + pobiera kontekst |
| `POST` | `/agentmemory/session/end` | Kończy sesję |
| `POST` | `/agentmemory/observe` | Przechwytuje obserwację (zobacz dostawę przechwytywania poniżej) |
| `GET` | `/agentmemory/capture` | Skrzynka przechwytywania, dead lettery i spool offline |
| `POST` | `/agentmemory/capture/retry` | Ponawia przechwycenia dead-letter |
| `POST` | `/agentmemory/capture/drain` | Wysyła teraz lokalny spool offline |
| `POST` | `/agentmemory/smart-search` | Wyszukiwanie hybrydowe |
| `POST` | `/agentmemory/context` | Generuje kontekst |
| `POST` | `/agentmemory/remember` | Zapisuje do pamięci długotrwałej |
| `POST` | `/agentmemory/forget` | Usuwa obserwacje |
| `POST` | `/agentmemory/enrich` | Kontekst plikowy + wspomnienia + błędy |
| `GET` | `/agentmemory/profile` | Profil projektu |
| `GET` | `/agentmemory/export` | Eksportuje wszystkie dane |
| `POST` | `/agentmemory/import` | Importuje z JSON |
| `POST` | `/agentmemory/graph/query` | Odpytanie grafu wiedzy |
| `POST` | `/agentmemory/graph/compact` | Przycina nadmiarowe pochodzenie grafu |
| `POST` | `/agentmemory/team/share` | Udostępnia zespołowi |
| `GET` | `/agentmemory/audit` | Ścieżka audytu |
Pełna lista endpointów: [Generowana dokumentacja REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Dostawa przechwytywania.** Hooki wysyłają każdą obserwację raz do `POST /agentmemory/observe` z `eventId`. Jest to własny id hosta dla tego wywołania, gdy payload go ma (na przykład `tool_use_id` Claude Code), albo w innym wypadku hash sesji, typu hooka, nazwy narzędzia, wejścia, wyjścia i znacznika czasu hosta. Serwer zapisuje zdarzenie do skrzynki przechwytywania w magazynie stanu, zapisuje obserwację, a następnie usuwa wpis ze skrzynki. Kod statusu mówi, co się stało:
| Status | Pole `status` | Znaczenie |
|---|---|---|
| `201` | `accepted` | Zapisano. `observationId` to nowa obserwacja. |
| `202` | `accepted` (`state: "retrying"`) | Zaakceptowano, ale zapis się nie powiódł. Serwer ponawia, również po restarcie. |
| `200` | `duplicate` | Ten `eventId` był już zaakceptowany. `observationId` to istniejąca obserwacja; nic nowego nie zostaje zapisane. |
| `400` / `422` | `rejected` | Nieprawidłowy payload, albo zapis nie powiódł się ostatecznie (zdarzenie jest zachowane jako dead letter). |
| `503` | `rejected` (`retryable: true`) | Skrzynka jest pełna (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooki umieszczają zdarzenie w spoolu i wysyłają je później. |
Nieudane zdarzenia są ponawiane co `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) z podwajającym się odstępem (backoff), do `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Zdarzenia, które wciąż zawodzą, zostają w skrzynce jako dead lettery, są wymienione na `/agentmemory/status` i stronie Stan podglądu, i mogą być ponowione za pomocą `POST /agentmemory/capture/retry` (`{"eventId": "..."}` albo `{"all": true}`). Zaakceptowane id zdarzeń są pamiętane przez `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 godzin, maksymalnie `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), więc hook odtworzony po timeoucie albo restarcie jest zapisany raz, natomiast dwa osobne wywołania narzędzia z własnymi id hosta są zapisywane dwukrotnie, nawet gdy ich treść jest identyczna. Gdy obserwacja jest usuwana (forget, usunięcie sesji, eviction, auto-forget albo import, który zastępuje magazyn), jej zdarzenie jest oznaczane jako usunięte przed usunięciem obserwacji, więc odtworzenie tego zdarzenia w tym samym oknie jest traktowane jako duplikat i nic nie zapisuje. Magazyn stanu zapisuje na dysk co 2 sekundy, więc odpowiedziane zdarzenie może przez chwilę istnieć jeszcze tylko w pamięci. Aby to pokryć, każda odpowiedź `2xx` niesie też `bootId` serwera (nowy przy każdym starcie), `acceptedAt` i `durableAfterMs` (odstęp zapisu plus 1.5 s w magazynie plikowym, 1.5 s na redisie, gdzie trwałość jest ustawieniem operatora). Hooki trzymają zdarzenie w lokalnym spoolu, dopóki to okno nie minie, i usuwają je przy kolejnym wywołaniu, bez dodatkowego żądania. Jeśli `bootId` zmienił się do tego czasu, serwer zrestartował się, więc hook wysyła zdarzenie ponownie z tym samym `eventId`; zdarzenie, które dotarło na dysk, nie jest zapisywane dwukrotnie. Serwer sam wysyła też takie zdarzenia przy starcie i w każdym interwale ponowień, więc restart niczego nie gubi, nawet jeśli potem żaden hook nie zostanie uruchomiony. Starsze hooki ignorują dodatkowe pola, a nowe hooki wobec starszego serwera odrzucają zdarzenie przy `2xx` jak dawniej.
Gdy serwer jest wyłączony, nie odpowiada w czasie albo zwraca 5xx, hook dopisuje obserwację do lokalnego pliku spool, `/capture-spool/-.jsonl` (nadpisz folder za pomocą `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Plik jest prywatny dla twojego użytkownika (uprawnienia 600), sekrety są redagowane w ten sam sposób, w jaki redaguje je serwer, zawiera maksymalnie `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) i odrzuca wpisy starsze niż `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Gdy jest pełny, nowe wpisy są odrzucane i zliczane, a `/agentmemory/status` to raportuje. Hook wciąż kończy się kodem 0 w ramach swojego limitu czasu i nie dodaje żadnego żądania, gdy serwer jest zdrowy. Spool jest wysyłany przy następnym starcie i przez pierwszy hook, który ponownie dotrze do serwera, w procesie w tle, więc agent nie czeka. Id zdarzeń zapewniają bezpieczeństwo tego mechanizmu: obserwacja, która dotarła przed timeoutem, nie jest zapisywana dwukrotnie. `npx @agentmemory/agentmemory capture` pokazuje spool i skrzynkę serwera, `--drain` wysyła spool teraz, a `GET /agentmemory/capture` zwraca to samo jako JSON. Ustaw `AGENTMEMORY_CAPTURE_SPOOL=false`, aby wyłączyć spool.
**Kompaktowanie pochodzenia grafu.** Kompaktowanie starszych danych pochodzenia jest odkładane przy starcie, ponieważ odczytuje całe starsze zakresy. `/agentmemory/status` zgłasza `deferred` lub `off`, gdy `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Wykonaj opisane poniżej ręczne kompaktowanie podczas konserwacji. Migracja indeksu wyszukiwania jest osobna: użyj `agentmemory graph-index migrate --allow-legacy-scan` zgodnie z [instrukcją konserwacji](../docs/reliability/graph-index-migration.md).
Aby uruchomić to ręcznie, wywołaj `POST /agentmemory/graph/compact`. Przechodzi przez indeksy nazw i kluczy krawędzi, zamiast listować każdy węzeł i krawędź, i jest bezpieczne do wielokrotnego uruchomienia. Gdy przycina id, zapisuje wpis audytu `graph_compact`.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}'
```
Na dużym magazynie, albo gdy wywołanie zwraca 504, uruchom to we fragmentach. Wyślij `scope` (`nodes`, `edges` albo `history`), `offset` i `limit`, a potem wywołaj znowu ze zwróconym `nextOffset`, aż będzie `null`. Zrób to dla `nodes`, `edges` i `history`, a zakończ jednym wywołaniem `{"scope":"snapshot"}`, bo uruchomienie we fragmentach nie dotyka zbuforowanej migawki.
```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)
```
Wymagania opisano w sekcji [Instalacja](#install). Zasady współtworzenia i kontrole wydania są w [CONTRIBUTING.md](../CONTRIBUTING.md).