Понимание графа: рекурсивная среда для устойчивого понимания

Рекурсивная среда для устойчивого, проверяемого понимания.

Understanding Graph — это MCP-сервер, который даёт AI-агентам структурированную, постоянную память. В отличие от баз знаний, хранящих факты, он хранит внешне полезные обновления понимания — напряжения, неожиданности, решения, доказательства и то, как убеждения менялись со временем. Он не требует приватной цепочки рассуждений. Несколько агентов могут координироваться через сам граф: каждый агент читает написанное другими, развивает это и оставляет проверяемые следы для следующего — стигмергия.

Почему Understanding Graph?

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

Related MCP server: Loxo

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

Рекомендуется: используйте свою подписку Codex или Claude

Запустите инициализатор в каталоге, где должна жить работа на основе графа:

cd your-project
npx -y understanding-graph@0.1.30 init

Он создаёт конфигурацию MCP в рамках проекта для Codex и Claude Code, устанавливает тот же контракт плавного понимания в AGENTS.md и CLAUDE.md, устанавливает навык reading-mode в рамках проекта для обоих клиентов и добавляет локальный путь projects/ в правила игнорирования, не устанавливая стартовый граф. Откройте любой клиент, войдите с обычной подпиской ChatGPT или Claude и попросите выполнить реальную задачу исследования, написания, кодирования или принятия решений. Агент создаёт граф с описательным именем, когда начинается настоящая работа. Вам не нужно говорить «используй граф». Модель работает в клиенте подписки; сам Understanding Graph не совершает вызовов к API моделей.

Для свежего хронологического чтения дайте агенту путь к файлу и попросите включить режим чтения. Он подготавливает исходник, не возвращая и не сэмплируя его содержимое, затем встречает только следующий упорядоченный отрывок через source_read и может прикреплять обычное, основанное на отрывке понимание перед продолжением. Codex также предоставляет $reading-mode; Claude Code предоставляет /reading-mode. Текст, вставленный прямо в чат, уже был встречен, поэтому используйте путь к файлу, когда действительно важно свежее чтение.

Codex доступен через подходящие планы ChatGPT, а Claude Code может использовать Claude Pro или Max. Обычные лимиты планов по-прежнему действуют.

Устанавливаемый плагин (навык рабочего процесса + MCP-сервер)

Пакет поставляется с манифестами .codex-plugin и .claude-plugin. Плагин объединяет возможности MCP с навыком understanding-work. Пока режим активен, в графе развивается материальное, передаваемое понимание, которое может иметь значение для работы или будущего запроса. Граф предлагает небольшой набор зависящих от состояния конкретных следующих шагов; модель оценивает их веса относительно задачи пользователя и свободно выбирает, комбинирует, изменяет или отклоняет их. Инициализатор выше предоставляет тот же контракт, не дожидаясь списка каталога плагинов.

Для Claude Code существующий поток маркетплейса выглядит так:

# One-time: add the Emergent Wisdom marketplace
claude plugin marketplace add emergent-wisdom/marketplace

# Install the plugin
claude plugin install understanding-graph

Для локальной разработки:

claude --plugin-dir /path/to/understanding-graph

Это даёт вам MCP-сервер и следующие навыки:

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

Что создаёт инициализатор

Он создаёт:

• .codex/config.toml — конфигурация MCP для Codex

• .mcp.json — конфигурация MCP проекта для Claude Code

• AGENTS.md и CLAUDE.md — один и тот же канонический рабочий процесс понимания

• .agents/skills/reading-mode/SKILL.md — явный рабочий процесс чтения для Codex

• .claude/skills/reading-mode/SKILL.md — явный рабочий процесс чтения для Claude Code

• запись в .gitignore для projects/ — сохраняет данные графа локально; стартовый проект не создаётся

Каждая сессия, открытая в каталоге, использует один и тот же корень проекта. После выбора именованного графа работающие там агенты используют его. Используйте дополнительных агентов только тогда, когда в работе есть реальные независимые стыки.

Сырая конфигурация MCP (продвинутый уровень)

Если клиент не может установить плагины или запустить инициализатор, подключите MCP-сервер напрямую:

claude mcp add ug -- npx -y understanding-graph@0.1.30 mcp

Инициализация MCP по-прежнему предоставляет краткий контракт использования графа, но поддержка серверных инструкций у клиентов различается. Для стабильного поведения также предоставьте встроенный навык understanding-work или его сгенерированные проектные инструкции.

Руководства по настройке для каждого клиента: Claude Code · Claude Desktop · Cursor · mcporter

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects",
        "UG_SOURCE_ROOT": "/path/to/your/source-project"
      }
    }
  }
}

UG_SOURCE_ROOT ограничивает загрузку файловых источников этим каталогом. Инициализатор проекта автоматически устанавливает его в корень проекта.

Cursor / Windsurf

Добавьте в вашу конфигурацию MCP:

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects"
      }
    }
  }
}

Веб-интерфейс / 3D-визуализация

Корневой npm-пакет включает собранный фронтенд и зависит от веб-сервера, поэтому опубликованный пакет может запускать интерфейс напрямую:

PROJECT_DIR=/path/to/your/projects npx -y understanding-graph@0.1.30 start
# open http://localhost:3000

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

PORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y understanding-graph@0.1.30 start
PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.1.30 start

Используйте абсолютные пути в развёртываниях. Совместное использование установленного пакета и его read-only фронтенда безопасно; не направляйте независимые сайдкары на один и тот же PROJECT_DIR.

Сервер по умолчанию привязывается к loopback. Чтобы запустить воркер на другом хосте, явно задайте HOST и приватный токен воркера; запуск не на loopback завершается с ошибкой без обоих:

HOST=0.0.0.0 PORT=3101 \
UG_WORKER_TOKEN=replace-with-a-long-random-secret \
PROJECT_DIR=/srv/undergraph/worker-1 \
npx -y understanding-graph@0.1.30 start

Доверенный вызывающий должен отправлять Authorization: Bearer <UG_WORKER_TOKEN> в каждом запросе к /api или /admin. Помещайте удалённый трафик за TLS или частную аутентифицированную сеть.

Чтобы вместо этого разрабатывать интерфейс из checkout:

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web
# open http://localhost:3000

Опционально: включение поиска на основе эмбеддингов

graph_semantic_search, graph_similar, graph_semantic_gaps и graph_backfill_embeddings могут использовать @huggingface/transformers (локальная модель эмбеддингов, примерно 160 МБ после компиляции). Это опциональная peer-зависимость, поэтому стандартная установка остаётся компактной. Для проекта на npx установите оба пакета локально, чтобы Node мог разрешить peer из того же дерева зависимостей:

npm install --save-dev understanding-graph@0.1.30 @huggingface/transformers@4.2.0
npx understanding-graph@0.1.30 init

Отдельная глобальная установка @huggingface/transformers не гарантированно удовлетворяет изолированную установку в кэше npx.

Без неё остальная часть графа работает нормально. graph_understand и graph_semantic_search используют детерминированный лексический поиск, когда эмбеддинги недоступны; инструменты семантического анализа объясняют, когда нужна опциональная модель.

Как это работает

Прямые мутации концепций и рёбер идут через graph_batch. Соответствующие режимы рабочего процесса также предоставляют помощники для документов на верхнем уровне; используйте пакет, когда связанные изменения документов, концепций и рёбер должны применяться вместе. Каждый пакет требует commit_message и выполняется в транзакции SQLite: если любая операция завершается с ошибкой, весь пакет откатывается, как будто его не было. Инструменты рабочего процесса, такие как source_read, управляют собственными атомарными обновлениями. Обычная работа пересматривает, архивирует или заменяет узлы, сохраняя их историю; необратимое удаление — отдельное, явно выбранное административное действие. Поток коммитов становится проверяемым журналом обновлений — сообщение коммита каждого узла становится его Историей происхождения.

1. project_switch({ project: "my-project" })
2a. DIRECT: use graph_understand, graph_batch, or another graph tool immediately
2b. GUIDED: graph_suggest_next({ task, workflow: "coding" })
3. [if guided, judge, modify, reject, skip, or choose a sampled route]
4. graph_batch({ commit_message, agent_name, ... }) # preserve artifact + understanding

Опциональный выборщик — это помощник для выявления специфичных для графа указателей, которые могут углубить или разнообразить понимание, восстановить упущенный материал, проверить текущее представление или выявить полезную связь. Предложения сэмплируются на стороне сервера из взвешенных по графу и рабочему процессу давлений, включают конкретные узлы или области, когда это возможно, и временно снижают вес недавно предложенных типов действий. Модель остаётся ответственной за соответствие задаче и может всегда работать напрямую, делать что-то другое или остановиться, а не фабриковать работу. Установите UG_GUIDANCE_MODE в direct, чтобы убрать фоновые подсказки; graph_suggest_next остаётся доступным по запросу.

Атомарные коммиты

graph_batch — это точка входа для мутаций концептов и рёбер, а также для атомарных многошаговых изменений документов. Внутри одного батча можно объединять graph_add_concept, graph_connect, graph_question, graph_supersede, doc_create и другие. Предварительная проверка принимает как ID, так и названия для graph_connect и вычисляет транзитивную достижимость (поэтому цепочка A → B → existing допустима, даже если A напрямую не касается existing). При любой ошибке в середине батча вся транзакция откатывается; никакого промежуточного состояния.

Межпроектные ссылки

Узел графа в одном проекте может ссылаться на узел в другом проекте через graph_add_reference({ refProject, refNodeId }). Другие проекты могут затем читать его без переключения через graph_lookup_external или находить его по ID через graph_global_lookup. Это основа для Иерархического графа понимания, используемого в конвейере хронологической аннотации entangled-alignment, где эпохи и документы создают перекрёстные ссылки.

Основные концепции

Узлы (единицы понимания)

Каждый когнитивный узел фиксирует авторское обновление понимания с триггером, указывающим почему он был создан:

Триггеры — это когнитивные акты, а не категории — они фиксируют почему агент создал узел именно в этот момент, а не что это за сущность. Семь, которые вы будете использовать чаще всего:

Менее распространённые, но доступные: hypothesis, model, evaluation, analysis, experiment, serendipity, repetition, randomness, reference, library. Эти обычные когнитивные узлы могут сохранять богатые, предварительные, неразрешённые свидетельства — не только устоявшиеся выводы — когда это поможет будущему агенту вернуться к работе. Триггер thinking отличается: он зарезервирован для отдельного синтетического синтезатора Reader/CMP, который реконструирует хронологические обучающие блоки из базового графа. Зарезервированные блоки скрыты и неизменяемы для обычного чтения, записи, кодирования и общих рабочих процессов; доступ к ним возможен только через TOOL_MODE=synthetic_reader. Полный, намеренно выбранный набор из 18 типов триггеров описан в статье о графе понимания (раздел 3.1); это развивающийся дизайн, а не заявленный формальный минимум.

Рёбра (связи)

Документы

Структурированная проза, исходные материалы и граф-нативный код используют одно и то же адресуемое дерево документов. Лист может быть отрывком, функцией, классом, типом или тестом с собственным зафиксированным назначением, исходным коммитом, ревизиями и типизированными ссылками на вопросы, решения, доказательства или противоречия, которые его сформировали. Это позволяет более позднему Reader'у спросить, почему существует именно эта единица — а не только почему существует файл, — вызвав doc_read({ nodeId, showProvenance: true, showRevisions: true }).

implements указывает от абстрактного обязательства к его конкретной единице; expresses и inspired_by указывают от единицы-артефакта на то, что она отображает или что её автор называет повлиявшим; learned_from указывает от когнитивного обновления на источник или встречу с артефактом, которая его вызвала. Это проверяемые авторские утверждения, а не подтверждённые причины. Корни кода генерируют исполняемые файлы; единицы можно разделять, объединять, перемещать и переупорядочивать перед регенерацией.

Проекты

Изолированные графы для разных контекстов. Каждый проект имеет собственную базу данных SQLite.

Обзор инструментов

Пакетные операции

Управление концептами и узлами (пакетные операции, если не указано иное в выбранном режиме)

Управление связями (пакетные операции, если не указано иное в выбранном режиме)

Чтение и анализ

Синтез и исследование

Операции с документами (доступность зависит от режима рабочего процесса)

Чтение источников

Управление проектами

Межпроектные операции

Мультиагентная координация (Solver)

Мультиагентность с командами агентов Claude Code

Understanding Graph спроектирован как общая постоянная среда для команд агентов Claude Code. После запуска npx -y understanding-graph@0.1.30 init лидер создаёт или выбирает именованный граф; каждый участник команды, работающий в этом корне проекта, может использовать его совместно — стигмергия без встроенных данных.

Как это работает

You: "Create an agent team to research and implement auth for this app"

Claude (Team Lead):
  ├── Researcher teammate   ─── reads/writes shared graph ───┐
  ├── Backend teammate       ─── reads/writes shared graph ───┤  Same Understanding Graph
  ├── Security teammate      ─── reads/writes shared graph ───┤  (via MCP)
  └── synthesizes findings from graph_history()               ┘

1. init устанавливает одинаковый жидкостный протокол для каждого участника команды — Каждый агент рассматривает граф как каноническую среду и может работать напрямую или запрашивать graph_suggest_next для конкретных возможностей в естественных точках выбора.

2. Сообщения коммитов — это уровень координации — Каждый graph_batch требует commit_message. Когда участник команды по безопасности пишет «Security Agent: найден JWT в localStorage — напряжение между удобством и риском XSS», участник по бэкенду видит это через graph_history() и реагирует.

3. Триггеры классифицируют вклад — Участники помечают свои узлы (tension, question, decision, surprise), что упрощает поиск важного: «покажи все нерешённые напряжения» или «какие вопросы ещё открыты?»

4. Постоянная передача задач без обязательных прямых сообщений — Участники могут координироваться через сам граф. Исследователь оставляет узлы question; бэкенд-агент находит их через graph_find_by_trigger и создаёт рёбра answers.

Начало работы с роем

cd your-project
npx -y understanding-graph@0.1.30 init     # one-time setup

Затем в Claude Code:

Create an agent team with 3 teammates to [your task].
Each teammate should work through the shared Understanding Graph,
preserve material understanding as it emerges, and use graph_batch
with descriptive commit messages so the team can coordinate.

Долгосрочная координация (система solver)

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

Система solver сохраняется в базе данных SQLite, поэтому задачи переживают сессии. Одна команда может делегировать работу, которую подхватит будущая команда.

Архитектура

packages/
  core/          # Graph logic, SQLite storage, embeddings
  mcp-server/    # MCP server (41 default / 69 full tools + batch operations)
  web-server/    # REST API + serves frontend
  frontend/      # 3D visualization (React + Three.js)

Стек:

• SQLite + better-sqlite3 — Постоянное хранилище

• Graphology — Операции с графом в памяти

• MCP Protocol — Интеграция агентов

• Transformers.js — Локальные эмбеддинги для семантического поиска

Разработка

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web    # Web UI at http://localhost:3000

Режим разработки

# Terminal 1: Web server with hot reload
npm run dev:web

# Terminal 2: Frontend dev server
cd packages/frontend && npm run dev

Переменные окружения

Принципы работы

1. Используйте граф как среду — Пока активен режим Understanding, сохраняйте передаваемое понимание и адресуемые единицы артефактов, которые важны для работы, а не только её конечный ответ.

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

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

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

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

Использование с sema

Understanding Graph даёт вашим агентам общую эпизодическую память — записанный интерпретационный след за решением. Sema даёт им общую семантическую память — словарь когнитивных паттернов с адресацией по содержимому. Они дополняют друг друга:

# Add both to Claude Code
claude mcp add ug   -- npx -y understanding-graph@0.1.30 mcp
claude mcp add sema -- uvx --from semahash sema mcp

При установке обоих агент может:

1. Ссылаться на URI паттерна sema (например, sema://StateLock#7859) внутри текста understanding или why узла, чтобы закрепить значение координационного примитива.

2. Использовать graph_semantic_search для поиска узлов, ссылающихся на паттерн в текущем проекте. Явно переключайте проекты или используйте инструменты межпроектных ссылок, когда поиск охватывает несколько графов.

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

Полное руководство: использование Understanding Graph с sema

Кодирование внутри графа

Код находится в корнях документов графа и их упорядоченных дочерних узлах. Создавайте исполняемые файлы с помощью doc_generate или doc_generate_all, запускайте реальную сборку и тесты, затем изменяйте или переупорядочивайте исходные узлы и перегенерируйте — никогда не патчите сгенерированную проекцию напрямую.

См. coding-inside-the-graph для полного рабочего процесса.

Цитирование

@misc{westerberg2026understanding,
  title        = {Understanding Graph: A Recursive Medium for Persistent Understanding},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = aug,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19462658},
  url          = {https://doi.org/10.5281/zenodo.19462658}
}

См. CITATION.cff для машиночитаемой версии (GitHub отображает кнопку «Cite this repository» на её основе).

Лицензия

MIT — LICENSE

GitHub: emergent-wisdom/understanding-graph npm: understanding-graph MCP Protocol: modelcontextprotocol.io