@danielsimonjr/memory-mcp 0.47.1 → 9.8.0

package/dist/utils/constants.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Application Constants
+ *
+ * Centralized configuration constants for file paths, extensions, and default values.
+ *
+ * @module utils/constants
+ */
+/**
+ * File extensions used by the memory system.
+ */
+export declare const FILE_EXTENSIONS: {
+    /** JSONL format for line-delimited JSON storage */
+    readonly JSONL: ".jsonl";
+    /** Legacy JSON format (backward compatibility) */
+    readonly JSON: ".json";
+};
+/**
+ * File name suffixes for auxiliary data files.
+ * These suffixes are appended to the base memory file name.
+ */
+export declare const FILE_SUFFIXES: {
+    /** Suffix for saved searches file */
+    readonly SAVED_SEARCHES: "-saved-searches";
+    /** Suffix for tag aliases file */
+    readonly TAG_ALIASES: "-tag-aliases";
+};
+/**
+ * Default file names used by the memory system.
+ */
+export declare const DEFAULT_FILE_NAMES: {
+    /** Default memory file name */
+    readonly MEMORY: "memory";
+    /** Legacy memory file name (for backward compatibility) */
+    readonly MEMORY_LEGACY: "memory";
+};
+/**
+ * Environment variable names used for configuration.
+ */
+export declare const ENV_VARS: {
+    /** Environment variable for custom memory file path */
+    readonly MEMORY_FILE_PATH: "MEMORY_FILE_PATH";
+};
+/**
+ * Default base directory relative to the compiled code.
+ */
+export declare const DEFAULT_BASE_DIR = "../";
+/**
+ * Log message prefixes for consistent logging.
+ */
+export declare const LOG_PREFIXES: {
+    /** Informational message prefix */
+    readonly INFO: "[INFO]";
+    /** Error message prefix */
+    readonly ERROR: "[ERROR]";
+    /** Warning message prefix */
+    readonly WARN: "[WARN]";
+};
+/**
+ * Similarity scoring weights for duplicate detection.
+ * These weights determine the relative importance of each factor
+ * when calculating entity similarity for duplicate detection.
+ * Total weights must sum to 1.0 (100%).
+ */
+export declare const SIMILARITY_WEIGHTS: {
+    /** Name similarity weight (40%) - Uses Levenshtein distance */
+    readonly NAME: 0.4;
+    /** Entity type match weight (20%) - Exact match required */
+    readonly TYPE: 0.2;
+    /** Observation overlap weight (30%) - Uses Jaccard similarity */
+    readonly OBSERVATIONS: 0.3;
+    /** Tag overlap weight (10%) - Uses Jaccard similarity */
+    readonly TAGS: 0.1;
+};
+/**
+ * Default threshold for duplicate detection (80% similarity required).
+ */
+export declare const DEFAULT_DUPLICATE_THRESHOLD = 0.8;
+/**
+ * Search result limits to prevent resource exhaustion.
+ */
+export declare const SEARCH_LIMITS: {
+    /** Default number of results to return */
+    readonly DEFAULT: 50;
+    /** Maximum number of results allowed */
+    readonly MAX: 200;
+    /** Minimum number of results (must be at least 1) */
+    readonly MIN: 1;
+};
+/**
+ * Entity importance range validation constants.
+ * Importance is used to prioritize entities (0 = lowest, 10 = highest).
+ */
+export declare const IMPORTANCE_RANGE: {
+    /** Minimum importance value */
+    readonly MIN: 0;
+    /** Maximum importance value */
+    readonly MAX: 10;
+};
+/**
+ * Graph size limits to prevent resource exhaustion and ensure performance.
+ * These limits help maintain system stability and responsiveness.
+ */
+export declare const GRAPH_LIMITS: {
+    /** Maximum number of entities in the graph */
+    readonly MAX_ENTITIES: 100000;
+    /** Maximum number of relations in the graph */
+    readonly MAX_RELATIONS: 1000000;
+    /** Maximum graph file size in megabytes */
+    readonly MAX_FILE_SIZE_MB: 500;
+    /** Maximum observations per entity */
+    readonly MAX_OBSERVATIONS_PER_ENTITY: 1000;
+    /** Maximum tags per entity */
+    readonly MAX_TAGS_PER_ENTITY: 100;
+};
+/**
+ * Query complexity limits to prevent expensive query operations.
+ * These limits protect against denial-of-service through complex queries.
+ */
+export declare const QUERY_LIMITS: {
+    /** Maximum nesting depth for boolean queries */
+    readonly MAX_DEPTH: 10;
+    /** Maximum number of terms in a single query */
+    readonly MAX_TERMS: 50;
+    /** Maximum number of boolean operators (AND/OR/NOT) */
+    readonly MAX_OPERATORS: 20;
+    /** Maximum query string length */
+    readonly MAX_QUERY_LENGTH: 5000;
+};
+/**
+ * Brotli compression configuration constants.
+ * Brotli is built into Node.js >=11.7.0 via the zlib module.
+ * No external dependencies required.
+ *
+ * Quality levels determine compression ratio vs speed tradeoff:
+ * - Lower values (0-4): Faster compression, lower ratio
+ * - Higher values (9-11): Slower compression, higher ratio
+ */
+export declare const COMPRESSION_CONFIG: {
+    /** Fast compression for real-time entity writes (quality 4) */
+    readonly BROTLI_QUALITY_REALTIME: 4;
+    /** Balanced compression for exports and imports (quality 6) */
+    readonly BROTLI_QUALITY_BATCH: 6;
+    /** Maximum compression for backups and archives (quality 11) */
+    readonly BROTLI_QUALITY_ARCHIVE: 11;
+    /** Fast decompress for cache compression (quality 5) */
+    readonly BROTLI_QUALITY_CACHE: 5;
+    /** Auto-compress exports larger than 100KB */
+    readonly AUTO_COMPRESS_EXPORT_SIZE: number;
+    /** Auto-compress MCP responses larger than 256KB */
+    readonly AUTO_COMPRESS_RESPONSE_SIZE: number;
+    /** Always compress backups by default */
+    readonly AUTO_COMPRESS_BACKUP: true;
+    /** Brotli compressed file extension */
+    readonly BROTLI_EXTENSION: ".br";
+    /** Chunk size for streaming compression (64KB) */
+    readonly COMPRESSION_CHUNK_SIZE: 65536;
+    /** Default window size for brotli (lgwin parameter) */
+    readonly COMPRESSION_WINDOW_SIZE: 22;
+};
+/**
+ * Type representing valid brotli quality levels used in the application.
+ */
+export type CompressionQuality = typeof COMPRESSION_CONFIG.BROTLI_QUALITY_REALTIME | typeof COMPRESSION_CONFIG.BROTLI_QUALITY_BATCH | typeof COMPRESSION_CONFIG.BROTLI_QUALITY_ARCHIVE | typeof COMPRESSION_CONFIG.BROTLI_QUALITY_CACHE;
+/**
+ * Environment variable names for embedding configuration.
+ */
+export declare const EMBEDDING_ENV_VARS: {
+    /** Embedding provider: 'openai', 'local', or 'none' (default: 'none') */
+    readonly PROVIDER: "MEMORY_EMBEDDING_PROVIDER";
+    /** OpenAI API key (required when provider is 'openai') */
+    readonly OPENAI_API_KEY: "MEMORY_OPENAI_API_KEY";
+    /** Optional model override for the embedding service */
+    readonly MODEL: "MEMORY_EMBEDDING_MODEL";
+    /** Auto-index entities on creation: 'true' or 'false' (default: 'false') */
+    readonly AUTO_INDEX: "MEMORY_AUTO_INDEX_EMBEDDINGS";
+};
+/**
+ * Default embedding configuration values.
+ */
+export declare const EMBEDDING_DEFAULTS: {
+    /** Default provider (disabled by default) */
+    readonly PROVIDER: "none";
+    /** Default OpenAI model for embeddings (1536 dimensions) */
+    readonly OPENAI_MODEL: "text-embedding-3-small";
+    /** Default local model for embeddings (384 dimensions) */
+    readonly LOCAL_MODEL: "Xenova/all-MiniLM-L6-v2";
+    /** OpenAI embedding dimensions for text-embedding-3-small */
+    readonly OPENAI_DIMENSIONS: 1536;
+    /** Local embedding dimensions for all-MiniLM-L6-v2 */
+    readonly LOCAL_DIMENSIONS: 384;
+    /** Maximum texts per batch for OpenAI */
+    readonly OPENAI_MAX_BATCH_SIZE: 2048;
+    /** Default batch size for embedding operations */
+    readonly DEFAULT_BATCH_SIZE: 100;
+    /** Whether to auto-index entities by default */
+    readonly AUTO_INDEX: false;
+};
+/**
+ * Semantic search configuration limits.
+ */
+export declare const SEMANTIC_SEARCH_LIMITS: {
+    /** Default number of results for semantic search */
+    readonly DEFAULT_LIMIT: 10;
+    /** Maximum number of results for semantic search */
+    readonly MAX_LIMIT: 100;
+    /** Minimum similarity score for results (0.0-1.0) */
+    readonly MIN_SIMILARITY: 0;
+};
+/**
+ * OpenAI API configuration.
+ */
+export declare const OPENAI_API_CONFIG: {
+    BASE_URL: string;
+    EMBEDDINGS_ENDPOINT: string;
+    MAX_RETRIES: number;
+    INITIAL_BACKOFF_MS: number;
+    MAX_BACKOFF_MS: number;
+};
+/**
+ * Get embedding configuration from environment variables.
+ *
+ * @returns EmbeddingConfig object with values from environment or defaults
+ */
+export declare function getEmbeddingConfig(): {
+    provider: 'openai' | 'local' | 'none';
+    apiKey?: string;
+    model?: string;
+    autoIndex: boolean;
+};
+/**
+ * Streaming export configuration.
+ *
+ * Controls when to use streaming mode and buffer sizes for optimal memory usage.
+ */
+export declare const STREAMING_CONFIG: {
+    /** Minimum entity count to trigger streaming mode */
+    readonly STREAMING_THRESHOLD: 5000;
+    /** Chunk size for batched streaming operations */
+    readonly CHUNK_SIZE: 500;
+    /** High water mark for stream buffers (bytes) */
+    readonly HIGH_WATER_MARK: number;
+    /** Flush interval for long-running streams (ms) */
+    readonly FLUSH_INTERVAL_MS: 100;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"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"}

package/dist/utils/constants.js

@@ -126,3 +126,127 @@ export const QUERY_LIMITS = {
     /** Maximum query string length */
     MAX_QUERY_LENGTH: 5000,
 };
+/**
+ * Brotli compression configuration constants.
+ * Brotli is built into Node.js >=11.7.0 via the zlib module.
+ * No external dependencies required.
+ *
+ * Quality levels determine compression ratio vs speed tradeoff:
+ * - Lower values (0-4): Faster compression, lower ratio
+ * - Higher values (9-11): Slower compression, higher ratio
+ */
+export const COMPRESSION_CONFIG = {
+    // Quality levels (0-11)
+    /** Fast compression for real-time entity writes (quality 4) */
+    BROTLI_QUALITY_REALTIME: 4,
+    /** Balanced compression for exports and imports (quality 6) */
+    BROTLI_QUALITY_BATCH: 6,
+    /** Maximum compression for backups and archives (quality 11) */
+    BROTLI_QUALITY_ARCHIVE: 11,
+    /** Fast decompress for cache compression (quality 5) */
+    BROTLI_QUALITY_CACHE: 5,
+    // Auto-compression thresholds (in bytes)
+    /** Auto-compress exports larger than 100KB */
+    AUTO_COMPRESS_EXPORT_SIZE: 100 * 1024,
+    /** Auto-compress MCP responses larger than 256KB */
+    AUTO_COMPRESS_RESPONSE_SIZE: 256 * 1024,
+    /** Always compress backups by default */
+    AUTO_COMPRESS_BACKUP: true,
+    // File extension for compressed files
+    /** Brotli compressed file extension */
+    BROTLI_EXTENSION: '.br',
+    // Performance tuning
+    /** Chunk size for streaming compression (64KB) */
+    COMPRESSION_CHUNK_SIZE: 65536,
+    /** Default window size for brotli (lgwin parameter) */
+    COMPRESSION_WINDOW_SIZE: 22,
+};
+// ==================== Semantic Search Configuration (Phase 4 Sprint 10-12) ====================
+/**
+ * Environment variable names for embedding configuration.
+ */
+export const EMBEDDING_ENV_VARS = {
+    /** Embedding provider: 'openai', 'local', or 'none' (default: 'none') */
+    PROVIDER: 'MEMORY_EMBEDDING_PROVIDER',
+    /** OpenAI API key (required when provider is 'openai') */
+    OPENAI_API_KEY: 'MEMORY_OPENAI_API_KEY',
+    /** Optional model override for the embedding service */
+    MODEL: 'MEMORY_EMBEDDING_MODEL',
+    /** Auto-index entities on creation: 'true' or 'false' (default: 'false') */
+    AUTO_INDEX: 'MEMORY_AUTO_INDEX_EMBEDDINGS',
+};
+/**
+ * Default embedding configuration values.
+ */
+export const EMBEDDING_DEFAULTS = {
+    /** Default provider (disabled by default) */
+    PROVIDER: 'none',
+    /** Default OpenAI model for embeddings (1536 dimensions) */
+    OPENAI_MODEL: 'text-embedding-3-small',
+    /** Default local model for embeddings (384 dimensions) */
+    LOCAL_MODEL: 'Xenova/all-MiniLM-L6-v2',
+    /** OpenAI embedding dimensions for text-embedding-3-small */
+    OPENAI_DIMENSIONS: 1536,
+    /** Local embedding dimensions for all-MiniLM-L6-v2 */
+    LOCAL_DIMENSIONS: 384,
+    /** Maximum texts per batch for OpenAI */
+    OPENAI_MAX_BATCH_SIZE: 2048,
+    /** Default batch size for embedding operations */
+    DEFAULT_BATCH_SIZE: 100,
+    /** Whether to auto-index entities by default */
+    AUTO_INDEX: false,
+};
+/**
+ * Semantic search configuration limits.
+ */
+export const SEMANTIC_SEARCH_LIMITS = {
+    /** Default number of results for semantic search */
+    DEFAULT_LIMIT: 10,
+    /** Maximum number of results for semantic search */
+    MAX_LIMIT: 100,
+    /** Minimum similarity score for results (0.0-1.0) */
+    MIN_SIMILARITY: 0.0,
+};
+/**
+ * OpenAI API configuration.
+ */
+export const OPENAI_API_CONFIG = {
+    /** Base URL for OpenAI API */
+    BASE_URL: 'https://api.openai.com/v1',
+    /** Embeddings endpoint */
+    EMBEDDINGS_ENDPOINT: '/embeddings',
+    /** Maximum retries for rate limiting */
+    MAX_RETRIES: 3,
+    /** Initial backoff delay in milliseconds */
+    INITIAL_BACKOFF_MS: 1000,
+    /** Maximum backoff delay in milliseconds */
+    MAX_BACKOFF_MS: 10000,
+};
+/**
+ * Get embedding configuration from environment variables.
+ *
+ * @returns EmbeddingConfig object with values from environment or defaults
+ */
+export function getEmbeddingConfig() {
+    const provider = (process.env[EMBEDDING_ENV_VARS.PROVIDER] || EMBEDDING_DEFAULTS.PROVIDER);
+    const apiKey = process.env[EMBEDDING_ENV_VARS.OPENAI_API_KEY];
+    const model = process.env[EMBEDDING_ENV_VARS.MODEL];
+    const autoIndex = process.env[EMBEDDING_ENV_VARS.AUTO_INDEX] === 'true';
+    return { provider, apiKey, model, autoIndex };
+}
+// ==================== Streaming Export Configuration (Phase 7 Sprint 1) ====================
+/**
+ * Streaming export configuration.
+ *
+ * Controls when to use streaming mode and buffer sizes for optimal memory usage.
+ */
+export const STREAMING_CONFIG = {
+    /** Minimum entity count to trigger streaming mode */
+    STREAMING_THRESHOLD: 5000,
+    /** Chunk size for batched streaming operations */
+    CHUNK_SIZE: 500,
+    /** High water mark for stream buffers (bytes) */
+    HIGH_WATER_MARK: 64 * 1024,
+    /** Flush interval for long-running streams (ms) */
+    FLUSH_INTERVAL_MS: 100,
+};