Справочник

Инструменты MCP: справочник

Как memex работает по MCP и что делает, принимает и возвращает каждый его инструмент.

Memex работает по MCP через обычный HTTPS по адресу https://memex.tools/mcp: один запрос JSON-RPC на вызов, без стриминга. Подключение авторизуется bearer-токеном, который memex выпустил для него: такой токен появляется либо при входе через ассистента, либо когда ты создаёшь его на вкладке Другой в разделе Настройки › Ассистенты. На недействительный или отозванный токен приходит ответ «Invalid or revoked token».

Любой идентификатор заметки в запросах и ответах — это номер заметки в твоей базе знаний, тот же, что в её адресе. Идентификаторы предложений и записей журнала так же нумеруются внутри базы.

У каждого инструмента есть название, которое клиенты показывают в списке инструментов memex. На каждый вызов приходит структурированный JSON. Отклонённый вызов (не хватает аргумента, якорь больше не совпадает, исчерпан лимит, у токена нет нужной роли) возвращается как ошибка инструмента с одним предложением о причине. Списки листаются через offset и limit и сообщают total. Длинный текст заметки тоже отдаётся частями — через max_chars и body_next_offset.

Инструменты — в том порядке, в каком их перечисляет memex:

search

Ищет заметки по смыслу и по ключевым словам или просто выводит их списком. С query результаты ранжируются так, как описано в статье Как работает поиск, и работают те же операторы (OR, NOT или -word, скобки, "quoted phrases"): с ними слова ищутся ровно так, как написаны, без поиска по смыслу, и ответ сообщает об этом в exact_match. Без запроса инструмент выводит заметки с отбором по tags (должны совпасть все) и status (verified или pending), в порядке order (по релевантности, по дате изменения или создания, по возрастанию или убыванию).

properties оставляет только заметки, у которых совпадают все названные свойства, — в синтаксисе Basic Memory, с запросом или без: {"status": "active"} — значение (свойство-список подходит, если содержит его); {"topics": ["a", "b"]} — список, в котором есть все эти значения; {"priority": {"$in": ["high", "critical"]}} — любое из них; {"due": {"$lt": "2026-11-01"}}, а также $gt, $gte, $lte — числа сравниваются по значению, а текст, включая даты в виде YYYY-MM-DD, — по алфавиту; {"score": {"$between": [0.3, 0.8]}} — оба конца включительно; {"client.name": "Acme"} — значение внутри сгруппированного свойства.

updated_after и updated_before, created_after и created_before отбирают заметки по времени последнего изменения или добавления. Каждый принимает момент в формате ISO-8601 или дату, которая считается началом дня по UTC: граница «после» включает свой момент, а граница «до» — нет. Без запроса один updated_after показывает, что изменилось с того момента.

До двадцати пяти результатов на страницу. В каждом — идентификатор, заголовок, описание, статус, URL источника, теги, свойства (если есть) и время последнего изменения, а иногда и раздел, который совпал. В совпадении по ключевым словам есть ещё matched_text — фрагмент текста вокруг найденных слов, так что ответ часто виден прямо в результате. Названия тегов, которым ничего не соответствует, возвращаются в unknown_tags. Если поиск по смыслу не сработал, ответ сообщает об этом в semantic_search_unavailable: тогда в результатах только заметки, где есть эти слова, а пустой результат значит лишь, что таких слов нет ни в одной заметке. Доступен всем ролям.

get

Читает одну заметку по id или по точному title, который сравнивается так же, как вики-ссылка: целиком и без учёта регистра; заметку находит и заголовок, который был у неё до переименования. Если такой же заголовок есть у других заметок, они перечислены в same_title. В ответе — весь текст, теги, свойства, вики-ссылки и обратные ссылки, статус, описание, кто добавил заметку и кто последним её менял, настоящая длина текста и former_titles — прежние заголовки. waiting_changes перечисляет правки к заметке, которые ждут твоего решения, в том числе от самого читающего: кто прислал каждую, о чём она, какие предложения текста она блокирует и что изменит. Если на заметке есть твоя пометка, в curation_flag будет твой комментарий, и ассистенту сказано ставить его выше собственного мнения. Если у заметки тег live-state, в live_state_notice — постоянная инструкция обновлять заметку, когда описанное в ней меняется; если тег user-profile, то в profile_notice — инструкция, как читать профиль, а для профиля, который ещё на проверке, — инструкция ему не следовать.

Длинную заметку ассистент может читать частями: max_chars задаёт размер куска, а следующий начинается с body_next_offset; memex говорит ассистентам не бросать заметку из-за размера. section вместо всего текста возвращает один раздел — его заголовок и всё, что под ним, до следующего заголовка того же уровня, а в ответе по длинной заметке есть outline — её заголовки, чтобы выбрать нужный. depth 1 или 2 добавляет neighbours: заметки, которые ссылаются на эту или на которые ссылается она, не дальше указанного числа ссылок, сначала ближайшие, каждая со своим описанием. Доступен всем ролям.

recent_changes

Что изменилось с заданного момента, по журналу, сначала новое: каждое изменение с заметкой, видом изменения и автором. Заметка добавлена или отправлена на проверку, изменена, удалена, восстановлена или стёрта навсегда; одобрено изменение, которое ждало проверки, или принято к сведению замечание; импорт; тег удалён или объединён с другим. since и until принимают момент в формате ISO-8601 или дату; без since берутся последние семь дней, а note_id сужает выборку до одной заметки. То, что ещё ждёт твоего решения, — в inbox, а не здесь. Только чтение, для всех ролей.

inbox

Что ждёт твоего решения: сколько заметок на проверке и сколько предложений ждут, и самые старые каждого вида, не больше limit; предложенный текст — только если передан max_chars. Только чтение, для всех ролей: ассистент может рассказать, что ждёт, и не присылать то, что уже прислал другой, но одобрить здесь ничего нельзя.

propose

Единственный инструмент записи, в двух вариантах.

Без note_id он присылает новую заметку: обязательны title и body_md, а ещё summary, tags, properties и при желании source_url. Ассистентам сказано самим писать описание, примерно в два-три предложения, сначала вызывать list_tags и list_properties и брать уже существующие теги и свойства, а в конце текста перечислять под заголовком Sources то, на что они опирались. Memex никогда не описывает и не размечает тегами то, что пишет ассистент: заметка, сохранённая без описания и тегов, ждёт в needs_enrichment. Заметка от агента попадает на проверку, от куратора — сразу проверена.

С note_id он присылает правку, и в ней только то, что должно измениться: новый title, body_md целиком на замену или patch — до пятидесяти операций по порядку, а ещё summary, tags (весь новый список), properties (только те, что меняются: каждое переданное записывается, null удаляет его, остальные остаются как есть) и change_title из шести-семи слов вместе с comment — что делает изменение, по одному короткому предложению на изменение. Один summary — уже полноценная правка.

Каждая операция patch — одна из этих:

find и replace: find скопирован из заметки точь-в-точь и встречается в ней ровно один раз; пустой replace удаляет текст. С count заменяется каждое из указанного числа вхождений; с section find ищется только в этом разделе.
append или prepend: текст добавляется в конец или в начало заметки.
section с append или prepend: в конец раздела под этим заголовком (после его подразделов) или сразу под заголовок.
section с replace: заменяет текст раздела под заголовком, сам заголовок остаётся.
section с before: текст ставится над заголовком — например, новый раздел перед Sources.

section указывается заголовком, с символами # или без; заголовок, который встречается дважды, не принимается — тогда место указывают через find. Ещё до отправки memex превращает каждую операцию в точный текст, который она меняет, так что её проверяют и применяют, как любую другую правку.

У агента правка ждёт проверки; у куратора patch или изменение поля применяется сразу, целый body_md ждёт проверки, а hold: true намеренно отправляет правку на проверку. Правка на проверке, в том числе целый body_md, хранится как набор изменённых слов и при одобрении снова сверяется с заметкой в нынешнем виде: применяются только эти слова, а слова, чей текст с тех пор изменился, отклоняются, а не применяются невпопад. body_md, который переписывает почти всю заметку, хранится целиком.

Правка предложения, заголовка, описания или свойства, которые уже меняет ждущая правка другого подключения, отклоняется — с указанием, чья правка их заняла. Один comment без всего остального — это замечание: заметка не меняется, а комментарий ждёт во «Входящих» как замечание о том, что заметка устарела. Второй propose к заметке, которая уже на проверке от того же подключения, обновляет этот черновик. Ответ говорит, что из этого произошло, и может добавить бесплатные подсказки hints: замеченные почти-дубликаты, заметки, которые текст упоминает, но не ссылается на них (с готовыми патчами), и теги из словаря, которые встречаются в тексте; ничего из этого не применено. Если на эту заметку ссылаются другие, ответ говорит об этом и просит ассистента их проверить.

propose_delete

Просит удалить заметку, с причиной reason, по которой ты сможешь решить. Ждёт проверки при любой роли. Если на заметку ссылаются другие, ответ спрашивает, куда теперь должны вести эти ссылки.

propose_merge

Просит объединить дубликат с основной заметкой: note_id вливается, into_note_id остаётся и получает его теги и обратные ссылки, а merged_body_md при желании заменяет текст основной заметки. Ждёт проверки при любой роли. Обе заметки остаются, пока ты не одобришь объединение.

needs_enrichment

Очередь заметок без описания или без тегов, сначала самые старые; заметки, описание которых уже ждёт во «Входящих», в неё не попадают. Задуманный цикл: get заметки, затем propose с её описанием, по одному вызову на заметку. Доступен всем ролям; ассистент разбирает очередь, когда ты попросишь, и никогда — без просьбы.

list_skills и get_skill

Наборы инструкций, которые memex отдаёт этому подключению: встроенные навыки и твои включённые навыки-заметки, у каждого — короткое имя, заголовок и описание; затем полный текст одного навыка по короткому имени. Список у каждого подключения свой, а не общий: его сужают то, включён ли навык, флаг, через что его отдавать (инструменты или ресурсы), и подключения, от которых он скрыт. Ассистентам сказано проверять список перед задачей, для которой может найтись навык, и следовать тому, что загрузили.

Каждый ответ инструмента несёт ещё skills_version — короткий хеш этого списка; если он отличается от того, что это подключение видело в прошлый раз, в ответе будет и skills_changed — текущий список одной строкой. Так об изменении на экране «Навыки» подключение узнаёт при первом же следующем вызове. Подробнее — Как ассистенты получают навыки и инструкции.

Все теги со счётчиком заметок по каждому, удалённые тобой названия (и во что их объединили, чтобы ассистент не предлагал вышедшее из оборота слово) и три системных тега с пометкой, что делает каждый.

list_properties

Названия свойств в заметках: у скольких заметок есть каждое и его самые частые значения, до десяти, а more_values считает остальные. У свойства-списка учитывается каждый элемент. Доступен всем ролям.

health

Подтверждает подключение, сообщает адрес этого memex, называет подключение и его роль и говорит, сколько работы ждёт (сколько всего во «Входящих» и сколько заметок ждут описания и тегов), чтобы запуск по расписанию мог остановиться, если делать нечего.

curation_candidates

Очередь на уборку: какие заметки требуют внимания и почему, в порядке, описанном в статье Как работает наведение порядка, со счётчиком по каждой причине. reason сужает выборку до одной проблемы, stale_days — до заметок, которые не читали столько дней, cooldown_days (по умолчанию семь) придерживает заметки, недавно прошедшие уборку, а include_pending добавляет заметки на проверке — для справки. Заметки, с которыми сейчас работает другое подключение, придерживаются до получаса. Доступен всем ролям. Пустой результат значит, что делать нечего.

blast_radius

Заметки, у которых недавно изменились связанные заметки, и что именно изменилось, — чтобы при уборке найти заметки, устаревшие после правки от тебя, агента или импорта; собственные правки кураторов не учитываются. Доступен всем ролям.

last_curated

Без аргументов — проверка перед стартом: когда была последняя уборка, что изменилось с тех пор, сколько заметок в очереди и не пора ли провести уборку. С note_ids — когда каждая из заметок последний раз проходила уборку. Доступен всем ролям; кураторы видят ещё, кто и что делал.

log

Только для куратора. Добавляет запись в журнал: итоги уборки не длиннее 60 слов (время начала, каждая просмотренная заметка — на что её проверяли и что нашли, — и цифры, которые называет ассистент; memex сверяет их с тем, что сам записал в журнал), наблюдение или запись о том, каких инструментов не хватает. Итоги, где перечислены просмотренные заметки, ещё и освобождают заметки, которые очередь придерживала для этого подключения; иначе они освободятся в течение получаса.

log_recent

Только для куратора. Читает журнал, начиная с новых записей: по умолчанию — историю уборок (что делали кураторы, а также твои решения, пометки и изменения тегов); по одной заметке — всё, что с ней делал кто угодно; либо записи одного вида; либо только решения, отмеченные тобой как прецедент. Ассистентам сказано, что твои комментарии к их предложениям на проверке важнее их собственного мнения и что прецедент с этого момента действует для похожих случаев.

resolve_curation_flag

Только для куратора. Снимает твою пометку с заметки с объяснением, что с ней сделано. Не согласиться с пометкой — тоже нормальный итог. Вызов отклоняется, пока удаление или объединение этой заметки ждёт твоего решения: твоё решение по этому предложению и будет ответом на пометку.

duplicate_candidates

Только для куратора. Пары самых близких по смыслу заметок с расстоянием между ними — чтобы во время уборки открыть обе и решить. unsettled считает заметки, которые ещё сравниваются; их пары придут в одном из следующих вызовов.

Фильтры коннекторов

Некоторые ассистенты обращаются к memex через коннектор, который блокирует текст, похожий на команды терминала, и вместо JSON отдаёт HTML-страницу блокировки. На этот случай любой инструмент записи принимает body_encoding: "base64": ассистент повторяет тот же вызов, закодировав текстовые поля в base64, включая текстовые поля каждой операции patch, а memex их раскодирует, и команды остаются в заметке дословно.