agentmemory: trwała pamięć dla kodujących agentów AI

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.

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

rohitg00/agentmemory | Trendshift

Dokument projektowy: 1.7k gwiazdek / 240 forków na giście

Gist rozszerza wzorzec LLM Wiki Karpathy'ego o ocenę ufności, cykl życia, grafy wiedzy i wyszukiwanie hybrydowe: agentmemory jest tą implementacją.

wersja npm CI Licencja Gwiazdki skills.sh installs

54 narzędzia MCP 12 automatycznych hooków 0 zewnętrznych baz danych 5,000+ zaliczonych testów

demo agentmemory

Instalacja • Szybki start • Benchmarki • Konkurenci • Agenci • Jak to działa • MCP • Podgląd • Konfiguracja • API

--- 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`).
---

Współpracuje z każdym agentem

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
Claude Code
plugin natywny + 12 hooków + MCP
Codex CLI
Codex CLI
plugin natywny + 6 hooków + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + hooki/skille pluginu
Cursor
Cursor
plugin natywny + hooki cyklu życia + MCP
OpenCode
OpenCode
plugin przechwytujący + MCP
Devin
Devin
6 hooków + skille + MCP
OpenClaw
OpenClaw
plugin natywny + MCP
Hermes
Hermes
plugin natywny + MCP
pi
pi
natywne przywoływanie + przechwytywanie + skille
OpenHuman
OpenHuman
natywny backend oparty na trait Memory
Gemini CLI
Gemini CLI
serwer MCP
Antigravity
Antigravity
MCP + hooki
Claude Desktop
Claude Desktop
serwer MCP
Warp
Warp
connect + MCP + skille
Zed
Zed
serwer MCP
Cline
Cline
serwer MCP
Continue
Continue
serwer MCP
Droid
Droid
serwer MCP
Kiro
Kiro
serwer MCP
Qwen Code
Qwen Code
serwer MCP
DeepSeek Harness
DeepSeek Harness
natywne przechwytywanie + MCP
Roo Code
Roo Code
serwer MCP
Kilo Code
Kilo Code
serwer MCP
Goose
Goose
serwer MCP
Aider
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). ---

Benchmarki

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). ---

Porównanie z konkurencją

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. ---

Szybki start

### 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).

Wdróż na fly.io Wdróż na Railway

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. ---

Dlaczego agentmemory

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 | ---

Jak to działa

### 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 | ---

Serwer MCP

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/ ``` ---

Podgląd w czasie rzeczywistym

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'`). ---

Konfiguracja

### 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. ---

API

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"}' ``` ---

Rozwój

```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).

Licencja

[Apache-2.0](../LICENSE)