io.github.emergent-wisdom/semahash

Ultra-minimal graph overview (~150 tokens). Shows regions, hubs, and recent activity. Returns: Text summary of the graph structure.

Byte-level definition agreement check between two agents. Verifies that the requesting agent and the local registry have the *same definition* of a pattern, by comparing content hashes. This is a necessary precondition for shared reasoning about a pattern, but it is NOT a guarantee of shared behavior: two agents can agree on the definition text and still implement it differently. Think of it as "we read the same paragraph," not "we will do the same thing." Use this when you need to rule out silent vocabulary drift before coordinating on a pattern. It does not replace behavioral testing. Args: ref: Pattern reference (e.g., "StateLock#c9c2", "StateLock", or the full "sema:StateLock#mh:SHA-256:<64 hex>" a document carries), "vocab" for the semantic-set root, or "catalog" for exact handle-to-definition bindings. A hash inside ref is compared like your_hash; your_hash takes precedence when both are given. your_hash: Your local hash — the 4-char pattern stub, or the 16-char vocab root stub (or full 64-char root). If omitted, returns the canonical hash for you to compare. strict: If true, only a full 64-character hash can produce PROCEED. A matching stub returns REQUIRE_FULL_HASH. If false (default), stubs may proceed for cooperative drift detection. your_scheme: Aggregate-root scheme returned by `sema_root` or an initial aggregate handshake. Required whenever `your_hash` is supplied for `vocab` or `catalog`. Omission or a different scheme fails with HALT; `sema pull` cannot repair algorithm-only drift. Returns: JSON with verdict: PROCEED (accepted under the selected mode), HALT (mismatch), PROVIDE_HASH (no hash supplied), or REQUIRE_FULL_HASH (stub matches but strict mode needs the complete digest). PROCEED includes assurance=prefix or assurance=full_hash. Example workflow (pattern): 1. Agent A: sema_handshake("StateLock") -…

Install a published library by name, path, or library.json URL. Sema downloads the release, verifies every pattern identity and both roots, and builds a fresh read-only database before it registers the library. A name installs exactly the release that the registry verified; if the publisher now serves a different one, nothing is installed. The active vocabulary does not change: call `sema_use(db_path=<name>)` to switch to it. Args: library: A name from `sema_library_search`, a local path, or an HTTPS URL that ends with library.json. registry: The registry that resolves a name. Returns: JSON with the installed name, version, pattern count, and roots.

Store a registry key that the user created on their profile page. Use this when the user gives you a key that starts with `sema_`. Sema checks the key with the registry and stores it under the user's Sema configuration with owner-only permissions. Do not write the key into a file that is committed or shared. Args: key: The key, starting with sema_. registry: The registry the key belongs to, https://semahash.org by default. Returns: JSON with the account the key belongs to, or an error.

Publish a library release on the public registry. This is a public action: everyone can see and install the library afterwards. Ask the user before you call it. The release must be a public GitHub Release in a repository that the logged-in account owns. Build it first with `sema package` and attach its library.json and pattern archive to the release. The registry verifies the release and keeps a snapshot; the GitHub release stays the source. Args: manifest_url: The release's stable URL, for example https://github.com/USER/REPO/releases/latest/download/library.json registry: The registry to publish on, https://semahash.org by default. Returns: JSON with the published library and its page, or an error that says how to log in.

Find published Sema libraries on a registry, https://semahash.org by default. No login is needed. Each result gives the library name, version, source repository, pattern count, semantic root, license, and a stable library.json URL. Install one with `sema_library_install(library=<name>)`. Args: query: Words that must all appear in the name, owner, or repository. Empty lists every library. registry: Another registry origin, for example a local test site. Returns: JSON with the matching libraries, or an error.

Lookup a pattern by its Sema reference (Handle#stub). Args: ref: Pattern reference like "ChainOfThought#27ad" or just "ChainOfThought" Returns: Full pattern JSON

Create a new pattern and add it to the vocabulary. The pattern is validated (schema, dependency wiring, DAG check), hashed to produce a content-addressed identity, and added to the local database. Returns the new pattern's sema_id on success. Exposed by default. Deployments that want a read-only server can set `SEMA_DISABLE_MINT=true` to hide this tool. Args: pattern_json: JSON string of the pattern to mint. Required fields: - handle: PascalCase name (e.g., "MyPattern") - mechanism: How the pattern works - gloss: One-line summary Recommended: invariants, preconditions, postconditions, failure_modes, dependencies, _meta.path (layer and category), _meta.ring, and _meta.tier Returns: JSON with the minted pattern's sema_id, or validation errors.

Propose a shared definition set for multi-agent coordination. Computes a truncated catalog Merkle root over the requested handle-to-definition bindings. The receiving agent calls sema_verify_context with the same handles and compares roots. Properties of the digest: - Order-independent: handle bindings are sorted before the versioned RFC 9162 tree construction. - Binding-sensitive: swapping two handles' definitions changes the root. - 32 bits wide (8 hex chars). Birthday collisions become likely after roughly 65k independently sampled contexts. This is sufficient to catch ACCIDENTAL vocabulary drift between cooperating agents, but NOT a security primitive: an active adversary can brute-force a matching 4-byte prefix. - What it verifies: that both agents have byte-identical definitions for every pattern in the set. - What it does NOT verify: that both agents will behave compatibly when executing those patterns. Workflow: 1. Agent A: sema_propose_context(["StateLock", "Check", "Task"]) -> returns context_hash "7f3a..." + root_scheme 2. Agent A sends both values to Agent B 3. Agent B: sema_verify_context( ["StateLock", "Check", "Task"], "7f3a...", "<scheme>" ) -> PROCEED or HALT Args: handles: List of pattern handles to include in the context. Returns: JSON with the context_hash, root scheme, and pattern refs.

Refresh the local vocabulary from upstream. Walks the upstream DAG in topological order and updates the active database in place. User-only patterns are preserved; hashes cascade automatically when their upstream deps change. Superseded handles are redirected to their replacements by default (opt out with `preserve_superseded=True`). Returns structured JSON with `success`, `added`, `updated`, `skipped`, `cascaded_user`, `superseded_removed`, `superseded_kept_orphan`, `upstream_removed`, `vocabulary_root_before`, `vocabulary_root_after`, and `vocabulary_root_scheme` so callers can react programmatically instead of parsing the human log. Exposed by default. Deployments that want a pinned vocabulary can set `SEMA_DISABLE_PULL=true` to hide this tool. Args: source: Optional path to an alternate upstream DB. Defaults to the bundled vocabulary shipped with the installed package. dry_run: If True, previews changes (including supersession redirects) without writing to the active DB. exclude: Handles to skip for this invocation. Unioned with the persistent `~/.config/sema/excluded` list. preserve_superseded: If True, retain locally superseded patterns alongside their upstream replacements instead of removing them. Returns: JSON string of the result dict.

Reset the session pattern cache. Clears the record of which patterns have been served this session, so the leading matches in subsequent searches return detailed results again. Use when context has been compressed or you need fresh detail. Returns: Confirmation with count of patterns cleared.

Get a pattern with its dependencies expanded. Args: handle: Pattern handle (e.g., "ChainOfThought") depth: How many hops to expand (1 = direct deps, 2 = deps of deps) Returns: JSON object with the pattern and its resolved dependencies

Get both aggregate roots of the active vocabulary. The semantic-set root commits to the unordered set of definition digests and ignores duplicate meanings. The catalog root separately commits to exact handle-to-digest bindings. Both use versioned, domain-separated RFC 9162 Merkle Tree Hash constructions. Pair with `sema_handshake(ref="vocab", ...)` for semantic-set alignment or `sema_handshake(ref="catalog", ...)` for namespace alignment. Returns: JSON with both roots, schemes, counts, full IDs, and short stubs.

Search Sema patterns by name, description, or meaning (semantic search). Also search with the problem in front of you, for example "decide under uncertainty" or "find where a disagreement starts": patterns include protocols and checks that structure reasoning. Returns at most 20 ranked matches. The first three unseen matches include search detail; later and previously seen matches use compact summaries. New matches name their layer and category. Searching inside a layer or category ranks its closest patterns, weak matches included: use it when you know which category fits or the first results miss, alongside the unscoped search rather than instead of it, since a category guessed from the top results is often the wrong one. Use sema_resolve() to fetch the complete Pattern Card you need. Args: query: Search term or concept description. limit: Maximum matches to return. Defaults to 10 and is capped at 20. layer: Only search this layer (Physics, Mind, Society, Infrastructure). category: Only search this category, e.g. "Verification". Names are case-insensitive; sema_tree() lists them. Returns: JSON array of matching patterns, or an error naming the valid layers or categories when the one given does not exist.

Get statistics about the Sema vocabulary. Returns: JSON with vocabulary statistics

Browse the vocabulary structure organized by layer and category. Args: layer: Filter to specific layer (Physics, Mind, Society, Infrastructure) category: Filter to specific category verbose: If True, includes the gloss (description) for each pattern. Returns: JSON tree structure of patterns

Switch the active vocabulary database without restarting. Args: db_path: Path to the database to switch to. Omit to show current. default: If True, switch back to the bundled vocabulary. Returns: JSON with the new vocabulary stats, or current status.

Validate a pattern JSON using the same rules as the mint pipeline. Args: pattern_json: JSON string of a pattern to validate Returns: Validation result with any errors or warnings

Verify a semantic context proposed by another agent. Computes the local truncated catalog root for the given handle bindings and compares it against the remote agent's root under the declared scheme. PROCEED if both match, HALT if not. The short root is a drift-detection primitive between cooperating agents, not a security primitive against an adversary (see sema_propose_context for details). Args: handles: List of pattern handles in the proposed context. remote_hash: The context_hash received from the proposing agent. remote_scheme: The root_scheme received from the proposing agent. Omission or a different scheme fails closed. Returns: JSON with verdict: PROCEED (contexts match) or HALT (drift detected).