Hivemind API

Collective memory layer as a service. Drop anonymous, shared insights into any AI product with two API calls.

What It Does

Hivemind API gives any AI chatbot, assistant, or product access to a growing pool of anonymized insights contributed by real users across the network. When someone has a useful conversation, they can contribute the key takeaway. When someone else asks something similar later, the API surfaces that insight — without revealing who contributed it.

Two endpoints. That's the whole integration.

How It Works

1. Contribute — after a useful conversation, call /v1/memory/contribute with the conversation array. The API extracts the core insight, vectorizes it, and stores it in the shared pool.
2. Retrieve — before your AI responds to a user, call /v1/memory/retrieve with the user's message. The API runs hybrid search (vector similarity + keyword matching) and returns the most relevant insights from the pool.
3. Inject — take the returned insights and inject them into your AI's system prompt as additional context. Your AI naturally references them when relevant.

Setup

1. Get an API key

Contact David Aluu via email @davidaluu1 to get access. You'll receive an API key in the format sk_hm_.... Store it securely, it is shown only once.

2. Make your first request

No installation needed. Just make HTTP requests to the API from any language or framework you're already using.

API Reference

All endpoints require an API key in the Authorization header:

Authorization: Bearer sk_hm_your_key_here

GET /v1/health

Health check. No authentication required.

Response:

{
  "status": "ok",
  "service": "Hivemind API",
  "version": "1.0.0"
}

POST /v1/memory/retrieve

Retrieves relevant insights from the pool for a given user message. Run this before your AI generates a response, then inject the results into your system prompt.

Request body:

{
  "message": "why does my Next.js app lose state on refresh?",
  "pool": "both"
}

Response:

{
  "insights": [
    {
      "id": "8435c8ec34ac4d4ebe3b906adf9d65ae",
      "summary": "Next.js wipes client side state on every page reload — the fix is persisting it to localStorage since React state resets on navigation.",
      "source": "global",
      "similarity": 0.8412,
      "rank": null
    }
  ]
}

Example — injecting into your system prompt:

insights = response["insights"]

if insights:
    context = "\n".join(f"- {i['summary']}" for i in insights)
    system_prompt += f"\n\nRelevant insights from past conversations:\n{context}\n\nOnly reference these if they genuinely add value. Never attribute them to a specific person."

POST /v1/memory/contribute

Extracts the core insight from a conversation and stores it in the pool. Call this after a conversation you want to contribute — either automatically or when a user opts in.

Request body:

{
  "conversation": [
    { "role": "user",      "content": "Why does my Next.js app lose state on page refresh?" },
    { "role": "assistant", "content": "React state is client side only and resets on every full page reload. To persist it across refreshes, store it in localStorage or sessionStorage and rehydrate on mount." },
    { "role": "user",      "content": "That worked, localStorage was the fix." }
  ],
  "pool": "global"
}

Response — success:

{
  "success": true,
  "summary": "Next.js wipes client side state on every page reload — the fix is persisting it to localStorage since React state resets on navigation."
}

Response — no insight found:

{
  "success": false,
  "reason": "no_insight",
  "message": "No clear insight found in this conversation."
}

This happens when the conversation is too shallow, purely small talk, or doesn't contain a real takeaway worth storing.

GET /v1/memory/stats

Returns insight counts for the authenticated namespace.

Response:

{
  "own_contributions": 142,
  "global_pool_size": 8731
}

Pool Modes

For /v1/memory/contribute, "own" stores the insight privately (only your namespace can retrieve it), while "global" adds it to the shared pool for everyone.

Tiers

Rate limiting is not yet enforced in the current version — tiers are recorded for future use.

Error Responses

All errors follow this format:

{
  "detail": "Error message here."
}

Quick Integration Example (Python)

import httpx

HIVEMIND_API = "https://hivemind-infrastructure.onrender.com"
API_KEY      = "sk_hm_your_key_here"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Before your AI responds — retrieve relevant insights
retrieve_res = httpx.post(
    f"{HIVEMIND_API}/v1/memory/retrieve",
    headers=headers,
    json={"message": user_message, "pool": "both"}
)
insights = retrieve_res.json()["insights"]

# Build system prompt with injected insights
system_prompt = "You are a helpful assistant."
if insights:
    context = "\n".join(f"- {i['summary']}" for i in insights)
    system_prompt += f"\n\nRelevant insights from past conversations:\n{context}"

# Call your AI with the enriched system prompt
# ... your OpenAI / Anthropic call here ...

# After a useful exchange — contribute the insight
httpx.post(
    f"{HIVEMIND_API}/v1/memory/contribute",
    headers=headers,
    json={
        "conversation": conversation_history,
        "pool": "global"
    }
)

Quick Integration Example (JavaScript)

const HIVEMIND_API = 'https://hivemind-infrastructure.onrender.com';
const API_KEY      = 'sk_hm_your_key_here';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// Retrieve insights before AI responds
const retrieveRes = await fetch(`${HIVEMIND_API}/v1/memory/retrieve`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ message: userMessage, pool: 'both' }),
});
const { insights } = await retrieveRes.json();

// Contribute after a useful exchange
await fetch(`${HIVEMIND_API}/v1/memory/contribute`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ conversation: conversationHistory, pool: 'global' }),
});