-
-
Notifications
You must be signed in to change notification settings - Fork 246
Expand file tree
/
Copy path.env.example
More file actions
224 lines (198 loc) · 10.6 KB
/
.env.example
File metadata and controls
224 lines (198 loc) · 10.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
# 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
# - sqlite_vec: Fast local storage (development)
# - cloudflare: Cloud storage with Cloudflare (production)
# - hybrid: Best of both - local speed + cloud persistence (recommended)
MCP_MEMORY_STORAGE_BACKEND=cloudflare
# =============================================================================
# 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)
# 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
# =============================================================================
# MEMORY TYPE ONTOLOGY CONFIGURATION
# =============================================================================
# Custom memory types (optional)
# Define additional base types and subtypes beyond the 75 built-in types
# Format: JSON object mapping base types to arrays of subtypes
# Example: {"legal": ["contract", "clause"], "sales": ["opportunity", "objection"]}
# MCP_CUSTOM_MEMORY_TYPES='{"legal": ["contract", "clause", "obligation"]}'
# =============================================================================
# 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