Skip to content

ENV_VARS.md

Latest commit

 

History

History
723 lines (527 loc) · 18.1 KB

ENV_VARS.md

File metadata and controls

723 lines (527 loc) · 18.1 KB
Raw

Mimir Environment Variables Reference

Last Updated: 2025-11-24
Version: 2.1 (Unified API + Vision Intelligence)

Overview

Mimir uses split configuration with base URLs and paths. This provides maximum flexibility while keeping configuration explicit and simple. No URL parsing or manipulation - just straightforward concatenation.

Core Philosophy

  • Explicit over Implicit: Base URL + paths (simple concatenation, no parsing)
  • Separation of Concerns: LLM and embeddings configured independently
  • Provider Agnostic: Works with Ollama, OpenAI, Copilot, or any OpenAI-compatible API
  • Flexible Paths: Different providers can use different endpoint paths

LLM API Configuration

MIMIR_LLM_API

Required: Yes
Type: String (Base URL)
Default: http://ollama:11434

Base URL of the LLM server (no paths).

# Ollama
MIMIR_LLM_API=http://ollama:11434

# Copilot API
MIMIR_LLM_API=http://copilot-api:4141

# External OpenAI-compatible
MIMIR_LLM_API=http://host.docker.internal:8080

# OpenAI
MIMIR_LLM_API=https://api.openai.com

MIMIR_LLM_API_PATH

Required: No
Type: String (Path)
Default: /v1/chat/completions

Path to the chat completions endpoint.

MIMIR_LLM_API_PATH=/v1/chat/completions

MIMIR_LLM_API_MODELS_PATH

Required: No
Type: String (Path)
Default: /v1/models

Path to the models list endpoint.

MIMIR_LLM_API_MODELS_PATH=/v1/models

MIMIR_LLM_API_KEY

Required: No (depends on provider)
Type: String
Default: dummy-key

API key for authentication.

# Local Ollama (no auth needed)
MIMIR_LLM_API_KEY=dummy-key

# OpenAI
MIMIR_LLM_API_KEY=sk-...

# Copilot
MIMIR_LLM_API_KEY=sk-copilot-...

Embeddings API Configuration

MIMIR_EMBEDDINGS_API

Required: Yes (if embeddings enabled)
Type: String (Base URL)
Default: http://ollama:11434

Base URL of the embeddings server (no paths).

# Ollama
MIMIR_EMBEDDINGS_API=http://ollama:11434

# Copilot API
MIMIR_EMBEDDINGS_API=http://copilot-api:4141

# OpenAI
MIMIR_EMBEDDINGS_API=https://api.openai.com

MIMIR_EMBEDDINGS_API_PATH

Required: No
Type: String (Path)
Default: /api/embeddings (for Ollama)

Path to the embeddings endpoint.

# Ollama native format (default)
MIMIR_EMBEDDINGS_API_PATH=/api/embeddings

# OpenAI-compatible format
MIMIR_EMBEDDINGS_API_PATH=/v1/embeddings

MIMIR_EMBEDDINGS_API_MODELS_PATH

Required: No
Type: String (Path)
Default: /api/tags (for Ollama)

Path to the models list endpoint for embeddings.

# Ollama native format
MIMIR_EMBEDDINGS_API_MODELS_PATH=/api/tags

# OpenAI-compatible format
MIMIR_EMBEDDINGS_API_MODELS_PATH=/v1/models

MIMIR_EMBEDDINGS_API_KEY

Required: No (depends on provider)
Type: String
Default: dummy-key

API key for embeddings authentication.

MIMIR_EMBEDDINGS_API_KEY=dummy-key

Provider and Model Configuration

MIMIR_DEFAULT_PROVIDER

Type: String
Default: copilot
Options: copilot | ollama | openai

Default provider for model discovery.

MIMIR_DEFAULT_MODEL

Type: String
Default: gpt-4.1

Default model name.

# Examples
MIMIR_DEFAULT_MODEL=gpt-4.1
MIMIR_DEFAULT_MODEL=qwen2.5-coder:14b
MIMIR_DEFAULT_MODEL=gpt-4-turbo

MIMIR_CONTEXT_WINDOW

Type: Number
Default: 128000

Maximum context window size in tokens.

Embeddings Configuration

MIMIR_EMBEDDINGS_ENABLED

Type: Boolean
Default: true

MIMIR_EMBEDDINGS_PROVIDER

Type: String
Default: ollama
Options: ollama | openai | copilot | llama.cpp

MIMIR_EMBEDDINGS_MODEL

Type: String
Default: Architecture-dependent

  • ARM64: mxbai-embed-large
  • AMD64: text-embedding-3-small

MIMIR_EMBEDDINGS_DIMENSIONS

Type: Number
Default: Architecture-dependent

  • ARM64: 1024
  • AMD64: 1536

MIMIR_EMBEDDINGS_CHUNK_SIZE

Type: Number
Default: 512

MIMIR_EMBEDDINGS_CHUNK_OVERLAP

Type: Number
Default: 50

Image/Vision Configuration

Overview

Mimir supports Vision-Language (VL) models for indexing images by generating text descriptions, which are then embedded alongside text content. This enables semantic search across both text and images.

Architecture:

Image File → llama.cpp (qwen2.5-vl) → Text Description → 
nomic-embed-text (embed description) → Neo4j (vector + description)

MIMIR_EMBEDDINGS_IMAGES

Type: Boolean
Default: false
⚠️ Security: Disabled by default (requires explicit opt-in)

Enable image indexing and embeddings.

MIMIR_EMBEDDINGS_IMAGES=true   # Enable
MIMIR_EMBEDDINGS_IMAGES=false  # Disable (default)

Why disabled by default?

  • Image processing is resource-intensive (2-8GB RAM for VL models)
  • Prevents accidental indexing of personal/sensitive images
  • Requires separate VL model server setup

MIMIR_EMBEDDINGS_IMAGES_DESCRIBE_MODE

Type: Boolean
Default: true

Use VL model to generate text descriptions (recommended).

MIMIR_EMBEDDINGS_IMAGES_DESCRIBE_MODE=true   # VL description mode
MIMIR_EMBEDDINGS_IMAGES_DESCRIBE_MODE=false  # Direct image embedding (not supported)

Note: Direct image embedding is not supported. Always use true for VL description mode.

Vision-Language Model Configuration

MIMIR_EMBEDDINGS_VL_PROVIDER

Type: String
Default: llama.cpp
Options: llama.cpp | ollama

VL model provider.

MIMIR_EMBEDDINGS_VL_PROVIDER=llama.cpp

MIMIR_EMBEDDINGS_VL_API

Type: String (Base URL)
Default: http://llama-vl-server:8080

Base URL of the VL server.

# Docker internal
MIMIR_EMBEDDINGS_VL_API=http://llama-vl-server:8080

# External VL server
MIMIR_EMBEDDINGS_VL_API=http://host.docker.internal:8081

MIMIR_EMBEDDINGS_VL_API_PATH

Type: String (Path)
Default: /v1/chat/completions

Path to VL chat completions endpoint (OpenAI-compatible).

MIMIR_EMBEDDINGS_VL_API_KEY

Type: String
Default: dummy-key

API key for VL server (not required for local llama.cpp).

MIMIR_EMBEDDINGS_VL_MODEL

Type: String
Default: qwen2.5-vl

VL model name.

# Recommended models
MIMIR_EMBEDDINGS_VL_MODEL=qwen2.5-vl-2b  # 2B parameters (~2GB RAM)
MIMIR_EMBEDDINGS_VL_MODEL=qwen2.5-vl-7b  # 7B parameters (~6GB RAM) ⭐ Best balance
MIMIR_EMBEDDINGS_VL_MODEL=qwen2.5-vl     # Generic name

MIMIR_EMBEDDINGS_VL_CONTEXT_SIZE

Type: Number
Default: 131072 (128K tokens)

Maximum context window for VL model.

MIMIR_EMBEDDINGS_VL_CONTEXT_SIZE=32768   # 32K tokens (2B model)
MIMIR_EMBEDDINGS_VL_CONTEXT_SIZE=131072  # 128K tokens (7B/72B models)

MIMIR_EMBEDDINGS_VL_MAX_TOKENS

Type: Number
Default: 2048

Maximum tokens to generate for image descriptions.

MIMIR_EMBEDDINGS_VL_MAX_TOKENS=512   # Brief descriptions
MIMIR_EMBEDDINGS_VL_MAX_TOKENS=2048  # Detailed descriptions (recommended)
MIMIR_EMBEDDINGS_VL_MAX_TOKENS=4096  # Very detailed descriptions

MIMIR_EMBEDDINGS_VL_TEMPERATURE

Type: Number (0.0-1.0)
Default: 0.7

Sampling temperature for VL generation.

MIMIR_EMBEDDINGS_VL_TEMPERATURE=0.0  # Deterministic (factual)
MIMIR_EMBEDDINGS_VL_TEMPERATURE=0.7  # Balanced (recommended)
MIMIR_EMBEDDINGS_VL_TEMPERATURE=1.0  # Creative (more varied)

MIMIR_EMBEDDINGS_VL_DIMENSIONS

Type: Number
Default: Falls back to MIMIR_EMBEDDINGS_DIMENSIONS

Embedding dimensions for VL descriptions (falls back to text embedding dimensions).

Image Processing Configuration

MIMIR_IMAGE_MAX_PIXELS

Type: Number
Default: 3211264 (~1792×1792 pixels, 3.2 MP)

Maximum pixel count for images before auto-resizing.

Qwen2.5-VL native limit: 3,211,264 pixels

MIMIR_IMAGE_MAX_PIXELS=3211264  # Qwen2.5-VL limit (recommended)
MIMIR_IMAGE_MAX_PIXELS=2073600  # Full HD limit (1920×1080)

Supported Image Sizes:

  • ✅ 1920×1080 (Full HD) = 2.07 MP → No resize needed
  • ✅ 1792×1792 (Square) = 3.21 MP → No resize needed
  • ⚠️ 2560×1440 (2K) = 3.69 MP → Auto-resized to fit
  • ⚠️ 3840×2160 (4K) = 8.29 MP → Auto-resized to fit

MIMIR_IMAGE_TARGET_SIZE

Type: Number (pixels)
Default: 1536

Target dimension for longest edge when resizing.

MIMIR_IMAGE_TARGET_SIZE=1024  # Conservative
MIMIR_IMAGE_TARGET_SIZE=1536  # Recommended (preserves detail)
MIMIR_IMAGE_TARGET_SIZE=2048  # Maximum detail (slower processing)

Example resizing:

  • Input: 3840×2160 (4K) → Output: 1536×864 (aspect ratio preserved)
  • Input: 2560×1440 (2K) → Output: 1536×864

MIMIR_IMAGE_RESIZE_QUALITY

Type: Number (1-100)
Default: 90

JPEG quality after resizing (higher = better quality, larger file).

MIMIR_IMAGE_RESIZE_QUALITY=80  # Good quality
MIMIR_IMAGE_RESIZE_QUALITY=90  # Excellent quality (recommended)
MIMIR_IMAGE_RESIZE_QUALITY=95  # Maximum quality

Database Configuration

NEO4J_URI

Default: bolt://neo4j_db:7687

NEO4J_USER

Default: neo4j

NEO4J_PASSWORD

Default: password

Server Configuration

PORT

Default: 3000

NODE_ENV

Default: production

Workspace Configuration

WORKSPACE_ROOT

Default: /workspace

Container's internal workspace path. All file operations inside the container use this path.

HOST_WORKSPACE_ROOT

Required: Yes (for file operations)
Type: String (absolute or tilde path)
Example: ~/src, /Users/john/code, or C:\Users\you\code

Host machine's workspace directory. This is automatically mounted to WORKSPACE_ROOT in the container.

Tilde Expansion Support:

  • ✅ Automatic: ~/src is expanded using HOST_HOME (passed from host's $HOME)
  • ✅ Cross-Platform: Works on macOS, Linux, and Windows (WSL)
  • ⚠️ Requires: HOST_HOME must be set (automatically injected by docker-compose)

HOST_HOME

Required: No (automatically set by docker-compose)
Type: String (absolute path)
Default: ${HOME} (from host environment)
Example: /Users/john, /home/user, C:\Users\you

Host machine's home directory for expanding tilde (~) in HOST_WORKSPACE_ROOT.

Purpose:

  • Enables automatic tilde expansion in Docker containers
  • Without this, ~/src cannot be resolved (container's home ≠ host's home)

Behavior:

  • ✅ If set: HOST_WORKSPACE_ROOT=~/src → expands to /Users/john/src
  • ⚠️ If missing: Warning logged with helpful solutions, path translation disabled

Docker Compose automatically sets this:

environment:
  - HOST_HOME=${HOME}  # Passes host's home to container

Manual Override (if needed):

HOST_HOME=/Users/john docker compose up

Feature Flags

MIMIR_AUTO_INDEX_DOCS

Type: Boolean
Default: true

Auto-index documentation on startup.

MIMIR_ENABLE_ECKO

Type: Boolean
Default: false

Enable Ecko orchestration mode.

MIMIR_FEATURE_PM_MODEL_SUGGESTIONS

Type: Boolean
Default: false

Enable PM model suggestions feature.

Agent Execution Configuration

MIMIR_AGENT_RECURSION_LIMIT

Type: Integer
Default: 100

Maximum number of steps (tool calls + responses) an agent can take before stopping.

Controls how many iterations the LangGraph agent can execute before hitting the recursion limit. Each step typically includes:

  • Agent thinking/reasoning
  • Tool call execution
  • Tool response processing

When to adjust:

  • Increase (150-200): For complex multi-step tasks requiring many tool calls
  • Decrease (50-75): To save costs or prevent runaway agents
  • Keep default (100): Suitable for most GPT-4.1 tasks

Error handling: If the limit is reached, the UI will display a user-friendly message:

"I'm sorry, but this task is too complex for me to complete in one go. Please try breaking it down into smaller, more focused subtasks."

Cost implications: Higher limits allow more tool calls but consume more tokens. Monitor your usage when increasing this value.

Example values:

# Conservative (cost-saving)
MIMIR_AGENT_RECURSION_LIMIT=50

# Default (recommended for GPT-4.1)
MIMIR_AGENT_RECURSION_LIMIT=100

# Complex tasks (research, multi-file refactoring)
MIMIR_AGENT_RECURSION_LIMIT=150

# Very complex tasks (full system analysis)
MIMIR_AGENT_RECURSION_LIMIT=200

Note: This is separate from the circuit breaker limit (MAX_TOOL_CALLS), which is set by the PM agent based on task complexity estimates.

Quick Start Configurations

Local Ollama Setup

# LLM
MIMIR_LLM_API=http://ollama:11434
MIMIR_LLM_API_PATH=/v1/chat/completions
MIMIR_LLM_API_MODELS_PATH=/v1/models
MIMIR_LLM_API_KEY=dummy-key

# Embeddings
MIMIR_EMBEDDINGS_API=http://ollama:11434
MIMIR_EMBEDDINGS_API_PATH=/api/embeddings
MIMIR_EMBEDDINGS_API_MODELS_PATH=/api/tags
MIMIR_EMBEDDINGS_API_KEY=dummy-key
MIMIR_EMBEDDINGS_PROVIDER=ollama
MIMIR_EMBEDDINGS_MODEL=mxbai-embed-large
MIMIR_EMBEDDINGS_DIMENSIONS=1024

# Provider
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_DEFAULT_MODEL=qwen2.5-coder:14b

OpenAI Setup

# LLM
MIMIR_LLM_API=https://api.openai.com
MIMIR_LLM_API_PATH=/v1/chat/completions
MIMIR_LLM_API_MODELS_PATH=/v1/models
MIMIR_LLM_API_KEY=sk-...

# Embeddings
MIMIR_EMBEDDINGS_API=https://api.openai.com
MIMIR_EMBEDDINGS_API_PATH=/v1/embeddings
MIMIR_EMBEDDINGS_API_MODELS_PATH=/v1/models
MIMIR_EMBEDDINGS_API_KEY=sk-...
MIMIR_EMBEDDINGS_PROVIDER=openai
MIMIR_EMBEDDINGS_MODEL=text-embedding-3-small
MIMIR_EMBEDDINGS_DIMENSIONS=1536

# Provider
MIMIR_DEFAULT_PROVIDER=openai
MIMIR_DEFAULT_MODEL=gpt-4-turbo

Hybrid Setup (Ollama LLM + OpenAI Embeddings)

# LLM (Local Ollama)
MIMIR_LLM_API=http://ollama:11434
MIMIR_LLM_API_PATH=/v1/chat/completions
MIMIR_LLM_API_MODELS_PATH=/v1/models
MIMIR_LLM_API_KEY=dummy-key

# Embeddings (Cloud OpenAI)
MIMIR_EMBEDDINGS_API=https://api.openai.com
MIMIR_EMBEDDINGS_API_PATH=/v1/embeddings
MIMIR_EMBEDDINGS_API_MODELS_PATH=/v1/models
MIMIR_EMBEDDINGS_API_KEY=sk-...
MIMIR_EMBEDDINGS_PROVIDER=openai
MIMIR_EMBEDDINGS_MODEL=text-embedding-3-small
MIMIR_EMBEDDINGS_DIMENSIONS=1536

# Provider
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_DEFAULT_MODEL=qwen2.5-coder:14b

Vision-Language Setup (Image Indexing)

Prerequisites:

  1. Uncomment llama-vl-server service in docker-compose.yml
  2. Choose model size: 2B (faster, 2GB RAM) or 7B (best quality, 6GB RAM)
# LLM
MIMIR_LLM_API=http://ollama:11434
MIMIR_LLM_API_PATH=/v1/chat/completions
MIMIR_LLM_API_KEY=dummy-key

# Text Embeddings
MIMIR_EMBEDDINGS_API=http://ollama:11434
MIMIR_EMBEDDINGS_API_PATH=/api/embeddings
MIMIR_EMBEDDINGS_PROVIDER=ollama
MIMIR_EMBEDDINGS_MODEL=mxbai-embed-large
MIMIR_EMBEDDINGS_DIMENSIONS=1024

# Image Embeddings (Enable)
MIMIR_EMBEDDINGS_IMAGES=true
MIMIR_EMBEDDINGS_IMAGES_DESCRIBE_MODE=true

# Vision-Language Model (Qwen2.5-VL 7B)
MIMIR_EMBEDDINGS_VL_PROVIDER=llama.cpp
MIMIR_EMBEDDINGS_VL_API=http://llama-vl-server:8080
MIMIR_EMBEDDINGS_VL_API_PATH=/v1/chat/completions
MIMIR_EMBEDDINGS_VL_API_KEY=dummy-key
MIMIR_EMBEDDINGS_VL_MODEL=qwen2.5-vl-7b
MIMIR_EMBEDDINGS_VL_CONTEXT_SIZE=131072  # 128K tokens
MIMIR_EMBEDDINGS_VL_MAX_TOKENS=2048      # Detailed descriptions
MIMIR_EMBEDDINGS_VL_TEMPERATURE=0.7      # Balanced

# Image Processing
MIMIR_IMAGE_MAX_PIXELS=3211264    # Qwen2.5-VL limit (3.2 MP)
MIMIR_IMAGE_TARGET_SIZE=1536      # Resize target (longest edge)
MIMIR_IMAGE_RESIZE_QUALITY=90     # JPEG quality

# Provider
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_DEFAULT_MODEL=qwen2.5-coder:14b

For 2B model (less RAM): Change to MIMIR_EMBEDDINGS_VL_MODEL=qwen2.5-vl-2b and MIMIR_EMBEDDINGS_VL_CONTEXT_SIZE=32768

See also: Qwen VL Setup Guide

Migration from v1.x

Removed Variables

  • ❌ LLM_API_URL → Use MIMIR_LLM_API
  • ❌ OLLAMA_BASE_URL → Use MIMIR_LLM_API or MIMIR_EMBEDDINGS_API
  • ❌ COPILOT_BASE_URL → Use MIMIR_LLM_API
  • ❌ OPENAI_BASE_URL → Use MIMIR_LLM_API
  • ❌ OPENAI_API_KEY → Use MIMIR_LLM_API_KEY or MIMIR_EMBEDDINGS_API_KEY
  • ❌ FILE_WATCH_POLLING → Removed (unused)
  • ❌ FILE_WATCH_INTERVAL → Removed (unused)

Migration Example

# OLD (v1.x)
OLLAMA_BASE_URL=http://ollama:11434
COPILOT_BASE_URL=http://copilot-api:4141/v1

# NEW (v2.0) - For Ollama
MIMIR_LLM_API=http://ollama:11434
MIMIR_LLM_API_PATH=/v1/chat/completions
MIMIR_LLM_API_MODELS_PATH=/v1/models
MIMIR_LLM_API_KEY=dummy-key

MIMIR_EMBEDDINGS_API=http://ollama:11434
MIMIR_EMBEDDINGS_API_PATH=/api/embeddings
MIMIR_EMBEDDINGS_API_MODELS_PATH=/api/tags
MIMIR_EMBEDDINGS_API_KEY=dummy-key

Troubleshooting

404 Error on Embeddings

Problem: 404 page not found when generating embeddings

Solution: Check that MIMIR_EMBEDDINGS_API_PATH is set correctly:

  • Ollama native (default): MIMIR_EMBEDDINGS_API_PATH=/api/embeddings
  • OpenAI-compatible: MIMIR_EMBEDDINGS_API_PATH=/v1/embeddings

400 Invalid Input on Embeddings

Problem: invalid input error from Ollama embeddings

Solution: You're using Ollama with OpenAI-compatible path. Switch to native:

MIMIR_EMBEDDINGS_API_PATH=/api/embeddings
MIMIR_EMBEDDINGS_API_MODELS_PATH=/api/tags

Model Not Found

Problem: LLM returns "model not supported"

Solution:

  1. Verify model exists: curl http://localhost:11434/v1/models
  2. Update MIMIR_DEFAULT_MODEL to match available model

Authentication Errors

Problem: 401 Unauthorized

Solution: Set correct API key in MIMIR_LLM_API_KEY or MIMIR_EMBEDDINGS_API_KEY

See Also