agentmemory: постійна пам'ять для AI-агентів кодування

Постійна пам’ять між сесіями й агентами розробки.
Постійна пам'ять для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode та будь-якого 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

Проєктний документ: 1.7k зірок / 240 форків на gist

Цей gist розширює підхід Karpathy «LLM Wiki», додаючи оцінку довіри, життєвий цикл, графи знань і гібридний пошук: agentmemory — це реалізація цього підходу.

версія npm CI Ліцензія Зірки skills.sh installs

54 інструменти MCP 12 автоматичних хуків 0 зовнішніх БД 5,000+ тестів пройдено

демонстрація agentmemory

Встановлення • Швидкий старт • Бенчмарки • Порівняння з конкурентами • Агенти • Як це працює • MCP • Переглядач • Конфігурація • API

--- AgentMemory зберігає підтримувані події сесій і дає змогу шукати рішення, виправлення та уроки між агентами. У viewer можна переглядати, редагувати, експортувати й видаляти спогади. Пошук за словами працює без API-ключа; ембединги додають семантичний пошук. ## Встановлення Вимоги: - Node.js 20 або новіше, з npm і npx (`node -v`, `npm -v` та `npx -v`). - Для автоматичного налаштування середовища macOS/Linux також потрібні `curl`, POSIX-оболонка `sh` і `tar`. - У Windows використовуйте WSL2 або [інструкцію для нативного встановлення](#windows). Канонічна команда для чистого встановлення: ```bash npx -y @agentmemory/agentmemory@latest ``` Виберіть агентів і постачальника або режим без ключа. Майстер запише налаштування, запустить сервер пам’яті й запропонує глобальне встановлення команди `agentmemory`. `-y` підтверджує запит npm; `@latest` вибирає поточний випуск. Стиснення через LLM потребує постачальника й `AGENTMEMORY_AUTO_COMPRESS=true`. Режим без ключа вимикає векторні ембединги. `memory_recall` (шлях `mem::search`) використовує BM25, тоді як `memory_smart_search` також може об'єднувати структурні збіги графа, якщо дані графа вже існують. Щоб безкоштовно отримати семантичне пригадування на пристрої, встановіть `EMBEDDING_PROVIDER=local` у `~/.agentmemory/.env` і перезапустіть. Перший запит ембединга завантажує `Xenova/all-MiniLM-L6-v2`; після цього первинного завантаження моделі обчислення виконуються локально. API працює на `http://localhost:3111`, viewer на `http://localhost:3113`. Типово обидва слухають лише локальні з’єднання. Налаштування містяться в `~/.agentmemory/.env`; каталоги пам’яті й окремі інстанси описано в розділі [зберігання даних](#data-storage). Потім перевірте, що пригадування працює, і дайте агенту його скіли: ```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 ``` Пошук за ключовими словами має спрацьовувати в типовому режимі без ключа через BM25. Запит `database performance optimization` у демо навмисно семантичний і може повертати нуль результатів, доки не налаштовано постачальника ембедингів. Бажаєте доручити все агенту кодування? Дайте йому одну інструкцію: > Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md Підключіть іншого агента через `agentmemory connect `. Див. [інтеграції](#works-with-every-agent) та [щоденні команди](#everyday-commands).
Глобальне встановлення / EACCES ```bash npm install -g @agentmemory/agentmemory@latest ``` Команда npx вище залишається канонічним шляхом для чистого встановлення і дозволяє уникнути проблем із правами доступу до глобального префікса.
npx видає стару версію npx кешує за версіями. Примусово отримайте останню версію за допомогою `npx -y @agentmemory/agentmemory@latest`, або одноразово очистьте кеш командою `rm -rf ~/.npm/_npx` (macOS/Linux; на Windows видаліть `%LOCALAPPDATA%\npm-cache\_npx`).
---

Працює з кожним агентом

agentmemory працює з будь-яким агентом, що підтримує хуки, MCP або REST API. Усі агенти використовують один і той самий сервер пам'яті.
Claude Code
Claude Code
нативний плагін + 12 хуків + MCP
Codex CLI
Codex CLI
нативний плагін + 6 хуків + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + хуки/скіли плагіна
Cursor
Cursor
нативний плагін + хуки життєвого циклу + MCP
OpenCode
OpenCode
плагін захоплення + MCP
Devin
Devin
6 хуків + скіли + MCP
OpenClaw
OpenClaw
нативний плагін + MCP
Hermes
Hermes
нативний плагін + MCP
pi
pi
нативне пригадування + захоплення + скіли
OpenHuman
OpenHuman
нативний бекенд на основі трейта Memory
Gemini CLI
Gemini CLI
MCP-сервер
Antigravity
Antigravity
MCP + хуки
Claude Desktop
Claude Desktop
MCP-сервер
Warp
Warp
підключення + MCP + скіли
Zed
Zed
MCP-сервер
Cline
Cline
MCP-сервер
Continue
Continue
MCP-сервер
Droid
Droid
MCP-сервер
Kiro
Kiro
MCP-сервер
Qwen Code
Qwen Code
MCP-сервер
DeepSeek Harness
DeepSeek Harness
нативне захоплення + MCP
Roo Code
Roo Code
MCP-сервер
Kilo Code
Kilo Code
MCP-сервер
Goose
Goose
MCP-сервер
Aider
Aider
REST API
Oh My Pi
нативне пригадування + захоплення + скіли + необов’язковий MCP

Працює з будь-яким агентом, що підтримує MCP або HTTP. Один сервер, пам'ять спільна для всіх них.

--- ### Зберігання даних Типово пам’ять зберігається поза репозиторієм: | Платформа | Каталог даних | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | Інстанс 0 повторно використовує наявний `./data/state_store.db`. Інший каталог задається через `--data-dir ` або `AGENTMEMORY_DATA_DIR`. Зберігайте той самий каталог під час перезапуску й оновлення. ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` `--instance 1` використовує підкаталог `instance-1`, порт API `3211` і viewer `3213`. Redis і міграцію описано в [посібнику зі зберігання та резервування](../docs/reliability/state-storage.md). Примітки до останнього релізу: [CHANGELOG.md](../CHANGELOG.md). ---

Бенчмарки

Актуальні результати пошуку, визначення метрик і кроки відтворення: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

Порівняння з конкурентами

Оновлене порівняння продуктів і варіантів розгортання з джерелами: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

Швидкий старт

### Спробуйте за 30 секунд ```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` створює 3 реалістичні сесії (JWT-автентифікація, виправлення запиту N+1, обмеження частоти запитів) і виконує пошук за ними. Встановлення без ключа вимикають вектори, тому запити за ключовими словами `mem::search` мають спрацьовувати через BM25, тоді як `database performance optimization` може повертати нуль результатів. `smart-search` може додатково повертати структурні збіги графа, якщо дані графа існують. Щоб семантичний запит знаходив виправлення N+1 через вектори, встановіть `EMBEDDING_PROVIDER=local`, перезапустіть і дайте завершитися першому завантаженню моделі. Відкрийте `http://localhost:3113`, щоб спостерігати за побудовою пам'яті в реальному часі. ### Перевірка чистого встановлення та стійкості після перезапуску Із запущеним сервером перевірте здоров’я, viewer і стан: ```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` показує стан сервера, постачальників, режим ембедингів, доставку спостережень і відновлення. Захищені REST-запити потребують секрет сервера. Використовуйте заданий `AGENTMEMORY_SECRET`, інакше завантажте згенерований локальний секрет: ```bash # Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead. read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret" curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}' curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"query":"restart persistence probe","limit":5}' ``` Потім виконайте `npx -y @agentmemory/agentmemory@latest stop`, знову запустіть канонічну команду в терміналі 1, дочекайтеся `/agentmemory/livez` і повторіть пошук. Тестовий запис має й надалі повертатися. Якщо ви обрали власний `--data-dir`, передайте той самий каталог під час перезапуску. ### Щоденні команди Встановлення та налаштування описані в розділі [Встановлення](#install) вище (перший запуск проведе вас через цей процес). Щодня: ```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 ``` ### Відтворення сесій Кожну сесію, яку записує agentmemory, можна відтворити. Відкрийте переглядач, оберіть вкладку **Replay** і прогортайте часову шкалу: промпти, виклики інструментів, результати інструментів і відповіді відображаються як окремі події з керуванням відтворення/паузи, регулюванням швидкості (від 0.5x до 4x) і клавіатурними скороченнями (пробіл — перемкнути, стрілки — покроково). Щоб імпортувати старіші JSONL-транскрипти 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 ``` Імпортовані сесії з’являються в Replay поруч із нативними. Транскрипти індексуються й отримують канал походження `import`; обробка також може створювати кристали сесій та уроки. > **Важливо, якщо ви покладаєтеся на `import-jsonl` як на основний шлях захоплення:** `cleanupPeriodDays` Claude Code (у `~/.claude/settings.json`, за замовчуванням **30**) автоматично видаляє JSONL-транскрипти, старіші за це вікно, з `~/.claude/projects/`. Якщо ви встановлюєте agentmemory на вже кількамісячну історію Claude Code, усе старіше за 30 днів уже зникло ще до першого імпорту. Або запускайте `import-jsonl` за розкладом (cron), або підвищте `cleanupPeriodDays`, або підключіть хуки автозахоплення (типовий шлях встановлення плагіна), щоб кожен крок потрапляв в agentmemory, поки сесія активна, і очищення JSONL більше не мало значення. ### Оновлення / обслуговування Використовуйте команду обслуговування, коли ви свідомо хочете оновити свій локальний рантайм: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` Команда оновлює локальне середовище й може змінити JavaScript-залежності поточного workspace. Зробіть резервну копію даних і прочитайте [посібник з оновлення](../docs/upgrades/iii-0.25.md). ### Claude Code (один блок, вставте як є) ```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 без встановлення плагіна (автономний шлях MCP) Якщо ви підключаєте MCP-сервер agentmemory напряму через `~/.claude.json` (типовий шлях), а не через `/plugin install`, Claude Code ніколи не розгортає `${CLAUDE_PLUGIN_ROOT}`, і вам доведеться вказувати абсолютні шляхи до скриптів хуків у `~/.claude/settings.json` (типовий шлях). Ці шляхи, як правило, містять версію agentmemory (наприклад, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), тому наступне оновлення непомітно зламає кожен хук. Обхідне рішення: ```bash agentmemory connect claude-code --with-hooks ``` Ця команда налаштовує MCP-сервер і додає включені до пакета хуки до конфігурації користувача Claude Code. Якщо `CLAUDE_CONFIG_DIR` не задано, вона порожня або містить лише пробільні символи, для MCP використовується `~/.claude.json`, а для хуків — `~/.claude/settings.json`. Інші значення каталогу використовуються без змін, включно з пробільними символами на початку та в кінці. Щоб використовувати власний каталог, задайте однакове непорожнє значення `CLAUDE_CONFIG_DIR` для цієї команди та Claude Code; тоді файлами будуть відповідно `$CLAUDE_CONFIG_DIR/.claude.json` і `$CLAUDE_CONFIG_DIR/settings.json`. Claude Code має отримати це значення у своєму середовищі запуску, навіть якщо конектор читає його з файлу `.env` AgentMemory. Створіть власний каталог перед виконанням цієї команди; інакше конектор пропустить Claude Code як невиявлений. Якщо значення в оболонці містить лише пробільні символи, вилучіть `CLAUDE_CONFIG_DIR` із середовища перед запуском Claude Code, щоб він також використовував типовий профіль. Використовуйте абсолютний шлях. Відносні шляхи визначаються від робочого каталогу, тому обидві команди потрібно запускати з одного каталогу. Команди хуків використовують абсолютні шляхи до каталогу `plugin/`, включеного до встановленого пакета. Після оновлення agentmemory запустіть команду ще раз, щоб оновити ці шляхи. Записи користувача у файлах конфігурації зберігаються; замінюються лише попередні записи agentmemory. Використання `/plugin install` залишається рекомендованим підходом. Для віддалених або захищених розгортань запускайте Claude Code зі встановленими `AGENTMEMORY_URL` та `AGENTMEMORY_SECRET`. Плагін передає обидва значення своєму вбудованому MCP-серверу; якщо `AGENTMEMORY_URL` порожній, MCP-шим використовує `http://localhost:3111`. ### Codex CLI (платформа плагінів 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 ``` Плагін Codex постачається з того самого каталогу `plugin/`, що й плагін Claude Code. Він реєструє: - Вбудований stdio MCP-мост до запущеного демона, без завантаження через npm і без локального резервного сховища. Див. [локальний посібник Codex](../docs/plugins/codex-local.md), щоб протестувати нерелізну збірку. - 6 хуків життєвого циклу: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 9 викликаних скілів: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, а також 8 довідкових скілів, які агент завантажує за потреби (дисципліна пам'яті, інструменти MCP, REST API, конфігурація, агенти, хуки, архітектура та посібник зі створення скілів) Механізм хуків Codex вставляє `CLAUDE_PLUGIN_ROOT` у підпроцеси хуків (згідно з [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), тому ті самі скрипти хуків працюють для обох хостів без дублювання. Події Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure доступні лише для Claude Code і не реєструються для Codex. #### Довіра до хуків Codex та сумісність Нативна диспетчеризація хуків плагіна підтверджена для Codex CLI 0.150.1. Перш ніж очікувати захоплення, підтвердьте довіру до хуків плагіна. Поведінка Codex Desktop залежить від вбудованого в нього середовища виконання; перевірте `/hooks` і підтвердьте захоплену подію, перш ніж застосовувати обхідне рішення. Якщо ваш хост вимагає глобальних хуків, продзеркаліть команди у `~/.codex/hooks.json`. Якщо MCP уже підключено, поточному конектору потрібен `--force`, щоб дістатися встановлення хуків: ```bash agentmemory connect codex --with-hooks --force ``` Це об'єднує глобальні хуки та перезаписує запис MCP agentmemory, зберігаючи незв'язані записи. Перевірте власні налаштування endpoint agentmemory, перш ніж використовувати `--force`. Запустіть повторно після оновлення, щоб оновити шляхи скриптів. Увімкніть або нативні хуки плагіна, або глобальні копії, щоб уникнути дублювання захоплення. ### GitHub Copilot CLI Для режиму агента VS Code скористайтеся [посібником з MCP та автозахоплення Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Конектор CLI не налаштовує VS Code. ```bash # MCP-only wiring agentmemory connect copilot-cli # Альтернативно, повний плагін хуків/скілів з підкаталогу GitHub copilot plugin install rohitg00/agentmemory:plugin ``` `agentmemory connect copilot-cli` об'єднує `mcpServers.agentmemory` з `~/.copilot/mcp-config.json` (або `$COPILOT_HOME/mcp-config.json`, якщо встановлено `COPILOT_HOME`) і зберігає наявні сервери. У нативному Windows це єдиний автоматизований адаптер `connect`; усіх інших нативних агентів Windows потрібно налаштовувати вручну. `connect` у WSL підтримується лише тоді, коли цільовий агент встановлено в тому самому середовищі WSL. Copilot підхоплює MCP-сервер під час наступного запуску або після `/mcp`. Встановіть також плагін, якщо хочете отримати повний досвід роботи з хуками/скілами. ### Cursor ```bash agentmemory connect cursor ``` Потім у **Settings → Plugins → Add marketplace** виберіть каталог agentmemory з `.cursor-plugin/plugin.json`, увімкніть плагін **agentmemory** і перезавантажте вікно. Плагін забезпечує захоплення життєвого циклу, визначення проєкту за workspace, скіли й MCP. Увімкніть або хуки плагіна, або ручні хуки в `~/.cursor/hooks.json`, щоб уникнути дублювання. [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 ``` Виберіть команду для свого клієнта. Pi та OMP встановлюють нативне пригадування, захоплення, повторне надсилання офлайн-даних і скіли; `--with-mcp` додає всі інструменти. Виконайте `/reload` у Pi або перезапустіть OMP, потім перевірте `/agentmemory-status`. DSH встановлює MCP і вбудований плагін захоплення; після підключення перезапустіть DSH. Pi також підтримує пакет `@agentmemory/pi`. Локальне встановлення й доступність npm описано в [посібнику Pi](../integrations/pi/). Використовуйте один спосіб встановлення на клієнт. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (вставте цей промпт) ```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`. ``` Повний посібник: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (вставте цей промпт) ```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. ``` Повний посібник: [`integrations/hermes/`](../integrations/hermes/)
### Інші агенти Запустіть сервер пам'яті: `npx -y @agentmemory/agentmemory@latest` #### Нативні скіли через `npx skills add` agentmemory постачає 17 скілів у форматі `/SKILL.md` у стилі Claude Code: 9 викликаних скілів-дій (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) і 8 довідкових скілів, які агент завантажує за потреби (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Довідкові скіли містять таблиці даних, згенеровані з джерела, тому вони ніколи не розходяться з ним. CLI [`skills`](https://npmjs.com/package/skills) від vercel-labs автоматично встановлює їх у нативний каталог скілів агента, що викликає, для понад 50 агентів (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf та інших): ```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 ``` Це **доповнює** `agentmemory connect `: - `agentmemory connect ` зазвичай записує конфігурацію MCP. Hermes, OpenClaw, Pi та Oh My Pi типово встановлюють нативну інтеграцію та скіли; MCP вмикається через `--with-mcp`. - `npx skills add rohitg00/agentmemory` встановлює скіли для агентів без вбудованого набору. Для Hermes, OpenClaw, Pi та Oh My Pi пропустіть цей крок: їхні конектори вже встановлюють скіли. Для декількох агентів, які CLI skills ще не підтримує (Zed v1.3.x і нижче), розмістіть 17 файлів SKILL.md у нативному каталозі скілів агента самостійно; той самий формат працює всюди. #### Стандартний блок MCP Запис agentmemory — це **той самий блок MCP-сервера** для кожного хоста, що використовує структуру `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}" } } ``` **Об'єднайте цей запис із наявним об'єктом `mcpServers`** у конфігураційному файлі хоста; не замінюйте файл повністю. Якщо файл уже містить інші сервери, додайте `agentmemory` поруч як ще один ключ усередині `mcpServers`. Якщо `mcpServers` взагалі відсутній, вставте блок усередину `{ "mcpServers": { ... } }`. Заповнювачі `${VAR}` успадковують `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` з оболонки під час запуску MCP-сервера; невстановлені змінні передають порожні рядки, і шим переходить на `http://localhost:3111`. Один підключений запис охоплює як локальні, так і віддалені (k8s / за реверс-проксі) розгортання. | Агент | Конфігураційний файл | Примітки | |---|---|---| | **Cursor (лише MCP)** | `~/.cursor/mcp.json` | Об'єднайте з `mcpServers`, або скористайтеся `agentmemory connect cursor`. На сайті також доступне глибоке посилання в один клік. | | **Cursor (повний плагін)** | `.cursor-plugin/` | Плагін надає хуки життєвого циклу, визначення workspace, скіли й MCP у Cursor IDE та `cursor-agent`. Див. [налаштування Cursor](#cursor). | | **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Об'єднайте з `mcpServers`. Перезапустіть Claude Desktop після редагування. | | **Cline / Roo Code / Kilo Code** | Налаштування MCP Cline (Settings UI → MCP Servers → Edit) | Той самий блок `mcpServers`. | | **Devin CLI (MCP + хуки)** | `~/.config/devin/config.json` | `agentmemory connect devin` об'єднує запис MCP; `--with-hooks` додає шість нативних хуків автозахоплення (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) із відповідниками інструментів Devin у нижньому регістрі. Перевірте за допомогою `devin mcp list` та `/hooks` усередині devin. | | **Devin CLI (повний плагін)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` з checkout реєструє всі 17 скілів як слеш-команди `/agentmemory:` разом із MCP-сервером. Хуки плагіна Devin не можуть викликати `SessionStart`/`SessionEnd`, тому поєднуйте це з `connect devin --with-hooks` для повного захоплення сесії. | | **Devin (хмара)** | Settings → Connections → MCP servers | Додайте власний MCP (STDIO): команда `npx`, аргументи `-y @agentmemory/mcp@latest`, змінна середовища `AGENTMEMORY_URL`, що вказує на доступне в мережі розгортання agentmemory, плюс `AGENTMEMORY_SECRET` (хмарні сесії не можуть дістатися localhost — див. [`../deploy/`](../deploy/)). Збережіть секрет у Devin Secrets, потім скористайтеся «Test listing tools», щоб перевірити появу всіх 54 інструментів. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (об'єднує автоматично). | | **GitHub Copilot CLI (лише MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` об'єднує `mcpServers.agentmemory`; Copilot підхоплює це під час наступного запуску або через `/mcp`. | | **GitHub Copilot CLI (повний плагін)** | Встановлення плагіна Copilot | `copilot plugin install rohitg00/agentmemory:plugin` для плагіна з підкаталогу GitHub. | | **OpenClaw** | Конфігурація MCP OpenClaw | Той самий блок `mcpServers`. Глибше: `openclaw plugins install ./integrations/openclaw` займає слот пам'яті OpenClaw (автоматично перемикається з `memory-core`); встановіть `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, інакше захоплення кроків буде непомітно блокуватися. Див. [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (лише MCP)** | `.codex/config.toml` | Формат TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, або додайте `[mcp_servers.agentmemory]` вручну. | | **Codex CLI (повний плагін)** | Marketplace плагінів Codex | `codex plugin marketplace add rohitg00/agentmemory`, потім `codex plugin add agentmemory@agentmemory`. Реєструє MCP + 6 хуків життєвого циклу + 17 скілів. Підтвердьте довіру до хуків і перевірте захоплення на вашому хості; див. [налаштування та перевірку Codex](../docs/plugins/codex-local.md). | | **OpenCode (лише MCP)** | `opencode.json` | Інший формат: ключ `mcp` на верхньому рівні, команда у вигляді масиву: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (повний плагін)** | `plugin/opencode/` | 22 хуки автозахоплення, що охоплюють життєвий цикл сесії, повідомлення, інструменти, помилки. Атрибуція проєкту відбувається для кожної сесії окремо, тому один процес OpenCode, що охоплює декілька репозиторіїв, фіксує кожну сесію під власним проєктом. Дві слеш-команди (`/recall`, `/remember`). Скопіюйте `plugin/opencode/` у ваш робочий простір OpenCode і додайте запис плагіна до `opencode.json`. Повну таблицю хуків + аналіз прогалин див. у [`plugin/opencode/README.md`](../plugin/opencode/README.md). | | **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. нативне пригадування + захоплення + скіли. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). | | **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. нативне пригадування + захоплення + скіли. [Oh My Pi](../integrations/omp/). | | **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` дає постачальника пам'яті з 6 хуками (попереднє отримання, захоплення кроку, завершення сесії, передстиснення, дзеркалювання MEMORY.md, блок системного промпту). Перевірте за допомогою `hermes plugins doctor` та `hermes memory status`. Див. [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` записує стандартний блок `mcpServers`. Корисне навантаження хука сумісне за полями з Claude Code, тому наявні скрипти для 12 хуків працюють без змін; підключіть їх через розділ `hooks` у тому самому `settings.json`. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` встановлює MCP і хуки захоплення у спільному каталозі налаштувань. Див. [налаштування та обмеження Antigravity](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` використовує ту саму конфігурацію MCP і хуків, що й поточні версії IDE. Наявні встановлення слід оновити за допомогою `--force`; див. [примітки щодо оновлення](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` записує конфігурацію рівня користувача. Перевизначення на рівні робочого простору розміщуються в `.kiro/settings/mcp.json` поруч із вашим кодом. | | **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` записує стандартний блок `mcpServers`. Warp також автоматично виявляє скіли з `.claude/skills/`; після встановлення плагіна Claude Code 9 скілів agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) з'являються нативно в палітрі слеш-команд Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` записує стандартний блок `mcpServers`. Користувачі розширення VS Code: вставте той самий блок через Cline Settings → MCP Servers → Edit JSON. | | **Continue.dev** | `~/.continue/config.yaml` (бажано) або `config.json` (застарілий) | `agentmemory connect continue` створює `config.yaml`, якщо налаштувань немає, або змінює наявний `config.json`. Для наявного YAML показує блок для `mcpServers:`, зберігаючи коментарі та якорі. Continue використовує масив, а не об’єкт. | | **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` записує дані під `context_servers` (ключ Zed, НЕ `mcpServers`). Віддалені MCP-сервери замість цього можна підключити через `{"url": "..."}`. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` записує стандартний блок `mcpServers`. Перевизначення на рівні проєкту розміщуються в `/.factory/mcp.json`. Передайте `--with-hooks` для нативного автозахоплення. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` вмикає інструменти MCP. Додайте `--with-hooks`, щоб завантажити вбудований в AgentMemory плагін запису подій. Окремий пакет плагіна не потрібен. [DSH](../docs/dsh.md). | | **Goose** | Інтерфейс налаштувань MCP Goose | Той самий блок `mcpServers`; скористайтеся `goose configure` → Add Extension → MCP. Пряме редагування YAML у `~/.config/goose/config.yaml` підтримується, але схема використовує `extensions:` + `cmd` (а не `mcpServers:` + `command`). | | **Aider** | н/д | Для збереження й пошуку зі скриптів використовуйте [REST-приклади з автентифікацією](#validate-a-fresh-install-and-restart-persistence). | | **Підтримувані агенти** | Лише скіли | `npx skills add rohitg00/agentmemory`; виберіть скіли для встановлення та цільових агентів. | **MCP-клієнти в sandbox** (Flatpak / Snap / обмежувальні контейнери), які не можуть дістатися `localhost` хоста: також встановіть `"AGENTMEMORY_FORCE_PROXY": "1"` у блоці `env` та вкажіть у `AGENTMEMORY_URL` маршрут, якого sandbox справді може досягти (наприклад, вашу IP-адресу в LAN). ### Програмний доступ (Python / Rust / Node) Використовуйте [REST API](#api) з будь-якої мови або [інструменти MCP](#mcp-server) з агента. REST використовує JSON і bearer-автентифікацію; див. [приклад збереження й пошуку](#validate-a-fresh-install-and-restart-persistence). Пряму інтеграцію середовища показано в [прикладах Python](../examples/python/). ### Зі джерельного коду ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` `npm start` запускає той самий локальний сервер, що й встановлений CLI. Вимоги наведено у [Встановленні](#install); API та viewer слухають `127.0.0.1`. ### Windows agentmemory працює у Windows 10/11; WSL2 може автоматично встановити engine. Нативна Windows потребує ручного встановлення iii-engine v0.25.1: завантажте архів зі [сторінки iii v0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), перевірте checksum і розмістіть `iii.exe` у `PATH`. CLI не розпаковує ZIP автоматично Автоматичне налаштування MCP у нативній Windows підтримує лише `agentmemory connect copilot-cli`; для інших скористайтеся [Other agents](#other-agents). У WSL виконуйте `connect`, лише якщо агент встановлений у тому самому середовищі **Лише standalone MCP без engine.** Якщо не потрібні REST API, переглядач і служби runtime: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` Запустіть `agentmemory doctor` або перезапустіть із `--verbose`. Якщо порти зайняті, використовуйте `--port ` або `--instance `. Сумісність і відновлення описано в [посібнику з оновлення](../docs/upgrades/iii-0.25.md). ---

Розгортання

Для власного розгортання використовуйте Docker Compose або шаблони нижче. Пам’ять і облікові дані містяться на томі `/data`; резервуйте його й використовуйте повторно під час оновлення. Автентифікацію, мережу, резервування та міграцію описано в [посібнику з розгортання](../deploy/README.md).

Розгорнути на fly.io Розгорнути на Railway

Кнопка розгортання в один клік для Render вимагає `render.yaml` у корені репозиторію, який ми свідомо тримаємо чистим. Скористайтеся процесом Render Blueprint, описаним у [`../deploy/render/`](.././deploy/render/README.md), щоб вручну вказати на blueprint усередині репозиторію. Повні деталі налаштування (захоплення HMAC, SSH-тунель для переглядача, ротація, резервне копіювання, мінімальна вартість) містяться в [`../deploy/`](.././deploy/README.md): - [`../deploy/fly`](.././deploy/fly/README.md): одна машина з `auto_stop_machines = "stop"`; найдешевший варіант у режимі очікування. - [`../deploy/railway`](.././deploy/railway/README.md): фіксована плата тарифу Hobby, том у панелі керування. - [`../deploy/render`](.././deploy/render/README.md): процес Blueprint, автоматичні знімки диска на платних тарифах. - [`../deploy/coolify`](.././deploy/coolify/README.md): самостійний хостинг на власному VPS через [Coolify](https://coolify.io/self-hosted); той самий Docker Compose-стек, хост і дані залишаються у вас. REST використовує `3111`, viewer `3113`. Залиште їх у приватній мережі або захистіть автентифікацією й TLS. Налаштування платформ і [міграцію старого Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) описано в посібнику з розгортання. ---

Чому agentmemory

Знання про проєкт розподілені між чатами й файлами інструкцій. AgentMemory дає змогу шукати попередні рішення, виправлення та уроки з поточного агента. ### Порівняно з вбудованою пам'яттю агента Кожен AI-агент кодування постачається з вбудованою пам'яттю: у Claude Code є `MEMORY.md`, у Cursor — notepads, у Cline — memory bank. Вони працюють як стікери-нагадування. agentmemory — це база даних із можливістю пошуку, що стоїть за цими стікерами. | | Вбудована (CLAUDE.md) | agentmemory | |---|---|---| | Обслуговування | Інструкції, редаговані вручну | Індексована історія сесій і спогади | | Пошук | Завантажує все у контекст | BM25 + вектор + граф (лише топ-K) | | Між агентами | Файли для кожного агента | MCP + REST (будь-який агент) | | Координація | Немає | Оренди, сигнали, дії, рутини | | Спостережуваність | Читання файлів вручну | Переглядач у реальному часі на :3113 | ---

Як це працює

### Конвеєр пам'яті ```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-рівнева консолідація пам'яті Побудовано за зразком того, як людський мозок обробляє пам'ять, включно з консолідацією під час сну. | Рівень | Що | Аналогія | |------|------|---------| | **Робочий (Working)** | Необроблені спостереження з використання інструментів | Короткочасна пам'ять | | **Епізодичний (Episodic)** | Стиснуті підсумки сесій | «Що сталося» | | **Семантичний (Semantic)** | Видобуті факти та закономірності | «Що я знаю» | | **Процедурний (Procedural)** | Робочі процеси та шаблони рішень | «Як це робити» | Пам'ять згасає з часом (крива Еббінгауза). Часто використовувана пам'ять зміцнюється. Застарілі записи пам'яті автоматично витісняються. Суперечності виявляються й вирішуються. ### Що фіксується Таблиця описує хуки Claude Code. Інші інтеграції захоплюють події, доступні в їхньому клієнті. Автоматичне додавання контексту через спільні хуки вмикається явно: `AGENTMEMORY_INJECT_CONTEXT=true`. | Хук | Фіксує | |------|----------| | `SessionStart` | Шлях до проєкту, ID сесії | | `UserPromptSubmit` | Промпти користувача (з фільтром приватності) | | `PreToolUse` | Шаблони доступу до файлів + збагачений контекст | | `PostToolUse` | Назву інструменту, вхідні та вихідні дані | | `PostToolUseFailure` | Контекст помилки | | `PreCompact` | Повторно вставляє пам'ять перед компактуванням | | `SubagentStart/Stop` | Життєвий цикл субагента | | `Stop` | Підсумок завершення сесії | | `SessionEnd` | Маркер завершення сесії | ### Ключові можливості | Можливість | Опис | |---|---| | **Автоматичне захоплення** | Підтримувані події сесій та інструментів, записані нативними інтеграціями | | **Семантичний пошук** | BM25 + вектор + граф знань зі злиттям RRF | | **Еволюція пам'яті** | Версіювання, заміщення, графи зв'язків | | **Гігієна пригадування** | Заміщені версії пам'яті зникають з пошукових індексів; ланцюжок версій у KV зберігає повну історію | | **Підказки про близькі дублікати** | Збереження повідомляє про рекомендаційний збіг `similarTo`, коли новий контент сильно нагадує наявну пам'ять | | **Скоупінг для кожного агента** | `agentId` проходить через збереження та пригадування в REST, MCP та пошуковому індексі, у спільному або ізольованому режимі | | **Походження на момент запису** | Кожне спостереження та запис пам'яті несе незмінний канал походження (користувач, агент, інструмент, імпорт або спільний доступ), зафіксований під час захоплення, збереження та імпорту | | **Автозабування** | Закінчення TTL, виявлення суперечностей, витіснення за важливістю | | **Приватність понад усе** | API-ключі, секрети, теги `` видаляються перед збереженням | | **Самовідновлення** | Circuit breaker, ланцюжок резервних постачальників, моніторинг стану | | **Місток до Claude** | Двостороння синхронізація з MEMORY.md | | **Граф знань** | Видобування сутностей + обхід у ширину (BFS) | | **Командна пам'ять** | Спільна + приватна пам'ять з просторами імен для членів команди | | **Походження цитат** | Простежуйте будь-яку пам'ять до вихідних спостережень | | **Знімки Git** | Версіювання, відкат і diff стану пам'яті | --- Потрійний потік пошуку, що поєднує три сигнали: | Потік | Що робить | Коли | |---|---|---| | **BM25** | Пошук за ключовими словами зі стеммінгом та розширенням синонімів | Завжди активний | | **Вектор** | Косинусна подібність для щільних ембедингів | Налаштовано постачальника ембедингів | | **Граф** | Обхід графа знань через збіг сутностей | У запиті виявлено сутності | Об'єднується за допомогою Reciprocal Rank Fusion (RRF, k=60) і диверсифікується за сесіями (максимум 3 результати на сесію). Коли векторний індекс заповнено, `mem::search` (що стоїть за `memory_recall`) використовує гібридний ранжувальник BM25 + вектор. Без ембедингів він використовує BM25. `smart-search` може додатково об'єднувати структурні збіги графа, якщо дані графа існують, зокрема в режимі без ключа. Пригадування уроків виконується на окремому BM25-індексі в пам'яті, а не шляхом сканування всього корпусу під час кожного запиту. Заміщені версії пам'яті виключаються з усіх шляхів пригадування; ланцюжок версій зберігає їхню історію. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). BM25 одразу токенізує грецьку, кирилицю, іврит, арабську та латиницю з діакритикою. Для пам'яті китайською / японською / корейською встановіть опційні сегментатори (`npm install @node-rs/jieba tiny-segmenter`), щоб розбивати послідовності CJK на токени рівня слів; без них agentmemory плавно переходить на токенізацію цілими послідовностями та одноразово виводить підказку в stderr. ### Постачальники ембедингів Встановлення без ключа вимикають векторні ембединги: `mem::search` використовує BM25, тоді як `smart-search` також може використовувати наявні структурні дані графа. Щоб безкоштовно підключити семантичні ембединги на пристрої, додайте це до `~/.agentmemory/.env` і перезапустіть agentmemory: ```env EMBEDDING_PROVIDER=local ``` Звичайне встановлення npm включає опційний рантайм `@huggingface/transformers`. Перший запит ембединга завантажує `Xenova/all-MiniLM-L6-v2`, тому потребує доступу до мережі й може займати більше часу; подальші обчислення виконуються на пристрої. Віддалені постачальники автоматично визначаються за їхніми ключами, якщо `EMBEDDING_PROVIDER` не перевизначає їх. | Постачальник | Модель | Вартість | Примітки | |---|---|---|---| | **Локальний (рекомендоване підключення)** | `all-MiniLM-L6-v2` | Безкоштовно | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | Gemini | `gemini-embedding-001` | Безкоштовний тариф | 100+ мов, 768/1536/3072 вимірів (MRL), вхід до 2048 токенів. Замінює `text-embedding-004` ([застаріла, вимкнення 14 січня 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` | Платно | Оптимізовано для коду | | Cohere | `embed-english-v3.0` | Безкоштовна пробна версія | Загального призначення | | OpenRouter | Будь-яка модель | Залежить | Проксі для декількох моделей | ---

MCP-сервер

54 інструменти, 6 ресурсів, 3 промпти та 17 скілів. > **MCP-шим проти повного сервера:** опублікований пакет `@agentmemory/mcp` — це тонкий шим. Він надає повну поверхню з 54 інструментів **лише тоді, коли може дістатися запущеного сервера agentmemory** через `AGENTMEMORY_URL` (режим проксі). Якщо жоден сервер недоступний, шим переходить на локальний набір із 7 інструментів (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Змінна середовища `AGENTMEMORY_TOOLS=core|all` — це прапорець *на боці сервера*; встановлення його в блоці `env` шима не має ефекту. Якщо ви бачите лише 7 інструментів у Cursor / OpenCode / Gemini CLI, запустіть `npx -y @agentmemory/agentmemory@latest` (або стек Docker) і встановіть `AGENTMEMORY_URL=http://localhost:3111`. ### 54 інструменти Три поверхні інструментів, від найменшої до найбільшої: `AGENTMEMORY_TOOLS=core` обмежує видимість до 8 основних (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); базовий набір нижче — це 14 фундаментальних інструментів реєстру; типовий режим (`AGENTMEMORY_TOOLS=all`) надає всі 54.
Базові інструменти (14) | Інструмент | Опис | |------|-------------| | `memory_recall` | Пошук минулих спостережень | | `memory_compress_file` | Стиснення markdown-файлів зі збереженням структури | | `memory_save` | Збереження інсайту, рішення або шаблону | | `memory_file_history` | Минулі спостереження щодо конкретних файлів | | `memory_patterns` | Виявлення повторюваних шаблонів | | `memory_sessions` | Перелік останніх сесій | | `memory_smart_search` | Гібридний семантичний + ключовий пошук | | `memory_vision_search` | Пошук спостережень із зображеннями | | `memory_timeline` | Хронологічні спостереження | | `memory_profile` | Профіль проєкту (концепти, файли, шаблони) | | `memory_export` | Експорт усіх даних пам'яті | | `memory_relations` | Запит графа зв'язків | | `memory_commit_lookup` | Сесії, що стоять за git-комітом | | `memory_commits` | Коміти, записані для сесії |
Розширені інструменти (54 загалом, типова поверхня) | Інструмент | Опис | |------|-------------| | `memory_patterns` | Виявлення повторюваних шаблонів | | `memory_timeline` | Хронологічні спостереження | | `memory_relations` | Запит графа зв'язків | | `memory_graph_query` | Обхід графа знань | | `memory_consolidate` | Запуск 4-рівневої консолідації | | `memory_claude_bridge_sync` | Синхронізація з MEMORY.md | | `memory_team_share` | Поширення серед членів команди | | `memory_team_feed` | Останні спільні елементи | | `memory_audit` | Журнал аудиту операцій | | `memory_governance_delete` | Видалення з журналом аудиту | | `memory_snapshot_create` | Знімок із версіюванням Git | | `memory_action_create` | Створення робочих елементів із залежностями | | `memory_action_update` | Оновлення статусу дії | | `memory_frontier` | Неблоковані дії, ранжовані за пріоритетом | | `memory_next` | Єдина найважливіша наступна дія | | `memory_lease` | Ексклюзивні оренди дій (мультиагентність) | | `memory_routine_run` | Інстанціювання рутин робочого процесу | | `memory_signal_send` | Обмін повідомленнями між агентами | | `memory_signal_read` | Читання повідомлень із підтвердженнями | | `memory_checkpoint` | Зовнішні умовні ворота | | `memory_mesh_sync` | P2P-синхронізація між інстансами | | `memory_sentinel_create` | Вартові на основі подій | | `memory_sentinel_trigger` | Зовнішнє спрацювання вартових | | `memory_sketch_create` | Ефемерні графи дій | | `memory_sketch_promote` | Підвищення до постійного стану | | `memory_crystallize` | Компактування ланцюжків дій | | `memory_diagnose` | Перевірки стану здоров'я | | `memory_heal` | Автовиправлення застряглого стану | | `memory_facet_tag` | Теги вимір:значення | | `memory_facet_query` | Запит за фасетними тегами | | `memory_verify` | Простеження походження |
### 6 ресурсів · 3 промпти · 17 скілів | Тип | Назва | Опис | |------|------|-------------| | Ресурс | `agentmemory://status` | Стан здоров'я, кількість сесій, кількість записів пам'яті | | Ресурс | `agentmemory://project/{name}/profile` | Аналітика для конкретного проєкту | | Ресурс | `agentmemory://project/{name}/recent` | Останні спостереження для проєкту | | Ресурс | `agentmemory://memories/latest` | 10 останніх активних записів пам'яті | | Ресурс | `agentmemory://graph/stats` | Статистика графа знань | | Ресурс | `agentmemory://team/{id}/profile` | Спільний командний профіль | | Промпт | `recall_context` | Пошук + повернення контекстних повідомлень | | Промпт | `session_handoff` | Передача даних між агентами | | Промпт | `detect_patterns` | Аналіз повторюваних шаблонів | | Скіл | `/recall` | Пошук у пам'яті | | Скіл | `/remember` | Збереження в довгострокову пам'ять | | Скіл | `/session-history` | Підсумки останніх сесій | | Скіл | `/forget` | Видалення спостережень/сесій | У таблиці показано чотири основні скіли. Повний набір — це 9 викликаних скілів плюс 8 довідкових скілів; див. розділ про нативні скіли вище. ### Автономний MCP Запуск без повного сервера, для будь-якого MCP-клієнта. Працює будь-який із варіантів: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` Або додайте до конфігурації MCP вашого агента: Більшість агентів (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` Об'єднайте запис `agentmemory` з наявним об'єктом `mcpServers` вашого хоста, а не замінюйте файл. Для клієнтів у sandbox, які не можуть дістатися `localhost` хоста, додайте `"AGENTMEMORY_FORCE_PROXY": "1"` до блоку env та встановіть у `AGENTMEMORY_URL` маршрут, до якого sandbox може дістатися. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` Скопіюйте файл плагіна з репозиторію: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

Переглядач у реальному часі

Автоматично запускається на порту `3113`. Переглядач завантажує один знімок під час підключення (`GET /agentmemory/viewer/snapshot`), а потім застосовує події живого потоку: нові записи пам'яті, уроки, спостереження, записи аудиту, зміни графа та оновлення стану здоров'я з'являються без опитування чи перезавантаження сторінки. Інші запити — лише ті дії, які ви клацаєте, сторінки «завантажити ще» та пошукові запити. Коли потік перериваться, переглядач показує, наскільки застарілими є його дані, перепідключається з наростанням інтервалу (backoff) і повторно синхронізується з одного знімка. - **12 вкладок у чотирьох групах** із показниками в реальному часі, глибокими посиланнями (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), клавіатурними скороченнями та мобільним меню. - **Memories (Пам'ять):** пошук на стороні сервера, фільтри за проєктом, агентом і типом, панель деталей із ланцюжком версій і порівнянням слів, посилання на походження, кнопки копіювання для id, виклику MCP та команди curl, редагування (нова версія), забування з підтвердженням, масове забування та експорт у JSON. - **Sessions (Сесії):** вбудована часова шкала спостережень із читабельними вхідними та вихідними даними інструментів, фільтри та пагінація, а також записи пам'яті та уроки, створені кожною сесією. - **Graph (Граф):** пошук, деталі вузла зі зв'язками та джерелами, легенда, що не покладається лише на колір, та керування масштабом. - **Health (Стан здоров'я):** жива версія `GET /agentmemory/status`. Кожна проблема супроводжується своїм виправленням, а також бекендом стану, станом збереження індексу, прогресом компактування походження графа та поясненням консолідації з реальними порогами. - Сторінки **Audit (Аудит), Activity (Активність), Profile (Профіль), Replay (Відтворення), Lessons (Уроки), Actions (Дії) та Crystals (Кристали)**, кожна з порожнім станом, що пояснює, що це за розділ, чому він порожній і яка команда заповнить його, а також підказка-глосарій `?` для кожного терміну і числа. ```bash open http://localhost:3113 ``` Сервер переглядача за замовчуванням прив'язується до `127.0.0.1` і додає серверний секрет, коли переадресовує запити до REST API, тож він не потребує налаштування. Ендпоінт `/agentmemory/viewer`, що обслуговується через REST, дотримується звичайних правил bearer-токена і переспрямовує браузери без токена на порт переглядача. Заголовки CSP використовують nonce скрипту для кожної відповіді та вимикають атрибути вбудованих обробників (`script-src-attr 'none'`). ---

Конфігурація

### Постачальники LLM agentmemory автоматично визначає постачальників із вашого середовища. Постачальник робить доступними операції на основі LLM, але сама лише конфігурація постачальника не вмикає стиснення спостережень, написане LLM. Цей шлях потребує як постачальника, так і `AGENTMEMORY_AUTO_COMPRESS=true`. | Постачальник | Конфігурація | Примітки | |----------|--------|-------| | **No-op (за замовчуванням)** | Конфігурація не потрібна | Стиснення/підсумовування на основі LLM вимкнено. Синтетичне стиснення та пригадування через BM25 все ще працюють. Див. `AGENTMEMORY_ALLOW_AGENT_SDK` нижче, якщо ви раніше покладалися на запасний варіант через підписку Claude. | | Anthropic API | `ANTHROPIC_API_KEY` | Оплата за токен | | MiniMax | `MINIMAX_API_KEY` | Сумісний з Anthropic | | Gemini | `GEMINI_API_KEY` | Також увімкає ембединги | | OpenRouter | `OPENROUTER_API_KEY` | Будь-яка модель | | OpenAI API | `OPENAI_API_KEY` | За замовчуванням `gpt-5.6-luna`, перевизначте через `OPENAI_MODEL` | | **Локальний (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) або `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Усе, що сумісне з OpenAI API. Нульова вартість, працює на вашому обладнанні. Див. [Локальні моделі](#local-models-ollama--lm-studio--vllm) нижче. | | Запасний варіант через підписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Лише за явним підключенням. Породжує сесії `@anthropic-ai/claude-agent-sdk`; раніше це спричиняло необмежену рекурсію хука Stop, тож більше не є значенням за замовчуванням. | ### Локальні моделі (Ollama / LM Studio / vLLM) agentmemory спілкується з будь-яким сервером, сумісним з OpenAI API, тож усе, що надає `/v1/chat/completions`, працює без змін у коді. Без платних ключів, без хмари, без обмежень частоти запитів; працює повністю на вашому обладнанні. **Ollama** (порт за замовчуванням `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** (порт за замовчуванням `1234`): Відкрийте LM Studio → вкладка Local Server → Start Server. Оберіть будь-яку чат-модель із переліку (Qwen 3, gpt-oss, DeepSeek R1 тощо). ```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**: той самий формат. Вкажіть у `OPENAI_BASE_URL` URL, який надає ваш сервер, і встановіть у `OPENAI_MODEL` назву, яку прийме ваш сервер. **Вибір моделей для роботи з пам'яттю**: стиснення та підсумовування — це короткі завдання (<2K токенів на вхід, <500 токенів на вихід), для яких цілком достатньо 7B instruct-моделі. Рекомендації: | Модель | Розмір | Чому | |-------|------|-----| | `qwen3:8b` | ~5.2 ГБ | Збалансований варіант за замовчуванням на машині з 16 ГБ; сильна у видобуванні та тексті, схожому на виклики інструментів | | `qwen3:4b` | ~2.6 ГБ | Найменший розумний варіант; підходить для стиснення, слабша для видобування графа | | `qwen3-coder:30b` | ~19 ГБ | Найкращий локальний вибір для сесій, орієнтованих на код (30B MoE, 3.3B активних) на обладнанні з 24-32 ГБ | | `gpt-oss:20b` | ~14 ГБ | Сильна загальна модель, що вписується в 16 ГБ RAM | | `deepseek-r1:8b` | ~5.2 ГБ | Дистиляція з міркуванням; повільніша, але чистіше видобування | Моделі Qwen 3 за замовчуванням «думають» і можуть витратити весь бюджет токенів на міркування ще до будь-якого виводу. Встановіть `AGENTMEMORY_LLM_NOTHINK=1`, щоб додавати `/no_think` до промптів видобування графа, і підвищте `MAX_TOKENS` (підходить 16384), якщо видобування повертається порожнім. Моделі класу reasoning (у стилі `o1` з блоками ``) можуть повертати порожній `content` із полем `reasoning`, яке ваш локальний сервер може не показувати. Якщо видобування повертається порожнім, спершу переключіться на модель без reasoning. Змінна середовища `OPENAI_REASONING_EFFORT=none` також може вимикати «мислення» на моделях Ollama Cloud, що дзеркалять схему reasoning OpenAI. Локальні ембединги постачаються як опційна залежність, але не увімкнені за замовчуванням. Встановіть `EMBEDDING_PROVIDER=local`, щоб підключити `Xenova/all-MiniLM-L6-v2` (384 вимірів). Перший запит ембединга завантажує модель; надалі обчислення виконуються на пристрої. Без цього налаштування або віддаленого ключа ембедингів вектори залишаються вимкненими, `mem::search` використовує BM25, а `smart-search` все одно може додавати наявні збіги графа. ### Вибір моделі з урахуванням вартості Почніть без ключа для захоплення й пошуку за словами. `EMBEDDING_PROVIDER=local` вмикає локальний семантичний пошук після завантаження моделі. Стиснення LLM потребує постачальника й `AGENTMEMORY_AUTO_COMPRESS=true`; запит можливий для кожного спостереження, тому перевірте поточні ціни. Viewer та `agentmemory status` показують активних постачальників. ### Пам'ять для кількох агентів (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) У мультиагентних конфігураціях, де декілька ролей використовують один сервер agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` позначає кожен запис роллю, яка його зробила. `AGENTMEMORY_AGENT_SCOPE` контролює, чи пригадування фільтрується за цим тегом. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` Два режими: | Режим | Позначає записи | Фільтрує пригадування | Коли використовувати | |------|------------|---------------|-------------| | `shared` (за замовчуванням) | так | ні | Контекст між агентами з журналом аудиту. Architect бачить, що зазначив developer, але кожен рядок записує, хто це сказав. | | `isolated` | так | так | Сувора відокремленість. Architect ніколи не бачить спостережень / записів пам'яті / сесій developer. | Що позначається, коли встановлено `AGENT_ID`: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Роль проходить шлях від `api::session::start` → `mem::observe` → `mem::compress` → KV. Що фільтрується в ізольованому режимі: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Кожен ендпоінт приймає `?agentId=` для перевизначення для конкретного запиту та `?agentId=*`, щоб повністю вийти зі скоупу змінної середовища. `/memories` також приймає `?includeOrphans=true`, щоб показати записи пам'яті до появи AGENT_ID, чий `agentId` не визначено. Перевизначення для кожного виклику на рівні SDK / REST: кожен змінювальний ендпоінт (`/session/start`, `/remember`) приймає поле `agentId` у тілі запиту, яке переважає над змінною середовища. Корисно для рантаймів, що маршрутизують багато ролей через один серверний процес. Інструмент MCP `memory_save` надає те саме поле `agentId`, автономний stdio-сервер передає як `agentId`, так і `project`, а збережені записи пам'яті несуть `agentId` у пошуковий індекс, тож пошук у межах скоупу агента охоплює як записи пам'яті, так і спостереження. Коли `AGENT_ID` не встановлено, пам'ять залишається без скоупу (застаріла поведінка, без тегів, без фільтрів). ### Порти | Port | Призначення | Змінна середовища | |---|---|---| | `3111` | REST API, MCP HTTP і живі події viewer | `III_REST_PORT` | | `3113` | Інтерфейс viewer | `III_VIEWER_PORT` | `--port ` задає REST-порт, а viewer типово використовує `N+2`. `--instance N` створює окреме середовище. Внутрішні порти мають залишатися приватними; перед зовнішнім доступом прочитайте [посібник з розгортання](../deploy/README.md). ### Сховище: файл або Redis Типове файлове сховище не потребує окремої бази. Redis вмикається через `AGENTMEMORY_STATE_BACKEND=redis` і `AGENTMEMORY_REDIS_URL`. Зміна бекенду не переносить пам’ять. Надійність запису, обмеження Redis та автентифікований експорт/імпорт описано в [посібнику зі зберігання](../docs/reliability/state-storage.md). ### Файл конфігурації Зберігайте конфігурацію runtime у `~/.agentmemory/.env`, а не експортуйте змінні в кожній shell. Змінні середовища процесу мають пріоритет над файлом. Після зміни налаштувань перезапустіть сервер. `%USERPROFILE%\.agentmemory\.env` ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` Щоб протестувати з підпискою Claude Code Pro/Max замість API-ключа, підключіться явно: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` Стиснення спостережень, написане LLM, потребує обох рядків: доступу до постачальника LLM (включно з цим явним запасним варіантом через підписку) та `AGENTMEMORY_AUTO_COMPRESS=true`. Сам лише постачальник залишає типовий шлях синтетичного стиснення без змін. Консолідація (вузли графа, уроки, кристали) увімкнена за замовчуванням, коли налаштовано постачальника LLM. Явно відмовтеся за допомогою `CONSOLIDATION_ENABLED=false`, якщо хочете роботи без LLM. Видобування графа — це окремий прапорець: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### Змінні середовища Основні параметри `~/.agentmemory/.env`. Додавання контексту й стиснення вмикаються явно; стиснення також потребує постачальника. Режим `core` обмежує видимі інструменти 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 ``` Повний довідник [`.env.example`](../.env.example) містить постачальників, фільтри захоплення, строки зберігання, сховище, команди й додаткові функції. `AGENTMEMORY_ENV_FILE` вибирає інший файл. Ніколи не комітьте заповнений `.env` або bearer-секрет. ---

API

147 ендпоінтів на порту `3111`. REST API за замовчуванням прив'язується до `127.0.0.1`. Захищені ендпоінти вимагають `Authorization: Bearer `, а ендпоінти синхронізації mesh вимагають явно встановленого `AGENTMEMORY_SECRET` на обох сторонах. **Автентифікацію ввімкнено типово.** Якщо `AGENTMEMORY_SECRET` не задано, під час першого запуску CLI створює випадковий секрет у `~/.agentmemory/secret` з правами `0600` і копіює його також у вибраний каталог даних. Вбудовані клієнти читають його звідти для локального сервера; secret надсилається лише на loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Віддалені клієнти мають отримати secret через власне середовище. Docker self-host і `deploy/` створюють власні секрети. Щоб викликати API вручну: ```bash curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health ``` **Правила запитів для записів.** Запити `POST`, `PUT`, `PATCH` і `DELETE` до REST API та переглядача повинні надсилати `Content-Type: application/json` (параметр `charset` допустимий), коли вони несуть тіло, а заголовок `Origin`, якщо присутній, має бути loopback-джерелом для налаштованого порту REST чи переглядача або бути перелічений у `VIEWER_ALLOWED_ORIGINS` (через кому, наприклад `https://memory.example.com`). Клієнти, що не надсилають заголовок `Origin` (CLI, хуки, MCP, curl, сервер-до-сервера), не впливають на це. Переглядач також приймає власне джерело. **Шляхи до файлів.** Ендпоінти, що читають або записують файли (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), приймають лише шляхи в межах `~/.agentmemory`, каталогу даних інстансу або каталогу, перелічений у `AGENTMEMORY_IMPORT_ROOT` (розділяйте декілька через `:`, або `;` на Windows). `/replay/import-jsonl` також приймає свій типовий `~/.claude/projects`. `/obsidian/export` залишається в межах `AGENTMEMORY_EXPORT_ROOT`, а `/migrate` — в межах `~/.agentmemory`. Символічні посилання розв'язуються перед кожною перевіркою. **Очищення секретів.** API-ключі, bearer-токени, блоки приватних ключів PEM та облікові дані, вбудовані в URL (`scheme://user:password@host`), видаляються перед збереженням тексту, на кожному шляху запису: спостереження, remember, evolve, слоти, уроки, дії, ескізи, сигнали, контрольні точки, імпорти, відтворення jsonl, синхронізація mesh, спільний доступ команди, вивід стиснення та підсумків, кристали й вузли графа.
Основні ендпоінти | Метод | Шлях | Опис | |--------|------|-------------| | `GET` | `/agentmemory/health` | Перевірка стану здоров'я (завжди публічна) | | `GET` | `/agentmemory/status` | Що не так і як це виправити (HTML для браузерів, JSON в інших випадках) | | `GET` | `/agentmemory/viewer/snapshot` | Усе, що показує переглядач, в одній відповіді | | `POST` | `/agentmemory/session/start` | Почати сесію + отримати контекст | | `POST` | `/agentmemory/session/end` | Завершити сесію | | `POST` | `/agentmemory/observe` | Захопити спостереження (див. доставку захоплення нижче) | | `GET` | `/agentmemory/capture` | Вхідна скринька захоплення, dead letters та офлайн-спул | | `POST` | `/agentmemory/capture/retry` | Повторити невдалі захоплення (dead-letter) | | `POST` | `/agentmemory/capture/drain` | Надіслати локальний офлайн-спул зараз | | `POST` | `/agentmemory/smart-search` | Гібридний пошук | | `POST` | `/agentmemory/context` | Згенерувати контекст | | `POST` | `/agentmemory/remember` | Зберегти в довгострокову пам'ять | | `POST` | `/agentmemory/forget` | Видалити спостереження | | `POST` | `/agentmemory/enrich` | Контекст файлу + записи пам'яті + помилки | | `GET` | `/agentmemory/profile` | Профіль проєкту | | `GET` | `/agentmemory/export` | Експортувати всі дані | | `POST` | `/agentmemory/import` | Імпортувати з JSON | | `POST` | `/agentmemory/graph/query` | Запит графа знань | | `POST` | `/agentmemory/graph/compact` | Обрізати завелике походження графа | | `POST` | `/agentmemory/team/share` | Поширити серед команди | | `GET` | `/agentmemory/audit` | Журнал аудиту | Повний перелік ендпоінтів: [Згенерований довідник REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Доставка захоплення.** Хуки надсилають кожне спостереження один раз на `POST /agentmemory/observe` з `eventId`. Це власний id хоста для виклику, якщо корисне навантаження має такий (наприклад, `tool_use_id` Claude Code), інакше — хеш сесії, типу хука, назви інструменту, вхідних і вихідних даних та часової метки хоста. Сервер записує подію у вхідну скриньку захоплення в хранилищі стану, зберігає спостереження, потім видаляє запис зі скриньки. Код статусу повідомляє, що сталося: | Статус | поле `status` | Значення | |---|---|---| | `201` | `accepted` | Збережено. `observationId` — нове спостереження. | | `202` | `accepted` (`state: "retrying"`) | Прийнято, але збереження не вдалося. Сервер повторює спробу, також після перезапуску. | | `200` | `duplicate` | Цей `eventId` уже прийнято раніше. `observationId` — наявне спостереження; нічого нового не зберігається. | | `400` / `422` | `rejected` | Некоректне корисне навантаження, або збереження остаточно не вдалося (подія зберігається як dead letter). | | `503` | `rejected` (`retryable: true`) | Вхідна скринька переповнена (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Хуки заносять подію в спул і надсилають її пізніше. | Невдалі події повторюються кожні `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 с) з подвоюваним відступом, до `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Події, що все ще не вдаються, залишаються у вхідній скриньці як dead letters, перелічуються на `/agentmemory/status` і сторінці Health переглядача, і можуть бути повторені через `POST /agentmemory/capture/retry` (`{"eventId": "..."}` або `{"all": true}`). Прийняті id подій пам'ятаються протягом `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 годин, щонайбільше `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), тож хук, відтворений після таймауту чи перезапуску, зберігається один раз, тоді як два окремі виклики інструменту з власними id хоста зберігаються двічі, навіть якщо їхній вміст ідентичний. Коли спостереження видаляється (forget, видалення сесії, витіснення, автозабування або імпорт, що замінює сховище), його подія позначається як видалена до видалення самого спостереження, тож відтворення цієї події в тому самому вікні відповідається як дублікат і нічого не зберігає. Хранилище стану записує на диск кожні 2 секунди, тож відповідена подія може ще якусь мить залишатися лише в пам'яті. Щоб покрити це, кожна відповідь `2xx` також несе `bootId` сервера (новий під час кожного запуску), `acceptedAt` і `durableAfterMs` (інтервал збереження плюс 1.5 с для файлового сховища, 1.5 с для redis, де стійкість — налаштування оператора). Хуки тримають подію в локальному спулі, доки не минув цей проміжок, і видаляють її під час наступного виклику без додаткового запиту. Якщо `bootId` змінився на той момент, сервер перезапустився, тож хук надсилає подію знову з тим самим `eventId`; подія, яка таки дістала диск, не зберігається двічі. Сервер також сам надсилає такі події під час запуску і кожного інтервалу повторення, тож перезапуск нічого не втрачає, навіть якщо надалі жоден хук не запускається. Старіші хуки ігнорують додаткові поля, а нові хуки проти старішого сервера відкидають подію на `2xx`, як і раніше. Коли сервер не працює, не відповідає вчасно або повертає 5xx, хук додає спостереження до локального файлу спулу, `/capture-spool/-.jsonl` (перевизначте папку через `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Файл приватний для вашого користувача (режим 600), секрети редагуються так само, як їх редагує сервер, він містить щонайбільше `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 МіБ) і відкидає записи, старіші за `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Коли він переповнений, нові записи відкидаються і підраховуються, і `/agentmemory/status` повідомляє про це. Хук все одно завершується з кодом 0 у межах свого часового лімиту і не додає запиту, коли сервер справний. Спул надсилається під час наступного запуску і першим хуком, що знову дістається сервера, у фоновому процесі, тож агент не чекає. Id подій роблять це безпечним: спостереження, яке таки надійшло до таймауту, не зберігається двічі. `npx @agentmemory/agentmemory capture` показує спул і вхідну скриньку сервера, `--drain` надсилає спул зараз, а `GET /agentmemory/capture` повертає те саме як JSON. Встановіть `AGENTMEMORY_CAPTURE_SPOOL=false`, щоб вимкнути спул. **Компактування походження графа.** Компактування старих даних походження відкладається під час запуску, оскільки воно читає старі області повністю. `/agentmemory/status` повідомляє `deferred` або `off`, якщо `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Виконуйте описане нижче ручне компактування під час обслуговування. Міграція пошукового індексу є окремою операцією: використовуйте `agentmemory graph-index migrate --allow-legacy-scan` згідно з [посібником з обслуговування](../docs/reliability/graph-index-migration.md). Щоб запустити це вручну, викличте `POST /agentmemory/graph/compact`. Він обходить індекси імен та ключів ребер, замість перелічування кожного вузла і ребра, і безпечний для повторного запуску. Коли він обрізає id, він записує запис аудиту `graph_compact`. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}' ``` На великому сховищі, або коли виклик повертає 504, запускайте це фрагментами. Надішліть `scope` (`nodes`, `edges` або `history`), `offset` і `limit`, потім викличте знову з поверненим `nextOffset`, доки він не стане `null`. Зробіть це для `nodes`, `edges` та `history`, і завершіть одним викликом `{"scope":"snapshot"}`, тому що фрагментований запуск не торкається кешованого знімка. ```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) ``` Вимоги наведено у [Встановленні](#install). Правила участі й перевірки випуску містяться в [CONTRIBUTING.md](../CONTRIBUTING.md).

Ліцензія

[Apache-2.0](../LICENSE)