claude-brain 0.5.1 → 0.8.0

package/src/hooks/queue.ts

@@ -0,0 +1,122 @@
+/**
+ * Phase 17: File Queue
+ * JSONL-based offline fallback when HTTP API server is unreachable.
+ * Queue file: ~/.claude-brain/data/hook-queue.jsonl
+ */
+
+import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { getHomePaths } from '@/config/home'
+import type { CapturedKnowledge } from './types'
+
+/** Get the queue file path */
+export function getQueuePath(): string {
+  return join(getHomePaths().data, 'hook-queue.jsonl')
+}
+
+/**
+ * Append captured knowledge to the offline queue.
+ * Creates the file and parent directory if needed.
+ */
+export function appendToQueue(items: CapturedKnowledge[]): void {
+  if (items.length === 0) return
+
+  const queuePath = getQueuePath()
+  const dir = dirname(queuePath)
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+
+  const lines = items.map(item => JSON.stringify(item)).join('\n') + '\n'
+  appendFileSync(queuePath, lines, 'utf-8')
+}
+
+/**
+ * Read all items from the queue file.
+ * Returns empty array if file doesn't exist.
+ */
+export function readQueue(): CapturedKnowledge[] {
+  const queuePath = getQueuePath()
+
+  if (!existsSync(queuePath)) return []
+
+  try {
+    const content = readFileSync(queuePath, 'utf-8').trim()
+    if (!content) return []
+
+    return content
+      .split('\n')
+      .filter(line => line.trim())
+      .map(line => {
+        try {
+          return JSON.parse(line) as CapturedKnowledge
+        } catch {
+          return null
+        }
+      })
+      .filter((item): item is CapturedKnowledge => item !== null)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Clear the queue file after successful processing.
+ */
+export function clearQueue(): void {
+  const queuePath = getQueuePath()
+  if (existsSync(queuePath)) {
+    writeFileSync(queuePath, '', 'utf-8')
+  }
+}
+
+/**
+ * Drain the queue by POSTing items to the ingest endpoint in batches.
+ * Called on server startup.
+ *
+ * @param port The HTTP API port
+ * @param batchSize Number of items per POST
+ * @returns Number of items drained
+ */
+export async function drainQueue(port: number = 3000, batchSize: number = 10): Promise<number> {
+  const items = readQueue()
+  if (items.length === 0) return 0
+
+  let drained = 0
+  const url = `http://localhost:${port}/api/hooks/ingest`
+
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize)
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ knowledge: batch }),
+        signal: AbortSignal.timeout(5000),
+      })
+
+      if (res.ok) {
+        drained += batch.length
+      } else {
+        // Stop draining on first failure
+        break
+      }
+    } catch {
+      // Server not ready yet, stop
+      break
+    }
+  }
+
+  if (drained === items.length) {
+    clearQueue()
+  } else if (drained > 0) {
+    // Partially drained — rewrite queue with remaining items
+    const remaining = items.slice(drained)
+    const queuePath = getQueuePath()
+    const lines = remaining.map(item => JSON.stringify(item)).join('\n') + '\n'
+    writeFileSync(queuePath, lines, 'utf-8')
+  }
+
+  return drained
+}

package/src/hooks/session-tracker.ts

@@ -0,0 +1,199 @@
+/**
+ * Phase 17: Session Tracker
+ * Server-side session tracking that maintains state across hook invocations.
+ * Buffers CapturedKnowledge items and generates session summaries on idle/stop.
+ */
+
+import type { Logger } from 'pino'
+import type { EpisodeManager } from '@/memory/episodic/manager'
+import { ExtractiveSummarizer } from '@/memory/episodic/summarizer'
+import type { CapturedKnowledge } from './types'
+import type { HooksConfig } from '@/config/schema'
+
+interface SessionState {
+  sessionId: string
+  project?: string
+  items: CapturedKnowledge[]
+  startedAt: string
+  lastActivityAt: string
+  episodeId?: string
+}
+
+export class HookSessionTracker {
+  private logger: Logger
+  private episodeManager: EpisodeManager | null
+  private summarizer: ExtractiveSummarizer
+  private sessions: Map<string, SessionState> = new Map()
+  private idleTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private idleTimeoutMs: number
+  private minEventsForSummary: number
+
+  constructor(
+    logger: Logger,
+    episodeManager: EpisodeManager | null,
+    config?: HooksConfig['sessions']
+  ) {
+    this.logger = logger.child({ component: 'hook-session-tracker' })
+    this.episodeManager = episodeManager
+    this.summarizer = new ExtractiveSummarizer()
+    this.idleTimeoutMs = (config?.idleTimeoutMinutes ?? 30) * 60 * 1000
+    this.minEventsForSummary = config?.minEventsForSummary ?? 3
+  }
+
+  /**
+   * Track a captured knowledge item within a session.
+   */
+  async track(sessionId: string, knowledge: CapturedKnowledge): Promise<void> {
+    let session = this.sessions.get(sessionId)
+
+    if (!session) {
+      session = {
+        sessionId,
+        project: knowledge.project,
+        items: [],
+        startedAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+      }
+      this.sessions.set(sessionId, session)
+
+      // Start episode if manager available
+      if (this.episodeManager) {
+        try {
+          const episode = await this.episodeManager.startEpisode(knowledge.project)
+          session.episodeId = episode.id
+        } catch (err) {
+          this.logger.warn({ err }, 'Failed to start episode for session')
+        }
+      }
+    }
+
+    session.items.push(knowledge)
+    session.lastActivityAt = new Date().toISOString()
+
+    // Reset idle timer
+    this.resetIdleTimer(sessionId)
+  }
+
+  /**
+   * End a session immediately (triggered by Stop hook event).
+   */
+  async endSession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    this.clearIdleTimer(sessionId)
+    await this.summarizeAndPersist(session)
+    this.sessions.delete(sessionId)
+  }
+
+  /**
+   * End all active sessions (for server shutdown).
+   */
+  async endAllSessions(): Promise<void> {
+    const sessionIds = Array.from(this.sessions.keys())
+    for (const id of sessionIds) {
+      await this.endSession(id)
+    }
+  }
+
+  /**
+   * Get stats about tracked sessions.
+   */
+  getStats(): { activeSessions: number; totalItems: number } {
+    let totalItems = 0
+    for (const session of this.sessions.values()) {
+      totalItems += session.items.length
+    }
+    return { activeSessions: this.sessions.size, totalItems }
+  }
+
+  private resetIdleTimer(sessionId: string): void {
+    this.clearIdleTimer(sessionId)
+    const timer = setTimeout(() => {
+      this.onIdle(sessionId)
+    }, this.idleTimeoutMs)
+    this.idleTimers.set(sessionId, timer)
+  }
+
+  private clearIdleTimer(sessionId: string): void {
+    const existing = this.idleTimers.get(sessionId)
+    if (existing) {
+      clearTimeout(existing)
+      this.idleTimers.delete(sessionId)
+    }
+  }
+
+  private async onIdle(sessionId: string): Promise<void> {
+    this.logger.debug({ sessionId }, 'Session idle timeout, summarizing')
+    await this.endSession(sessionId)
+  }
+
+  private async summarizeAndPersist(session: SessionState): Promise<void> {
+    if (session.items.length < this.minEventsForSummary) {
+      this.logger.debug(
+        { sessionId: session.sessionId, items: session.items.length },
+        'Too few items for summary, skipping'
+      )
+      // Still end the episode if started
+      if (session.episodeId && this.episodeManager) {
+        try {
+          await this.episodeManager.endEpisode(session.episodeId)
+        } catch {}
+      }
+      return
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, items: session.items.length, project: session.project },
+      'Summarizing session'
+    )
+
+    // Build a synthetic episode for the summarizer
+    const messages = session.items.map((item) => ({
+      role: 'assistant' as const,
+      content: `[${item.type}] ${item.content}`,
+      timestamp: item.timestamp,
+      token_estimate: Math.ceil(item.content.length / 4),
+    }))
+
+    const syntheticEpisode = {
+      id: session.sessionId,
+      project: session.project,
+      status: 'completed' as const,
+      started_at: session.startedAt,
+      ended_at: new Date().toISOString(),
+      messages,
+      related_decisions: session.items
+        .filter(i => i.type === 'decision')
+        .map((_, idx) => `hook-decision-${idx}`),
+      related_patterns: session.items
+        .filter(i => i.type === 'pattern')
+        .map((_, idx) => `hook-pattern-${idx}`),
+      related_corrections: session.items
+        .filter(i => i.type === 'correction')
+        .map((_, idx) => `hook-correction-${idx}`),
+      token_count: messages.reduce((sum, m) => sum + (m.token_estimate || 0), 0),
+      message_count: messages.length,
+    }
+
+    const summary = this.summarizer.summarize(syntheticEpisode)
+
+    // End the episode with summary attached
+    if (session.episodeId && this.episodeManager) {
+      try {
+        // Add messages to episode before ending
+        for (const msg of messages) {
+          await this.episodeManager.addMessage(session.episodeId, msg)
+        }
+        await this.episodeManager.endEpisode(session.episodeId)
+      } catch (err) {
+        this.logger.warn({ err, sessionId: session.sessionId }, 'Failed to end episode')
+      }
+    }
+
+    this.logger.info(
+      { sessionId: session.sessionId, summary: summary.brief },
+      'Session summarized'
+    )
+  }
+}

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/store.ts

@@ -223,6 +223,7 @@ export class ChromaMemoryStore {
     example?: string
     confidence: number
     context?: string
+    source?: string
   }): Promise<string> {
     const id = randomUUID()
     const now = new Date().toISOString()
@@ -236,7 +237,7 @@ export class ChromaMemoryStore {
       context: input.context || '',
       created_at: now,
       updated_at: now,
-      source: 'manual'
+      source: input.source || 'manual'
     }
 
     try {

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}`
+      })
+    }
+  }
+}