Tesserae v0.3.0 — связи проза-в-код, полиглотный граф кода, живая синхронизация

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Español · Français · Deutsch

<!-- translations:end -->

Выпущено 2026-05-24 · PyPI · GitHub release · pip install --upgrade tesserae==0.3.0

Tesserae 0.3.0 замыкает контур между прозаическими решениями и теми символами кода, которые их реализуют, и делает это сразу на 21 языке вместо ограниченного только Python фундамента v0.2.0. Релиз приносит три аддитивные возможности без ломающих изменений: проход построения рёбер discusses, который чеканит типизированные связи от находок сессии (SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway) к соответствующим узлам кода; подкоманду tesserae project sync-code, которая импортирует tree-sitter SQLite-индекс из colbymchenry/codegraph в типизированный ResearchGraph Tesserae; и включённый по умолчанию хук SessionStart живой синхронизации sync-code, поддерживающий этот импорт в актуальном состоянии по мере того, как вы редактируете код. Вместе они делают Tesserae единственным PKM-AI инструментом памяти в ландшафте 2026 года, где запрос «что мы решили насчёт X?» возвращает сами решения, сессии, в которых они были приняты, и конкретные функции / классы / маршруты, реализующие их — по всему полиглотному стеку, который реально используется в исследовательских кодовых базах.

Содержание:

1. Рёбра MD0 — связь прозы с символами кода (фича H)
2. MD0 — адаптер CodeGraph, 21 язык
3. Хук SessionStart живой sync-code (после v0.3.0 в MD0)
4. Обновление с v0.2.0
5. Стратегический контекст

Рёбра discusses — связь прозы с символами кода (фича H)

Что это

Опциональный пост-компиляционный проход, который сканирует тело каждой находки сессии на упоминания символов кода, существующих в графе, и чеканит типизированное ребро discusses от находки к каждому совпавшему узлу кода. Источниками являются шесть типов находок сессии, которые эмитирует агентская гарнесса — SessionInsight, Decision, Hypothesis, Todo, Question, Takeaway — а целями выступают все варианты узлов кода, которые теперь знает Tesserae: CodeFunction, CodeClass, CodeMethod, плюс новые в v0.3.0 CodeInterface, CodeTrait, CodeStruct, CodeEnum, CodeEnumMember, CodeTypeAlias, CodeVariable, CodeConstant, CodeRoute, CodeComponent, CodeField, CodeNamespace, а также резервный CodeSymbol.

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

Символы, определённые в нескольких файлах, получают веерное разветвление по одному имени (same-name fanout): упоминание голого идентификатора User в находке сессии порождает по одному ребру discusses на каждый совпавший CodeClass (по файлу), так что нисходящий graph_ppr, посеянный на находке, расходится веером ко всем правдоподобным реализациям, а не выбирает одну произвольно.

Новый MCP-инструмент — find_code_symbol_mentions(node_id) — открывает тот же экстрактор агенту во время запроса. Он принимает любой узел (обычно находку сессии) и возвращает все символы кода, упомянутые в теле, с указанием уровня совпадения. Это полезно, когда вы хотите спросить «каких символов реально касается это решение?», не перезапуская проход компиляции.

Как использовать

Включите через переменную окружения, затем скомпилируйте:

export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

После включения каждая находка сессии, упоминающая известный символ, получает одно или несколько исходящих рёбер discusses. Из MCP-клиента:

// Выявить символы, которых касается конкретное решение
{
  "tool": "find_code_symbol_mentions",
  "arguments": { "node_id": "decision-2026-05-22-switch-to-rrf-fusion" }
}

// → возвращает
// [
//   {"node_id": "code-function-tesserae.retrieval.hybrid.reciprocal_rank_fusion",
//    "tier": "backticked", "kind": "CodeFunction"},
//   {"node_id": "code-class-tesserae.retrieval.hybrid.HybridRetriever",
//    "tier": "dotted",     "kind": "CodeClass"}
// ]

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

{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_ids": [
      "decision-2026-05-22-switch-to-rrf-fusion",
      "hypothesis-2026-05-23-embedding-helps-paraphrases"
    ],
    "top_k": 20,
    "edge_type_weights": { "discusses": 3.0, "references": 1.5 }
  }
}

Когда включать

• У вас есть история сессий с реальным обсуждением кода — многонедельный проект, где сессии Claude Code действительно ссылаются на функции/классы/маршруты по имени, а не просто описывают поведение прозой.
• Вы хотите, чтобы ответы ask цитировали реализующий символ, а не только README, который его упоминает.
• Вы потребляете граф из другого инструмента (LSP-подобный «go to implementation» из узла решения) и нуждаетесь в запрашиваемом ребре, а не в догадке, переэкстрагируемой во время запроса.

Если ваш проект в основном состоит из прозаических документов и PDF и почти не имеет истории Claude Code, проход добавит время компиляции и очень мало полезных рёбер — оставьте его выключенным.

Где это живёт

Основная реализация: MD0. Регистрация инструмента: tesserae/mcp_server.py.

Оговорки

• Уровень голых идентификаторов намеренно консервативен — требуется попадание в индекс и отсутствие в стоп-словах. Слишком общие идентификаторы (run, get, set) всё ещё пройдут фильтр стоп-слов, но утонут в веере связей со многими файлами; это известный компромисс, а не баг.
• Same-name fanout работает по типу узла: упоминание User, совпадающее одновременно с CodeClass и CodeRoute, порождает рёбра к обоим. Если нужен только класс, фильтруйте во время запроса по target.kind == "CodeClass".
• Проход выполняется после sync-code (или ingest-code) — если включить фичу H без заполненного графа кода, ей не с чем связывать, и она произведёт ноль рёбер. Порядок компиляции обрабатывается автоматически; ручное упорядочивание не требуется.
• Список стоп-слов глобальный, не пер-языковой; Rust-проект, который законно хочет использовать Vec как идентификатор, уже работает (Vec отсутствует в наборе стоп-слов), но локальные переопределения на уровне проекта запланированы как продолжение для v0.4.

tesserae project sync-code — адаптер CodeGraph, 21 язык

Что это

Новая подкоманда CLI, которая импортирует внешний SQLite-индекс colbymchenry/codegraph в типизированный ResearchGraph Tesserae. CodeGraph — это полиглотный экстрактор графа кода на базе tree-sitter с собственным MCP-сервером; адаптер читает его .codegraph/codegraph.db, транслирует каждую строку в ResearchNode Tesserae и записывает .tesserae/code-graph.json, чтобы следующий запуск tesserae project compile его подхватил — точно так же, как вывод ingest-code из v0.2.0, но наполненный из гораздо более широкой языковой базы.

Языковое покрытие подскакивает с 1 до 21: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Lua и Luau. (Экстрактор tesserae project ingest-code из v0.2.0 на базе stdlib-ast по-прежнему работает без изменений для пользователей, которым нужен путь только для Python без зависимости от Node-runtime.)

Чтобы представить то, что tree-sitter реально извлекает из этих языков, v0.3.0 добавляет 14 новых вариантов ResearchNodeType:

…и 8 новых типов рёбер: implements, exports, references, instantiates, overrides, decorates, type_of и returns. Эти рёбра прямо соответствуют тому, что вычисляет резолвер CodeGraph для каждого языка; существующие рёбра Tesserae calls, imports, inherits_from, contains и declared_in остаются неизменными и продолжают наполняться.

Единственное наиболее важное архитектурное решение в адаптере — стратегия id_seed. Собственный id строки CodeGraph включает start_line, так что один и тот же символ получает новый id всякий раз, когда вы добавляете над ним пустую строку — фатально для нисходящих рёбер, хранящих этот id. Адаптер отбрасывает id из CodeGraph и пересевает id Tesserae как f"{file_path}:{kind}:{qualified_name}". Результат: id символа в Tesserae переживает сдвиги строк без изменений, и совпадения голых идентификаторов из фичи H в находках сессии продолжают разрешаться в один и тот же узел между многими компиляциями.

Как использовать

# Разовый импорт: читает .codegraph/codegraph.db, пишет .tesserae/code-graph.json,
# затем следующая компиляция это подхватит.
tesserae project sync-code

# Явный корень проекта + кастомные пути к БД / выходу
tesserae project sync-code \
  --project /path/to/repo \
  --db /path/to/.codegraph/codegraph.db \
  --output /path/to/.tesserae/code-graph.json

# Цикл наблюдения — перезапускает sync-code при изменении БД.
# Полезно, если вы не хотите хук SessionStart из фичи 3, но всё ещё
# хотите, чтобы граф кода оставался свежим во время правок.
tesserae project sync-code --auto-sync

Типичный сквозной поток на новом проекте:

# 1. Пусть CodeGraph проиндексирует репо (его собственный CLI; разовая настройка)
npx codegraph index .

# 2. Втянуть это в типизированный граф Tesserae
tesserae project sync-code

# 3. Обычная компиляция подхватывает code-graph.json и (если включено) запускает фичу H
export TESSERAE_INSIGHT_SYMBOL_LINK=true
tesserae project compile

# 4. Теперь задавайте вопросы, охватывающие прозу и код
tesserae project ask "Какие функции реализуют решение про RRF-фьюжн?"

Когда включать

• Ваш проект — что угодно, кроме чистого Python, или чистый Python плюс один Node-фронтенд.
• Вы уже используете CodeGraph за его MCP-сервер с «find references» / «find implementations» — адаптер позволяет тому же индексу питать типизированный граф Tesserae без дополнительных затрат на извлечение.
• Вы хотите гранулярность на уровне маршрутов или компонентов (CodeRoute, CodeComponent) помимо функций и классов, чего ingest-code из v0.2.0 не производит.

Если у вас только Python и вы не хотите Node-runtime в вашей цепочке инструментов, tesserae project ingest-code (v0.2.0) по-прежнему работает и производит совместимый code-graph.json.

Где это живёт

Основная реализация: MD0. Подключение CLI: tesserae/cli.py (подпарсер sync-code, около строки 897). Подкоманда ingest-code из v0.2.0 в tesserae/code_graph_extractor.py не изменилась.

Оговорки

• Требуется заполненный .codegraph/codegraph.db (собственный одноразовый шаг CodeGraph npx codegraph index .). Адаптер быстро падает с понятным сообщением об ошибке, если БД отсутствует.
• Резолвер CodeGraph действует «по мере возможности» на 21 языке; ожидайте периодических неразрешённых ссылок в патологических обобщениях или коде с обилием макросов. Адаптер записывает то, что эмитирует CodeGraph, и не пытается переразрешать.
• Некоторые виды узлов (CodeParameter, CodeField) эмитируются только когда пер-языковой экстрактор CodeGraph их выдаёт — покрытие зависит от языка. Резервный вид CodeSymbol подхватывает всё, что tree-sitter видит, а мы ещё не типизировали, поэтому ничего не выбрасывается молча.
• Атомарные записи используют PID + случайный суффикс для временного файла (а не общий .tmp), чтобы два одновременных вызова sync-code не сталкивались — это совпадает с тем же исправлением, которое недавно приземлилось в писателе batch-манифеста.

Хук SessionStart живой sync-code (после v0.3.0 в main)

Что это

Небольшой хук SessionStart в плагине Tesserae, который замыкает контур «непрерывно обновляющегося графа кода». MCP-сервер CodeGraph уже автоматически следит за файловой системой и поддерживает .codegraph/codegraph.db в актуальном состоянии по мере правок — но .tesserae/code-graph.json обновлялся только когда вы вручную запускали sync-code. Этот хук фоново запускает tesserae project sync-code --project <root> каждый раз, когда Claude Code открывает сессию, но только если SQLite-БД новее, чем производный JSON.

Включён по умолчанию; отключение по проекту через frontmatter в .claude/tesserae.local.md:

---
hooks:
  sync_code_on_start: false
---

Хук молча пропускает запуск, когда выполняется любое из следующего, поэтому он никогда не добавляет шума в проекты, не использующие CodeGraph:

• Проект не использует CodeGraph (нет .codegraph/codegraph.db).
• .tesserae/code-graph.json уже не старше БД.
• Бинарника tesserae нет в PATH.
• Другой sync-code уже выполняется для того же корня проекта (защита от повторного входа на основе pgrep, зеркалирующая защиту SessionEnd-компиляции, приземлившуюся в 0a3d35f).
• Пользователь отказался через sync_code_on_start: false.

Когда он всё же срабатывает, вы видите одну строку в заголовке сессии:

  ⟳ syncing code-graph from CodeGraph (background)

…а фактический вызов sync-code идёт отсоединённым (setsid → nohup → резервный голый &) с выводом в .tesserae/.session-start-hook.log, чтобы вы могли посмотреть, что произошло, без утечки в стенограмму сессии Claude.

Этот хук приземлился после v0.3.0 в main (PR #11, коммит 395e9fb) и поставится в следующей публикации компилятора / маркетплейса плагинов; сам v0.3.0 на PyPI его не содержит, потому что хук живёт в плагине, а не в Python-пакете tesserae.

Как использовать

Если вы установили плагин Tesserae через маркетплейс Claude Code, он у вас уже есть — хук включён по умолчанию. Чтобы убедиться, что он сработал:

tail -n 20 .tesserae/.session-start-hook.log

Чтобы выключить его для отдельного проекта (например, репозитория только на Python, где предпочтителен ingest-code):

mkdir -p .claude
cat > .claude/tesserae.local.md <<'EOF'
---
hooks:
  sync_code_on_start: false
---

Этот проект использует `tesserae project ingest-code` (Python AST) вместо
адаптера CodeGraph, поэтому хук живой sync-code отключён.
EOF

Чтобы принудительно запустить разовую синхронизацию, не дожидаясь новой сессии, просто запустите tesserae project sync-code напрямую — хук и ручная команда разделяют ту же pgrep-защиту, так что они не запустятся дважды.

Когда включать

• Вы хотите свойство «постоянного обновления» без необходимости помнить о перезапуске sync-code после каждой партии правок.
• Ваши редакторские сессии короткие и частые (открыть сессию, задать вопрос, закрыть) — хук гарантирует, что каждая новая сессия видит актуальный граф кода.
• Вы уже запускаете MCP-сервер CodeGraph с наблюдением за файлами — хук просто распространяет эту свежесть в Tesserae.

Оставьте его выключенным, когда вы в плотной внутренней петле и не хотите никаких фоновых работ на каждую сессию, или когда проект вообще не использует CodeGraph (хук в таком случае молча превращается в no-op, но явный отказ чище).

Где это живёт

• Точка входа хука: MD0
• Парсер настроек: MD0 — таблица read_plugin_setting получила значение по умолчанию sync_code_on_start=true.
• Защита от повторного входа: тот же паттерн pgrep -f "tesserae project sync-code.*${project_root}", что и защита SessionEnd-компиляции (hooks/session-end.sh).

Оговорки

• Хук срабатывает только на SessionStart, не на каждое сохранение файла. Если вы хотите, чтобы sync-code работал непрерывно во время правок (без открытия новой сессии Claude), используйте tesserae project sync-code --auto-sync из фичи 2 в отдельном терминале.
• Сравнение mtime использует BSD stat -f %m (macOS) → GNU stat -c %Y (Linux) → резервно [[ A -nt B ]]. На экзотических файловых системах с низким разрешением mtime вы можете изредка пропустить синхронизацию, выполненную менее чем через секунду после индекса CodeGraph — следующая сессия её подхватит.
• Фоновый запуск использует setsid, когда он доступен, затем nohup, затем голый &. На крайне зажатых оболочках, где ни один из этих способов не отсоединяет процесс, синхронизация всё равно выполнится, но может задержать старт сессии на несколько секунд. Откройте дружественную к терминалу оболочку или установите sync_code_on_start: false в этом случае.

Обновление с v0.2.0

pip install --upgrade tesserae==0.3.0

И это всё обновление — v0.3.0 аддитивен и не содержит ломающих изменений. Поведение tesserae project compile по умолчанию не изменилось; новые части — опциональные и обнаружимые.

Переменная окружения для нового опционального прохода (фича 1):

# Включить пост-компиляционный проход построения discusses-рёбер проза-в-код (фича H)
export TESSERAE_INSIGHT_SYMBOL_LINK=true

Новая подкоманда CLI, чтобы добавить в мышечную память (фича 2):

tesserae project sync-code             # разовый импорт CodeGraph → Tesserae
tesserae project sync-code --auto-sync # цикл наблюдения

Подкоманда tesserae project ingest-code из v0.2.0 по-прежнему работает без изменений — выбирайте sync-code, если ваш проект использует что-то помимо Python; выбирайте ingest-code, если не хотите зависимости от Node-runtime.

Новый MCP-инструмент, доступный агенту (фича 1):

• find_code_symbol_mentions(node_id) — извлечение символов во время запроса по телу любого узла.

Новая настройка плагина (фича 3, после v0.3.0 в main):

# .claude/tesserae.local.md
---
hooks:
  sync_code_on_start: true   # по умолчанию; установите false, чтобы отключить хук живой синхронизации
---

Всё остальное — graph_ppr, гибридный search_nodes, embedding_status, list_communities, fresh_insights, сводки сообществ, скоринг с затуханием, supersedes, контроль дрейфа схемы, slash-команды, проекция wiki / Obsidian — не изменилось по сравнению с v0.2.0.

Стратегический контекст

Tesserae v0.2.0 заложил типизированные узлы графа кода и прозаические примитивы (decay, supersedes, сводки сообществ). v0.3.0 — это релиз, в котором две половины соединяются: фича H чеканит типизированные рёбра discusses от решений и гипотез к символам, которых они касаются, а адаптер CodeGraph делает так, что эти символы покрывают полиглотный стек, который реально используется в исследовательских кодовых базах — TypeScript, Rust, Go, Swift и ещё 17 — а не только Python.

В обследованном перед этой вехой ландшафте PKM-AI первой волны нет другого инструмента, делающего это. Cursor Memories — это пер-проектный мешок текста — ни графа, ни типизированных рёбер. Claude CLAUDE.md — один плоский markdown-файл. Cline memory-bank — каталог markdown-файлов, без типизированной экстракции. Aider CONVENTIONS.md — один файл-префикс для промпта. Ни один из них не связывает прозаическое решение с функцией или классом, которые его реализуют; ни один из них не знает, что Decision и CodeRoute — это разные виды сущностей. Ребро discusses v0.3.0 на 21 языке типизированных узлов кода — это клин, а хук живой SessionStart — то, что делает этот клин ощущаемым как свойство окружения, а не как рабочий процесс, который пользователю надо помнить.

Ближайший аналог в более широком пространстве GraphRAG — Microsoft GraphRAG — имеет типизированные сущности и сводки сообществ (что зеркалирует Tesserae v0.2.0), но не имеет слоя графа кода вообще; это корпусная RAG-система, а не компилятор памяти проекта. Примитив PPR из HippoRAG 2 (Tesserae v0.2.0) и операции памяти Mem0 (supersedes из Tesserae v0.2.0) дополняют прозаическую часть state of the art. v0.3.0 добавляет измерение, которого не касается ни один из них: типизированные рёбра от собственных находок агента в типизированные узлы, представляющие код, о котором эти находки, на тех языках, на которых реально написаны кодовые базы.

Смотрите также:

• Заметки о выпуске v0.2.0 — типизированный поиск, граф кода (Python), эволюция онтологии
• Обзор архитектуры — карта модулей и пайплайн
• Карта возможностей — полная таблица статуса возможностей со ссылками на исходники
• Интеграция сессий — узлы-источники находок сессии, от которых тянет связи фича H
• Интеграция MCP — полный список MCP-инструментов (новый find_code_symbol_mentions появится здесь в следующем проходе документации)