Skip to content

configuration-guide.md

Latest commit

 

History

History
98 lines (70 loc) · 4.55 KB

configuration-guide.md

File metadata and controls

98 lines (70 loc) · 4.55 KB
Raw

MCP Memory Service — Configuration Guide

All configuration is driven via environment variables and sensible defaults resolved in src/mcp_memory_service/config.py.

Base Paths

  • MCP_MEMORY_BASE_DIR: Root directory for service data. Defaults per-OS to an app-data directory and is created if missing.
  • Derived paths (auto-created):
    • SQLite database: ${BASE_DIR}/sqlite_vec.db unless overridden.
    • Backups path: ${BASE_DIR}/backups unless overridden.

Overrides:

  • MCP_MEMORY_SQLITE_PATH: SQLite-vec database file path.
  • MCP_MEMORY_BACKUPS_PATH or mcpMemoryBackupsPath: Backups directory path.

Storage Backend Selection

  • MCP_MEMORY_STORAGE_BACKEND: sqlite_vec (default), cloudflare, or hybrid.
    • sqlite-vec aliases to sqlite_vec.
    • Unknown values default to sqlite_vec with a warning.

SQLite-vec options:

  • MCP_MEMORY_SQLITE_PATH or MCP_MEMORY_SQLITEVEC_PATH: Path to .db file. Default ${BASE_DIR}/sqlite_vec.db.
  • MCP_MEMORY_SQLITE_PRAGMAS: CSV list of custom pragmas e.g. journal_mode=WAL,busy_timeout=15000,cache_size=20000 (recommended for concurrent access).

Cloudflare options (required unless otherwise noted):

  • CLOUDFLARE_API_TOKEN (required)
  • CLOUDFLARE_ACCOUNT_ID (required)
  • CLOUDFLARE_VECTORIZE_INDEX (required)
  • CLOUDFLARE_D1_DATABASE_ID (required)
  • CLOUDFLARE_R2_BUCKET (optional, for large content)
  • CLOUDFLARE_EMBEDDING_MODEL (default @cf/baai/bge-base-en-v1.5)
  • CLOUDFLARE_LARGE_CONTENT_THRESHOLD (bytes; default 1,048,576)
  • CLOUDFLARE_MAX_RETRIES (default 3)
  • CLOUDFLARE_BASE_DELAY (seconds; default 1.0)

Embedding Model

  • MCP_EMBEDDING_MODEL: Model name (default all-MiniLM-L6-v2).
  • MCP_MEMORY_USE_ONNX: true|false toggle for ONNX path.

HTTP/HTTPS Interface

  • MCP_HTTP_ENABLED: true|false to enable HTTP interface.
  • MCP_HTTP_HOST: Bind address (default 0.0.0.0).
  • MCP_HTTP_PORT: Port (default 8000).
  • MCP_CORS_ORIGINS: Comma-separated origins (default *).
  • MCP_SSE_HEARTBEAT: SSE heartbeat interval seconds (default 30).
  • MCP_API_KEY: Optional API key for HTTP.

TLS:

  • MCP_HTTPS_ENABLED: true|false.
  • MCP_SSL_CERT_FILE, MCP_SSL_KEY_FILE: Certificate and key paths.

mDNS Service Discovery

  • MCP_MDNS_ENABLED: true|false (default true).
  • MCP_MDNS_SERVICE_NAME: Service display name (default MCP Memory Service).
  • MCP_MDNS_SERVICE_TYPE: Service type (default _mcp-memory._tcp.local.).
  • MCP_MDNS_DISCOVERY_TIMEOUT: Seconds to wait for discovery (default 5).

Consolidation (Optional)

  • MCP_CONSOLIDATION_ENABLED: true|false.
  • Archive location:
    • MCP_CONSOLIDATION_ARCHIVE_PATH or MCP_MEMORY_ARCHIVE_PATH (default ${BASE_DIR}/consolidation_archive).
  • Config knobs:
    • Decay: MCP_DECAY_ENABLED, retention by type: MCP_RETENTION_CRITICAL, MCP_RETENTION_REFERENCE, MCP_RETENTION_STANDARD, MCP_RETENTION_TEMPORARY.
    • Associations: MCP_ASSOCIATIONS_ENABLED, MCP_ASSOCIATION_MIN_SIMILARITY, MCP_ASSOCIATION_MAX_SIMILARITY, MCP_ASSOCIATION_MAX_PAIRS.
    • Clustering: MCP_CLUSTERING_ENABLED, MCP_CLUSTERING_MIN_SIZE, MCP_CLUSTERING_ALGORITHM.
    • Compression: MCP_COMPRESSION_ENABLED, MCP_COMPRESSION_MAX_LENGTH, MCP_COMPRESSION_PRESERVE_ORIGINALS.
    • Forgetting: MCP_FORGETTING_ENABLED, MCP_FORGETTING_RELEVANCE_THRESHOLD, MCP_FORGETTING_ACCESS_THRESHOLD.
  • Scheduling (APScheduler-ready):
    • MCP_SCHEDULE_DAILY (default 02:00), MCP_SCHEDULE_WEEKLY (default SUN 03:00), MCP_SCHEDULE_MONTHLY (default 01 04:00), MCP_SCHEDULE_QUARTERLY (default disabled), MCP_SCHEDULE_YEARLY (default disabled).

Machine Identification

  • MCP_MEMORY_INCLUDE_HOSTNAME: true|false to tag memories with source:<hostname> and include hostname metadata.

Logging and Performance

  • LOG_LEVEL: Root logging level (default WARNING).
  • DEBUG_MODE: When unset, the service raises log levels for performance-critical libs (sentence_transformers, transformers, torch, numpy, onnxruntime).

Recommended Defaults by Backend

  • SQLite-vec:
    • Defaults enable WAL, busy timeout, optimized cache; customize with MCP_MEMORY_SQLITE_PRAGMAS.
    • For multi-client setups, the service auto-detects and may start/use an HTTP coordinator.
  • Cloudflare:
    • Ensure required variables are set or the process exits with a clear error and checklist.
  • Hybrid (recommended for production):
    • Uses SQLite-vec for 5 ms local reads with background Cloudflare sync. Requires all CLOUDFLARE_* variables. Set MCP_HYBRID_SYNC_OWNER=http when running alongside an MCP server so only the HTTP server syncs.