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 (local mode)
{
"mcpServers": {
"hippodid": {
"command": "java",
"args": ["-jar", "/path/to/hippodid-mcp-server.jar"],
"env": {
"HIPPODID_API_KEY": "hd_key_...",
"HIPPODID_MCP_CHARACTER_ID": "...",
"HIPPODID_AI_API_KEY": "sk-...",
"HIPPODID_AI_PROVIDER": "openai",
"HIPPODID_AI_MODEL": "gpt-4o-mini"
}
}
}
}
This uses local mode (stdio transport). For hosted mode, AI provider configuration is done via the dashboard settings page, not environment variables. See MCP Setup for both modes.
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
Since BYOK is mandatory for all paid tiers, there are no HippoDid-imposed AI operation limits. Your AI usage is bounded only by:
- Your AI provider’s own rate limits and account quota
- HippoDid’s infrastructure rate limits (SEARCH, WRITE, SYNC, MANAGEMENT buckets — see Tiers & Limits)
You pay your AI provider directly at their published rates. HippoDid charges for infrastructure only.
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.