io.github.emergent-wisdom/semahash

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.

Search Sema patterns by name, description, or meaning (semantic search). Returns at most 20 ranked matches. The first three unseen matches include search detail; later and previously seen matches use compact summaries. 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. Returns: JSON array of matching patterns.

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

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

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

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

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

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

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.

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.

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" or "StateLock"), "vocab" for the semantic-set root, or "catalog" for exact handle-to-definition bindings. 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") -> gets canonical hash "2f3c" 2. Agent A: sema_handshake("StateLock", "2f3c") -> PROCEED 3. Agent B with drift: sema_handshake("StateLock", "9x7z") -> HALT Example workflow (whole vocabulary): 1. Agent A: sema_handshake("vocab") -> gets stub + root_scheme 2. Agent B: sema_handshake( "vocab", "<that stub>", your_scheme="<that scheme>" ) -> PROCEED / HALT

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.

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).