Sema: Cuando el hash es la palabra

Semántica direccionada por contenido para la coordinación multiagente.

Sema es un bien común semántico que direcciona por contenido el significado mismo: la definición es el identificador. Al derivar identificadores del hash criptográfico de la definición de un patrón, cualquier divergencia en el significado produce un hash distinto, garantizando que los agentes desalineados se detengan en lugar de fallar silenciosamente.

Web: semahash.org · Discord: Unirse

Instalación

Servidor MCP (recomendado)

Añadir a cualquier cliente MCP (Claude Code, Cursor, VS Code, Windsurf, Claude Desktop):

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

O mediante la CLI de Claude Code:

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

Esto utiliza uv para descargar, instalar y ejecutar sema en un entorno aislado en la primera invocación, y luego lo almacena en caché para llamadas posteriores.

Plugin de Claude Code (servidor MCP + habilidad)

Sema también se distribuye como un plugin de Claude Code: servidor MCP más una habilidad que enseña al agente el flujo de trabajo de buscar/resolver/acuñar/apretón de manos:

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

# Install the plugin
claude plugin install sema

Esto le proporciona el servidor MCP y la habilidad sema-usage (cargada automáticamente), que enseña cuándo buscar frente a acuñar, cómo incrustar identificadores en el texto y cómo verificar el significado en los límites. La habilidad es una conveniencia de Claude Code; el servidor MCP funciona con cualquier cliente.

Para desarrollo local:

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

Instalación permanente (pip)

pip install "semahash[mcp]"

Para uso exclusivo de CLI (sin servidor MCP):

pip install semahash

Related MCP server: giskard-memory

Inicio rápido

Uso con agentes de IA (MCP)

Ya cubierto anteriormente mediante la configuración JSON o la ruta pip install. Para el desarrollo contra este repositorio:

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

Su agente ahora tiene acceso a sema_search, sema_lookup, sema_handshake y 9 herramientas más. Cualquier cliente compatible con MCP funciona: Sema expone un servidor stdio estándar.

Verifique que funciona: pregunte a su agente: "Busca en sema patrones de coordinación y realiza un apretón de manos en StateLock"

Sema expone un servidor stdio MCP estándar; cualquier cliente compatible con MCP funciona, incluido OpenClaw (openclaw mcp set sema '{"command":"uvx","args":["--from","semahash[mcp]","sema","mcp"]}').

Uso mediante 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

Traiga su propio vocabulario

Construya un registro privado desde cero, sin PR ni mantenedor en el proceso:

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

Los comandos sema posteriores (incluido sema mcp) leen desde su registro privado. Consulte CONTRIBUTING.md para conocer la ruta de contribución canónica y docs/specification/versioning.md para conocer la política de refinamiento y sustitución.

Uso en 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

Pruebe el protocolo (no se necesitan claves API)

python experiments/demos/local_handshake.py

Vea el apretón de manos en acción: los hashes coincidentes CONTINÚAN, los hashes no coincidentes SE DETIENEN, los patrones desconocidos SE DETIENEN. Tarda 2 segundos.

Cómo funciona

word = hash(canonical(definition))

Tome cualquier concepto (un protocolo de coordinación, un patrón de razonamiento, un mecanismo de confianza), expréselo en forma canónica, aplíquele hash. Ese hash ES la palabra. Cambie un byte en la definición, obtenga una palabra diferente.

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

Este es el principio Anti-Postel: mismos bytes = CONTINUAR, bytes diferentes = DETENER. Sin ambigüedad, sin fallos silenciosos.

El vocabulario

427 patrones predeterminados en 4 capas (los patrones adicionales con una superficie de riesgo mayor se mantienen en una base de datos separada; consulte Seguridad):

• Física — Sustrato inmutable (bloqueos, entropía, causalidad)

• Mente — Cognición híbrida (razonamiento, inferencia, estrategia)

• Sociedad — Coordinación multiagente (economía, gobernanza, protocolos)

• Infraestructura — Restricciones operativas (estructuras de datos, verificación)

Cada patrón es una especificación ejecutable que contiene contratos verificables por máquina, invariantes, modos de fallo y dependencias tipadas.

Herramientas MCP

Al ejecutarse como un servidor MCP (sema mcp), estas herramientas están disponibles:

Interfaz web

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

Visualización de gráficos 3D interactivos, navegador de patrones y búsqueda. Construido con React + Three.js.

Experimentos

El directorio experiments/ contiene un desafío de diseño multiagente controlado que compara tres condiciones:

Los agentes con patrones Sema produjeron diseños basados en la física que sobrevivieron al escrutinio adversarial. Los agentes sin Sema produjeron diseños superficiales que fallaron en la revisión de seguridad.

Para reproducir:

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

Consulte experiments/sema_design_challenge/README.md para obtener más detalles.

Propiedades clave

• Cero colisiones semánticas en todo el vocabulario

• Compresión de tokens promedio de 16.9x mediante stubs direccionados por contenido

• Arquitectura de fallo cerrado: las discrepancias se detienen, nunca fallan silenciosamente

• Similitud de incrustación media de 0.21: alta distinción estructural

Uso con understanding-graph

Sema proporciona a sus agentes una memoria semántica compartida: un vocabulario de patrones cognitivos con identidad direccionada por contenido. Understanding Graph les proporciona una memoria episódica compartida: el rastro de pensamiento real detrás de una decisión. Se componen:

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

Con ambos instalados, un agente puede:

1. Anclar un nodo de decisión de understanding-graph en un hash de patrón sema (p. ej., StateLock#5602) para que el significado de la primitiva nunca pueda desviarse.

2. Usar graph_semantic_search para encontrar todos los nodos de gráfico anteriores que hacen referencia a un patrón sema determinado: historial estable por hash, no coincidencia de palabras clave.

3. Llamar a sema_handshake antes de escribir una decisión que dependa de un concepto compartido; si devuelve HALT, el agente escribe un nodo de tensión en su lugar y se detiene, evitando la divergencia silenciosa.

Tutorial completo: docs/guides/understanding-graph.md

Estructura del repositorio

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

Contribución

¿Quiere añadir patrones, mejorar los existentes u alojar la interfaz localmente? Consulte CONTRIBUTING.md.

Citación

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

Consulte CITATION.cff para la versión legible por máquina (GitHub muestra un botón de "Citar este repositorio" a partir de ella).

Seguridad

Sema no envía código ejecutable: es una biblioteca de definiciones de patrones (identificadores, mecanismos, invariantes, gráficos de dependencia). El servidor MCP entrega patrones a los clientes como datos; no ejecuta los comportamientos que describen.

Uso previsto: razonamiento y referencia. Los patrones son herramientas de pensamiento: conceptos nombrados que los agentes pueden buscar, resolver y sobre los cuales realizar apretones de manos para razonar sobre la coordinación, el riesgo y el procedimiento. Consulte docs/manuals/vocabulary-design.md para conocer la intención detrás de cada patrón y las decisiones de diseño.

La ejecución de patrones como recetas ejecutables no está probada. Muchos patrones describen procedimientos que un agente podría seguir. Esa ruta sigue siendo una fase de investigación: el texto del mecanismo no ha sido validado de extremo a extremo, y no hacemos afirmaciones sobre la seguridad cuando un patrón se ejecuta en lugar de referenciarse. Si elige esta ruta, ejecute el paso de ejecución del agente en un entorno aislado. Los patrones con riesgos conocidos llevan un campo caution en sus metadatos; la ausencia de esa marca significa que el patrón no ha sido clasificado como arriesgado, no que haya sido certificado como seguro.

El objetivo a largo plazo son las restricciones de seguridad aplicadas criptográficamente en la comunicación entre agentes: una dirección de investigación activa.

Licencia

Sema tiene licencia dual:

• Código (todo en src/, web/, experiments/, scripts/ y la configuración del paquete) — MIT. Aloje usted mismo, bifurque, cree productos comerciales sobre él.

• Contenido (el vocabulario de patrones en data/, la documentación en docs/, el artículo académico en paper/ y la prosa mostrada en semahash.org) — CC BY 4.0. Reutilice los patrones y la prosa en cualquier lugar, para cualquier propósito, incluido el comercial, siempre que atribuya a Henrik Westerberg.

Para citación académica, consulte CITATION.cff. GitHub muestra esto como un botón de "Citar este repositorio" en la página del proyecto que genera APA y BibTeX automáticamente.