hypermind 1.6.3__tar.gz → 1.6.4__tar.gz

{hypermind-1.6.3 → hypermind-1.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 1.6.3
+Version: 1.6.4
 Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
 Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
 Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs
@@ -331,6 +331,29 @@ Every `hmctl <cmd> --help` lists its flags. Full engine reference: [docs/simulat
 
 ---
 
+## Configuration
+
+All configuration is via environment variables.  Set them in `~/.hypermind/env` (one `KEY=VALUE` per line) — the CLI and MCP server load this file automatically.
+
+```bash
+OPENAI_API_KEY=sk-…          # LLM key (OpenAI / OpenRouter / Ollama / …)
+HYPERMIND_LLM_MODEL=gpt-4o   # model name (required for OpenRouter)
+RELATA_URL=http://localhost:5432  # durable knowledge ledger
+RELATA_BEARER_TOKEN=…        # auth token for managed RelataDB instances
+HYPERMIND_DB=~/.hypermind/cache.db  # local SQLite fallback
+```
+
+See **[docs/configuration.md](docs/configuration.md)** for the full reference of every `HYPERMIND_*` variable, its default, and what it controls.  Quick commands:
+
+```bash
+hmctl env-vars    # live table of all tuning knobs
+hmctl doctor      # health-check (reports SSE port, webhook, secret status)
+hmctl config      # interactive wizard
+hmctl status      # shows which features are active
+```
+
+---
+
 ## Status
 
 **Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.6.0**.

{hypermind-1.6.3 → hypermind-1.6.4}/README.md

@@ -259,6 +259,29 @@ Every `hmctl <cmd> --help` lists its flags. Full engine reference: [docs/simulat
 
 ---
 
+## Configuration
+
+All configuration is via environment variables.  Set them in `~/.hypermind/env` (one `KEY=VALUE` per line) — the CLI and MCP server load this file automatically.
+
+```bash
+OPENAI_API_KEY=sk-…          # LLM key (OpenAI / OpenRouter / Ollama / …)
+HYPERMIND_LLM_MODEL=gpt-4o   # model name (required for OpenRouter)
+RELATA_URL=http://localhost:5432  # durable knowledge ledger
+RELATA_BEARER_TOKEN=…        # auth token for managed RelataDB instances
+HYPERMIND_DB=~/.hypermind/cache.db  # local SQLite fallback
+```
+
+See **[docs/configuration.md](docs/configuration.md)** for the full reference of every `HYPERMIND_*` variable, its default, and what it controls.  Quick commands:
+
+```bash
+hmctl env-vars    # live table of all tuning knobs
+hmctl doctor      # health-check (reports SSE port, webhook, secret status)
+hmctl config      # interactive wizard
+hmctl status      # shows which features are active
+```
+
+---
+
 ## Status
 
 **Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.6.0**.

hypermind-1.6.4/docs/configuration.md

@@ -0,0 +1,149 @@
+# HyperMind Configuration Reference
+
+All configuration is supplied via environment variables.  The recommended
+way to set them permanently is to add `KEY=VALUE` lines (one per line) to
+`~/.hypermind/env`.  The MCP server (`hmctl mcp serve`) and the CLI load
+this file automatically on startup.
+
+```bash
+# Example ~/.hypermind/env
+OPENAI_API_KEY=sk-…
+HYPERMIND_LLM_MODEL=gpt-4o
+RELATA_URL=http://localhost:5432
+HYPERMIND_DB=~/.hypermind/cache.db
+```
+
+Run `hmctl env-vars` at any time to see the live effective values of every
+tuning knob in a formatted table.
+
+---
+
+## LLM / Responder
+
+| Variable | Default | Description |
+|---|---|---|
+| `OPENAI_API_KEY` | *(none)* | API key for any OpenAI-compatible provider (OpenAI, OpenRouter, vLLM, MiniMax, …). Required for `hm_ask` and research to call a real LLM. |
+| `OPENAI_BASE_URL` | *(none)* | Override the OpenAI base URL; use for OpenRouter (`https://openrouter.ai/api/v1`), local Ollama (`http://localhost:11434/v1`), or any OpenAI-compatible proxy. |
+| `HYPERMIND_LLM_MODEL` | *(auto)* | Model name passed to the LLM backend (e.g. `gpt-4o`, `llama3.1`, `MiniMax-M3`). Required when using OpenRouter. Set to `auto` for automatic Ollama model detection. |
+| `ANTHROPIC_API_KEY` | *(none)* | API key for direct Anthropic API calls. Used by the `anthropic` responder backend. |
+| `HYPERMIND_LLM` | *(auto)* | Force a specific responder backend: `openai`, `anthropic`, or `ollama`. When unset the SDK auto-detects from available keys and base URL. |
+| `HYPERMIND_MAX_REASONING_CHARS` | `6000` | Maximum characters of intermediate reasoning retained per responder call (capped at 50 000). Controls context window usage. Source: `src/hypermind/responders/structured.py`. |
+| `HYPERMIND_TOOL_RESULT_LLM_CHARS` | `4000` | Maximum characters of tool output fed back to the LLM per tool call. Larger values improve grounding; smaller values save tokens. Source: `src/hypermind/responders/tools.py`. |
+| `HYPERMIND_CONTEXT_FINDING_CHARS` | `900` | Maximum characters of each finding included in the LLM context during an OrgSim research cycle. Source: `src/hypermind/orgs/sim.py`. |
+
+---
+
+## Storage
+
+| Variable | Default | Description |
+|---|---|---|
+| `RELATA_URL` | *(none)* | HTTP URL of a running RelataDB instance (e.g. `http://localhost:5432`). When set, claims are persisted to the durable ledger and `hm_related` can use graph traversal and BM25 search. Without it, storage falls back to in-process SQLite (see `HYPERMIND_DB`). |
+| `RELATA_BEARER_TOKEN` | *(none)* | Bearer token for authenticating requests to RelataDB. Also accepted as `RELATA_TOKEN`. Required when the RelataDB instance is protected by token auth (e.g. managed cloud deployments). Source: `src/hypermind/integrations/client.py`. |
+| `RELATA_TOKEN` | *(none)* | Alias for `RELATA_BEARER_TOKEN` (checked as fallback). |
+| `HYPERMIND_DB` | `~/.hypermind/cache.db` | Path to the local SQLite cache database. Auto-activated when `RELATA_URL` is not set. Persists claims, agent state, and hypothesis records across restarts. |
+| `HYPERMIND_STORAGE` | *(auto)* | Force a storage backend: `relata` or `sqlite`. When unset the SDK selects `relata` if `RELATA_URL` is present, otherwise `sqlite`. Source: `src/hypermind/storage/__init__.py`. |
+| `HYPERMIND_NAMESPACE` | *(sandbox default)* | Default namespace ID used when creating the storage backend. Source: `src/hypermind/storage/__init__.py`. |
+| `HYPERMIND_KERNEL_STORE_MAX_FILE_SIZE_MB` | `50` | Maximum size in megabytes for each per-persona KernelStore JSON file under `HYPERMIND_HOME/swarm_memory/`. When a save would exceed this limit, the least-observed topics are pruned first. Source: `src/hypermind/knowledge/kernel_store.py`. |
+
+---
+
+## Networking / Transport
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMIND_SSE_PORT` | `0` | Port for the optional SSE (Server-Sent Events) event stream in `hmctl mcp serve`. `0` disables SSE. When set, browse `http://127.0.0.1:<port>` for a live loop dashboard. `hmctl doctor` checks that this port is bindable when set. Source: `src/hypermind/integrations/mcp_tools.py`. |
+| `HYPERMIND_WEBHOOK_PORT` | `0` | Port for the inbound webhook HTTP server. `0` disables it. When active, the server accepts signed `POST /webhook/publish`, `/webhook/loop/wake`, and `/webhook/ingest` requests. Source: `src/hypermind/integrations/mcp_tools.py`. |
+| `HYPERMIND_WEBHOOK_SECRET` | *(none)* | HMAC-SHA256 shared secret for verifying the `X-HM-Signature` header on inbound webhook requests. When empty, the webhook server accepts unsigned requests (development only). `hmctl doctor` masks this value when reporting it. Source: `src/hypermind/integrations/mcp_tools.py`. |
+| `HYPERMIND_PEERS` | *(none)* | Comma-separated list of TCP peer addresses for multi-node federation (e.g. `192.168.1.10:7100,192.168.1.11:7100`). Source: `src/hypermind/agent.py`. |
+| `HYPERMIND_BUS_CREDIT_DEFAULT` | `1024` | Per-peer gossip bus credit in bytes. Limits message backlog toward a single peer. Source: `src/hypermind/transport/bus.py`. |
+
+---
+
+## Notifications
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMIND_NOTIFY_URL` | *(none)* | HTTP endpoint that receives POST notifications on loop events (cycle start/end, contradiction detected, etc.). Source: `src/hypermind/integrations/notifier.py`. |
+| `HYPERMIND_NOTIFY_FILE` | *(none)* | File path that receives newline-delimited JSON notifications for loop events. Useful for local monitoring without an HTTP server. Source: `src/hypermind/integrations/notifier.py`. |
+
+---
+
+## Observability
+
+| Variable | Default | Description |
+|---|---|---|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | *(none)* | OTLP endpoint for shipping spans and metrics to Jaeger, Grafana Tempo, Honeycomb, Datadog, or any OTLP-compatible backend (e.g. `http://localhost:4317`). Without this, the audit trail is local-only. |
+
+---
+
+## Autonomous Loop & Population
+
+| Variable | Default | Unit | Description |
+|---|---|---|---|
+| `HYPERMIND_LOOP_EVOLVE_EVERY` | `10` | cycles | Cycles between population evolution ticks in the autonomous loop. Read at use time (no restart required). Takes precedence over the legacy `HYPERMIND_EVOLVE_EVERY` alias. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_EVOLVE_EVERY` | `10` | cycles | Legacy alias for `HYPERMIND_LOOP_EVOLVE_EVERY`. Prefer the `HYPERMIND_LOOP_*` form. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_LOOP_CLUSTER_MIN_CLAIMS` | `5` | claims | Minimum number of claims before a sub-topic loop is spawned during clustering. Read at use time (no restart required). Takes precedence over `HYPERMIND_LOOP_CLUSTER_EVERY` and the legacy `HYPERMIND_CLUSTER_MIN_CLAIMS` alias. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_LOOP_CLUSTER_EVERY` | `5` | claims | Alias for `HYPERMIND_LOOP_CLUSTER_MIN_CLAIMS`. Prefer the `HYPERMIND_LOOP_CLUSTER_MIN_CLAIMS` form. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_CLUSTER_MIN_CLAIMS` | `5` | claims | Legacy alias for `HYPERMIND_LOOP_CLUSTER_MIN_CLAIMS`. Prefer the `HYPERMIND_LOOP_*` form. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_MAX_POPULATION` | `20` | tasks | Maximum concurrent loop tasks across all topics. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_MAX_CONCURRENT_TOPICS` | `50` | topics | Hard cap on the total number of concurrent topic loops. Source: `src/hypermind/integrations/loop.py`. |
+| `HYPERMIND_CLUSTER_MAX_TOPICS` | `10` | topics | Maximum sub-topics produced by a single clustering pass. Source: `src/hypermind/integrations/topic_clustering.py`. |
+| `HYPERMIND_CHECKPOINT_MAX_CLAIMS` | `1000` | claims | Maximum claims written into a single population checkpoint file. Source: `src/hypermind/integrations/population.py`. |
+| `HYPERMIND_POPULATION` | `default` | string | Population name written during an evolution tick (used by the loop and MCP server). Source: `src/hypermind/integrations/loop.py`. |
+
+---
+
+## Freshness / TTLs
+
+| Variable | Default | Unit | Description |
+|---|---|---|---|
+| `HYPERMIND_TTL_MEDICAL` | `180` | days | Freshness TTL for claims with `domain='medical'`. Claims older than this are flagged as stale. Source: `src/hypermind/integrations/freshness.py`. |
+| `HYPERMIND_TTL_DEFAULT` | `365` | days | Freshness TTL for all claims without a specific domain TTL. Source: `src/hypermind/integrations/freshness.py`. |
+| `HYPERMIND_TTL_TECHNICAL` | `730` | days | Freshness TTL for claims with `domain='technical'`. Source: `src/hypermind/integrations/freshness.py`. |
+
+---
+
+## Research Engine
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMIND_JOB_TTL_DAYS` | `7` | Number of days before a completed research job record is eligible for eviction from persistent storage. Source: `src/hypermind/integrations/research.py`. |
+| `HYPERMIND_JOB_TTL_S` | `3600` | In-memory TTL in seconds for active research job handles. Source: `src/hypermind/integrations/research.py`. |
+| `HYPERMIND_INGEST_ROOT` | *(cwd)* | Root directory for the `hm_ingest_directory` MCP tool. Defaults to the current working directory. Source: `src/hypermind/integrations/mcp_tools.py`. |
+| `HYPERMIND_MCP_CONFIG` | *(auto)* | Explicit path to the MCP tool configuration JSON. When unset the SDK searches standard locations. Source: `src/hypermind/orgs/mcp_config.py`. |
+
+---
+
+## Security / Crypto
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMIND_LEGACY_QUORUM` | `0` | Set to `1` to disable the strict Sybil-resistant quorum check in the dispute FSM (legacy compatibility only). Do not set in production. Source: `src/hypermind/dispute.py`. |
+| `HYPERMIND_ANCHOR_KEY` | *(none)* | Private key for on-chain anchoring of simulation commitments. Source: `src/hypermind/simlab/backends/anchor.py`. |
+
+---
+
+## Paths
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMIND_HOME` | `~/.hypermind` | Root directory for HyperMind state: populations, loops, simulation runs, the env file, and the identity seed. Source: `src/hypermind/agent.py`, `src/hypermind/simlab/registry.py`, `src/hypermind/knowledge/kernel_store.py`. |
+| `HYPERMIND_KERNEL_STORE_MAX_TOPICS` | `1000` | Maximum number of topics tracked in the in-process kernel store before the oldest are evicted. Source: `src/hypermind/knowledge/kernel_store.py`. |
+
+---
+
+## SDK / MCP Behaviour
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMIND_NO_ENV_FILE` | `0` | Set to `1` to skip loading `~/.hypermind/env` on startup (useful in container environments where all vars are injected directly). Source: `src/hypermind/integrations/mcp_tools.py`. |
+
+---
+
+## See also
+
+- `hmctl env-vars` — print a live table of all tuning knobs with current values
+- `hmctl doctor` — health-check that reports `HYPERMIND_SSE_PORT`, `HYPERMIND_WEBHOOK_PORT`, and `HYPERMIND_WEBHOOK_SECRET` status
+- `hmctl config` — interactive wizard for setting the most common variables
+- `hmctl status` — shows which optional features (LLM, RelataDB, OTEL, SQLite) are active
+- [docs/integrations.md](integrations.md) — integration guide and advanced tuning knobs

{hypermind-1.6.3 → hypermind-1.6.4}/examples/01_hello_world.py

@@ -17,6 +17,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.01_hello_world
 """
 
+# Run: python -m examples.01_hello_world
+
 from __future__ import annotations
 
 import asyncio
@@ -63,3 +65,4 @@ async def main() -> None:
 
 if __name__ == "__main__":
     asyncio.run(main())
+

{hypermind-1.6.3 → hypermind-1.6.4}/examples/02_two_agents_dispute.py

@@ -21,6 +21,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.02_two_agents_dispute
 """
 
+# Run: python -m examples.02_two_agents_dispute
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/03_consult_panel.py

@@ -20,6 +20,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.03_consult_panel
 """
 
+# Run: python -m examples.03_consult_panel
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/04_oracle_resolve.py

@@ -25,6 +25,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.04_oracle_resolve
 """
 
+# Run: python -m examples.04_oracle_resolve
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/05_consult_to_synthesis.py

@@ -35,6 +35,8 @@ learned" — the headline federated-learning property.
 Run with:    python -m examples.05_consult_to_synthesis
 """
 
+# Run: python -m examples.05_consult_to_synthesis
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/06_hybrid_pq.py

@@ -34,6 +34,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.06_hybrid_pq
 """
 
+# Run: python -m examples.06_hybrid_pq
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/07_frost_threshold.py

@@ -29,6 +29,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.07_frost_threshold
 """
 
+# Run: python -m examples.07_frost_threshold
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/08_ramp_and_diagnostics.py

@@ -29,6 +29,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.08_ramp_and_diagnostics
 """
 
+# Run: python -m examples.08_ramp_and_diagnostics
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/09_audit_export_chain.py

@@ -28,6 +28,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.09_audit_export_chain
 """
 
+# Run: python -m examples.09_audit_export_chain
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/10_autonomous_agent.py

@@ -13,6 +13,8 @@ Run:
     .venv/bin/python -m examples.10_autonomous_agent
 """
 
+# Run: python -m examples.10_autonomous_agent
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/11_swarm_deliberation.py

@@ -14,6 +14,8 @@ Run:
     .venv/bin/python -m examples.11_swarm_deliberation
 """
 
+# Run: python -m examples.11_swarm_deliberation
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/12_swarm_iq_scorecard.py

@@ -13,6 +13,8 @@ Run:
     .venv/bin/python -m examples.12_swarm_iq_scorecard
 """
 
+# Run: python -m examples.12_swarm_iq_scorecard
+
 from __future__ import annotations
 
 import json

{hypermind-1.6.3 → hypermind-1.6.4}/examples/13_role_specialisation.py

@@ -9,6 +9,8 @@ Run:
     .venv/bin/python -m examples.13_role_specialisation
 """
 
+# Run: python -m examples.13_role_specialisation
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/14_active_learning_loop.py

@@ -11,6 +11,8 @@ Run:
     .venv/bin/python -m examples.14_active_learning_loop
 """
 
+# Run: python -m examples.14_active_learning_loop
+
 from __future__ import annotations
 
 from hypermind.knowledge.swarm_memory import (

{hypermind-1.6.3 → hypermind-1.6.4}/examples/16_wire_message.py

@@ -35,6 +35,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.16_wire_message
 """
 
+# Run: python -m examples.16_wire_message
+
 from __future__ import annotations
 
 import cbor2

{hypermind-1.6.3 → hypermind-1.6.4}/examples/17_tool_delegation.py

@@ -45,6 +45,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.17_tool_delegation
 """
 
+# Run: python -m examples.17_tool_delegation
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/18_custom_responder.py

@@ -34,6 +34,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.18_custom_responder
 """
 
+# Run: python -m examples.18_custom_responder
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/19_governance.py

@@ -29,6 +29,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.19_governance
 """
 
+# Run: python -m examples.19_governance
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/20_conformance_check.py

@@ -29,6 +29,8 @@ CHECKS
 Run with:    python -m examples.20_conformance_check
 """
 
+# Run: python -m examples.20_conformance_check
+
 from __future__ import annotations
 
 import hashlib

{hypermind-1.6.3 → hypermind-1.6.4}/examples/21_revocation.py

@@ -24,6 +24,8 @@ Importantly, statements signed *before* the revocation point remain
 valid — historical-claim immutability. A revocation is forward-only.
 """
 
+# Run: python -m examples.21_revocation
+
 from __future__ import annotations
 
 from hypermind.capability import CapToken, Caveat

{hypermind-1.6.3 → hypermind-1.6.4}/examples/22_agent_card.py

@@ -28,6 +28,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.22_agent_card
 """
 
+# Run: python -m examples.22_agent_card
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/23_task_delegation.py

@@ -27,6 +27,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.23_task_delegation
 """
 
+# Run: python -m examples.23_task_delegation
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/24_mcp_tool_call.py

@@ -29,6 +29,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.24_mcp_tool_call
 """
 
+# Run: python -m examples.24_mcp_tool_call
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/25_swarm_trace.py

@@ -28,6 +28,8 @@ WHAT THIS EXAMPLE SHOWS
 Run with:    python -m examples.25_swarm_trace
 """
 
+# Run: python -m examples.25_swarm_trace
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/26_submit_goal_and_goal_handle.py

@@ -18,6 +18,8 @@ Run:
     .venv/bin/python -m examples.26_submit_goal_and_goal_handle
 """
 
+# Run: python -m examples.26_submit_goal_and_goal_handle
+
 from __future__ import annotations
 
 import asyncio

{hypermind-1.6.3 → hypermind-1.6.4}/examples/27_safety_policies.py

@@ -16,6 +16,8 @@ Run::
     .venv/bin/python -m examples.27_safety_policies
 """
 
+# Run: python -m examples.27_safety_policies
+
 from __future__ import annotations
 
 import asyncio

hypermind-1.6.4/examples/28_relata_connection.py

@@ -0,0 +1,90 @@
+"""Example 28 — Connect to a real Relata backend.
+
+THE STORY
+─────────
+You've been running HyperMind in sandbox mode (in-memory, no persistence).
+Now you want durable storage: claims survive restarts, audit logs are
+tamper-evident across sessions, and other nodes can reach your namespace.
+
+Relata is the reference persistence layer for HyperMind. This example
+shows how to:
+  1. Point an agent at a running Relata instance via env vars
+  2. Publish a claim that lands in the real ledger
+  3. Retrieve it back by kid, confirming round-trip persistence
+
+PREREQUISITES
+  export RELATA_URL=http://localhost:9090
+  export RELATA_BEARER_TOKEN=<your-token>
+
+  (Start a local Relata dev instance: see deploy/relata-serve.sh)
+
+WHAT THIS EXAMPLE SHOWS
+───────────────────────
+  1. Reading RELATA_URL / RELATA_BEARER_TOKEN from the environment
+  2. Building a HyperMindAgent that uses a RelataBackend
+  3. publish_claim → returns a kid
+  4. retrieve(kid) → confirms durable round-trip
+"""
+
+# Run: python -m examples.28_relata_connection
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from hypermind import HyperMindAgent, Uncertainty
+
+
+async def main() -> None:
+    relata_url = os.environ.get("RELATA_URL", "")
+    relata_token = os.environ.get("RELATA_BEARER_TOKEN", "")
+
+    if not relata_url:
+        print("RELATA_URL not set — running in offline sandbox mode for demonstration.")
+        print("Set RELATA_URL and RELATA_BEARER_TOKEN to connect to a real Relata instance.\n")
+        relata_url = None
+        relata_token = None
+
+    print("Step 1 — Build an agent.")
+    if relata_url:
+        print(f"  Connecting to Relata at {relata_url}")
+        from hypermind.storage import RelataBackend
+        backend = RelataBackend(url=relata_url, token=relata_token)
+        async with HyperMindAgent.sandbox(room="threat-intel", backend=backend) as alice:
+            await _demo(alice)
+    else:
+        async with HyperMindAgent.sandbox(room="threat-intel") as alice:
+            await _demo(alice)
+
+
+async def _demo(alice: HyperMindAgent) -> None:
+    print(f"  alice did:key = {alice.keypair.did_key}\n")
+
+    print("Step 2 — Publish a claim.")
+    kid = await alice.publish_claim(
+        {"indicator": "198.51.100.42", "verdict": "malicious", "confidence": 0.91},
+        claim_type="threat_intel",
+        uncertainty=Uncertainty.beta(9, 1),
+        topic="threat-intel",
+    )
+    print(f"  ✓ sealed kid = {kid.hex()[:32]}…\n")
+
+    print("Step 3 — Retrieve it back via audit_export.")
+    records = [frame async for frame in alice.audit_export()]
+    found = any(kid in frame for frame in records)
+    print(f"  ✓ found in ledger = {found}")
+    print(f"  ✓ frames returned = {len(records)}")
+    print()
+
+    print("Round-trip persistence confirmed.")
+    print()
+    print("WHAT'S NEXT")
+    print("───────────")
+    print("  • Set RELATA_URL to a real instance and re-run")
+    print("  • See deploy/relata-serve.sh to start a local Relata")
+    print("  • See examples/org_university.py for a full OrgSim with Relata")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())