Speak in Sema

Sema is a content-addressed vocabulary protocol. Several hundred patterns that give you precise, shared words for concepts that would otherwise require paragraphs of re-explanation. Each pattern has a handle (e.g. StateLock#c9c2) that is a cryptographic commitment to its definition — two agents using the same handle are provably talking about the same thing.

Before defining a concept from scratch, check if sema already has a word:

1. sema_search with the idea
2. sema_resolve to read mechanism and invariants
3. Use the handle as a load-bearing noun in your text: "This uses `StateLock#c9c2` to prevent concurrent mutation"

Not footnotes — actual words you think with.

When the user wants to see patterns visually

If the user asks to "see", "view", "show", or "explore" patterns visually — or asks to see the graph or browse the vocabulary — invoke the sema-ui skill to launch http://localhost:3030. The local view gives them a pattern browser, search, and a 3D graph that grows as you mint. When you start building a vocabulary with the user, offer it once so they can watch the work.

Session memory

The server tracks which patterns you've already seen. Subsequent searches return compact results for known patterns (handle + gloss + _seen: true). Just use the handle — the full definition is already in your context. Call sema_resolve only if you need to re-read a pattern's mechanism.

Call sema_reset_session() if your context was compressed or you need full results again.

The workflow

1. Search — sema_search({ query: "trust model" }) — find existing patterns by meaning
2. Resolve — sema_resolve({ handle: "TrustModel#7859" }) — read full definition, mechanism, invariants
3. Handshake — sema_handshake({ ref: "X#1234" }) — verify exact meaning before relying on a handle
4. Mint — sema_mint({ pattern_json: "..." }) — create a new pattern (rare!)

Switching and managing databases

The CLI and MCP server are separate processes with separate DB state. sema use on the CLI does NOT affect the running MCP server. Always use the MCP tool for switching:

• sema_use() — show current DB
• sema_use(db_path="/path/to/my.db") — switch to a project DB
• sema_use(default=true) — switch back to the bundled vocabulary

If sema_use MCP tool is unavailable (older server version), the MCP server cannot be hot-swapped. Use CLI for search/resolve and accept the limitation — do not confuse CLI state with MCP state.

Published libraries

People publish finished vocabularies as libraries on semahash.org.

• sema_library_search(query) finds them. No account is needed.
• sema_library_install(library) verifies and installs one by name, or from any library.json URL such as a GitHub release or a Swarm gateway address. Then sema_use(db_path=<name>) switches to it.
• Publishing needs a public GitHub release of the library, made with sema package. If the user gives you a key from their semahash.org profile, store it with sema_library_login(key). Ask the user before sema_library_publish(manifest_url), because it makes the library public.

Never write a key to a file in the project.

Vocabulary fingerprint — sema_root

Every active DB exposes two versioned identities:

• Semantic-set root (sema-semantic-set-v1): the unordered set of unique

pattern-definition hashes. Use this to compare definition sets. Under canonicalization v2, renaming a referenced target can also rehash its dependents because structured references still contain target handles.

• Catalog root (sema-catalog-v1): the exact handle → definition bindings.

Use this when both parties must resolve the same names.

Both use domain-separated canonical binary Merkle trees. sema_root() returns both roots, both scheme labels, pattern_count, definition_count, and the DB path. CLI sema root prints both; sema root --short prints the semantic-set scheme and 16-character stub together.

Use it when:

• The user asks "which version of the vocabulary are we on?"
• You need a one-shot check before a multi-step operation that depends on the vocab being stable
• The user is comparing two DBs and wants a fast equality probe

The semantic-set root is the same value that scripts/vocabulary_merkle_root.py writes into docs/information/vocabulary_information.md, so a root from the docs can be verified directly when its scheme accompanies it.

Keeping the vocabulary fresh (sema_pull / sema pull)

When upstream ships new patterns or fixes existing ones, sync the user's active DB. This is available both as an MCP tool (prefer this — you get structured output) and as a CLI command:

sema_pull()                              // apply upstream → active DB
sema_pull({ dry_run: true })             // preview without writing
sema_pull({ preserve_superseded: true }) // keep old handles alongside new
sema_pull({ exclude: ["SomeHandle"] })   // ad-hoc skip

The tool returns structured JSON: added, updated, superseded_removed, superseded_kept_orphan, upstream_removed, vocabulary_root_before, vocabulary_root_after, and vocabulary_root_scheme. Read those fields rather than re-parsing the human log.

When to suggest pull unprompted:

• A sema_handshake returns HALT against a handle the user expected to know — the upstream definition may have evolved.
• The user mentions they just upgraded the package (pip install -U semahash).
• The user asks how to "update vocabulary", "sync", or "get latest patterns".

When NOT to pull. Do not call sema_pull as part of routine orientation. It's not a "check in" — it's an update. Pulling removes locally-superseded handles by default, which can drop patterns the user has intentionally pinned. The orient phase is sema_graph_skeleton() + sema_search() — both read-only. Reserve sema_pull for the specific triggers above.

Supersession cleanup. When upstream ships a pattern whose _meta.supersedes lists a sema_id you have locally, sema_pull removes the superseded local pattern by default and adds the replacement. Two guard cases:

• Orphan guard — if a user-only local pattern still depends on the superseded one (references its exact sema_id), pull keeps the superseded pattern in place and reports the orphan in superseded_kept_orphan. Re-point the dependents and re-run to complete the cleanup.
• Opt-out — pass preserve_superseded: true to keep both old and new handles coexisting. Useful when the user wants to compare, or has reason to pin the old pattern.

Other guarantees (no need to over-explain to the user):

• Custom local patterns are NEVER deleted unless upstream explicitly supersedes them (and even then the orphan guard kicks in when dependents exist).
• User-set _meta.caution and _meta.related survive updates.
• Failures roll back atomically — there's no half-applied state to recover from.
• Each successful pull keeps ONE pre-pull snapshot. If the user says "oh that update broke things," suggest sema pull --undo (CLI) to revert.

Excluding patterns the user doesn't want. For persistent exclusions, write to ~/.config/sema/excluded (one handle per line, # starts a comment). Version-pinning recipe: keep a local copy of a pattern AND add it to the exclusion list. Dependents resolve against the local frozen version while upstream evolves around it.

Refuses to modify the bundled DB. The same sema build + sema use setup required for minting also applies here — pull only operates on writable project DBs.

Deployment opt-outs. Environment variables control which mutating tools are exposed by the MCP server. Both are off (i.e., tools exposed) by default:

• SEMA_DISABLE_PULL=true — hides sema_pull (deployments that want a pinned vocabulary)
• SEMA_DISABLE_MINT=true — hides sema_mint (read-only deployments)

Before you can mint

The bundled vocabulary is read-only — it gets overwritten on pip upgrades. To mint, you need your own project DB:

1. Run in shell (bash): sema build /tmp/my-project.db --preset full
2. Switch to it via MCP: sema_use(db_path="/tmp/my-project.db")
3. Now sema_mint will work

Note: As of 0.2.1, sema_mint is exposed by default. If the tool is unavailable, the deployment has explicitly disabled it via SEMA_DISABLE_MINT=true; ask the user to re-enable it if they want to mint.

When to mint vs reuse

Always search first. Minting is rare — only after searching three different glosses finds nothing, AND the concept has stable invariants.

Mint when:

• Repetition: explaining the same concept 3+ times
• Invariants: concept has non-negotiable constraints
• Boundary: another agent needs exact protocol
• Saturation: concept refined 3+ times (stable enough to crystallize)

Minting structure

sema_mint({
  pattern_json: JSON.stringify({
    handle: "PatternName",          // 1–2 syllables, speakable
    mechanism: "How the pattern works",
    gloss: "One-line summary",      // What it IS
    invariants: ["Must...", ...],   // Non-negotiable constraints
    _meta: {
      path: ["Mind", "Reasoning"],
      ring: 1,
      tier: 2,
    },
  })
})

Embedding handles in text

Use sema handles as load-bearing nouns — not footnotes, actual words you think with:

"This uses StateLock#c9c2 to prevent concurrent mutation"

Wrap handles in backticks for readability. When you encounter a handle you don't recognize, resolve it before proceeding.

Verify at boundaries

When two agents (or an agent and a human) need to agree on meaning:

const challenge = sema_handshake({ ref: "StateLock" })
// → PROVIDE_HASH with the canonical stub. Compare against your local value, then:
sema_handshake({ ref: "StateLock", your_hash: challenge.canonical_stub })
// PROCEED (match) or HALT (drift). No silent misunderstandings.

For bulk verification of a specific handle-selected set, call sema_propose_context, then pass both its context_hash and root_scheme to sema_verify_context. Context roots use the catalog scheme so every selected handle remains bound to its definition.

Vocabulary-wide handshake

When two agents need a cooperative definition-set drift check, pass ref="vocab" and echo both the root and scheme:

const challenge = sema_handshake({ ref: "vocab" })
// → { verdict: "PROVIDE_HASH", full_sema_id, root_scheme, definition_count }

sema_handshake({
  ref: "vocab",
  your_hash: challenge.full_sema_id.split(":").at(-1),
  your_scheme: challenge.root_scheme,
  strict: true
})
// → PROCEED with full_hash assurance, or a non-proceeding verdict

The full hash with strict: true is the identity check; a prefix is only cooperative drift detection. Use ref="catalog" in the same workflow when handle bindings must also match. If equal schemes have different roots, sema pull may converge their data or sema_propose_context can scope agreement to a known-shared subset. If schemes differ, upgrade the older Sema installation: pulling identical pattern leaves cannot repair an aggregate-algorithm mismatch.

Think with sema, don't just cite it

Sema patterns are thinking tools, not references. When a user asks you to reason about any problem — farming, architecture, career decisions, anything — search sema for patterns that structure the reasoning itself.

For example, if someone asks "how should I start a business?":

1. Search for strategy, risk, decision, explore exploit, decompose
2. Resolve the top hits — read their mechanisms and invariants
3. Use those patterns to structure your answer: "This is a Strategy#3dc5 problem, not a Plan#246d problem, because..."

The patterns aren't labels you slap on afterward. They're lenses that change what you see. ExploreExploit#218c doesn't just name a concept — it tells you when to stop researching and start acting. PreMortem#e4c2 doesn't just mean "think about failure" — it has a specific mechanism for surfacing hidden risks.

A pattern whose path ends in Dynamics describes how a system behaves rather than what to do. Apply it as a model to test against the case: do its conditions hold here, and what should you observe if they do? MalthusianTrap#0f6b tells you what to expect of population and living standards; it gives no steps to run.

When to reach for sema unprompted:

• User asks an open-ended reasoning question (how, why, what should I)
• You're about to give generic advice that sema could sharpen
• A problem has clear structure (tradeoffs, risks, sequences, feedback loops) that sema patterns could make explicit

When NOT to force it:

• Simple factual questions
• The user wants a quick answer, not a framework
• No relevant patterns exist after searching

Thinking nodes should use sema too

When you create concept nodes alongside creative work (stories, analysis, prose), check whether a sema pattern captures the cognitive move you're making. It won't always fit — a narrative tension node doesn't need a handle forced in — but consider it. The thinking layer is where sema is most useful, because it compresses recurring patterns into precise vocabulary that future agents can reason with.