BYOK AI
HippoDid is infrastructure, not AI compute. You bring your own LLM key.
Table of contents
What HippoDid pays for vs what you pay for
| Cost | Paid by |
|---|---|
| Database storage (memories, embeddings) | HippoDid |
| API servers, sync engine, rate limiting | HippoDid |
| AI extraction (AUDN calls, embeddings) | You — via your own API key |
| Semantic search embeddings | You — via your own API key |
HippoDid never proxies your data to a third-party AI model without your explicit configuration. On FREE tier, no AI operations run at all — memories are stored as plain text.
Which operations use AI
| Operation | AI used | Tier required |
|---|---|---|
| Memory extraction from unstructured text | Yes — AUDN pipeline | Starter+ |
| Semantic embedding for search | Yes — embedding model | Starter+ |
import_document pipeline | Yes — extraction + embedding | Starter+ |
| Auto-capture (background) | Yes — AUDN | Paid + auto-capture=true |
| Auto-recall (background) | Yes — embedding search | Paid + auto-recall=true |
Direct memory write (add_memory_direct) | No | Starter+ |
| File sync push/pull | No | All tiers |
Current configuration: MCP environment variables
AI provider configuration is set via environment variables when running the MCP server.
application.yml properties
hippodid:
mcp:
ai:
api-key: ${HIPPODID_AI_API_KEY:} # Your AI provider API key
provider: ${HIPPODID_AI_PROVIDER:openai} # openai | anthropic
model: ${HIPPODID_AI_MODEL:gpt-4o-mini} # Model identifier
base-url: ${HIPPODID_AI_BASE_URL:} # Optional: custom endpoint URL
Environment variables
| Variable | Default | Description |
|---|---|---|
HIPPODID_AI_API_KEY | (none) | Your OpenAI or Anthropic API key |
HIPPODID_AI_PROVIDER | openai | Provider: openai or anthropic |
HIPPODID_AI_MODEL | gpt-4o-mini | Model to use for extraction and embedding |
HIPPODID_AI_BASE_URL | (auto) | Custom base URL for self-hosted or proxy endpoints |
Claude Desktop example
{
"mcpServers": {
"hippodid": {
"command": "/path/to/hippodid-mcp",
"env": {
"HIPPODID_MCP_API_KEY": "hd_key_...",
"HIPPODID_MCP_CHARACTER_ID": "...",
"HIPPODID_AI_API_KEY": "sk-...",
"HIPPODID_AI_PROVIDER": "openai",
"HIPPODID_AI_MODEL": "gpt-4o-mini",
"SPRING_DATASOURCE_URL": "jdbc:postgresql://localhost:5432/hippodid",
"SPRING_DATASOURCE_USERNAME": "hippodid_app",
"SPRING_DATASOURCE_PASSWORD": "your_password"
}
}
}
}
Supported providers
OpenAI
HIPPODID_AI_PROVIDER=openai
HIPPODID_AI_API_KEY=sk-...
HIPPODID_AI_MODEL=gpt-4o-mini # or gpt-4o, gpt-4-turbo
Models tested: gpt-4o-mini, gpt-4o, gpt-4-turbo
Embeddings model is fixed at text-embedding-3-small (OpenAI) — this is not configurable at this time.
Anthropic
HIPPODID_AI_PROVIDER=anthropic
HIPPODID_AI_API_KEY=sk-ant-...
HIPPODID_AI_MODEL=claude-haiku-4-5-20251001 # or claude-sonnet-4-6
Models tested: claude-haiku-4-5-20251001, claude-sonnet-4-6
When using Anthropic, semantic search embedding falls back to an internal similarity model. Full vector embedding requires an OpenAI key or a compatible embedding endpoint.
Custom / self-hosted endpoints
Use HIPPODID_AI_BASE_URL to point to any OpenAI-compatible endpoint (e.g., Ollama, Azure OpenAI, LM Studio):
HIPPODID_AI_PROVIDER=openai
HIPPODID_AI_BASE_URL=http://localhost:11434/v1 # Ollama
HIPPODID_AI_MODEL=llama3.2
HIPPODID_AI_API_KEY=ollama # Ollama ignores the key but it must be non-empty
BYOK and rate limits
When you provide your own AI key, you are not subject to HippoDid’s AI operations quota (maxAiOpsPerMonth). Your usage is only limited by:
- Your AI provider’s own rate limits and account quota
- HippoDid’s infrastructure rate limits (SEARCH, WRITE, SYNC, MANAGEMENT buckets — see Tiers & Limits)
This means on BUSINESS tier with BYOK, you have effectively unlimited AI operations bounded only by your provider plan.
REST API for AI config
A PUT /v1/ai-config endpoint for managing AI provider configuration via the REST API is planned for a future sprint. Currently, all AI provider configuration is via environment variables as documented above.