causantic 0.2.0

package/dist/config/loader.js

@@ -0,0 +1,339 @@
+/**
+ * Configuration loader with priority-based resolution.
+ *
+ * Priority (highest to lowest):
+ * 1. CLI flags (passed directly)
+ * 2. Environment variables (CAUSANTIC_*)
+ * 3. Project config file (./causantic.config.json)
+ * 4. User config file (~/.causantic/config.json)
+ * 5. Built-in defaults
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolvePath } from './memory-config.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('config-loader');
+/** Default external config values */
+const EXTERNAL_DEFAULTS = {
+    decay: {
+        backward: {
+            type: 'linear',
+            diesAtHops: 10,
+            holdHops: 0,
+        },
+        forward: {
+            type: 'delayed-linear',
+            diesAtHops: 20,
+            holdHops: 5,
+        },
+    },
+    clustering: {
+        threshold: 0.10,
+        minClusterSize: 4,
+    },
+    traversal: {
+        maxDepth: 15, // Limits latency on sparse graphs; raise for dense edge sets
+        minWeight: 0.01,
+        directHitBoost: 1.5,
+        graphAgreementBoost: 2.0,
+    },
+    tokens: {
+        claudeMdBudget: 500,
+        mcpMaxResponse: 2000,
+    },
+    storage: {
+        dbPath: '~/.causantic/memory.db',
+        vectorPath: '~/.causantic/vectors',
+    },
+    llm: {
+        clusterRefreshModel: 'claude-3-haiku-20240307',
+        refreshRateLimitPerMin: 30,
+    },
+    encryption: {
+        enabled: false,
+        cipher: 'chacha20',
+        keySource: 'keychain',
+        auditLog: false,
+    },
+    vectors: {
+        ttlDays: 90,
+    },
+    embedding: {
+        device: 'auto',
+    },
+    maintenance: {
+        clusterHour: 2,
+    },
+};
+/**
+ * Load config from a JSON file.
+ */
+function loadConfigFile(path) {
+    const resolvedPath = resolvePath(path);
+    if (!existsSync(resolvedPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(resolvedPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        log.warn(`Failed to parse config file ${path}`, { error: error.message });
+        return null;
+    }
+}
+/**
+ * Load config from environment variables.
+ * Variables are prefixed with CAUSANTIC_ and use underscores for nesting.
+ * Examples:
+ *   CAUSANTIC_DECAY_BACKWARD_TYPE=linear
+ *   CAUSANTIC_CLUSTERING_THRESHOLD=0.09
+ *   CAUSANTIC_STORAGE_DB_PATH=~/.causantic/memory.db
+ */
+function loadEnvConfig() {
+    const config = {};
+    // Decay backward
+    if (process.env.CAUSANTIC_DECAY_BACKWARD_TYPE) {
+        config.decay = config.decay ?? {};
+        config.decay.backward = config.decay.backward ?? {};
+        config.decay.backward.type = process.env.CAUSANTIC_DECAY_BACKWARD_TYPE;
+    }
+    if (process.env.CAUSANTIC_DECAY_BACKWARD_DIES_AT_HOPS) {
+        config.decay = config.decay ?? {};
+        config.decay.backward = config.decay.backward ?? {};
+        config.decay.backward.diesAtHops = parseInt(process.env.CAUSANTIC_DECAY_BACKWARD_DIES_AT_HOPS, 10);
+    }
+    if (process.env.CAUSANTIC_DECAY_BACKWARD_HOLD_HOPS) {
+        config.decay = config.decay ?? {};
+        config.decay.backward = config.decay.backward ?? {};
+        config.decay.backward.holdHops = parseInt(process.env.CAUSANTIC_DECAY_BACKWARD_HOLD_HOPS, 10);
+    }
+    // Decay forward
+    if (process.env.CAUSANTIC_DECAY_FORWARD_TYPE) {
+        config.decay = config.decay ?? {};
+        config.decay.forward = config.decay.forward ?? {};
+        config.decay.forward.type = process.env.CAUSANTIC_DECAY_FORWARD_TYPE;
+    }
+    if (process.env.CAUSANTIC_DECAY_FORWARD_DIES_AT_HOPS) {
+        config.decay = config.decay ?? {};
+        config.decay.forward = config.decay.forward ?? {};
+        config.decay.forward.diesAtHops = parseInt(process.env.CAUSANTIC_DECAY_FORWARD_DIES_AT_HOPS, 10);
+    }
+    if (process.env.CAUSANTIC_DECAY_FORWARD_HOLD_HOPS) {
+        config.decay = config.decay ?? {};
+        config.decay.forward = config.decay.forward ?? {};
+        config.decay.forward.holdHops = parseInt(process.env.CAUSANTIC_DECAY_FORWARD_HOLD_HOPS, 10);
+    }
+    // Clustering
+    if (process.env.CAUSANTIC_CLUSTERING_THRESHOLD) {
+        config.clustering = config.clustering ?? {};
+        config.clustering.threshold = parseFloat(process.env.CAUSANTIC_CLUSTERING_THRESHOLD);
+    }
+    if (process.env.CAUSANTIC_CLUSTERING_MIN_CLUSTER_SIZE) {
+        config.clustering = config.clustering ?? {};
+        config.clustering.minClusterSize = parseInt(process.env.CAUSANTIC_CLUSTERING_MIN_CLUSTER_SIZE, 10);
+    }
+    // Traversal
+    if (process.env.CAUSANTIC_TRAVERSAL_MAX_DEPTH) {
+        config.traversal = config.traversal ?? {};
+        config.traversal.maxDepth = parseInt(process.env.CAUSANTIC_TRAVERSAL_MAX_DEPTH, 10);
+    }
+    if (process.env.CAUSANTIC_TRAVERSAL_MIN_WEIGHT) {
+        config.traversal = config.traversal ?? {};
+        config.traversal.minWeight = parseFloat(process.env.CAUSANTIC_TRAVERSAL_MIN_WEIGHT);
+    }
+    // Tokens
+    if (process.env.CAUSANTIC_TOKENS_CLAUDE_MD_BUDGET) {
+        config.tokens = config.tokens ?? {};
+        config.tokens.claudeMdBudget = parseInt(process.env.CAUSANTIC_TOKENS_CLAUDE_MD_BUDGET, 10);
+    }
+    if (process.env.CAUSANTIC_TOKENS_MCP_MAX_RESPONSE) {
+        config.tokens = config.tokens ?? {};
+        config.tokens.mcpMaxResponse = parseInt(process.env.CAUSANTIC_TOKENS_MCP_MAX_RESPONSE, 10);
+    }
+    // Storage
+    if (process.env.CAUSANTIC_STORAGE_DB_PATH) {
+        config.storage = config.storage ?? {};
+        config.storage.dbPath = process.env.CAUSANTIC_STORAGE_DB_PATH;
+    }
+    if (process.env.CAUSANTIC_STORAGE_VECTOR_PATH) {
+        config.storage = config.storage ?? {};
+        config.storage.vectorPath = process.env.CAUSANTIC_STORAGE_VECTOR_PATH;
+    }
+    // LLM
+    if (process.env.CAUSANTIC_LLM_CLUSTER_REFRESH_MODEL) {
+        config.llm = config.llm ?? {};
+        config.llm.clusterRefreshModel = process.env.CAUSANTIC_LLM_CLUSTER_REFRESH_MODEL;
+    }
+    if (process.env.CAUSANTIC_LLM_REFRESH_RATE_LIMIT) {
+        config.llm = config.llm ?? {};
+        config.llm.refreshRateLimitPerMin = parseInt(process.env.CAUSANTIC_LLM_REFRESH_RATE_LIMIT, 10);
+    }
+    // Encryption
+    if (process.env.CAUSANTIC_ENCRYPTION_ENABLED) {
+        config.encryption = config.encryption ?? {};
+        config.encryption.enabled = process.env.CAUSANTIC_ENCRYPTION_ENABLED === 'true';
+    }
+    if (process.env.CAUSANTIC_ENCRYPTION_CIPHER) {
+        config.encryption = config.encryption ?? {};
+        config.encryption.cipher = process.env.CAUSANTIC_ENCRYPTION_CIPHER;
+    }
+    if (process.env.CAUSANTIC_ENCRYPTION_KEY_SOURCE) {
+        config.encryption = config.encryption ?? {};
+        config.encryption.keySource = process.env.CAUSANTIC_ENCRYPTION_KEY_SOURCE;
+    }
+    if (process.env.CAUSANTIC_ENCRYPTION_AUDIT_LOG) {
+        config.encryption = config.encryption ?? {};
+        config.encryption.auditLog = process.env.CAUSANTIC_ENCRYPTION_AUDIT_LOG === 'true';
+    }
+    // Vectors
+    if (process.env.CAUSANTIC_VECTORS_TTL_DAYS) {
+        config.vectors = config.vectors ?? {};
+        config.vectors.ttlDays = parseInt(process.env.CAUSANTIC_VECTORS_TTL_DAYS, 10);
+    }
+    // Maintenance
+    if (process.env.CAUSANTIC_MAINTENANCE_CLUSTER_HOUR) {
+        config.maintenance = config.maintenance ?? {};
+        config.maintenance.clusterHour = parseInt(process.env.CAUSANTIC_MAINTENANCE_CLUSTER_HOUR, 10);
+    }
+    // Embedding
+    if (process.env.CAUSANTIC_EMBEDDING_DEVICE) {
+        config.embedding = config.embedding ?? {};
+        config.embedding.device = process.env.CAUSANTIC_EMBEDDING_DEVICE;
+    }
+    return config;
+}
+/**
+ * Deep merge two config objects, with source overriding target.
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        if (sourceValue === undefined) {
+            continue;
+        }
+        if (typeof sourceValue === 'object' &&
+            sourceValue !== null &&
+            !Array.isArray(sourceValue) &&
+            typeof targetValue === 'object' &&
+            targetValue !== null &&
+            !Array.isArray(targetValue)) {
+            result[key] = {
+                ...targetValue,
+                ...sourceValue,
+            };
+        }
+        else {
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}
+/**
+ * Validate the external config structure.
+ */
+export function validateExternalConfig(config) {
+    const errors = [];
+    // Clustering validation
+    if (config.clustering?.threshold !== undefined) {
+        if (config.clustering.threshold <= 0 || config.clustering.threshold >= 1) {
+            errors.push('clustering.threshold must be between 0 and 1 (exclusive)');
+        }
+    }
+    if (config.clustering?.minClusterSize !== undefined) {
+        if (config.clustering.minClusterSize < 2) {
+            errors.push('clustering.minClusterSize must be at least 2');
+        }
+    }
+    // Decay validation
+    if (config.decay?.backward?.diesAtHops !== undefined) {
+        if (config.decay.backward.diesAtHops < 1) {
+            errors.push('decay.backward.diesAtHops must be at least 1');
+        }
+    }
+    if (config.decay?.forward?.diesAtHops !== undefined) {
+        if (config.decay.forward.diesAtHops < 1) {
+            errors.push('decay.forward.diesAtHops must be at least 1');
+        }
+    }
+    // Traversal validation
+    if (config.traversal?.maxDepth !== undefined) {
+        if (config.traversal.maxDepth < 1) {
+            errors.push('traversal.maxDepth must be at least 1');
+        }
+    }
+    if (config.traversal?.minWeight !== undefined) {
+        if (config.traversal.minWeight < 0 || config.traversal.minWeight > 1) {
+            errors.push('traversal.minWeight must be between 0 and 1');
+        }
+    }
+    // Token validation
+    if (config.tokens?.claudeMdBudget !== undefined) {
+        if (config.tokens.claudeMdBudget < 100) {
+            errors.push('tokens.claudeMdBudget should be at least 100');
+        }
+    }
+    if (config.tokens?.mcpMaxResponse !== undefined) {
+        if (config.tokens.mcpMaxResponse < 500) {
+            errors.push('tokens.mcpMaxResponse should be at least 500');
+        }
+    }
+    return errors;
+}
+/**
+ * Load configuration with priority-based resolution.
+ *
+ * Priority (highest to lowest):
+ * 1. CLI flags (cliOverrides)
+ * 2. Environment variables (CAUSANTIC_*)
+ * 3. Project config file (./causantic.config.json)
+ * 4. User config file (~/.causantic/config.json)
+ * 5. Built-in defaults
+ */
+export function loadConfig(options = {}) {
+    let config = { ...EXTERNAL_DEFAULTS };
+    // 5. Start with defaults (already done)
+    // 4. User config file
+    if (!options.skipUserConfig) {
+        const userConfigPath = options.userConfigPath ?? '~/.causantic/config.json';
+        const userConfig = loadConfigFile(userConfigPath);
+        if (userConfig) {
+            config = deepMerge(config, userConfig);
+        }
+    }
+    // 3. Project config file
+    if (!options.skipProjectConfig) {
+        const projectConfigPath = options.projectConfigPath ?? join(process.cwd(), 'causantic.config.json');
+        const projectConfig = loadConfigFile(projectConfigPath);
+        if (projectConfig) {
+            config = deepMerge(config, projectConfig);
+        }
+    }
+    // 2. Environment variables
+    if (!options.skipEnv) {
+        const envConfig = loadEnvConfig();
+        config = deepMerge(config, envConfig);
+    }
+    // 1. CLI overrides
+    if (options.cliOverrides) {
+        config = deepMerge(config, options.cliOverrides);
+    }
+    return config;
+}
+/**
+ * Get the resolved storage paths.
+ */
+export function getResolvedPaths(config) {
+    const storage = config.storage ?? EXTERNAL_DEFAULTS.storage;
+    const dbPath = storage.dbPath ?? EXTERNAL_DEFAULTS.storage.dbPath;
+    const vectorPath = storage.vectorPath ?? EXTERNAL_DEFAULTS.storage.vectorPath;
+    return {
+        dbPath: resolvePath(dbPath),
+        vectorPath: resolvePath(vectorPath),
+    };
+}
+// Re-export for convenience
+export { EXTERNAL_DEFAULTS };
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

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

package/dist/config/memory-config.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Centralized configuration for the Causantic Memory System.
+ */
+import type { DecayModelConfig } from '../core/decay-types.js';
+import { type VectorDecayConfig } from '../storage/decay.js';
+/**
+ * Short-range decay: 15min hold, optimized for immediate context recall.
+ * Best overall MRR (0.492) - good for recent references.
+ */
+export declare const DECAY_SHORT_RANGE: DecayModelConfig;
+/**
+ * Long-range decay: 60min hold, optimized for distant context recall.
+ * Best long-range MRR (0.560 for >3 turns) - good for cross-session memory.
+ */
+export declare const DECAY_LONG_RANGE: DecayModelConfig;
+/** @deprecated Use DECAY_SHORT_RANGE or DECAY_LONG_RANGE */
+export declare const DELAYED_LINEAR_30MIN: DecayModelConfig;
+/**
+ * Exponential decay with 10-minute half-life.
+ * Used for forward (prediction) edges.
+ */
+export declare const EXPONENTIAL_10MIN: DecayModelConfig;
+/**
+ * Complete memory system configuration.
+ */
+export interface MemoryConfig {
+    /** Angular distance threshold for assigning chunks to clusters */
+    clusterThreshold: number;
+    /** HDBSCAN minimum cluster size */
+    minClusterSize: number;
+    /** Decay model for short-range backward retrieval (recent context) */
+    shortRangeDecay: DecayModelConfig;
+    /** Decay model for long-range backward retrieval (distant context) */
+    longRangeDecay: DecayModelConfig;
+    /** Decay model for forward (prediction) edges */
+    forwardDecay: DecayModelConfig;
+    /**
+     * Legacy exponential vector decay (used by older experiment code).
+     * @deprecated Direction-specific hop decay is now automatic:
+     * - Backward: Linear (dies@10) for 4-20 hop range
+     * - Forward: Delayed linear (5h, dies@20) for 1-20 hop range
+     * See src/storage/decay.ts BACKWARD_HOP_DECAY and FORWARD_HOP_DECAY
+     */
+    vectorDecay: VectorDecayConfig;
+    /** Maximum graph traversal depth */
+    maxTraversalDepth: number;
+    /** Minimum signal threshold for traversal */
+    minSignalThreshold: number;
+    /** Boost multiplier for direct search hits (vector/keyword/cluster) */
+    directHitBoost: number;
+    /** Boost multiplier for graph agreement (chunks found by both vector and graph) */
+    graphAgreementBoost: number;
+    /** Token budget for CLAUDE.md memory section */
+    claudeMdBudgetTokens: number;
+    /** Maximum tokens for MCP tool responses */
+    mcpMaxResponseTokens: number;
+    /** Model to use for cluster description refresh */
+    clusterRefreshModel: string;
+    /** Rate limit for refresh calls (per minute) */
+    refreshRateLimitPerMin: number;
+    /** Configuration for hybrid BM25 + vector search */
+    hybridSearch: {
+        /** RRF constant (default: 60) */
+        rrfK: number;
+        /** Weight for vector results in RRF */
+        vectorWeight: number;
+        /** Weight for keyword results in RRF */
+        keywordWeight: number;
+        /** Max keyword results before fusion */
+        keywordSearchLimit: number;
+    };
+    /** Configuration for cluster expansion during retrieval */
+    clusterExpansion: {
+        /** Max clusters to expand from */
+        maxClusters: number;
+        /** Max siblings per cluster */
+        maxSiblings: number;
+        /** Score multiplier for cluster siblings */
+        boostFactor: number;
+    };
+    /** Path to SQLite database file */
+    dbPath: string;
+    /** Path to LanceDB vector store directory */
+    vectorStorePath: string;
+}
+/**
+ * Default configuration values.
+ * Cluster threshold: 0.10 balances coverage and separation on large collections.
+ * Phase 0.1 calibrated F1=0.940 at 0.09; bumped to 0.10 after noise rescue
+ * pass doubled cluster coverage (26% → 50%) on a 7k-chunk dataset.
+ */
+export declare const DEFAULT_CONFIG: MemoryConfig;
+/**
+ * Get configuration with overrides applied.
+ */
+export declare function getConfig(overrides?: Partial<MemoryConfig>): MemoryConfig;
+/**
+ * Resolve ~ to home directory in paths.
+ */
+export declare function resolvePath(path: string): string;
+/**
+ * Validate configuration values.
+ */
+export declare function validateConfig(config: MemoryConfig): string[];
+/**
+ * Hold period variants for Phase 0 experiments.
+ */
+export declare const HOLD_PERIOD_VARIANTS: DecayModelConfig[];
+//# sourceMappingURL=memory-config.d.ts.map

package/dist/config/memory-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-config.d.ts","sourceRoot":"","sources":["../../src/config/memory-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EAAE,KAAK,iBAAiB,EAAwB,MAAM,qBAAqB,CAAC;AAEnF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAQ/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAQ9B,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,EAAE,gBAQlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAO/B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAE3B,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IAGvB,sEAAsE;IACtE,eAAe,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,cAAc,EAAE,gBAAgB,CAAC;IACjC,iDAAiD;IACjD,YAAY,EAAE,gBAAgB,CAAC;IAC/B;;;;;;OAMG;IACH,WAAW,EAAE,iBAAiB,CAAC;IAG/B,oCAAoC;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,mBAAmB,EAAE,MAAM,CAAC;IAG5B,gDAAgD;IAChD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,oBAAoB,EAAE,MAAM,CAAC;IAG7B,mDAAmD;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,sBAAsB,EAAE,MAAM,CAAC;IAG/B,oDAAoD;IACpD,YAAY,EAAE;QACZ,iCAAiC;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,uCAAuC;QACvC,YAAY,EAAE,MAAM,CAAC;QACrB,wCAAwC;QACxC,aAAa,EAAE,MAAM,CAAC;QACtB,wCAAwC;QACxC,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IAEF,2DAA2D;IAC3D,gBAAgB,EAAE;QAChB,kCAAkC;QAClC,WAAW,EAAE,MAAM,CAAC;QACpB,+BAA+B;QAC/B,WAAW,EAAE,MAAM,CAAC;QACpB,4CAA4C;QAC5C,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IAGF,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,YA4C5B,CAAC;AAEF;;GAEG;AACH,wBAAgB,SAAS,CAAC,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,YAAY,CAE7E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMhD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAgC7D;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAAgB,EA6BlD,CAAC"}

package/dist/config/memory-config.js

@@ -0,0 +1,182 @@
+/**
+ * Centralized configuration for the Causantic Memory System.
+ */
+import { MS_PER_MINUTE, MS_PER_HOUR } from '../core/decay-types.js';
+import { DEFAULT_VECTOR_DECAY } from '../storage/decay.js';
+/**
+ * Short-range decay: 15min hold, optimized for immediate context recall.
+ * Best overall MRR (0.492) - good for recent references.
+ */
+export const DECAY_SHORT_RANGE = {
+    id: 'delayed-linear-15min',
+    name: 'Short-Range (15min hold)',
+    description: 'Optimized for immediate context - 15min hold, then decay',
+    type: 'delayed-linear',
+    initialWeight: 1.0,
+    holdPeriodMs: 15 * MS_PER_MINUTE,
+    decayRate: 1.0 / (2 * MS_PER_HOUR),
+};
+/**
+ * Long-range decay: 60min hold, optimized for distant context recall.
+ * Best long-range MRR (0.560 for >3 turns) - good for cross-session memory.
+ */
+export const DECAY_LONG_RANGE = {
+    id: 'delayed-linear-60min',
+    name: 'Long-Range (60min hold)',
+    description: 'Optimized for distant context - 60min hold, then slower decay',
+    type: 'delayed-linear',
+    initialWeight: 1.0,
+    holdPeriodMs: 60 * MS_PER_MINUTE,
+    decayRate: 1.0 / (3 * MS_PER_HOUR), // Slower decay for long-range
+};
+/** @deprecated Use DECAY_SHORT_RANGE or DECAY_LONG_RANGE */
+export const DELAYED_LINEAR_30MIN = {
+    id: 'delayed-linear-30min',
+    name: 'Delayed Linear (30min hold)',
+    description: 'Full weight for 30 minutes, then linear decay over 2 hours',
+    type: 'delayed-linear',
+    initialWeight: 1.0,
+    holdPeriodMs: 30 * MS_PER_MINUTE,
+    decayRate: 1.0 / (2 * MS_PER_HOUR),
+};
+/**
+ * Exponential decay with 10-minute half-life.
+ * Used for forward (prediction) edges.
+ */
+export const EXPONENTIAL_10MIN = {
+    id: 'exponential-10min',
+    name: 'Exponential (10min half-life)',
+    description: 'Exponential decay with 10-minute half-life for prediction',
+    type: 'exponential',
+    initialWeight: 1.0,
+    decayRate: Math.log(2) / (10 * MS_PER_MINUTE),
+};
+/**
+ * Default configuration values.
+ * Cluster threshold: 0.10 balances coverage and separation on large collections.
+ * Phase 0.1 calibrated F1=0.940 at 0.09; bumped to 0.10 after noise rescue
+ * pass doubled cluster coverage (26% → 50%) on a 7k-chunk dataset.
+ */
+export const DEFAULT_CONFIG = {
+    // Clustering
+    clusterThreshold: 0.10,
+    minClusterSize: 4,
+    // Time-based decay (fallback) - based on Phase 0.2 experiment results
+    shortRangeDecay: DECAY_SHORT_RANGE, // 15min hold, best for recent (MRR=0.492)
+    longRangeDecay: DECAY_LONG_RANGE, // 60min hold, best for distant (MRR=0.560)
+    forwardDecay: EXPONENTIAL_10MIN,
+    // Direction-specific hop decay is now automatic (see decay.ts):
+    // - Backward: Linear (dies@10) - MRR=0.688 (+35% vs exponential)
+    // - Forward: Delayed (5h, dies@20) - MRR=0.849 (+271% vs exponential)
+    vectorDecay: DEFAULT_VECTOR_DECAY, // Legacy fallback only
+    // Traversal
+    maxTraversalDepth: 15, // Limits latency on sparse graphs; raise for dense edge sets
+    minSignalThreshold: 0.01,
+    directHitBoost: 1.5,
+    graphAgreementBoost: 2.0,
+    // Integration
+    claudeMdBudgetTokens: 500,
+    mcpMaxResponseTokens: 2000,
+    // LLM refresh
+    clusterRefreshModel: 'claude-3-haiku-20240307',
+    refreshRateLimitPerMin: 30, // Haiku can handle much higher rates
+    // Hybrid search
+    hybridSearch: {
+        rrfK: 60,
+        vectorWeight: 1.0,
+        keywordWeight: 1.0,
+        keywordSearchLimit: 20,
+    },
+    clusterExpansion: {
+        maxClusters: 3,
+        maxSiblings: 5,
+        boostFactor: 0.3,
+    },
+    // Storage - defaults to ~/.causantic/
+    dbPath: '~/.causantic/memory.db',
+    vectorStorePath: '~/.causantic/vectors',
+};
+/**
+ * Get configuration with overrides applied.
+ */
+export function getConfig(overrides = {}) {
+    return { ...DEFAULT_CONFIG, ...overrides };
+}
+/**
+ * Resolve ~ to home directory in paths.
+ */
+export function resolvePath(path) {
+    if (path.startsWith('~')) {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        return path.replace('~', home);
+    }
+    return path;
+}
+/**
+ * Validate configuration values.
+ */
+export function validateConfig(config) {
+    const errors = [];
+    if (config.clusterThreshold <= 0 || config.clusterThreshold >= 1) {
+        errors.push('clusterThreshold must be between 0 and 1 (exclusive)');
+    }
+    if (config.minClusterSize < 2) {
+        errors.push('minClusterSize must be at least 2');
+    }
+    if (config.maxTraversalDepth < 1) {
+        errors.push('maxTraversalDepth must be at least 1');
+    }
+    if (config.minSignalThreshold < 0 || config.minSignalThreshold > 1) {
+        errors.push('minSignalThreshold must be between 0 and 1');
+    }
+    if (config.claudeMdBudgetTokens < 100) {
+        errors.push('claudeMdBudgetTokens should be at least 100');
+    }
+    if (config.mcpMaxResponseTokens < 500) {
+        errors.push('mcpMaxResponseTokens should be at least 500');
+    }
+    if (config.refreshRateLimitPerMin < 0) {
+        errors.push('refreshRateLimitPerMin cannot be negative');
+    }
+    if (config.directHitBoost < 0) {
+        errors.push('directHitBoost cannot be negative');
+    }
+    if (config.graphAgreementBoost < 0) {
+        errors.push('graphAgreementBoost cannot be negative');
+    }
+    return errors;
+}
+/**
+ * Hold period variants for Phase 0 experiments.
+ */
+export const HOLD_PERIOD_VARIANTS = [
+    {
+        id: 'delayed-linear-15min',
+        name: 'Delayed Linear (15min hold)',
+        description: 'Full weight for 15 minutes, then linear decay over 2 hours',
+        type: 'delayed-linear',
+        initialWeight: 1.0,
+        holdPeriodMs: 15 * MS_PER_MINUTE,
+        decayRate: 1.0 / (2 * MS_PER_HOUR),
+    },
+    DELAYED_LINEAR_30MIN,
+    {
+        id: 'delayed-linear-45min',
+        name: 'Delayed Linear (45min hold)',
+        description: 'Full weight for 45 minutes, then linear decay over 2 hours',
+        type: 'delayed-linear',
+        initialWeight: 1.0,
+        holdPeriodMs: 45 * MS_PER_MINUTE,
+        decayRate: 1.0 / (2 * MS_PER_HOUR),
+    },
+    {
+        id: 'delayed-linear-60min',
+        name: 'Delayed Linear (60min hold)',
+        description: 'Full weight for 60 minutes, then linear decay over 2 hours',
+        type: 'delayed-linear',
+        initialWeight: 1.0,
+        holdPeriodMs: 60 * MS_PER_MINUTE,
+        decayRate: 1.0 / (2 * MS_PER_HOUR),
+    },
+];
+//# sourceMappingURL=memory-config.js.map

package/dist/config/memory-config.js.map

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