.env.example

# Cloudflare Configuration for MCP Memory Service
# ================================================
# Copy this file to .env and replace with your actual credentials
#
# Setup Instructions:
# 1. Copy this file: cp .env.example .env
# 2. Create Cloudflare API Token at: https://dash.cloudflare.com/profile/api-tokens
# 3. Replace placeholder values below with your actual credentials
# 4. Never commit your .env file to git (it's already in .gitignore)

# =============================================================================
# REQUIRED: Cloudflare API Token
# =============================================================================
# Create at: https://dash.cloudflare.com/profile/api-tokens
# Required permissions:
#   - Account: Cloudflare Workers:Edit
#   - Zone Resources: Include All zones
#   - Account Resources: Include All accounts
#
# IMPORTANT: Test your token with the account-scoped endpoint:
#   curl "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/tokens/verify" \
#        -H "Authorization: Bearer {YOUR_TOKEN}"
#
# DO NOT use the generic endpoint (will fail for scoped tokens):
#   curl "https://api.cloudflare.com/client/v4/user/tokens/verify" ❌
CLOUDFLARE_API_TOKEN=your-cloudflare-api-token-here

# =============================================================================
# REQUIRED: Cloudflare Account ID
# =============================================================================
# Find in: Cloudflare Dashboard > Right sidebar under "Account ID"
# Example: be0e35a26715043ef8df90253268c33f
CLOUDFLARE_ACCOUNT_ID=your-account-id-here

# =============================================================================
# REQUIRED: D1 Database ID
# =============================================================================
# Create with: wrangler d1 create mcp-memory-database
# Or find existing: wrangler d1 list
# Example: f745e9b4-ba8e-4d47-b38f-12af91060d5a
CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id-here

# =============================================================================
# REQUIRED: Vectorize Index Name
# =============================================================================
# Create with: wrangler vectorize create mcp-memory-index --dimensions=384
# Or find existing: wrangler vectorize list
# Example: mcp-memory-index
CLOUDFLARE_VECTORIZE_INDEX=your-vectorize-index-name

# =============================================================================
# OPTIONAL: R2 Bucket for Large Content Storage
# =============================================================================
# Create with: wrangler r2 bucket create mcp-memory-content
# Only needed if you plan to store large content (>1MB)
# CLOUDFLARE_R2_BUCKET=mcp-memory-content

# =============================================================================
# STORAGE BACKEND CONFIGURATION
# =============================================================================
# Options: sqlite_vec | cloudflare | hybrid | milvus
# - sqlite_vec: Fast local storage (development)
# - cloudflare: Cloud storage with Cloudflare (production)
# - hybrid: Best of both - local speed + cloud persistence (recommended)
# - milvus: Vector DB — Milvus Lite (single file), self-hosted Milvus, or Zilliz Cloud
MCP_MEMORY_STORAGE_BACKEND=cloudflare

# =============================================================================
# MILVUS BACKEND CONFIGURATION (when MCP_MEMORY_STORAGE_BACKEND=milvus)
# =============================================================================
# Default uri uses Milvus Lite — a single local file, zero external dependencies.
# Point at an HTTP(S) endpoint for a self-hosted Milvus server or Zilliz Cloud.
#
# Examples:
#   MCP_MILVUS_URI=./milvus.db                      # Milvus Lite (default)
#   MCP_MILVUS_URI=http://localhost:19530           # Self-hosted Milvus
#   MCP_MILVUS_URI=https://xxx.zillizcloud.com      # Zilliz Cloud (set MCP_MILVUS_TOKEN too)
#
# NOTE: We use MCP_MILVUS_* (not MILVUS_*) because pymilvus reserves the MILVUS_URI
# env var and rejects local file paths at import time.
#
# MCP_MILVUS_URI=./milvus.db
# MCP_MILVUS_TOKEN=your-milvus-or-zilliz-token      # Required for Zilliz Cloud; optional otherwise
# MCP_MILVUS_COLLECTION_NAME=mcp_memory             # Collection name (default: mcp_memory)

# =============================================================================
# OPTIONAL: Advanced Configuration
# =============================================================================

# Semantic deduplication settings
MCP_SEMANTIC_DEDUP_ENABLED=true               # Enable/disable semantic dedup (default: true)
MCP_SEMANTIC_DEDUP_TIME_WINDOW_HOURS=24      # Hours to look back (default: 24)
MCP_SEMANTIC_DEDUP_THRESHOLD=0.85            # Similarity threshold 0.0-1.0 (default: 0.85)

# Cloudflare embedding model (default is recommended)
# CLOUDFLARE_EMBEDDING_MODEL=@cf/baai/bge-base-en-v1.5

# Large content threshold for R2 storage (bytes)
# CLOUDFLARE_LARGE_CONTENT_THRESHOLD=1048576

# Quality System - Batched Inference Configuration
# MCP_QUALITY_BATCH_SIZE=32             # Max items per ONNX inference batch (default: 32)
# MCP_QUALITY_MIN_GPU_BATCH=16          # Min batch size for GPU batched inference (default: 16)
#                                       # Below this threshold, uses sequential GPU calls (faster for small batches)

# Quality System - OpenAI-Compatible Provider (homelab / self-hosted LLM)
# Point scoring at any OpenAI-compatible /v1/chat/completions endpoint:
# LiteLLM proxy, Ollama, vLLM, MLX-LM server, or any OpenAI-shim.
# Required when MCP_QUALITY_AI_PROVIDER=openai-compatible
#
# MCP_QUALITY_AI_PROVIDER=openai-compatible
# MCP_QUALITY_AI_BASE_URL=http://localhost:11434/v1   # Ollama default
# MCP_QUALITY_AI_MODEL=qwen2.5:7b-instruct            # Recommended: Ollama
# MCP_QUALITY_AI_API_KEY=ollama                       # Optional; use "ollama" for Ollama, omit for local stacks
#
# Recommended models by runtime:
#   Apple Silicon / MLX:  mlx-community/Qwen2.5-7B-Instruct-4bit
#   Ollama:               qwen2.5:7b-instruct  |  llama3.1:8b  |  mistral-small:24b
#   LiteLLM proxy:        set MCP_QUALITY_AI_BASE_URL=http://litellm:4000/v1, model=your-alias
#   vLLM:                 set MCP_QUALITY_AI_BASE_URL=http://vllm:8000/v1, model=<served-model-id>
#
# Notes:
#   - Avoid base (non-instruct) models, sub-3B models, and reasoning models (QwQ, etc.)
#   - Scoring uses max_tokens=50, temperature=0.1; the model must return a bare float
#   - On endpoint failure the tier falls back to implicit_signals automatically

# HTTP Interface (Web Dashboard)
# NOTE: The HTTP dashboard is a SEPARATE server from the MCP server.
# To start the dashboard: uv run python scripts/server/run_http_server.py
# Or use Windows Task Scheduler: scripts/service/windows/install_scheduled_task.ps1
MCP_HTTP_ENABLED=true
MCP_HTTP_PORT=8000
# MCP_HTTPS_ENABLED=true
# MCP_HTTPS_PORT=8443

# =============================================================================
# Authentication
# =============================================================================

# API Key Authentication (simple, no OAuth required)
# Accepts API key via X-API-Key header or api_key query parameter
# Example: curl -H "X-API-Key: your-secret-key" http://localhost:8000/api/memories
# MCP_API_KEY=your-secret-key-here

# OAuth 2.1 Authentication (for web interface with team collaboration)
# MCP_OAUTH_ENABLED=false

# OAuth Storage Backend (memory|sqlite)
MCP_OAUTH_STORAGE_BACKEND=memory
MCP_OAUTH_SQLITE_PATH=./data/oauth.db

# Anonymous Access (allow unauthenticated access with read+write permissions)
# When enabled, all users can read, store, and delete memories without credentials.
# Only enable for local development or if you're behind a firewall/external auth.
# MCP_ALLOW_ANONYMOUS_ACCESS=false

# Hybrid Backend Configuration (if using hybrid)
# MCP_HYBRID_SYNC_INTERVAL=300      # Sync every 5 minutes
# MCP_HYBRID_BATCH_SIZE=50          # Sync 50 operations at a time
# MCP_HYBRID_SYNC_ON_STARTUP=true   # Initial sync on startup

# Offline Mode (for air-gapped deployments)
# MCP_MEMORY_OFFLINE=1              # Prevent HuggingFace model downloads
                                    # Note: Models must be pre-cached before enabling
                                    # First install downloads models automatically

# Initialization Timeout (Windows users may need to increase this)
# Controls the eager storage initialization timeout in seconds
# Default: 30s on Windows, 15s on other platforms (auto-doubled on first run or missing deps)
# Increase if you see "Storage initialization timed out" in logs on every startup
# MCP_INIT_TIMEOUT=120              # Set to 120s for slow Windows systems

# =============================================================================
# OPTIONAL: External Embedding API (vLLM, Ollama, TEI, OpenAI)
# =============================================================================
# Use external embedding service instead of local models
# Useful for: shared infrastructure, GPU offloading, hosted services
#
# ⚠️  IMPORTANT: Only supported with MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
# External APIs do NOT work with 'hybrid' or 'cloudflare' backends
#
# API endpoint (OpenAI-compatible /v1/embeddings)
# MCP_EXTERNAL_EMBEDDING_URL=http://localhost:8890/v1/embeddings
#
# Model name to pass to the API
# MCP_EXTERNAL_EMBEDDING_MODEL=nomic-embed-text
#
# Optional: API key for authenticated endpoints
# MCP_EXTERNAL_EMBEDDING_API_KEY=sk-xxx
#
# Examples:
# - vLLM: http://localhost:8890/v1/embeddings
# - Ollama: http://localhost:11434/v1/embeddings
# - OpenAI: https://api.openai.com/v1/embeddings
# - TEI: http://localhost:8080/v1/embeddings
#
# ⚠️  Embedding dimensions must match your storage backend:
#   - all-MiniLM-L6-v2 (default ONNX): 384 dims
#   - nomic-embed-text: 768 dims
#   - text-embedding-3-small: 1536 dims
#   - @cf/baai/bge-base-en-v1.5 (Cloudflare): 768 dims

# =============================================================================
# GRAPH DATABASE CONFIGURATION (v8.51.0+)
# =============================================================================
# Controls how memory associations are stored
# Options:
#   - memories_only: Store in memories.metadata.associations (backward compatible, v8.48.0 behavior)
#   - dual_write: Write to both memories.metadata AND memory_graph table (migration mode, default)
#   - graph_only: Write to memory_graph table only (future mode, requires migration complete)
#
# Migration Path:
#   1. Start with dual_write (default) - maintains compatibility while building graph data
#   2. Run migration script to backfill memory_graph from existing associations
#   3. Validate graph data completeness
#   4. Switch to graph_only mode after validation
#
# Benefits of graph_only mode:
#   - 5-10x faster association queries (indexed graph table vs JSON metadata parsing)
#   - Efficient bidirectional traversal (A→B and B→A)
#   - Support for multiple connection types (semantic, temporal, causal, thematic)
#   - Foundation for advanced graph analytics (PageRank, clustering, path finding)
#
MCP_GRAPH_STORAGE_MODE=dual_write

# =============================================================================
# HYBRID SEARCH CONFIGURATION (v10.8.0+)
# =============================================================================
# Hybrid search combines BM25 keyword matching with vector similarity search
# for better exact match scoring. Only available with sqlite_vec backend.
#
# Enable/disable hybrid search (default: true)
MCP_HYBRID_SEARCH_ENABLED=true

# Score fusion weights (must sum to ~1.0)
# - Keyword weight: BM25 keyword match score weight (default: 0.3)
# - Semantic weight: Vector similarity score weight (default: 0.7)
#
# Adjust weights based on your use case:
# - More keyword-focused: increase keyword_weight (e.g., 0.5/0.5)
# - More semantic-focused: increase semantic_weight (e.g., 0.2/0.8)
MCP_HYBRID_KEYWORD_WEIGHT=0.3
MCP_HYBRID_SEMANTIC_WEIGHT=0.7

# Fusion method: how BM25 and vector scores are combined (default: weighted_average)
# - weighted_average: linear combination using weights above (original method)
# - rrf: Reciprocal Rank Fusion — rank-based, robust to score scale mismatch
#   Reference: Cormack, Clarke & Buettcher (2009)
# MCP_HYBRID_FUSION_METHOD=weighted_average

# RRF parameters (only used when fusion_method=rrf)
# - K: smoothing constant (default: 60, industry standard)
# - CONSENSUS_BOOST: bonus for items found by both retrievers (default: 0.1)
# MCP_HYBRID_RRF_K=60
# MCP_HYBRID_RRF_CONSENSUS_BOOST=0.1

# MISTAKE NOTES CONFIGURATION
# Similarity threshold for deduplication (0.0-1.0, default: 0.85)
# When adding a mistake note, if an existing note has similarity above this
# threshold, the failure_count is incremented instead of creating a duplicate.
# MCP_MISTAKE_NOTE_DEDUP_THRESHOLD=0.85

# =============================================================================
# MEMORY TYPE ONTOLOGY CONFIGURATION
# =============================================================================
# memory_type values are validated against a built-in taxonomy. Unknown
# types are silently coerced to 'observation' and the MCP/HTTP response
# includes a warning. Use this variable to register additional base types
# and subtypes ahead of time.
#
# Format: JSON object mapping base types to arrays of subtypes (subtypes
# may be empty when you only need a flat type name).
#
# Examples:
#   MCP_CUSTOM_MEMORY_TYPES='{"foo": []}'
#   MCP_CUSTOM_MEMORY_TYPES='{"legal": ["contract", "clause", "obligation"]}'
#   MCP_CUSTOM_MEMORY_TYPES='{"planning": ["okr", "north_star"]}'
#
# Restart the server after changing this — the merged taxonomy is cached
# in-process. See docs/memory-ontology.md for the full type list and the
# rules around custom-type validation.
# MCP_CUSTOM_MEMORY_TYPES='{"legal": ["contract", "clause", "obligation"]}'

# =============================================================================
# CONSOLIDATION SCHEDULING (v8.23.0+)
# =============================================================================
# Dream-inspired memory maintenance: decay scoring, association discovery,
# semantic compression, and quality-based archival. Runs via APScheduler.
#
# Master switch (consolidation logic itself):
# MCP_CONSOLIDATION_ENABLED=true
#
# Schedule values control WHEN automatic consolidation runs. ALL schedules
# default to 'disabled' (manual-only mode). Uncomment AND set a value to
# enable each interval. Use 'disabled' (or leave commented) to skip.
#
# Behavior change in v10.48: previously, daily/weekly/monthly defaults were
# active (02:00 / SUN 03:00 / 01 04:00) even when these env vars were not
# set, which silently archived files on deployments expecting manual-only
# operation (issue #808). All defaults are now 'disabled'.
#
# Format reference:
#   daily:     HH:MM             (e.g. '02:00' = every day at 2 AM local)
#   weekly:    DAY HH:MM         (e.g. 'SUN 03:00' = Sundays at 3 AM)
#   monthly:   DD HH:MM          (e.g. '01 04:00' = 1st of month at 4 AM)
#   quarterly: MM-DD HH:MM       (e.g. '01-01 04:00' — month part is ignored;
#                                  always fires on the given DD at quarter
#                                  starts: Jan, Apr, Jul, Oct)
#   yearly:    MM-DD HH:MM       (e.g. '01-01 05:00' = Jan 1 at 5 AM)
#
# Recommended values when enabling automatic consolidation:
# MCP_SCHEDULE_DAILY=02:00
# MCP_SCHEDULE_WEEKLY=SUN 03:00
# MCP_SCHEDULE_MONTHLY=01 04:00
# MCP_SCHEDULE_QUARTERLY=disabled
# MCP_SCHEDULE_YEARLY=disabled
#
# To run consolidation on demand without a schedule, leave all the above
# commented (or set to 'disabled') and call the API/MCP tool manually:
#   curl -X POST http://localhost:8000/api/consolidation/run -d '{"horizon":"daily"}'
#   memory_consolidate(action="run", horizon="daily")

# =============================================================================
# TROUBLESHOOTING
# =============================================================================
# Common issues:
# 1. "Invalid API Token" - Check token permissions and expiry
# 2. "Database not found" - Verify D1 database ID is correct
# 3. "Vectorize index not found" - Check index name and dimensions (384)
# 4. "Account access denied" - Ensure API token has account permissions
#
# Documentation: https://github.com/doobidoo/mcp-memory-service/wiki
# Support: https://github.com/doobidoo/mcp-memory-service/issues