Thoth-Mem

Постоянная память для ИИ-агентов кодирования

Дайте агентам кодирования долговременную память проекта между сеансами, сжатиями и сбросами контекста.

Thoth-Mem — это локальный MCP-сервер на основе SQLite и FTS5. Он сохраняет полезные решения, исправления ошибок, соглашения и непрерывность сеансов, а затем извлекает только те доказательства, которые нужны агенту. Та же установка предоставляет CLI, опциональный HTTP API и нативную интеграцию с жизненным циклом для поддерживаемых сред кодирования.

Глобальная область действия управляет конфигурацией обвязки текущего пользователя; область проекта явная и ограничена выбранным проектом и его деревом квитанций. Engram, thoth-agents или другая интеграция памяти могут пересекаться; рассматривайте это только как предупреждение: thoth-mem не редактирует, не отключает, не удаляет и не записывает во внешние репозитории.

Быстрый старт

Требуется Node.js 18 или новее. Нативная настройка необязательна: для ручного MCP-подключения нужна только команда mcp.

Запуск опубликованного пакета

Запустите последний опубликованный MCP-сервер без установки глобальной команды:

npx -y thoth-mem@latest mcp

Это запускает MCP-сервер и его локальный HTTP-мост. Добавьте --no-http, если нужен только MCP-транспорт. В новых конфигурациях клиента следует использовать явную подкоманду mcp.

Нативные интеграции вызывают постоянную команду thoth-mem после настройки, поэтому установите или обновите эту команду глобально перед настройкой обвязки. Используйте npx для запуска реализации настройки из последнего опубликованного пакета, просмотрите её план без записи, а затем примените его:

npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

Замените codex на opencode или claude для другой поддерживаемой обвязки, затем перезапустите эту обвязку. Сам по себе запуск setup не устанавливает и не обновляет npm-пакет.

Установка из этого репозитория

Используйте поток репозитория, чтобы протестировать коммиты, которые ещё не были опубликованы:

pnpm install
pnpm run build
pnpm add -g .
thoth-mem version
thoth-mem setup codex --scope global --plan --json
thoth-mem setup codex --scope global --json

thoth-mem@latest содержит только последний опубликованный релиз. Пересоберите и повторно выполните pnpm add -g . после получения новых неопубликованных коммитов.

Обновление существующей установки

Сначала обновите пакет. Если установлена нативная интеграция, повторно запустите её настройку, чтобы скопированные ресурсы, навыки, хуки и управляемые объявления пришли к новой версии пакета:

pnpm add -g thoth-mem@latest
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

Затем перезапустите обвязку или MCP-процесс. Пользователям ручного MCP не нужен setup; достаточно перезапустить npx -y thoth-mem@latest mcp.

Настройка сохраняет базу данных памяти и конфигурацию, принадлежащую пользователю. При запуске недостающие поля конфигурации могут быть заполнены автоматически, но явные значения, такие как модель LM Studio, остаются выбранными. Формат конфигурации остаётся "version": 1. Для опубликованной установки вручную обновите старый URL $schema до версии этого релиза для актуальной проверки и автодополнения в редакторе. Неопубликованная рабочая копия должна использовать config.schema.json из этого репозитория для соответствующей проверки, поскольку unpkg не может предоставить изменение до релиза. URL схемы не управляет миграцией во время выполнения.

Изменение модели эмбеддингов — это операция конфигурации, а не настройки. При необходимости отредактируйте embedding.provider, model, baseUrl и нативные dimensions; profile: "auto" разрешает поддерживаемые семейства моделей. Перезапустите thoth-mem и позвольте изменённой линии эмбеддингов поставить в очередь идемпотентную пересборку семантического индекса.

Related MCP server: LumenCore

Цикл памяти

Полезный рабочий процесс агента мал и повторяем:

1. Сохраните ценный урок. Используйте mem_save для решения, первопричины, соглашения или другого неочевидного факта, который должен пережить текущий контекст.

2. Выполняйте узкий поиск. Начните с mem_recall(mode="compact"), расширьте сильных кандидатов с помощью mode="context" и получите полную выбранную запись через mem_get.

3. Возобновляйте с идентичностью. Сохраняйте один и тот же стабильный session_id и project; используйте mem_context для недавней непрерывности и mem_session для событий жизненного цикла, принадлежащих корню.

Пример наблюдения:

{
  "kind": "observation",
  "title": "Retry SQLite writes in a new transaction",
  "type": "bugfix",
  "project": "my-project",
  "topic_key": "sqlite/busy-retry",
  "content": "**What**: Roll back after SQLITE_BUSY and retry in a new transaction.\n**Why**: Retrying inside the failed transaction repeats the failure.\n**Where**: write transaction helper.\n**Learned**: Use bounded backoff before opening the new transaction."
}

Удалите содержимое внутри <private>...</private> перед сохранением. Не храните учётные данные, полные стенограммы, сгенерированные подсказки агента как намерение пользователя или необработанные журналы без извлекаемого урока.

Шесть MCP-инструментов

Команды настройки, синхронизации, миграции, пересборки и обслуживания — это администрирование CLI/HTTP, а не дополнительные MCP-инструменты.

Просмотр графовых сообществ

Сообщества — это ограниченные сводки, полученные из графа знаний проекта. Оператор создаёт или обновляет зафиксированные сводки через CLI:

thoth-mem rebuild-communities --project my-project

Затем агент получает их через mem_project:

{
  "action": "graph",
  "project": "my-project",
  "navigation": "community",
  "limit": 5,
  "max_chars": 2000
}

Ответ сообщает состояние сообщества и свежесть, затем записи, такие как community=<id>, покрытие графа, уверенность, состояние деградации, ограниченную сводку и sources=obs:<id>. Просмотр сообщества требует проекта, но не узла фокуса или ID наблюдения. Если зафиксированных сводок нет, об этом сообщается вместо синтезирования глобального ответа.

Чтобы просмотреть доказательства, лежащие в основе сообщества, возьмите obs:<id> из его поля sources и вызовите mem_get(kind="observation", id=<id>). Идентификаторы наблюдений также появляются в результатах поиска. Для ограниченной окрестности графа используйте его как focus_node_id="obs:<id>" с navigation="neighborhood".

Встроенные интеграции с обвязками

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

Команда настройки OpenCode по умолчанию: thoth-mem setup opencode; добавьте thoth-mem setup opencode --scope project --project /path/to/project --force при явном нацеливании на проект или используйте thoth-mem setup codex --rollback /path/to/receipt.json для отката в рамках квитанции.

Статус настройки и коды выхода процесса стабильны:

Локальная настройка проекта явная:

thoth-mem setup opencode --scope project --project /path/to/project --plan --json

Проверьте обнаруженные конфликты перед применением. Используйте --force только для конфликтующих расположений, для которых владение thoth-mem уже доказано. Codex 0.144.x, 0.146.x и 0.147.x входят в протестированный набор совместимости и не требуют --force. Для других версий Codex --force может переопределить только шлюз протестированной версии, если выбранная область по-прежнему предоставляет полные, независимо проверяемые возможности диспетчера плагинов; настройка выдаёт предупреждение при использовании этого переопределения. Это не обходит проверку состояния, владения, изоляции, сверки или защиты очистки и не даёт никаких полномочий в отношении несвязанной конфигурации.

Claude Code также поддерживает собственный поток маркетплейса:

claude plugin marketplace add EremesNG/thoth-mem
claude plugin install thoth-mem

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

Резервный ручной MCP

Нативные хуки необязательны. Сохраняйте простое MCP-подключение с шестью инструментами, если вы не хотите управляемой настройки или нативного плагина; существующие воспоминания остаются доступными.

Переход на встроенную интеграцию с обвязкой

Встроенная настройка выполняется по желанию: просмотрите план без записи, проверьте конфликты, затем примените соответствующую команду обвязки. Для Codex откройте /plugins, установите thoth-mem из EremesNG/thoth-mem и проверьте состояние маркетплейса и плагина. Внешняя регистрация Codex не является атомарно обратимой, поэтому подтвердите внешнее состояние перед повторной попыткой или откатом локальной настройки.

Управляемый контракт настройки: режим плана выполняет ноль записей и только мутацию в управляемых thoth-mem расположениях. Резервные копии создаются перед первой мутацией; OpenCode принимает opencode.json или opencode.jsonc. Каждая попытка мутации записывает защищённую HMAC квитанцию со статусом in_progress перед изменениями:

• глобальные квитанции: <thoth-data-dir>/setup/receipts/<receipt-id>/receipt.json

• квитанции проекта: <project>/.thoth/setup/receipts/<receipt-id>/receipt.json

Отсутствующие или подделанные квитанции завершаются сбоем. Проверенный откат сохраняет несвязанные настройки, в то время как расхождение или недоступные возможности возвращают requires_user_action. Повторная настройка и повторный завершённый откат не выполняют операций, если проверенное состояние уже совпадает.

Gemini CLI: ручной MCP

Gemini CLI — это путь ручного MCP-клиента, а не управляемая встроенная интеграция thoth-mem. Добавьте эту запись в ~/.gemini/settings.json:

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": ["-y", "thoth-mem@latest", "mcp"]
    }
  }
}

Оценка качества поиска и графа

Репозиторий содержит детерминированные команды оценки:

pnpm run eval:retrieval
pnpm run eval:kg
pnpm run eval:embedding-models -- --help

eval:retrieval заполняет сигнальные наблюдения плюс отвлекающие факторы и измеряет, ранжируется ли ожидаемая память рядом с верхней частью. Читайте отчёт как набор сигналов:

• Полнота и ранг показывают, были ли найдены правильные доказательства и насколько рано.

• Шум и смесь случаев показывают устойчивость на прямых, перефразированных и производных от репозитория примерах.

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

• Дорожка и резервные доказательства показывают лексическое, семантическое необработанное/HyDE и KG-участие, включая ожидающее или деградировавшее семантическое поведение.

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

eval:kg измеряет ожидаемый отзыв субъект-отношение-объект, утечку запрещённых троек, детерминированное поведение извлечения и проверенное необязательное обогащение LLM. Отсутствующие ожидаемые факты указывают на пробелы в покрытии; запрещённые совпадения указывают на небезопасное изобретение графа.

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

Профили эмбеддингов и сравнение моделей

Входные данные семантических эмбеддингов форматируются версионированным профилем модели. auto распознаёт псевдонимы семейств моделей Nomic, EmbeddingGemma и Qwen3-Embedding; неизвестные модели используют raw и не получают предполагаемого асимметричного форматирования. Публичная конфигурация намеренно не имеет глобального поля task: намерение поиска и роль запроса/документа назначаются внутри для каждого входа, включая ответы HyDE в роли документа.

{
  "embedding": {
    "provider": "lmstudio",
    "model": "text-embedding-embeddinggemma-300m",
    "baseUrl": "http://127.0.0.1:1234",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

Поддерживаемые значения профиля: auto, nomic, embeddinggemma, qwen3 и raw. Переменные THOTH_EMBEDDING_PROFILE и THOTH_EMBEDDING_NORMALIZE переопределяют сохранённые значения. Разрешённая версия профиля и флаг нормализации являются частью родословной семантического индекса, поэтому их изменение помечает прежние векторы как устаревшие и использует существующую идемпотентную очередь перестроения.

Локальный вывод Transformers.js может выбирать конкретное устройство выполнения ONNX:

{
  "embedding": {
    "provider": "transformers_local",
    "model": "onnx-community/embeddinggemma-300m-ONNX",
    "device": "dml",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

Поддерживаемые значения устройства: auto, cpu, dml, cuda и coreml; по умолчанию используется cpu. Переменная THOTH_EMBEDDING_DEVICE переопределяет сохранённое значение embedding.device. В предварительно собранной среде выполнения Node ONNX Runtime, используемой Transformers.js, dml нацелен на DirectML в Windows, cuda — на поддерживаемые установки CUDA для Linux x64, а coreml — на macOS. Явно указанное недоступное устройство приводит к сбою инициализации модели, а не к молчаливому переключению на CPU. Значение auto делегирует порядок выбора провайдера и откат для конкретной платформы Transformers.js, поэтому фактический бэкенд может меняться в зависимости от хоста или версий зависимостей.

Выбор устройства влияет только на transformers_local; удалённые запросы Ollama и LM Studio его игнорируют. Бэкенды на GPU могут иметь существенно более медленный холодный старт, поэтому они наиболее полезны для постоянных процессов MCP или более крупных пакетов эмбеддингов. Устройство намеренно исключено из родословной семантического индекса: изменение только embedding.device не помечает существующие векторы как устаревшие и не ставит перестроение в очередь.

Примеры моделей провайдеров:

Локальное выполнение EmbeddingGemma использует sentence_embedding. Локальное выполнение Qwen применяет инструкцию поиска только к запросам и использует последний attended скрытый токен для пулинга. Все провайдеры отклоняют неполные, неконечные, нулевые или несовместимые по размерности пакеты. Индексы ответов LM Studio проверяются, а допустимые строки, идущие не по порядку, восстанавливаются в порядке ввода; отсутствующие, дублирующиеся или недопустимые индексы отклоняются. Во время поиска эти ошибки явно понижают семантический поиск, в то время как лексический поиск и поиск по графу знаний продолжают работать.

Запустите проверку качества на трёх моделях с явными идентификаторами моделей и постоянным путём вывода:

pnpm run eval:embedding-models -- --provider lmstudio --base-url http://127.0.0.1:1234 --nomic-model <nomic-id> --embeddinggemma-model <gemma-id> --qwen3-model <qwen-id> --output <result.json>

Проверка требует завершения всех трёх выполнений и как минимум одного кандидата, удовлетворяющего порогам Recall@1/Recall@5/MRR без регресса любого показателя Nomic. Nomic является относительным компаратором, а не кандидатом, подлежащим абсолютным порогам. Если оба кандидата проходят, явная оценка качества и стабильное правило разрешения ничьей выбирают победителя. Отсутствующая модель, недопустимый вектор, отсутствие подходящего кандидата или сбой записи отчёта приводят к ненулевому коду выхода и сохранению текущего значения по умолчанию.

Зафиксированный прогон LM Studio от 2026-08-08 выбрал EmbeddingGemma в качестве поставляемого локального значения по умолчанию. EmbeddingGemma и Qwen3 обе завершились с Recall@1 1.00, Recall@5 1.00 и MRR 1.00, против Nomic 0.50, 1.00 и 0.7167; оба кандидата были допустимы, и EmbeddingGemma выиграла их точную ничью по качеству благодаря стабильному правилу лексического идентификатора профиля. Медианная задержка в зафиксированном решающем прогоне составила 190,5 мс для Nomic, 195 мс для EmbeddingGemma и 320,5 мс для Qwen3.

Размеры файлов Qwen3 зависят от артефакта выполнения:

Модель Qwen3 Q8 на 304 069 133 байта больше, чем EmbeddingGemma Q8 в Transformers.js, и на 305 559 648 байт больше в LM Studio. Она также использует собственные векторы размерностью 1024 вместо 768 измерений EmbeddingGemma. Исполнитель не устанавливает и не обнаруживает модели провайдеров от имени оператора.

Увеличьте шум поиска, когда нужен более сложный локальный прогон:

$env:THOTH_RETRIEVAL_EVAL_NOISE='250'
pnpm run eval:retrieval

Расширенные операции

• Выполните thoth-mem help для получения полного списка команд и опций CLI.

• Откройте локальную панель по адресу http://localhost:7438/ и документацию OpenAPI по адресу http://localhost:7438/docs.

• Используйте thoth-mem sync --dir=.thoth-sync и thoth-mem sync-import --dir=.thoth-sync для переносимости, удобной для Git.

• repair-sync-journal (--project <name> | --all) --apply предварительно просматривает и внутренне связывает свой пакет исправлений. Необязательный --expected-fingerprint остаётся доступным, когда внешний рабочий процесс уже имеет предварительное связывание.

• prune-operation-traces (--project <name> | --all) --apply аналогичным образом внутренне связывает один пакет хранения. Добавьте --until-complete, чтобы обработать изначально ограниченную очередь с одним фиксированным эффективным моментом и свежими более поздними отпечатками. Внешне предоставленное связывание должно включать как --expected-fingerprint, так и --effective-now.

• compact-database [--data-dir <path>] выполняет предварительный просмотр только для чтения. Добавляйте --apply только после проверки его оценок освобождаемого пространства и ёмкости. Применение может потребовать удвоенного большего из физического и логического размеров базы данных, может быть заблокировано другими клиентами SQLite и сообщает об успехе только после проверок целостности, внешних ключей, схемы, устойчивого счётчика и WAL. Он использует управляемые SQLite контрольные точки и VACUUM; он не гарантирует откат после завершённой компактации.

• Компактация никогда не выполняется автоматически. Запуск её на живых данных требует отдельной авторизации оператора; тесты репозитория используют только одноразовые базы данных.

• Ознакомьтесь с config.schema.json для сохранённой конфигурации и настроек на основе переменных окружения.

• Данные по умолчанию хранятся в ~/.thoth/thoth.db; переопределите каталог данных с помощью THOTH_DATA_DIR или --data-dir.

Семантическое индексирование не блокирует работу. Если эмбеддинги или sqlite-vec недоступны, поиск остаётся работоспособным через поддерживаемые лексические и графовые свидетельства и сообщает о пониженном канале вместо молчаливого заявления о семантическом успехе.

Разработка

pnpm install
pnpm run integration:verify
pnpm run build
pnpm test

Лицензия

MIT