semahash

Sema：ハッシュが言葉になるとき

マルチエージェント連携のためのコンテンツアドレス型セマンティクス。

Semaは、推論とコミュニケーションのためのコンテンツアドレス型参照システムです。参加者は合意した表現形式で情報をエンコードしてハッシュ化し、その後、検証可能な参照としてコンテンツアドレスを再利用します。必要に応じて、人が読めるハンドルを組み合わせることもできます。一致する完全な参照は、解決されたハッシュ対象コンテンツの同一性を確立します。一方、意味的な同等性、正確性、適用は別個の問題として扱われます。

Web： semahash.org · Discord： 参加する

インストール

MCP サーバー（推奨）

任意のMCPクライアント（Claude Code、Cursor、VS Code、Windsurf、Claude Desktop）に追加します。

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

または、Claude Code CLIから実行します。

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

クイックスタート

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サーバーを公開します。

動作を確認する — エージェントに次のように尋ねます：「semaで連携パターンを検索し、StateLockでハンドシェイクしてください」

Semaは標準的なMCP stdioサーバーを公開しているため、OpenClaw（openclaw mcp set sema '{"command":"uvx","args":["--from","semahash[mcp]","sema","mcp"]}'）を含め、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

# Watch the active vocabulary in the local view (binds to 127.0.0.1 by default)
sema serve --open

独自の語彙を持ち込む

PR やメンテナーを介さずに、プライベートレジストリをゼロから構築できます。

sema init ./mylib.db
sema use ./mylib.db
sema apply --add path/to/MyPattern.json
sema search "..."

以降の sema コマンド（sema mcp を含む）は、プライベートレジストリから読み込みます。（SEMA_DB_PATH が設定されている場合は、sema use より優先されます。）標準的なコントリビューション方法については CONTRIBUTING.md を、改良と置き換えのポリシーについては docs/specification/versioning.md を参照してください。

プロジェクトデータベースを、検証済みのスタンドアロンライブラリリリースとしてパッケージ化します。

sema package ./mylib.db \
  --name mylib \
  --version 1.0.0 \
  --output-dir dist/mylib-1.0.0 \
  --github-repo acme/sema-mylib

生成された library.json とバージョン付き ZIP を、対応する公開済み GitHub Release のアセットとして公開します。利用者は、リポジトリの URL やブランチではなく、library.json の Release アセット URL をインストールします。

sema install https://github.com/acme/sema-mylib/releases/latest/download/library.json
sema use mylib
sema list
sema root

語彙をマージするのではなく、一度に検証済みスナップショットを 1 つインストールします。バンドルされた語彙はオフライン時のデフォルトとして維持されます。sema update mylib を使うと、インストール済みライブラリに記録されたリリースポインターを追跡できます。DeFi の作成、依存関係のクロージャー、パッケージ化、GitHub Release、更新のワークフロー全体については、語彙ライブラリの公開とインストールを参照してください。

semahash.org で公開されたライブラリは、アカウントなしで名前から検索してインストールできます。

sema registry search defi
sema install mylib

他の人やエージェントが見つけられるように、そこでリリースを掲載するには、一度ログインしてコマンドラインから公開します。

sema login        # approve the short code in your browser, once
sema registry import https://github.com/acme/sema-mylib/releases/latest/download/library.json

エージェントは、代わりに semahash.org のプロフィールページで作成したキーを使ってログインできます。キーを sema login --key - にパイプするか、sema_library_login MCP ツールを呼び出します。

ログインでは OAuth 2.0 デバイス認可フローを使用するため、ブラウザーのないエージェントやマシンからも利用できます。別のデプロイ先を使うには、sema login --registry https://registry.example を実行します。ログインに成功すると、そのレジストリが以降のコマンド用に記憶されます。--registry と SEMA_REGISTRY_URL は記憶された選択を上書きします。初回使用時のデフォルトは https://semahash.org です。

Python での使用

from sema.core.registry import RegistryManager

registry = RegistryManager()
pattern = registry.get_pattern("StateLock")

# Look up the canonical reference
print(pattern["sema_ref"])  # StateLock#c9c2

# Verify an inline reference before relying on it
assert pattern["sema_ref"] == "StateLock#c9c2"

プロトコルを試す（API キー不要）

python experiments/demos/local_handshake.py

ハンドシェイクの動作を確認できます。一致するハッシュでは PROCEED、不一致のハッシュでは HALT、未知のパターンでも HALT になります。協調モードではドリフト検出に短いプレフィックスを使用できます。厳密モードではハッシュ全体が必要です。所要時間は 2 秒です。

仕組み

word = hash(canonical(definition))

任意の概念（協調プロトコル、推論パターン、信頼メカニズムなど）を正規形式で表現してハッシュ化します。そのハッシュが単語になります。定義の 1 バイトを変更すれば、別の単語になります。

Cooperative: sema_handshake("StateLock#c9c2")
             -> PROCEED with assurance="prefix", or HALT

Strict:      sema_handshake("StateLock", "<full 64-char hash>", strict=true)
             -> PROCEED with assurance="full_hash", or HALT

これはアンチ・ポステル原則です。厳密モードではハッシュ全体が一致する場合にのみ進行します。協調モードでは、非敵対的なドリフトの兆候として短いプレフィックスを使用します。どちらのモードでも、不一致の場合はフェイルクローズします。

語彙

バンドルされた語彙は、次の 4 つのレイヤーにまたがります。

• Physics — 不変の基盤（ロック、エントロピー、因果律）
• Mind — ハイブリッド認知（推論、推測、戦略）
• Society — 複数エージェント間の協調（経済、ガバナンス、プロトコル）
• Infrastructure — 運用上の制約（データ構造、検証）

各パターンは、コンテンツアドレス方式の振る舞いの定義です。具体的なカードには、アイデンティティを定義するフィールドとして、機械検証可能な契約、不変条件、障害モード、パラメーター、型付き依存関係を追加できます。

MCP ツール

MCP サーバーとして実行すると（sema mcp）、以下のツールを利用できます。

ツール	説明
sema_search	名前、説明、または意味からパターンを検索します
sema_lookup	参照（例：StateLock#c9c2）を指定してパターンを取得します
sema_resolve	依存関係を展開した状態でパターンを取得します
sema_handshake	エージェント間のフェイルクローズ方式の意味検証を行います
sema_mint	新しいパターンを作成します（検証、ハッシュ化、語彙への追加）
sema_propose_context	マルチエージェントの定義セットのコンテキストダイジェストを計算します（ドリフト検出）
sema_verify_context	別のエージェントからのコンテキスト提案を検証します
sema_tree	レイヤーとカテゴリ別に語彙を閲覧します
sema_validate	パターン JSON の正しさを検証します
sema_stats	語彙の統計情報を表示します
sema_graph_skeleton	超簡易なグラフ概要（約150トークン）
sema_reset_session	セッションキャッシュをクリアし、検索結果を再びすべて表示します
sema_library_search	semahash.org で公開されているライブラリを探します
sema_library_install	名前または library.json の URL でライブラリを検証してインストールします
sema_library_login	ユーザーがエージェントに渡した semahash.org キーを保存します
sema_library_publish	ユーザーの同意を得た後、semahash.org に GitHub リリースを公開します

ローカルビュー

pip install "semahash[api]"
sema serve --open
# Opens http://localhost:3000

ローカルビューには、sema use で選択した語彙が表示されます。これは接続されたエージェントが書き込みを行う語彙と同じものです。後からの切り替えも反映されます。また、エージェントがパターンを作成するにつれて3Dグラフが拡大し、新しいパターンが点灯してリアルタイムのリストに表示されます。パターンブラウザーでは、カード、リスト、JSON の各ビューを利用できます。開発はお使いのコンピューター上で行われます。semahash.org では完成したライブラリをホストしており、書き込み可能な語彙のページには、そこへ公開するための任意の手順が記載されています。

実験

experiments/ ディレクトリには、Sema の主張と実装上の境界を評価する再現可能なテストが含まれています。

差分の再構築

公開版 v0.3.0 から v0.4.0 への再構築実験では、現在のグラフとハッシュカスケードアルゴリズムを使って、以前のリリースから対象の語彙を再構築できるかを検証します。集約ルート、意味的なパターンの内容、論理的な依存関係グラフ、ハッシュ化されていないメタデータ、正規化された完全な読み取りモデルを比較します。ルートが一致すればリリース全体も一致すると見なすことはありません。また、安全な再構築手順も示します。差分を完全なステージング済みカードスナップショットに統合し、新しいデータベースをコンパイルして、結果を検証した後にのみ有効化します。

.venv/bin/python experiments/delta_reconstruction/reproduce.py

この実験と期待される結果については、experiments/delta_reconstruction/README.md に記載されています。追加、削除、名前変更、カスケード、メタデータ、および失敗ケースの小規模な合成版は、通常のテストスイートで実行されます。

マルチエージェント設計チャレンジ

制御されたマルチエージェント設計チャレンジでは、次の3つの条件を比較します。

条件	Sema	ターン数	結果
A：自然言語のみ	いいえ	4	設計は却下
B：Sema 語彙	はい	11	SAD Engine を承認
C：Sema + プロトコル	はい	25	徹底的な審査を経て SAD Engine を承認

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 — 構造上の差異が明確です

形式検証のパイロット

Sema のハンドシェイク判定カーネルと正規化の型タグには、小規模な Lean 4 証明スイートがあります。ハンドシェイクは、通常のドリフト検出には協調的なプレフィックスマッチングを、証明レベルの同一性確認には厳密なフルハッシュ検証をサポートしており、それぞれの保証は個別に証明されています。エンコーディングの証明では、ハッシュ計算前のドメイン分離を確立し、Python の適合性テストでモデルと本番環境を結び付けています。証明済みの定理、信頼される計算基盤の前提、および主張の明確な限界については、verification/README.md を参照してください。

understanding-graph との併用

Sema はエージェントに共有の意味的メモリを提供します。これは、コンテンツアドレス方式で識別される認知パターンの語彙です。Understanding Graph は、意思決定の背後にある実際の思考の軌跡という、共有のエピソード的メモリを提供します。この 2 つは組み合わせて使えます。

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

両方をインストールすると、エージェントは次のことができます。

1. understanding-graph の意思決定ノードを sema パターンのハッシュ（例：StateLock#c9c2）に紐付け、プリミティブの意味が決して揺らがないようにします。
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 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)
│   ├── delta_reconstruction/  Historical release reconstruction validation
│   ├── 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.19462702},
  url          = {https://doi.org/10.5281/zenodo.19462702}
}

機械可読形式については CITATION.cff を参照してください（GitHub はこのファイルから「このリポジトリを引用」ボタンを表示します）。

安全性

Sema には実行可能なコードは含まれていません。これはパターンの定義（ハンドル、メカニズム、不変条件、依存関係グラフ）のライブラリです。MCP サーバーはパターンをデータとしてクライアントに渡すものであり、記述された動作を実行するものではありません。

想定される用途：推論と参照。 パターンは思考ツールです。エージェントが検索、解決、ハンドシェイクに使う名前付きの概念であり、連携、リスク、手順について推論するために使います。各パターンの意図と設計上の選択については、docs/manuals/vocabulary-design.md を参照してください。

パターンを実行可能なレシピとして実行することは、テストされていません。 多くのパターンはエージェントが順を追って実行できる手順を記述しています。一方、Dynamics カテゴリのパターンはシステムの挙動を記述しており、実行するのではなく、事例の解釈に適用するため、これには当てはまりません。手順の実行は現在も研究段階です。メカニズムの説明はエンドツーエンドで検証されておらず、パターンを参照するのではなく実行した場合の安全性について、いかなる主張も行っていません。この方法を選ぶ場合は、エージェントの実行ステップをサンドボックス環境で実行してください。既知のリスクがあるパターンには、メタデータに caution フィールドがあります。このフラグがない場合、そのパターンはリスク分類されていないことを意味するだけで、安全性が認証されているわけではありません。

長期的な目標は、エージェント間通信に対する安全性制約を暗号学的に強制することです。これは現在進行中の研究分野です。

ライセンス

Sema はデュアルライセンスです。

• コード（src/、web/、experiments/、scripts/ 内のすべてのファイルと、パッケージ設定）— MIT。セルフホストしたり、フォークしたり、その上に商用製品を構築したりできます。

• コンテンツ（data/ 内のパターン語彙、docs/ 内のドキュメント、paper/ 内の学術論文、および semahash.org に表示される文章）— CC BY 4.0。パターンと文章は、商用利用を含め、あらゆる目的で自由に再利用できます。語彙を共有する際に推奨される帰属表示：

  Sema の語彙。CC BY 4.0 ライセンス。

学術引用については、CITATION.cff を参照してください。GitHub ではプロジェクトページに「このリポジトリを引用」というボタンが表示され、APA 形式と BibTeX 形式の引用を自動生成できます。