claude-brain 0.3.0

package/src/knowledge/graph/builder.ts

@@ -0,0 +1,159 @@
+/**
+ * Knowledge Graph Builder
+ * Auto-populates the graph when decisions/patterns/corrections are stored
+ */
+
+import type { Logger } from 'pino'
+import type { InMemoryKnowledgeGraph } from './memory-graph'
+import { EntityExtractor, type ExtractedEntity } from '../entity-extractor'
+import { RelationshipExtractor } from '../relationship-extractor'
+import type { StoreDecisionInput, StoredDecision } from '../../memory/chroma/store'
+import type { CollectionManager } from '../../memory/chroma/collection-manager'
+
+export class KnowledgeGraphBuilder {
+  private graph: InMemoryKnowledgeGraph
+  private entityExtractor: EntityExtractor
+  private relationshipExtractor: RelationshipExtractor
+  private logger: Logger
+
+  constructor(graph: InMemoryKnowledgeGraph, logger: Logger) {
+    this.graph = graph
+    this.entityExtractor = new EntityExtractor()
+    this.relationshipExtractor = new RelationshipExtractor()
+    this.logger = logger.child({ component: 'graph-builder' })
+  }
+
+  async initialize(): Promise<void> {
+    await this.entityExtractor.initialize()
+  }
+
+  processDecision(input: StoreDecisionInput & { id: string }): void {
+    try {
+      const fullText = `${input.decision} ${input.context} ${input.reasoning}`
+      const entities = this.entityExtractor.extract(fullText)
+      const relationships = this.relationshipExtractor.extract(fullText, entities)
+
+      // Create decision node
+      const decisionNode = this.graph.addNode({
+        name: input.decision.slice(0, 100),
+        type: 'decision',
+        properties: {
+          decision_id: input.id,
+          project: input.project,
+          context: input.context,
+          reasoning: input.reasoning,
+          full_decision: input.decision
+        }
+      })
+
+      // Create project node if it doesn't exist
+      let projectNode = this.graph.findNodeByName(input.project, 'project')
+      if (!projectNode) {
+        projectNode = this.graph.addNode({
+          name: input.project,
+          type: 'project',
+          properties: {}
+        })
+      }
+
+      // Link decision to project
+      this.graph.addEdge({
+        source: decisionNode.id,
+        target: projectNode.id,
+        relationship: 'decided_in',
+        weight: 1.0,
+        properties: {}
+      })
+
+      // Create entity nodes and link to decision
+      const entityNodeMap = new Map<string, string>() // normalizedName → nodeId
+      for (const entity of entities) {
+        let entityNode = this.graph.findNodeByName(entity.normalizedName, entity.type)
+        if (!entityNode) {
+          entityNode = this.graph.addNode({
+            name: entity.normalizedName,
+            type: entity.type,
+            properties: {
+              confidence: entity.confidence,
+              source: entity.source
+            }
+          })
+        }
+        entityNodeMap.set(entity.normalizedName, entityNode.id)
+
+        // Link decision to entity
+        this.graph.addEdge({
+          source: decisionNode.id,
+          target: entityNode.id,
+          relationship: 'relates_to',
+          weight: entity.confidence,
+          properties: {}
+        })
+      }
+
+      // Create relationship edges between entities
+      for (const rel of relationships) {
+        const sourceId = entityNodeMap.get(rel.sourceEntity)
+        const targetId = entityNodeMap.get(rel.targetEntity)
+
+        if (sourceId && targetId) {
+          this.graph.addEdge({
+            source: sourceId,
+            target: targetId,
+            relationship: rel.relationship,
+            weight: rel.confidence,
+            properties: { evidence: rel.evidence }
+          })
+        }
+      }
+
+      this.logger.debug({
+        decisionId: input.id,
+        entities: entities.length,
+        relationships: relationships.length
+      }, 'Decision processed into knowledge graph')
+    } catch (error) {
+      this.logger.error({ error, decisionId: input.id }, 'Failed to process decision into graph')
+    }
+  }
+
+  async migrateExistingDecisions(collections: CollectionManager): Promise<{ processed: number; errors: number }> {
+    let processed = 0
+    let errors = 0
+
+    try {
+      const collection = await collections.getDecisions()
+      const result = await collection.get({
+        include: ['documents', 'metadatas']
+      })
+
+      for (let i = 0; i < result.ids.length; i++) {
+        try {
+          const id = result.ids[i]
+          const document = result.documents?.[i] as string
+          const metadata = result.metadatas?.[i] as Record<string, any>
+
+          if (!document || !metadata) continue
+
+          this.processDecision({
+            id,
+            project: metadata.project || 'unknown',
+            context: metadata.context || '',
+            decision: document,
+            reasoning: metadata.reasoning || ''
+          })
+
+          processed++
+        } catch {
+          errors++
+        }
+      }
+
+      this.logger.info({ processed, errors }, 'Migration of existing decisions complete')
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to migrate existing decisions')
+    }
+
+    return { processed, errors }
+  }
+}

package/src/knowledge/graph/linker.ts

@@ -0,0 +1,201 @@
+/**
+ * Cross-Reference Linker
+ * Finds implicit links, contradictions, and decision chains
+ */
+
+import type { Logger } from 'pino'
+import type { InMemoryKnowledgeGraph } from './memory-graph'
+import type { GraphNode, GraphEdge } from './schema'
+
+export interface ImplicitLink {
+  sourceId: string
+  targetId: string
+  sourceName: string
+  targetName: string
+  reason: string
+  confidence: number
+}
+
+export interface Contradiction {
+  decisionA: GraphNode
+  decisionB: GraphNode
+  reason: string
+  confidence: number
+}
+
+export interface DecisionChain {
+  topic: string
+  decisions: GraphNode[]
+}
+
+export class CrossReferenceLinker {
+  private graph: InMemoryKnowledgeGraph
+  private logger: Logger
+
+  constructor(graph: InMemoryKnowledgeGraph, logger: Logger) {
+    this.graph = graph
+    this.logger = logger.child({ component: 'cross-reference-linker' })
+  }
+
+  findImplicitLinks(): ImplicitLink[] {
+    const links: ImplicitLink[] = []
+    const decisionNodes = this.graph.findNodes({ type: 'decision' })
+
+    for (let i = 0; i < decisionNodes.length; i++) {
+      for (let j = i + 1; j < decisionNodes.length; j++) {
+        const nodeA = decisionNodes[i]
+        const nodeB = decisionNodes[j]
+
+        // Check if they share entities (connected via common neighbor)
+        const sharedEntities = this.findSharedEntities(nodeA.id, nodeB.id)
+
+        if (sharedEntities.length >= 2) {
+          // Already directly connected?
+          const existingEdges = this.graph.getEdges(nodeA.id, 'outgoing')
+          const alreadyLinked = existingEdges.some(e => e.target === nodeB.id && e.relationship === 'similar_to')
+
+          if (!alreadyLinked) {
+            links.push({
+              sourceId: nodeA.id,
+              targetId: nodeB.id,
+              sourceName: nodeA.name,
+              targetName: nodeB.name,
+              reason: `Share ${sharedEntities.length} entities: ${sharedEntities.slice(0, 3).join(', ')}`,
+              confidence: Math.min(0.9, 0.5 + sharedEntities.length * 0.1)
+            })
+          }
+        }
+      }
+    }
+
+    this.logger.debug({ linkCount: links.length }, 'Found implicit links')
+    return links
+  }
+
+  findContradictions(): Contradiction[] {
+    const contradictions: Contradiction[] = []
+    const decisionNodes = this.graph.findNodes({ type: 'decision' })
+
+    const contradictionKeywords = ['not', 'avoid', 'don\'t', 'never', 'instead', 'rather than', 'rejected']
+    const approvalKeywords = ['chose', 'use', 'adopt', 'selected', 'prefer', 'recommend']
+
+    for (let i = 0; i < decisionNodes.length; i++) {
+      for (let j = i + 1; j < decisionNodes.length; j++) {
+        const nodeA = decisionNodes[i]
+        const nodeB = decisionNodes[j]
+
+        // Check if same project
+        const projectA = nodeA.properties.project as string
+        const projectB = nodeB.properties.project as string
+        if (projectA !== projectB) continue
+
+        // Check if they share entities but with opposing sentiment
+        const sharedEntities = this.findSharedEntities(nodeA.id, nodeB.id)
+        if (sharedEntities.length === 0) continue
+
+        const textA = (nodeA.properties.full_decision as string || nodeA.name).toLowerCase()
+        const textB = (nodeB.properties.full_decision as string || nodeB.name).toLowerCase()
+
+        // Check for opposing sentiment
+        const aNegative = contradictionKeywords.some(k => textA.includes(k))
+        const bNegative = contradictionKeywords.some(k => textB.includes(k))
+        const aPositive = approvalKeywords.some(k => textA.includes(k))
+        const bPositive = approvalKeywords.some(k => textB.includes(k))
+
+        if ((aNegative && bPositive) || (aPositive && bNegative)) {
+          contradictions.push({
+            decisionA: nodeA,
+            decisionB: nodeB,
+            reason: `Opposing sentiment about shared entities: ${sharedEntities.join(', ')}`,
+            confidence: 0.7
+          })
+        }
+      }
+    }
+
+    this.logger.debug({ count: contradictions.length }, 'Found potential contradictions')
+    return contradictions
+  }
+
+  findDecisionChains(): DecisionChain[] {
+    const chains: DecisionChain[] = []
+    const decisionNodes = this.graph.findNodes({ type: 'decision' })
+
+    // Group by shared topics (entity neighbors)
+    const topicGroups = new Map<string, GraphNode[]>()
+
+    for (const decision of decisionNodes) {
+      const edges = this.graph.getEdges(decision.id, 'outgoing')
+      for (const edge of edges) {
+        if (edge.relationship === 'relates_to') {
+          const target = this.graph.getNode(edge.target)
+          if (target && target.type === 'technology') {
+            const topic = target.name
+            if (!topicGroups.has(topic)) {
+              topicGroups.set(topic, [])
+            }
+            topicGroups.get(topic)!.push(decision)
+          }
+        }
+      }
+    }
+
+    // Create chains from groups with 2+ decisions
+    for (const [topic, decisions] of topicGroups) {
+      if (decisions.length >= 2) {
+        // Sort by creation time
+        const sorted = [...decisions].sort((a, b) =>
+          a.created_at.localeCompare(b.created_at)
+        )
+        chains.push({ topic, decisions: sorted })
+      }
+    }
+
+    this.logger.debug({ chainCount: chains.length }, 'Found decision chains')
+    return chains
+  }
+
+  applyImplicitLinks(links: ImplicitLink[]): number {
+    let applied = 0
+    for (const link of links) {
+      try {
+        this.graph.addEdge({
+          source: link.sourceId,
+          target: link.targetId,
+          relationship: 'similar_to',
+          weight: link.confidence,
+          properties: { reason: link.reason, auto_linked: true }
+        })
+        applied++
+      } catch {
+        // May fail if nodes were deleted
+      }
+    }
+    return applied
+  }
+
+  private findSharedEntities(nodeAId: string, nodeBId: string): string[] {
+    const edgesA = this.graph.getEdges(nodeAId, 'outgoing')
+    const edgesB = this.graph.getEdges(nodeBId, 'outgoing')
+
+    const neighborsA = new Set<string>()
+    for (const edge of edgesA) {
+      if (edge.relationship === 'relates_to') {
+        const target = this.graph.getNode(edge.target)
+        if (target) neighborsA.add(target.name)
+      }
+    }
+
+    const shared: string[] = []
+    for (const edge of edgesB) {
+      if (edge.relationship === 'relates_to') {
+        const target = this.graph.getNode(edge.target)
+        if (target && neighborsA.has(target.name)) {
+          shared.push(target.name)
+        }
+      }
+    }
+
+    return shared
+  }
+}

package/src/knowledge/graph/memory-graph.ts

@@ -0,0 +1,359 @@
+/**
+ * In-Memory Knowledge Graph
+ * Graph data structure with traversal, persistence, and search
+ */
+
+import { randomUUID } from 'crypto'
+import { readFile, writeFile, mkdir } from 'fs/promises'
+import { dirname } from 'path'
+import type {
+  GraphNode,
+  GraphEdge,
+  KnowledgeGraph,
+  TraversalOptions,
+  EntityType,
+  SerializedGraph
+} from './schema'
+import type { Logger } from 'pino'
+
+export class InMemoryKnowledgeGraph implements KnowledgeGraph {
+  private nodes: Map<string, GraphNode> = new Map()
+  private edges: Map<string, GraphEdge> = new Map()
+  private outgoing: Map<string, Set<string>> = new Map()
+  private incoming: Map<string, Set<string>> = new Map()
+  private logger: Logger
+  private autoSaveTimer: ReturnType<typeof setInterval> | null = null
+  private dirty = false
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'knowledge-graph' })
+  }
+
+  addNode(input: Omit<GraphNode, 'id' | 'created_at' | 'updated_at'>): GraphNode {
+    const now = new Date().toISOString()
+    const node: GraphNode = {
+      ...input,
+      id: randomUUID(),
+      created_at: now,
+      updated_at: now
+    }
+    this.nodes.set(node.id, node)
+    this.outgoing.set(node.id, new Set())
+    this.incoming.set(node.id, new Set())
+    this.dirty = true
+    return node
+  }
+
+  getNode(id: string): GraphNode | undefined {
+    return this.nodes.get(id)
+  }
+
+  updateNode(id: string, updates: Partial<Omit<GraphNode, 'id' | 'created_at'>>): GraphNode | undefined {
+    const node = this.nodes.get(id)
+    if (!node) return undefined
+
+    const updated: GraphNode = {
+      ...node,
+      ...updates,
+      id: node.id,
+      created_at: node.created_at,
+      updated_at: new Date().toISOString()
+    }
+    this.nodes.set(id, updated)
+    this.dirty = true
+    return updated
+  }
+
+  deleteNode(id: string): boolean {
+    if (!this.nodes.has(id)) return false
+
+    // Delete all connected edges
+    const outEdges = this.outgoing.get(id) || new Set()
+    const inEdges = this.incoming.get(id) || new Set()
+
+    for (const edgeId of outEdges) {
+      const edge = this.edges.get(edgeId)
+      if (edge) {
+        this.incoming.get(edge.target)?.delete(edgeId)
+        this.edges.delete(edgeId)
+      }
+    }
+
+    for (const edgeId of inEdges) {
+      const edge = this.edges.get(edgeId)
+      if (edge) {
+        this.outgoing.get(edge.source)?.delete(edgeId)
+        this.edges.delete(edgeId)
+      }
+    }
+
+    this.outgoing.delete(id)
+    this.incoming.delete(id)
+    this.nodes.delete(id)
+    this.dirty = true
+    return true
+  }
+
+  addEdge(input: Omit<GraphEdge, 'id' | 'created_at'>): GraphEdge {
+    if (!this.nodes.has(input.source) || !this.nodes.has(input.target)) {
+      throw new Error(`Both source (${input.source}) and target (${input.target}) must exist`)
+    }
+
+    const edge: GraphEdge = {
+      ...input,
+      id: randomUUID(),
+      created_at: new Date().toISOString()
+    }
+
+    this.edges.set(edge.id, edge)
+
+    if (!this.outgoing.has(input.source)) this.outgoing.set(input.source, new Set())
+    if (!this.incoming.has(input.target)) this.incoming.set(input.target, new Set())
+
+    this.outgoing.get(input.source)!.add(edge.id)
+    this.incoming.get(input.target)!.add(edge.id)
+    this.dirty = true
+    return edge
+  }
+
+  getEdges(nodeId: string, direction: 'outgoing' | 'incoming' | 'both' = 'both'): GraphEdge[] {
+    const result: GraphEdge[] = []
+
+    if (direction === 'outgoing' || direction === 'both') {
+      const outEdgeIds = this.outgoing.get(nodeId) || new Set()
+      for (const edgeId of outEdgeIds) {
+        const edge = this.edges.get(edgeId)
+        if (edge) result.push(edge)
+      }
+    }
+
+    if (direction === 'incoming' || direction === 'both') {
+      const inEdgeIds = this.incoming.get(nodeId) || new Set()
+      for (const edgeId of inEdgeIds) {
+        const edge = this.edges.get(edgeId)
+        if (edge) result.push(edge)
+      }
+    }
+
+    return result
+  }
+
+  deleteEdge(id: string): boolean {
+    const edge = this.edges.get(id)
+    if (!edge) return false
+
+    this.outgoing.get(edge.source)?.delete(id)
+    this.incoming.get(edge.target)?.delete(id)
+    this.edges.delete(id)
+    this.dirty = true
+    return true
+  }
+
+  traverse(startId: string, options: TraversalOptions = {}): GraphNode[] {
+    const { maxDepth = 3, nodeTypes, relationshipTypes, limit = 100 } = options
+
+    if (!this.nodes.has(startId)) return []
+
+    const visited = new Set<string>()
+    const result: GraphNode[] = []
+    const queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }]
+
+    while (queue.length > 0 && result.length < limit) {
+      const { id, depth } = queue.shift()!
+
+      if (visited.has(id)) continue
+      visited.add(id)
+
+      const node = this.nodes.get(id)
+      if (!node) continue
+
+      if (nodeTypes && !nodeTypes.includes(node.type)) {
+        // Don't add to results but still traverse through
+      } else {
+        result.push(node)
+      }
+
+      if (depth >= maxDepth) continue
+
+      // Get neighbors via edges
+      const edges = this.getEdges(id)
+      for (const edge of edges) {
+        if (relationshipTypes && !relationshipTypes.includes(edge.relationship)) continue
+
+        const neighborId = edge.source === id ? edge.target : edge.source
+        if (!visited.has(neighborId)) {
+          queue.push({ id: neighborId, depth: depth + 1 })
+        }
+      }
+    }
+
+    return result
+  }
+
+  shortestPath(sourceId: string, targetId: string): string[] | null {
+    if (!this.nodes.has(sourceId) || !this.nodes.has(targetId)) return null
+    if (sourceId === targetId) return [sourceId]
+
+    const visited = new Set<string>()
+    const parent = new Map<string, string>()
+    const queue: string[] = [sourceId]
+    visited.add(sourceId)
+
+    while (queue.length > 0) {
+      const current = queue.shift()!
+
+      const edges = this.getEdges(current)
+      for (const edge of edges) {
+        const neighbor = edge.source === current ? edge.target : edge.source
+
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor)
+          parent.set(neighbor, current)
+
+          if (neighbor === targetId) {
+            // Reconstruct path
+            const path: string[] = [targetId]
+            let node = targetId
+            while (parent.has(node)) {
+              node = parent.get(node)!
+              path.unshift(node)
+            }
+            return path
+          }
+
+          queue.push(neighbor)
+        }
+      }
+    }
+
+    return null
+  }
+
+  findNodes(query: { type?: EntityType; name?: string; properties?: Record<string, unknown> }): GraphNode[] {
+    const results: GraphNode[] = []
+
+    for (const node of this.nodes.values()) {
+      if (query.type && node.type !== query.type) continue
+      if (query.name && !node.name.toLowerCase().includes(query.name.toLowerCase())) continue
+
+      if (query.properties) {
+        let match = true
+        for (const [key, value] of Object.entries(query.properties)) {
+          if (node.properties[key] !== value) {
+            match = false
+            break
+          }
+        }
+        if (!match) continue
+      }
+
+      results.push(node)
+    }
+
+    return results
+  }
+
+  findNodeByName(name: string, type?: EntityType): GraphNode | undefined {
+    const lowerName = name.toLowerCase()
+    for (const node of this.nodes.values()) {
+      if (node.name.toLowerCase() === lowerName) {
+        if (type && node.type !== type) continue
+        return node
+      }
+    }
+    return undefined
+  }
+
+  getNodeCount(): number {
+    return this.nodes.size
+  }
+
+  getEdgeCount(): number {
+    return this.edges.size
+  }
+
+  async save(path: string): Promise<void> {
+    const data: SerializedGraph = {
+      nodes: Array.from(this.nodes.values()),
+      edges: Array.from(this.edges.values()),
+      version: '1.0.0',
+      saved_at: new Date().toISOString()
+    }
+
+    try {
+      await mkdir(dirname(path), { recursive: true })
+      await writeFile(path, JSON.stringify(data, null, 2), 'utf-8')
+      this.dirty = false
+      this.logger.debug({ path, nodes: data.nodes.length, edges: data.edges.length }, 'Graph saved')
+    } catch (error) {
+      this.logger.error({ error, path }, 'Failed to save graph')
+      throw error
+    }
+  }
+
+  async load(path: string): Promise<void> {
+    try {
+      const content = await readFile(path, 'utf-8')
+      const data: SerializedGraph = JSON.parse(content)
+
+      this.nodes.clear()
+      this.edges.clear()
+      this.outgoing.clear()
+      this.incoming.clear()
+
+      for (const node of data.nodes) {
+        this.nodes.set(node.id, node)
+        this.outgoing.set(node.id, new Set())
+        this.incoming.set(node.id, new Set())
+      }
+
+      for (const edge of data.edges) {
+        this.edges.set(edge.id, edge)
+        this.outgoing.get(edge.source)?.add(edge.id)
+        this.incoming.get(edge.target)?.add(edge.id)
+      }
+
+      this.dirty = false
+      this.logger.info({ path, nodes: data.nodes.length, edges: data.edges.length }, 'Graph loaded')
+    } catch (error: any) {
+      if (error.code === 'ENOENT') {
+        this.logger.info({ path }, 'No existing graph file, starting fresh')
+        return
+      }
+      this.logger.error({ error, path }, 'Failed to load graph')
+      throw error
+    }
+  }
+
+  startAutoSave(path: string, intervalMs: number = 60000): void {
+    this.stopAutoSave()
+    this.autoSaveTimer = setInterval(async () => {
+      if (this.dirty) {
+        try {
+          await this.save(path)
+        } catch (error) {
+          this.logger.error({ error }, 'Auto-save failed')
+        }
+      }
+    }, intervalMs)
+  }
+
+  stopAutoSave(): void {
+    if (this.autoSaveTimer) {
+      clearInterval(this.autoSaveTimer)
+      this.autoSaveTimer = null
+    }
+  }
+
+  isDirty(): boolean {
+    return this.dirty
+  }
+
+  clear(): void {
+    this.nodes.clear()
+    this.edges.clear()
+    this.outgoing.clear()
+    this.incoming.clear()
+    this.dirty = true
+  }
+}