SoupNet-oss

Soup.net — это общая память для ИИ-агентов. Агенты, с которыми вы работаете, записывают ваши суждения по мере их возникновения, а затем возвращают их в вашей следующей сессии, в другом инструменте или агенту коллеги, присоединяющемуся к проекту. Книга рецептов строится сама.

Единица хранения — рецепт: одно суждение в структурированной форме с доказательствами — «Как [роль], работая над [целью], я предпочитаю [X], чтобы [причина]», плюс дословные подтверждающие цитаты. Агенты используют его через проверку рецепта: семантический поиск, единственный побочный эффект которого — добавление записи. Ваш агент ищет, исходя из своей текущей гипотезы о вашем вкусе, получает ваши прошлые решения с их доказательствами, а сама гипотеза становится следом, который будущие агенты смогут найти. Ничто никогда не перезаписывается, и каждая проверка делает следующую умнее — тот же механизм, который муравьи используют для усиления феромонных троп (стигмергия).

Почему

ИИ-агенты сами выполняют всё более крупные фрагменты работы, и вы никогда не запускаете только одного. Каждая новая сессия — это новый агент, каждый инструмент — ещё один, а коллеги приносят своих. Каждому нужны ваши ответы, отдельно, с нуля. Ограниченный ресурс — это вы.

Большинство агентских память хранит факты и состояние разговора внутри экосистемы одного вендора. Soup.net хранит само суждение, с контекстом и доказательствами, которые его ограничивают, и он живёт с вами — переносим между Claude Code, ChatGPT, Gemini или кастомным агентом, написанным вашей командой. Прошлые решения возвращаются как контекст, а не директивы: ваш агент взвешивает их относительно текущей задачи, а не воспроизводит устаревшие факты.

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

Soup.net разрабатывается с использованием собственного рабочего процесса. ИИ-агенты, которые его создают, проверяют свои проектные решения по рецептам в корпус сопровождающего по мере работы — так что история проектирования системы живёт в самой системе, а агенты, расширяющие её, извлекают суждения, которые сформировали код, который они меняют.

Recipe Map — это способ, которым человек наблюдает за ростом этого корпуса: рецепты группируются по семантической близости, проецируясь на любые две выбранные вами оси понятий.

Related MCP server: memmd-mcp

Полевые данные

Полевая оценка проводилась на реальной работе сопровождающего в середине 2026 года — два проекта, координаторные агенты, порождающие флоты субагентов, каждый агент получил инструкцию проверять рецепты в моменты принятия решений и самостоятельно сообщать, что каждая проверка ему дала. Честные рамки: один разработчик, 3-дневное окно обратной связи по 3-месячному корпусу, все агенты семейства Claude. Наблюдательное исследование, а не бенчмарк.

• 178 проверок в 64 различных сессиях агентов, в одном объединяемом журнале.

• 68% проверок подтвердили предыдущее решение, поэтому агент продолжал работать, а не прерывал человека.

• ~4,5% проверок изменили действие агента. Редко по замыслу — но именно в этом хвосте сосредоточена ценность: самый сильный случай — это измеренный, но ошибочный вывод агента «отбросить этот индекс», который был оспорен человеком, повторно протестирован, отменён и навсегда занесён в журнал, чтобы ни один будущий агент не выводил его заново.

• 12 из 12 проверенных случаев с высоким воздействием подтвердились по сырому корпусу; ни один не был опровергнут.

• Затраты: ~1–3 КБ возвращаемого контекста на проверку, 4–6 КБ брифинг сессии, 0,15–0,36 с задержка тёплой проверки.

Известные режимы отказа, из той же оценки: самоотчёты ни разу не сказали «нет» (относитесь к каждому проценту как к верхней границе); молодой корпус возвращает ничего примерно в 1 из 10 проверок (это посев, а не сбой); и пакетные проверки в конце сессии в основном извлекают собственные свежие следы агента. Проверяйте в момент принятия решения, а не в заключительной церемонии. И один честный пробел: путь с обычным URL протестирован и работает с ChatGPT (веб), Gemini и Claude — но каждая инструментированная полевая строка до сих пор получена от агентов семейства Claude в Claude Code, поэтому цифр эффективности между вендорами пока нет. Если вы запускаете его из другого окружения, вы генерируете первые реальные данные.

Попробуйте

• Хостинг — бесплатно, открыт для новых регистраций: soup.net. Сайт генерирует одноразовый брифинг для любого используемого вами агента, от веб-чат-ботов до полноценных MCP-клиентов. На claude.ai подключение в один клик из списка в каталоге Connectors (все тарифы, включая Free).

  Путь веб-чат-бота — это полноценный интерфейс, а не запасной: агенты без MCP участвуют через сгенерированные ссылки — проверка рецепта — это URL, который агент конструирует или человек нажимает. Протестировано с ChatGPT (веб), Gemini и Claude, включая бесплатные тарифы.

• Самостоятельный хостинг — лицензия MIT, намеренно скучный стек (Postgres 17 + pgvector, Hono, React). Никакой LLM не запускается на сервере для основного пути проверки: агенты выполняют рассуждения там, где они уже работают; сервер занимается хранением и векторным поиском. (Опциональные премиум-функции — выключены по умолчанию, включаются индивидуально для пользователя — используют один серверный вызов LLM; см. docs/planning/premium-llm-features.md.) Эмбеддинги по умолчанию используют Google Gemini API (подойдёт ключ AI Studio; детерминированный заглушечный провайдер покрывает разработку и тесты без вызовов API), но самостоятельные хостинг-пользователи могут запускать их полностью локально без ключа — в процессе на CPU или против любого локального сервера /v1/embeddings (Локальные / офлайн-эмбеддинги ниже). Gemini тогда нужен только для опциональных премиум-функций. Быстрый старт ниже. В любом случае ваш корпус экспортируется как один JSON-файл (GET /auth/me/export, при входе) — и импортируется обратно: POST /import принимает тот же файл как сырое тело запроса (только для вошедших людей), так что корпус можно переносить между инстансами, восстанавливать из резервной копии или пересобирать в новую книгу рецептов. По умолчанию импорт создаёт новую книгу рецептов (назовите её через ?book_name=); передайте ?book=<slug|id>, чтобы импортировать в существующую. Повторный импорт собственного корпуса идемпотентен (upsert по точному id — повторная загрузка пропускает уже добавленное); импорт корпуса, чьи id принадлежат другому пользователю на инстансе, создаёт новые id и сообщает соответствие старых→новых, так что это инструмент переносимости, а не побайтовое восстановление (строка может даже прийти без id и всё равно импортироваться). Импорт повторно встраивает асинхронно через контентно-адресуемый векторный кэш, так что текст, который инстанс уже встраивал, стоит ноль вызовов провайдера — а удаление аккаунта сохраняет этот общий кэш, так что повторное предоставление того же корпуса остаётся бесплатным.

Укажите MCP-совместимому агенту на хостинг-сервис одной строкой:

claude mcp add --transport http soupnet https://mcp.soup.net/mcp --header "Authorization: Bearer YOUR_KEY"

Узнать больше

• docs/benchmarks.md — контролируемые результаты бенчмарков по PERMA, SWE-Lancer и π-Bench (абстракт + страницы деталей по каждому бенчмарку), дополнение к полевым данным выше

• docs/design-thinking.md — видение продукта, архетипы пользователей, сценарии проверки рецептов

• docs/architecture/overview.md — топология системы, три поверхности агента, модель данных с первого взгляда

• docs/architecture/ranking-engine.md — движок ранжирования check_recipe: цели, конвейер по этапам, точки расширения и реестр гипотез

• docs/planning/pivot-search-as-logging.md — поворот «поиск как журналирование» (история решений)

• docs/engineering-principles.md — 13 принципов, управляющих каждым проектным решением

• docs/backlog.md — текущая очередь работ; выполненные пункты в docs/backlog-completed.md

• docs/adr/ — архитектурные решения с датами и статусами

• docs/testing-plan.md, docs/workflows/security.md — как работают тесты и аудиты

Верхний раздел каждого документа указывает его назначение и отличие от соседних документов. Если вы добавляете новый документ, сделайте то же самое — и дайте ссылку в этом разделе.

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

cp .env.example .env
# Edit .env: set JWT_SECRET (openssl rand -hex 32), DEV_USERNAME, DEV_PASSWORD.
# GEMINI_API_KEY is optional locally — leave EMBEDDINGS_PROVIDER=stub for tests.

docker compose up --build -d    # postgres + backend (with in-process embedding worker) + mailpit
npm run dev:frontend            # Vite SPA on :5273 (separate terminal)

Откройте http://localhost:5273 — войдите, сгенерируйте ссылку проверки рецепта и начните проверять рецепты.

Mailpit Web UI для локальной разработки: http://localhost:8625

Локальные / офлайн-эмбеддинги

Для семантического поиска нужен провайдер эмбеддингов, выбираемый на уровне процесса через EMBEDDINGS_PROVIDER. По умолчанию (gemini) вызывает Google; stub возвращает детерминированные фейковые векторы для разработки и тестов. Ещё два провайдера позволяют самостоятельному хостингу запускать настоящий семантический поиск без внешнего API и без ключа:

• local — внутрипроцессная CPU-модель через @huggingface/transformers (по умолчанию bge-small-en-v1.5). Установите EMBEDDINGS_PROVIDER=local и всё — модель (~23 МБ) загружается один раз. Минимальное трение; хорошо для ознакомления и CI.

• openai-compatible — указывает на любой локальный сервер /v1/embeddings в стиле OpenAI, так что вы можете обслуживать более сильную модель через уже запущенный инструментарий:

  EMBEDDINGS_PROVIDER=openai-compatible
  EMBEDDINGS_BASE_URL=http://localhost:8080/v1   # llama.cpp: llama-server -m <model>.gguf --embedding --pooling mean
  EMBEDDINGS_MODEL=<the id the server reports>
  # EMBEDDINGS_API_KEY=...                        # optional bearer, if your server requires one

  LM Studio (http://localhost:1234/v1), Ollama (ollama pull nomic-embed-text → http://localhost:11434/v1) и Hugging Face TEI работают одинаково — любой конечный пункт /v1/embeddings. Если Soup.net работает в собственном контейнере, localhost означает контейнер: используйте host.docker.internal или IP хоста.

Два предостережения. Один провайдер эмбеддингов на развёртывание — векторы из разных моделей живут в разных семантических пространствах и никогда не смешиваются, поэтому переключение провайдера или модели означает повторное встраивание корпуса (поиск отказоустойчиво возвращает пустые результаты, пока вы этого не сделаете). И нативная размерность модели должна быть ≤ 3072 (или поддерживать MRL). Под капотом векторы размером менее 3072 дополняются нулями до существующей колонки halfvec(3072), что доказуемо без потерь для косинуса — дизайн, математика и критерий выхода описаны в ADR-0023 и docs/planning/local-embedding-provider.md.

Структура репозитория

Это карта ориентации для всего репозитория. Подкаталоги с собственным README (или указанным назначением в верхнем документе) содержат детали; эта карта ссылается на них.

apps/backend       Hono HTTP server (port 3101) — auth, REST API, /check recipe page,
                   remote MCP endpoint (/mcp), plus in-process pg-boss embedding consumers
                   (src/embedding-worker/). See ADR-0020, ADR-0021.
apps/frontend      Vite React SPA (port 5273) — dashboard, recipe map, admin pages
apps/mcp-server    Stdio MCP server (bundled as soupnet.mcpb for Claude Desktop)

packages/db        Drizzle schema + migrations — single claimnet schema, single source of truth
packages/domain    Business logic, ranking rules, shared agent-facing copy (no I/O)
packages/contracts Zod schemas + OpenAPI registry (mostly pre-pivot shapes; new routes inline-validate)
packages/client-sdk REST API client wrapper
packages/api-client Auto-generated React Query hooks (regenerated from contracts)
packages/config    Shared tsconfig, ESLint config

docs/              Top level: design-thinking.md, engineering-principles.md, testing-plan.md,
                   backlog.md + backlog-completed.md (the cross-session work queue)
docs/adr/          Architecture decision records — dated, with status lines
docs/architecture/ How the code works: overview, search algorithms, data model (generated)
docs/planning/     Validated proposals ready (or nearly ready) to implement
docs/rough-notes/  Dated working notes, meant to rot — see its README for the contract
                   and the fidelity ladder (rough-notes → planning → adopted docs/ADRs)
docs/workflows/    Repeatable processes (security audit cycle, etc.)
docs/connectors/   Connector-facing docs (claude.ai directory submission material)
docs/legal/        Privacy policy + ToS source material

scripts/           Dev/ops one-offs: test-ci-local.mjs (the canonical gate), cleanup,
                   data-model doc generation, QA harnesses

Настройка MCP

Основной путь — удалённый MCP через Streamable HTTP (без состояния, ADR-0021). Укажите вашему агенту на конечную точку /mcp бэкенда с API-ключом в качестве Bearer-токена — работает одинаково, запускаете ли вы локально (http://localhost:3101/mcp) или против развёрнутого инстанса (https://mcp.soup.net/mcp).

Два пути получения учетных данных, одна конечная точка. API-ключ Bearer (ниже) подходит для инструментов разработчика, где естественно вставить ключ. Клиенты в стиле чата — claude.ai, ChatGPT Developer Mode, Mistral Le Chat, Perplexity — подключаются к тому же URL /mcp через OAuth 2.1: сервер реализует метаданные RFC 8414 (/.well-known/oauth-authorization-server и /oauth-protected-resource), динамическую регистрацию клиентов (RFC 7591, POST /oauth/register), авторизацию PKCE-S256 с экраном согласия для каждой книги рецептов и ротацию refresh-токенов (apps/backend/src/routes/oauth.ts). На claude.ai Soup.net указан как коннектор в каталоге Anthropic Connectors Directory — один клик от claude.ai/directory/soupnet, доступен на всех тарифах Claude, включая Free. Пошаговые инструкции для каждого клиента: docs/connectors/index.md (отображается на soup.net/info/connect).

1. Создайте API-ключ — Войдите в SPA, откройте API keys, создайте ежедневный или ограниченный ключ, скопируйте исходное значение.

2. Добавьте сервер. В Claude Code это одна строка:

claude mcp add --transport http soupnet http://localhost:3101/mcp --header "Authorization: Bearer YOUR_KEY"

Любой HTTP-MCP клиент использует те же три факта, как бы они ни назывались в его схеме конфигурации:

{
  "mcpServers": {
    "soupnet": {
      "type": "http",
      "url": "http://localhost:3101/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Блоки конфигурации для каждого клиента (Codex, VS Code, Google Antigravity, Claude Desktop через mcp-remote или stdio-сервер в apps/mcp-server/) находятся в руководстве по адресу /docs/mcp-setup — оно обслуживается вашим собственным экземпляром или хостится с предзаполненным ключом при переходе с панели управления. Одна живая страница вместо разветвлённых копий.

3. Перезапустите клиент (или выполните /mcp в Claude Code), чтобы подхватить новый сервер. Доступные инструменты: check_recipe, get_briefing, list_my_recipe_books, update_recipe_book_description.

Контракт инструментов — только чтение и добавление. Нет поверхности для обновления или удаления, поэтому сбитый с толку (или подвергшийся prompt-инъекции) агент может добавить следы, но никогда не сможет уничтожить или переписать запись — это стоит знать, если вы оцениваете MCP-серверы с точки зрения безопасности.

Разработка

Предварительные требования: Node 24 LTS, npm ≥ 10, Docker

Запустите всё через Docker:

docker compose up --build -d    # postgres + backend + worker
npm run dev:frontend             # Vite dev server (separate terminal)

Или запустите бэкенд локально с горячей перезагрузкой:

docker compose up -d postgres    # just the database
npm run build:packages           # build internal packages
source .env && npm run dev:backend   # Hono with tsx watch on :3101
npm run dev:frontend             # Vite on :5273

Миграции базы данных:

cd packages/db
npx drizzle-kit generate         # generate migration from schema changes
# migrations auto-apply at backend startup

Тестирование

npx vitest run                    # all tests (.env auto-loaded by vitest config)
npx vitest watch                  # watch mode
npm run test:ci                   # clean reproduction of CI (fresh DB on :5534, no Gemini)

Интеграционные тесты обращаются к запущенному Docker-бэкенду, поэтому держите docker compose up -d активным.

Интеграционные тесты создают тестовые данные в живой базе данных (пользователи с email @test.local, в своих собственных книгах рецептов). Тестовые следы ограничены книгой рецептов и не появляются в ваших личных результатах поиска. Чтобы очистить накопленные тестовые данные:

npx tsx scripts/cleanup-test-data.ts           # clean up
npx tsx scripts/cleanup-test-data.ts --status  # just show counts

См. docs/testing-plan.md для ожиданий по покрытию и категорий тестов.

Публичная версия и хостинговая

Это открытый исходный код. Особенности развёртывания хостинговой версии — Terraform, операционные runbook'и, топология AWS — находятся в отдельном приватном репозитории-компаньоне, потому что они специфичны для инфраструктурных решений одного оператора и не представляют общей пользы.

Критерий для того, что должно быть в этом репозитории: понадобится ли это содержимое тому, кто самостоятельно размещает этот стек на своей инфраструктуре? Если да — оно здесь. Если это специфично для конкретного хостингового развёртывания — его здесь нет.

Приложение не зависит от способа развёртывания — только Postgres 17 с pgvector и переменные окружения из .env.example. Также не зависит от контейнерной платформы: Docker Compose локально, что угодно ещё (Kubernetes, ECS, Fly, Hetzner) в продакшене.

Ключевые правила

• Никакой бизнес-логики в обработчиках маршрутов или React-компонентах — используйте сервисы

• Никогда не вносите прямые изменения в БД — всегда используйте миграции Drizzle

• import type { ... } для импортов только типов; unknown, а не any

• См. docs/engineering-principles.md

Человек за этим

Бо́льшая часть Soup.net — код, документация, части этого README — написана AI-агентами. Всё это направляется, проверяется и за него отвечает один проверяемый человек: Andy Forest, системный архитектор и разработчик с 30-летним стажем. Недавняя работа: AI Platform Architect в Scratch Foundation; десятилетие управления Steamlabs, канадской некоммерческой организацией, которая принесла практическое AI-образование более чем 850 000 юным учащимся; соавтор Make: AI Robots (O'Reilly, переведена на японский); LiteLLM контрибьютор.

Soup.net существует потому, что он запускает множество агентов и хотел, чтобы его суждения сохранялись между ними. Модель подотчётности, описанная в этом README — агенты выполняют работу, человек отвечает за неё — это та модель, на которой построен сам репозиторий.

Лицензия и товарные знаки

Код и документация в этом репозитории лицензированы под лицензией MIT.

Название Soup.net, логотип, словесный знак и фирменные иллюстрации идентифицируют хостинговый сервис на soup.net и не покрываются лицензией MIT. Форкайте код, размещайте его самостоятельно, свободно развивайте — но представляйте свой собственный публичный экземпляр под своим именем и брендом.