В период с 26 февраля по 1 апреля 2026 года я выпустил одиннадцать выпусков Neotoma. Первоначальный [выпуск для разработчиков](/posts/neotoma-developer-release) был функциональным, но сырым. Он работал на моей машине, в моих рабочих процессах, с учетом моих предположений. Пять недель отзывов оценщиков, ежедневного тестирования и практического использования выявились там, где это не помогло всем остальным.

Самая большая категория улучшений — это надежность CLI, поскольку CLI — это первое, к чему прикасается новый пользователь, и первое, что может выйти из строя во время адаптации.

Во-вторых, это стабильность MCP, потому что сервер MCP — это то, к чему агенты обращаются сотни раз в день, и молчаливые сбои на нем без предупреждения портят рабочие процессы.

Третье — целостность данных в реальных условиях. В этом посте рассказывается о том, что изменилось в пакете npm, а не на сайте или документации.

Темп был один выпуск каждые три-четыре дня. В некоторых выпусках исправлена ​​одна ошибка нумерации страниц. Другие потратили недели на усиление безопасности CLI, действий HTTP и среды выполнения MCP. Общей нитью является то, что каждый выпуск посвящен чему-то, что сломало или сбило с толку реального человека, впервые пытающегося использовать Neotoma.

## CLI перестал предполагать, что это я

Интерфейс командной строки для разработчиков работал на моей машине из исходного кода. Это был единственный контекст, который я тестировал. Первая волна отзывов показала, что этого недостаточно.

Первым исправлением было разрешение пути. Когда вы устанавливаете Neotoma глобально через npm и запускаете его из произвольного каталога, CLI должен найти свои собственные ресурсы без проверки исходного кода. В версии 0.3.3 добавлено резервное разрешение из места установки пакета. Версия 0.3.8 поставляла openapi.yaml внутри архива npm, поэтому файл спецификации был доступен всегда, а не только при клонировании репозитория.

Следующим шагом было обнаружение окружающей среды. CLI теперь различает запуск из извлечения исходного кода и запуск из глобальной установки npm. Функции, для которых требуется источник (например, туннельный режим), закрываются четкими сообщениями об ошибках, а не загадочными сбоями. Терминология в выводе CLI также изменилась: «Путь Neotoma» для настроенного местоположения среды выполнения, «Извлечение исходного кода» для рабочих процессов разработки. В предыдущем языке для обоих использовалось «репо», что сбивало с толку людей, которые устанавливали через npm и не имели репо.

Поток инициализации улучшился в нескольких выпусках. В версиях с 0.3.6 по 0.3.9 постепенно ужесточаются условия первого запуска: улучшено нацеливание на среду, более понятен пользовательский интерфейс при запуске, улучшена обработка путей конфигурации. Начиная с версии 0.3.10, CLI мог определять собственный контекст установки и корректировать поведение без необходимости сообщать пользователю что-либо.

Версия 0.3.11 была самой крупной версией CLI. Он добавил гибкий поиск («поиск объектов neotoma» с позиционными идентификаторами, «--identifier» и «--query» в качестве псевдонимов), предпочтительный структурированный путь ввода для хранилища («--entities» и «--file» наряду с существующим «--json=») и «storage merge-db» для объединения баз данных SQLite с режимами разрешения конфликтов. В версии 0.4.0 обработка аргументов стала более надежной в оболочках node, Bun и deno.

Конечный эффект: CLI перешел от «работает на моей машине» к «работает при новой установке npm в произвольном каталоге на чужой машине». Этот разрыв оказался больше, чем я ожидал.

## MCP стал безопасным для ежедневного использования агента

Сервер MCP — это то, как агенты взаимодействуют с Neotoma. Он должен быть надежным и отличаться от CLI. Агенты не читают сообщения об ошибках. Они повторяют попытку, неправильно интерпретируют или молча теряют контекст.

Первое исправление MCP было тривиальным, но важным. В версии 0.3.8 информация о реестре схемы перенесена из стандартного вывода. MCP использует stdio для структурированной связи между агентом и сервером. Вход в тот же поток повредил протокол. Агенты получали искаженные ответы или зависали. Перемещение журналов в stderr исправило класс скрытых сбоев, которые было трудно диагностировать.

Версия 0.3.11 включала более широкие обновления среды выполнения MCP, а также уровень действий HTTP и обработку запросов сущностей. Пути получения стали более надежными для запросов в виде списков, а не идентификаторов. Интеграция лексического поиска получила регрессионное покрытие. Сервер MCP и HTTP API теперь имеют больше общего поведения, поэтому агенты и прямые потребители API видят согласованные результаты.

Версия 0.4.0 продолжила эту работу, внося улучшения в создание временной шкалы, проекцию наблюдения, вычисление снимков и поведение реестра схем. Это внутренние механизмы, определяющие, что видят агенты, когда они запрашивают состояние объекта. Правильная реализация означает, что агенты получают последовательные и правильные ответы на всех сеансах.

## Пагинация и фильтрация сущностей стали честными

В версии 0.3.4 исправлена конкретная ошибка, которая выявила более широкую проблему. Когда вы запрашивали объекты по типу (скажем, все задачи), удаленные объекты включались в подсчет результатов, но отфильтровывались из видимых результатов. Для смещений нумерации страниц использовалось нефильтрованное количество. Результат: страницы с меньшим количеством элементов, чем ожидалось, непоследовательные итоговые данные и агенты, которые думали, что получили все, хотя на самом деле это не так.

Исправление заключалось в разбиении на страницы после фильтрации, а не до этого. Сумма теперь отражает видимые объекты. Это звучит незначительно, но это важно для любого рабочего процесса агента, просматривающего результаты, а это большинство из них, если у вас более нескольких десятков объектов любого типа.

## Объединение баз данных стало настоящим инструментом

Я [писал о потере и восстановлении 6000 воспоминаний](/posts/how-i-lost-and-recovered-6000-memories) в марте. Этот опыт побудил выпустить `storage merge-db` как полноценную команду CLI в версии 0.3.11.

Команда объединяет две базы данных SQLite с явной обработкой конфликтов. Три режима: «безопасный» (по умолчанию, сбой при любом конфликте), «держать цель» (цель побеждает при столкновении), «держать источник» (побеждает источник). Режим пробного прогона позволяет предварительно просмотреть, что будет вставлено и что будет конфликтовать, прежде чем вы зафиксируете изменения. После слияния команда пересчитывает снимки объектов из журнала наблюдения, поэтому полученное состояние остается правильным.

Это не просто инструмент восстановления. Он обрабатывает объединение данных из нескольких экземпляров Neotoma, миграцию между компьютерами и объединение баз данных разработки и производства. Архитектура, основанная на наблюдениях, делает все эти операции безопасными, поскольку наблюдения неизменяемы, а состояние объекта детерминировано при одном и том же наборе наблюдений.

## Расширена поддержка нескольких инструментов

Версия для разработчиков поддерживала Cursor, Claude и ChatGPT через MCP. В версии 0.3.11 добавлена ​​явная документация по интеграции ChatGPT и добавлен `openapi_actions.yaml`, поверхность в форме OpenAPI для рабочих процессов пользовательских GPT и HTTP-действий. Это означает, что ChatGPT может использовать Neotoma не только через MCP, но и через собственный интерфейс действий, который используют пользовательские GPT.

Сам контракт OpenAPI был обновлен в версиях 0.3.11 и 0.4.0, чтобы отразить изменения на уровне действий. Если вы используете Neotoma программно через API, эти выпуски требуют перепроверки всех сгенерированных клиентов.

## Старый путь извлечения удален.

В версии 0.4.0 удален путь к коду `llm_extraction`. Это был устаревший подход, в котором в конвейере хранения использовались языковые модели. Принцип проектирования Neotoma заключается в том, что ни один LLM не находится на критическом пути хранения или извлечения. Извлечение происходит на уровне агента, а не внутри Neotoma. Удаление старого пути приводит кодовую базу в соответствие с этим принципом и упрощает внутреннее устройство.

Это тот тип изменений, который невидим для пользователей, но имеет значение для направления проекта. Неотома — это слой истины, а не слой вывода. Путь эвакуации размыл эту линию. Теперь это не так.

## Чему меня научил темп

Выпуск одиннадцати релизов за пять недель не планировался. Каждый выпуск реагировал на что-то конкретное: отчет об ошибке, запутанный опыт первого запуска, рабочий процесс, нарушивший работу, архитектурную несогласованность, которую я не мог игнорировать.

Возникла следующая закономерность: ежедневное использование выявляет проблемы, отзывы оценщиков подтверждают приоритеты, а небольшие выпуски исправляют их до того, как они усугубятся. Альтернатива — пакетное объединение изменений в большие выпуски — привела бы к тому, что реальные пользователи застряли бы в некорректном поведении на несколько недель.

Релиз разработчика позиционировался как «намеренно грубый». Это было честно. Что я недооценил, так это то, сколько острых углов было характерно для моей собственной установки. Разрешение пути, обнаружение среды, безопасность stdio, согласованность нумерации страниц: все это не было для меня проблемой, потому что я запускал данные из исходного кода в своем терминале. Каждый из них был проблемой для того, кто впервые устанавливал через npm.

Следующий этап другой. Первые пять недель отвечали: «Подойдет ли это кому-то, кроме меня». Следующий этап отвечает на вопрос: «Почему кто-то отказывается от того, что уже построил».

По крайней мере десять человек из моей [группы оценщиков](/posts/customer-research-through-agents) создают собственную агентскую память. Файлы Markdown, SQLite, контрольные сигналы JSON, CRM в виде плоских файлов. Та же проблема, разные реализации. Некоторые из них назвали точные причины, по которым их решение может сломаться: одновременная запись от нескольких агентов, вопросы о происхождении, на которые они не могут ответить, масштабируются за пределы нескольких десятков активных объектов. Эти триггеры — моя дорожная карта.

Конкретные следующие цели исходят из того, что просили оценщики, а не из списка пожеланий.

- **Тривиальное внедрение с немедленной отдачей.** Интерфейс командной строки теперь работает и на других машинах, но «работает» — это не то же самое, что «пять минут на оценку». Один оценщик потратил час на чтение документации, прежде чем приступить к настройке виртуальной машины. Это должно занять пять минут, и первое, что произойдет после установки, не должно быть пустой базой данных. Адаптация, управляемая агентом, должна сканировать ваши локальные файлы, наполнять Neotoma реальными записями и выявлять временную шкалу или информацию, которой у вас раньше не было. Ага-момент не в том, что «оно установлено». Ага-момент: «он уже знает что-то полезное о моих данных».
- **Ясная история сосуществования.** Несколько экспертов задавались вопросом, должен ли Neotoma жить вместе с автоматической памятью Клода или встроенной памятью ChatGPT или заменять их. Ответ рядом, и продукт должен сделать это очевидным.
- **Глубина в областях, где происхождение не подлежит обсуждению.** Здравоохранение, соблюдение требований, финансовый аудит: оценщики в этих областях заявили, что этот язык уже подходит. Работа заключается в создании схем и гарантий бетона по этим вертикалям.

Более глубокая архитектурная работа исходит из моего ежедневного использования, а не из запросов оценщиков. Использование Neotoma в качестве основного слоя памяти в течение нескольких месяцев выявило структурные проблемы, которые никто со стороны еще не заметил.

- **Ограниченная сходимость.** Агенты стохастические. Одно и то же пользовательское сообщение может создавать разные типы сущностей, имена полей и структуры отношений в зависимости от настроения модели. Мой экземпляр имеет 170 типов сущностей, и часть этого разнообразия — это дрейф, а не настоящая онтология. В следующих выпусках добавлена ​​нормализация времени записи: сопоставления псевдонимов, чтобы `purchase` и `transaction` разрешались к одному и тому же каноническому типу, нечеткое сопоставление полей, чтобы `amount` и `amount_eur` не разветвляли схему, и хранилище с расширенным поиском, чтобы система проверяла наличие дубликатов до того, как агент их создаст.
- **Управление схемой.** Прямо сейчас любой агент может придумать новый тип объекта в первом хранилище. Эта свобода полезна на раннем этапе, но создает проблему очистки в масштабе. Планируемый уровень управления добавляет регистрацию псевдонимов, жизненные циклы устаревания и диагностические предупреждения, когда магазин отклоняется от канонической схемы. Система по-прежнему разрешает запись, но дает обратную связь в ответе, чтобы агенты могли самостоятельно исправить ситуацию.
- **Прогрессивное правоприменение.** Сегодняшние схемы предусматриваются один раз и никогда не ужесточаются. Следующим шагом является отслеживание достоверности: после достаточного количества наблюдений за типом схема кристаллизуется, и система может предупреждать об отсутствии общих полей, несоответствии типов и нарушении шаблонов отношений. Не блокировать магазины, а просто указывать на то, что выглядит не так. Строгий режим становится предпочтительным для таких важных типов данных, как финансовые отчеты, где важны отклонения при извлечении.

Neotoma — это [с открытым исходным кодом на GitHub](https://github.com/markmhendrickson/neotoma). Если вы попробовали версию для разработчиков и столкнулись с трудностями, многие из них были устранены в этих версиях. Если вы еще не пробовали, лучше всего начать с [попросите своего агента оценить, подходит ли Neotoma вашему рабочему процессу](https://neotoma.io/evaluate). Агент читает страницу, проверяет вашу установку и честно сообщает вам, подходит ли она, прежде чем что-либо устанавливать.