claude-brain 0.3.0

package/src/temporal/query-processor.ts

@@ -0,0 +1,190 @@
+/**
+ * Temporal Query Processor
+ * Parses temporal expressions from natural language using chrono-node
+ */
+
+import * as chrono from 'chrono-node'
+import type { Logger } from 'pino'
+
+export interface TemporalQuery {
+  /** Original query text */
+  original: string
+  /** Cleaned query with temporal expressions removed */
+  cleaned: string
+  /** Parsed start date (if any) */
+  startDate?: string
+  /** Parsed end date (if any) */
+  endDate?: string
+  /** Temporal intent detected */
+  intent: 'range' | 'before' | 'after' | 'point' | 'none'
+  /** Relative time expressions found */
+  expressions: string[]
+}
+
+export class TemporalQueryProcessor {
+  private logger: Logger
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'temporal-query-processor' })
+  }
+
+  /**
+   * Parse temporal expressions from a natural language query
+   */
+  parse(query: string): TemporalQuery {
+    const result: TemporalQuery = {
+      original: query,
+      cleaned: query,
+      intent: 'none',
+      expressions: []
+    }
+
+    try {
+      // Parse with chrono-node
+      const parsed = chrono.parse(query, new Date(), { forwardDate: false })
+
+      if (parsed.length === 0) {
+        // Try manual temporal patterns
+        return this.parseManualPatterns(query, result)
+      }
+
+      const ref = parsed[0]
+      result.expressions.push(ref.text)
+
+      // Remove temporal expression from query for cleaner semantic search
+      result.cleaned = query.replace(ref.text, '').replace(/\s+/g, ' ').trim()
+
+      if (ref.start && ref.end) {
+        // Date range
+        result.startDate = ref.start.date().toISOString()
+        result.endDate = ref.end.date().toISOString()
+        result.intent = 'range'
+      } else if (ref.start) {
+        const startDate = ref.start.date()
+
+        // Check context for before/after
+        const beforeIndex = query.toLowerCase().indexOf('before')
+        const afterIndex = query.toLowerCase().indexOf('after')
+        const sinceIndex = query.toLowerCase().indexOf('since')
+        const untilIndex = query.toLowerCase().indexOf('until')
+
+        if (beforeIndex >= 0 && beforeIndex < query.indexOf(ref.text)) {
+          result.endDate = startDate.toISOString()
+          result.intent = 'before'
+        } else if (
+          (afterIndex >= 0 && afterIndex < query.indexOf(ref.text)) ||
+          (sinceIndex >= 0 && sinceIndex < query.indexOf(ref.text))
+        ) {
+          result.startDate = startDate.toISOString()
+          result.intent = 'after'
+        } else if (untilIndex >= 0 && untilIndex < query.indexOf(ref.text)) {
+          result.endDate = startDate.toISOString()
+          result.intent = 'before'
+        } else {
+          // Default: treat as a point in time, create a window around it
+          const dayBefore = new Date(startDate)
+          dayBefore.setDate(dayBefore.getDate() - 1)
+          const dayAfter = new Date(startDate)
+          dayAfter.setDate(dayAfter.getDate() + 1)
+
+          result.startDate = dayBefore.toISOString()
+          result.endDate = dayAfter.toISOString()
+          result.intent = 'point'
+        }
+      }
+
+      // Handle multiple temporal expressions
+      for (let i = 1; i < parsed.length; i++) {
+        result.expressions.push(parsed[i].text)
+        result.cleaned = result.cleaned.replace(parsed[i].text, '').replace(/\s+/g, ' ').trim()
+      }
+    } catch (error) {
+      this.logger.debug({ error, query }, 'Failed to parse temporal expression')
+    }
+
+    return result
+  }
+
+  private parseManualPatterns(query: string, result: TemporalQuery): TemporalQuery {
+    const lowerQuery = query.toLowerCase()
+    const now = new Date()
+
+    // "last week", "last month", "last year"
+    const lastMatch = lowerQuery.match(/\b(?:in the )?last\s+(week|month|year|quarter|(\d+)\s*(days?|weeks?|months?))\b/)
+    if (lastMatch) {
+      result.expressions.push(lastMatch[0])
+      result.cleaned = query.replace(new RegExp(lastMatch[0], 'i'), '').replace(/\s+/g, ' ').trim()
+      result.endDate = now.toISOString()
+
+      const start = new Date(now)
+      if (lastMatch[1] === 'week') {
+        start.setDate(start.getDate() - 7)
+      } else if (lastMatch[1] === 'month') {
+        start.setMonth(start.getMonth() - 1)
+      } else if (lastMatch[1] === 'year') {
+        start.setFullYear(start.getFullYear() - 1)
+      } else if (lastMatch[1] === 'quarter') {
+        start.setMonth(start.getMonth() - 3)
+      } else if (lastMatch[2] && lastMatch[3]) {
+        const n = parseInt(lastMatch[2])
+        const unit = lastMatch[3].replace(/s$/, '')
+        if (unit === 'day') start.setDate(start.getDate() - n)
+        else if (unit === 'week') start.setDate(start.getDate() - n * 7)
+        else if (unit === 'month') start.setMonth(start.getMonth() - n)
+      }
+
+      result.startDate = start.toISOString()
+      result.intent = 'range'
+      return result
+    }
+
+    // "recently", "lately"
+    if (/\b(recently|lately)\b/.test(lowerQuery)) {
+      const match = lowerQuery.match(/\b(recently|lately)\b/)!
+      result.expressions.push(match[0])
+      result.cleaned = query.replace(new RegExp(match[0], 'i'), '').replace(/\s+/g, ' ').trim()
+      const start = new Date(now)
+      start.setDate(start.getDate() - 14) // 2 weeks for "recently"
+      result.startDate = start.toISOString()
+      result.endDate = now.toISOString()
+      result.intent = 'range'
+      return result
+    }
+
+    // "this week", "this month", "this year"
+    const thisMatch = lowerQuery.match(/\bthis\s+(week|month|year)\b/)
+    if (thisMatch) {
+      result.expressions.push(thisMatch[0])
+      result.cleaned = query.replace(new RegExp(thisMatch[0], 'i'), '').replace(/\s+/g, ' ').trim()
+      result.endDate = now.toISOString()
+
+      const start = new Date(now)
+      if (thisMatch[1] === 'week') {
+        start.setDate(start.getDate() - start.getDay())
+        start.setHours(0, 0, 0, 0)
+      } else if (thisMatch[1] === 'month') {
+        start.setDate(1)
+        start.setHours(0, 0, 0, 0)
+      } else if (thisMatch[1] === 'year') {
+        start.setMonth(0, 1)
+        start.setHours(0, 0, 0, 0)
+      }
+
+      result.startDate = start.toISOString()
+      result.intent = 'range'
+      return result
+    }
+
+    // "ever", "all time", "historically"
+    if (/\b(ever|all\s+time|historically|over\s+time)\b/.test(lowerQuery)) {
+      const match = lowerQuery.match(/\b(ever|all\s+time|historically|over\s+time)\b/)!
+      result.expressions.push(match[0])
+      result.cleaned = query.replace(new RegExp(match[0], 'i'), '').replace(/\s+/g, ' ').trim()
+      result.intent = 'range'
+      // No date constraints = all time
+      return result
+    }
+
+    return result
+  }
+}

package/src/temporal/timeline.ts

@@ -0,0 +1,259 @@
+/**
+ * Timeline Construction
+ * Builds chronological timelines from ChromaDB memories
+ */
+
+import type { Logger } from 'pino'
+import type { CollectionManager } from '@/memory/chroma/collection-manager'
+import type { EmbeddingProvider } from '@/memory/chroma/embeddings'
+
+export interface TimelineEntry {
+  id: string
+  date: string
+  type: 'decision' | 'pattern' | 'correction'
+  project: string
+  content: string
+  metadata: Record<string, any>
+}
+
+export interface Timeline {
+  entries: TimelineEntry[]
+  project?: string
+  startDate?: string
+  endDate?: string
+  totalCount: number
+}
+
+export class TimelineBuilder {
+  private logger: Logger
+  private collections: CollectionManager
+  private embeddings?: EmbeddingProvider
+
+  constructor(logger: Logger, collections: CollectionManager, embeddings?: EmbeddingProvider) {
+    this.logger = logger.child({ component: 'timeline-builder' })
+    this.collections = collections
+    this.embeddings = embeddings
+  }
+
+  /**
+   * Build a timeline of decisions for a project or topic
+   */
+  async buildTimeline(options: {
+    project?: string
+    topic?: string
+    startDate?: string
+    endDate?: string
+    limit?: number
+    types?: Array<'decision' | 'pattern' | 'correction'>
+  } = {}): Promise<Timeline> {
+    const {
+      project,
+      topic,
+      startDate,
+      endDate,
+      limit = 50,
+      types = ['decision', 'pattern', 'correction']
+    } = options
+
+    const entries: TimelineEntry[] = []
+
+    // Fetch from each collection type
+    if (types.includes('decision')) {
+      const decisions = await this.fetchDecisions(project, topic, startDate, endDate, limit)
+      entries.push(...decisions)
+    }
+
+    if (types.includes('pattern')) {
+      const patterns = await this.fetchPatterns(project, topic, startDate, endDate, limit)
+      entries.push(...patterns)
+    }
+
+    if (types.includes('correction')) {
+      const corrections = await this.fetchCorrections(project, topic, startDate, endDate, limit)
+      entries.push(...corrections)
+    }
+
+    // Sort chronologically
+    entries.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime())
+
+    // Apply limit after merge
+    const limited = entries.slice(0, limit)
+
+    return {
+      entries: limited,
+      project,
+      startDate: limited[0]?.date,
+      endDate: limited[limited.length - 1]?.date,
+      totalCount: limited.length
+    }
+  }
+
+  private async fetchDecisions(
+    project?: string,
+    topic?: string,
+    startDate?: string,
+    endDate?: string,
+    limit: number = 50
+  ): Promise<TimelineEntry[]> {
+    try {
+      const collection = await this.collections.getDecisions()
+
+      if (topic && this.embeddings) {
+        // Semantic search by topic
+        const embedding = await this.embeddings.generate(topic)
+        const where = this.buildWhere(project, startDate, endDate)
+        const results = await collection.query({
+          queryEmbeddings: [embedding],
+          nResults: limit,
+          where: Object.keys(where).length > 0 ? where : undefined,
+          include: ['documents', 'metadatas', 'distances']
+        })
+
+        return this.processQueryResults(results, 'decision')
+      }
+
+      // Direct fetch
+      const where = this.buildWhere(project, startDate, endDate)
+      const results = await collection.get({
+        where: Object.keys(where).length > 0 ? where : undefined,
+        include: ['documents', 'metadatas'],
+        limit
+      })
+
+      return results.ids.map((id, i) => ({
+        id,
+        date: (results.metadatas![i] as any)?.created_at || new Date().toISOString(),
+        type: 'decision' as const,
+        project: (results.metadatas![i] as any)?.project || '',
+        content: results.documents![i] as string,
+        metadata: results.metadatas![i] as Record<string, any>
+      }))
+    } catch (error) {
+      this.logger.warn({ error }, 'Failed to fetch decisions for timeline')
+      return []
+    }
+  }
+
+  private async fetchPatterns(
+    project?: string,
+    topic?: string,
+    startDate?: string,
+    endDate?: string,
+    limit: number = 50
+  ): Promise<TimelineEntry[]> {
+    try {
+      const collection = await this.collections.getPatterns()
+
+      if (topic && this.embeddings) {
+        const embedding = await this.embeddings.generate(topic)
+        const where = this.buildWhere(project, startDate, endDate)
+        const results = await collection.query({
+          queryEmbeddings: [embedding],
+          nResults: limit,
+          where: Object.keys(where).length > 0 ? where : undefined,
+          include: ['documents', 'metadatas', 'distances']
+        })
+
+        return this.processQueryResults(results, 'pattern')
+      }
+
+      const where = this.buildWhere(project, startDate, endDate)
+      const results = await collection.get({
+        where: Object.keys(where).length > 0 ? where : undefined,
+        include: ['documents', 'metadatas'],
+        limit
+      })
+
+      return results.ids.map((id, i) => ({
+        id,
+        date: (results.metadatas![i] as any)?.created_at || new Date().toISOString(),
+        type: 'pattern' as const,
+        project: (results.metadatas![i] as any)?.project || '',
+        content: results.documents![i] as string,
+        metadata: results.metadatas![i] as Record<string, any>
+      }))
+    } catch (error) {
+      this.logger.warn({ error }, 'Failed to fetch patterns for timeline')
+      return []
+    }
+  }
+
+  private async fetchCorrections(
+    project?: string,
+    topic?: string,
+    startDate?: string,
+    endDate?: string,
+    limit: number = 50
+  ): Promise<TimelineEntry[]> {
+    try {
+      const collection = await this.collections.getCorrections()
+
+      if (topic && this.embeddings) {
+        const embedding = await this.embeddings.generate(topic)
+        const where = this.buildWhere(project, startDate, endDate)
+        const results = await collection.query({
+          queryEmbeddings: [embedding],
+          nResults: limit,
+          where: Object.keys(where).length > 0 ? where : undefined,
+          include: ['documents', 'metadatas', 'distances']
+        })
+
+        return this.processQueryResults(results, 'correction')
+      }
+
+      const where = this.buildWhere(project, startDate, endDate)
+      const results = await collection.get({
+        where: Object.keys(where).length > 0 ? where : undefined,
+        include: ['documents', 'metadatas'],
+        limit
+      })
+
+      return results.ids.map((id, i) => ({
+        id,
+        date: (results.metadatas![i] as any)?.created_at || new Date().toISOString(),
+        type: 'correction' as const,
+        project: (results.metadatas![i] as any)?.project || '',
+        content: results.documents![i] as string,
+        metadata: results.metadatas![i] as Record<string, any>
+      }))
+    } catch (error) {
+      this.logger.warn({ error }, 'Failed to fetch corrections for timeline')
+      return []
+    }
+  }
+
+  private buildWhere(project?: string, startDate?: string, endDate?: string): Record<string, any> {
+    const conditions: any[] = []
+
+    if (project) {
+      conditions.push({ project: { $eq: project } })
+    }
+    if (startDate) {
+      conditions.push({ created_at: { $gte: startDate } })
+    }
+    if (endDate) {
+      conditions.push({ created_at: { $lte: endDate } })
+    }
+
+    if (conditions.length === 0) return {}
+    if (conditions.length === 1) return conditions[0]
+    return { $and: conditions }
+  }
+
+  private processQueryResults(results: any, type: 'decision' | 'pattern' | 'correction'): TimelineEntry[] {
+    if (!results.ids || !results.ids[0]) return []
+
+    const ids = results.ids[0] || []
+    const documents = results.documents?.[0] || []
+    const metadatas = results.metadatas?.[0] || []
+
+    return ids.map((id: string, i: number) => ({
+      id,
+      date: metadatas[i]?.created_at || new Date().toISOString(),
+      type,
+      project: metadatas[i]?.project || '',
+      content: documents[i] || '',
+      metadata: metadatas[i] || {}
+    }))
+  }
+}