@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
541 lines • 18.5 kB
TypeScript
/**
* Performance Configuration Constants
*
* Centralized configuration for performance-related magic numbers including
* lock timeouts, metrics batching, cache memory estimation, and other
* performance-critical constants.
*
* All values can be overridden via environment variables for flexibility.
*
* @module performance-constants
*/
/**
* File locking configuration
*
* Lock timeout is based on p95 operation time analysis:
* - Measured p95 operation time: 2.5 seconds
* - Safety buffer: 4x multiplier
* - Default timeout: 10 seconds (2.5s * 4)
*
* This provides enough time for operations to complete while preventing
* deadlocks from hung processes.
*/
export declare const FILE_LOCK_CONFIG: {
/**
* Default timeout for lock acquisition (milliseconds)
*
* Based on empirical analysis:
* - P95 file operation time: 2.5s
* - Buffer multiplier: 4x for safety
* - Total: 10,000ms (10 seconds)
*
* Environment: DOLLHOUSE_LOCK_TIMEOUT
*/
readonly DEFAULT_TIMEOUT_MS: number;
/**
* Minimum allowed lock timeout (1 second)
* Prevents misconfiguration that could cause spurious timeouts
*/
readonly MIN_TIMEOUT_MS: 1000;
/**
* Maximum allowed lock timeout (60 seconds)
* Prevents indefinite hangs while allowing for slow operations
*/
readonly MAX_TIMEOUT_MS: 60000;
/**
* Stale lock cleanup threshold (milliseconds)
* Locks older than this are considered abandoned and can be forcibly released
*
* Environment: DOLLHOUSE_LOCK_STALE_THRESHOLD
*/
readonly STALE_THRESHOLD_MS: number;
/**
* Lock retry configuration
*/
readonly RETRY: {
/**
* Maximum number of retry attempts for lock acquisition
*
* Environment: DOLLHOUSE_LOCK_MAX_RETRIES
*/
readonly MAX_ATTEMPTS: number;
/**
* Initial delay between retries (milliseconds)
* Uses exponential backoff from this base
*
* Environment: DOLLHOUSE_LOCK_RETRY_DELAY
*/
readonly INITIAL_DELAY_MS: number;
};
};
/**
* Metrics batching configuration
*
* Optimizes write performance by batching metrics updates:
* - Batch size tuned for memory vs. latency trade-off
* - Small batches = lower latency, higher overhead
* - Large batches = higher latency, lower overhead
*
* Current values provide good balance for typical workloads.
*/
export declare const METRICS_CONFIG: {
/**
* Number of metrics to batch before flushing to disk
*
* Trade-offs:
* - Size 10: ~50ms flush latency, minimal memory (chosen for balance)
* - Size 100: ~200ms flush latency, 10x more memory
* - Size 1: No batching, highest overhead
*
* Environment: DOLLHOUSE_METRICS_BATCH_SIZE
*/
readonly BATCH_SIZE: number;
/**
* Minimum batch size (no batching)
*/
readonly MIN_BATCH_SIZE: 1;
/**
* Maximum batch size to prevent memory issues
*/
readonly MAX_BATCH_SIZE: 1000;
/**
* Time interval to force flush even if batch not full (milliseconds)
*
* Ensures metrics are persisted within reasonable time:
* - 5 seconds provides good balance between freshness and efficiency
* - Prevents unbounded delay for low-traffic scenarios
*
* Environment: DOLLHOUSE_METRICS_FLUSH_INTERVAL
*/
readonly FLUSH_INTERVAL_MS: number;
/**
* Minimum flush interval (100ms)
* Prevents excessive disk I/O
*/
readonly MIN_FLUSH_INTERVAL_MS: 100;
/**
* Maximum flush interval (5 minutes)
* Ensures timely metric persistence
*/
readonly MAX_FLUSH_INTERVAL_MS: 300000;
};
/**
* Cache size estimation configuration
*
* Fast byte-based heuristics for memory estimation based on V8 memory layout analysis.
* These values are derived from empirical measurements of V8 object representations.
*
* Accuracy vs. Speed trade-offs:
* - Fast mode: 2-5x faster than JSON.stringify, 50-200% accuracy
* - Balanced mode: Samples first 10 elements, better accuracy
* - Accurate mode: Uses JSON.stringify, slowest but most precise
*/
export declare const CACHE_SIZE_ESTIMATION_CONFIG: {
/**
* Size of primitive values in V8 (bytes)
* Covers numbers, booleans, small integers
*
* Based on V8 Smi (Small Integer) representation
*/
readonly PRIMITIVE_SIZE: 8;
/**
* Base memory overhead for JavaScript objects (bytes)
*
* Includes:
* - Object header: ~32 bytes
* - Hidden class pointer: ~8 bytes
* - Properties backing store: ~24 bytes
* - Total: ~64 bytes
*/
readonly OBJECT_BASE_OVERHEAD: 64;
/**
* Base memory overhead for JavaScript arrays (bytes)
*
* Includes:
* - Array header: ~16 bytes
* - Length property: ~8 bytes
* - Elements backing store pointer: ~8 bytes
* - Total: ~32 bytes
*/
readonly ARRAY_BASE_OVERHEAD: 32;
/**
* Memory overhead per object field/property (bytes)
*
* Includes:
* - Property name string: ~24 bytes average
* - Property value pointer: ~8 bytes
* - Property descriptor: ~16 bytes
* - Total: ~48 bytes
*/
readonly FIELD_OVERHEAD: 48;
/**
* Average element size estimate for arrays (bytes)
*
* Conservative estimate for mixed content:
* - Small objects: ~32 bytes
* - Strings: ~64 bytes average
* - Numbers: ~8 bytes
* - Average: ~64 bytes
*/
readonly ELEMENT_ESTIMATE: 64;
/**
* Number of elements to sample in balanced mode
*
* Sampling first 10 elements provides:
* - ~85% accuracy for homogeneous arrays
* - ~70% accuracy for mixed content
* - 2-3x speedup over full traversal
*/
readonly BALANCED_SAMPLE_SIZE: number;
/**
* Minimum sample size for balanced mode
*/
readonly MIN_SAMPLE_SIZE: 1;
/**
* Maximum sample size for balanced mode
* Prevents excessive sampling overhead
*/
readonly MAX_SAMPLE_SIZE: 100;
};
/**
* Memory limits for various cache types
*
* These limits prevent unbounded memory growth and provide
* reasonable defaults for different use cases.
*/
export declare const MEMORY_LIMITS: {
/**
* Cache limits for persona data
*/
readonly PERSONA_CACHE: {
/**
* Maximum number of cached persona entries
* Environment: DOLLHOUSE_MAX_PERSONA_CACHE_SIZE
*/
readonly MAX_SIZE: number;
/**
* Maximum memory for persona cache (MB)
* Environment: DOLLHOUSE_MAX_PERSONA_CACHE_MEMORY
*/
readonly MAX_MEMORY_MB: number;
};
/**
* Cache limits for metrics data
*/
readonly METRICS_CACHE: {
/**
* Maximum number of cached metrics entries
* Environment: DOLLHOUSE_MAX_METRICS_CACHE_SIZE
*/
readonly MAX_SIZE: number;
/**
* Maximum memory for metrics cache (MB)
* Environment: DOLLHOUSE_MAX_METRICS_CACHE_MEMORY
*/
readonly MAX_MEMORY_MB: number;
};
/**
* Cache limits for search results
*/
readonly SEARCH_CACHE: {
/**
* Maximum number of cached search results
* Environment: DOLLHOUSE_MAX_SEARCH_CACHE_SIZE
*/
readonly MAX_SIZE: number;
/**
* Maximum memory for search cache (MB)
* Environment: DOLLHOUSE_MAX_SEARCH_CACHE_MEMORY
*/
readonly MAX_MEMORY_MB: number;
};
/**
* Cache limits for index data
*/
readonly INDEX_CACHE: {
/**
* Maximum number of cached index entries
* Environment: DOLLHOUSE_MAX_INDEX_CACHE_SIZE
*/
readonly MAX_SIZE: number;
/**
* Maximum memory for index cache (MB)
* Environment: DOLLHOUSE_MAX_INDEX_CACHE_MEMORY
*/
readonly MAX_MEMORY_MB: number;
};
/**
* Cache limits for API responses
*/
readonly API_CACHE: {
/**
* Maximum number of cached API responses
* Environment: DOLLHOUSE_MAX_API_CACHE_SIZE
*/
readonly MAX_SIZE: number;
/**
* Maximum memory for API cache (MB)
* Environment: DOLLHOUSE_MAX_API_CACHE_MEMORY
*/
readonly MAX_MEMORY_MB: number;
};
};
/**
* Storage layer configuration
*
* Centralizes TTL, cooldown, and debounce values used by ElementStorageLayer,
* MemoryStorageLayer, and tool discovery caching. Each constant supports a
* DOLLHOUSE_* env var with a legacy fallback for backward compatibility.
*/
export declare const STORAGE_LAYER_CONFIG: {
/**
* Minimum interval between full directory scans (milliseconds)
* Prevents excessive I/O on rapid list() calls.
*
* Environment: DOLLHOUSE_SCAN_COOLDOWN_MS (legacy: ELEMENT_SCAN_COOLDOWN_MS)
*/
readonly SCAN_COOLDOWN_MS: number;
readonly MIN_SCAN_COOLDOWN_MS: 100;
readonly MAX_SCAN_COOLDOWN_MS: 60000;
/**
* Debounce interval for persisting _index.json in MemoryStorageLayer (milliseconds)
*
* Environment: DOLLHOUSE_INDEX_DEBOUNCE_MS (legacy: MEMORY_INDEX_DEBOUNCE_MS)
*/
readonly INDEX_DEBOUNCE_MS: number;
readonly MIN_INDEX_DEBOUNCE_MS: 100;
readonly MAX_INDEX_DEBOUNCE_MS: 30000;
/**
* TTL for element LRU caches in BaseElementManager (milliseconds)
* Default: 1 hour. This is a safety net only — the storage layer's mtime-based
* scanning handles real freshness detection. Set to 0 to disable TTL entirely.
*
* Environment: DOLLHOUSE_ELEMENT_CACHE_TTL_MS (legacy: ELEMENT_CACHE_TTL_MS)
*/
readonly ELEMENT_CACHE_TTL_MS: number;
readonly MIN_ELEMENT_CACHE_TTL_MS: 0;
readonly MAX_ELEMENT_CACHE_TTL_MS: 3600000;
/**
* TTL for file-path-to-ID reverse index caches (milliseconds)
* Default: 1 hour. Set to 0 to disable TTL (rely on storage layer mtime scanning).
*
* Environment: DOLLHOUSE_PATH_CACHE_TTL_MS (legacy: ELEMENT_PATH_CACHE_TTL_MS)
*/
readonly PATH_CACHE_TTL_MS: number;
readonly MIN_PATH_CACHE_TTL_MS: 0;
readonly MAX_PATH_CACHE_TTL_MS: 3600000;
/**
* TTL for tool discovery cache in ServerSetup (milliseconds)
*
* Environment: DOLLHOUSE_TOOL_CACHE_TTL_MS
*/
readonly TOOL_CACHE_TTL_MS: number;
readonly MIN_TOOL_CACHE_TTL_MS: 5000;
readonly MAX_TOOL_CACHE_TTL_MS: 600000;
/**
* Global memory budget for all registered LRU caches (bytes)
* Provides a cross-cache ceiling that triggers eviction from the least-active
* cache when the aggregate memory usage exceeds this limit.
*
* Environment: DOLLHOUSE_GLOBAL_CACHE_MEMORY_MB (default: 150 MB)
*/
readonly GLOBAL_CACHE_MEMORY_BYTES: number;
readonly MIN_GLOBAL_CACHE_MEMORY_MB: 20;
readonly MAX_GLOBAL_CACHE_MEMORY_MB: 1000;
/**
* Maximum backup files to keep per memory name per date folder.
* When a new backup is created and the count exceeds this limit,
* the oldest backups for that memory are deleted.
*
* Environment: DOLLHOUSE_MAX_BACKUPS_PER_MEMORY (default: 3)
*/
readonly MAX_BACKUPS_PER_MEMORY: number;
readonly MIN_BACKUPS_PER_MEMORY: 1;
readonly MAX_BACKUPS_PER_MEMORY_LIMIT: 50;
/**
* Maximum backup files to keep per element per date folder (all non-memory types).
* When a new backup is created and the count exceeds this limit,
* the oldest backups for that element are deleted.
*
* Environment: DOLLHOUSE_MAX_BACKUPS_PER_ELEMENT (default: 3)
*/
readonly MAX_BACKUPS_PER_ELEMENT: number;
readonly MIN_BACKUPS_PER_ELEMENT: 1;
readonly MAX_BACKUPS_PER_ELEMENT_LIMIT: 50;
/**
* Whether element backups are enabled.
* Set to 'false' to disable automatic pre-save and pre-delete backups.
*
* Environment: DOLLHOUSE_BACKUPS_ENABLED (default: true)
*/
readonly BACKUPS_ENABLED: boolean;
/**
* Maximum age in days for backup date folders.
* Date folders older than this are eligible for automatic cleanup.
* Set to 0 to disable age-based cleanup.
*
* Environment: DOLLHOUSE_BACKUP_RETENTION_DAYS (default: 7)
*/
readonly BACKUP_RETENTION_DAYS: number;
readonly MIN_BACKUP_RETENTION_DAYS: 1;
readonly MAX_BACKUP_RETENTION_DAYS: 365;
/**
* Debounce window for memory saves (milliseconds).
* When addEntry is called rapidly, saves are coalesced — only the latest
* state is written to disk after this delay. Prevents FD exhaustion from
* high-frequency memory updates (Issue #656).
*
* Environment: DOLLHOUSE_MEMORY_SAVE_DEBOUNCE_MS (default: 2000)
*/
readonly MEMORY_SAVE_DEBOUNCE_MS: number;
readonly MIN_MEMORY_SAVE_DEBOUNCE_MS: 500;
readonly MAX_MEMORY_SAVE_DEBOUNCE_MS: 30000;
/**
* Save frequency monitoring window (milliseconds).
* Tracks addEntry calls per memory within this window.
* When a memory exceeds MEMORY_SAVE_FREQUENCY_WARN_THRESHOLD
* calls in this window, a warning is logged.
*
* Issue #657: Detect runaway save loops before they exhaust resources.
*
* Environment: DOLLHOUSE_MEMORY_SAVE_MONITOR_WINDOW_MS (default: 60000 = 1 minute)
*/
readonly MEMORY_SAVE_MONITOR_WINDOW_MS: number;
/**
* Warn threshold: number of addEntry calls per memory per monitor window.
* If exceeded, log a warning. Default: 50 calls/minute. Range: 5–10000.
*
* Environment: DOLLHOUSE_MEMORY_SAVE_FREQUENCY_WARN (default: 50)
*/
readonly MEMORY_SAVE_FREQUENCY_WARN_THRESHOLD: number;
/**
* Critical threshold: number of addEntry calls per memory per monitor window.
* If exceeded, log an error-level alert. Default: 200 calls/minute. Range: 10–50000.
*
* Environment: DOLLHOUSE_MEMORY_SAVE_FREQUENCY_CRITICAL (default: 200)
*/
readonly MEMORY_SAVE_FREQUENCY_CRITICAL_THRESHOLD: number;
};
/**
* Get validated scan cooldown within acceptable bounds
*/
export declare function getValidatedScanCooldown(): number;
/**
* Get validated index debounce within acceptable bounds
*/
export declare function getValidatedIndexDebounce(): number;
/**
* Get validated element cache TTL within acceptable bounds
*/
export declare function getValidatedElementCacheTTL(): number;
/**
* Get validated path cache TTL within acceptable bounds
*/
export declare function getValidatedPathCacheTTL(): number;
/**
* Get validated tool cache TTL within acceptable bounds
*/
export declare function getValidatedToolCacheTTL(): number;
/**
* Get validated max backups per element within acceptable bounds
*/
export declare function getValidatedMaxBackupsPerElement(): number;
/**
* Get validated global cache memory budget in bytes
*/
export declare function getValidatedGlobalCacheMemoryBytes(): number;
/**
* Environment variable names for documentation and tooling
*/
export declare const ENV_VARS: {
readonly LOCK_TIMEOUT: "DOLLHOUSE_LOCK_TIMEOUT";
readonly LOCK_STALE_THRESHOLD: "DOLLHOUSE_LOCK_STALE_THRESHOLD";
readonly LOCK_MAX_RETRIES: "DOLLHOUSE_LOCK_MAX_RETRIES";
readonly LOCK_RETRY_DELAY: "DOLLHOUSE_LOCK_RETRY_DELAY";
readonly METRICS_BATCH_SIZE: "DOLLHOUSE_METRICS_BATCH_SIZE";
readonly METRICS_FLUSH_INTERVAL: "DOLLHOUSE_METRICS_FLUSH_INTERVAL";
readonly CACHE_SAMPLE_SIZE: "DOLLHOUSE_CACHE_SAMPLE_SIZE";
readonly SCAN_COOLDOWN: "DOLLHOUSE_SCAN_COOLDOWN_MS";
readonly INDEX_DEBOUNCE: "DOLLHOUSE_INDEX_DEBOUNCE_MS";
readonly ELEMENT_CACHE_TTL: "DOLLHOUSE_ELEMENT_CACHE_TTL_MS";
readonly PATH_CACHE_TTL: "DOLLHOUSE_PATH_CACHE_TTL_MS";
readonly TOOL_CACHE_TTL: "DOLLHOUSE_TOOL_CACHE_TTL_MS";
readonly GLOBAL_CACHE_MEMORY: "DOLLHOUSE_GLOBAL_CACHE_MEMORY_MB";
readonly MAX_BACKUPS_PER_ELEMENT: "DOLLHOUSE_MAX_BACKUPS_PER_ELEMENT";
readonly BACKUPS_ENABLED: "DOLLHOUSE_BACKUPS_ENABLED";
readonly MAX_PERSONA_CACHE_SIZE: "DOLLHOUSE_MAX_PERSONA_CACHE_SIZE";
readonly MAX_PERSONA_CACHE_MEMORY: "DOLLHOUSE_MAX_PERSONA_CACHE_MEMORY";
readonly MAX_METRICS_CACHE_SIZE: "DOLLHOUSE_MAX_METRICS_CACHE_SIZE";
readonly MAX_METRICS_CACHE_MEMORY: "DOLLHOUSE_MAX_METRICS_CACHE_MEMORY";
readonly MAX_SEARCH_CACHE_SIZE: "DOLLHOUSE_MAX_SEARCH_CACHE_SIZE";
readonly MAX_SEARCH_CACHE_MEMORY: "DOLLHOUSE_MAX_SEARCH_CACHE_MEMORY";
readonly MAX_INDEX_CACHE_SIZE: "DOLLHOUSE_MAX_INDEX_CACHE_SIZE";
readonly MAX_INDEX_CACHE_MEMORY: "DOLLHOUSE_MAX_INDEX_CACHE_MEMORY";
readonly MAX_API_CACHE_SIZE: "DOLLHOUSE_MAX_API_CACHE_SIZE";
readonly MAX_API_CACHE_MEMORY: "DOLLHOUSE_MAX_API_CACHE_MEMORY";
};
/**
* Validation Helpers
*/
/**
* Get validated lock timeout within acceptable bounds
*
* @returns Validated timeout in milliseconds (1s - 60s)
*
* @example
* ```typescript
* const timeout = getValidatedLockTimeout();
* // Returns value between 1000 and 60000
* ```
*/
export declare function getValidatedLockTimeout(): number;
/**
* Get validated metrics batch size within acceptable bounds
*
* @returns Validated batch size (1 - 1000)
*
* @example
* ```typescript
* const batchSize = getValidatedBatchSize();
* // Returns value between 1 and 1000
* ```
*/
export declare function getValidatedBatchSize(): number;
/**
* Get validated metrics flush interval within acceptable bounds
*
* @returns Validated flush interval in milliseconds (100ms - 5min)
*
* @example
* ```typescript
* const interval = getValidatedFlushInterval();
* // Returns value between 100 and 300000
* ```
*/
export declare function getValidatedFlushInterval(): number;
/**
* Get validated cache sample size for balanced estimation mode
*
* @returns Validated sample size (1 - 100)
*
* @example
* ```typescript
* const sampleSize = getValidatedSampleSize();
* // Returns value between 1 and 100
* ```
*/
export declare function getValidatedSampleSize(): number;
/**
* Calculate retry delay using exponential backoff
*
* @param attempt - Current retry attempt number (1-based)
* @returns Delay in milliseconds for this attempt
*
* @example
* ```typescript
* const delay = calculateLockRetryDelay(3);
* // Returns 400ms (100 * 2^2)
* ```
*/
export declare function calculateLockRetryDelay(attempt: number): number;
//# sourceMappingURL=performance-constants.d.ts.map