claude-brain 0.5.0 → 0.8.0

package/src/hooks/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Phase 17: Passive Learning via Hooks — Shared Types
+ */
+
+/** Claude Code hook stdin JSON format */
+export interface HookInput {
+  session_id: string
+  hook_event_name: 'PostToolUse' | 'Stop' | 'PreToolUse'
+  cwd: string
+  tool_name?: string
+  tool_input?: Record<string, any>
+  tool_response?: {
+    content?: string | Array<{ type: string; text?: string }>
+    [key: string]: any
+  }
+}
+
+/** Knowledge type classifications */
+export type KnowledgeType = 'decision' | 'pattern' | 'correction' | 'progress'
+
+/** A piece of knowledge captured from a hook event */
+export interface CapturedKnowledge {
+  type: KnowledgeType
+  confidence: number
+  content: string
+  project?: string
+  technologies: string[]
+  metadata: Record<string, any>
+  source: 'hook-passive'
+  timestamp: string
+}
+
+/** What to do with captured knowledge before storage */
+export type StoreAction =
+  | { action: 'store_new' }
+  | { action: 'merge'; existingId: string; mergedContent: string }
+  | { action: 'skip'; reason: string }
+
+/** Hook event stats for status reporting */
+export interface HookStats {
+  totalCaptured: number
+  totalSkipped: number
+  totalMerged: number
+  sessionsTracked: number
+  lastCaptureAt?: string
+  queueSize: number
+}

package/src/memory/chroma/client.ts

@@ -92,7 +92,7 @@ export class ChromaClientManager {
       }
 
     } catch (error) {
-      this.logger.error({ error }, 'Failed to initialize ChromaDB client')
+      this.logger.warn({ error }, 'ChromaDB not available, will use SQLite fallback')
       throw error
     }
   }

package/src/memory/chroma/index.ts

@@ -54,7 +54,7 @@ export class ChromaManager {
       this.logger.info('ChromaDB initialized successfully')
 
     } catch (error) {
-      this.logger.error({ error }, 'Failed to initialize ChromaDB')
+      this.logger.warn({ error }, 'ChromaDB unavailable')
       throw error
     }
   }

package/src/memory/chroma/store.ts

@@ -6,6 +6,25 @@ import type { DecisionMetadata, MemoryMetadata } from './schemas'
 import type { EmbeddingProvider } from './embeddings'
 import type { SearchResult } from './search'
 
+/**
+ * Sanitize metadata for ChromaDB v3.x compatibility.
+ * Strips undefined/null values (ChromaDB only accepts string, number, boolean).
+ */
+function sanitizeMetadata(metadata: Record<string, any>): Record<string, string | number | boolean> {
+  const clean: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      clean[key] = value
+    } else if (Array.isArray(value)) {
+      clean[key] = JSON.stringify(value)
+    } else {
+      clean[key] = String(value)
+    }
+  }
+  return clean
+}
+
 export interface StoreDecisionInput {
   project: string
   context: string
@@ -145,7 +164,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.decision],
-        metadatas: [metadata as Record<string, any>],
+        metadatas: [sanitizeMetadata(metadata as Record<string, any>)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -166,7 +185,7 @@ export class ChromaMemoryStore {
         await memoriesCollection.add({
           ids: [id], // Use same ID for cross-reference
           documents: [memoryContent],
-          metadatas: [memoryMetadata],
+          metadatas: [sanitizeMetadata(memoryMetadata)],
           ...(embeddings ? { embeddings } : {})
         })
 
@@ -204,6 +223,7 @@ export class ChromaMemoryStore {
     example?: string
     confidence: number
     context?: string
+    source?: string
   }): Promise<string> {
     const id = randomUUID()
     const now = new Date().toISOString()
@@ -217,7 +237,7 @@ export class ChromaMemoryStore {
       context: input.context || '',
       created_at: now,
       updated_at: now,
-      source: 'manual'
+      source: input.source || 'manual'
     }
 
     try {
@@ -230,7 +250,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.description],
-        metadatas: [metadata],
+        metadatas: [sanitizeMetadata(metadata)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -252,7 +272,7 @@ export class ChromaMemoryStore {
         await memoriesCollection.add({
           ids: [id],
           documents: [memoryContent],
-          metadatas: [memoryMetadata],
+          metadatas: [sanitizeMetadata(memoryMetadata)],
           ...(embeddings ? { embeddings } : {})
         })
 
@@ -304,7 +324,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.correction],
-        metadatas: [metadata],
+        metadatas: [sanitizeMetadata(metadata)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -325,7 +345,7 @@ export class ChromaMemoryStore {
         await memoriesCollection.add({
           ids: [id],
           documents: [memoryContent],
-          metadatas: [memoryMetadata],
+          metadatas: [sanitizeMetadata(memoryMetadata)],
           ...(embeddings ? { embeddings } : {})
         })
 
@@ -367,7 +387,7 @@ export class ChromaMemoryStore {
       await collection.add({
         ids: [id],
         documents: [input.content],
-        metadatas: [metadata as Record<string, any>],
+        metadatas: [sanitizeMetadata(metadata as Record<string, any>)],
         ...(embeddings ? { embeddings } : {})
       })
 
@@ -409,7 +429,7 @@ export class ChromaMemoryStore {
       await collection.upsert({
         ids: [id],
         documents: [input.decision],
-        metadatas: [metadata as Record<string, any>],
+        metadatas: [sanitizeMetadata(metadata as Record<string, any>)],
         ...(embeddings ? { embeddings } : {})
       })
 

package/src/memory/index.ts

@@ -316,6 +316,7 @@ export class MemoryManager {
     example?: string
     confidence: number
     context?: string
+    source?: string
   }): Promise<string> {
     if (this.useChromaDB) {
       return this.chroma.store.storePattern(input)

package/src/memory/store.ts

@@ -336,6 +336,7 @@ export class MemoryStore {
     example?: string
     confidence: number
     context?: string
+    source?: string
   }): Promise<string> {
     try {
       const content = `Pattern (${input.pattern_type}): ${input.description}${input.context ? `\nContext: ${input.context}` : ''}${input.example ? `\nExample: ${input.example}` : ''}`

package/src/packs/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Phase 18: Knowledge Packs
+ * Pre-seeded knowledge for zero cold-start experience
+ */
+
+export * from './types'
+export { PackManager } from './manager'
+export { PackLoader } from './loader'
+export { KnowledgeRanker, type RankedResult } from './ranker'

package/src/packs/loader.ts

@@ -0,0 +1,134 @@
+/**
+ * Phase 18: Pack Loader
+ * Orchestrates loading pack entries into the memory system
+ */
+
+import type { Logger } from 'pino'
+import type { MemoryManager } from '@/memory/index'
+import type { PackManager } from './manager'
+import type { PacksConfig } from '@/config/schema'
+import { ENTRY_TYPE_TO_PATTERN_TYPE, type PackEntry, type PackLoadResult } from './types'
+
+export class PackLoader {
+  private logger: Logger
+  private memory: MemoryManager
+  private packManager: PackManager
+  private config: PacksConfig
+
+  constructor(logger: Logger, memory: MemoryManager, packManager: PackManager, config: PacksConfig) {
+    this.logger = logger.child({ component: 'pack-loader' })
+    this.memory = memory
+    this.packManager = packManager
+    this.config = config
+  }
+
+  /** Main entry point: load all relevant packs for a project */
+  async loadPacksForProject(project: string, techStack: string[]): Promise<PackLoadResult> {
+    const result: PackLoadResult = {
+      packsLoaded: 0,
+      entriesLoaded: 0,
+      packDetails: [],
+      skipped: []
+    }
+
+    const relevantPackIds = this.packManager.findRelevantPacks(techStack)
+    this.logger.info({ project, techStack, relevantPackIds }, 'Loading packs for project')
+
+    const manifest = await this.packManager.getManifest(project)
+
+    for (const packId of relevantPackIds) {
+      try {
+        const pack = await this.packManager.loadPack(packId)
+
+        // Idempotency check
+        if (this.packManager.isPackLoaded(manifest, packId, pack.version)) {
+          result.skipped.push({ packId, reason: `Already loaded (v${pack.version})` })
+          this.logger.debug({ packId, version: pack.version }, 'Pack already loaded, skipping')
+          continue
+        }
+
+        // Load each entry
+        let entriesLoaded = 0
+        for (const entry of pack.entries) {
+          try {
+            await this.storeEntry(project, packId, entry)
+            entriesLoaded++
+          } catch (error) {
+            this.logger.warn({ error, packId, entry: entry.title }, 'Failed to store pack entry')
+          }
+        }
+
+        // Update manifest
+        manifest.packs.push({
+          packId,
+          version: pack.version,
+          entriesLoaded,
+          loadedAt: new Date().toISOString()
+        })
+
+        result.packsLoaded++
+        result.entriesLoaded += entriesLoaded
+        result.packDetails.push({
+          packId,
+          name: pack.name,
+          entriesLoaded
+        })
+
+        this.logger.info({ packId, entriesLoaded }, 'Pack loaded successfully')
+      } catch (error) {
+        result.skipped.push({
+          packId,
+          reason: `Load failed: ${error instanceof Error ? error.message : String(error)}`
+        })
+        this.logger.warn({ error, packId }, 'Failed to load pack')
+      }
+    }
+
+    // Save updated manifest
+    await this.packManager.saveManifest(manifest)
+
+    this.logger.info({
+      project,
+      packsLoaded: result.packsLoaded,
+      entriesLoaded: result.entriesLoaded,
+      skipped: result.skipped.length
+    }, 'Pack loading complete')
+
+    return result
+  }
+
+  /** Route a single pack entry to the appropriate storage method */
+  private async storeEntry(project: string, packId: string, entry: PackEntry): Promise<void> {
+    const dampenedConfidence = entry.confidence * this.config.communityConfidenceMultiplier
+
+    if (entry.type === 'decision-template') {
+      // Decision templates go to rememberDecision
+      await this.memory.rememberDecision(
+        project,
+        `[community:pack:${packId}] ${entry.category}`,
+        `${entry.title}: ${entry.content}`,
+        `Pre-seeded from knowledge pack: ${packId}`,
+        {
+          tags: ['pack', `pack:${packId}`, ...entry.tags]
+        }
+      )
+    } else {
+      // All other types go to storePattern
+      const patternType = ENTRY_TYPE_TO_PATTERN_TYPE[entry.type]
+      if (!patternType) {
+        this.logger.warn({ type: entry.type, packId }, 'Unknown entry type, skipping')
+        return
+      }
+
+      await this.memory.storePattern({
+        project,
+        pattern_type: patternType,
+        description: `${entry.title}: ${entry.content}`,
+        example: entry.example,
+        confidence: dampenedConfidence,
+        context: `[community:pack:${packId}] ${entry.category}`,
+        source: `pack:${packId}`
+      })
+    }
+  }
+}

package/src/packs/manager.ts

@@ -0,0 +1,204 @@
+/**
+ * Phase 18: Pack Manager
+ * Handles discovery, loading, and manifest tracking for knowledge packs
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import type { Logger } from 'pino'
+import type { PacksConfig } from '@/config/schema'
+import { KnowledgePackSchema, type KnowledgePack, type PackManifest } from './types'
+
+/** Maps tech stack names to relevant pack IDs */
+const STACK_MAP: Record<string, string[]> = {
+  // Languages
+  typescript: ['core/typescript'],
+  javascript: ['core/javascript'],
+
+  // Frontend frameworks
+  react: ['frontend/react'],
+  vue: ['frontend/react'], // reuse performance patterns; will add vue pack later
+  angular: ['frontend/react'],
+  svelte: ['frontend/react'],
+  'next.js': ['frontend/react'],
+  nuxt: ['frontend/react'],
+  remix: ['frontend/react'],
+  gatsby: ['frontend/react'],
+
+  // Backend
+  node: ['backend/node'],
+  express: ['backend/node'],
+  fastify: ['backend/node'],
+  hono: ['backend/node'],
+  elysia: ['backend/node'],
+  nestjs: ['backend/node'],
+  bun: ['backend/node'],
+
+  // Meta
+  jest: ['meta/testing'],
+  vitest: ['meta/testing'],
+  mocha: ['meta/testing'],
+  'bun:test': ['meta/testing'],
+  testing: ['meta/testing']
+}
+
+export class PackManager {
+  private logger: Logger
+  private config: PacksConfig
+  private packageRoot: string
+  private dataDir: string
+
+  constructor(logger: Logger, config: PacksConfig, packageRoot: string, dataDir: string) {
+    this.logger = logger.child({ component: 'pack-manager' })
+    this.config = config
+    this.packageRoot = packageRoot
+    this.dataDir = dataDir
+  }
+
+  /** Find pack IDs relevant to a given tech stack */
+  findRelevantPacks(techStack: string[]): string[] {
+    const packIds = new Set<string>()
+
+    // Always include core and meta packs when configured
+    if (this.config.alwaysLoadCore) {
+      packIds.add('core/typescript')
+      packIds.add('core/javascript')
+    }
+    if (this.config.alwaysLoadMeta) {
+      packIds.add('meta/testing')
+    }
+
+    // Add tech-stack specific packs
+    for (const tech of techStack) {
+      const normalizedTech = tech.toLowerCase()
+      const mapped = STACK_MAP[normalizedTech]
+      if (mapped) {
+        for (const packId of mapped) {
+          packIds.add(packId)
+        }
+      }
+    }
+
+    return Array.from(packIds)
+  }
+
+  /** Load and validate a pack from the packs directory */
+  async loadPack(packId: string): Promise<KnowledgePack> {
+    const packPath = path.join(this.packageRoot, this.config.packsDir, `${packId}.json`)
+
+    try {
+      const content = await fs.readFile(packPath, 'utf-8')
+      const raw = JSON.parse(content)
+      const pack = KnowledgePackSchema.parse(raw)
+      this.logger.debug({ packId, entries: pack.entries.length }, 'Pack loaded and validated')
+      return pack
+    } catch (error) {
+      this.logger.error({ error, packId, packPath }, 'Failed to load pack')
+      throw new Error(`Failed to load pack "${packId}": ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  /** Get the manifest for a project (tracks which packs are loaded) */
+  async getManifest(project: string): Promise<PackManifest> {
+    const manifestPath = this.getManifestPath(project)
+
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8')
+      return JSON.parse(content) as PackManifest
+    } catch {
+      // No manifest yet — return empty
+      return {
+        project,
+        packs: [],
+        lastUpdated: new Date().toISOString()
+      }
+    }
+  }
+
+  /** Save manifest after loading packs */
+  async saveManifest(manifest: PackManifest): Promise<void> {
+    const manifestPath = this.getManifestPath(manifest.project)
+    const manifestDir = path.dirname(manifestPath)
+
+    await fs.mkdir(manifestDir, { recursive: true })
+    manifest.lastUpdated = new Date().toISOString()
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8')
+
+    this.logger.debug({ project: manifest.project, packs: manifest.packs.length }, 'Manifest saved')
+  }
+
+  /** Delete manifest for a project (used by reload) */
+  async deleteManifest(project: string): Promise<void> {
+    const manifestPath = this.getManifestPath(project)
+    try {
+      await fs.unlink(manifestPath)
+    } catch {
+      // File didn't exist, that's fine
+    }
+  }
+
+  /** Check if a pack version is already loaded */
+  isPackLoaded(manifest: PackManifest, packId: string, version: string): boolean {
+    return manifest.packs.some(p => p.packId === packId && p.version === version)
+  }
+
+  /** List all available packs in the packs directory */
+  async listAvailablePacks(): Promise<Array<{ id: string; name: string; description: string; entries: number; version: string }>> {
+    const packsDir = path.join(this.packageRoot, this.config.packsDir)
+    const packs: Array<{ id: string; name: string; description: string; entries: number; version: string }> = []
+
+    try {
+      await this.scanPacksDir(packsDir, '', packs)
+    } catch (error) {
+      this.logger.warn({ error, packsDir }, 'Failed to scan packs directory')
+    }
+
+    return packs
+  }
+
+  private async scanPacksDir(
+    dir: string,
+    prefix: string,
+    result: Array<{ id: string; name: string; description: string; entries: number; version: string }>
+  ): Promise<void> {
+    let entries: import('fs').Dirent[]
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await this.scanPacksDir(
+          path.join(dir, entry.name),
+          prefix ? `${prefix}/${entry.name}` : entry.name,
+          result
+        )
+      } else if (entry.name.endsWith('.json')) {
+        const packId = prefix
+          ? `${prefix}/${entry.name.replace('.json', '')}`
+          : entry.name.replace('.json', '')
+
+        try {
+          const content = await fs.readFile(path.join(dir, entry.name), 'utf-8')
+          const raw = JSON.parse(content)
+          const pack = KnowledgePackSchema.parse(raw)
+          result.push({
+            id: packId,
+            name: pack.name,
+            description: pack.description,
+            entries: pack.entries.length,
+            version: pack.version
+          })
+        } catch (error) {
+          this.logger.warn({ error, packId }, 'Skipping invalid pack file')
+        }
+      }
+    }
+  }
+
+  private getManifestPath(project: string): string {
+    return path.join(this.dataDir, 'pack-manifests', `${project}.json`)
+  }
+}

package/src/packs/ranker.ts

@@ -0,0 +1,78 @@
+/**
+ * Phase 18: Knowledge Ranker
+ * Post-processing layer for search results that boosts personal entries
+ * over community (pack) entries
+ */
+
+import type { PacksConfig } from '@/config/schema'
+
+export interface RankedResult {
+  id: string
+  content: string
+  metadata: Record<string, any>
+  similarity: number
+  adjustedScore: number
+  badge: 'personal' | 'community'
+}
+
+export class KnowledgeRanker {
+  private personalBoost: number
+  private projectBoost: number
+
+  constructor(config: PacksConfig) {
+    this.personalBoost = config.personalBoost
+    this.projectBoost = config.projectBoost
+  }
+
+  /** Adjust similarity scores based on entry source */
+  rank(
+    results: Array<{ id: string; content: string; metadata: Record<string, any>; similarity: number }>,
+    currentProject?: string
+  ): RankedResult[] {
+    const ranked = results.map(result => {
+      const isCommunity = this.isCommunityEntry(result.metadata)
+      let adjustedScore = result.similarity
+
+      if (!isCommunity) {
+        // Personal entries get a boost
+        adjustedScore *= this.personalBoost
+
+        // Project-specific entries get an additional boost
+        if (currentProject && result.metadata.project === currentProject) {
+          adjustedScore *= this.projectBoost
+        }
+      }
+      // Community entries: no boost (effectively ranked lower)
+
+      // Cap at 1.0
+      adjustedScore = Math.min(adjustedScore, 1.0)
+
+      return {
+        id: result.id,
+        content: result.content,
+        metadata: result.metadata,
+        similarity: result.similarity,
+        adjustedScore,
+        badge: isCommunity ? 'community' as const : 'personal' as const
+      }
+    })
+
+    // Sort by adjusted score descending
+    return ranked.sort((a, b) => b.adjustedScore - a.adjustedScore)
+  }
+
+  /** Detect if a search result is from a community pack */
+  isCommunityEntry(metadata: Record<string, any>): boolean {
+    // Check source field
+    if (typeof metadata.source === 'string' && metadata.source.startsWith('pack:')) {
+      return true
+    }
+
+    // Check context field for community marker
+    if (typeof metadata.context === 'string' && metadata.context.includes('[community:pack:')) {
+      return true
+    }
+
+    return false
+  }
+}