herobrain 0.1.1

AI memory for every app. Store, search, and chat with persistent memory.

HeroBrain Python SDK

AI memory for every app. Give your AI persistent, searchable memory in 3 lines of code.

Install

pip install herobrain

Quick start

from herobrain import HeroBrainMemory

m = HeroBrainMemory(api_key="hb_...")

# Store a memory
m.add("User prefers dark mode and uses Python 3.12")

# Search memories
results = m.search("what programming language?")
print(results[0]["memory"]["content"])
# → "User prefers dark mode and uses Python 3.12"

# Chat with memory context
reply = m.chat("What do you know about my preferences?")
print(reply["response"])

That's it. HeroBrain handles embedding, dedup, hybrid search, and fact extraction automatically.

Configuration

from herobrain import HeroBrainMemory

# Pass the key directly
m = HeroBrainMemory(api_key="hb_...")

# Or set an environment variable
# export HEROBRAIN_API_KEY=hb_...
m = HeroBrainMemory()

# Self-hosted
m = HeroBrainMemory(
    api_key="hb_...",
    base_url="https://your-instance.example.com",
)

Memories

# Add a memory (auto-extracts facts, deduplicates, and classifies)
memories = m.add("I have a meeting with Jake tomorrow at 2pm")

# Add with options
memories = m.add(
    "Alice lives in Portland",
    agent_id="user-alice",       # isolate per user
    type="identity",             # semantic, episodic, identity, preference, task, procedural
    importance=0.9,
    metadata={"source": "onboarding"},
    expires_at="2026-12-31T00:00:00Z",  # auto-cleanup
)

# Search
results = m.search("where does alice live?", agent_id="user-alice")

# List all
all_memories = m.list(limit=50, agent_id="user-alice")

# Get one
memory = m.get("memory-uuid")

# Update
m.update("memory-uuid", content="Alice moved to Seattle")

# Delete
m.delete("memory-uuid")

# History (audit trail)
history = m.history("memory-uuid")

Chat

Memory-grounded conversations with streaming support.

# Simple chat
reply = m.chat("What meetings do I have?")
print(reply["response"])
print(reply["memoryReferences"])  # which memories were used

# Streaming
for event in m.chat_stream("Tell me about my week"):
    if event["type"] == "text":
        print(event["content"], end="", flush=True)

# Scoped to a user
reply = m.chat("What's my name?", agent_id="user-alice")

Multi-user / multi-agent

Use agent_id to isolate memory per user, agent, or session — just like Stripe uses customer_id.

# Each user gets their own memory space
m.add("Loves hiking", agent_id="user-42")
m.add("Prefers email", agent_id="user-42")

# Only searches user-42's memories
results = m.search("hobbies", agent_id="user-42")

# Chat with user-42's context only
reply = m.chat("What do I like?", agent_id="user-42")

Async

from herobrain import AsyncHeroBrainMemory

async def main():
    m = AsyncHeroBrainMemory(api_key="hb_...")
    
    memories = await m.add("User signed up for Pro plan")
    results = await m.search("plan")
    reply = await m.chat("What plan am I on?")
    
    await m.close()

Error handling

from herobrain import HeroBrainMemory, HeroBrainAuthError, HeroBrainRateLimitError

m = HeroBrainMemory(api_key="hb_...")

try:
    m.search("hello")
except HeroBrainAuthError:
    print("Bad API key")
except HeroBrainRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

Get your API key

1. Go to herobrain.app
2. Create an account
3. Go to API Keys and generate one
4. pip install herobrain and start building

Links

• API Docs
• GitHub
• Recall — example app built with HeroBrain