#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
Этот гист расширяет шаблон LLM Wiki от Karpathy: оценкой уверенности, жизненным циклом, графами знаний и гибридным поиском — 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 может также сливать структурные совпадения из графа, если граф-данные уже существуют. Чтобы получить бесплатный семантический recall на устройстве, задайте EMBEDDING_PROVIDER=local в ~/.agentmemory/.env и перезапустите. Первый запрос эмбеддинга скачивает Xenova/all-MiniLM-L6-v2; после этой первоначальной загрузки модели инференс выполняется локально.
API доступен по http://localhost:3111, viewer по http://localhost:3113. По умолчанию оба слушают только локальные подключения. Настройки находятся в ~/.agentmemory/.env; каталоги памяти и отдельные экземпляры описаны в разделе хранения данных.
Затем убедитесь, что recall работает, и дайте агенту его skill'ы:
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>. См. интеграции и повседневные команды.
Global install / 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 + хуки/skill'ы плагина |
Cursor нативный плагин + хуки жизненного цикла + MCP |
OpenCode плагин захвата + MCP |
|
Devin 6 хуков + skill'ы + MCP |
OpenClaw нативный плагин + MCP |
Hermes нативный плагин + MCP |
pi нативное извлечение + захват + skills |
OpenHuman нативный бэкенд трейта Memory |
|
Gemini CLI MCP-сервер |
Antigravity MCP + хуки |
Claude Desktop MCP-сервер |
Warp connect + MCP + skill'ы |
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 нативное извлечение + захват + skills + 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-запроса, rate limiting) и запускает по ним поиск. Установки без ключей отключают векторы, поэтому запросы по ключевым словам 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, снова запустите каноническую команду в Terminal 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 и пролистывайте таймлайн: промпты, вызовы инструментов, результаты вызовов и ответы отображаются как отдельные события с play/pause, регулировкой скорости (от 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— ваш основной путь захвата: параметрcleanupPeriodDaysв Claude Code (в~/.claude/settings.json, по умолчанию 30) автоматически удаляет JSONL-расшифровки старше этого окна из~/.claude/projects/. Если вы ставите agentmemory заново на историю Claude Code возрастом в несколько месяцев, всё, что старше 30 дней, уже пропало до первого импорта. Либо запускайтеimport-jsonlпо cron, либо поднимитеcleanupPeriodDays, либо подключите хуки авто-захвата (путь установки плагина по умолчанию), чтобы каждый ход попадал в agentmemory ещё во время живой сессии — тогда очистка JSONL перестаёт иметь значение.
Обновление / обслуживание
Используйте команду обслуживания, когда намеренно хотите обновить локальный runtime:
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-standalone)
Если подключать 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-shim использует 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 вызываемых skills:
/recall,/remember,/session-history,/forget,/recap,/handoff,/lesson,/commit-context,/commit-history, плюс 8 справочных skills, которые агент загружает по запросу (memory discipline, инструменты MCP, REST API, конфигурация, агенты, хуки, архитектура и руководство по написанию skills)
Хук-движок 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 зависит от встроенного в него runtime; проверьте /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
# Альтернативно, полный плагин хуков/skill'ов из 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. Установите также плагин, если хотите полный опыт с хуками/skill'ами.
Cursor
agentmemory connect cursor
Затем в Settings → Plugins → Add marketplace выберите каталог agentmemory с .cursor-plugin/plugin.json, включите плагин agentmemory и перезагрузите окно. Плагин обеспечивает захват жизненного цикла, определение проекта по workspace, skills и 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 устанавливают нативное извлечение памяти, захват, повторную отправку офлайн-данных и skills; --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
Нативные skill'ы через npx skills add
agentmemory поставляет 17 skill'ов в формате <dir>/SKILL.md в стиле Claude Code: 9 вызываемых action-skill'ов (remember, recall, recap, handoff, forget, lesson, commit-context, commit-history, session-history) и 8 справочных skill'ов, которые агент подгружает по мере надобности (memory-discipline, agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-config, agentmemory-agents, agentmemory-hooks, agentmemory-architecture, write-agentmemory-skill). Справочные skill'ы содержат таблицы данных, сгенерированные из исходников, поэтому они никогда не устаревают. CLI skills от vercel-labs автоматически устанавливает их в нативный каталог skill'ов вызывающего агента для 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 по умолчанию устанавливают нативную интеграцию и skills; MCP включается через--with-mcp.npx skills add rohitg00/agentmemoryустанавливает skills для агентов без встроенного набора. Для Hermes, OpenClaw, Pi и Oh My Pi пропустите этот шаг: их коннекторы уже устанавливают skills.
Для немногих агентов, которые skills CLI пока не покрывает (Zed v1.3.x и ниже), разложите 17 файлов SKILL.md по нативному каталогу skill'ов агента самостоятельно; тот же формат работает везде.
Стандартный блок 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 из shell в момент запуска MCP-сервера; незаданные переменные передаются пустыми строками, и shim откатывается на http://localhost:3111. Одна подключённая запись покрывает как локальные, так и удалённые (k8s / reverse-proxied) развёртывания.
| Агент | Файл конфигурации | Заметки |
|---|---|---|
| Cursor (только MCP) | ~/.cursor/mcp.json |
Добавьте в mcpServers, либо используйте agentmemory connect cursor. На сайте также доступен deeplink в один клик. |
| Cursor (полный плагин) | .cursor-plugin/ |
Плагин предоставляет хуки жизненного цикла, определение workspace, skills и 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 подключает шесть нативных hooks автозахвата (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) с матчерами инструментов Devin в нижнем регистре. Проверьте через devin mcp list и /hooks внутри devin. |
| Devin CLI (полный плагин) | plugin/.devin-plugin/ |
devin plugins install ./plugin из checkout'а регистрирует все 17 skill'ов как slash-команды /agentmemory:<skill> плюс MCP-сервер. Хуки плагина Devin не могут сработать на SessionStart/SessionEnd, поэтому для полного захвата сессии сочетайте это с connect devin --with-hooks. |
| Devin (облако) | Settings → Connections → MCP servers | Добавьте пользовательский MCP (STDIO): command npx, args -y @agentmemory/mcp@latest, env 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 (полный плагин) | Маркетплейс плагинов Codex | codex plugin marketplace add rohitg00/agentmemory, затем codex plugin add agentmemory@agentmemory. Регистрирует MCP + 6 хуков жизненного цикла + 17 skill'ов. Подтвердите доверие к хукам и проверьте захват на вашем хосте; см. установку и проверку Codex. |
| OpenCode (только MCP) | opencode.json |
Другая форма: корневой ключ mcp, команда задаётся массивом: {"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}. |
| OpenCode (полный плагин) | plugin/opencode/ |
22 хука авто-захвата по жизненному циклу сессии, сообщениям, инструментам и ошибкам. Атрибуция проекта задаётся на уровне сессии, поэтому один процесс OpenCode, охватывающий несколько репозиториев, кладёт каждую сессию в её собственный проект. Две slash-команды (/recall, /remember). Скопируйте plugin/opencode/ в свой рабочий каталог OpenCode и добавьте запись плагина в opencode.json. Полная таблица хуков и анализ пробелов — в plugin/opencode/README.md. |
| pi | ~/.pi/agent/extensions/agentmemory |
agentmemory connect pi --with-mcp. нативное извлечение + захват + skills. /reload, /agentmemory-status. Pi. |
| Oh My Pi | ~/.omp/agent |
agentmemory connect omp --with-mcp. нативное извлечение + захват + skills. 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. Payload хуков по полям совместим с 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 записывает конфиг на уровне пользователя. Переопределения на уровне workspace — в .kiro/settings/mcp.json рядом с кодом. |
| Warp | ~/.warp/.mcp.json |
agentmemory connect warp записывает стандартный блок mcpServers. Warp также автоматически обнаруживает skill'ы из .claude/skills/; как только установлен плагин Claude Code, 9 skill'ов agentmemory (remember, recall, recap, handoff, forget, lesson, commit-context, commit-history, session-history) нативно появляются в палитре slash-команд 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 (legacy) |
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 | UI настроек MCP в Goose | Тот же блок mcpServers; используйте goose configure → Add Extension → MCP. Прямое редактирование YAML в ~/.config/goose/config.yaml поддерживается, но схема использует extensions: + cmd (а не mcpServers: + command). |
| Aider | н/д | Для сохранения и поиска из скриптов используйте REST-примеры с авторизацией. |
| Поддерживаемые агенты | Только skills | npx skills add rohitg00/agentmemory; выберите skills для установки и целевых агентов. |
MCP-клиенты в sandbox (Flatpak / Snap / ограничивающие контейнеры), которые не могут добраться до localhost хоста: дополнительно установите "AGENTMEMORY_FORCE_PROXY": "1" в блоке env и укажите AGENTMEMORY_URL на маршрут, до которого sandbox действительно может дотянуться (например, IP в локальной сети).
Программный доступ (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 используется путь Linux, и закреплённый движок устанавливается автоматически. Для нативной работы в Windows требуется вручную установить закреплённый бинарь iii-engine v0.25.0: скачайте подходящий архив со страницы релиза iii v0.25.0, проверьте контрольную сумму и поместите iii.exe в PATH (например, %USERPROFILE%\.local\bin\iii.exe). CLI не распаковывает Windows ZIP автоматически.
Автоматизированное подключение MCP в нативной Windows поддерживает только agentmemory connect copilot-cli. Для других нативных Windows-агентов используйте ручной блок MCP из раздела Другие агенты. Запускайте connect внутри WSL только если целевой агент установлен в той же среде WSL.
Только standalone MCP (без движка). Если нужны только MCP-инструменты, а 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: self-hosted на собственном VPS через Coolify; тот же стек Docker Compose, хост и данные остаются у вас.
REST использует 3111, viewer 3113. Оставьте их в приватной сети либо защитите авторизацией и TLS. Настройки платформ и миграция старого Docker описаны в руководстве по развёртыванию.
Знания о проекте распределены между чатами и файлами инструкций. AgentMemory позволяет искать прежние решения, исправления и уроки из текущего агента.
vs встроенная память агента
Каждый ИИ-агент программирования поставляется со встроенной памятью: у Claude Code есть MEMORY.md, у Cursor — notepad'ы, у Cline — memory bank. Они работают как стикеры. agentmemory — это индексируемая база данных за этими стикерами.
| Встроенная (CLAUDE.md) | agentmemory | |
|---|---|---|
| Обслуживание | Инструкции, редактируемые вручную | Индексируемая история сессий и воспоминания |
| Поиск | Загружает всё в контекст | BM25 + вектор + граф (только top-K) |
| Между агентами | Файлы на каждого агента | MCP + REST (любой агент) |
| Координация | Нет | Lease'ы, сигналы, action'ы, routine'ы |
| Наблюдаемость | Читать файлы вручную | Просмотрщик в реальном времени на :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 | Workflow'ы и паттерны принятия решений | «Как это сделать» |
Воспоминания затухают со временем (кривая Эббингауза). Часто используемые воспоминания усиливаются. Устаревшие автоматически вытесняются. Противоречия обнаруживаются и разрешаются.
Что захватывается
Таблица описывает хуки Claude Code. Другие интеграции захватывают события, доступные в их клиенте. Автоматическая передача контекста через общие хуки включается явно: AGENTMEMORY_INJECT_CONTEXT=true.
| Хук | Захватывает |
|---|---|
SessionStart |
Путь к проекту, идентификатор сессии |
UserPromptSubmit |
Пользовательские промпты (с приватным фильтром) |
PreToolUse |
Паттерны доступа к файлам + обогащённый контекст |
PostToolUse |
Имя инструмента, вход, выход |
PostToolUseFailure |
Контекст ошибки |
PreCompact |
Заново подмешивает память перед компакцией |
SubagentStart/Stop |
Жизненный цикл подагентов |
Stop |
Итог в конце сессии |
SessionEnd |
Маркер завершения сессии |
Ключевые возможности
| Возможность | Описание |
|---|---|
| Автоматический захват | Поддерживаемые события сессий и инструментов, записанные нативными интеграциями |
| Семантический поиск | BM25 + векторный + граф знаний со слиянием RRF |
| Эволюция памяти | Версионирование, supersession, графы связей |
| Гигиена recall | Вытесненные (superseded) версии памяти покидают поисковые индексы; цепочка версий в KV хранит полную историю |
| Подсказки о почти-дубликатах | Сохранения возвращают консультативное совпадение similarTo, когда новый контент близко напоминает существующую запись |
| Scope на агента | agentId проходит через сохранение и recall в REST, MCP и поисковом индексе, в режиме shared или isolated |
| Происхождение при записи | Каждое наблюдение и запись памяти несёт неизменяемый канал происхождения (user, agent, tool, import или shared), проставляемый при захвате, сохранении и импорте |
| Авто-забывание | Истечение TTL, обнаружение противоречий, вытеснение по важности |
| Privacy first | API-ключи, секреты, теги <private> вырезаются до сохранения |
| Самовосстановление | Circuit breaker, цепочка fallback-провайдеров, мониторинг состояния |
| Claude bridge | Двусторонняя синхронизация с MEMORY.md |
| Граф знаний | Извлечение сущностей + обход BFS |
| Командная память | Отдельные namespace'ы для общего и приватного у участников команды |
| Происхождение цитат | Любую запись памяти можно проследить до исходных наблюдений |
| Git-снапшоты | Версионирование, откат и diff состояния памяти |
Тройной поток извлечения, объединяющий три сигнала:
| Поток | Что делает | Когда |
|---|---|---|
| BM25 | Сопоставление по стеммированным ключевым словам с расширением синонимами | Всегда включён |
| Vector | Косинусное сходство по плотным эмбеддингам | Если настроен embedding-провайдер |
| Graph | Обход графа знаний по сопоставлению сущностей | Если в запросе обнаружены сущности |
Сливаются через Reciprocal Rank Fusion (RRF, k=60) и диверсифицируются по сессиям (не более 3 результатов на сессию).
Когда векторный индекс заполнен, mem::search (за которым стоит memory_recall) использует гибридный ранжировщик BM25 + вектор. Без эмбеддингов используется BM25. smart-search может дополнительно сливать структурные совпадения из графа, если граф-данные существуют, в том числе в режиме без ключей. Recall уроков работает на выделенном in-memory BM25-индексе вместо сканирования всего корпуса на каждый запрос. Вытесненные (superseded) версии памяти исключаются из каждого пути recall; цепочка версий хранит их историю.
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 включает опциональный runtime @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 skill'ов.
MCP-shim против полного сервера: опубликованный пакет
@agentmemory/mcp— это тонкий shim. Он раскрывает полную поверхность из 54 инструментов только если может достучаться до работающего сервера agentmemory черезAGENTMEMORY_URL(режим прокси). Если сервер недоступен, shim откатывается к локальному набору из 7 инструментов (memory_save,memory_recall,memory_smart_search,memory_sessions,memory_export,memory_audit,memory_governance_delete). Переменная окруженияAGENTMEMORY_TOOLS=core|all— это серверный флаг; задавать её в блокеenvshim'а бесполезно. Если в Cursor / OpenCode / Gemini CLI видно только 7 инструментов, запустите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 |
Гибридный семантический + keyword-поиск |
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 |
Обновить статус action |
memory_frontier |
Разблокированные action'ы, отсортированные по приоритету |
memory_next |
Самый важный следующий action |
memory_lease |
Эксклюзивные lease'ы для action'ов (мультиагентность) |
memory_routine_run |
Инстанцировать workflow-routine'ы |
memory_signal_send |
Межагентный обмен сообщениями |
memory_signal_read |
Чтение сообщений с подтверждениями |
memory_checkpoint |
Внешние условные шлюзы |
memory_mesh_sync |
P2P-синхронизация между инстансами |
memory_sentinel_create |
События-наблюдатели |
memory_sentinel_trigger |
Запустить sentinel'ы извне |
memory_sketch_create |
Эфемерные графы action'ов |
memory_sketch_promote |
Перевести в постоянное состояние |
memory_crystallize |
Сжать цепочки action'ов |
memory_diagnose |
Проверки состояния |
memory_heal |
Авто-исправление зависшего состояния |
memory_facet_tag |
Теги вида измерение:значение |
memory_facet_query |
Запрос по фасет-тегам |
memory_verify |
Трассировка происхождения |
6 ресурсов · 3 промпта · 17 skill'ов
| Тип | Имя | Описание |
|---|---|---|
| Ресурс | 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 |
Анализ повторяющихся паттернов |
| Skill | /recall |
Поиск по памяти |
| Skill | /remember |
Сохранение в долговременную память |
| Skill | /session-history |
Краткие итоги последних сессий |
| Skill | /forget |
Удаление наблюдений/сессий |
В таблице показаны четыре основных skill'а. Полный набор — 9 вызываемых skill'ов плюс 8 справочных; см. раздел про нативные skill'ы выше.
Standalone 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), а затем применяет живые события по SSE через /agentmemory/viewer/events REST-воркера: новые записи памяти, уроки, наблюдения, записи аудита, изменения графа и обновления состояния появляются без опроса и перезагрузок страницы. Единственные другие запросы — это действия, на которые вы кликаете, страницы «load more» и поиск. Когда поток прерывается, просмотрщик показывает, насколько устарели его данные, переподключается с задержкой и синхронизируется заново по одному снимку.
- 12 вкладок в четырёх группах с живыми счётчиками, глубокими ссылками (
#memories/<id>,#sessions/<id>?obs=<id>,#graph/<id>,#health/consolidation), горячими клавишами и мобильным меню. - Memories: поиск на стороне сервера, фильтры по проекту, агенту и типу, панель деталей с цепочкой версий и word diff, ссылки на происхождение, кнопки копирования id, вызова MCP и команды curl, редактирование (новая версия), forget с подтверждением, массовый forget и экспорт в JSON.
- Sessions: встроенный таймлайн наблюдений с читаемым входом и выходом инструментов, фильтры и постраничная навигация, а также записи памяти и уроки, которые произвела каждая сессия.
- Graph: поиск, детали узла со связями и источниками, легенда, не зависящая только от цвета, и управление масштабом.
- Health: живая версия
GET /agentmemory/status. Для каждой проблемы указано её решение, плюс backend состояния, состояние сохранения индекса, прогресс компакции происхождения графа и объяснение консолидации с реальными порогами. - Страницы Audit, Activity, Profile, Replay, Lessons, Actions и Crystals, у каждой — пустое состояние, объясняющее, что это за раздел, почему он пуст и какая команда его заполнит, а также подсказка-глоссарий
?на каждом термине и числе.
open http://localhost:3113
Сервер просмотрщика по умолчанию слушает на 127.0.0.1 и подставляет серверный секрет при пересылке запросов к REST API. При привязке не к loopback HTML-оболочка остаётся общедоступной, но каждый запрос прокси требует bearer-токен; просмотрщик запрашивает его и хранит в session storage. Перед публикацией настройте явные списки разрешённых хостов и origins, а также TLS. Эндпоинт /agentmemory/viewer, отдаваемый REST'ом, подчиняется обычным правилам bearer-токена и перенаправляет браузеры без токена на порт просмотрщика. Заголовки CSP используют nonce скрипта на каждый ответ и отключают inline-атрибуты-обработчики (script-src-attr 'none').
LLM-провайдеры
agentmemory автоопределяет провайдеров по вашему окружению. Провайдер делает доступными операции на базе LLM, но сама конфигурация провайдера сама по себе не включает сжатие наблюдений, написанное LLM. Для этого пути нужны и провайдер, и AGENTMEMORY_AUTO_COMPRESS=true.
| Провайдер | Конфигурация | Заметки |
|---|---|---|
| No-op (по умолчанию) | Настройка не нужна | LLM-сжатие/резюме отключено. Синтетическое сжатие и recall через BM25 продолжают работать. См. AGENTMEMORY_ALLOW_AGENT_SDK ниже, если вы раньше полагались на fallback подписки Claude. |
| Anthropic API | ANTHROPIC_API_KEY |
Поминутная (token-based) оплата |
| 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. Нулевая стоимость, работает на вашем железе. См. Локальные модели ниже. |
| Fallback на подписку Claude | AGENTMEMORY_ALLOW_AGENT_SDK=true |
Только по согласию. Запускает сессии @anthropic-ai/claude-agent-sdk; раньше это приводило к неограниченной рекурсии Stop-хука, поэтому больше не включено по умолчанию. |
Локальные модели (Ollama / LM Studio / vLLM)
agentmemory разговаривает с любым сервером, совместимым с OpenAI API, поэтому всё, что раскрывает /v1/chat/completions, работает без изменений кода. Никаких платных ключей, облака и rate-limit'ов; выполняется целиком на вашем железе.
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. Выберите любую chat-модель в пикере (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 ГБ; силён в извлечении и tool-образном тексте |
qwen3:4b |
~2.6 ГБ | Наименьший разумный вариант; годится для сжатия, слабее для извлечения графа |
qwen3-coder:30b |
~19 ГБ | Лучший локальный выбор для code-сессий (30B MoE, 3.3B активных) на железе с 24–32 ГБ |
gpt-oss:20b |
~14 ГБ | Сильная общая модель, помещающаяся в 16 ГБ RAM |
deepseek-r1:8b |
~5.2 ГБ | Reasoning-дистилляция; медленнее, но извлечения чище |
Модели Qwen 3 думают по умолчанию и могут сжечь весь токен-бюджет на рассуждения до какого-либо вывода. Установите AGENTMEMORY_LLM_NOTHINK=1, чтобы добавлять /no_think к промптам извлечения графа, и поднимите MAX_TOKENS (16384 работает), если извлечения возвращаются пустыми.
Модели reasoning-класса (в стиле o1 с блоками <think>) могут вернуть пустой content с полем reasoning, которое ваш локальный сервер может не отдавать. Если извлечения приходят пустыми, сначала переключитесь на модель без reasoning. Переменная OPENAI_REASONING_EFFORT=none также умеет отключать thinking у thinking-моделей 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 управляет тем, фильтрует ли recall по этому тегу.
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
Два режима:
| Режим | Помечать записи | Фильтровать recall | Когда использовать |
|---|---|---|---|
shared (по умолчанию) |
да | нет | Общий контекст между агентами с аудит-журналом. Architect видит, что отметил developer, но каждая запись фиксирует, кто это сказал. |
isolated |
да | да | Строгое разделение. Architect никогда не увидит наблюдения / записи памяти / сессии developer'а. |
Что помечается, когда AGENT_ID задан: Session.agentId, RawObservation.agentId, CompressedObservation.agentId, Memory.agentId. Роль течёт по api::session::start → mem::observe → mem::compress → KV.
Что фильтруется в режиме isolated: mem::smart-search, /agentmemory/memories, /agentmemory/observations, /agentmemory/sessions. Каждый эндпоинт принимает ?agentId=<role> для переопределения на конкретный запрос и ?agentId=*, чтобы полностью выйти из env-scope. /memories дополнительно принимает ?includeOrphans=true, чтобы поднять записи памяти до появления AGENT_ID, у которых agentId не определён.
Переопределение в самом вызове на уровне SDK / REST: каждый мутирующий эндпоинт (/session/start, /remember) принимает поле agentId в теле запроса, которое выигрывает у env. Полезно для runtime'ов, прогоняющих много ролей через один серверный процесс. Инструмент MCP memory_save раскрывает то же поле agentId, автономный stdio-сервер пробрасывает и agentId, и project, а сохранённые записи памяти несут agentId в поисковый индекс, поэтому поиск со scope'ом агента покрывает записи памяти так же, как наблюдения.
Когда AGENT_ID не задан, память остаётся без scope (legacy-поведение: ни тегов, ни фильтров).
Порты
| 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. Смена backend не переносит существующую память. Надёжность записи, ограничения Redis и авторизованный экспорт/импорт описаны в руководстве по хранению.
Конфигурационный файл
Помещайте runtime-конфигурацию agentmemory в ~/.agentmemory/.env, а не экспортируйте переменные в каждой сессии shell. Если просмотрщик показывает подсказку настройки вида export ANTHROPIC_API_KEY=..., скопируйте её в этот файл как ANTHROPIC_API_KEY=... без префикса export, затем перезапустите agentmemory.
Переменные окружения процесса имеют приоритет над файлом. После изменения настроек перезапустите сервер.
В Windows тот же файл лежит в %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 (включая этот явный fallback на подписку) и AGENTMEMORY_AUTO_COMPRESS=true. Один только провайдер оставляет в силе путь синтетического сжатия по умолчанию.
Консолидация (узлы графа, уроки, crystals) включена по умолчанию, когда настроен провайдер 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 и копирует его также в выбранный каталог данных. Каждый встроенный клиент читает его оттуда, когда говорит с локальным сервером: CLI, просмотрщик, хуки из plugin/scripts, MCP-сервер и shim @agentmemory/mcp, конфиги, записанные agentmemory connect, и встроенные интеграции OpenCode, Pi, OpenClaw, Hermes и filesystem-watcher. Сохранённый секрет отправляется только на loopback-адреса (localhost, 127.0.0.0/8, ::1). Явно заданный AGENTMEMORY_SECRET всегда выигрывает, и удалённым клиентам он всё равно нужен. Docker и entrypoint'ы deploy/ уже генерируют и экспортируют собственный секрет. Чтобы вызвать API вручную:
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
Правила запросов для записи. Запросы POST, PUT, PATCH и DELETE к REST API и просмотрщику должны отправлять Content-Type: application/json (параметр charset допустим), когда у них есть тело, а заголовок Origin, если он есть, должен быть loopback-origin для настроенного порта REST или просмотрщика, либо быть перечислен в VIEWER_ALLOWED_ORIGINS (через запятую, например https://memory.example.com). Клиенты, которые не отправляют заголовок Origin (CLI, хуки, MCP, curl, сервер-сервер), не затрагиваются. Просмотрщик также принимает собственный origin.
Пути к файлам. Эндпоинты, которые читают или пишут файлы (/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, slots, уроки, action'ы, sketches, сигналы, checkpoints, импорты, jsonl replay, mesh sync, team shares, вывод сжатия и резюме, crystals и узлы графа.
Ключевые эндпоинты
| Метод | Путь | Описание |
|---|---|---|
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 и offline-spool |
POST |
/agentmemory/capture/retry |
Повторить захваты из dead letter |
POST |
/agentmemory/capture/drain |
Немедленно отправить локальный offline-spool |
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 вызова от хоста, если он есть в payload'е (например, tool_use_id у Claude Code), иначе — хеш сессии, типа хука, имени инструмента, входа, выхода и timestamp'а хоста. Сервер записывает событие в инбокс захвата в state store, сохраняет наблюдение, затем удаляет запись из инбокса. Код статуса говорит о том, что произошло:
| Статус | поле status |
Значение |
|---|---|---|
201 |
accepted |
Сохранено. observationId — новое наблюдение. |
202 |
accepted (state: "retrying") |
Принято, но сохранение не удалось. Сервер повторяет попытку, в том числе после перезапуска. |
200 |
duplicate |
Этот eventId уже был принят. observationId — существующее наблюдение; новое не сохраняется. |
400 / 422 |
rejected |
Некорректный payload, либо сохранение окончательно не удалось (событие сохраняется как dead letter). |
503 |
rejected (retryable: true) |
Инбокс заполнен (AGENTMEMORY_CAPTURE_INBOX_MAX). Хуки откладывают событие в spool и отправляют его позже. |
Неудавшиеся события повторяются каждые AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS (10 с) с удваивающимся backoff'ом, до 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), поэтому хук, воспроизведённый после таймаута или перезапуска, сохраняется один раз, тогда как два отдельных вызова инструмента со своими собственными host-id сохраняются дважды, даже если их содержимое идентично. Когда наблюдение удаляется (forget, удаление сессии, вытеснение, авто-забывание или импорт, заменяющий хранилище), его событие помечается как удалённое до удаления самого наблюдения, поэтому повтор этого события в том же окне отвечается как дубликат и ничего не сохраняет. State store пишет на диск каждые 2 секунды, поэтому отвеченное событие может ещё на мгновение существовать только в памяти. Чтобы это покрыть, каждый ответ 2xx также несёт bootId сервера (новый при каждом запуске), acceptedAt и durableAfterMs (интервал сохранения плюс 1.5 с на файловом хранилище, 1.5 с на redis, где устойчивость — настройка оператора). Хуки держат событие в локальном spool, пока это окно не пройдёт, и удаляют его при следующем вызове без дополнительного запроса. Если к этому моменту bootId изменился, сервер перезапустился, поэтому хук отправляет событие снова с тем же eventId; событие, которое всё же достигло диска, не сохраняется дважды. Сервер также сам отправляет такие события при запуске и на каждом интервале повтора, поэтому перезапуск ничего не теряет, даже если после него не запускается ни один хук. Старые хуки игнорируют дополнительные поля, а новые хуки против старого сервера отбрасывают событие на 2xx, как и раньше.
Когда сервер недоступен, не отвечает вовремя или возвращает 5xx, хук добавляет наблюдение в локальный spool-файл <data dir>/capture-spool/<host>-<port>.jsonl (переопределите папку через AGENTMEMORY_CAPTURE_SPOOL_DIR). Файл приватен для вашего пользователя (права 600), секреты вырезаются так же, как их вырезает сервер, он хранит не больше AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES (5 MiB) и отбрасывает записи старше AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS (168). Когда он заполнен, новые записи отбрасываются и считаются, и /agentmemory/status сообщает об этом. Хук всё равно завершается с кодом 0 в пределах своего лимита времени и не добавляет ни одного запроса, когда сервер здоров. Spool отправляется при следующем запуске и первым хуком, который снова достучится до сервера, в фоновом процессе, чтобы агент не ждал. Id событий делают это безопасным: наблюдение, которое всё же дошло до таймаута, не сохраняется дважды. npx @agentmemory/agentmemory capture показывает spool и инбокс сервера, --drain отправляет spool сейчас, а GET /agentmemory/capture возвращает то же самое в JSON. Задайте AGENTMEMORY_CAPTURE_SPOOL=false, чтобы отключить spool.
Усечение происхождения графа. Усечение старых данных происхождения откладывается при запуске, поскольку оно читает старые области целиком. /agentmemory/status сообщает deferred или off при AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false. Выполняйте описанное ниже ручное усечение во время обслуживания. Миграция поискового индекса выполняется отдельно: используйте agentmemory graph-index migrate --allow-legacy-scan согласно руководству по обслуживанию.
Чтобы запустить его вручную, вызовите POST /agentmemory/graph/compact. Он проходит по индексам имён и edge-key вместо перечисления каждого узла и ребра, и его безопасно запускать повторно. Когда он усекает 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.