Metadata-Version: 2.4
Name: leviathan-hivemind-mcp
Version: 0.2.1
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<2.0.0,>=1.2.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.**
