Sema: When the Hash Is the Word

Content-addressed semantics for multi-agent coordination.

Sema is a content-addressed reference system for reasoning and communication. Participants encode and hash information under an agreed representation, then reuse the content address as a verifiable reference, optionally paired with a human-readable handle. Matching full references establishes identity of the resolved hashed content; semantic equivalence, correctness, and enforcement remain separate questions.

Web: semahash.org · Discord: Join

Install

MCP Server (recommended)

Add to any MCP client (Claude Code, Cursor, VS Code, Windsurf, Claude Desktop):

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

Or via Claude Code CLI:

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

This uses uv to download, install, and run sema in an isolated environment on first invocation, then caches it for subsequent calls.

Claude Code plugin (MCP server + skill)

Sema also ships as a Claude Code plugin — MCP server plus a skill that teaches the agent the search/resolve/mint/handshake workflow:

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

# Install the plugin
claude plugin install sema

This gives you the MCP server and the sema-usage skill (auto-loaded), which teaches when to search vs mint, how to embed handles in text, and how to verify meaning at boundaries. The skill is a Claude Code convenience — the MCP server works with any client.

For local development:

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

Permanent install (pip)

pip install "semahash[mcp]"

For CLI-only use (no MCP server):

pip install semahash

Quick Start

Use with AI Agents (MCP)

Already covered above via the JSON config or pip install path. For development against this repo:

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

Your agent now has access to sema_search, sema_lookup, sema_handshake, and 9 more tools. Any MCP-compatible client works — Sema exposes a standard stdio server.

Verify it works — ask your agent: "Search sema for coordination patterns and handshake on StateLock"

Sema exposes a standard MCP stdio server — any MCP-compatible client works, including OpenClaw (openclaw mcp set sema '{"command":"uvx","args":["--from","semahash[mcp]","sema","mcp"]}').

Use via 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

Build a private registry from scratch — no PR or maintainer in the loop:

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

Subsequent sema commands (including sema mcp) read from your private registry. (SEMA_DB_PATH, if set, overrides sema use.) See CONTRIBUTING.md for the canonical contribution path and docs/specification/versioning.md for the refinement and supersession policy.

Package a project database as a verified, standalone library release:

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

Publish the generated library.json and versioned ZIP as assets on the corresponding published GitHub Release. Consumers install the Release asset URL for library.json—not the repository URL or a branch:

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

It installs one verified snapshot at a time rather than merging vocabularies; the bundled vocabulary remains the offline default. Use sema update mylib to follow the installed library's recorded release pointer. See Publishing and Installing Vocabulary Libraries for the complete DeFi authoring, dependency-closure, packaging, GitHub Release, and update workflow.

Use in 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"

Try the Protocol (No API Keys Needed)

python experiments/demos/local_handshake.py

See the handshake in action: matching hashes PROCEED, mismatched hashes HALT, and unknown patterns HALT. Cooperative mode accepts short prefixes for drift detection; strict mode requires the full hash. Takes 2 seconds.

How It Works

word = hash(canonical(definition))

Take any concept (a coordination protocol, a reasoning pattern, a trust mechanism), express it in canonical form, hash it. That hash IS the word. Change one byte in the definition, get a different word.

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

This is the Anti-Postel principle: strict mode proceeds only on full-hash identity; cooperative mode uses compact prefixes as a non-adversarial drift signal. Mismatches fail closed in both modes.

The Vocabulary

The bundled vocabulary spans 4 layers:

• Physics — Immutable substrate (locks, entropy, causality)
• Mind — Hybrid cognition (reasoning, inference, strategy)
• Society — Multi-agent coordination (economics, governance, protocols)
• Infrastructure — Operational constraints (data structures, verification)

Each pattern is a content-addressed behavioral definition. Concrete cards may add machine-verifiable contracts, invariants, failure modes, parameters, and typed dependencies where those fields are identity-defining.

MCP Tools

When running as an MCP server (sema mcp), these tools are available:

Web Frontend

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

Interactive 3D graph visualization, pattern browser, and search. Built with React + Three.js.

Experiments

The experiments/ directory contains reproducible evaluations of Sema's claims and implementation boundaries.

Delta reconstruction

The public v0.3.0 to v0.4.0 reconstruction experiment checks whether the current graph and hash-cascade algorithm can rebuild a target vocabulary from an earlier release. It compares both aggregate roots, semantic pattern content, the logical dependency graph, unhashed metadata, and the complete normalized read model rather than treating root equality as complete release equality. It also demonstrates the safe reconstruction path: integrate the delta into a complete staged card snapshot, compile a fresh database, verify the result, and only then activate it.

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

The experiment and its expected results are documented in experiments/delta_reconstruction/README.md. Small synthetic versions of its addition, removal, rename, cascade, metadata, and failure cases run in the regular test suite.

Multi-agent design challenge

The controlled multi-agent design challenge compares three conditions: