\n\n# Sema: When the Hash Is the Word\n\n**Content-addressed semantics for multi-agent coordination.**\n\n[](https://pypi.org/project/semahash/)\n[](https://registry.modelcontextprotocol.io/servers/io.github.emergent-wisdom/semahash)\n[](https://github.com/emergent-wisdom/sema/blob/main/paper/sema.pdf)\n[](https://doi.org/10.5281/zenodo.19462702)\n[](https://github.com/emergent-wisdom/sema/blob/main/LICENSE)\n[](https://github.com/emergent-wisdom/sema/blob/main/LICENSE-CONTENT)\n\nSema 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.\n\n**Web:** [semahash.org](https://semahash.org) · **Discord:** [Join](https://discord.gg/hRhVqAuDYQ)\n\n## Install\n\n### MCP Server (recommended)\n\nAdd to any MCP client (Claude Code, Cursor, VS Code, Windsurf, Claude Desktop):\n\n```json\n{\n \"mcpServers\": {\n \"sema\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"semahash[mcp]\", \"sema\", \"mcp\"]\n }\n }\n}\n```\n\nOr via Claude Code CLI:\n\n```bash\nclaude mcp add sema -- uvx --from \"semahash[mcp]\" sema mcp\n```\n\nThis uses [uv](https://docs.astral.sh/uv/) to download, install, and run sema\nin an isolated environment on first invocation, then caches it for subsequent\ncalls.\n\n### Claude Code plugin (MCP server + skill)\n\nSema also ships as a Claude Code plugin — MCP server plus a skill that teaches the agent the search/resolve/mint/handshake workflow:\n\n```bash\n# One-time: add the Emergent Wisdom marketplace\nclaude plugin marketplace add emergent-wisdom/marketplace\n\n# Install the plugin\nclaude plugin install sema\n```\n\nThis 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.\n\nFor local development:\n\n```bash\nclaude --plugin-dir /path/to/sema\n```\n\n### Permanent install (pip)\n\n```bash\npip install \"semahash[mcp]\"\n```\n\nFor CLI-only use (no MCP server):\n\n```bash\npip install semahash\n```\n\n## Quick Start\n\n### Use with AI Agents (MCP)\n\nAlready covered above via the JSON config or `pip install` path. For development against this repo:\n\n```bash\ngit clone https://github.com/emergent-wisdom/sema.git\npip install -e \"./sema[mcp]\"\n```\n\nYour 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.\n\n**Verify it works** — ask your agent: *\"Search sema for coordination patterns and handshake on StateLock\"*\n\nSema exposes a standard MCP stdio server — any MCP-compatible client works, including [OpenClaw](https://openclaw.ai/) (`openclaw mcp set sema '{\"command\":\"uvx\",\"args\":[\"--from\",\"semahash[mcp]\",\"sema\",\"mcp\"]}'`).\n\n### Use via CLI\n\n```bash\n# Search the vocabulary\nsema search \"coordination\"\n\n# Look up a specific pattern\nsema resolve StateLock\n\n# Print a pattern's full definition\nsema show StateLock\n\n# Browse the graph structure\nsema skeleton\n\n# Start local API + web frontend (binds to 127.0.0.1 by default)\nsema serve\n```\n\n### Bring Your Own Vocabulary\n\nBuild a private registry from scratch — no PR or maintainer in the loop:\n\n```bash\nsema init ./mylib.db\nsema use ./mylib.db\nsema apply --add path/to/MyPattern.json\nsema search \"...\"\n```\n\nSubsequent `sema` commands (including `sema mcp`) read from your private\nregistry. (`SEMA_DB_PATH`, if set, overrides `sema use`.) See\n[CONTRIBUTING.md](CONTRIBUTING.md) for the canonical\ncontribution path and [docs/specification/versioning.md](docs/specification/versioning.md) for the\nrefinement and supersession policy.\n\nPackage a project database as a verified, standalone library release:\n\n```bash\nsema package ./mylib.db \\\n --name mylib \\\n --version 1.0.0 \\\n --output-dir dist/mylib-1.0.0 \\\n --github-repo acme/sema-mylib\n```\n\nPublish the generated `library.json` and versioned ZIP as assets on the\ncorresponding published GitHub Release. Consumers install the Release asset URL\nfor `library.json`—not the repository URL or a branch:\n\n```bash\nsema install https://github.com/acme/sema-mylib/releases/latest/download/library.json\nsema use mylib\nsema list\nsema root\n```\n\nIt installs one verified snapshot at a time rather than merging vocabularies;\nthe bundled vocabulary remains the offline default. Use `sema update mylib` to\nfollow the installed library's recorded release pointer. See\n[Publishing and Installing Vocabulary Libraries](docs/guides/libraries.md) for\nthe complete DeFi authoring, dependency-closure, packaging, GitHub Release, and\nupdate workflow.\n\n### Use in Python\n\n```python\nfrom sema.core.registry import RegistryManager\n\nregistry = RegistryManager()\npattern = registry.get_pattern(\"StateLock\")\n\n# Look up the canonical reference\nprint(pattern[\"sema_ref\"]) # StateLock#c9c2\n\n# Verify an inline reference before relying on it\nassert pattern[\"sema_ref\"] == \"StateLock#c9c2\"\n```\n\n### Try the Protocol (No API Keys Needed)\n\n```bash\npython experiments/demos/local_handshake.py\n```\n\nSee the handshake in action: matching hashes PROCEED, mismatched hashes HALT,\nand unknown patterns HALT. Cooperative mode accepts short prefixes for drift\ndetection; strict mode requires the full hash. Takes 2 seconds.\n\n## How It Works\n\n```\nword = hash(canonical(definition))\n```\n\nTake 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.\n\n```\nCooperative: sema_handshake(\"StateLock#c9c2\")\n -> PROCEED with assurance=\"prefix\", or HALT\n\nStrict: sema_handshake(\"StateLock\", \"\", strict=true)\n -> PROCEED with assurance=\"full_hash\", or HALT\n```\n\nThis is the **Anti-Postel principle**: strict mode proceeds only on full-hash\nidentity; cooperative mode uses compact prefixes as a non-adversarial drift\nsignal. Mismatches fail closed in both modes.\n\n## The Vocabulary\n\nThe bundled vocabulary spans 4 layers:\n\n- **Physics** — Immutable substrate (locks, entropy, causality)\n- **Mind** — Hybrid cognition (reasoning, inference, strategy)\n- **Society** — Multi-agent coordination (economics, governance, protocols)\n- **Infrastructure** — Operational constraints (data structures, verification)\n\nEach pattern is a content-addressed behavioral definition. Concrete cards may\nadd machine-verifiable contracts, invariants, failure modes, parameters, and\ntyped dependencies where those fields are identity-defining.\n\n## MCP Tools\n\nWhen running as an MCP server (`sema mcp`), these tools are available:\n\n| Tool | Description |\n|------|-------------|\n| `sema_search` | Search patterns by name, description, or meaning |\n| `sema_lookup` | Get a pattern by its reference (e.g., `StateLock#c9c2`) |\n| `sema_resolve` | Get a pattern with dependencies expanded |\n| `sema_handshake` | Fail-closed semantic verification between agents |\n| `sema_mint` | Create a new pattern (validate, hash, add to vocabulary) |\n| `sema_propose_context` | Compute a context digest for a multi-agent definition set (drift detection) |\n| `sema_verify_context` | Verify a context proposal from another agent |\n| `sema_tree` | Browse vocabulary by layer and category |\n| `sema_validate` | Validate a pattern JSON for correctness |\n| `sema_stats` | Vocabulary statistics |\n| `sema_graph_skeleton` | Ultra-minimal graph overview (~150 tokens) |\n| `sema_reset_session` | Clear session cache so searches return full results again |\n\n## Web Frontend\n\n```bash\npip install \"semahash[api]\"\nsema serve\n# Open http://localhost:3000\n```\n\nInteractive 3D graph visualization, pattern browser, and search. Built with React + Three.js.\n\n## Experiments\n\nThe `experiments/` directory contains reproducible evaluations of Sema's\nclaims and implementation boundaries.\n\n### Delta reconstruction\n\nThe public `v0.3.0` to `v0.4.0` reconstruction experiment checks whether the\ncurrent graph and hash-cascade algorithm can rebuild a target vocabulary from\nan earlier release. It compares both aggregate roots, semantic pattern content,\nthe logical dependency graph, unhashed metadata, and the complete normalized\nread model rather than treating root equality as complete release equality.\nIt also demonstrates the safe reconstruction path: integrate the delta into a\ncomplete staged card snapshot, compile a fresh database, verify the result, and\nonly then activate it.\n\n```bash\n.venv/bin/python experiments/delta_reconstruction/reproduce.py\n```\n\nThe experiment and its expected results are documented in\n[`experiments/delta_reconstruction/README.md`](experiments/delta_reconstruction/README.md).\nSmall synthetic versions of its addition, removal, rename, cascade, metadata,\nand failure cases run in the regular test suite.\n\n### Multi-agent design challenge\n\nThe controlled multi-agent design challenge compares three conditions:\n\n| Condition | Sema | Turns | Outcome |\n|-----------|------|-------|---------|\n| A: Natural language only | No | 4 | Design rejected |\n| B: Sema vocabulary | Yes | 11 | SAD Engine approved |\n| C: Sema + protocol | Yes | 25 | SAD Engine with exhaustive vetting |\n\nAgents with Sema patterns produced physics-grounded designs that survived adversarial scrutiny. Agents without Sema produced shallow designs that failed safety review.\n\nTo reproduce:\n\n```bash\ncd experiments/sema_design_challenge\nexport GOOGLE_API_KEY=your_key\n./reproduce.sh\n```\n\nSee [`experiments/sema_design_challenge/README.md`](experiments/sema_design_challenge/README.md) for details.\n\n## Key Properties\n\n- **Zero semantic collisions** across the full vocabulary\n- **16.9x average token compression** via content-addressed stubs\n- **Fail-closed architecture** — mismatches halt, never fail silently\n- **Mean embedding similarity of 0.21** — high structural distinctness\n\n### Formal-verification pilot\n\nSema's handshake decision kernel and canonicalization type tags have a small\nLean 4 proof suite. The handshake supports cooperative prefix matching for\nordinary drift detection and strict full-hash verification for proof-grade\nidentity; the proofs state each guarantee separately. The encoding proof\nestablishes pre-hash domain separation, while Python conformance tests connect\nthe models to production. See\n[`verification/README.md`](verification/README.md) for the proven theorems,\ntrusted-computing-base assumptions, and explicit limits of the claim.\n\n## Using with understanding-graph\n\nSema gives your agents shared *semantic* memory — a vocabulary of cognitive patterns with content-addressed identity. [Understanding Graph](https://github.com/emergent-wisdom/understanding-graph) gives them shared *episodic* memory — the actual thinking trail behind a decision. They compose:\n\n```bash\nclaude mcp add sema -- uvx --from \"semahash[mcp]\" sema mcp\nclaude mcp add ug -- npx -y understanding-graph mcp\n```\n\nWith both installed, an agent can:\n\n1. Anchor an understanding-graph decision node in a sema pattern hash (e.g. `StateLock#c9c2`) so the meaning of the primitive can never drift.\n2. Use `graph_semantic_search` to find all past graph nodes that reference a given sema pattern — hash-stable history, not keyword matching.\n3. Call `sema_handshake` *before* writing a decision that depends on a shared concept; if it returns `HALT`, the agent writes a `tension` node instead and stops, preventing silent divergence.\n\nFull walkthrough: [docs/guides/understanding-graph.md](docs/guides/understanding-graph.md)\n\n## Repository Structure\n\n```\nsema/\n├── src/sema/ Core library (hashing, validation, MCP server, API)\n├── data/ Vocabulary pattern cards + taxonomy databases\n├── docs/ Documentation (philosophy, schema spec, CLI reference)\n├── paper/ Academic paper (sema.tex)\n├── web/ Web frontend (React + Three.js graph visualization)\n├── experiments/\n│ ├── orchestrator/ Multi-agent engine (bundled for experiment reproduction)\n│ ├── delta_reconstruction/ Historical release reconstruction validation\n│ ├── sema_design_challenge/ Main experiment (3 conditions, 5 runs, full traces)\n│ └── demos/ Standalone demos (local handshake, Babel Test)\n└── pyproject.toml Package config (extras: [mcp], [api], [full])\n```\n\n## Contributing\n\nWant to add patterns, improve existing ones, or host the frontend locally? See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Citing\n\n```bibtex\n@misc{westerberg2026sema,\n title = {Sema: When the Hash Is the Word},\n author = {Westerberg, Henrik},\n year = {2026},\n month = apr,\n publisher = {Zenodo},\n doi = {10.5281/zenodo.19462702},\n url = {https://doi.org/10.5281/zenodo.19462702}\n}\n```\n\nSee [`CITATION.cff`](CITATION.cff) for the machine-readable version (GitHub\nrenders a \"Cite this repository\" button from it).\n\n## Safety\n\nSema ships no executable code — it's a library of pattern *definitions* (handles, mechanisms, invariants, dependency graphs). The MCP server hands patterns to clients as data; it does not execute the behaviors they describe.\n\n**Intended use: reasoning and reference.** Patterns are thinking tools — named concepts agents can search, resolve, and handshake on to reason about coordination, risk, and procedure. See [`docs/manuals/vocabulary-design.md`](docs/manuals/vocabulary-design.md) for the intent behind each pattern and the design choices.\n\n**Running patterns as executable recipes is untested.** Many patterns describe procedures an agent could step through. That path is still a research phase — the mechanism text has not been validated end-to-end, and we make no claims about safety when a pattern is executed rather than referenced. If you go this route, run the agent's execution step in a sandboxed environment. Patterns with known risks carry a `caution` field in their metadata; absence of that flag means the pattern has not been classified as risky, not that it has been certified safe.\n\nThe long-term goal is cryptographically enforced safety constraints on agent-to-agent communication — an active research direction.\n\n## License\n\nSema is dual-licensed:\n\n- **Code** (everything in `src/`, `web/`, `experiments/`, `scripts/`, and the\n package config) — [MIT](LICENSE). Self-host it, fork it, build commercial\n products on top of it.\n- **Content** (the pattern vocabulary in `data/`, the documentation in `docs/`,\n the academic paper in `paper/`, and the prose displayed on\n [semahash.org](https://semahash.org)) —\n [CC BY 4.0](LICENSE-CONTENT). Reuse the patterns and prose anywhere, for any\n purpose including commercial, as long as you attribute Henrik Westerberg.\n\nFor academic citation, see [`CITATION.cff`](CITATION.cff). GitHub renders this\nas a \"Cite this repository\" button on the project page that generates APA and\nBibTeX automatically.\n",
"bytes": 15763,
"sha": "8a9518f353fc33c35a59086f7373b6a0a2206a3743b2f8119212031dd91ef19d",
"repo_slug": "emergent-wisdom/sema",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_emergent_wisdom_semahash_57d3d4aa/readme"
}
![\"Sema](\"https://raw.githubusercontent.com/emergent-wisdom/sema/main/docs/images/sema_banner.png\")
\n