Общая, постоянная память для агентов, пишущих код.
Память, которая сохраняется при переключении с Claude Code на Codex и Cursor в середине проекта — и переживает исчерпание токенов в одном из них.
Если вы когда-нибудь сжигали контекстное окно, открывали другой инструмент, а затем тратили десять минут на повторное объяснение того, что делали, — это решение для этой проблемы. BlueOcean Vector запускает один небольшой сервер на вашей машине. Любой агент, поддерживающий MCP, может читать из него и записывать в него. Какой бы инструмент вы ни открыли следующим, он просто спросит: «что мы знаем об этом проекте?» и продолжит с того места, где остановился предыдущий.
[!TIP] Сохраните решение в Claude Code → откройте Codex завтра → он уже будет знать, почему вы выбрали Postgres, а не DynamoDB, а не просто то, что вы это сделали.
Related MCP server: AIVectorMemory
Каждый сеанс агента начинается с нуля. Вы объясняете проект, ограничения, «мы уже пробовали это, не сработало» — а затем сеанс заканчивается, и все исчезает. Умножьте это на каждый используемый вами инструмент, и вы тратите реальные токены просто на восстановление контекста, который уже существовал час назад.
BlueOcean Vector — это небольшое, скучное исправление: одно общее хранилище памяти, один URL и общий набор инструментов (memory_store, memory_search, memory_summarize_session и еще несколько), которые может вызывать любой MCP-клиент. Он не пытается быть умным в том, что запоминать — он просто дает агентам место, куда можно положить информацию и забрать ее обратно, с областью действия в рамках проекта, чтобы поиск в одной кодовой базе не выдавал шум из другой.
Уже существует множество проектов, посвященных «памяти для AI-агентов». Стоит честно рассказать, где находится этот проект, вместо того чтобы притворяться, что пространство пусто.
Проект | Как агент с ним взаимодействует | Кто решает, что запоминать | Семантический векторный поиск |
SDK / хостинг API | Автоматически — LLM извлекает факты при загрузке | Да, обернутый слоем извлечения | |
SDK или официальный MCP-сервер | Автоматически — сущности/связи извлекаются в граф знаний | Вторичен по отношению к обходу графа | |
Letta (ранее MemGPT) | Полноценная платформа с сохранением состояния, сервер + SDK | Полуавтоматически — собственный LLM агента управляет страничной памятью | Да, для архивной памяти |
Нативный MCP, не требует запуска сервера | Явно — вызывающий агент записывает | Только как запасной вариант (~1.8с), основной поиск — по ключевым словам | |
threadctx-mcp | Нативный MCP | Явно + опциональный пассивный захват git | Платный облачный уровень — локальный режим только по ключевым словам |
BlueOcean Vector | Нативный MCP, один общий сервер | Явно — вызывающий агент записывает | Основной и всегда включен |
Два честных вывода:
Ниша «нативный MCP, работает с любым клиентом» не пуста — Memorix уже там, с большим количеством встроенных инструментов. Отличие здесь в том, что векторный поиск является основным путем извлечения, а не запасным вариантом или чем-то, скрытым за платным уровнем, модель эмбеддингов по умолчанию действительно многоязычна (проверено на тайском+английском), и он создан для работы в качестве одного общего, постоянного сервера, а не инструмента с нулевой установкой для каждого агента — аутентификация по токену-носителю, документированный путь к ECS, готовые к Kubernetes проверки работоспособности и реальные исправления проблем параллелизма, с которыми сталкивается общий сервер.
Нет автоматического извлечения или консолидации — в отличие от mem0, Graphiti, Letta, cognee или LangMem, здесь ничто не читает ваш разговор и не решает, что стоит запомнить. Это осознанный компромисс в пользу простоты, а не отсутствующая функция: агент должен явно вызывать memory_store. Если вам нужна система, которая сама решает, что сохранить, один из проектов выше справится с этим лучше.
Некоторые проекты насчитывают миллион строк кода. И ни одна система памяти — включая BlueOcean Vector — не должна пытаться хранить все это. Хранение кода — это задача инструмента для поиска кода, а не сервера памяти.
Задача BlueOcean уже и полезнее: запоминать, что было важно, и где это найти. Он хранит решения, архитектуру, «мы пробовали это, не сработало» — сжатые знания, которые агенту пришлось бы заново извлекать из миллиона строк — плюс достаточно контекста, чтобы указать агенту на реальный код, когда нужны детали.
В результате память растет вместе с тем, что действительно стоит запомнить, а не с размером кодовой базы. У проекта на миллион строк может быть несколько тысяч записей в памяти. Это сохраняет извлечение дешевым, независимо от того, насколько большим станет проект.
Чтение памяти — вот где это различие окупается. Самый дешевый альтернативный вариант — навык или плагин, который сбрасывает заметки о проекте в файл .remember, который агент читает обратно — отлично работает, пока файл не превысит контекстное окно, после чего он перестает быть полезным.
BlueOcean ограничивает каждый поиск бюджетом токенов (по умолчанию 2000 токенов, настраивается через BLUEOCEAN_MAX_TOKENS). Семантический поиск извлекает только релевантные записи, а затем распределяет бюджет: ~60% на сжатые сводки, ~40% на полное содержание лучших результатов. Записи, выходящие за пределы бюджета, обрезаются, а не сбрасываются целиком.
Подход | Стоимость одного извлечения | Растет с размером памяти? |
BlueOcean Vector ( | ограничена бюджетом токенов (по умолчанию 2000) | Нет — ограничена, независимо от размера коллекции |
Файл | равна размеру всего файла | Да — линейно; в конечном итоге превышает контекстное окно |
Файл | равна размеру этого раздела | Частично — но агент должен угадать, какой раздел, без ранжирования релевантности |
Реальный поиск по небольшому демо-проекту вернул 121 токен для одной сводки + одной полной записи — несколько процентов от бюджета в 2000 токенов, и этот бюджет никогда не растет по мере накопления памяти в проекте. С обычным файлом то же чтение стоит полного размера файла каждый раз, поэтому проект с 5000 записей (сотни тысяч токенов) невозможно прочитать за один раз.
┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│Claude Code │ │Cursor│ │ Codex │ │Gemini/Antigrav│ │ Kiro │ ...any MCP-http tool
└─────┬──────┘ └──┬───┘ └───┬────┘ └───────┬───────┘ └──┬───┘
└───────────┴─────────┴──────────────┴────────────┘
│ http://localhost:8765/mcp
┌───────────────────────────┐
│ blueocean-mcp │ Python MCP server
│ (one shared, persistent │ (docker compose)
│ server, not per-agent) │
└─────────────┬─────────────┘
│
┌───────────────────────────┐
│ Qdrant (vector DB) │ Docker locally → ECS Fargate in the cloud
└───────────────────────────┘Несколько важных архитектурных решений:
Решение | Почему |
Один сервер, доступный по URL | Каждый популярный MCP-клиент (и множество нишевых) имеет свою собственную команду «добавить удаленный сервер». Направьте их все на один URL, и ни одному из них не понадобится от нас специальное редактирование конфигурационных файлов. |
Qdrant под капотом, одна коллекция на проект | Память для |
Многоязычность по умолчанию | Модель эмбеддингов — |
Чтение с ограничением по токенам |
|
Транспорт stdio также работает, если вы предпочитаете, чтобы каждый инструмент запускал свой собственный локальный процесс вместо обращения к общему серверу — см. Альтернатива: stdio ниже. Общий HTTP-сервер по-прежнему является рекомендуемым путем; stdio запускает отдельную копию модели эмбеддингов для каждого агента.
# 1. Bring up Qdrant + the MCP server (both run in the background via docker compose)
./scripts/setup_local.sh
# 2. Register the URL with whichever agents you use
./scripts/register_mcp.shВот и все. setup_local.sh запускает оба контейнера, ждет, пока Qdrant действительно начнет отвечать (а не просто «процесс запущен»), копирует .env.example в .env при первом запуске и синхронизирует Python-пакет. Затем register_mcp.sh вызывает CLI mcp add каждого инструмента (или, для Cursor, редактирует ~/.cursor/mcp.json напрямую, так как CLI Cursor работает только при открытом приложении), чтобы указать ему на http://localhost:8765/mcp.
Для любого другого инструмента, поддерживающего MCP через HTTP, включая те, о которых мы никогда не слышали, просто укажите ему тот же URL через функцию «добавить удаленный MCP-сервер» этого инструмента:
http://localhost:8765/mcpРегистрация сервера делает инструменты доступными; это не заставляет агента использовать их самостоятельно. scripts/install_skill.sh устанавливает небольшой навык — «проверять память в начале сеанса, записывать в нее до того, как закончится контекст» — в используемые вами агенты, чтобы привычка была без необходимости повторять это в каждом промпте:
./scripts/install_skill.sh # interactive picker
./scripts/install_skill.sh all # install into every supported tool found
./scripts/install_skill.sh --list # see what's installed whereЭто один канонический SKILL.md, символически связанный в каталог навыков каждого инструмента — отредактируйте его один раз, и каждый инструмент подхватит изменения.
Нет Docker или вы предпочитаете не запускать общий сервер? Запустите:
uv run blueocean-mcp --transport stdio --qdrant-url http://localhost:6333и укажите в конфигурации MCP инструмента command (см. .venv/bin/blueocean-mcp) вместо url.
Инструмент | Что делает |
| Сохраняет запись — содержимое, сжатое резюме, оценку важности и теги области/модуля |
| Семантический поиск с бюджетом токенов: сначала дешёвые резюме, полное содержимое для того, что помещается |
| Получает полное содержимое одной записи по ID |
| Удаляет одну запись по ID |
| Перечисляет все проекты, у которых есть коллекция памяти |
| Показывает существующие области/модули перед поиском, чтобы разумно ограничить запрос |
| Оставляет сжатую заметку для передачи любому агенту, который возьмёт задачу дальше |
| Счётчики и распределение, в основном для администрирования/отладки |
Разумный рабочий процесс агента: вызовите memory_manifest, затем memory_search в начале сессии, чтобы дёшево загрузить контекст; сохраняйте реальные решения по ходу работы с помощью memory_store (важность 5 для «почему мы выбрали X вместо Y», важность 3 для рутинного статуса); вызовите memory_summarize_session перед переключением инструментов или при нехватке бюджета.
Всё находится в .env (скопируйте .env.example для начала). Значения по умолчанию подходят для локального использования на одной машине; интересные параметры:
BLUEOCEAN_EMBEDDING — fastembed (по умолчанию, локально и бесплатно), openai или bedrock. Также укажите BLUEOCEAN_EMBED_MODEL: векторы, записанные одной моделью, невозможно осмысленно искать другой, поэтому локальная и облачная версии должны согласовывать модель.
BLUEOCEAN_QDRANT_URL — где находится Qdrant.
BLUEOCEAN_MAX_TOKENS / BLUEOCEAN_TOP_K — бюджет поиска по умолчанию.
BLUEOCEAN_AUTH_TOKEN — не задан по умолчанию (подходит для использования только на 127.0.0.1). См. Безопасность, если вы открываете доступ за пределы своей машины.
Транспорт (streamable-http vs stdio) — это флаг командной строки, а не переменная окружения: это выбор «как запустить», сделанный при старте, а не постоянная настройка.
uv run blueocean-admin stats <project>
uv run blueocean-admin manifest <project>
uv run blueocean-admin list
uv run blueocean-admin export <project>
uv run blueocean-admin prune <project> --older-days 90 --max-importance 2 [--dry-run]
uv run blueocean-admin snapshot <project> [--out ./backups]
uv run blueocean-admin restore <project> <snapshot-file> --yes
uv run blueocean-admin generate-token --write-env[!WARNING] Если несколько сессий агента используют один проект,
pruneне знает об этом. Он удаляет всё, что соответствует вашим фильтрам, даже записи, созданные другой сессией пять минут назад. Сначала запустите с--dry-runи предпочитайте узкие фильтры широкому сбросу.
export только выгружает данные в формате JSON (with_vectors=False) — восстановление из него означает повторное встраивание всего с нуля, а не реальное восстановление на момент времени. snapshot/restore используют собственный механизм снимков Qdrant: векторы, данные и состояние индекса, захваченные атомарно. snapshot загружает файл на локальный диск и удаляет серверную копию после подтверждения целостности загрузки (резервные копии, хранящиеся только внутри того же тома Qdrant, который они резервируют, не являются резервными копиями). restore перезаписывает текущие данные проекта, поэтому требует --yes.
Имена проектов строго проверяются (^[a-z0-9][a-z0-9_-]*$, в соответствии с соглашением об именах каталогов, которое уже рекомендует этот проект), а не молча нормализуются — два агента, угадывающие слегка разные написания одного проекта ("Team A" vs "team-a"), раньше сливались в одну коллекцию без предупреждения; теперь несовпадающее имя отклоняется.
Тестовые файлы в tests/ — это автономные скрипты (if __name__ == "__main__":), а не файлы, обнаруживаемые pytest — запускайте их как модули:
uv run python -m tests.smoke
uv run python -m tests.auth
uv run python -m tests.mcp_e2e
uv run python -m tests.backup # real snapshot -> delete collection -> restore cycle
uv run python -m tests.health # /health diagnostics + the cloud-provider self-test TTL cachetests/auth.py специально проверяет, что неаутентифицированные запросы и запросы с неверным токеном отклоняются (401), а правильный токен работает как через заголовок, так и через путь с параметром запроса ?token=.
По умолчанию аутентификация отсутствует — разумно для локального использования только на 127.0.0.1, но неразумно, как только сервер становится доступен откуда-либо ещё.
[!IMPORTANT] Если вы открываете доступ к этому серверу за пределами localhost (общая машина, облако), установите
BLUEOCEAN_AUTH_TOKENпрежде чем делать что-либо ещё.
uv run blueocean-admin generate-token --write-env
docker compose up -d --force-recreate blueocean-mcp
./scripts/register_mcp.sh # reads the token from .env, re-sends it to every toolНе каждый инструмент может установить пользовательский заголовок при регистрации удалённого сервера по URL, поэтому сервер принимает токен двумя способами, и каждый клиент использует тот, который поддерживает:
Authorization: Bearer <token> — Claude Code, Gemini/Antigravity
?token=<token> в URL — Codex, Kiro, Cursor
Транспорт stdio полностью пропускает это: это локально порождённый подпроцесс, уже ограниченный правами ОС на порождение процессов, а не находящийся в сети.
GET /health намеренно не требует аутентификации и проверяет, что Qdrant действительно доступен, а не только то, что процесс жив. Именно этот эндпоинт опрашивает healthcheck в docker-compose.yml. Он также сообщает активного провайдера/модель встраивания, а для openai/bedrock (не fastembed, чья загрузка модели уже блокирует запуск процесса) проверяет учётные данные через бесплатный управляющий вызов, а не платный эндпоинт встраивания, кэшируя результат на BLUEOCEAN_HEALTH_EMBED_TTL секунд (по умолчанию 60), чтобы интервал опроса в 10 секунд не превращался в вызов API провайдера при каждом запросе:
{"status": "ok", "qdrant": "reachable", "embedding": {"provider": "fastembed", "model": "intfloat/multilingual-e5-large", "ok": true}}Устанавливайте токен через BLUEOCEAN_AUTH_TOKEN (переменная окружения / .env), а не через флаг CLI --auth-token — значение, переданное как аргумент командной строки, видно любому другому локальному пользователю через ps. Журналирование доступа к запросам также отключено по умолчанию (access_log=False), поскольку три из пяти поддерживаемых клиентов отправляют токен как ?token=..., и обычный журнал доступа помещал бы его в открытом виде в ваши логи при каждом запросе.
docker compose up -d запускает два долгоживущих сервиса: qdrant (порт 6333) и blueocean-mcp (порт 8765). Для облака те же два сервиса переносятся в ECS Fargate (или Qdrant Cloud плюс небольшой сервис Fargate/App Runner для blueocean-mcp) — зарегистрируйте публичный URL в каждом инструменте точно так же, как вы делали бы локально. Dockerfile фиксирует модель встраивания, чтобы векторы, созданные в облаке, были совместимы с созданными на вашем ноутбуке.
Kubernetes не читает healthcheck: из docker-compose.yml — ему нужны собственные пробы в спецификации Pod, но они могут указывать на тот же путь:
readinessProbe:
httpGet: { path: /health, port: 8765 }
livenessProbe:
httpGet: { path: /health, port: 8765 }qdrant-client привязан к точной версии сервера Qdrant (см. тег образа в docker-compose.yml). Qdrant версионирует клиент и сервер синхронно, и API менялся между релизами — .search() был удалён в пользу .query_points() в версии 1.19. Если вы обновляете образ сервера, обновите qdrant-client до соответствующей версии и перезапустите набор тестов; не перескакивайте через несколько версий на реальных данных без предварительного снимка.
mcp зафиксирован >=2.0.0,<3.0.0, жёстче, чем большинство зависимостей здесь. Его API (mcp.server.mcpserver.MCPServer и друзья) значительно менялся между релизами, и свободное ограничение рискует тем, что Docker-сборка молча разрешит несовместимую версию — Docker-сборки не используют uv.lock.
Провайдер и модель встраивания — это согласованная пара. Если изменить что-то одно, старые векторы станут бесполезным мусором для новых. Зафиксируйте модель в .env, а не полагайтесь на значение библиотеки по умолчанию, которое может измениться без вашего ведома.
MIT — см. LICENSE.
Delete a single memory entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| point_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full disclosure burden. It only says 'Delete', which implies irreversibility, but fails to state this explicitly, required auth scopes, or if the deletion is soft or hard. No annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Could arguably add 'irreversibly' for transparency, but current length is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 required params, 0% coverage, an output schema exists but is not referenced, and 7 siblings. The description is too minimal; it omits return value info, ID source hints, and deletion semantics. Incomplete for reliable agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It does not explain what 'project' or 'point_id' represent, their formats, or any validation rules. The description adds no paramenter meaning beyond the schema's field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a single memory entry'), differentiated from siblings like memory_store or memory_search. The 'by ID' detail specifies the key identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives (e.g., memory_summarize_session might delete differently), no prerequisites for which IDs are valid, and no consequences like cascading effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full content of a single memory entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| point_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It states it retrieves content, but it does not disclose any side effects (none expected for get), permissions needed, or error behavior (e.g., what happens if point_id not found). The lack of annotations is mitigated by the read-only nature implied by 'Fetch', but more context on behavior would improve the score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, short and front-loaded with action and object. It contains no redundant information, earning its place. However, it lacks any additional detail that could make it more helpful without expanding much.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is adequate for a basic retrieval. However, it leaves gaps: the 'project' parameter is unexplained, and the response format is not described (no output schema). A more complete description could clarify the project scope or that the full content is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description mentions 'by ID' which aligns with 'point_id', but it does not explain the 'project' parameter's role or provide any context beyond what the schema already offers. The description adds minimal value, leaving the agent to infer the purpose of 'project'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), identifies the resource ('a single memory entry'), and specifies the retrieval mode ('full content by ID'). It clearly distinguishes from sibling tools like memory_search (searches) or memory_list_projects (lists), as it targets a single entry by a unique identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is clear but does not provide explicit guidance on when to use this tool vs alternatives. It implies usage for retrieving a known memory entry by ID, but it does not mention when not to use it (e.g., for partial content) or direct the agent to other tools like memory_search for lookup by content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects that have a memory collection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'List all projects,' failing to disclose read-only nature, return format, authentication needs, or any side effects. This is insufficient for safe agent usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no unnecessary words. Every part adds value, and it is front-loaded with the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and low complexity, the description should clarify what is returned (list of project names? IDs?). It is adequate for a simple listing but incomplete for an agent to fully understand the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is 100% by default. Per guidelines, 0 params yields a baseline of 4. The description adds no param semantics, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'all projects that have a memory collection,' using a specific verb and resource. It is distinct from sibling tools like memory_store or memory_search, though it does not explicitly differentiate from memory_stats or memory_manifest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives (e.g., memory_stats might list stats). The description only states what it does, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the areas/modules present in a project's memory.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It does not mention whether the operation is read-only, what happens if the project does not exist, or any side effects (likely none). The verb 'Show' implies a read operation, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is very concise. However, it is somewhat under-specified for a tool with no annotations and no param descriptions, so it leans slightly toward being too brief rather than optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (1 required param, no annotations, no output schema), the description is incomplete. It does not explain what 'areas/modules' mean, what the output format looks like, or how this differs from memory_stats. An agent would need to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single parameter 'project'. It does not explain what valid project values are, how to specify them (e.g., name, ID), or whether the parameter is case-sensitive. This leaves the agent guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show' and the resource 'areas/modules present in a project's memory', which is specific and distinguishes it from siblings like memory_stats (which likely shows statistics) or memory_store (which stores data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as memory_stats or memory_search. The description does not provide context about what kind of memory overview this offers or when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search a project's memory with token-budgeted return (summary + full layers).
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| query | Yes | ||
| top_k | No | ||
| module | No | ||
| project | Yes | ||
| max_tokens | No | ||
| importance_min | No | ||
| time_range_end | No | ||
| time_range_start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It hints at token budgeting and a two-layer result structure, but it doesn't disclose what happens when the token budget is exceeded (truncation? sorting?), whether the tool is idempotent/read-only, or any rate-limit concerns. For a semantic search that returns multiple entries, key behavioral traits like ordering (by relevance?) and result format are underspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It could improve clarity by unpacking jargon like 'full layers' and 'token-budgeted return', but it remains concise and scannable. A small structure improvement would be breaking into two sentences for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (9 parameters, zero descriptions, no output schema), a one-line description is vastly insufficient. It omits the return format structure, ordering, how filters combine, and the role of the token budget. The agent cannot reliably determine how to craft calls or interpret results from this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the nine parameters, so the description must compensate. It mentions 'query' and 'token-budgeted' (mapped to max_tokens) but fails to explain area, module, top_k, importance_min, time_range_start, time_range_end, or their interplay. Most parameters remain opaque to the agent, making effective invocation difficult.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as performing a semantic search over a project's memory with a token-budgeted return that includes both a summary and full layers. This distnguishes it from siblings like memory_get (exact retrieval) and memory_store (write), but it doesn't explicitly contrast them. The purpose is well-stated but could be strengthened by naming when to prefer this over other memory tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use semantic search vs. the alternative memory tools like memory_get or memory_list_projects. It doesn't state prerequisites, restrictions (e.g., project must exist), or typical use cases. With seven siblings, explicit 'when to use' advice is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Admin: collection stats (count, importance/area distribution, size).
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It mentions the output includes 'count, importance/area distribution, size' but does not explicitly state that the operation is read-only, what permissions are required beyond 'Admin', whether any side effects occur, or if rate limits apply. The safety profile is only implied by the nature of 'stats'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one short sentence with no filler. It front-loads the key information ('Admin: collection stats') and then lists the statistics provided. However, it could be slightly more informative without losing conciseness (e.g., specifying the parameter). It earns its place but is at the edge of under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the high-level output but omits the return format (e.g., object keys, data types) and any explanation of valid values for 'project'. With no output schema, the agent might need to guess the structure. The description is minimally complete for a stats retrieval but lacks enough detail for reliable invocation without domain knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required parameter 'project'. The description does not explain what 'project' represents (e.g., project name, ID, or path) or how to use it. The phrase 'collection stats' loosely ties to the parameter, but the agent is left guessing whether 'project' refers to a project identifier or a collection name. The description adds no semantic value beyond the schema's bare type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it provides admin-level collection statistics including count, importance/area distribution, and size. This distinguishes it from sibling tools like memory_list_projects (which lists projects) and memory_search (which searches within a collection). The verb 'stats' implies retrieval, and the resource is 'collection stats', making the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The prefix 'Admin:' hints at restricted access, but there is no explicit statement of prerequisites, user roles, or scenarios where other tools (e.g., memory_list_projects, memory_get) would be more appropriate. The agent receives no help in deciding between memory_stats and its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a memory entry for a project (content + condensed summary + importance + area/module).
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | ||
| module | Yes | ||
| content | Yes | ||
| project | Yes | ||
| summary | Yes | ||
| metadata | No | ||
| importance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions persistence but does not state whether this is a create or update operation, if it overwrites existing entries, or what idempotency guarantees exist. For a tool that stores data, these details are critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It effectively conveys the core action, but could benefit from a second sentence to cover usage guidance or behavioral notes without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 0% schema coverage, no annotations, and an output schema (not described), the description is incomplete. It fails to clarify what the tool returns, how conflicts are handled, or how 'importance' is interpreted. The sibling tools suggest a rich system, but this description lacks enough detail for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate. It mentions content, summary, importance, area, and module but adds no extra context (e.g., format, constraints, or relationships). The 'metadata' and 'importance' parameters lack any semantic explanation beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it persists a memory entry and lists the key fields (content, condensed summary, importance, area/module). It distinguishes the tool from siblings like memory_search and memory_get, but could be more explicit about its unique role among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives like memory_summarize_session or memory_manifest. It does not specify prerequisites, when not to use it, or how it fits into the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a condensed summary of a work session for later retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | ||
| project | Yes | ||
| conclusion | Yes | ||
| importance | No | ||
| session_id | Yes | ||
| observations | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'store for later retrieval' without disclosing side effects like overwriting, idempotency, or dependencies. With no annotations, the bare description fails to convey behavioral traits beyond basic write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, which is very concise. However, it lacks any structure (e.g., bullet points, examples) and does not earn its place by providing sufficient information for a tool with 6 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters (5 required), 0% schema coverage, and no annotations, the description is severely incomplete. It does not explain the purpose of each parameter, expected output, or constraints, making it inadequate for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no parameter-level meaning. The agent receives no explanation for fields like project, area, observations, conclusion, session_id, or importance, leaving critical semantics ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores a condensed summary of a work session, using a specific verb and resource. It distinguishes from generic memory_store by emphasizing session summaries, but does not explicitly differentiate from siblings like memory_store or memory_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., memory_store for raw data, memory_search for retrieval). The description lacks context for prerequisites or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0memory_deletememory_getmemory_list_projectsmemory_manifestmemory_searchmemory_statsmemory_storememory_summarize_sessionScored across 8 tools
Each tool targets a distinct memory operation: stats, store, search, get by ID, delete, list projects, manifest areas, and session summary. No two tools overlap in purpose, ensuring clear differentiation for an agent.
All tools follow the uniform 'memory_<verb>_<noun>' pattern with snake_case. Verbs are descriptive and consistent (stats, store, search, get, delete, list_projects, manifest, summarize_session), making the set predictable and easy to navigate.
With 8 tools, the surface covers the core memory management lifecycle (create, read, delete, search) plus administrative utilities (stats, manifest, project listing, session summary). This is well-scoped without being excessive or sparse.
The tool set covers the fundamental CRUD operations except for an explicit update/modify tool. While search and get provide read access, and store creates new entries, the absence of an update operation is a minor gap that agents may need to work around.
Long-term memory for AI coding agents: durable project facts, recalled by every MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
An MCP memory server. One memory your agents share — across models, devices and apps.
