Sema: Когда хеш становится словом

Семантика с адресацией по содержимому для координации мультиагентных систем.

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

Веб-сайт: semahash.org · Discord: Присоединиться

Установка

MCP-сервер (рекомендуется)

Добавьте в любой MCP-клиент (Claude Code, Cursor, VS Code, Windsurf, Claude Desktop):

{
  "mcpServers": {
    "sema": {
      "command": "uvx",
      "args": ["--from", "semahash[mcp]", "sema", "mcp"]
    }
  }
}

Или через CLI Claude Code:

claude mcp add sema -- uvx --from "semahash[mcp]" sema mcp

Это использует uv для загрузки, установки и запуска sema в изолированной среде при первом вызове, а затем кэширует его для последующих обращений.

Плагин для Claude Code (MCP-сервер + навык)

Sema также поставляется как плагин для Claude Code — MCP-сервер плюс навык, который обучает агента рабочему процессу поиска/разрешения/создания/рукопожатия:

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

# Install the plugin
claude plugin install sema

Это дает вам MCP-сервер и навык sema-usage (загружается автоматически), который учит, когда искать, а когда создавать, как встраивать дескрипторы в текст и как проверять значение на границах. Навык — это удобство для Claude Code, MCP-сервер работает с любым клиентом.

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

claude --plugin-dir /path/to/sema

Постоянная установка (pip)

pip install "semahash[mcp]"

Для использования только через CLI (без MCP-сервера):

pip install semahash

Related MCP server: giskard-memory

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

Использование с AI-агентами (MCP)

Уже описано выше через JSON-конфиг или путь pip install. Для разработки на основе этого репозитория:

git clone https://github.com/emergent-wisdom/sema.git
pip install -e "./sema[mcp]"

Ваш агент теперь имеет доступ к sema_search, sema_lookup, sema_handshake и еще 9 инструментам. Работает любой MCP-совместимый клиент — Sema предоставляет стандартный stdio-сервер.

Проверьте работу — спросите своего агента: "Search sema for coordination patterns and handshake on StateLock"

Sema предоставляет стандартный MCP stdio-сервер — работает любой MCP-совместимый клиент, включая OpenClaw (openclaw mcp set sema '{"command":"uvx","args":["--from","semahash[mcp]","sema","mcp"]}').

Использование через CLI

# Search the vocabulary
sema search "coordination"

# Look up a specific pattern
sema resolve StateLock

# Print a pattern's full definition
sema show StateLock

# Browse the graph structure
sema skeleton

# Start local API + web frontend (binds to 127.0.0.1 by default)
sema serve

Использование собственного словаря

Создайте частный реестр с нуля — без участия PR или сопровождающих:

sema init ./mylib.db
export SEMA_DB_PATH=$(pwd)/mylib.db
sema apply --add path/to/MyPattern.json
sema search "..."

Последующие команды sema (включая sema mcp) будут считываться из вашего частного реестра. См. CONTRIBUTING.md для канонического пути внесения вклада и docs/specification/versioning.md для политики уточнения и замены.

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

from sema.core.actions import sema_handshake
import json

# Look up the canonical hash
result = json.loads(sema_handshake("StateLock"))
print(result["canonical_stub"])  # b91b

# Verify alignment
result = json.loads(sema_handshake("StateLock#5602"))
print(result["verdict"])  # PROCEED

Попробуйте протокол (API-ключи не нужны)

python experiments/demos/local_handshake.py

Посмотрите на рукопожатие в действии: совпадающие хеши ПРОДОЛЖАЮТ, несовпадающие хеши ОСТАНАВЛИВАЮТ, неизвестные паттерны ОСТАНАВЛИВАЮТ. Занимает 2 секунды.

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

word = hash(canonical(definition))

Возьмите любую концепцию (протокол координации, паттерн рассуждения, механизм доверия), выразите ее в канонической форме, хешируйте. Этот хеш И ЕСТЬ слово. Измените один байт в определении — получите другое слово.

Agent A: "Let's use StateLock#5602"
Agent B: sema_handshake("StateLock#5602")
         -> PROCEED (hashes match) or HALT (drift detected)

Это принцип Анти-Постела: одинаковые байты = ПРОДОЛЖИТЬ, разные байты = ОСТАНОВИТЬ. Никакой двусмысленности, никаких скрытых сбоев.

Словарь

427 стандартных паттернов на 4 уровнях (дополнительные паттерны с более высоким уровнем риска хранятся в отдельной БД — см. Безопасность):

• Физика — Неизменяемая подложка (блокировки, энтропия, причинность)

• Разум — Гибридное познание (рассуждение, вывод, стратегия)

• Общество — Мультиагентная координация (экономика, управление, протоколы)

• Инфраструктура — Операционные ограничения (структуры данных, верификация)

Каждый паттерн — это исполняемая спецификация, содержащая машиночитаемые контракты, инварианты, режимы отказа и типизированные зависимости.

Инструменты MCP

При запуске в качестве MCP-сервера (sema mcp) доступны следующие инструменты:

Веб-интерфейс

pip install "semahash[api]"
sema serve
# Open http://localhost:3000

Интерактивная 3D-визуализация графа, браузер паттернов и поиск. Построено на React + Three.js.

Эксперименты

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

Агенты с паттернами Sema создали физически обоснованные проекты, которые прошли проверку на устойчивость. Агенты без Sema создали поверхностные проекты, которые не прошли проверку безопасности.

Для воспроизведения:

cd experiments/sema_design_challenge
export GOOGLE_API_KEY=your_key
./reproduce.sh

См. experiments/sema_design_challenge/README.md для подробностей.

Ключевые свойства

• Нулевые семантические коллизии во всем словаре

• 16.9-кратное среднее сжатие токенов через заглушки с адресацией по содержимому

• Архитектура с закрытием при ошибке — несовпадения останавливают работу, никогда не приводят к скрытым сбоям

• Среднее сходство эмбеддингов 0.21 — высокая структурная различимость

Использование с understanding-graph

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

claude mcp add sema -- uvx --from "semahash[mcp]" sema mcp
claude mcp add ug   -- npx -y understanding-graph mcp

С установленными обоими инструментами агент может:

1. Закрепить узел решения understanding-graph в хеше паттерна sema (например, StateLock#5602), чтобы значение примитива никогда не могло измениться.

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

3. Вызвать sema_handshake перед записью решения, которое зависит от общей концепции; если возвращается HALT, агент записывает узел tension и останавливается, предотвращая скрытое расхождение.

Полное руководство: docs/guides/understanding-graph.md

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

sema/
├── src/sema/              Core library (hashing, validation, MCP server, API)
├── data/                  Vocabulary (427 default + 26 higher-risk pattern cards + taxonomy databases)
├── docs/                  Documentation (philosophy, schema spec, CLI reference)
├── paper/                 Academic paper (sema.tex)
├── web/                   Web frontend (React + Three.js graph visualization)
├── experiments/
│   ├── orchestrator/      Multi-agent engine (bundled for experiment reproduction)
│   ├── sema_design_challenge/  Main experiment (3 conditions, 5 runs, full traces)
│   └── demos/             Standalone demos (local handshake, Babel Test)
└── pyproject.toml         Package config (extras: [mcp], [api], [full])

Вклад

Хотите добавить паттерны, улучшить существующие или разместить фронтенд локально? См. CONTRIBUTING.md.

Цитирование

@misc{westerberg2026sema,
  title        = {Sema: When the Hash Is the Word},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = apr,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19548971},
  url          = {https://doi.org/10.5281/zenodo.19548971}
}

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

Безопасность

Sema не поставляет исполняемый код — это библиотека определений паттернов (дескрипторы, механизмы, инварианты, графы зависимостей). MCP-сервер передает паттерны клиентам как данные; он не выполняет описанные ими поведения.

Предполагаемое использование: рассуждение и ссылка. Паттерны — это инструменты мышления, именованные концепции, по которым агенты могут искать, разрешать и совершать рукопожатия для рассуждения о координации, рисках и процедурах. См. docs/manuals/vocabulary-design.md для понимания намерений каждого паттерна и выбора дизайна.

Запуск паттернов как исполняемых рецептов не тестировался. Многие паттерны описывают процедуры, которые агент мог бы выполнить. Этот путь все еще находится на стадии исследования — текст механизмов не был проверен от начала до конца, и мы не делаем заявлений о безопасности, когда паттерн выполняется, а не используется как ссылка. Если вы пойдете по этому пути, запускайте шаг выполнения агента в изолированной среде. Паттерны с известными рисками имеют поле caution в своих метаданных; отсутствие этого флага означает, что паттерн не был классифицирован как рискованный, а не то, что он был сертифицирован как безопасный.

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

Лицензия

Sema имеет двойную лицензию:

• Код (все в src/, web/, experiments/, scripts/ и конфигурации пакета) — MIT. Размещайте его самостоятельно, делайте форки, стройте на его основе коммерческие продукты.

• Контент (словарь паттернов в data/, документация в docs/, академическая статья в paper/ и текст, отображаемый на semahash.org) — CC BY 4.0. Используйте паттерны и текст где угодно, для любых целей, включая коммерческие, при условии указания авторства Хенрика Вестерберга.

Для академического цитирования см. CITATION.cff. GitHub отображает это как кнопку "Cite this repository" на странице проекта, которая автоматически генерирует APA и BibTeX.