Sema: Wenn der Hash das Wort ist

Inhaltsadressierte Semantik für die Koordination zwischen Agenten.

Sema ist ein semantisches Gemeingut, das Bedeutung selbst inhaltsadressiert: Die Definition ist der Bezeichner. Da Bezeichner aus dem kryptografischen Hash der Definition eines Musters abgeleitet werden, führt jede Abweichung in der Bedeutung zu einem eindeutigen Hash. Dies garantiert, dass nicht aufeinander abgestimmte Agenten anhalten, anstatt unbemerkt zu scheitern.

Web: semahash.org · Discord: Beitreten

Installation

MCP-Server (empfohlen)

Fügen Sie dies zu einem beliebigen MCP-Client hinzu (Claude Code, Cursor, VS Code, Windsurf, Claude Desktop):

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

Oder über die Claude Code CLI:

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

Dies verwendet uv, um sema beim ersten Aufruf in einer isolierten Umgebung herunterzuladen, zu installieren und auszuführen, und speichert es dann für nachfolgende Aufrufe zwischen.

Claude Code Plugin (MCP-Server + Skill)

Sema wird auch als Claude Code Plugin ausgeliefert – ein MCP-Server plus ein Skill, der dem Agenten den Workflow Suchen/Auflösen/Erstellen/Handshake beibringt:

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

# Install the plugin
claude plugin install sema

Dies gibt Ihnen den MCP-Server und den (automatisch geladenen) sema-usage-Skill, der lehrt, wann gesucht oder erstellt werden soll, wie Handles in Text eingebettet werden und wie die Bedeutung an Schnittstellen überprüft wird. Der Skill ist eine Annehmlichkeit für Claude Code – der MCP-Server funktioniert mit jedem Client.

Für die lokale Entwicklung:

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

Permanente Installation (pip)

pip install "semahash[mcp]"

Für die reine CLI-Nutzung (kein MCP-Server):

pip install semahash

Related MCP server: giskard-memory

Schnellstart

Verwendung mit KI-Agenten (MCP)

Bereits oben über den JSON-Konfigurations- oder pip install-Pfad abgedeckt. Für die Entwicklung gegen dieses Repository:

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

Ihr Agent hat nun Zugriff auf sema_search, sema_lookup, sema_handshake und 9 weitere Tools. Jeder MCP-kompatible Client funktioniert – Sema stellt einen Standard-stdio-Server bereit.

Überprüfen Sie, ob es funktioniert – fragen Sie Ihren Agenten: "Suche in sema nach Koordinationsmustern und mache einen Handshake für StateLock"

Sema stellt einen Standard-MCP-stdio-Server bereit – jeder MCP-kompatible Client funktioniert, einschließlich OpenClaw (openclaw mcp set sema '{"command":"uvx","args":["--from","semahash[mcp]","sema","mcp"]}').

Verwendung über 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

Bring Your Own Vocabulary (Eigenes Vokabular)

Bauen Sie eine private Registrierung von Grund auf neu auf – ohne PR oder Maintainer in der Schleife:

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

Nachfolgende sema-Befehle (einschließlich sema mcp) lesen aus Ihrer privaten Registrierung. Siehe CONTRIBUTING.md für den kanonischen Beitragspfad und docs/specification/versioning.md für die Richtlinie zur Verfeinerung und Ablösung.

Verwendung in 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

Testen des Protokolls (Keine API-Schlüssel erforderlich)

python experiments/demos/local_handshake.py

Sehen Sie den Handshake in Aktion: übereinstimmende Hashes FAHREN FORT, nicht übereinstimmende Hashes HALTEN AN, unbekannte Muster HALTEN AN. Dauert 2 Sekunden.

Funktionsweise

word = hash(canonical(definition))

Nehmen Sie ein beliebiges Konzept (ein Koordinationsprotokoll, ein Argumentationsmuster, einen Vertrauensmechanismus), drücken Sie es in kanonischer Form aus und hashen Sie es. Dieser Hash IST das Wort. Ändern Sie ein Byte in der Definition, erhalten Sie ein anderes Wort.

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

Dies ist das Anti-Postel-Prinzip: gleiche Bytes = FORTFAHREN, unterschiedliche Bytes = ANHALTEN. Keine Mehrdeutigkeit, keine unbemerkten Fehler.

Das Vokabular

427 Standardmuster über 4 Ebenen (zusätzliche Muster mit einer höheren Risikofläche werden in einer separaten Datenbank aufbewahrt – siehe Sicherheit):

• Physik — Unveränderliches Substrat (Locks, Entropie, Kausalität)

• Geist — Hybride Kognition (Argumentation, Schlussfolgerung, Strategie)

• Gesellschaft — Koordination zwischen Agenten (Wirtschaft, Governance, Protokolle)

• Infrastruktur — Betriebliche Einschränkungen (Datenstrukturen, Verifizierung)

Jedes Muster ist eine ausführbare Spezifikation, die maschinenprüfbare Verträge, Invarianten, Fehlermodi und typisierte Abhängigkeiten enthält.

MCP-Tools

Wenn es als MCP-Server (sema mcp) ausgeführt wird, sind diese Tools verfügbar:

Web-Frontend

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

Interaktive 3D-Graph-Visualisierung, Muster-Browser und Suche. Erstellt mit React + Three.js.

Experimente

Das Verzeichnis experiments/ enthält eine kontrollierte Multi-Agenten-Design-Challenge, die drei Bedingungen vergleicht:

Agenten mit Sema-Mustern erstellten physikalisch fundierte Designs, die einer gegnerischen Prüfung standhielten. Agenten ohne Sema erstellten oberflächliche Designs, die bei der Sicherheitsüberprüfung scheiterten.

Zur Reproduktion:

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

Siehe experiments/sema_design_challenge/README.md für Details.

Schlüsseleigenschaften

• Null semantische Kollisionen über das gesamte Vokabular hinweg

• 16,9-fache durchschnittliche Token-Kompression durch inhaltsadressierte Stubs

• Fail-Closed-Architektur — Nichtübereinstimmungen halten an, scheitern niemals unbemerkt

• Durchschnittliche Embedding-Ähnlichkeit von 0,21 — hohe strukturelle Unterscheidbarkeit

Verwendung mit understanding-graph

Sema gibt Ihren Agenten ein gemeinsames semantisches Gedächtnis – ein Vokabular kognitiver Muster mit inhaltsadressierter Identität. Understanding Graph gibt ihnen ein gemeinsames episodisches Gedächtnis – den tatsächlichen Denkpfad hinter einer Entscheidung. Sie ergänzen sich:

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

Wenn beide installiert sind, kann ein Agent:

1. Einen understanding-graph-Entscheidungsknoten in einem Sema-Muster-Hash verankern (z. B. StateLock#5602), sodass die Bedeutung des Primitivs niemals driften kann.

2. graph_semantic_search verwenden, um alle vergangenen Graph-Knoten zu finden, die auf ein bestimmtes Sema-Muster verweisen – hash-stabile Historie, kein Keyword-Matching.

3. sema_handshake aufrufen, bevor eine Entscheidung geschrieben wird, die von einem gemeinsamen Konzept abhängt; wenn es HALT zurückgibt, schreibt der Agent stattdessen einen tension-Knoten und stoppt, wodurch eine unbemerkte Divergenz verhindert wird.

Vollständige Anleitung: docs/guides/understanding-graph.md

Repository-Struktur

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])

Mitwirken

Möchten Sie Muster hinzufügen, bestehende verbessern oder das Frontend lokal hosten? Siehe CONTRIBUTING.md.

Zitieren

@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}
}

Siehe CITATION.cff für die maschinenlesbare Version (GitHub rendert daraus eine "Cite this repository"-Schaltfläche).

Sicherheit

Sema liefert keinen ausführbaren Code aus – es ist eine Bibliothek von Muster-Definitionen (Handles, Mechanismen, Invarianten, Abhängigkeitsgraphen). Der MCP-Server übergibt Muster als Daten an Clients; er führt die beschriebenen Verhaltensweisen nicht aus.

Beabsichtigte Verwendung: Argumentation und Referenz. Muster sind Denkwerkzeuge – benannte Konzepte, nach denen Agenten suchen, die sie auflösen und auf die sie sich per Handshake einigen können, um über Koordination, Risiko und Verfahren nachzudenken. Siehe docs/manuals/vocabulary-design.md für die Absicht hinter jedem Muster und die Designentscheidungen.

Das Ausführen von Mustern als ausführbare Rezepte ist nicht getestet. Viele Muster beschreiben Verfahren, die ein Agent durchlaufen könnte. Dieser Pfad befindet sich noch in einer Forschungsphase – der Mechanismus-Text wurde nicht von Ende zu Ende validiert, und wir erheben keine Ansprüche auf Sicherheit, wenn ein Muster ausgeführt anstatt referenziert wird. Wenn Sie diesen Weg gehen, führen Sie den Ausführungsschritt des Agenten in einer Sandbox-Umgebung aus. Muster mit bekannten Risiken tragen ein caution-Feld in ihren Metadaten; das Fehlen dieses Flags bedeutet, dass das Muster nicht als riskant eingestuft wurde, nicht, dass es als sicher zertifiziert wurde.

Das langfristige Ziel sind kryptografisch erzwungene Sicherheitsbeschränkungen für die Kommunikation zwischen Agenten – eine aktive Forschungsrichtung.

Lizenz

Sema ist doppelt lizenziert:

• Code (alles in src/, web/, experiments/, scripts/ und die Paketkonfiguration) — MIT. Hosten Sie es selbst, forken Sie es, bauen Sie kommerzielle Produkte darauf auf.

• Inhalt (das Mustervokabular in data/, die Dokumentation in docs/, das wissenschaftliche Paper in paper/ und die auf semahash.org angezeigte Prosa) — CC BY 4.0. Verwenden Sie die Muster und die Prosa überall wieder, für jeden Zweck, einschließlich kommerzieller, solange Sie Henrik Westerberg als Urheber nennen.

Für akademische Zitate siehe CITATION.cff. GitHub rendert dies als "Cite this repository"-Schaltfläche auf der Projektseite, die automatisch APA- und BibTeX-Formate generiert.