Minting Sema Patterns

Minting creates a new content-addressed pattern in the sema vocabulary. The definition IS the identity — hash the content, get the name. Change one invariant, get a different hash.

Before you start a minting session

1. Check that minting is enabled. sema_mint is exposed by default. If it's missing from your available MCP tools, the server has been explicitly configured to hide it. Tell the user:

"Minting isn't available on this server — it's disabled via SEMA_DISABLE_MINT=true. Unset that env var and restart to re-enable."

2. Make sure the active DB is writable. The bundled vocabulary is read-only — minting into it will be blocked with an error. If the user wants to mint, they need a project DB:

sema build my-project.db --preset full
sema use my-project.db

Or use sema_use(db_path="...") via MCP.

3. Offer the UI. Ask: "Want to open the Sema UI to watch the patterns appear as they get minted?" If yes, invoke the sema-ui skill. The UI refreshes every 5 seconds locally, so each new pattern appears within a few seconds of being minted.

When to mint

Minting is rare. Before minting, search at least three different glosses. Only mint when:

• You've explained the same concept 3+ times across conversations
• The concept has stable, non-negotiable invariants
• Another agent needs the exact protocol to coordinate
• A graph concept has been refined 3+ times (stable enough to crystallize)

The pipeline

sema_mint(pattern_json) runs a full validation + hash + store pipeline:

1. Parse — JSON syntax check
2. Schema validate — required fields, handle format, layer/category validity
3. Dependency wiring — every {{placeholder}} in text must be declared in dependencies; every declared dependency must be used
4. DAG check — no cycles in the dependency graph; topological sort
5. Layer direction — lower layers cannot depend on higher layers (Infrastructure < Physics < Mind < Society)
6. Merkle hash — hash only the semantic fields to produce the content-addressed identity
7. Store — add to vocabulary database with computed sema_id, sema_ref, sema_stub

If any step fails, the pattern is rejected with an error message. No partial writes.

Required fields

{
  "handle": "MyPattern",
  "mechanism": "How it works, referencing {{dependency_key}} placeholders",
  "gloss": "One-line summary",
  "_meta": {
    "layer": "Mind",
    "category": "Reasoning",
    "ring": 1,
    "tier": 2
  }
}

When to add a caution flag

Add _meta.caution if:

• The pattern enables irreversible action (data loss, financial commitment, governance changes)
• The pattern bypasses safety checks or oversight
• The pattern enables evasion, manipulation, or covert coordination
• The risk isn't already explicit in the mechanism, invariants, or failure_modes

Skip the flag if:

• The pattern's existing fields make the risk self-evident
• The pattern is purely cognitive (a reasoning lens) with no external effect

The caution sits in _meta (unhashed), so it can be revised without changing the pattern's identity.

Layer categories

Recommended fields

Never use empty lists `[]` or empty objects `{}`. Omit the field instead.

Dependencies

Dependencies are the structural wiring between patterns. Four categories:

Each key must be snake_case and used as a {{placeholder}} in mechanism, invariants, preconditions, postconditions, or failure_modes.

"dependencies": {
  "references": {
    "think": "sema:Think#mh:SHA-256:e1bd..."
  },
  "composes_with": {
    "reflexion": "sema:Reflexion#mh:SHA-256:51b9..."
  },
  "accepts": {
    "context": "sema:Context#mh:SHA-256:510a..."
  },
  "yields": {
    "datum": "sema:Datum#mh:SHA-256:31cf..."
  }
}

Wiring rules

• Forward rule: every {{key}} used in text fields MUST be declared in dependencies
• Inverse rule: every key declared in dependencies MUST be used at least once in text fields
• Uniqueness: each key appears in exactly one category
• Layer direction: cannot depend on a pattern from a higher layer

Getting dependency hashes

Before minting, resolve the full sema_id of each dependency:

sema_resolve("Think")  →  sema_id: "sema:Think#mh:SHA-256:e1bd..."

Use the full sema_id as the dependency value. During initial minting (before the pattern has been hashed), you can use the handle alone — the pipeline will resolve it.

The content hash

Only semantic fields are hashed — metadata and computed fields are excluded:

Hashed: mechanism, gloss, invariants, preconditions, postconditions, failure_modes, dependencies, signature, parameters, data_schema, derived_from

NOT hashed: handle, _meta, sema_id, sema_ref, sema_stub

This means: rename a pattern (change handle) and the hash stays the same. Change one invariant and you get a different hash. Same semantic content = same identity, guaranteed.

The hash uses a Merkle tree: strings are NFC-normalized, dicts are sorted by key, lists preserve order. The result is a SHA-256 digest truncated to a 4-char stub for human readability.

Before you mint: the checklist

1. Search three glosses — sema_search with different phrasings. If >80% similar exists, don't mint.
2. Resolve dependencies — sema_resolve each pattern you'll reference. Get full sema_id values.
3. Validate first — sema_validate with your draft JSON. Fix all errors before minting.
4. Check layer direction — your pattern's layer must be >= all dependency layers.
5. Wire all placeholders — every {{key}} in text has a dependency; every dependency appears in text.
6. No empty fields — omit rather than [] or {}.

Example: minting a pattern

// 1. Search first
sema_search({ query: "pre-mortem risk analysis" })
// Nothing close enough — proceed

// 2. Resolve dependencies
sema_resolve({ handle: "Strategy" })   // → sema_id: "sema:Strategy#mh:SHA-256:47a4..."
sema_resolve({ handle: "Risk" })       // → sema_id: "sema:Risk#mh:SHA-256:8b2c..."

// 3. Validate draft
sema_validate({ pattern_json: JSON.stringify({
  "handle": "PreMortem",
  "mechanism": "Before committing to a {{strategy}}, assume it has already failed. Work backward to identify the most likely {{risk}} factors that caused the failure. Each identified risk becomes an input to mitigation planning.",
  "gloss": "Assume failure, then find what caused it",
  "invariants": [
    "Must be applied BEFORE commitment, not after",
    "Every identified {{risk}} must have a corresponding mitigation"
  ],
  "failure_modes": [
    "Anchoring: team fixates on one failure mode and misses others",
    "Premature closure: stopping after 2-3 obvious {{risk}} factors"
  ],
  "_meta": {
    "layer": "Mind",
    "category": "Strategy",
    "ring": 1,
    "tier": 2
  },
  "dependencies": {
    "references": {
      "strategy": "sema:Strategy#mh:SHA-256:47a4...",
      "risk": "sema:Risk#mh:SHA-256:8b2c..."
    }
  }
}) })

// 4. Mint
sema_mint({ pattern_json: "..." })
// → { success: true, handle: "PreMortem", sema_ref: "PreMortem#6cc4", sema_id: "sema:PreMortem#mh:SHA-256:f69d..." }

Common errors and fixes