claude-brain 0.3.0

package/src/config/loader.ts

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { config as loadEnv } from 'dotenv'
+import { ConfigSchema, type Config, type PartialConfig } from './schema'
+import { defaultConfig } from './defaults'
+import { getClaudeBrainHome, resolveHomePath } from './home'
+
+const CONFIG_FILE_NAME = '.claudebrainrc.json'
+
+/** Load configuration from a JSON file if it exists */
+function loadFromFile(basePath: string): PartialConfig {
+  // Check basePath first, then Claude Brain home
+  for (const dir of [basePath, getClaudeBrainHome()]) {
+    const configPath = resolve(dir, CONFIG_FILE_NAME)
+    if (!existsSync(configPath)) {
+      continue
+    }
+
+    try {
+      const content = readFileSync(configPath, 'utf-8')
+      return JSON.parse(content) as PartialConfig
+    } catch (error) {
+      console.warn(`Warning: Failed to parse config file at ${configPath}:`, error)
+      return {}
+    }
+  }
+
+  return {}
+}
+
+/** Load configuration from environment variables */
+function loadFromEnv(): PartialConfig {
+  // Skip .env loading if SKIP_DOTENV is set (for MCP servers where env is provided externally)
+  if (!process.env.SKIP_DOTENV) {
+    // Load .env from Claude Brain home directory
+    loadEnv({ path: resolve(getClaudeBrainHome(), '.env'), debug: false })
+  }
+
+  const config: PartialConfig = {}
+
+  if (process.env.VAULT_PATH) {
+    config.vaultPath = process.env.VAULT_PATH
+  }
+  if (process.env.MCP_SERVER_NAME) {
+    config.serverName = process.env.MCP_SERVER_NAME
+  }
+  if (process.env.MCP_SERVER_VERSION) {
+    config.serverVersion = process.env.MCP_SERVER_VERSION
+  }
+  if (process.env.LOG_LEVEL) {
+    config.logLevel = process.env.LOG_LEVEL as Config['logLevel']
+  }
+  if (process.env.LOG_FILE_PATH) {
+    config.logFilePath = process.env.LOG_FILE_PATH
+  }
+  if (process.env.DB_PATH) {
+    config.dbPath = process.env.DB_PATH
+  }
+  if (process.env.PORT) {
+    config.port = parseInt(process.env.PORT, 10)
+  }
+  if (process.env.ENABLE_FILE_WATCH) {
+    config.enableFileWatch = process.env.ENABLE_FILE_WATCH === 'true'
+  }
+  if (process.env.CACHE_SIZE) {
+    config.cacheSize = parseInt(process.env.CACHE_SIZE, 10)
+  }
+  if (process.env.NODE_ENV) {
+    config.nodeEnv = process.env.NODE_ENV as Config['nodeEnv']
+  }
+
+  // Retrieval configuration
+  if (process.env.RETRIEVAL_ENABLED) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.enabled = process.env.RETRIEVAL_ENABLED === 'true'
+  }
+  if (process.env.RETRIEVAL_DENSE_WEIGHT) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.dense = config.retrieval.dense || {}
+    config.retrieval.dense.weight = parseFloat(process.env.RETRIEVAL_DENSE_WEIGHT)
+  }
+  if (process.env.RETRIEVAL_SPARSE_ENABLED) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.sparse = config.retrieval.sparse || {}
+    config.retrieval.sparse.enabled = process.env.RETRIEVAL_SPARSE_ENABLED === 'true'
+  }
+  if (process.env.RETRIEVAL_SPARSE_WEIGHT) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.sparse = config.retrieval.sparse || {}
+    config.retrieval.sparse.weight = parseFloat(process.env.RETRIEVAL_SPARSE_WEIGHT)
+  }
+  if (process.env.RETRIEVAL_FUSION_METHOD) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.fusion = config.retrieval.fusion || {}
+    config.retrieval.fusion.method = process.env.RETRIEVAL_FUSION_METHOD as 'rrf' | 'linear' | 'max'
+  }
+  if (process.env.RETRIEVAL_RRF_K) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.fusion = config.retrieval.fusion || {}
+    config.retrieval.fusion.rrfK = parseInt(process.env.RETRIEVAL_RRF_K, 10)
+  }
+  if (process.env.RETRIEVAL_RERANKER_ENABLED) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.reranker = config.retrieval.reranker || {}
+    config.retrieval.reranker.enabled = process.env.RETRIEVAL_RERANKER_ENABLED === 'true'
+  }
+  if (process.env.RETRIEVAL_RERANKER_MODEL) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.reranker = config.retrieval.reranker || {}
+    config.retrieval.reranker.model = process.env.RETRIEVAL_RERANKER_MODEL
+  }
+  if (process.env.RETRIEVAL_FEEDBACK_ENABLED) {
+    config.retrieval = config.retrieval || {}
+    config.retrieval.feedback = config.retrieval.feedback || {}
+    config.retrieval.feedback.enabled = process.env.RETRIEVAL_FEEDBACK_ENABLED === 'true'
+  }
+
+  return config
+}
+
+/** Merge multiple partial configs, later values override earlier */
+function mergeConfigs(...configs: PartialConfig[]): PartialConfig {
+  return configs.reduce((acc, config) => {
+    return { ...acc, ...Object.fromEntries(Object.entries(config).filter(([_, v]) => v !== undefined)) }
+  }, {})
+}
+
+/** Load and validate configuration from all sources */
+export async function loadConfig(basePath: string = process.cwd()): Promise<Config> {
+  const fileConfig = loadFromFile(basePath)
+  const envConfig = loadFromEnv()
+
+  const merged = mergeConfigs(defaultConfig, fileConfig, envConfig)
+
+  const result = ConfigSchema.safeParse(merged)
+
+  if (!result.success) {
+    const errors = result.error.errors
+      .map(e => `  - ${e.path.join('.')}: ${e.message}`)
+      .join('\n')
+    throw new Error(`Configuration validation failed:\n${errors}`)
+  }
+
+  // Resolve relative paths against Claude Brain home
+  const data = result.data
+  data.logFilePath = resolveHomePath(data.logFilePath)
+  data.dbPath = resolveHomePath(data.dbPath)
+  if (data.chroma.path) {
+    data.chroma.path = resolveHomePath(data.chroma.path)
+  }
+  if (data.knowledge?.graph?.persistPath) {
+    data.knowledge.graph.persistPath = resolveHomePath(data.knowledge.graph.persistPath)
+  }
+
+  return data
+}
+
+/** Validate a partial configuration object */
+export function validateConfig(config: unknown): config is Config {
+  return ConfigSchema.safeParse(config).success
+}
+
+/** Get the path to the config file */
+export function getConfigFilePath(basePath: string = process.cwd()): string {
+  return resolve(basePath, CONFIG_FILE_NAME)
+}

package/src/config/migration.ts

@@ -0,0 +1,76 @@
+import fs from 'fs/promises'
+import type { Logger } from 'pino'
+
+export interface ConfigVersion {
+  version: string
+  config: Record<string, any>
+}
+
+export class ConfigMigration {
+  private logger: Logger
+  private currentVersion = '1.0.0'
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'config-migration' })
+  }
+
+  async migrate(config: any): Promise<any> {
+    const configVersion = config.version || '0.0.0'
+
+    if (configVersion === this.currentVersion) {
+      return config
+    }
+
+    this.logger.info(
+      { from: configVersion, to: this.currentVersion },
+      'Migrating configuration'
+    )
+
+    await this.backup(config)
+
+    let migrated = { ...config }
+
+    if (this.compareVersions(configVersion, '1.0.0') < 0) {
+      migrated = await this.migrateTo_1_0_0(migrated)
+    }
+
+    migrated.version = this.currentVersion
+
+    return migrated
+  }
+
+  private async migrateTo_1_0_0(config: any): Promise<any> {
+    this.logger.info('Migrating to version 1.0.0')
+
+    return {
+      ...config,
+      enableFileWatch: config.enableFileWatch ?? true,
+      serverVersion: config.serverVersion || '1.0.0'
+    }
+  }
+
+  private async backup(config: any): Promise<void> {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+    const backupPath = `./data/config-backup-${timestamp}.json`
+
+    await fs.writeFile(
+      backupPath,
+      JSON.stringify(config, null, 2),
+      'utf-8'
+    )
+
+    this.logger.info({ backupPath }, 'Configuration backed up')
+  }
+
+  private compareVersions(v1: string, v2: string): number {
+    const parts1 = v1.split('.').map(Number)
+    const parts2 = v2.split('.').map(Number)
+
+    for (let i = 0; i < 3; i++) {
+      if (parts1[i] > parts2[i]) return 1
+      if (parts1[i] < parts2[i]) return -1
+    }
+
+    return 0
+  }
+}

package/src/config/schema.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod'
+
+/** Log level options for the application */
+export const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error'])
+export type LogLevel = z.infer<typeof LogLevelSchema>
+
+/** Retrieval configuration for hybrid search */
+export const RetrievalConfigSchema = z.object({
+  /** Enable hybrid retrieval pipeline (opt-in) */
+  enabled: z.boolean().default(false),
+
+  /** Dense (semantic) search configuration */
+  dense: z.object({
+    /** Weight for dense search in fusion (0-1) */
+    weight: z.number().min(0).max(1).default(0.7),
+    /** Maximum number of results from dense search */
+    limit: z.number().int().min(1).max(100).default(20),
+    /** Minimum similarity threshold (0-1) */
+    minSimilarity: z.number().min(0).max(1).default(0.3)
+  }).default({}),
+
+  /** Sparse (BM25) search configuration */
+  sparse: z.object({
+    /** Enable sparse search */
+    enabled: z.boolean().default(true),
+    /** Weight for sparse search in fusion (0-1) */
+    weight: z.number().min(0).max(1).default(0.3),
+    /** Maximum number of results from sparse search */
+    limit: z.number().int().min(1).max(100).default(20)
+  }).default({}),
+
+  /** Fusion configuration for combining results */
+  fusion: z.object({
+    /** Fusion method */
+    method: z.enum(['rrf', 'linear', 'max']).default('rrf'),
+    /** RRF k parameter (default 60 per original paper) */
+    rrfK: z.number().int().min(1).default(60)
+  }).default({}),
+
+  /** Cross-encoder reranking configuration */
+  reranker: z.object({
+    /** Enable cross-encoder reranking */
+    enabled: z.boolean().default(false),
+    /** Model to use for reranking */
+    model: z.string().default('cross-encoder/ms-marco-MiniLM-L-6-v2'),
+    /** Number of results to rerank */
+    topK: z.number().int().min(1).max(100).default(10)
+  }).default({}),
+
+  /** Query understanding configuration */
+  queryUnderstanding: z.object({
+    /** Enable query understanding */
+    enabled: z.boolean().default(true),
+    /** Enable intent classification */
+    intentClassification: z.boolean().default(true),
+    /** Enable query expansion */
+    queryExpansion: z.boolean().default(true),
+    /** Enable temporal parsing */
+    temporalParsing: z.boolean().default(true)
+  }).default({}),
+
+  /** Feedback collection configuration */
+  feedback: z.object({
+    /** Enable feedback collection */
+    enabled: z.boolean().default(true),
+    /** Enable adaptive threshold learning */
+    adaptiveThresholds: z.boolean().default(true),
+    /** Minimum feedback count before adaptation */
+    minFeedbackForAdaptation: z.number().int().min(1).default(10)
+  }).default({})
+})
+
+export type RetrievalConfig = z.infer<typeof RetrievalConfigSchema>
+
+/** Knowledge graph and episodic memory configuration */
+export const KnowledgeConfigSchema = z.object({
+  /** Entity extraction settings */
+  extraction: z.object({
+    /** Minimum confidence for extracted entities */
+    minConfidence: z.number().min(0).max(1).default(0.5),
+    /** Maximum entities to extract per text */
+    maxEntities: z.number().int().min(1).max(200).default(50)
+  }).default({}),
+
+  /** Knowledge graph settings */
+  graph: z.object({
+    /** Enable knowledge graph auto-population */
+    enabled: z.boolean().default(true),
+    /** Path for graph persistence */
+    persistPath: z.string().default('./data/knowledge-graph.json'),
+    /** Auto-save interval in seconds */
+    autoSaveInterval: z.number().int().min(10).default(60),
+    /** Maximum graph traversal depth */
+    maxTraversalDepth: z.number().int().min(1).max(10).default(5),
+    /** Alpha for combined scoring (vector vs graph proximity) */
+    alpha: z.number().min(0).max(1).default(0.6)
+  }).default({}),
+
+  /** Episodic memory settings */
+  episodic: z.object({
+    /** Enable episodic memory */
+    enabled: z.boolean().default(true),
+    /** Time gap in minutes to detect new session */
+    sessionGapMinutes: z.number().int().min(1).default(30),
+    /** Maximum messages per episode before auto-splitting */
+    maxMessagesPerEpisode: z.number().int().min(10).default(200),
+    /** Number of top sentences for brief summary */
+    briefSummarySize: z.number().int().min(1).max(10).default(2),
+    /** Number of top sentences for detailed summary */
+    detailedSummarySize: z.number().int().min(1).max(20).default(8)
+  }).default({}),
+
+  /** Memory consolidation settings */
+  consolidation: z.object({
+    /** Enable memory consolidation */
+    enabled: z.boolean().default(true),
+    /** Similarity threshold for merge candidates */
+    mergeThreshold: z.number().min(0).max(1).default(0.85),
+    /** Importance score threshold for archival */
+    archiveThreshold: z.number().min(0).max(1).default(0.2),
+    /** Importance scoring weights */
+    weights: z.object({
+      recency: z.number().min(0).max(1).default(0.2),
+      frequency: z.number().min(0).max(1).default(0.2),
+      references: z.number().min(0).max(1).default(0.2),
+      feedback: z.number().min(0).max(1).default(0.2),
+      uniqueness: z.number().min(0).max(1).default(0.2)
+    }).default({})
+  }).default({})
+})
+
+export type KnowledgeConfig = z.infer<typeof KnowledgeConfigSchema>
+
+/** Phase 15: Advanced Intelligence configuration */
+export const AdvancedIntelligenceConfigSchema = z.object({
+  /** Enable advanced intelligence features (Phase 15) */
+  enabled: z.boolean().default(true),
+
+  /** Temporal intelligence settings */
+  temporal: z.object({
+    /** Enable temporal query processing */
+    enabled: z.boolean().default(true),
+    /** Default timeline limit */
+    defaultTimelineLimit: z.number().int().min(1).max(500).default(50),
+    /** Default trend analysis period in days */
+    defaultTrendPeriodDays: z.number().int().min(1).max(3650).default(90)
+  }).default({}),
+
+  /** Multi-hop reasoning settings */
+  reasoning: z.object({
+    /** Enable multi-hop reasoning */
+    enabled: z.boolean().default(true),
+    /** Maximum retrieval hops */
+    maxHops: z.number().int().min(1).max(10).default(3),
+    /** Results per hop */
+    resultsPerHop: z.number().int().min(1).max(50).default(5)
+  }).default({}),
+
+  /** Predictive intelligence settings */
+  prediction: z.object({
+    /** Enable predictive features */
+    enabled: z.boolean().default(true),
+    /** Default recommendation limit */
+    defaultRecommendationLimit: z.number().int().min(1).max(50).default(10)
+  }).default({}),
+
+  /** Cross-project intelligence settings */
+  crossProject: z.object({
+    /** Enable cross-project analysis */
+    enabled: z.boolean().default(true),
+    /** Minimum projects for pattern detection */
+    minProjects: z.number().int().min(2).max(50).default(2)
+  }).default({}),
+
+  /** Semantic caching settings */
+  cache: z.object({
+    /** Enable semantic caching */
+    enabled: z.boolean().default(true),
+    /** Maximum cache entries */
+    maxSize: z.number().int().min(10).max(10000).default(500),
+    /** Cache TTL in milliseconds */
+    ttlMs: z.number().int().min(60000).default(30 * 60 * 1000),
+    /** Semantic similarity threshold for cache hits */
+    similarityThreshold: z.number().min(0.5).max(1).default(0.85)
+  }).default({})
+})
+
+export type AdvancedIntelligenceConfig = z.infer<typeof AdvancedIntelligenceConfigSchema>
+
+/** Main configuration schema for Claude Brain */
+export const ConfigSchema = z.object({
+  /** Absolute path to the Obsidian vault */
+  vaultPath: z.string().min(1, 'Vault path is required'),
+
+  /** MCP server identifier */
+  serverName: z.string().default('claude-brain'),
+
+  /** Server version in semver format */
+  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.3.0'),
+
+  /** Logging level */
+  logLevel: LogLevelSchema.default('info'),
+
+  /** Path to log file */
+  logFilePath: z.string().default('./logs/claude-brain.log'),
+
+  /** Path to vector database */
+  dbPath: z.string().default('./data/memory.db'),
+
+  /** Port for future HTTP interface */
+  port: z.number().int().min(1).max(65535).default(3000),
+
+  /** Enable file watching for vault changes */
+  enableFileWatch: z.boolean().default(true),
+
+  /** Cache size in MB for context cache */
+  cacheSize: z.number().int().min(1).default(100),
+
+  /** Node environment */
+  nodeEnv: z.enum(['development', 'production', 'test']).default('development'),
+
+  /** ChromaDB configuration */
+  chroma: z.object({
+    /** Enable ChromaDB vector database */
+    enabled: z.boolean().default(true),
+    /** ChromaDB mode */
+    mode: z.enum(['persistent', 'client-server', 'ephemeral', 'cloud']).default('persistent'),
+    /** Path for persistent storage */
+    path: z.string().default('./data/chroma'),
+    /** Host for client-server or cloud mode */
+    host: z.string().optional(),
+    /** Port for client-server mode */
+    port: z.number().optional(),
+    /** Embedding provider */
+    embeddingProvider: z.enum(['default', 'transformers', 'openai']).default('default'),
+    /** Chroma Cloud or secured instance authentication token */
+    chromaAuthToken: z.string().optional(),
+    /** Chroma Cloud tenant name */
+    chromaTenant: z.string().optional(),
+    /** Chroma Cloud database name */
+    chromaDatabase: z.string().optional()
+  }).default({}),
+
+  /** Hybrid retrieval configuration */
+  retrieval: RetrievalConfigSchema.default({}),
+
+  /** Knowledge graph and episodic memory configuration */
+  knowledge: KnowledgeConfigSchema.default({}),
+
+  /** Advanced intelligence configuration (Phase 15) */
+  advancedIntelligence: AdvancedIntelligenceConfigSchema.default({})
+})
+
+export type Config = z.infer<typeof ConfigSchema>
+
+/** Partial config for merging with defaults */
+export type PartialConfig = z.input<typeof ConfigSchema>

package/src/config/validator.ts

@@ -0,0 +1,184 @@
+import fs from 'fs/promises'
+import path from 'path'
+import type { Logger } from 'pino'
+
+export interface ValidationResult {
+  valid: boolean
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+}
+
+export interface ValidationError {
+  field: string
+  message: string
+  severity: 'error'
+}
+
+export interface ValidationWarning {
+  field: string
+  message: string
+  severity: 'warning'
+}
+
+export class ConfigValidator {
+  private logger: Logger
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'config-validator' })
+  }
+
+  async validate(config: any): Promise<ValidationResult> {
+    const errors: ValidationError[] = []
+    const warnings: ValidationWarning[] = []
+
+    await this.validateVaultPath(config.vaultPath, errors, warnings)
+    await this.validateDatabasePath(config.dbPath, errors, warnings)
+    this.validateLogConfig(config, errors, warnings)
+    this.validateServerConfig(config, errors, warnings)
+
+    const valid = errors.length === 0
+
+    return { valid, errors, warnings }
+  }
+
+  private async validateVaultPath(
+    vaultPath: string,
+    errors: ValidationError[],
+    warnings: ValidationWarning[]
+  ): Promise<void> {
+    if (!vaultPath) {
+      errors.push({
+        field: 'vaultPath',
+        message: 'Vault path is required',
+        severity: 'error'
+      })
+      return
+    }
+
+    try {
+      const stat = await fs.stat(vaultPath)
+
+      if (!stat.isDirectory()) {
+        errors.push({
+          field: 'vaultPath',
+          message: 'Vault path must be a directory',
+          severity: 'error'
+        })
+        return
+      }
+
+      const projectsPath = path.join(vaultPath, 'Projects')
+      try {
+        await fs.access(projectsPath)
+      } catch {
+        warnings.push({
+          field: 'vaultPath',
+          message: 'Projects directory not found. It will be created automatically.',
+          severity: 'warning'
+        })
+      }
+
+      try {
+        await fs.access(vaultPath, fs.constants.W_OK)
+      } catch {
+        errors.push({
+          field: 'vaultPath',
+          message: 'Vault path is not writable',
+          severity: 'error'
+        })
+      }
+
+    } catch (error) {
+      errors.push({
+        field: 'vaultPath',
+        message: `Vault path does not exist: ${vaultPath}`,
+        severity: 'error'
+      })
+    }
+  }
+
+  private async validateDatabasePath(
+    dbPath: string,
+    errors: ValidationError[],
+    warnings: ValidationWarning[]
+  ): Promise<void> {
+    if (!dbPath) {
+      errors.push({
+        field: 'dbPath',
+        message: 'Database path is required',
+        severity: 'error'
+      })
+      return
+    }
+
+    const dbDir = path.dirname(dbPath)
+
+    try {
+      await fs.mkdir(dbDir, { recursive: true })
+    } catch (error) {
+      errors.push({
+        field: 'dbPath',
+        message: `Cannot create database directory: ${dbDir}`,
+        severity: 'error'
+      })
+    }
+  }
+
+  private validateLogConfig(
+    config: any,
+    errors: ValidationError[],
+    warnings: ValidationWarning[]
+  ): void {
+    const validLevels = ['error', 'warn', 'info', 'debug']
+
+    if (config.logLevel && !validLevels.includes(config.logLevel)) {
+      warnings.push({
+        field: 'logLevel',
+        message: `Invalid log level: ${config.logLevel}. Using 'info' as default.`,
+        severity: 'warning'
+      })
+    }
+  }
+
+  private validateServerConfig(
+    config: any,
+    errors: ValidationError[],
+    warnings: ValidationWarning[]
+  ): void {
+    if (!config.serverName) {
+      errors.push({
+        field: 'serverName',
+        message: 'Server name is required',
+        severity: 'error'
+      })
+    }
+
+    if (!config.serverVersion) {
+      warnings.push({
+        field: 'serverVersion',
+        message: 'Server version not specified',
+        severity: 'warning'
+      })
+    }
+  }
+
+  async checkSystemRequirements(): Promise<ValidationResult> {
+    const errors: ValidationError[] = []
+    const warnings: ValidationWarning[] = []
+
+    const bunVersion = process.versions.bun
+    if (!bunVersion) {
+      errors.push({
+        field: 'runtime',
+        message: 'Bun runtime not detected. Claude Brain requires Bun.',
+        severity: 'error'
+      })
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    }
+  }
+}