leviathan-hivemind-mcp 0.2.0__tar.gz

leviathan_hivemind_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chaz Leland Hamm (HaChazal) — Metanoia Unlimited LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

leviathan_hivemind_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: leviathan-hivemind-mcp
+Version: 0.2.0
+Summary: HiveMind MCP — persistent swarm memory through Obsidian, powered by your preferred LLM providers, gated by GitHub Sponsors subscription.
+Author-email: "Chaz Leland Hamm (HaChazal)" <HaChazal@metanoiaunlimited.com>
+License: MIT License
+        
+        Copyright (c) 2026 Chaz Leland Hamm (HaChazal) — Metanoia Unlimited LLC
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/chazam41892-gif/hivemind-mcp
+Project-URL: Documentation, https://github.com/chazam41892-gif/hivemind-mcp#readme
+Project-URL: Issue Tracker, https://github.com/chazam41892-gif/hivemind-mcp/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# HiveMind MCP
+
+**Persistent swarm memory through Obsidian — powered by your preferred LLM providers, gated by a GitHub Sponsors subscription.**
+
+> **Created by HaChazal (Chaz Leland Hamm) — Metanoia Unlimited LLC.**
+> This is the memory layer of the LeviathanTalon swarm. Every agent, every
+> conversation, every decision lives in your Obsidian vault and is recalled
+> semantically — across any provider you already pay for.
+
+---
+
+## Why this exists
+
+AI agents forget. HiveMind MCP makes them *remember* — permanently, locally,
+in your own Obsidian vault, with semantic recall across all your preferred
+LLM providers (OpenAI, Anthropic, Gemini, Grok, DeepSeek, Mistral, Cohere,
+Cerebras, Together, OpenRouter, Braintrust) routed through the Leviathan
+Key Rotator so you never burn a single key dry.
+
+## What it does
+
+- **Persistent memory** — reads/writes `HiveMind.md` and the full vault
+  (journals, entities, decisions) through Obsidian.
+- **Semantic recall** — embeddings + cosine similarity, not just keyword grep.
+  Ask "what did we decide about the video pipeline?" and get the actual
+  decision, even if the words don't match.
+- **Provider-agnostic** — one interface, your preferred providers, key-rotated
+  and budget-capped.
+- **Subscription-gated** — a GitHub Sponsors subscription unlocks the paid
+  provider tier. Free tier works fully local (Ollama) with no API costs.
+
+## Credit
+
+This project is the work of **HaChazal (Chaz Leland Hamm)**, Principal
+Operator of the LeviathanTalon swarm, founder of **Metanoia Unlimited LLC**.
+The HiveMind vault architecture, the key rotator, the swarm memory protocol,
+and the Obsidian integration are all his design. If you use this, star the
+repo and follow HaChazal — the swarm runs on community.
+
+## Install
+
+```bash
+pip install leviathan-hivemind-mcp
+```
+
+The distribution is **`leviathan-hivemind-mcp`** on PyPI; the command stays **`hivemind-mcp`**. Zero-config launch from anywhere (auto-downloads on first use):
+
+```bash
+uvx --from leviathan-hivemind-mcp hivemind-mcp
+```
+
+Or clone and run from source:
+
+```bash
+git clone https://github.com/chazam41892-gif/leviathan-hivemind-mcp
+cd leviathan-hivemind-mcp
+pip install -e .
+```
+
+## Configure
+
+Set your vault and provider keys — or drop them into the unified
+`~/.leviathan/HiveMind/.obsidian/HiveMind.env`, which every HiveMind MCP
+server loads automatically (front-end ↔ back-end):
+
+```bash
+export HIVEMIND_VAULT=~/.leviathan/HiveMind          # your Obsidian vault
+export HIVEMIND_OWNER=1                              # owner mode: skip subscription gate
+export LEVIATHAN_KEY_OPENAI_1=sk-...                  # key rotator format
+export LEVIATHAN_KEY_ANTHROPIC_1=sk-ant-...
+export LEVIATHAN_BUDGET_OPENAI=10.0                  # optional budget caps
+```
+
+## Run
+
+```bash
+hivemind-mcp
+```
+
+Register it in your MCP client (Claude Desktop, Cursor, OpenCode, etc.):
+
+```json
+{
+  "mcpServers": {
+    "hivemind": {
+      "command": "hivemind-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_shared_memory` | Read `HiveMind.md` shared swarm state |
+| `read_soul` | Read `SOUL.md` — swarm identity + doctrine |
+| `append_to_journal` | Append a memory to an agent's journal (append-only) |
+| `recall` | Keyword or semantic recall across the vault |
+| `semantic_recall` | Embedding-based recall (needs a provider or local model) |
+| `read_entity` / `upsert_entity` | Read / layer canonical entities |
+| `read_agent_identity` | Read an agent's identity.md |
+| `read_openai_hivemind` | Read the OpenAI/Codex shared operating memory |
+| `record_openai_highlight` | Write a resumable project capsule → 4 replicas |
+| `chat` | Ask any preferred provider (gated by subscription) |
+| `list_providers` | Show configured providers + key health |
+
+## License
+
+MIT — but the *credit* is HaChazal's. Star the repo. Follow the swarm.
+
+**Built by HaChazal — Metanoia Unlimited. The swarm remembers.**

leviathan_hivemind_mcp-0.2.0/README.md

@@ -0,0 +1,113 @@
+# HiveMind MCP
+
+**Persistent swarm memory through Obsidian — powered by your preferred LLM providers, gated by a GitHub Sponsors subscription.**
+
+> **Created by HaChazal (Chaz Leland Hamm) — Metanoia Unlimited LLC.**
+> This is the memory layer of the LeviathanTalon swarm. Every agent, every
+> conversation, every decision lives in your Obsidian vault and is recalled
+> semantically — across any provider you already pay for.
+
+---
+
+## Why this exists
+
+AI agents forget. HiveMind MCP makes them *remember* — permanently, locally,
+in your own Obsidian vault, with semantic recall across all your preferred
+LLM providers (OpenAI, Anthropic, Gemini, Grok, DeepSeek, Mistral, Cohere,
+Cerebras, Together, OpenRouter, Braintrust) routed through the Leviathan
+Key Rotator so you never burn a single key dry.
+
+## What it does
+
+- **Persistent memory** — reads/writes `HiveMind.md` and the full vault
+  (journals, entities, decisions) through Obsidian.
+- **Semantic recall** — embeddings + cosine similarity, not just keyword grep.
+  Ask "what did we decide about the video pipeline?" and get the actual
+  decision, even if the words don't match.
+- **Provider-agnostic** — one interface, your preferred providers, key-rotated
+  and budget-capped.
+- **Subscription-gated** — a GitHub Sponsors subscription unlocks the paid
+  provider tier. Free tier works fully local (Ollama) with no API costs.
+
+## Credit
+
+This project is the work of **HaChazal (Chaz Leland Hamm)**, Principal
+Operator of the LeviathanTalon swarm, founder of **Metanoia Unlimited LLC**.
+The HiveMind vault architecture, the key rotator, the swarm memory protocol,
+and the Obsidian integration are all his design. If you use this, star the
+repo and follow HaChazal — the swarm runs on community.
+
+## Install
+
+```bash
+pip install leviathan-hivemind-mcp
+```
+
+The distribution is **`leviathan-hivemind-mcp`** on PyPI; the command stays **`hivemind-mcp`**. Zero-config launch from anywhere (auto-downloads on first use):
+
+```bash
+uvx --from leviathan-hivemind-mcp hivemind-mcp
+```
+
+Or clone and run from source:
+
+```bash
+git clone https://github.com/chazam41892-gif/leviathan-hivemind-mcp
+cd leviathan-hivemind-mcp
+pip install -e .
+```
+
+## Configure
+
+Set your vault and provider keys — or drop them into the unified
+`~/.leviathan/HiveMind/.obsidian/HiveMind.env`, which every HiveMind MCP
+server loads automatically (front-end ↔ back-end):
+
+```bash
+export HIVEMIND_VAULT=~/.leviathan/HiveMind          # your Obsidian vault
+export HIVEMIND_OWNER=1                              # owner mode: skip subscription gate
+export LEVIATHAN_KEY_OPENAI_1=sk-...                  # key rotator format
+export LEVIATHAN_KEY_ANTHROPIC_1=sk-ant-...
+export LEVIATHAN_BUDGET_OPENAI=10.0                  # optional budget caps
+```
+
+## Run
+
+```bash
+hivemind-mcp
+```
+
+Register it in your MCP client (Claude Desktop, Cursor, OpenCode, etc.):
+
+```json
+{
+  "mcpServers": {
+    "hivemind": {
+      "command": "hivemind-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_shared_memory` | Read `HiveMind.md` shared swarm state |
+| `read_soul` | Read `SOUL.md` — swarm identity + doctrine |
+| `append_to_journal` | Append a memory to an agent's journal (append-only) |
+| `recall` | Keyword or semantic recall across the vault |
+| `semantic_recall` | Embedding-based recall (needs a provider or local model) |
+| `read_entity` / `upsert_entity` | Read / layer canonical entities |
+| `read_agent_identity` | Read an agent's identity.md |
+| `read_openai_hivemind` | Read the OpenAI/Codex shared operating memory |
+| `record_openai_highlight` | Write a resumable project capsule → 4 replicas |
+| `chat` | Ask any preferred provider (gated by subscription) |
+| `list_providers` | Show configured providers + key health |
+
+## License
+
+MIT — but the *credit* is HaChazal's. Star the repo. Follow the swarm.
+
+**Built by HaChazal — Metanoia Unlimited. The swarm remembers.**

leviathan_hivemind_mcp-0.2.0/hivemind_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""HiveMind MCP — persistent swarm memory through Obsidian.
+
+Created by HaChazal (Chaz Leland Hamm) — Metanoia Unlimited LLC.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Chaz Leland Hamm (HaChazal)"
+__license__ = "MIT"

leviathan_hivemind_mcp-0.2.0/hivemind_mcp/_vault.py

@@ -0,0 +1,243 @@
+"""Vault — the markdown read/write engine for the HiveMind.
+
+Operates directly on the vault's markdown files per the contract in
+shared/conventions.md. Stdlib-only. Preservation Doctrine is enforced
+structurally: journals are opened in append mode, entities are layered
+(never rewritten), and nothing is ever truncated.
+"""
+from __future__ import annotations
+
+import os
+import random
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+# Allowed journal entry kinds (from .brain/config.yaml entry_kinds).
+ENTRY_KINDS = (
+    "observation", "decision", "action", "result",
+    "question", "learning", "handoff",
+)
+
+# type -> entities subdir (the canonical entity folders that exist in the vault).
+ENTITY_DIRS = {
+    "person": "people", "people": "people",
+    "project": "projects", "projects": "projects",
+    "token": "tokens", "tokens": "tokens",
+    "account": "accounts", "accounts": "accounts",
+    "client": "clients", "clients": "clients",
+    "concept": "concepts", "concepts": "concepts",
+    "media": "media", "video": "media", "image": "media",
+}
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _ulid() -> str:
+    """Sortable ULID-ish id: 10-char time + 16-char randomness, Crockford b32.
+    Good enough for vault ids (monotonic-ish, collision-resistant); no deps."""
+    t = int(time.time() * 1000)
+    ts = ""
+    for _ in range(10):
+        ts = _CROCKFORD[t & 31] + ts
+        t >>= 5
+    rnd = "".join(random.choice(_CROCKFORD) for _ in range(16))
+    return ts + rnd
+
+
+def _vault_root(root: Optional[str] = None) -> Path:
+    if root:
+        return Path(root).expanduser()
+    env = os.environ.get("HIVEMIND_VAULT")
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".leviathan" / "HiveMind"
+
+
+def _as_list(x) -> list:
+    if x is None:
+        return []
+    if isinstance(x, (list, tuple)):
+        return [str(i) for i in x]
+    return [str(x)]
+
+
+class Vault:
+    def __init__(self, root: Optional[str] = None):
+        self.root = _vault_root(root)
+        if not self.root.exists():
+            raise FileNotFoundError(f"HiveMind vault not found at {self.root}")
+
+    # ── paths ──────────────────────────────────────────────────────────
+    def _journal(self, agent: str) -> Path:
+        return self.root / "agents" / agent / "journal.md"
+
+    # ── 1. append_to_journal (APPEND-ONLY) ─────────────────────────────
+    def append_to_journal(self, agent: str, kind: str, body: str,
+                          tags=None, links=None, session: Optional[str] = None) -> dict:
+        if kind not in ENTRY_KINDS:
+            raise ValueError(f"kind {kind!r} not in {ENTRY_KINDS}")
+        agent = str(agent).strip()
+        if not agent:
+            raise ValueError("agent is required")
+        tags = _as_list(tags)
+        links = _as_list(links)
+        ts = _now()
+
+        jp = self._journal(agent)
+        jp.parent.mkdir(parents=True, exist_ok=True)
+        if not jp.exists():  # seed with frontmatter on first write
+            jp.write_text(
+                f"---\nid: {_ulid()}\ntype: journal\nagent: {agent}\n"
+                f"created: {ts}\nupdated: {ts}\ntags: [journal]\n---\n\n"
+                f"# {agent} — journal (append-only)\n",
+                encoding="utf-8",
+            )
+
+        links_md = ", ".join(f"[[{l}]]" for l in links)
+        block = (
+            f"\n## {ts} — {kind}\n"
+            f"- session: {session or ''}\n"
+            f"- tags: [{', '.join(tags)}]\n"
+            f"- links: {links_md}\n\n"
+            f"{body.rstrip()}\n"
+        )
+        with jp.open("a", encoding="utf-8") as f:  # append mode = Preservation
+            f.write(block)
+        return {"agent": agent, "kind": kind, "ts": ts, "tags": tags,
+                "links": links, "session": session, "body": body, "file": str(jp)}
+
+    # ── 2. recall ───────────────────────────────────────────────────────
+    def recall(self, query: Optional[str] = None, agent: Optional[str] = None,
+               kind: Optional[str] = None, tags=None, links=None,
+               since: Optional[str] = None, mode: str = "keyword",
+               limit: int = 50, fast: bool = False) -> list:
+        # Optional FTS accelerator (as-of-last-reindex). Falls back to the
+        # always-correct scan below if the index is missing/unavailable.
+        if fast and query and not tags and not links and not since:
+            try:
+                from .index import Index
+                rows = Index(self.root).search(query, agent=agent, kind=kind, limit=limit)
+                if rows is not None:
+                    return rows
+            except Exception:
+                pass
+        want_tags = set(_as_list(tags))
+        want_links = set(_as_list(links))
+        q = (query or "").lower().strip()
+        results = []
+
+        agents_dir = self.root / "agents"
+        agent_dirs = ([agents_dir / agent] if agent else
+                      [d for d in agents_dir.glob("*") if d.is_dir()])
+        for ad in agent_dirs:
+            jp = ad / "journal.md"
+            if not jp.exists():
+                continue
+            who = ad.name
+            for e in self._parse_journal(jp.read_text(encoding="utf-8", errors="replace")):
+                e["agent"] = who
+                e["file"] = str(jp)
+                if kind and e["kind"] != kind:
+                    continue
+                if since and e["ts"] < since:
+                    continue
+                if want_tags and not want_tags & set(e["tags"]):
+                    continue
+                if want_links and not want_links & set(e["links"]):
+                    continue
+                if q and q not in e["body"].lower() and not any(q in t.lower() for t in e["tags"]):
+                    continue
+                results.append(e)
+
+        results.sort(key=lambda e: e["ts"], reverse=True)
+        return results[:limit]
+
+    @staticmethod
+    def _parse_journal(text: str) -> list:
+        """Split a journal.md into entry dicts on the `## <ts> — <kind>` headers."""
+        out = []
+        header = re.compile(r"^##\s+(\S+)\s+—\s+(\w+)\s*$", re.M)
+        marks = list(header.finditer(text))
+        for i, m in enumerate(marks):
+            ts, kind = m.group(1), m.group(2)
+            seg = text[m.end(): marks[i + 1].start() if i + 1 < len(marks) else len(text)]
+            tags, links, session = [], [], ""
+            body_lines = []
+            for line in seg.splitlines():
+                ls = line.strip()
+                if ls.startswith("- session:"):
+                    session = ls[len("- session:"):].strip()
+                elif ls.startswith("- tags:"):
+                    inner = ls[ls.find("[") + 1: ls.rfind("]")] if "[" in ls else ""
+                    tags = [t.strip() for t in inner.split(",") if t.strip()]
+                elif ls.startswith("- links:"):
+                    links = re.findall(r"\[\[([^\]|]+)", ls)
+                else:
+                    body_lines.append(line)
+            out.append({"ts": ts, "kind": kind, "tags": tags, "links": links,
+                        "session": session, "body": "\n".join(body_lines).strip()})
+        return out
+
+    # ── 3. read_entity ──────────────────────────────────────────────────
+    def read_entity(self, name: str) -> Optional[dict]:
+        ent = self.root / "entities"
+        for f in ent.rglob(f"{name}.md"):  # first match wins
+            return {"name": name, "file": str(f), "text": f.read_text(encoding="utf-8", errors="replace")}
+        return None
+
+    # ── 4. upsert_entity (CREATE or LAYER — never overwrite) ────────────
+    def upsert_entity(self, name: str, body: str, type: str = "concept",
+                      merge: bool = True) -> dict:
+        existing = self.read_entity(name)
+        ts = _now()
+        if existing:
+            if not merge:
+                raise FileExistsError(f"entity {name!r} exists and merge=False")
+            with Path(existing["file"]).open("a", encoding="utf-8") as f:  # LAYER
+                f.write(f"\n\n## update {ts}\n\n{body.rstrip()}\n")
+            return {**existing, "layered": True, "ts": ts}
+        sub = ENTITY_DIRS.get(type.lower(), "concepts")
+        d = self.root / "entities" / sub
+        d.mkdir(parents=True, exist_ok=True)
+        fp = d / f"{name}.md"
+        fp.write_text(
+            f"---\nid: {_ulid()}\ntype: entity\ncreated: {ts}\nupdated: {ts}\n"
+            f"tags: [{type}]\n---\n\n# {name}\n\n{body.rstrip()}\n",
+            encoding="utf-8",
+        )
+        return {"name": name, "file": str(fp), "created": True, "ts": ts}
+
+
+# ── module-level convenience wrappers (the tool surface) ────────────────
+_default: Optional[Vault] = None
+
+
+def _v() -> Vault:
+    global _default
+    if _default is None:
+        _default = Vault()
+    return _default
+
+
+def append_to_journal(agent, kind, body, tags=None, links=None, session=None):
+    return _v().append_to_journal(agent, kind, body, tags, links, session)
+
+
+def recall(query=None, agent=None, kind=None, tags=None, links=None,
+           since=None, mode="keyword", limit=50):
+    return _v().recall(query, agent, kind, tags, links, since, mode, limit)
+
+
+def read_entity(name):
+    return _v().read_entity(name)
+
+
+def upsert_entity(name, body, type="concept", merge=True):
+    return _v().upsert_entity(name, body, type, merge)

leviathan_hivemind_mcp-0.2.0/hivemind_mcp/env_bridge.py

@@ -0,0 +1,84 @@
+"""HiveMind.env bridge — the front-end ↔ back-end credential layer.
+
+Loads the operator's consolidated HiveMind.env (default:
+``~/.leviathan/HiveMind/.obsidian/HiveMind.env``, override with
+``HIVEMIND_ENV_FILE``) into ``os.environ`` for any AI client that spawns
+this MCP server. Existing process environment ALWAYS wins — this only
+fills gaps, so an app that already exports a key is never overridden.
+
+Mapping rules:
+  * ``KEY="value"`` / ``KEY=value`` / tab-indented lines are parsed; quotes
+    and trailing ``\\r`` are stripped; ``#`` comments and blanks skipped.
+  * Plural pool → singular export: ``FOO_API_KEYS="k1, k2"`` also exports
+    ``FOO_API_KEY`` = first key (matching the provider adapters' env
+    fallback names) when the singular is not already set.
+  * Alias: ``XAI_API_KEYS``/``XAI_API_KEY`` also fill ``GROK_API_KEY``.
+
+Stdlib-only; never raises; returns the number of new names exported.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_ENV_FILE = Path.home() / ".leviathan" / "HiveMind" / ".obsidian" / "HiveMind.env"
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    pairs: dict[str, str] = {}
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return pairs
+    for raw in text.splitlines():
+        line = raw.strip().lstrip("\ufeff")
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip("\r")
+        if not key or not value:
+            continue
+        if value[:1] in ('"', "'") and value[-1:] == value[:1]:
+            value = value[1:-1]
+        if not value:
+            continue
+        pairs.setdefault(key, value)
+    return pairs
+
+
+def load_env_file(path: Optional[Path] = None) -> int:
+    """Export HiveMind.env into os.environ (fill-gaps only). Returns count."""
+    env_file = Path(path) if path else Path(os.environ.get("HIVEMIND_ENV_FILE", DEFAULT_ENV_FILE))
+    pairs = _parse_env_file(env_file)
+    if not pairs:
+        return 0
+
+    exported = 0
+    for key, value in pairs.items():
+        if key not in os.environ:
+            os.environ[key] = value
+            exported += 1
+
+    # Plural pool → singular provider-key export.
+    for key, value in pairs.items():
+        if key.endswith("_API_KEYS"):
+            singular = key[:-1]  # FOO_API_KEYS -> FOO_API_KEY
+            if not os.environ.get(singular):
+                first = value.split(",")[0].strip()
+                if first:
+                    os.environ[singular] = first
+                    exported += 1
+
+    # xAI → Grok alias (the provider registry calls it "grok").
+    for src, dst in (("XAI_API_KEY", "GROK_API_KEY"),
+                     ("XAI_API_KEYS", "GROK_API_KEYS")):
+        if os.environ.get(src) and not os.environ.get(dst):
+            os.environ[dst] = os.environ[src]
+            exported += 1
+
+    return exported