HiveMind Python SDK

Persistent memory and a working-context compiler for your agent, in three lines inside your own loop. Your model, your key — HiveMind never calls an LLM.

pip install hivemind-sdk

Python ≥ 3.10, zero dependencies. The import name is hivemind. Docs: https://hivemind.militant.ai/docs

from hivemind import HiveMind

mind = HiveMind(base_url="...", api_key="...", tenant_id="...")
session = mind.session(budget_total=8192)

result = session.turn(user_input)       # store -> recall -> compile
reply = call_your_llm(result.messages)  # your model, your key
session.record(reply)                   # completes the exchange

What one turn() does

1. Stores the user message (receipted).
2. Semantically recalls relevant memories and past conversation.
3. Compiles local history + recalled records + active holds + your operator briefing into a token-budgeted bundle.

result.messages is the entire prompt payload — send it as-is, splice nothing in. result.bundle["decisions"] explains every admission under the budget; result.receipt is the audit record. Empty recall on a young tenant is normal, not an error.

session.record(reply) stores your model's reply as the other half of the exchange, so the next turn — and every future session — remembers it.

Beyond the loop

• mind.remember(content, metadata) — deliberately store a durable lesson, decision, fact, or outcome.
• mind.recall(query) / mind.recall_filtered(query, metadata) — explicit recall, [] when nothing matches.
• session.hold_set(key, content) / hold_clear(key) — pin operational state ("stop-order", "API is down") into every compile until cleared.
• mind.receipts(session_id=...) — the audit trail: what ran, what it consumed, what it produced, with lineage.
• mind.delete_by_metadata(metadata) — destructive, audited deletion.
• mind.client — the raw HTTP client for anything not wrapped.

Configuration

Constructor arguments override environment:

Examples

• examples/quickstart.py — the full loop with no LLM key needed.
• examples/chat_loop.py — a real chat with any OpenAI-compatible model.

Development note (this repo)

The import name hivemind collides with the service package at the repo root, so run SDK tests as their own invocation:

python -m pytest sdk/python/tests