by ipiton (community) Claude Desktop, Claude Code, OpenCode, Cursor, Codex, любой MCP-клиент, macOS, Linux
MCP-сервер, дающий AI-агентам персистентную память с семантическим поиском.
MCP-сервер для веб-поиска через Exa AI — поисковик, оптимизированный для нейросетей. В отличие от обычных поисковых …
Показывает, что coding-агенты уже знают о проекте. Docmancer индексирует память, правила и инструкции, которые Claude Code, …
Минималистичная расширяемая agent-native база знаний, поддерживающая общий контекст актуальным и инспектируемым.
Биологически вдохновлённый движок персистентной памяти для Claude Code. 26 когнитивных подсистем, сети Хопфилда, предиктивное кодирование, каузальный …
brew tap ipiton/tap brew install agent-memory-mcp go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest cp .env.example .env agent-memory-mcp
Слой памяти, документов и контекста репозитория для инженерных агентов.
agent-memory-mcp помогает агентам работать с живым инженерным контекстом, а не только с изолированными заметками. Он объединяет типизированную память, извлечение документов и инструменты, ориентированные на репозиторий, чтобы клиенты Claude, Cursor, Codex и другие MCP могли вспоминать решения, искать инструкции, изучать проектные документы и повторно использовать операционные знания между сеансами.
Он предназначен для инженерных рабочих процессов, таких как:
Большинство серверов памяти MCP сосредоточены на "сохранить заметку, вспомнить заметку".
agent-memory-mcp направлен на более широкий инженерный контекстный слой:
Это делает его более подходящим, когда агент должен отвечать на вопросы, такие как:
CLAUDE.md / .cursorrulesСправочная документация: ... · ... · ... · ... · ... · ... · ... · ... · ... · ...
.env: запускайте из корня проекта без ручного подключения переменных окруженияagent-memory-mcp reembed для миграции памяти и agent-memory-mcp index для перестройки RAG после переключения моделейstats и memory_stats показывают, сколько воспоминаний принадлежит каждой модели встраивания, и называют те, которые не могут быть достигнуты семантическим запросом — записи, которые кодировщик отклонил полностью, и записи, встроенные из их открытияsource_type, confidence, freshness, owner и last_verified_at, а ранжирование использует доверие/актуальность вместо схожести/console127.0.0.1; привязка к не-локальной петле требует аутентификации, если вы явно не выбираете небезопасный доступ без аутентификации# go install
go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest
cp .env.example .env
# Edit .env:
# - keep the solo-local defaults unless you need to change them
# - enable at least one embedding provider
# JINA_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL
steward_run выполняет полный цикл обслуживания — обнаружение дубликатов, разрешение конфликтов, сканирование устаревших записей и кандидатов на продвижение в канонические — одной командойdrift_scan сравнивает записи памяти с живыми файлами репозитория и документами, чтобы найти устаревшие, отсутствующие или изменённые ссылкиverify_entry и verification_candidates позволяют агентам и пользователям отслеживать, когда знание было проверено в последний раз и что требует вниманияsteward_policy и переменные окруженияvalid_from / valid_until, а recall_as_of извлекает знания, которые были действительны в определённый момент времениmark_outdated с заменяющей записью автоматически строит двунаправленные ссылки (superseded_by / replaces) и устанавливает временные границыknowledge_timeline показывает хронологическое развитие знаний по темеMCP_RECALL_HALFLIFE_DAYS, и обратите внимание, что MCP_RECALL_DECAY_TYPES (по умолчанию working) решает, какие типы вообще затухают — ось типа важнее, чем скоростьsteward_policy)Рекомендуемый путь: сначала запустите локально, докажите ценность на одном репозитории, затем расширьте.
Выполните эти команды из корня вашего проекта.
Установите бинарный файл с помощью одного из этих вариантов:
# Homebrew (macOS/Linux) — recommended, auto-configures Claude Code hooks
brew tap ipiton/tap
brew install agent-memory-mcp
# go install
go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest
Затем настройте один провайдер встраивания:
bge-m3 для локальной настройкиcp .env.example .env
# Edit .env:
# - keep the solo-local defaults unless you need to change them
# - enable at least one embedding provider
# JINA_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL
Бинарный файл автоматически загружает .env из текущей директории, поэтому вам не нужно выполнять source .env.
Рекомендуемая предустановка для одиночного локального использования сохраняет всё состояние выполнения внутри одной директории:
.agent-memory/
rag-index/
memory-store/
logs/
Используйте локальный режим, когда вам нужны встраивания без отправки текста на хостинговые API.
cp .env.example .env
# Then set:
# MCP_EMBEDDING_MODE=local-only
# JINA_API_KEY=
# OPENAI_API_KEY=
В режиме local-only:
agent-memory-mcp никогда не вызывает Jina AIagent-memory-mcp никогда не вызывает совместимые с OpenAI API для встраиванияЧто всё ещё использует сеть:
http://localhost:11434http://127.0.0.1:8080/v1Если локальный бэкенд не запущен или нет доступной поддерживаемой локальной модели, запросы на встраивание завершаются ошибкой, специфичной для local-only, сообщающей вам, чтобы вы запустили бэкенд или отключили ...
Если вы уже запускаете llama.cpp (Apple Silicon native, GGUF модели), направьте сервер на его совместимый с OpenAI /v1/embeddings эндпоинт вместо установки Ollama. Это опционально — установите LLAMACPP_BASE_URL, чтобы включить его. После установки он входит в цепочку резервных вариантов перед Ollama (Jina → OpenAI → llama.cpp → Ollama) и работает в режиме local-only.
# Start llama.cpp with an embedding model
llama-server -m bge-m3.gguf --embedding --pooling cls -c 8192 -ub 8192
# Then configure the MCP server
LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
LLAMACPP_EMBEDDING_MODEL=bge-m3
MCP_EMBEDDING_MODE=local-only
MCP_EMBEDDING_DIMENSION соответствует ей (1024 для bge-m3) — несоответствие отклоняется при вызове.На медленном самоподдерживаемом оборудовании (Ollama с bge-m3 на низкоядерном или ARM VPS), одна часть может занимать 4–7 секунд для встраивания, и таймаут по умолчанию в 5 секунд будет срабатывать многократно. Увеличьте лимиты:
MCP_EMBEDDING_TIMEOUT=30s # default 5s
MCP_EMBEDDING_MAX_RETRIES=3 # default 1
Некорректные значения возвращаются к значениям по умолчанию, поэтому сервис всё равно запускается.
Одиночный llama-server обрабатывает запросы строго последовательно. При включённом MCP_RAG_AUTO_INDEX / MCP_RAG_FILE_WATCHER фоновые пакеты реиндексации (по 50 частей каждый) занимают единственный слот на десятки секунд, поэтому интерактивные вызовы recall / semantic_search / index_documents попадают в очередь и получают ошибку context deadline exceeded — сервер выглядит "деградированным", хотя пропускная способность нормальная. Давайте серверу встраивания параллельные слоты, чтобы интерактивные вызовы проскальзывали между пакетами:
llama-server -m bge-m3.gguf --embedding --pooling cls \
-c 32768 -b 8192 -ub 8192 \ # 8192 ctx PER SLOT (see note) — fits the largest chunk
-np 4 -cb \ # 4 slots + continuous batching: interactive calls don't wait for the batch
--metrics # exposes Prometheus /metrics; /slots shows live slot occupancy
-npразбивает контекст. Контекст на слот —ctx_size / n_parallel. bge-m3 — это энкодер — каждая часть должна помещаться в один слот целиком, и-b/-ubдолжны быть ≥ самой большой части в токенах, иначе он падает с ошибкой "input too large to process". Поэтому при-np 4вам нужно-c 32768, чтобы сохранить 8192 на слот; не уменьшайте-c,-bили-ubниже значения для одного слота при добавлении слотов.
Измеренный эффект (Apple Silicon, bge-m3 Q8_0): пакет из 50 входов падает с ~50s до ~5s, а интерактивный запрос при нагрузке пакета падает с 8–20s до ~0.03s.
Также сгладите лавину реиндексации для больших часто редактируемых файлов (переразбиение файла на части при каждом изменении может перезапускать цикл посредине):
MCP_RAG_DEBOUNCE=2m # default 30s — collapses bursts of edits into one reindex
MCP_RAG_WATCH_INTERVAL=5m # periodic full-scan cadence
Для клиентов MCP, таких как Claude Desktop, Cursor или Codex:
agent-memory-mcp
Для прямого использования через CLI, тот же бинарный файл уже работает без клиента MCP:
agent-memory-mcp store -content "Ingress rollback uses previous Helm revision" -type procedural -tags "helm,rollback"
agent-memory-mcp recall "helm rollback"
agent-memory-mcp stats
agent-memory-mcp store -content "Solo local smoke check" -type working -tags "smoke,local"
agent-memory-mcp recall "solo local smoke"
agent-memory-mcp index
agent-memory-mcp search "agent memory"
Если вы работаете из исходного кода, вы можете запустить тот же поток:
make local-smoke
После запуска локального режима против проекта, проиндексируйте документы и ищите их:
agent-memory-mcp index
agent-memory-mcp search "recent ingress change"
Типичные источники высокой ценности включают:
docs/README.mdCHANGELOG.mdКогда локальный режим оказывается полезным, переходите в три шага:
Самый быстрый путь к общей службе:
cd deploy/docker
cp .env.shared.example .env.shared
# edit MCP_HTTP_AUTH_TOKEN and MCP_PROJECT_ROOT
docker compose --env-file .env.shared up -d --build
Это сохраняет тот же стек извлечения, но упаковывает его для командного использования.
Справочные документы:
brew tap ipiton/tap
brew install agent-memory-mcp
brew services start agent-memory-mcp
Это устанавливает бинарный файл, создаёт конфигурацию по умолчанию и запускает службу на 127.0.0.1:18080 с включённой памятью. Поиск документов RAG отключён по умолчанию — включите его, отредактировав конфигурацию:
# Edit config
nano $(brew --prefix)/etc/agent-memory-mcp/config.env
Установите ... ... и ... Изменения применяются автоматически в течение ~30 секунд или принудительно перезагрузите с помощью kill -HUP $(pgrep agent-memory-mcp).
Управление службой:
brew services restart agent-memory-mcp
brew services stop agent-memory-mcp
brew services info agent-memory-mcp
Если вы ранее устанавливали через Cask и хотите brew services:
brew uninstall --cask agent-memory-mcp
brew install ipiton/tap/agent-memory-mcp
Скачайте предварительно собранный архив со страницы ...
Архивы релизов содержат версию в имени файла, поэтому сначала разрешите последний тег:
# Resolve latest version once
VERSION=$(curl -fsSL https://api.github.com/repos/ipiton/agent-memory-mcp/releases/latest \
| grep '"tag_name"' | head -1 | cut -d'"' -f4 | sed 's/^v//')
# macOS (Apple Silicon)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
# macOS (Intel)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
# Linux (x86_64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
# Linux (arm64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/
git clone https://github.com/ipiton/agent-memory-mcp.git
cd agent-memory-mcp
go build -o bin/agent-memory-mcp ./cmd/agent-memory-mcp
docker build -f deploy/docker/Dockerfile -t agent-memory-mcp .
docker run -p 18080:18080 \
-v memory-data:/data \
-e MCP_HTTP_MODE=http \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
agent-memory-mcp
Или с помощью docker compose:
cd deploy/docker
cp .env.shared.example .env.shared
docker compose --env-file .env.shared up -d --build
HTTP-эндпоинт MCP будет доступен по адресу ...
По умолчанию, HTTP-режим для bare-metal теперь привязывается к 127.0.0.1. Для развёртывания в общем/контейнеризированном режиме установите MCP_HTTP_HOST=0.0.0.0 и токен доступа.
Бинарный файл также работает как автономный CLI:
# Memory operations
agent-memory-mcp store -content "Project uses chi router" -type procedural -tags "go,chi"
agent-memory-mcp recall "router middleware"
agent-memory-mcp list -type procedural
agent-memory-mcp delete <memory-id>
# RAG search
agent-memory-mcp search "authentication flow"
agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type runbook -debug "ingress rollback"
agent-memory-mcp index
# Project bank and session close
agent-memory-mcp project-bank canonical_overview
agent-memory-mcp close-session -summary "Updated payments rollback runbook after fixing ingress timeout" -context payments-api -service payments-api
agent-memory-mcp review-session -mode incident -stdin < notes/session.txt
agent-memory-mcp accept-session -summary "Added migration caveat for billing schema rename" -mode migration -context billing -service billing-api
agent-memory-mcp accept-session -raw-only -summary "Exploratory notes that are too noisy for consolidation"
# Utilities
agent-memory-mcp stats
agent-memory-mcp config claude-desktop
agent-memory-mcp reembed
agent-memory-mcp export > backup.json
agent-memory-mcp import backup.json
# JSON output for scripting
agent-memory-mcp recall "test" -json
agent-memory-mcp stats -json
Запустите agent-memory-mcp <command> -help, чтобы получить детали по любой команде.
Команды памяти CLI и инструменты памяти MCP теперь используют одни и те же правила валидации и нормализации:
verified скрыты из сводок доверия в выводе как CLI, так и MCPКогда команда не задана (или флаги начинаются с -), бинарный файл запускает сервер MCP, как и прежде — полная обратная совместимость.
Используйте встроенный генератор для создания локальной конфигурации проекта, которая запускает сервер из корня вашего репозитория.
Это рекомендуемый путь, потому что он:
.env без дублирования настроек во всех клиентах MCP.agent-memory/ относительно корня проектаВы можете переопределить обнаруженный корень проекта или путь к бинарному файлу с помощью -root и -command.
Вставьте в `~/Library/Application ...
agent-memory-mcp config claude-desktop
Пример сгенерированного вывода:
{
"mcpServers": {
"memory": {
"command": "/bin/sh",
"args": [
"-lc",
"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
]
}
}
}
Вставьте в ~/.cursor/mcp.json:
agent-memory-mcp config cursor
Пример сгенерированного вывода:
{
"mcpServers": {
"memory": {
"command": "/bin/sh",
"args": [
"-lc",
"cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
]
}
}
}
Вставьте в ...
agent-memory-mcp config codex
Пример сгенерированного вывода:
[mcp_servers.memory]
command = "/bin/sh"
args = ["-lc", "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"]
agent-memory-mcp config claude-desktop \
-name engineering-memory \
-root /path/to/your/project \
-command /absolute/path/to/agent-memory-mcp
Без этих фрагментов агент будет использовать только базовые store_memory и recall_memory. Чтобы разблокировать закрытие сессии, типы инженерии памяти, проектный банк и консолидацию, добавьте соответствующие фрагменты в инструкции вашего агента.
Где размещать их:
CLAUDE.md в корне проекта.cursorrules в корне проектаAGENTS.mdВыберите фрагменты, соответствующие вашему рабочему процессу. Начните с "Начало сессии" и "Закрытие кодирования" — они покрывают наиболее распространённый случай.
Before you start, recall the project context for this task.
Then recall recent changes related to the service or component I am touching.
Search for relevant runbooks, RFCs, changelog notes, or incident notes.
Prefer `summarize_project_context` or `project_bank_view view=canonical_overview` for the first pass and then drill into `search_runbooks` or `recall_similar_incidents`.
Summarize the constraints, caveats, and likely risks before making changes.
When the coding session ends, call `close_session` with a concise summary, service, and context.
Review the proposed `new`, `update`, `merge`, and `raw_only` actions plus the decision trace.
If the plan looks low risk, use `accept_session_changes`.
If the report is noisy or mostly exploratory, keep `save_raw_only` as the fallback.
Prefer `project_bank_view` at the next session start to confirm what became maintained knowledge.
When incident work stabilizes, call `close_session` or `review_session_changes` with `mode=incident`.
Expect stricter review-first behavior for updates, merges, and anything touching canonical operational knowledge.
Capture impact, mitigation, rollback, and unresolved follow-ups in the summary.
Apply only the low-risk actions automatically and leave ambiguous runbook or incident changes in review.
Follow up with `recall_similar_incidents` and `project_bank_view view=incidents` if you need to compare against existing knowledge.
When a migration session ends, call `close_session` with `mode=migration`, affected service, and the migration summary.
Prefer explicit notes about prerequisites, sequencing, rollback, and post-deploy verification.
Treat runbook replacements, caveat changes, and supersede proposals as review-first even when the textual match looks strong.
Use `accept_session_changes` only after checking the report for stale or superseded knowledge.
Finish by checking `project_bank_view view=migrations` to see the maintained migration notes.
If the session was exploratory, ambiguous, or too noisy, skip consolidation and save only the raw summary.
Use `close_session` / `review_session_changes` to inspect the plan first, then pick `save_raw_only`.
In CLI mode, `agent-memory-mcp accept-session -raw-only ...` is the explicit override.
This keeps the raw trace without forcing weak knowledge updates into the project bank.
Before making infra or platform changes, recall similar fixes, migrations, incidents, and known caveats.
Search for runbooks, postmortems, changelog notes, and recent project context related to this component.
Summarize blast radius, rollback options, and operational risks before editing files.
When memory has grown or a session just ended, run `steward_run` with `dry_run=true` to see what needs attention.
Review the report for duplicates, conflicts, stale entries, and canonical promotion candidates.
Check `steward_inbox` for pending review items and resolve them with `steward_inbox_resolve`.
Use `drift_scan` periodically to catch memories that reference files or docs that have changed.
Use `verification_candidates` to find knowledge that has not been verified recently.
When you need to understand what was true at a specific point in time, use `recall_as_of` with an RFC3339 timestamp.
To trace how knowledge about a topic evolved over time, use `knowledge_timeline`.
When superseding an old decision or runbook, use `mark_outdated` with the superseding entry ID to build a proper chain.
Запустите сервер в режиме HTTP:
# Standalone
MCP_HTTP_MODE=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=18080 \
MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
agent-memory-mcp
# Or with Docker
cd deploy/docker
docker compose --env-file .env.shared up -d --build
Затем направьте вашего HTTP-совместимого клиента MCP или прокси на:
http://localhost:18080/mcp
Конечная точка /mcp поддерживает транспорт MCP Streamable HTTP: запросы JSON-RPC передаются через POST, а клиенты, которым нужен канал серверного push (Cursor и аналоги), открывают его с помощью GET и Accept: text/event-stream. Сервер поддерживает этот поток с помощью периодических keepalive-комментариев. Простой GET без заголовка Accept для SSE возвращает 405.
curl -N -H "Accept: text/event-stream" \
-H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
http://localhost:18080/mcp
Для проверки извлечения в браузере откройте:
http://localhost:18080/console
Консоль — это лёгкий интерфейс для:
В общем режиме сама страница статична, но живые запросы из консоли всё равно требуют того же токена носителя, что и /mcp.
Для общего режима HTTP:
MCP_HTTP_HOST=127.0.0.1; это безопасный локальный стандартMCP_HTTP_HOST=0.0.0.0MCP_HTTP_AUTH_TOKEN, чтобы требовать Authorization: Bearer <token> на /mcpMCP_HTTP_AUTH_TOKEN, если вы явно не установили .../health для проверок состояния балансировщика нагрузки или контейнераlocal -> team laptop -> shared service| Команда | Описание |
|---|---|
serve |
Запуск сервера MCP (stdio/http) — по умолчанию, когда команда не задана |
store |
Сохранение памяти (-content, -title, -type, -tags, -context, -importance, -stdin) |
recall |
Напоминание памяти с доверием (позиционный запрос, -type, -tags, -limit, -json) |
list |
Список памяти (-type, -context, -limit, -json) |
delete |
Удаление памяти по ID (позиционный) |
search |
Гибридный поиск RAG с метаданными доверия (позиционный запрос, -limit, -source-type, -debug, -json) |
index |
Переиндексация документов для RAG |
close-session |
Анализ итогового отчёта сессии и создание отчёта о закрытии сессии (-summary, -stdin, -mode, -context, -service, -tags, -metadata, -started-at, -ended-at, -raw-only, -json) |
review-session |
Ориентированный на обзор псевдоним для close-session с теми же входами и поверхностью отчёта |
accept-session |
Сохранение сырого резюме и автоматическое применение изменений с низким риском (-summary, -stdin, -mode, -context, -service, -tags, -metadata, -started-at, -ended-at, -raw-only, -json) |
stats |
Показать статистику памяти (-json) |
config |
Сгенерировать готовые фрагменты конфигурации клиента MCP |
project-bank |
Показать структурированные представления проектного банка (canonical_overview, decisions, runbooks, incidents, caveats, migrations, review_queue) |
resolve-review-item |
Разрешить элемент очереди ожидающих (<id>, -resolution, -note, -owner, -json) |
reembed |
Повторно сгенерировать вложения памяти с активной моделью (-json) |
export |
Экспорт всех памяти в JSON (-o файл, по умолчанию stdout) |
import |
Импорт памяти из JSON (позиционный файл или stdin) |
index-triples |
Доработка (subj, rel, obj) триплетов для памяти, которой их не хватает (-resume, -force, -limit, -context, -dry-run, -progress-every, -json). Обеспечивает работу инструмента recall_multihop MCP — см. MCP_TRIPLE_EXTRACTOR_* envs. |
dead-ends-stale |
Список памяти dead_end, старше -age (по умолчанию 12 месяцев) для повторной оценки (-limit, -json) |
setup |
Автоматическая настройка хуков Claude Code в ... (-command, -dry-run, -force). См. ... |
hooks-config |
Вывести JSON хуков Claude Code для ручной вставки в settings.json (-command, -json) |
context-inject |
Полезная нагрузка хука SessionStart: недавние памяти + ожидающие сырые резюме (-limit, -pending-limit, -context, -service) |
auto-capture |
Хук SessionEnd: чтение транскрипта из stdin, выполнение конвейера extract → plan → apply (-stdin, -summary, -mode, -context, -service, -tags, -dry-run, -json) |
checkpoint |
Хук PreCompact: сохранение контрольной точки сессии перед сжатием контекста (-stdin, -summary, -boundary, -context, -service, -tags) |
sweep-archive |
Сканировать MCP_TASK_ARCHIVE_ROOTS и запустить end-task для каждого архивированного слага (T47) |
end-task |
Консолидировать рабочие/процедурные памяти, связанные с одним архивированным слагом задачи (T47) |
mark-dead-end |
Записать заброшенный подход с его рационалом неудачи (T46) |
sediment-cycle |
Применить переходы слоёв для осаждения памяти: тривиальные повышения применяются автоматически, остальные помещаются в очередь на рассмотрение (T48) |
recount-refs |
Обратное заполнение метаданных referenced_by_count из существующих межпамятных связей (идемпотентно) |
| ## Справочник по инструментам MCP |
| Инструмент | Описание |
|---|---|
store_memory |
Сохранить память с содержимым, типом, тегами и важностью |
recall_memory |
Вызвать память по семантическому/текстовому запросу с возможными фильтрами и ранжированием с учётом доверия |
update_memory |
Обновить существующую память по ID |
delete_memory |
Удалить память по ID |
list_memories |
Вывести список всех памяти с возможными фильтрами по типу/контексту |
memory_stats |
Получить статистику памяти (количество по типам) |
merge_duplicates |
Объединить дублирующиеся памяти в основную запись и архивировать остальные |
mark_outdated |
Пометить память как устаревшую или заменённую, чтобы при вызове она имела меньший приоритет |
promote_to_canonical |
Повысить память до канонического знания и повысить её рейтинг доверия |
conflicts_report |
Вывести отчёт о дубликатах, конфликтующих статусах и нескольких канонических записях |
list_canonical_knowledge |
Вывести список канонических знаний, полученных из подтверждённых памяти |
recall_canonical_knowledge |
Вызвать только канонические знания, исключая сырые памяти из результатов |
recall_multihop |
Многошаговый графовый поиск по корпусу (субъект, отношение, объект) — возвращает памяти, ранжированные по агрегированному пути с цепочкой триплетов, которые достигли каждого результата. Используйте для запросов, требующих межпамятного рассуждения, которые не могут быть найдены обычным поиском. Требует заполненного MCP_TRIPLE_EXTRACTOR_*; заполните через CLI index-triples. |
| Инструмент | Описание |
|---|---|
semantic_search |
Гибридный поиск по индексированным документам с возможными source_type, метаданными доверия и режимом объяснения debug |
index_documents |
Переиндексировать документы для поиска RAG |
| Инструмент | Описание |
|---|---|
repo_list |
Вывести список файлов и папок в разрешенных путях |
repo_read |
Прочитать файл из разрешенных путей |
repo_search |
Текстовый поиск по разрешенным путям |
| Инструмент | Описание |
|---|---|
store_decision |
Сохранить решение инженера с обоснованием, статусом и последствиями |
store_incident |
Сохранить инцидент с влиянием, причиной, решением, сервисом и серьезностью |
store_runbook |
Сохранить инструкцию с процедурой, триггером, проверкой и заметками о откате |
store_postmortem |
Сохранить постмортем с причиной и действиями |
close_session |
Анализировать завершённую сессию в сырые метаданные резюме, кандидаты знаний и действия для безопасного ревью |
analyze_session |
Совместимый псевдоним для close_session с аналогичным поведением планирования и отчётов |
review_session_changes |
Вывести объяснимый отчёт ревью для завершённой сессии без принудительной записи |
accept_session_changes |
Сохранить сырое резюме и автоматически применить только низкорисковые действия консолидации |
resolve_review_item |
Разрешить элемент очереди ревью, чтобы он исчез из активного ящика, сохраняя аудит |
search_runbooks |
Поиск памяти инструкций и индексированных документов инструкций |
recall_similar_incidents |
Вызвать похожие инциденты из памяти и индексированных постмортемов |
end_task |
Консолидировать память для архивированного идентификатора задачи: пометить рабочие/процедурные записи как устаревшие, перенаправить высокоимпортные в очередь ревью |
sweep_archive |
Режим pull для сканирования MCP_TASK_ARCHIVE_ROOTS, который запускает end_task для каждого архивированного идентификатора |
store_dead_end |
Записать неудавшийся подход (с причиной и альтернативой), чтобы при поиске он выводился как предупреждение о ловушке. Используйте это для автономных неудач без контекста решения. Используйте store_decision -avoided-dead-end-id <id>, когда ловушка является частью более крупного архитектурного решения и вы хотите связать обе записи в одну цепочку обоснования (T46) |
promote_sediment |
Повысить память на более высокий слой осадка (поверхностный → эпизодический → семантический → персональный). Смотрите ... |
demote_sediment |
Понизить память на один слой осадка |
sediment_cycle |
Запустить цикл перехода осадка — автоматически применяет тривиальные повышения, направляет нетривиальные в очередь ревью |
| ... | Суммировать последние решения, инструкции, инциденты и связанные документы |
project_bank_view |
Показать структурированный вид банка проекта для канонических знаний, решений, инструкций, инцидентов, замечаний, миграций, очереди ревью или кандидатов на повышение осадка |
| Инструмент | Описание |
|---|---|
steward_run |
Запустить цикл кураторства знаний: сканировать дубликаты, конфликты, устаревшие записи и кандидаты на повышение до канонических |
steward_report |
Получить последний отчёт кураторства или конкретный по ID запуска |
steward_policy |
Получить или обновить политику кураторства, которая управляет порогами обнаружения, правилами автоматического применения и планированием |
steward_status |
Показать текущий статус кураторства: режим политики, резюме последнего запуска, количество ожидающих ревью, следующий запланированный запуск |
drift_scan |
Сравнить записи памяти с живыми источниками (файлы репозитория, документы) для обнаружения дрифта, отсутствующих ссылок и устаревшего неверифицированного знания |
verification_candidates |
Вывести список памяти, требующих верификации, ранжированные по срочности |
verify_entry |
Пометить память как верифицированную, обновив её метаданные верификации |
steward_inbox |
Вывести элементы ящика кураторства — действия, требующие ревью из обслуживания, сканирования дрифта и консолидации сессий |
steward_inbox_resolve |
Разрешить элемент ящика кураторства, применив действие: объединить, mark_outdated, повысить, верифицировать, подавить или отложить |
| ### Временные инструменты знаний |
| Инструмент | Описание |
|---|---|
recall_as_of |
Извлечение знаний, которые были актуальны в определенный момент времени, с фильтрацией по временной актуальности |
knowledge_timeline |
Показать хронологическое развитие знаний по теме — как записи создавались, заменялись и заменялись со временем |
Каждый клиент MCP загружает полную JSON-схему каждого инструмента во время initialize —
до вашего первого сообщения. При ~40 инструментах этот полезный нагрузки может занимать
десятки КБ в окне контекста модели на каждой сессии. Два дополнительных расхода усугубляют это: LLM хуже выбирают правильный инструмент по мере увеличения количества до ~20–40, и частые перезагрузки сеансов повторно оплачивают весь расход.
Установите ... для сжатия основного набора инструментов в несколько
группированных мета-инструментов, каждый из которых диспетчеризуется по обязательному дискриминатору action:
// Grouped form // Equivalent legacy form
{ "name": "memory", { "name": "store_memory",
"arguments": { "arguments": { "content": "…" } }
"action": "store", "content": "…" } }
Группы: repo · memory · memory_admin · engineering · search ·
session, плюс index_documents и project_bank_view — единственные экземпляры — поверхность по умолчанию сокращается с 41 инструмента до 8 (~42% меньше полезной нагрузки схемы).
false; флаг изменяет только то, что
tools/list возвращает.tools/call принимает группированную форму
(memory + action=store) и устаревшее имя (store_memory) независимо от флага, поэтому существующие скрипты никогда не ломаются.steward_inbox_resolve уже использует свой собственный
аргумент action — группировка специально оставляет их негруппированными.Компромисс: каждый группированный вызов несет немного больше схемы на вызов (объединение аргументов его действий). Предпочитайте группировку для высоконагруженных запусков агента, где стоимость обнаружения доминирует; оставьте его выключенным для интерактивной отладки, где видеть каждый инструмент по имени понятнее. Политика ссылки: ... покрывает связанную поверхность архивной очистки.
Вся конфигурация выполняется через переменные окружения. Смотрите ... для полного списка.
Конфигурационные файлы загружаются в этом порядке (каждый файл заполняет только значения, которые еще не установлены):
--config /path/to/file (явный путь, пропускает цепочку).env в текущей директорииДля локального режима работы скопируйте .env.example в .env в корне вашего проекта. Для brew services конфигурация автоматически создается в `$(brew ...
При запуске в качестве службы (режим HTTP) конфигурационный файл отслеживается на изменения каждые 30 секунд. Настройки RAG (каталоги индексов, ключи встраивания, включено/отключено) применяются без перезапуска. Настройки HTTP (порт, хост) требуют полного перезапуска.
Вы также можете принудительно выполнить немедленную перезагрузку:
kill -HUP $(pgrep agent-memory-mcp)
| Переменная | По умолчанию | Описание |
|---|---|---|
MCP_ROOT |
Текущая директория | Путь к корневому каталогу проекта |
MCP_ALLOW_DIRS |
"" (только MCP_ROOT) |
Разделенные запятыми дополнительные пути, относительные к репозиторию, которые инструменты файлов (repo_list, repo_read, repo_search) могут читать. Пути должны оставаться под MCP_ROOT; абсолютные пути или .. перемещения отклоняются при загрузке конфигурации. Критически для общего/HTTP-режима — держите узкими |
MCP_MAX_FILE_BYTES |
2097152 |
Максимальный размер файла (в байтах), который repo_read вернет; большие файлы отклоняются |
MCP_MAX_SEARCH_RESULTS |
200 |
Жесткий предел для количества результатов repo_search |
MCP_MAX_DEPTH |
3 |
Максимальная глубина рекурсии директорий для repo_list |
MCP_STDIO_MODE |
line |
Фрейминг stdio: line (разделенный новой строкой) или lsp (заголовки Content-Length) |
MCP_TOOL_GROUPING |
false |
Свернуть основной набор инструментов в группированные мета-инструменты в tools/list для сокращения полезной нагрузки схемы обнаружения (~42% меньше, 41→8 инструментов). tools/call принимает как группированную форму (memory+action), так и устаревшие имена независимо от флага. Смотрите [Группировка инструментов ... |
MCP_MEMORY_ENABLED |
true |
Включить инструменты памяти |
MCP_MEMORY_PREVIEW_RUNES |
0 |
Переопределить предел обрезки для поверхностей памяти (на основе рун) в ответах инструментов MCP (recall_memory, list_memories, search_runbooks, …). 0 сохраняет встроенные пределы (150/220/300); положительное значение принудительно устанавливает этот один предел для всех поверхностей; отрицательное значение отключает обрезку (полный текст). |
MCP_RAG_ENABLED |
true |
Включить инструменты RAG/поиска (предустановка службы Homebrew переопределяет это на false, пока вы не установите MCP_ROOT) |
MCP_HTTP_MODE |
stdio |
Транспорт: stdio или http |
MCP_HTTP_HOST |
127.0.0.1 |
Хост привязки HTTP; установите 0.0.0.0 для развертывания в общем/контейнере |
MCP_HTTP_PORT |
18080 |
Порт HTTP (в режиме HTTP) |
MCP_HTTP_AUTH_TOKEN |
- | Токен Bearer, требуемый для нелокального общего HTTP-режима |
| ... | false |
Явное небезопасное переопределение для общего HTTP без аутентификации |
JINA_API_KEY |
- | Ключ API Jina AI для встраивания |
OPENAI_API_KEY |
- | Ключ API OpenAI (или совместимый: Together, Mistral) |
OPENAI_BASE_URL |
... | Базовый URL совместимый с OpenAI |
OPENAI_EMBEDDING_MODEL |
text-embedding-3-small |
Название модели встраивания |
OLLAMA_BASE_URL |
http://localhost:11434 |
URL Ollama (локальный резервный) |
LLAMACPP_BASE_URL |
- | Базовый URL совместимый с OpenAI для llama.cpp (например, http://127.0.0.1:8080/v1); пусто отключает его |
LLAMACPP_EMBEDDING_MODEL |
bge-m3 |
Метка модели встраивания llama.cpp (используется только при установленном LLAMACPP_BASE_URL). Метка является частью производного идентификатора модели, хранящегося на каждой записи, поэтому ее изменение делает банк недействительным точно так же, как и изменение модели — смотрите ... |
MCP_EMBEDDING_MODE |
auto |
Режим встраивания: auto или local-only |
MCP_EMBEDDING_DIMENSION |
1024 |
Размерность вектора (изменение требует повторного индексирования) |
MCP_EMBEDDING_TIMEOUT |
5s |
Тайм-аут на запрос встраивания; увеличьте для медленных локальных бэкендов |
MCP_EMBEDDING_MAX_RETRIES |
1 |
Количество повторных попыток встраивания при временных сбоях |
MCP_INDEX_DIRS |
docs |
Разделенные запятыми каталоги и отдельные файлы для индексирования RAG. Резервный код — docs; предустановка .env.example задает ... для типичного макета проекта |
MCP_RAG_AUTO_INDEX |
true |
Индексировать документы при запуске. Код по умолчанию — true (хорошо для режима HTTP/службы); предустановка .env.example для локального режима отключает его, чтобы вы управляли индексированием с помощью явных запусков agent-memory-mcp index |
MCP_RAG_FILE_WATCHER |
false |
Отслеживать MCP_INDEX_DIRS на изменения и повторно индексировать инкрементно; полезно для долгоживущих общих/служебных экземпляров |
MCP_INDEX_EXCLUDE_DIRS |
встроенные значения по умолчанию | Дополнительные имена каталогов или относительные пути репозитория для исключения из индексирования RAG |
MCP_INDEX_EXCLUDE_GLOBS |
- | Дополнительные шаблоны glob, сопоставляемые с относительными путями репозитория, например ... |
MCP_REDACT_SECRETS |
true |
Редактировать контент, похожий на секреты, перед тем как документы будут проиндексированы |
MCP_ARCHIVE_SWEEP_ENABLED |
true |
Консолидация без операций: фоновый цикл помечает архивные рабочие памяти устаревшими (или продвигает надежные) без ручных запусков. Автоматически обнаруживает ... бездействует, если отсутствует. Смотрите [Zero-ops ... |
MCP_ARCHIVE_SWEEP_INTERVAL |
1h |
Интервал фоновой архивной очистки. 0 отключает цикл |
| ... | true |
Включить фоновое отслеживание сеансов, автоматические сырые резюме и низкорисковые оркестрации закрытия сеанса |
MCP_SESSION_IDLE_TIMEOUT |
10m |
Тайм-аут простоя перед автоматическим закрытием активного фонового сеанса |
| ... | 30m |
Интервал для периодических контрольных точек сырых снимков во время активных сеансов |
MCP_SESSION_MIN_EVENTS |
2 |
Минимальное количество отслеживаемых вызовов инструментов MCP перед автоматическим закрытием фонового сеанса |
MCP_DATA_PATH |
data |
Базовый путь для хранения данных |
MCP_RAG_INDEX_PATH |
... | Переопределить расположение индекса SQLite для векторов |
MCP_MEMORY_DB_PATH |
... | Переопределить путь к базе данных SQLite памяти |
MCP_LOG_PATH |
... | Переопределить путь к файлу диагностического журнала |
MCP_STATS_ENABLED |
false |
Добавлять записи о использовании за вызов (jsonl) для самонаблюдения |
MCP_STATS_PATH |
... | Путь к выходному файлу статистики jsonl |
MCP_STATS_SAMPLE_RATE |
1.0 |
Доля (0.0–1.0) вызовов для записи при включенных статистиках |
MCP_STEWARD_ENABLED |
auto | Включить кураторство знаний (автоматически включено в режиме HTTP с памятью) |
MCP_STEWARD_MODE |
manual |
Режим кураторства: off, manual, scheduled, event_driven |
| ... | 24h |
Интервал между запланированными запусками кураторства |
| ... | 0.85 |
Порог сходства для обнаружения дубликатов |
MCP_STEWARD_STALE_DAYS |
30 |
Дни, после которых память считается устаревшей |
MCP_STEWARD_CANONICAL_MIN_CONFIDENCE |
0.80 |
Минимальная уверенность для кандидатов на каноническое продвижение |
| ... | 0.9 |
Порог сходства Jaccard, при котором контрольная точка считается дубликатом предыдущей в том же контексте |
MCP_CHECKPOINT_DEDUP_WINDOW |
10m |
Окно времени для поиска дубликатов — только контрольные точки новее этого сравниваются |
| ... | 100 |
Минимальная длина контента (символы), после которой контрольная точка может быть сохранена; короче контента отбрасывается как пустое |
| ... | false |
Аварийный выход: полностью отключить дедупликацию контрольных точек |
MCP_TASK_ARCHIVE_ROOTS |
- | Разделенные двоеточием корни архивов для sweep-archive / end-task (например, ... Пусто отключает функцию |
MCP_TASK_SLUG_PATTERN |
- | Необязательный фильтр имен подкаталогов архива с помощью регулярного выражения; недопустимый regex приводит к сбою загрузки конфигурации |
MCP_RERANK_ENABLED |
false |
Основной выключатель для этапа нейро-реранжирования после гибридного поиска. Должен быть true И MCP_RERANK_PROVIDER должен быть реальным поставщиком (jina), чтобы реранжировщик работал |
MCP_RERANK_PROVIDER |
disabled |
Поставщик реранжирования: jina или disabled. При disabled (или пустом) конвейер деградирует до гибридного ранжирования даже при ... |
JINA_RERANKER_MODEL |
... | Идентификатор модели реранжирования Jina |
MCP_RERANK_TIMEOUT |
5s |
Жесткий тайм-аут для одного вызова реранжирования; при тайм-ауте сохраняется порядок гибрида, и rerank_failed:timeout добавляется в отладочные сигналы |
MCP_RERANK_TOP_N |
40 |
Количество лучших кандидатов гибрида, отправляемых на реранжирование; ограничено до 100 при вызове |
MCP_RETRIEVAL_STRICT |
false |
Преобразовать тихое деградирование на пути чтения в неудачный вызов: проваленный поставщик встраивания, тайм-аут реранжировщика, многошаговый запрос без графа для обхода. Предназначено для измерительных запусков (make eval включает его) и для диагностики полунастроенной установки — оставьте его выключенным в продакшене, где худший ответ лучше, чем отсутствие ответа. Независимо от этого флага каждый ответ semantic_search содержит блок retrieval, указывающий путь, который фактически обслужил его |
MCP_SEDIMENT_ENABLED |
false |
Включить извлечение с учетом слоев (символ всегда поверх, поверхность исключена вне контекста). Миграция схемы + обратная заполнение всегда выполняются; только взвешивание извлечения регулируется. Смотрите ... |
MCP_RECALL_CENTERED |
true |
Оценка воспоминания памяти по центрированным встраиваниям вместо сырого косинуса. Принято на измеренной выигрыше (T76a): на 345 запросов, помеченных машиной против живого банка, Hit@5 пошел 0.6232 → 0.7217, а MRR 0.4922 → 0.5739. Сырой косинус на реальных корпусах анизотропен — не связанные пары находились на медиане 0.555, поэтому minScore очистил 100% кандидатов и не пропустил ничего; центрированный, та же выборка очищает его при 34.1%. Банки с менее чем 100 встраиваниями игнорируют это и используют сырой косинус, так как среднее по нескольким векторам доминируется векторами, которые оно должно отменять. Установите false, чтобы оценивать так, как это делали ранние версии |
MCP_RECALL_HALFLIFE_DAYS |
0 |
T68 экспоненциальное затухание оценки воспоминания (полужизнь в днях; карта этой давности оценивается на половину веса). 0 отключает затухание — значение по умолчанию с момента T121, когда оно было измерено: на 345 запросах, помеченных машиной, Hit@5 был 0.7217 с отключенным затуханием против 0.1942 при предыдущем значении по умолчанию 30 дней, монотонный между ними (365d 0.6087, 180d 0.4609, 90d 0.2870), и нет возрастного блока, где затухание оправдало себя. Предпочтение текущей версии факта уже обрабатывается семантически за счет замещения и статуса жизненного цикла; календарный множитель не может отличить "написано давно" от "больше не правда". Вечные записи (канонические знания, слой символов) никогда не затухают |
MCP_RECALL_DECAY_TYPES |
working |
Какие типы памяти стареют, когда затухание включено вообще. Ось типа доминирует над скоростью: при той же 30-дневной полужизни затухание каждого типа оценило Hit@5 0.1942, тогда как затухание только working оценило 0.7043 — старое поведение затухало шаблоны и факты, которые являются знаниями, которые банк существует для накопления. Пусто означает, что каждый тип затухает |
MCP_RAG_KEEP_NOISE |
false |
T49 аварийный выход: сохранять шумные разделы Markdown (Содержание / Ссылки / Журнал изменений / и т.д.) в индексе вместо их удаления при разбиении на части |
MCP_TRIPLE_EXTRACTOR_ENABLED |
false |
T50 слой графа знаний. Включите, чтобы запустить асинхронный вызов LLM при каждой записи памяти, который извлекает 3-7 (subj, rel, obj) троек, управляющих recall_multihop |
MCP_TRIPLE_EXTRACTOR_BASE_URL |
- | Конечная точка /chat/completions, совместимая с OpenAI (DeepSeek, Together, Groq, Qwen, …); резервный вариант — OPENAI_BASE_URL, когда пусто |
MCP_TRIPLE_EXTRACTOR_API_KEY |
- | Токен Bearer для извлекателя. Резервный вариант — OPENAI_API_KEY только когда MCP_TRIPLE_EXTRACTOR_BASE_URL пуст или равен OPENAI_BASE_URL. Направление извлекателя на стороннюю конечную точку без предоставления ему собственного ключа отключает извлечение с явным сообщением — ключ OpenAI никогда не отправляется на адрес, для которого он не был выдан |
MCP_TRIPLE_EXTRACTOR_MODEL |
- | Идентификатор модели, переданный извлекателю (например, deepseek-chat, ... |
| ### Пути данных |
Сервер создаёт эти директории под MCP_DATA_PATH:
rag-index/ — SQLite-векторный индекс для поиска документовmemory-store/ — SQLite-база данных для памяти агентаРекомендуемая локальная настройка хранит их под .agent-memory/.
Индексация RAG сканирует поддерживаемые документы и текстовые файлы инженерии, но вы можете дополнительно снизить риски с помощью явных контролов:
.git, .agent-memory, node_modules, logs и .terraformMCP_INDEX_EXCLUDE_DIRS для исключения относительных путей репозитория, таких как ...MCP_INDEX_EXCLUDE_GLOBS для исключения по шаблону, таких как ...MCP_REDACT_SECRETS=true для удаления конфиденциальных строк и блоков приватных ключей перед индексациейЭто особенно важно, если вы используете хостинговые провайдеры встраивания или общий HTTP-режим.
При запуске сервера MCP с политикой отслеживания сессий по умолчанию он поддерживает лёгкий фоновый буфер сессий.
Текущее поведение:
close_sessionnotifications/session_event и ...safe_auto_applyЧтобы просмотреть очередь, используйте project_bank_view view=review_queue или agent-memory-mcp project-bank -view review_queue.
Чтобы закрыть элемент после ручного рассмотрения, используйте resolve_review_item или agent-memory-mcp resolve-review-item <id>.
Пример полезной нагрузки уведомления:
{
"jsonrpc": "2.0",
"method": "notifications/session_event",
"params": {
"event": "task_done",
"summary": "Incident stabilized, workaround verified, follow-up is to replace the temporary fix.",
"context": "payments",
"service": "api",
"mode": "incident",
"tags": ["done", "verification"]
}
}
Если вы хотите настроить или отключить это поведение, используйте ... MCP_SESSION_IDLE_TIMEOUT, ... и MCP_SESSION_MIN_EVENTS.
Индексация документов теперь рассматривает обновления чанков и метаданные отслеживания как единое логическое состояние.
dirty перед изменением чанковready вместе с indexed_files, embedding_model и last_indexedindex_documents / agent-memory-mcp index обнаруживает грязное состояние и принудительно перестраивает индексЭто делает инкрементальную индексацию более предсказуемой после сбоев, прерываний провайдера или ошибок хранилища.
Индексатор теперь классифицирует источники инженерии и переносит эту метаинформацию в извлечение.
Поддерживаемые типы источников:
docs для README.md и общих документов в Markdownadr и rfc для документов архитектурных решений и RFCchangelog для CHANGELOG.md и документов в стиле заметок о релизахrunbook и postmortem для операционной информацииci_config для файлов конфигурации GitHub Actions, GitLab CI и Jenkinshelm, terraform и k8s для инфраструктурных файлов с осознанием источникаИспользуйте source_type, когда хотите сузить извлечение до конкретного класса знаний:
agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type adr "cache invalidation decision"
Инструмент MCP semantic_search также принимает source_type и debug.
Поиск теперь использует несколько сигналов ранжирования вместо единственного косинусного сходства.
Текущие сигналы ранжирования:
source_type, когда требуется более узкое извлечениеКонвейер извлечения теперь работает в два этапа:
Только объединённый набор кандидатов переранжируется. Это делает совместное обслуживание извлечения более предсказуемым по мере роста корпуса индексированных документов.
Это означает, что сильное ключевое совпадение в рутбуке или changelog может занять более высокое место, чем семантически похожий, но менее релевантный документ.
Каждый результат может содержать:
source_typeconfidencelast_verified_atownerfreshness_scoreЧто это означает на практике:
search / recall и MCP semantic_search / recall_memory теперь показывают сводки доверия в удобочитаемом выводеИнструменты инженерных рабочих процессов также добавляют метку last_verified_at к сохранённым записям, чтобы свежие операционные знания было легче доверять и ранжировать.
Используйте режим отладки, когда хотите, чтобы поиск объяснил, почему был возвращён документ.
CLI:
agent-memory-mcp search -source-type runbook -debug "ingress rollback"
MCP:
semantic_search с debug: truedebug не установленным или false для нормального компактного ответаРежим отладки добавляет:
source_type=runbooksource, confidence, freshness, owner, verifiedsemantic, keyword_raw, ... recency_boost, source_boost, confidence_boost, final_scorekeyword_match или source_type:runbookЕсли вам нужен более быстрый способ инспекции, чем сырые CLI или JSON-RPC вызовы, используйте встроенную консоль в HTTP-режиме:
/console
Для чего это хорошо:
Консоль намеренно лёгкая и не заменяет инструменты MCP или рабочие процессы CLI.
Эти инструменты MCP отображают специфические рабочие процессы на существующие бэкенды памяти и поиска.
Рекомендуемые начальные точки:
store_decision для архитектурных или операционных решений, таких как отключение HPA или закрепление версии ingressstore_incident для кратковременных операционных фактов, которые вы хотите вспомнить во время активной отладкиstore_runbook для процедурных шагов, инструкций по откату и проверочных заметокstore_postmortem для устойчивых выводов по инцидентам и элементам действийclose_session когда вы хотите явный план окончания сессии с обоснованием, трассировкой и действиями, готовыми к проверкеaccept_session_changes когда отчёт о закрытии сессии низкорискованный, и вы хотите сохранить сырую сводку и применить безопасные обновленияresolve_review_item когда фоновый ящик уже содержит проверенный элемент, и вы хотите очистить его без удаления аудитного следаsearch_runbooks когда вам нужен путь исправления и вы хотите как хранимые в памяти инструкции, так и проиндексированные документы инструкцийrecall_similar_incidents когда вы триажите сбой или регрессиюproject_bank_view когда вы хотите поддерживаемое знание по представлению, а не по сырым результатам напоминания, включая review_queue для ожидающих фоновых решенийЭти инструменты рабочих процессов также добавляют метаданные проверки, чтобы поиск мог рассматривать вновь сохранённое операционное знание как более свежее и надёжное, чем анонимные сырые заметки.
Слой памяти теперь поддерживает ручной процесс консолидации без удаления исторических заметок.
Используйте эти инструменты MCP, когда знание проекта начинает расходиться:
merge_duplicates для консолидации повторяющихся заметок в одну основную память и архивирования остальных как объединённых дубликатовmark_outdated для понижения устаревших инструкций, заменённых решений или устаревших заметок по инцидентам без их потериpromote_to_canonical для пометки текущего лучшего знания как каноническогоconflicts_report для выявления duplicate_candidates, status_conflict и multiple_canonical группТекущее поведение:
Каждый завершённый таск оставляет после себя рабочие памяти (Task started, заметки по фазам, Session close, автоматически извлечённые элементы для ревью). Оставленные без внимания они накапливаются линейно и продолжают всплывать в реколле для уже завершённых тасков. Сервис автоматически консолидирует их — без крона, без ручной очистки, без конфигурации:
outdated. Он запускает первый проход сразу после старта, который также заполняет архив, накопленный до появления цикла.MCP_TASK_ARCHIVE_ROOTS он следит за ... соглашением; отсутствующая директория — тихий no-op.end_task и sweep_archive по умолчанию ведут себя так же, как и консолидирующий, поэтому явный /end-task консолидирует сразу.Детали политики (вывод состояния, порог повышения, идемпотентность, ...): ... Отключите цикл с помощью ...
Проект теперь предоставляет два отдельных слоя:
сырая память: захваченные заметки, инциденты, решения и процедурные памяти, как они были сохраненыканонические знания: подтверждённые записи, спроецированные из повышенных в канонические памятиЧто это меняет:
list_canonical_knowledge даёт вам текущий набор подтверждённых знаний без шума сырых данныхrecall_canonical_knowledge ищет только в канонических записяхlayer=raw, layer=canonical, или layer=documentИстория миграции:
promote_to_canonicaldecision или service:api, всё ещё распознаются каноническим слоемСлой управления предоставляет автоматизированное и ручное обслуживание знаний.
steward_run выполняет полный цикл обслуживания за один вызов:
dry_run=false применяет безопасные действия и отправляет остальные в папку управленияdrift_scan сравнивает записи памяти с живыми файлами репозитория:
source_changed, когда изменялся файл, на который ссылается память, после последней проверкиsource_missing, когда путь к файлу, на который ссылается память, больше не существуетstale_unverified, когда записи превышают порог устареванияverification_candidates ранжирует памяти, которые нуждаются в проверке:
verification_failed или needs_update: высокая срочностьsteward_inbox — единственное место для всех действий, требующих ревью. Решайте элементы с помощью steward_inbox_resolve, используя действия вроде merge, mark_outdated, promote, verify, suppress, или defer.
Управление автоматически включается в HTTP-режиме, когда память доступна. Настройте пороги и режим через переменные окружения MCP_STEWARD_*. Смотрите steward_policy для конфигурации во время выполнения.
Для подробного руководства см. [Stewardship ...
Памяти могут содержать временные метаданные, которые отслеживают, когда знания были действительны, и как они эволюционировали:
valid_from / valid_until — временной интервал, в течение которого эти знания были верныsuperseded_by / replaces — двунаправленные ссылки, формирующие цепочки заменыobserved_at — когда знания были впервые замечены (может отличаться от created_at)recall_as_of извлекает знания, актуальные на определённый момент времени. Это полезно для вопросов вроде "какая была наша стратегия базы данных в январе?" или "что изменилось между этими двумя датами?"knowledge_timeline показывает хронологическую эволюцию записей, соответствующих запросу, упорядоченных по valid_from.mark_outdated с заменяющей записью система автоматически устанавливает valid_until для старой записи и valid_from + replaces для новой записи, создавая навигационную цепочку.Основные рекомендации по развёртыванию:
MCP_HTTP_HOST=0.0.0.0, установите MCP_HTTP_AUTH_TOKEN, оставьте TLS на обратном прокси и сузьте MCP_ALLOW_DIRSMCP_INDEX_EXCLUDE_DIRS / MCP_INDEX_EXCLUDE_GLOBS.agent-memory/, либо используйте agent-memory-mcp export для резервных копий памятиСправочная документация:
┌──────────────────────────────────────────────────┐
│ MCP Protocol Layer │
│ (stdio or HTTP/JSON-RPC) │
├────────────┬──────────┬───────────┬───────────────┤
│Memory Tools│RAG Tools │File Tools │Steward Tools │
├────────────┼──────────┼───────────┼───────────────┤
│MemoryStore │RAGEngine │ PathGuard │ Steward │
│ (SQLite) │ │ │ Service │
│ │┌────────┐│ │ Scheduler │
│ Embedder◄──┤│DocSvc ││ │ Inbox │
│ ││VecSvc ││ │ Drift/Verify │
│ │└────────┘│ │ Policy │
│ │ (SQLite) │ │ (SQLite) │
└────────────┴──────────┴───────────┴───────────────┘
Сервер поддерживает три поставщика эмбеддингов в режиме auto:
jina-embeddings-v3, нативные 1024 измерения, мультиязычная поддержкаtext-embedding-3-small или любой совместимый с OpenAI API. Нативное измерение 1536; сервер запрашивает dimensions=1024 через параметр MRL OpenAI, чтобы соответствовать остальной части стекаbge-m3, нативные 1024 измерения, работает локально бесплатноВсе три поставщика нормализованы до одинакового векторного измерения (MCP_EMBEDDING_DIMENSION, по умолчанию 1024), но они не взаимозаменяемы: каждая модель имеет своё собственное пространство эмбеддингов. Совпадение измерений не делает косинусную схожесть безопасной между разными моделями — поэтому сервер тегирует каждую память её embedding_model и отказывается смешивать их при извлечении.
Что означает auto режим на практике:
embedding_model, с которым они были созданыembedding_model не соответствует текущей модели запроса, и переключается на текстовое сопоставление для этих записейЭто предотвращает опасный случай, когда резервный поставщик возвращает уверенные, но неверные семантические совпадения.
Если вы намеренно меняете поставщика или модель, обрабатывайте это как миграцию:
# rebuild document index for the new embedding model
agent-memory-mcp index
# re-embed stored memories for the new embedding model
agent-memory-mcp reembed
# inspect how many memories still belong to older models
agent-memory-mcp stats -json
Вы можете увеличить измерение через MCP_EMBEDDING_DIMENSION для повышения точности (например, 3072 с ... но любое изменение измерения или модели требует переиндексации и переэмбеддинга.
Если вы установите ... размещённые поставщики пропускаются полностью, и только Ollama используется для эмбеддингов.
auto режим без скрытого повреждения семантического извлеченияagent-memory-mcp statsbrew install ipiton/tap/agent-memory-mcp
brew services start agent-memory-mcp
Подробности и расположение конфигурации см. в разделе Installation Options.
./scripts/install-macos.sh
Это компилирует бинарный файл, создаёт файл .env и устанавливает сервис launchd, который автоматически запускается при входе в систему.
Ручное управление:
# Status
launchctl list | grep com.agent-memory-mcp
# Start
launchctl load ~/Library/LaunchAgents/com.agent-memory-mcp.plist
# Stop
launchctl unload ~/Library/LaunchAgents/com.agent-memory-mcp.plist
Сервер пытается использовать Jina → OpenAI → Ollama в режиме auto и останавливается на первом доступном. Если ни один из них недоступен, эмбеддинги (и, следовательно, семантическое извлечение) отключены.
JINA_API_KEY, OPENAI_API_KEY или запустите Ollama с загруженным bge-m3 (ollama pull bge-m3)OLLAMA_BASE_URL (по умолчанию http://localhost:11434), отвечает ли онCLI agent-memory-mcp store … без embedder всё равно сохраняет память, но пропускает вектор — запись будет доступна только через текстовый/ключевой поиск, пока вы не выполните agent-memory-mcp reembed.
RAG-индекс и сохранённые воспоминания помечены моделью встраивания, которая их создала. Если вы переключаете провайдера или модель, извлечение отказывается смешивать векторные пространства:
agent-memory-mcp index # rebuild RAG index for the new model
agent-memory-mcp reembed # re-embed stored memories
agent-memory-mcp stats -json # check how many memories still belong to older models
18080 занятДругой agent-memory-mcp (или не связанная служба) удерживает порт:
lsof -nP -iTCP:18080 -sTCP:LISTEN
brew services list | grep agent-memory-mcp
Если были запущены два экземпляра, остановите один (brew services stop agent-memory-mcp или kill <pid>) или измените MCP_HTTP_PORT.
brew services start agent-memory-mcp не запускает демонНаиболее распространённые причины:
brew uninstall --cask agent-memory-mcp && brew install ipiton/tap/agent-memory-mcpПосле agent-memory-mcp setup перезапустите Claude Code (хуки загружаются при запуске процесса). Проверьте слияние:
agent-memory-mcp setup --dry-run # show what would be written
jq '.hooks' ~/.claude/settings.json # inspect actual config
Если вы обновили через brew upgrade, повторно выполните agent-memory-mcp setup --force, чтобы команда хука указывала на новый путь к бинарному файлу. Смотрите ...
В режиме HTTP сервер отказывается привязываться к нелокальным адресам без MCP_HTTP_AUTH_TOKEN. Либо:
agent-memory-mcp project-bank canonical_overview и … review_queue, чтобы выявить сырые сессионные сводки, которые следует продвинуть или пометить устаревшимиMCP_CHECKPOINT_DEDUP_WINDOW)agent-memory-mcp export > backup.json (смотрите ...recall_multihop возвращает пустой результатМногоходовый граф обходит корпус (subj, rel, obj). Он пуст, пока вы либо:
agent-memory-mcp index-triples (идемпотентно, поддерживает --resume)Оба пути требуют MCP_TRIPLE_EXTRACTOR_* (смотрите Ключевые переменные) — извлечение вызывает конечную точку /chat/completions совместимую с OpenAI.
Изменения применяются в течение ~30 секунд. Принудительная перезагрузка:
kill -HUP $(pgrep agent-memory-mcp)
Примечание: хост и порт HTTP требуют полного перезапуска (brew services restart agent-memory-mcp). Только RAG-параметры поддерживают горячую перезагрузку.
# Build
make build
# Run
make run
# Test
make test
# Full quality gate (lint + tests + smoke)
make quality-gates
Для репозитория, стиля кода и соглашений по PR смотрите ...
MIT