#1 Persistent memory for AI coding agents based on real-world benchmarks
Постійна пам’ять між сесіями й агентами розробки.
Постійна пам'ять для 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
Цей gist розширює підхід Karpathy «LLM Wiki», додаючи оцінку довіри, життєвий цикл, графи знань і гібридний пошук: 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 або інструкцію для нативного встановлення.
Канонічна команда для чистого встановлення:
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; каталоги пам’яті й окремі інстанси описано в розділі зберігання даних.
Потім перевірте, що пригадування працює, і дайте агенту його скіли:
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 <agent>. Див. інтеграції та щоденні команди.
Глобальне встановлення / EACCES
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 нативний плагін + 12 хуків + MCP |
Codex CLI нативний плагін + 6 хуків + MCP |
GitHub Copilot CLI MCP + хуки/скіли плагіна |
Cursor нативний плагін + хуки життєвого циклу + MCP |
OpenCode плагін захоплення + MCP |
|
Devin 6 хуків + скіли + MCP |
OpenClaw нативний плагін + MCP |
Hermes нативний плагін + MCP |
pi нативне пригадування + захоплення + скіли |
OpenHuman нативний бекенд на основі трейта Memory |
|
Gemini CLI MCP-сервер |
Antigravity MCP + хуки |
Claude Desktop MCP-сервер |
Warp підключення + MCP + скіли |
Zed MCP-сервер |
|
Cline MCP-сервер |
Continue MCP-сервер |
Droid MCP-сервер |
Kiro MCP-сервер |
Qwen Code MCP-сервер |
|
DeepSeek Harness нативне захоплення + MCP |
Roo Code MCP-сервер |
Kilo Code MCP-сервер |
Goose MCP-сервер |
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 <path> або AGENTMEMORY_DATA_DIR. Зберігайте той самий каталог під час перезапуску й оновлення.
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
--instance 1 використовує підкаталог instance-1, порт API 3211 і viewer 3213. Redis і міграцію описано в посібнику зі зберігання та резервування.
Примітки до останнього релізу: CHANGELOG.md.
Актуальні результати пошуку, визначення метрик і кроки відтворення:
0.9.31 · 2026-10-28 · strict recall-all@5 · eval/README.md.
Оновлене порівняння продуктів і варіантів розгортання з джерелами:
AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem · 2026-10-28.
Спробуйте за 30 секунд
# 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 і стан:
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, інакше завантажте згенерований локальний секрет:
# 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, передайте той самий каталог під час перезапуску.
Щоденні команди
Встановлення та налаштування описані в розділі Встановлення вище (перший запуск проведе вас через цей процес). Щодня:
agentmemory # start the server
agentmemory stop # stop it cleanly
agentmemory status
agentmemory capture
agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
Відтворення сесій
Кожну сесію, яку записує agentmemory, можна відтворити. Відкрийте переглядач, оберіть вкладку Replay і прогортайте часову шкалу: промпти, виклики інструментів, результати інструментів і відповіді відображаються як окремі події з керуванням відтворення/паузи, регулюванням швидкості (від 0.5x до 4x) і клавіатурними скороченнями (пробіл — перемкнути, стрілки — покроково).
Щоб імпортувати старіші JSONL-транскрипти Claude Code:
# 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як на основний шлях захоплення:cleanupPeriodDaysClaude Code (у~/.claude/settings.json, за замовчуванням 30) автоматично видаляє JSONL-транскрипти, старіші за це вікно, з~/.claude/projects/. Якщо ви встановлюєте agentmemory на вже кількамісячну історію Claude Code, усе старіше за 30 днів уже зникло ще до першого імпорту. Або запускайтеimport-jsonlза розкладом (cron), або підвищтеcleanupPeriodDays, або підключіть хуки автозахоплення (типовий шлях встановлення плагіна), щоб кожен крок потрапляв в agentmemory, поки сесія активна, і очищення JSONL більше не мало значення.
Оновлення / обслуговування
Використовуйте команду обслуговування, коли ви свідомо хочете оновити свій локальний рантайм:
npx -y @agentmemory/agentmemory@latest upgrade
Команда оновлює локальне середовище й може змінити JavaScript-залежності поточного workspace. Зробіть резервну копію даних і прочитайте посібник з оновлення.
Claude Code (один блок, вставте як є)
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/…), тому наступне оновлення непомітно зламає кожен хук.
Обхідне рішення:
agentmemory connect claude-code --with-hooks
Ця команда об'єднує ті самі команди хуків у ~/.claude/settings.json, використовуючи абсолютні шляхи, визначені до вбудованого каталогу plugin/ наразі встановленого пакета @agentmemory/agentmemory. Повторно запустіть команду після оновлення agentmemory, щоб оновити шляхи. Записи користувача в тому самому файлі зберігаються; замінюються лише попередні записи agentmemory. Шлях через /plugin install залишається рекомендованим підходом.
Для віддалених або захищених розгортань запускайте Claude Code зі встановленими AGENTMEMORY_URL та AGENTMEMORY_SECRET. Плагін передає обидва значення своєму вбудованому MCP-серверу; якщо AGENTMEMORY_URL порожній, MCP-шим використовує http://localhost:3111.
Codex CLI (платформа плагінів Codex)
# 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, щоб протестувати нерелізну збірку.
- 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), тому ті самі скрипти хуків працюють для обох хостів без дублювання. Події Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure доступні лише для Claude Code і не реєструються для Codex.
Довіра до хуків Codex та сумісність
Нативна диспетчеризація хуків плагіна підтверджена для Codex CLI 0.150.1. Перш ніж очікувати захоплення, підтвердьте довіру до хуків плагіна. Поведінка Codex Desktop залежить від вбудованого в нього середовища виконання; перевірте /hooks і підтвердьте захоплену подію, перш ніж застосовувати обхідне рішення.
Якщо ваш хост вимагає глобальних хуків, продзеркаліть команди у ~/.codex/hooks.json. Якщо MCP уже підключено, поточному конектору потрібен --force, щоб дістатися встановлення хуків:
agentmemory connect codex --with-hooks --force
Це об'єднує глобальні хуки та перезаписує запис MCP agentmemory, зберігаючи незв'язані записи. Перевірте власні налаштування endpoint agentmemory, перш ніж використовувати --force. Запустіть повторно після оновлення, щоб оновити шляхи скриптів. Увімкніть або нативні хуки плагіна, або глобальні копії, щоб уникнути дублювання захоплення.
GitHub Copilot CLI
Для режиму агента VS Code скористайтеся посібником з MCP та автозахоплення Copilot. Конектор CLI не налаштовує VS Code.
# 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
agentmemory connect cursor
Потім у Settings → Plugins → Add marketplace виберіть каталог agentmemory з .cursor-plugin/plugin.json, увімкніть плагін agentmemory і перезавантажте вікно. Плагін забезпечує захоплення життєвого циклу, визначення проєкту за workspace, скіли й MCP. Увімкніть або хуки плагіна, або ручні хуки в ~/.cursor/hooks.json, щоб уникнути дублювання.
Pi, Oh My Pi, DeepSeek Harness
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. Використовуйте один спосіб встановлення на клієнт.
OpenClaw (вставте цей промпт)
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/
Hermes Agent (вставте цей промпт)
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 the agentmemory repo to ~/.hermes/plugins/agentmemory.
Повний посібник: integrations/hermes/
Інші агенти
Запустіть сервер пам'яті: npx -y @agentmemory/agentmemory@latest
Нативні скіли через npx skills add
agentmemory постачає 17 скілів у форматі <dir>/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 від vercel-labs автоматично встановлює їх у нативний каталог скілів агента, що викликає, для понад 50 агентів (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf та інших):
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 <agent>:
agentmemory connect <agent>зазвичай записує конфігурацію 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):
"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. |
| 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:<skill> разом із 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/). Збережіть секрет у 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. |
| 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. |
| 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. |
| pi | ~/.pi/agent/extensions/agentmemory |
agentmemory connect pi --with-mcp. нативне пригадування + захоплення + скіли. /reload, /agentmemory-status. Pi. |
| Oh My Pi | ~/.omp/agent |
agentmemory connect omp --with-mcp. нативне пригадування + захоплення + скіли. Oh My Pi. |
| 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. |
| 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. |
Antigravity CLI (agy) |
~/.gemini/config/mcp_config.json |
agentmemory connect antigravity-cli --with-hooks використовує ту саму конфігурацію MCP і хуків, що й поточні версії IDE. Наявні встановлення слід оновити за допомогою --force; див. примітки щодо оновлення. |
| 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. Перевизначення на рівні проєкту розміщуються в <repo>/.factory/mcp.json. Передайте --with-hooks для нативного автозахоплення. |
| DeepSeek Harness | $DSH_HOME/cordis.patch.yml |
agentmemory connect dsh вмикає інструменти MCP. Додайте --with-hooks, щоб завантажити вбудований в AgentMemory плагін запису подій. Окремий пакет плагіна не потрібен. DSH. |
| Goose | Інтерфейс налаштувань MCP Goose | Той самий блок mcpServers; скористайтеся goose configure → Add Extension → MCP. Пряме редагування YAML у ~/.config/goose/config.yaml підтримується, але схема використовує extensions: + cmd (а не mcpServers: + command). |
| Aider | н/д | Для збереження й пошуку зі скриптів використовуйте REST-приклади з автентифікацією. |
| Підтримувані агенти | Лише скіли | 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 з будь-якої мови або інструменти MCP з агента. REST використовує JSON і bearer-автентифікацію; див. приклад збереження й пошуку. Пряму інтеграцію середовища показано в прикладах Python.
Зі джерельного коду
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
npm start запускає той самий локальний сервер, що й встановлений CLI. Вимоги наведено у Встановленні; API та viewer слухають 127.0.0.1.
Windows
agentmemory працює у Windows 10/11; WSL2 може автоматично встановити engine. Нативна Windows потребує ручного встановлення iii-engine v0.25.0: завантажте архів зі сторінки iii v0.25.0, перевірте checksum і розмістіть iii.exe у PATH. CLI не розпаковує ZIP автоматично
Автоматичне налаштування MCP у нативній Windows підтримує лише agentmemory connect copilot-cli; для інших скористайтеся Other agents. У WSL виконуйте connect, лише якщо агент встановлений у тому самому середовищі
Лише standalone MCP без engine. Якщо не потрібні REST API, переглядач і служби runtime:
npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp
Запустіть agentmemory doctor або перезапустіть із --verbose. Якщо порти зайняті, використовуйте --port <N> або --instance <N>. Сумісність і відновлення описано в посібнику з оновлення.
Розгортання
Для власного розгортання використовуйте Docker Compose або шаблони нижче. Пам’ять і облікові дані містяться на томі /data; резервуйте його й використовуйте повторно під час оновлення. Автентифікацію, мережу, резервування та міграцію описано в посібнику з розгортання.
Кнопка розгортання в один клік для Render вимагає render.yaml у корені репозиторію, який ми свідомо тримаємо чистим. Скористайтеся процесом Render Blueprint, описаним у ../deploy/render/, щоб вручну вказати на blueprint усередині репозиторію.
Повні деталі налаштування (захоплення HMAC, SSH-тунель для переглядача, ротація, резервне копіювання,
мінімальна вартість) містяться в ../deploy/:
../deploy/fly: одна машина зauto_stop_machines = "stop"; найдешевший варіант у режимі очікування.../deploy/railway: фіксована плата тарифу Hobby, том у панелі керування.../deploy/render: процес Blueprint, автоматичні знімки диска на платних тарифах.../deploy/coolify: самостійний хостинг на власному VPS через Coolify; той самий Docker Compose-стек, хост і дані залишаються у вас.
REST використовує 3111, viewer 3113. Залиште їх у приватній мережі або захистіть автентифікацією й TLS. Налаштування платформ і міграцію старого Docker описано в посібнику з розгортання.
Знання про проєкт розподілені між чатами й файлами інструкцій. AgentMemory дає змогу шукати попередні рішення, виправлення та уроки з поточного агента.
Порівняно з вбудованою пам'яттю агента
Кожен AI-агент кодування постачається з вбудованою пам'яттю: у Claude Code є MEMORY.md, у Cursor — notepads, у Cline — memory bank. Вони працюють як стікери-нагадування. agentmemory — це база даних із можливістю пошуку, що стоїть за цими стікерами.
| Вбудована (CLAUDE.md) | agentmemory | |
|---|---|---|
| Обслуговування | Інструкції, редаговані вручну | Індексована історія сесій і спогади |
| Пошук | Завантажує все у контекст | BM25 + вектор + граф (лише топ-K) |
| Між агентами | Файли для кожного агента | MCP + REST (будь-який агент) |
| Координація | Немає | Оренди, сигнали, дії, рутини |
| Спостережуваність | Читання файлів вручну | Переглядач у реальному часі на :3113 |
Конвеєр пам'яті
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-ключі, секрети, теги <private> видаляються перед збереженням |
| Самовідновлення | 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.
BM25 одразу токенізує грецьку, кирилицю, іврит, арабську та латиницю з діакритикою. Для пам'яті китайською / японською / корейською встановіть опційні сегментатори (npm install @node-rs/jieba tiny-segmenter), щоб розбивати послідовності CJK на токени рівня слів; без них agentmemory плавно переходить на токенізацію цілими послідовностями та одноразово виводить підказку в stderr.
Постачальники ембедингів
Встановлення без ключа вимикають векторні ембединги: mem::search використовує BM25, тоді як smart-search також може використовувати наявні структурні дані графа. Щоб безкоштовно підключити семантичні ембединги на пристрої, додайте це до ~/.agentmemory/.env і перезапустіть agentmemory:
EMBEDDING_PROVIDER=local
Звичайне встановлення npm включає опційний рантайм @huggingface/transformers. Перший запит ембединга завантажує Xenova/all-MiniLM-L6-v2, тому потребує доступу до мережі й може займати більше часу; подальші обчислення виконуються на пристрої. Віддалені постачальники автоматично визначаються за їхніми ключами, якщо EMBEDDING_PROVIDER не перевизначає їх.
| Постачальник | Модель | Вартість | Примітки |
|---|---|---|---|
| Локальний (рекомендоване підключення) | all-MiniLM-L6-v2 |
Безкоштовно | EMBEDDING_PROVIDER=local |
| Gemini | gemini-embedding-001 |
Безкоштовний тариф | 100+ мов, 768/1536/3072 вимірів (MRL), вхід до 2048 токенів. Замінює text-embedding-004 (застаріла, вимкнення 14 січня 2026) |
| OpenAI | text-embedding-3-small |
OpenAI | text-embedding-3-small |
| Voyage AI | voyage-code-3 |
Платно | Оптимізовано для коду |
| Cohere | embed-english-v3.0 |
Безкоштовна пробна версія | Загального призначення |
| OpenRouter | Будь-яка модель | Залежить | Проксі для декількох моделей |
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-клієнта. Працює будь-який із варіантів:
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):
{
"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):
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
Скопіюйте файл плагіна з репозиторію:
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/<id>,#sessions/<id>?obs=<id>,#graph/<id>,#health/consolidation), клавіатурними скороченнями та мобільним меню. - Memories (Пам'ять): пошук на стороні сервера, фільтри за проєктом, агентом і типом, панель деталей із ланцюжком версій і порівнянням слів, посилання на походження, кнопки копіювання для id, виклику MCP та команди curl, редагування (нова версія), забування з підтвердженням, масове забування та експорт у JSON.
- Sessions (Сесії): вбудована часова шкала спостережень із читабельними вхідними та вихідними даними інструментів, фільтри та пагінація, а також записи пам'яті та уроки, створені кожною сесією.
- Graph (Граф): пошук, деталі вузла зі зв'язками та джерелами, легенда, що не покладається лише на колір, та керування масштабом.
- Health (Стан здоров'я): жива версія
GET /agentmemory/status. Кожна проблема супроводжується своїм виправленням, а також бекендом стану, станом збереження індексу, прогресом компактування походження графа та поясненням консолідації з реальними порогами. - Сторінки Audit (Аудит), Activity (Активність), Profile (Профіль), Replay (Відтворення), Lessons (Уроки), Actions (Дії) та Crystals (Кристали), кожна з порожнім станом, що пояснює, що це за розділ, чому він порожній і яка команда заповнить його, а також підказка-глосарій
?для кожного терміну і числа.
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=<your model> |
Усе, що сумісне з OpenAI API. Нульова вартість, працює на вашому обладнанні. Див. Локальні моделі нижче. |
| Запасний варіант через підписку Claude | AGENTMEMORY_ALLOW_AGENT_SDK=true |
Лише за явним підключенням. Породжує сесії @anthropic-ai/claude-agent-sdk; раніше це спричиняло необмежену рекурсію хука Stop, тож більше не є значенням за замовчуванням. |
Локальні моделі (Ollama / LM Studio / vLLM)
agentmemory спілкується з будь-яким сервером, сумісним з OpenAI API, тож усе, що надає /v1/chat/completions, працює без змін у коді. Без платних ключів, без хмари, без обмежень частоти запитів; працює повністю на вашому обладнанні.
Ollama (порт за замовчуванням 11434):
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
# ~/.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 тощо).
# ~/.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 з блоками <think>) можуть повертати порожній 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 контролює, чи пригадування фільтрується за цим тегом.
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=<role> для перевизначення для конкретного запиту та ?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 <N> задає REST-порт, а viewer типово використовує N+2. --instance N створює окреме середовище. Внутрішні порти мають залишатися приватними; перед зовнішнім доступом прочитайте посібник з розгортання.
Сховище: файл або Redis
Типове файлове сховище не потребує окремої бази. Redis вмикається через AGENTMEMORY_STATE_BACKEND=redis і AGENTMEMORY_REDIS_URL. Зміна бекенду не переносить пам’ять. Надійність запису, обмеження Redis та автентифікований експорт/імпорт описано в посібнику зі зберігання.
Файл конфігурації
Зберігайте конфігурацію runtime у ~/.agentmemory/.env, а не експортуйте змінні в кожній shell.
Змінні середовища процесу мають пріоритет над файлом. Після зміни налаштувань перезапустіть сервер.
%USERPROFILE%\.agentmemory\.env
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
Щоб протестувати з підпискою Claude Code Pro/Max замість API-ключа, підключіться явно:
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
Стиснення спостережень, написане LLM, потребує обох рядків: доступу до постачальника LLM (включно з цим явним запасним варіантом через підписку) та AGENTMEMORY_AUTO_COMPRESS=true. Сам лише постачальник залишає типовий шлях синтетичного стиснення без змін.
Консолідація (вузли графа, уроки, кристали) увімкнена за замовчуванням, коли налаштовано постачальника LLM. Явно відмовтеся за допомогою CONSOLIDATION_ENABLED=false, якщо хочете роботи без LLM. Видобування графа — це окремий прапорець:
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
Змінні середовища
Основні параметри ~/.agentmemory/.env. Додавання контексту й стиснення вмикаються явно; стиснення також потребує постачальника. Режим core обмежує видимі інструменти MCP:
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 містить постачальників, фільтри захоплення, строки зберігання, сховище, команди й додаткові функції. AGENTMEMORY_ENV_FILE вибирає інший файл. Ніколи не комітьте заповнений .env або bearer-секрет.
146 ендпоінтів на порту 3111. REST API за замовчуванням прив'язується до 127.0.0.1. Захищені ендпоінти вимагають Authorization: Bearer <secret>, а ендпоінти синхронізації 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 вручну:
curl -H "Authorization: Bearer <secret-from-data-dir>" 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
Доставка захоплення. Хуки надсилають кожне спостереження один раз на 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, хук додає спостереження до локального файлу спулу, <data dir>/capture-spool/<host>-<port>.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 згідно з посібником з обслуговування.
Щоб запустити це вручну, викличте POST /agentmemory/graph/compact. Він обходить індекси імен та ключів ребер, замість перелічування кожного вузла і ребра, і безпечний для повторного запуску. Коли він обрізає id, він записує запис аудиту graph_compact.
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{}'
На великому сховищі, або коли виклик повертає 504, запускайте це фрагментами. Надішліть scope (nodes, edges або history), offset і limit, потім викличте знову з поверненим nextOffset, доки він не стане null. Зробіть це для nodes, edges та history, і завершіть одним викликом {"scope":"snapshot"}, тому що фрагментований запуск не торкається кешованого знімка.
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
npm run dev # Hot reload
npm run build # Production build
npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
Вимоги наведено у Встановленні. Правила участі й перевірки випуску містяться в CONTRIBUTING.md.