claude-brain 0.3.0

package/src/knowledge/graph/schema.ts

@@ -0,0 +1,99 @@
+/**
+ * Knowledge Graph Schema
+ * Type definitions for the knowledge graph data structures
+ */
+
+export type EntityType =
+  | 'project'
+  | 'technology'
+  | 'concept'
+  | 'person'
+  | 'file'
+  | 'decision'
+  | 'pattern'
+  | 'correction'
+  | 'date'
+
+export type RelationshipType =
+  | 'uses'
+  | 'depends_on'
+  | 'replaces'
+  | 'contradicts'
+  | 'relates_to'
+  | 'part_of'
+  | 'created_by'
+  | 'decided_in'
+  | 'similar_to'
+  | 'precedes'
+  | 'follows'
+
+export interface GraphNode {
+  id: string
+  name: string
+  type: EntityType
+  properties: Record<string, unknown>
+  created_at: string
+  updated_at: string
+}
+
+export interface GraphEdge {
+  id: string
+  source: string
+  target: string
+  relationship: RelationshipType
+  weight: number
+  properties: Record<string, unknown>
+  created_at: string
+}
+
+export interface TraversalOptions {
+  maxDepth?: number
+  nodeTypes?: EntityType[]
+  relationshipTypes?: RelationshipType[]
+  limit?: number
+}
+
+export interface GraphSearchOptions {
+  query?: string
+  nodeType?: EntityType
+  relationshipType?: RelationshipType
+  startNodeId?: string
+  hops?: number
+  limit?: number
+  alpha?: number
+}
+
+export interface GraphSearchResult {
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  paths: string[][]
+  scores: Map<string, number>
+}
+
+export interface KnowledgeGraph {
+  addNode(node: Omit<GraphNode, 'id' | 'created_at' | 'updated_at'>): GraphNode
+  getNode(id: string): GraphNode | undefined
+  updateNode(id: string, updates: Partial<Omit<GraphNode, 'id' | 'created_at'>>): GraphNode | undefined
+  deleteNode(id: string): boolean
+
+  addEdge(edge: Omit<GraphEdge, 'id' | 'created_at'>): GraphEdge
+  getEdges(nodeId: string, direction?: 'outgoing' | 'incoming' | 'both'): GraphEdge[]
+  deleteEdge(id: string): boolean
+
+  traverse(startId: string, options?: TraversalOptions): GraphNode[]
+  shortestPath(sourceId: string, targetId: string): string[] | null
+  findNodes(query: { type?: EntityType; name?: string; properties?: Record<string, unknown> }): GraphNode[]
+
+  getNodeCount(): number
+  getEdgeCount(): number
+
+  save(path: string): Promise<void>
+  load(path: string): Promise<void>
+}
+
+export interface SerializedGraph {
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  version: string
+  saved_at: string
+}

package/src/knowledge/graph/search.ts

@@ -0,0 +1,168 @@
+/**
+ * Graph Search Engine
+ * Combines vector similarity with graph proximity for enhanced search
+ */
+
+import type { Logger } from 'pino'
+import type { InMemoryKnowledgeGraph } from './memory-graph'
+import type { GraphNode, GraphEdge, GraphSearchOptions, GraphSearchResult } from './schema'
+
+export class GraphSearchEngine {
+  private graph: InMemoryKnowledgeGraph
+  private logger: Logger
+
+  constructor(graph: InMemoryKnowledgeGraph, logger: Logger) {
+    this.graph = graph
+    this.logger = logger.child({ component: 'graph-search' })
+  }
+
+  search(options: GraphSearchOptions): GraphSearchResult {
+    const {
+      query,
+      nodeType,
+      startNodeId,
+      hops = 2,
+      limit = 20,
+      alpha = 0.6
+    } = options
+
+    const scores = new Map<string, number>()
+    const resultNodes: GraphNode[] = []
+    const resultEdges: GraphEdge[] = []
+    const paths: string[][] = []
+
+    if (startNodeId) {
+      // Graph expansion from a starting node
+      return this.expandFromNode(startNodeId, hops, limit, nodeType)
+    }
+
+    if (query) {
+      // Text-based search: find nodes matching query, then expand
+      const matchingNodes = this.findMatchingNodes(query, nodeType)
+
+      for (const node of matchingNodes) {
+        const nameScore = this.calculateNameScore(node.name, query)
+        scores.set(node.id, nameScore)
+
+        // Expand from each matching node
+        const neighbors = this.graph.traverse(node.id, {
+          maxDepth: hops,
+          nodeTypes: nodeType ? [nodeType] : undefined,
+          limit: Math.ceil(limit / Math.max(matchingNodes.length, 1))
+        })
+
+        for (const neighbor of neighbors) {
+          if (!scores.has(neighbor.id)) {
+            // Graph proximity score: decreases with distance
+            const path = this.graph.shortestPath(node.id, neighbor.id)
+            const distance = path ? path.length - 1 : hops + 1
+            const graphScore = 1 / (1 + distance)
+
+            // Combined score
+            const combinedScore = alpha * nameScore + (1 - alpha) * graphScore
+            scores.set(neighbor.id, Math.max(scores.get(neighbor.id) || 0, combinedScore))
+
+            if (path && path.length > 1) {
+              paths.push(path)
+            }
+          }
+        }
+      }
+
+      // Collect nodes sorted by score
+      const sortedEntries = Array.from(scores.entries())
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, limit)
+
+      for (const [nodeId] of sortedEntries) {
+        const node = this.graph.getNode(nodeId)
+        if (node) resultNodes.push(node)
+      }
+
+      // Collect edges between result nodes
+      const resultNodeIds = new Set(resultNodes.map(n => n.id))
+      for (const node of resultNodes) {
+        const edges = this.graph.getEdges(node.id)
+        for (const edge of edges) {
+          if (resultNodeIds.has(edge.source) && resultNodeIds.has(edge.target)) {
+            if (!resultEdges.some(e => e.id === edge.id)) {
+              resultEdges.push(edge)
+            }
+          }
+        }
+      }
+    }
+
+    return { nodes: resultNodes, edges: resultEdges, paths, scores }
+  }
+
+  findRelated(nodeId: string, hops: number = 2): GraphSearchResult {
+    return this.expandFromNode(nodeId, hops, 50)
+  }
+
+  private expandFromNode(
+    nodeId: string,
+    hops: number,
+    limit: number,
+    nodeType?: string
+  ): GraphSearchResult {
+    const scores = new Map<string, number>()
+    const nodes = this.graph.traverse(nodeId, {
+      maxDepth: hops,
+      nodeTypes: nodeType ? [nodeType as any] : undefined,
+      limit
+    })
+
+    const resultEdges: GraphEdge[] = []
+    const paths: string[][] = []
+    const nodeIds = new Set(nodes.map(n => n.id))
+
+    for (const node of nodes) {
+      const path = this.graph.shortestPath(nodeId, node.id)
+      const distance = path ? path.length - 1 : 0
+      scores.set(node.id, 1 / (1 + distance))
+
+      if (path && path.length > 1) {
+        paths.push(path)
+      }
+
+      const edges = this.graph.getEdges(node.id)
+      for (const edge of edges) {
+        if (nodeIds.has(edge.source) && nodeIds.has(edge.target)) {
+          if (!resultEdges.some(e => e.id === edge.id)) {
+            resultEdges.push(edge)
+          }
+        }
+      }
+    }
+
+    return { nodes, edges: resultEdges, paths, scores }
+  }
+
+  private findMatchingNodes(query: string, nodeType?: string): GraphNode[] {
+    const lowerQuery = query.toLowerCase()
+    const queryTerms = lowerQuery.split(/\s+/).filter(t => t.length > 1)
+
+    return this.graph.findNodes({
+      type: nodeType as any,
+      name: undefined
+    }).filter(node => {
+      const lowerName = node.name.toLowerCase()
+      return queryTerms.some(term => lowerName.includes(term) || term.includes(lowerName))
+    })
+  }
+
+  private calculateNameScore(nodeName: string, query: string): number {
+    const lowerName = nodeName.toLowerCase()
+    const lowerQuery = query.toLowerCase()
+
+    if (lowerName === lowerQuery) return 1.0
+    if (lowerQuery.includes(lowerName)) return 0.9
+    if (lowerName.includes(lowerQuery)) return 0.8
+
+    // Partial term matching
+    const queryTerms = lowerQuery.split(/\s+/)
+    const matchCount = queryTerms.filter(t => lowerName.includes(t)).length
+    return matchCount > 0 ? 0.5 + (0.3 * matchCount / queryTerms.length) : 0.3
+  }
+}

package/src/knowledge/relationship-extractor.ts

@@ -0,0 +1,108 @@
+/**
+ * Relationship Extractor
+ * Pattern-based extraction of relationships between entities
+ */
+
+import type { RelationshipType } from './graph/schema'
+import type { ExtractedEntity } from './entity-extractor'
+
+export interface ExtractedRelationship {
+  sourceEntity: string
+  targetEntity: string
+  relationship: RelationshipType
+  confidence: number
+  evidence: string
+}
+
+interface RelationshipPattern {
+  regex: RegExp
+  relationship: RelationshipType
+  confidence: number
+  sourceGroup: number
+  targetGroup: number
+}
+
+const PATTERNS: RelationshipPattern[] = [
+  // "chose X for Y", "use X for Y", "selected X for Y"
+  { regex: /(?:chose|choose|use|using|selected|picked)\s+(\w[\w.-]*)\s+(?:for|in|with)\s+(\w[\w.-]*)/gi, relationship: 'uses', confidence: 0.85, sourceGroup: 2, targetGroup: 1 },
+  // "X uses Y", "X depends on Y"
+  { regex: /(\w[\w.-]*)\s+(?:uses|utilizes|leverages|employs)\s+(\w[\w.-]*)/gi, relationship: 'uses', confidence: 0.8, sourceGroup: 1, targetGroup: 2 },
+  // "X depends on Y", "X requires Y"
+  { regex: /(\w[\w.-]*)\s+(?:depends?\s+on|requires|needs)\s+(\w[\w.-]*)/gi, relationship: 'depends_on', confidence: 0.85, sourceGroup: 1, targetGroup: 2 },
+  // "replaced X with Y", "migrated from X to Y"
+  { regex: /(?:replaced|replace|swap(?:ped)?)\s+(\w[\w.-]*)\s+(?:with|for)\s+(\w[\w.-]*)/gi, relationship: 'replaces', confidence: 0.9, sourceGroup: 2, targetGroup: 1 },
+  { regex: /(?:migrated?|moved?|switched?)\s+(?:from\s+)?(\w[\w.-]*)\s+to\s+(\w[\w.-]*)/gi, relationship: 'replaces', confidence: 0.85, sourceGroup: 2, targetGroup: 1 },
+  // "X contradicts Y", "X conflicts with Y"
+  { regex: /(\w[\w.-]*)\s+(?:contradicts|conflicts?\s+with|incompatible\s+with)\s+(\w[\w.-]*)/gi, relationship: 'contradicts', confidence: 0.8, sourceGroup: 1, targetGroup: 2 },
+  // "X is part of Y", "X belongs to Y"
+  { regex: /(\w[\w.-]*)\s+(?:is\s+part\s+of|belongs?\s+to|included?\s+in)\s+(\w[\w.-]*)/gi, relationship: 'part_of', confidence: 0.8, sourceGroup: 1, targetGroup: 2 },
+  // "X relates to Y", "X is related to Y"
+  { regex: /(\w[\w.-]*)\s+(?:relates?\s+to|is\s+related\s+to|connects?\s+(?:to|with))\s+(\w[\w.-]*)/gi, relationship: 'relates_to', confidence: 0.7, sourceGroup: 1, targetGroup: 2 },
+  // "X is similar to Y", "X like Y"
+  { regex: /(\w[\w.-]*)\s+(?:is\s+similar\s+to|like|resembles|comparable\s+to)\s+(\w[\w.-]*)/gi, relationship: 'similar_to', confidence: 0.7, sourceGroup: 1, targetGroup: 2 },
+  // "after X, Y" / "X then Y" (temporal sequencing)
+  { regex: /(?:after|following)\s+(\w[\w.-]*)\s*,?\s*(?:we\s+)?(?:use|chose|moved\s+to|adopted)\s+(\w[\w.-]*)/gi, relationship: 'follows', confidence: 0.7, sourceGroup: 2, targetGroup: 1 },
+]
+
+export class RelationshipExtractor {
+  extract(text: string, entities: ExtractedEntity[]): ExtractedRelationship[] {
+    const relationships: ExtractedRelationship[] = []
+    const entityNames = new Set(entities.map(e => e.normalizedName))
+
+    for (const pattern of PATTERNS) {
+      let match: RegExpExecArray | null
+      const regex = new RegExp(pattern.regex.source, pattern.regex.flags)
+
+      while ((match = regex.exec(text)) !== null) {
+        const rawSource = match[pattern.sourceGroup]?.toLowerCase()
+        const rawTarget = match[pattern.targetGroup]?.toLowerCase()
+
+        if (!rawSource || !rawTarget) continue
+        if (rawSource === rawTarget) continue
+
+        // Check if at least one entity is known
+        const sourceKnown = entityNames.has(rawSource) || this.findEntityMatch(rawSource, entities)
+        const targetKnown = entityNames.has(rawTarget) || this.findEntityMatch(rawTarget, entities)
+
+        if (!sourceKnown && !targetKnown) continue
+
+        const sourceName = this.resolveEntityName(rawSource, entities) || rawSource
+        const targetName = this.resolveEntityName(rawTarget, entities) || rawTarget
+
+        // Avoid duplicates
+        const exists = relationships.some(r =>
+          r.sourceEntity === sourceName &&
+          r.targetEntity === targetName &&
+          r.relationship === pattern.relationship
+        )
+
+        if (!exists) {
+          relationships.push({
+            sourceEntity: sourceName,
+            targetEntity: targetName,
+            relationship: pattern.relationship,
+            confidence: pattern.confidence * (sourceKnown && targetKnown ? 1.0 : 0.8),
+            evidence: match[0].trim()
+          })
+        }
+      }
+    }
+
+    return relationships
+  }
+
+  private findEntityMatch(name: string, entities: ExtractedEntity[]): boolean {
+    return entities.some(e =>
+      e.normalizedName === name ||
+      e.name.toLowerCase() === name
+    )
+  }
+
+  private resolveEntityName(name: string, entities: ExtractedEntity[]): string | undefined {
+    const entity = entities.find(e =>
+      e.normalizedName === name ||
+      e.name.toLowerCase() === name
+    )
+    return entity?.normalizedName
+  }
+}

package/src/memory/chroma/client.ts

@@ -0,0 +1,169 @@
+import { ChromaClient, Collection } from 'chromadb'
+import type { Logger } from 'pino'
+import type { ChromaConfig } from './config'
+
+export class ChromaClientManager {
+  private client: ChromaClient | null = null
+  private logger: Logger
+  private config: ChromaConfig
+  private isConnected: boolean = false
+  private collections: Map<string, Collection> = new Map()
+
+  constructor(logger: Logger, config: ChromaConfig) {
+    this.logger = logger.child({ component: 'chroma-client' })
+    this.config = config
+  }
+
+  async initialize(): Promise<void> {
+    this.logger.info({ mode: this.config.mode }, 'Initializing ChromaDB client')
+
+    try {
+      const authConfig = this.config.chromaAuthToken ? {
+        headers: {
+          'Authorization': `Bearer ${this.config.chromaAuthToken}`,
+          'X-Chroma-Token': this.config.chromaAuthToken
+        },
+        ...(this.config.chromaTenant ? { tenant: this.config.chromaTenant } : {}),
+        ...(this.config.chromaDatabase ? { database: this.config.chromaDatabase } : {})
+      } : {}
+
+      switch (this.config.mode) {
+        case 'persistent':
+          this.client = new ChromaClient({
+            path: this.config.path,
+            ...authConfig
+          })
+          break
+
+        case 'client-server':
+          if (!this.config.host || !this.config.port) {
+            throw new Error('Host and port required for client-server mode')
+          }
+          this.client = new ChromaClient({
+            host: this.config.host,
+            port: this.config.port,
+            ...authConfig
+          })
+          break
+
+        case 'cloud':
+          if (!this.config.host) {
+            throw new Error('Host URL required for cloud mode')
+          }
+          const hostWithProtocol = this.config.host.startsWith('http')
+            ? this.config.host
+            : `https://${this.config.host}`
+          const url = new URL(hostWithProtocol)
+          this.client = new ChromaClient({
+            host: url.hostname,
+            port: url.port ? parseInt(url.port) : (url.protocol === 'https:' ? 443 : 80),
+            ssl: url.protocol === 'https:',
+            ...authConfig
+          })
+          break
+
+        case 'ephemeral':
+          try {
+            this.client = new ChromaClient()
+          } catch (err) {
+            this.logger.warn({ error: err }, 'Ephemeral mode failed, attempting client-server mode')
+            this.client = new ChromaClient({
+              host: 'localhost',
+              port: 8000,
+              ssl: false,
+              ...authConfig
+            })
+          }
+          break
+      }
+
+      try {
+        await this.client.heartbeat()
+        this.isConnected = true
+        this.logger.info('ChromaDB client initialized successfully')
+      } catch (heartbeatError) {
+        this.logger.warn({ error: heartbeatError }, 'ChromaDB heartbeat failed, connection may not be fully established')
+        this.isConnected = true
+      }
+
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to initialize ChromaDB client')
+      throw error
+    }
+  }
+
+  async getCollection(name: string): Promise<Collection> {
+    if (!this.client) {
+      throw new Error('ChromaDB client not initialized')
+    }
+
+    if (this.collections.has(name)) {
+      return this.collections.get(name)!
+    }
+
+    try {
+      const collection = await this.client.getOrCreateCollection({
+        name,
+        metadata: {
+          'hnsw:space': 'cosine',
+          'created_at': new Date().toISOString()
+        }
+      })
+
+      this.collections.set(name, collection)
+      this.logger.info({ collection: name }, 'Collection retrieved/created')
+
+      return collection
+
+    } catch (error) {
+      this.logger.error({ error, collection: name }, 'Failed to get collection')
+      throw error
+    }
+  }
+
+  async listCollections(): Promise<string[]> {
+    if (!this.client) {
+      throw new Error('ChromaDB client not initialized')
+    }
+
+    const collections = await this.client.listCollections()
+    return collections.map(c => c.name)
+  }
+
+  async deleteCollection(name: string): Promise<void> {
+    if (!this.client) {
+      throw new Error('ChromaDB client not initialized')
+    }
+
+    await this.client.deleteCollection({ name })
+    this.collections.delete(name)
+    this.logger.info({ collection: name }, 'Collection deleted')
+  }
+
+  async healthCheck(): Promise<boolean> {
+    if (!this.client) return false
+
+    try {
+      await this.client.heartbeat()
+      return true
+    } catch {
+      this.isConnected = false
+      return false
+    }
+  }
+
+  getStatus(): { connected: boolean; mode: string; collections: number } {
+    return {
+      connected: this.isConnected,
+      mode: this.config.mode,
+      collections: this.collections.size
+    }
+  }
+
+  async close(): Promise<void> {
+    this.collections.clear()
+    this.client = null
+    this.isConnected = false
+    this.logger.info('ChromaDB client closed')
+  }
+}

package/src/memory/chroma/collection-manager.ts

@@ -0,0 +1,94 @@
+import type { Collection } from 'chromadb'
+import type { Logger } from 'pino'
+import type { ChromaClientManager } from './client'
+import { COLLECTIONS, type CollectionName } from './schemas'
+
+export class CollectionManager {
+  private logger: Logger
+  private client: ChromaClientManager
+  private initialized: boolean = false
+
+  constructor(logger: Logger, client: ChromaClientManager) {
+    this.logger = logger.child({ component: 'collection-manager' })
+    this.client = client
+  }
+
+  async initialize(): Promise<void> {
+    this.logger.info('Initializing collections')
+
+    try {
+      for (const collectionName of Object.values(COLLECTIONS)) {
+        await this.client.getCollection(collectionName)
+      }
+
+      this.initialized = true
+      this.logger.info('All collections initialized')
+
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to initialize collections')
+      throw error
+    }
+  }
+
+  async getDecisions(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.DECISIONS)
+  }
+
+  async getMemories(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.MEMORIES)
+  }
+
+  async getPatterns(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.PATTERNS)
+  }
+
+  async getCorrections(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.CORRECTIONS)
+  }
+
+  async getFeedback(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.FEEDBACK)
+  }
+
+  async getEpisodes(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.EPISODES)
+  }
+
+  async getArchivedMemories(): Promise<Collection> {
+    return this.client.getCollection(COLLECTIONS.ARCHIVED_MEMORIES)
+  }
+
+  async getProjectCollection(projectName: string): Promise<Collection> {
+    const collectionName = `project_${projectName.toLowerCase().replace(/[^a-z0-9]/g, '_')}`
+    return this.client.getCollection(collectionName)
+  }
+
+  async getStats(): Promise<Record<string, number>> {
+    const stats: Record<string, number> = {}
+
+    for (const collectionName of Object.values(COLLECTIONS)) {
+      try {
+        const collection = await this.client.getCollection(collectionName)
+        stats[collectionName] = await collection.count()
+      } catch {
+        stats[collectionName] = 0
+      }
+    }
+
+    return stats
+  }
+
+  async clearAll(): Promise<void> {
+    this.logger.warn('Clearing all collections')
+
+    for (const collectionName of Object.values(COLLECTIONS)) {
+      try {
+        await this.client.deleteCollection(collectionName)
+      } catch (error) {
+        this.logger.error({ error, collection: collectionName }, 'Failed to delete collection')
+      }
+    }
+
+    await this.initialize()
+  }
+}

package/src/memory/chroma/config.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod'
+
+export const ChromaConfigSchema = z.object({
+  mode: z.enum(['persistent', 'client-server', 'ephemeral', 'cloud']).default('persistent'),
+  path: z.string().default('./data/chroma'),
+  host: z.string().optional(),
+  port: z.number().optional(),
+  embeddingProvider: z.enum(['default', 'transformers', 'openai']).default('default'),
+  embeddingModel: z.string().default('Xenova/all-MiniLM-L6-v2'),
+  defaultCollection: z.string().default('memories'),
+  batchSize: z.number().default(100),
+  openaiApiKey: z.string().optional(),
+  chromaAuthToken: z.string().optional(),
+  chromaTenant: z.string().optional(),
+  chromaDatabase: z.string().optional()
+})
+
+export type ChromaConfig = z.infer<typeof ChromaConfigSchema>
+
+export const DEFAULT_CHROMA_CONFIG: ChromaConfig = {
+  mode: 'persistent',
+  path: './data/chroma',
+  embeddingProvider: 'default',
+  embeddingModel: 'Xenova/all-MiniLM-L6-v2',
+  defaultCollection: 'memories',
+  batchSize: 100
+}
+
+export function getChromaConfigFromEnv(): Partial<ChromaConfig> {
+  const config: Partial<ChromaConfig> = {
+    chromaAuthToken: process.env.CHROMA_API_KEY,
+    chromaTenant: process.env.CHROMA_TENANT,
+    chromaDatabase: process.env.CHROMA_DATABASE
+  }
+
+  if (process.env.CHROMA_HOST) {
+    config.host = process.env.CHROMA_HOST
+    config.mode = 'cloud'
+  }
+
+  if (process.env.CHROMA_EMBEDDING_PROVIDER) {
+    config.embeddingProvider = process.env.CHROMA_EMBEDDING_PROVIDER as any
+  }
+
+  return config
+}