Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

116 KB
Raw Blame

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

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

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

rohitg00/agentmemory | Trendshift

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

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

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

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

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

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


AgentMemory зберігає підтримувані події сесій і дає змогу шукати рішення, виправлення та уроки між агентами. У viewer можна переглядати, редагувати, експортувати й видаляти спогади. Пошук за словами працює без API-ключа; ембединги додають семантичний пошук.

Встановлення

Вимоги:

  • Node.js 20 або новіше, з npm і npx (node -v, npm -v та npx -v).
  • Для автоматичного налаштування середовища macOS/Linux також потрібні curl, POSIX-оболонка sh і tar.
  • У Windows використовуйте WSL2 або інструкцію для нативного встановлення.

Канонічна команда для чистого встановлення:

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

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


Зберігання даних

Типово пам’ять зберігається поза репозиторієм:

Платформа Каталог даних
macOS ~/Library/Application Support/agentmemory
Linux $XDG_DATA_HOME/agentmemory / ~/.local/share/agentmemory
Windows %APPDATA%\agentmemory

Інстанс 0 повторно використовує наявний ./data/state_store.db. Інший каталог задається через --data-dir <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 як на основний шлях захоплення: cleanupPeriodDays Claude 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, щоб уникнути дублювання.

Cursor

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. Використовуйте один спосіб встановлення на клієнт.

Pi · Oh My Pi · DSH

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; резервуйте його й використовуйте повторно під час оновлення. Автентифікацію, мережу, резервування та міграцію описано в посібнику з розгортання.

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

Кнопка розгортання в один клік для 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

Знання про проєкт розподілені між чатами й файлами інструкцій. 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 Будь-яка модель Залежить Проксі для декількох моделей

MCP-сервер

54 інструменти, 6 ресурсів, 3 промпти та 17 скілів.

MCP-шим проти повного сервера: опублікований пакет @agentmemory/mcp — це тонкий шим. Він надає повну поверхню з 54 інструментів лише тоді, коли може дістатися запущеного сервера agentmemory через AGENTMEMORY_URL (режим проксі). Якщо жоден сервер недоступний, шим переходить на локальний набір із 7 інструментів (memory_save, memory_recall, memory_smart_search, memory_sessions, memory_export, memory_audit, memory_governance_delete). Змінна середовища AGENTMEMORY_TOOLS=core|all — це прапорець на боці сервера; встановлення його в блоці env шима не має ефекту. Якщо ви бачите лише 7 інструментів у Cursor / OpenCode / Gemini CLI, запустіть npx -y @agentmemory/agentmemory@latest (або стек Docker) і встановіть AGENTMEMORY_URL=http://localhost:3111.

54 інструменти

Три поверхні інструментів, від найменшої до найбільшої: AGENTMEMORY_TOOLS=core обмежує видимість до 8 основних (memory_save, memory_recall, memory_consolidate, memory_smart_search, memory_sessions, memory_diagnose, memory_lesson_save, memory_reflect); базовий набір нижче — це 14 фундаментальних інструментів реєстру; типовий режим (AGENTMEMORY_TOOLS=all) надає всі 54.

Базові інструменти (14)
Інструмент Опис
memory_recall Пошук минулих спостережень
memory_compress_file Стиснення markdown-файлів зі збереженням структури
memory_save Збереження інсайту, рішення або шаблону
memory_file_history Минулі спостереження щодо конкретних файлів
memory_patterns Виявлення повторюваних шаблонів
memory_sessions Перелік останніх сесій
memory_smart_search Гібридний семантичний + ключовий пошук
memory_vision_search Пошук спостережень із зображеннями
memory_timeline Хронологічні спостереження
memory_profile Профіль проєкту (концепти, файли, шаблони)
memory_export Експорт усіх даних пам'яті
memory_relations Запит графа зв'язків
memory_commit_lookup Сесії, що стоять за git-комітом
memory_commits Коміти, записані для сесії
Розширені інструменти (54 загалом, типова поверхня)
Інструмент Опис
memory_patterns Виявлення повторюваних шаблонів
memory_timeline Хронологічні спостереження
memory_relations Запит графа зв'язків
memory_graph_query Обхід графа знань
memory_consolidate Запуск 4-рівневої консолідації
memory_claude_bridge_sync Синхронізація з MEMORY.md
memory_team_share Поширення серед членів команди
memory_team_feed Останні спільні елементи
memory_audit Журнал аудиту операцій
memory_governance_delete Видалення з журналом аудиту
memory_snapshot_create Знімок із версіюванням Git
memory_action_create Створення робочих елементів із залежностями
memory_action_update Оновлення статусу дії
memory_frontier Неблоковані дії, ранжовані за пріоритетом
memory_next Єдина найважливіша наступна дія
memory_lease Ексклюзивні оренди дій (мультиагентність)
memory_routine_run Інстанціювання рутин робочого процесу
memory_signal_send Обмін повідомленнями між агентами
memory_signal_read Читання повідомлень із підтвердженнями
memory_checkpoint Зовнішні умовні ворота
memory_mesh_sync P2P-синхронізація між інстансами
memory_sentinel_create Вартові на основі подій
memory_sentinel_trigger Зовнішнє спрацювання вартових
memory_sketch_create Ефемерні графи дій
memory_sketch_promote Підвищення до постійного стану
memory_crystallize Компактування ланцюжків дій
memory_diagnose Перевірки стану здоров'я
memory_heal Автовиправлення застряглого стану
memory_facet_tag Теги вимір:значення
memory_facet_query Запит за фасетними тегами
memory_verify Простеження походження

6 ресурсів · 3 промпти · 17 скілів

Тип Назва Опис
Ресурс agentmemory://status Стан здоров'я, кількість сесій, кількість записів пам'яті
Ресурс agentmemory://project/{name}/profile Аналітика для конкретного проєкту
Ресурс agentmemory://project/{name}/recent Останні спостереження для проєкту
Ресурс agentmemory://memories/latest 10 останніх активних записів пам'яті
Ресурс agentmemory://graph/stats Статистика графа знань
Ресурс agentmemory://team/{id}/profile Спільний командний профіль
Промпт recall_context Пошук + повернення контекстних повідомлень
Промпт session_handoff Передача даних між агентами
Промпт detect_patterns Аналіз повторюваних шаблонів
Скіл /recall Пошук у пам'яті
Скіл /remember Збереження в довгострокову пам'ять
Скіл /session-history Підсумки останніх сесій
Скіл /forget Видалення спостережень/сесій

У таблиці показано чотири основні скіли. Повний набір — це 9 викликаних скілів плюс 8 довідкових скілів; див. розділ про нативні скіли вище.

Автономний MCP

Запуск без повного сервера, для будь-якого MCP-клієнта. Працює будь-який із варіантів:

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-секрет.


API

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.

Ліцензія

Apache-2.0