@derive-ltd/uht-substrate

CLI and MCP client config for the Universal Hex Taxonomy Substrate API — classify entities, compare concepts, manage facts, and build knowledge graphs.

Operated by DERIVE LTD (Company 17159546, England & Wales)

Install

npm install -g @derive-ltd/uht-substrate

Or run without installing:

npx @derive-ltd/uht-substrate <command>

Setup

uht-substrate config set token <your-api-token>

Get a token by signing in at substrate.universalhex.org (Google or GitHub login).

The default API URL is https://substrate.universalhex.org/api. To override:

uht-substrate config set api-url https://your-server.com/api

Or use environment variables:

export UHT_API_URL=https://substrate.universalhex.org/api
export UHT_TOKEN=your-token

MCP Client Config

This package includes mcp.json for connecting AI agents (Claude Desktop, etc.) to the hosted MCP server. Add to your Claude Desktop config:

{
  "mcpServers": {
    "uht-substrate": {
      "url": "https://substrate.universalhex.org/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Quick Start

# Classify an entity — get its 8-char hex code and 32 trait bits
uht-substrate classify hammer
uht-substrate classify "cognitive dissonance" -c "a psychology concept" --format pretty

# Reclassify in place (skip cache, update existing entity)
uht-substrate classify "epistemic humility" \
  -c "the intellectual virtue of recognizing the limits of one's knowledge" \
  --force

# Compare two entities — Jaccard similarity, shared/unique traits
uht-substrate compare hammer screwdriver --format pretty

# Batch compare — rank candidates by similarity
uht-substrate batch-compare hammer wrench screwdriver pliers saw

# Semantic search across 16k+ entities
uht-substrate search "hand tools" --limit 10

# Disambiguate a polysemous term
uht-substrate disambiguate bank

Commands

Classification & Reasoning

| Command | Description | |---------|-------------| | classify <entity> | Classify an entity (-c context, -f force, -n namespace, --display-name) | | infer <entity> | Infer properties from classification | | compare <a> <b> | Compare two entities | | batch-compare <entity> <candidates...> | Compare against multiple, ranked by Jaccard | | search <query> | Semantic search across the entity corpus | | disambiguate <term> | Get word senses for polysemous terms | | semantic-triangle <text> | Ogden-Richards semantic triangle decomposition | | map-properties <props...> | Map natural language properties to UHT trait bits |

Entity Management

| Command | Description | |---------|-------------| | entities list | List entities (-n name, --namespace, -l limit/all, --offset, --count-only) | | entities get | Get a single entity by --name or --uuid | | entities update <name> | Update metadata (-d description, --display-name) | | entities reclassify <name> | Re-run classification preserving UUID and facts (-c, -n) | | entities merge <source> <target> | Merge duplicate entities, transferring all facts and relationships | | entities history <name> | View classification history (previous hex codes) | | entities delete <name> | Delete entity (unbinds referencing facts) | | entities deduplicate | Find/remove entities that leaked from global into a namespace | | entities find-similar <entity> | Find similar entities by trait overlap | | entities search-traits | Search entities by trait pattern (--<trait> / --no-<trait>) |

Trait search example

Use --<trait-name> to require a trait, --no-<trait-name> to exclude:

uht-substrate entities search-traits --synthetic --powered --no-biological

Fact Management

| Command | Description | |---------|-------------| | facts store <subject> <predicate> <object> | Store a fact (-n namespace, -u user) | | facts store-bulk -f <path> | Store multiple facts from JSON (-n default namespace) | | facts upsert <subject> <predicate> <object> | Create or update a fact | | facts query | Query facts with filters (-s, -o, -p, -c, -n, -l limit/all) | | facts update <fact-id> | Update an existing fact | | facts delete <fact-id> | Delete a fact | | facts user-context | Get a user's stored facts | | facts namespace-context <namespace> | Get all entities and facts under a namespace | | facts reconcile | Cross-check facts against AIRGen trace links |

# Store a typed fact
uht-substrate facts store "spark plug" PART_OF "engine" --namespace SE:automotive

# Query facts (returns total count for pagination)
uht-substrate facts query --subject "spark plug" --category compositional
uht-substrate facts query --namespace SE:automotive --predicate PART_OF --limit all

# Bulk store from JSON with default namespace
echo '[{"subject":"bolt","predicate":"PART_OF","object_value":"frame"}]' \
  | uht-substrate facts store-bulk -f - --namespace SE:automotive

Namespace Management

| Command | Description | |---------|-------------| | namespaces create <code> <name> | Create a namespace | | namespaces list | List namespaces | | namespaces assign <entity> <namespace> | Assign an entity to a namespace |

uht-substrate namespaces create SE:automotive "Automotive Engineering"
uht-substrate namespaces assign "spark plug" SE:automotive
uht-substrate namespaces list --parent SE --descendants

Reference

| Command | Description | |---------|-------------| | info | System information and overview | | traits | All 32 trait definitions (with version) | | trait-prompts | Classifier prompts sent to the LLM (edge cases, examples) | | patterns | Reasoning patterns for tool orchestration |

Configuration

| Command | Description | |---------|-------------| | config set <key> <value> | Set a config value (api-url, token, format) | | config show | Show current configuration |

Pipeline Integration

Semantic Impact Analysis

Analyse the semantic impact of requirement changes from an Airgen diff. For each changed requirement, the command classifies the text using UHT and detects semantic drift — cases where a textual edit shifts the requirement into a different meaning-space.

# Generate a diff from airgen
airgen diff --json > diff.json

# Analyse impact
uht-substrate impact --airgen-diff diff.json --format pretty
uht-substrate impact --airgen-diff diff.json --json

The input file must be the JSON output from airgen diff --json, structured as { summary, added, removed, modified } where each requirement has ref and text fields, and modified entries have old_text and new_text.

Global Options

| Option | Description | |--------|-------------| | --api-url <url> | API base URL | | --token <token> | Bearer token for authentication | | --format <fmt> | Output format: json (default) or pretty | | --verbose | Show request/response details | | --version | Show version |

Output Formats

JSON (default) — machine-readable, pipe to jq:

uht-substrate classify hammer | jq '.hex_code'

Pretty — colored terminal output:

uht-substrate classify hammer --format pretty

What is UHT?

The Universal Hex Taxonomy encodes any concept as a 32-bit classification (8-char hex code) across four layers:

• Physical (bits 1–8): Material properties, boundaries, energy
• Functional (bits 9–16): Capabilities, interfaces, state
• Abstract (bits 17–24): Symbolic, temporal, rule-governed
• Social (bits 25–32): Cultural, economic, institutional

Two entities with similar hex codes share similar properties. Jaccard similarity measures meaningful overlap between classifications.

License

MIT