Sema: 해시가 곧 단어일 때

다중 에이전트 조정을 위한 콘텐츠 주소 지정 방식의 의미론.

Sema는 의미 자체에 콘텐츠 주소를 지정하는 의미론적 공통 기반입니다. 즉, 정의가 곧 식별자입니다. 패턴 정의의 암호화 해시에서 식별자를 도출하므로, 의미가 조금이라도 다르면 고유한 해시가 생성되어 정렬되지 않은 에이전트가 조용히 실패하는 대신 즉시 중단되도록 보장합니다.

웹: 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

Related MCP server: giskard-memory

빠른 시작

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 서버를 노출합니다.

작동 확인 — 에이전트에게 다음과 같이 물어보세요: "Search sema for coordination patterns and handshake on 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

# Start local API + web frontend (binds to 127.0.0.1 by default)
sema serve

나만의 어휘 가져오기

PR이나 관리자 개입 없이 처음부터 비공개 레지스트리를 구축하세요:

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

이후의 sema 명령어(sema mcp 포함)는 비공개 레지스트리에서 읽어옵니다. 표준 기여 경로는 CONTRIBUTING.md를, 개선 및 대체 정책은 docs/specification/versioning.md를 참조하세요.

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

프로토콜 체험 (API 키 불필요)

python experiments/demos/local_handshake.py

핸드셰이크가 작동하는 모습을 확인하세요: 해시가 일치하면 진행(PROCEED), 일치하지 않으면 중단(HALT), 알 수 없는 패턴은 중단(HALT)됩니다. 2초면 충분합니다.

작동 원리

word = hash(canonical(definition))

개념(조정 프로토콜, 추론 패턴, 신뢰 메커니즘 등)을 가져와 표준 형식으로 표현하고 해시합니다. 그 해시가 곧 단어입니다. 정의에서 바이트 하나만 바꿔도 다른 단어가 됩니다.

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

이것이 **반(反) 포스텔 원칙(Anti-Postel principle)**입니다: 바이트가 같으면 진행(PROCEED), 다르면 중단(HALT). 모호함도, 조용한 실패도 없습니다.

어휘

4개 계층에 걸친 427개의 기본 패턴 (위험도가 높은 추가 패턴은 별도의 DB에 보관됨 — 안전 참조):

• 물리학 — 불변의 기질 (잠금, 엔트로피, 인과관계)

• 마음 — 하이브리드 인지 (추론, 추론, 전략)

• 사회 — 다중 에이전트 조정 (경제, 거버넌스, 프로토콜)

• 인프라 — 운영 제약 (데이터 구조, 검증)

각 패턴은 기계 검증 가능한 계약, 불변성, 실패 모드 및 유형화된 종속성을 포함하는 실행 가능한 사양입니다.

MCP 도구

MCP 서버(sema mcp)로 실행할 때 다음 도구를 사용할 수 있습니다:

웹 프론트엔드

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

대화형 3D 그래프 시각화, 패턴 브라우저 및 검색. React + Three.js로 구축되었습니다.

실험

experiments/ 디렉토리에는 세 가지 조건을 비교하는 통제된 다중 에이전트 설계 챌린지가 포함되어 있습니다:

Sema 패턴을 사용하는 에이전트는 적대적 검토를 견뎌내는 물리 기반 설계를 생성했습니다. Sema가 없는 에이전트는 안전성 검토를 통과하지 못하는 얕은 설계를 생성했습니다.

재현 방법:

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

자세한 내용은 experiments/sema_design_challenge/README.md를 참조하세요.

주요 속성

• 전체 어휘에 걸쳐 의미론적 충돌 제로

• 콘텐츠 주소 지정 방식의 스텁을 통한 평균 16.9배 토큰 압축

• 실패-닫힘(Fail-closed) 아키텍처 — 불일치 시 중단되며, 절대 조용히 실패하지 않음

• 평균 임베딩 유사도 0.21 — 높은 구조적 차별성

understanding-graph와 함께 사용

Sema는 에이전트에게 공유된 의미론적 기억, 즉 콘텐츠 주소 지정 방식의 식별자를 가진 인지 패턴 어휘를 제공합니다. Understanding Graph는 공유된 일화적 기억, 즉 결정 뒤에 숨겨진 실제 사고 과정을 제공합니다. 이 둘은 결합됩니다:

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

둘 다 설치하면 에이전트는 다음을 수행할 수 있습니다:

1. understanding-graph 결정 노드를 sema 패턴 해시(예: StateLock#5602)에 고정하여 기본 요소의 의미가 절대 변하지 않도록 합니다.

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

기여

패턴을 추가하거나, 기존 패턴을 개선하거나, 프론트엔드를 로컬에서 호스팅하고 싶으신가요? 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.19548971},
  url          = {https://doi.org/10.5281/zenodo.19548971}
}

기계 판독 가능 버전은 CITATION.cff를 참조하세요(GitHub에서 "Cite this repository" 버튼을 렌더링합니다).

안전

Sema는 실행 가능한 코드를 제공하지 않습니다. 패턴 정의(핸들, 메커니즘, 불변성, 종속성 그래프) 라이브러리입니다. MCP 서버는 패턴을 데이터로 클라이언트에게 전달할 뿐, 패턴이 설명하는 동작을 실행하지 않습니다.

사용 목적: 추론 및 참조. 패턴은 사고 도구입니다. 에이전트가 조정, 위험 및 절차에 대해 추론하기 위해 검색, 해결 및 핸드셰이크할 수 있는 명명된 개념입니다. 각 패턴의 의도와 설계 선택 사항은 docs/manuals/vocabulary-design.md를 참조하세요.

패턴을 실행 가능한 레시피로 실행하는 것은 테스트되지 않았습니다. 많은 패턴이 에이전트가 따라 할 수 있는 절차를 설명합니다. 해당 경로는 아직 연구 단계입니다. 메커니즘 텍스트는 처음부터 끝까지 검증되지 않았으며, 패턴이 참조되는 대신 실행될 때의 안전성에 대해 어떠한 주장도 하지 않습니다. 이 경로를 선택하는 경우, 에이전트의 실행 단계를 샌드박스 환경에서 실행하십시오. 알려진 위험이 있는 패턴은 메타데이터에 caution 필드가 포함되어 있습니다. 해당 플래그가 없다는 것은 패턴이 안전하다고 인증된 것이 아니라 위험하다고 분류되지 않았음을 의미합니다.

장기적인 목표는 에이전트 간 통신에 대한 암호화로 강제되는 안전 제약 조건이며, 이는 현재 활발히 연구 중인 방향입니다.

라이선스

Sema는 이중 라이선스를 따릅니다:

• 코드 (src/, web/, experiments/, scripts/ 및 패키지 구성의 모든 것) — MIT. 직접 호스팅하고, 포크하고, 그 위에 상용 제품을 구축하세요.

• 콘텐츠 (data/의 패턴 어휘, docs/의 문서, paper/의 학술 논문, semahash.org에 표시된 산문) — CC BY 4.0. Henrik Westerberg에게 저작자 표시를 하는 한, 상업적 목적을 포함하여 어디서든 패턴과 산문을 재사용하세요.

학술적 인용은 CITATION.cff를 참조하세요. GitHub는 프로젝트 페이지에 APA 및 BibTeX를 자동으로 생성하는 "Cite this repository" 버튼을 렌더링합니다.