Metadata-Version: 2.4
Name: herobrain
Version: 0.1.2
Summary: AI memory for every app. Store, search, and chat with persistent memory.
Project-URL: Homepage, https://github.com/tinyspaceturtle/brain-memory-v1
Project-URL: Documentation, https://github.com/tinyspaceturtle/brain-memory-v1/tree/main/sdks/python
Project-URL: Repository, https://github.com/tinyspaceturtle/brain-memory-v1
Project-URL: Issues, https://github.com/tinyspaceturtle/brain-memory-v1/issues
Author: HeroBrain
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,embeddings,llm,memory,rag,vector
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: async
Requires-Dist: httpx[http2]>=0.25.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# HeroBrain Python SDK

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

## Install

```bash
pip install herobrain
```

## Quick start

```python
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

```python
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

```python
# 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.

```python
# 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`.

```python
# 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

```python
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

```python
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](https://herobrain.app)
2. Create an account
3. Go to API Keys and generate one
4. `pip install herobrain` and start building

## Links

- [API Docs](https://herobrain.app/openapi.json)
- [GitHub](https://github.com/tinyspaceturtle/brain-memory-v1)
- [Recall — example app built with HeroBrain](https://github.com/tinyspaceturtle/recall-hb-app)
