# 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):
  - Chroma path: `${BASE_DIR}/chroma_db` unless overridden.
  - Backups path: `${BASE_DIR}/backups` unless overridden.

Overrides:

- `MCP_MEMORY_CHROMA_PATH` or `mcpMemoryChromaPath`: ChromaDB directory path.
- `MCP_MEMORY_BACKUPS_PATH` or `mcpMemoryBackupsPath`: Backups directory path.

## Storage Backend Selection

- `MCP_MEMORY_STORAGE_BACKEND`: `sqlite_vec` (default), `chroma`, or `cloudflare`.
  - `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. `busy_timeout=15000,cache_size=20000` (v8.9.0+ recommended values for concurrent access).

Chroma options:

- `MCP_MEMORY_CHROMADB_HOST`: Hostname for remote Chroma.
- `MCP_MEMORY_CHROMADB_PORT`: Port (default 8000).
- `MCP_MEMORY_CHROMADB_SSL`: `true|false` for HTTPS.
- `MCP_MEMORY_CHROMADB_API_KEY`: API key when remote.
- `MCP_MEMORY_COLLECTION_NAME`: Collection name (default `memory_collection`).

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 (`chromadb`, `sentence_transformers`, `transformers`, `torch`, `numpy`).

## 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.
- ChromaDB:
  - HNSW space/ef/M values tuned for balanced accuracy and speed; migration messaging warns of deprecation and recommends moving to SQLite-vec.
- Cloudflare:
  - Ensure required variables are set or the process exits with a clear error and checklist.

