claudecode-rlm 1.0.0

package/src/graph/traversal.ts

@@ -0,0 +1,348 @@
+/**
+ * Graph traversal and search for RLM-Graph.
+ *
+ * Provides utilities for navigating and searching the knowledge graph:
+ * - GraphTraverser: Breadth-first and path-based traversal
+ * - GraphSearcher: Combined keyword and semantic search
+ */
+
+import {
+  type GraphNode,
+  type GraphSearchResult,
+  NodeType,
+  RelationType,
+} from "./types.js"
+import { GraphStorage } from "./storage.js"
+
+/**
+ * Traverses the knowledge graph to find related context.
+ */
+export namespace GraphTraverser {
+  /**
+   * Get neighboring nodes.
+   */
+  export function getNeighbors(
+    sessionID: string,
+    nodeID: string,
+    direction: "outgoing" | "incoming" | "both" = "outgoing",
+    relationship?: RelationType
+  ): GraphNode[] {
+    return GraphStorage.getNeighbors(sessionID, nodeID, direction, relationship)
+  }
+
+  /**
+   * Expand context by traversing from given nodes using BFS.
+   */
+  export function expandContext(
+    sessionID: string,
+    nodeIDs: string[],
+    maxDepth: number = 2,
+    maxNodes: number = 20
+  ): GraphNode[] {
+    const visited = new Set<string>()
+    const result: GraphNode[] = []
+    const queue: Array<{ nodeID: string; depth: number }> = nodeIDs.map(
+      (nodeID) => ({ nodeID, depth: 0 })
+    )
+
+    while (queue.length > 0 && result.length < maxNodes) {
+      const { nodeID, depth } = queue.shift()!
+
+      if (visited.has(nodeID)) {
+        continue
+      }
+
+      visited.add(nodeID)
+
+      const node = GraphStorage.getNode(sessionID, nodeID)
+      if (node) {
+        result.push(node)
+      }
+
+      if (depth < maxDepth) {
+        // Get neighbors from edges
+        const edges = GraphStorage.getEdges(sessionID, nodeID, "both")
+        for (const edge of edges) {
+          const neighborID =
+            edge.sourceID === nodeID ? edge.targetID : edge.sourceID
+          if (!visited.has(neighborID)) {
+            queue.push({ nodeID: neighborID, depth: depth + 1 })
+          }
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Find a path between two nodes using BFS.
+   */
+  export function findPath(
+    sessionID: string,
+    startID: string,
+    endID: string,
+    maxDepth: number = 5
+  ): GraphNode[] | null {
+    const visited = new Set<string>()
+    const queue: Array<{ nodeID: string; path: string[] }> = [
+      { nodeID: startID, path: [startID] },
+    ]
+
+    while (queue.length > 0) {
+      const { nodeID, path } = queue.shift()!
+
+      if (nodeID === endID) {
+        // Build node list from path
+        const nodes: GraphNode[] = []
+        for (const id of path) {
+          const node = GraphStorage.getNode(sessionID, id)
+          if (node) {
+            nodes.push(node)
+          }
+        }
+        return nodes
+      }
+
+      if (path.length >= maxDepth) {
+        continue
+      }
+
+      visited.add(nodeID)
+
+      const edges = GraphStorage.getEdges(sessionID, nodeID, "both")
+      for (const edge of edges) {
+        const neighborID =
+          edge.sourceID === nodeID ? edge.targetID : edge.sourceID
+        if (!visited.has(neighborID)) {
+          queue.push({ nodeID: neighborID, path: [...path, neighborID] })
+        }
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Get all chunks that mention a specific entity.
+   */
+  export function getEntityContext(
+    sessionID: string,
+    entityName: string,
+    maxChunks: number = 10
+  ): GraphNode[] {
+    // Find entity nodes matching the name
+    const entities = GraphStorage.searchNodes(
+      sessionID,
+      entityName,
+      NodeType.ENTITY,
+      5
+    )
+
+    const chunkIDs = new Set<string>()
+
+    for (const entity of entities) {
+      // Find chunks that mention this entity (incoming MENTIONS edges)
+      const edges = GraphStorage.getEdges(sessionID, entity.id, "incoming")
+      for (const edge of edges) {
+        if (edge.relationship === RelationType.MENTIONS) {
+          chunkIDs.add(edge.sourceID)
+        }
+      }
+    }
+
+    // Get chunk nodes
+    const chunks: GraphNode[] = []
+    for (const chunkID of Array.from(chunkIDs).slice(0, maxChunks)) {
+      const node = GraphStorage.getNode(sessionID, chunkID)
+      if (node) {
+        chunks.push(node)
+      }
+    }
+
+    return chunks
+  }
+
+  /**
+   * Get the parent document for a chunk.
+   */
+  export function getDocumentForChunk(
+    sessionID: string,
+    chunkID: string
+  ): GraphNode | null {
+    // Navigate up: chunk -> section -> document
+    const chunkEdges = GraphStorage.getEdges(sessionID, chunkID, "incoming")
+    for (const edge of chunkEdges) {
+      if (edge.relationship === RelationType.HAS_CHUNK) {
+        // Found the section
+        const sectionID = edge.sourceID
+
+        // Now find the document
+        const sectionEdges = GraphStorage.getEdges(
+          sessionID,
+          sectionID,
+          "incoming"
+        )
+        for (const sectionEdge of sectionEdges) {
+          if (sectionEdge.relationship === RelationType.HAS_SECTION) {
+            return GraphStorage.getNode(sessionID, sectionEdge.sourceID)
+          }
+        }
+      }
+    }
+
+    return null
+  }
+}
+
+/**
+ * Search the knowledge graph using combined strategies.
+ */
+export namespace GraphSearcher {
+  /**
+   * Search the graph for relevant nodes.
+   */
+  export function search(
+    sessionID: string,
+    query: string,
+    options: {
+      limit?: number
+      expandContext?: boolean
+      nodeType?: NodeType
+    } = {}
+  ): GraphSearchResult[] {
+    const { limit = 10, expandContext = true, nodeType = NodeType.CHUNK } = options
+    const results = new Map<string, GraphSearchResult>()
+
+    // 1. Keyword search
+    const keywordMatches = GraphStorage.searchNodes(
+      sessionID,
+      query,
+      nodeType,
+      limit * 2
+    )
+
+    const queryTerms = new Set(query.toLowerCase().split(/\s+/))
+
+    for (const node of keywordMatches) {
+      const contentTerms = new Set(node.content.toLowerCase().split(/\s+/))
+      const overlap = [...queryTerms].filter((t) => contentTerms.has(t)).length
+      const score = overlap / Math.max(queryTerms.size, 1)
+
+      results.set(node.id, {
+        node,
+        score: score * 0.4, // Keyword weight: 0.4
+        matchedOn: "content",
+      })
+    }
+
+    // 2. Entity-based search
+    const entities = extractQueryEntities(query)
+    for (const entityName of entities) {
+      const chunks = GraphTraverser.getEntityContext(sessionID, entityName, 5)
+      for (const chunk of chunks) {
+        if (results.has(chunk.id)) {
+          // Boost existing result
+          const existing = results.get(chunk.id)!
+          results.set(chunk.id, {
+            ...existing,
+            score: existing.score + 0.3,
+          })
+        } else {
+          results.set(chunk.id, {
+            node: chunk,
+            score: 0.3,
+            matchedOn: "entity",
+          })
+        }
+      }
+    }
+
+    // 3. Expand context via graph traversal
+    if (expandContext && results.size > 0) {
+      const topIDs = [...results.entries()]
+        .sort((a, b) => b[1].score - a[1].score)
+        .slice(0, 3)
+        .map(([id]) => id)
+
+      const expanded = GraphTraverser.expandContext(
+        sessionID,
+        topIDs,
+        1,
+        5
+      )
+
+      for (const node of expanded) {
+        if (!results.has(node.id)) {
+          results.set(node.id, {
+            node,
+            score: 0.2,
+            matchedOn: "traversal",
+          })
+        }
+      }
+    }
+
+    // Sort by score and return
+    return [...results.values()]
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+  }
+
+  /**
+   * Search across all sessions.
+   */
+  export function searchAllSessions(
+    query: string,
+    options: {
+      limit?: number
+      expandContext?: boolean
+    } = {}
+  ): GraphSearchResult[] {
+    const { limit = 10 } = options
+    const allResults: GraphSearchResult[] = []
+
+    for (const sessionID of GraphStorage.getSessions()) {
+      const sessionResults = search(sessionID, query, {
+        ...options,
+        limit: Math.ceil(limit / 2),
+      })
+      allResults.push(...sessionResults)
+    }
+
+    // Sort by score and deduplicate
+    const seen = new Set<string>()
+    return allResults
+      .sort((a, b) => b.score - a.score)
+      .filter((r) => {
+        if (seen.has(r.node.id)) return false
+        seen.add(r.node.id)
+        return true
+      })
+      .slice(0, limit)
+  }
+
+  /**
+   * Extract potential entity names from a query.
+   */
+  function extractQueryEntities(query: string): string[] {
+    const entities: string[] = []
+
+    // Capitalized terms
+    const capitalizedPattern = /\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\b/g
+    let match: RegExpExecArray | null
+    while ((match = capitalizedPattern.exec(query)) !== null) {
+      entities.push(match[1])
+    }
+
+    // Code elements (PascalCase, snake_case)
+    const codePattern = /\b([A-Z][a-zA-Z0-9]*|[a-z_][a-z0-9_]+)\b/g
+    while ((match = codePattern.exec(query)) !== null) {
+      if (match[1].length > 3) {
+        entities.push(match[1])
+      }
+    }
+
+    return [...new Set(entities)]
+  }
+}

package/src/graph/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Graph types for RLM-Graph knowledge storage.
+ *
+ * Defines the node and edge types for the knowledge graph that stores
+ * archived conversation context.
+ */
+
+import { z } from "zod"
+
+/**
+ * Node types in the knowledge graph.
+ */
+export const NodeType = {
+  /** Top-level document representing an archived context block */
+  DOCUMENT: "document",
+  /** Section within a document (e.g., markdown header section) */
+  SECTION: "section",
+  /** Individual content chunk for retrieval */
+  CHUNK: "chunk",
+  /** Named entity (code element, file path, concept) */
+  ENTITY: "entity",
+} as const
+
+export type NodeType = (typeof NodeType)[keyof typeof NodeType]
+
+/**
+ * Relationship types between nodes.
+ */
+export const RelationType = {
+  /** Document contains section */
+  HAS_SECTION: "has_section",
+  /** Section/Document contains chunk */
+  HAS_CHUNK: "has_chunk",
+  /** Chunk mentions entity */
+  MENTIONS: "mentions",
+  /** Related concepts */
+  RELATED_TO: "related_to",
+  /** Temporal ordering (chunk follows chunk) */
+  FOLLOWS: "follows",
+  /** Parent-child relationship */
+  PARENT_OF: "parent_of",
+} as const
+
+export type RelationType = (typeof RelationType)[keyof typeof RelationType]
+
+/**
+ * Entity types for extracted entities.
+ */
+export const EntityType = {
+  /** Code element (class, function, variable) */
+  CODE_ELEMENT: "code_element",
+  /** File path */
+  FILE_PATH: "file_path",
+  /** Proper noun / named concept */
+  PROPER_NOUN: "proper_noun",
+  /** Reference (link, citation) */
+  REFERENCE: "reference",
+} as const
+
+export type EntityType = (typeof EntityType)[keyof typeof EntityType]
+
+/**
+ * Graph node schema.
+ */
+export const GraphNodeSchema = z.object({
+  /** Unique node identifier */
+  id: z.string(),
+  /** Session this node belongs to */
+  sessionID: z.string(),
+  /** Node type */
+  type: z.enum(["document", "section", "chunk", "entity"]),
+  /** Node content (text, entity name, etc.) */
+  content: z.string(),
+  /** Additional metadata */
+  metadata: z.record(z.any()).default({}),
+  /** Optional embedding vector */
+  embedding: z.array(z.number()).optional(),
+  /** Creation timestamp */
+  createdAt: z.number(),
+})
+
+export type GraphNode = z.infer<typeof GraphNodeSchema>
+
+/**
+ * Graph edge schema.
+ */
+export const GraphEdgeSchema = z.object({
+  /** Source node ID */
+  sourceID: z.string(),
+  /** Target node ID */
+  targetID: z.string(),
+  /** Relationship type */
+  relationship: z.enum([
+    "has_section",
+    "has_chunk",
+    "mentions",
+    "related_to",
+    "follows",
+    "parent_of",
+  ]),
+  /** Edge weight (0-1) */
+  weight: z.number().min(0).max(1).default(1.0),
+  /** Additional metadata */
+  metadata: z.record(z.any()).default({}),
+  /** Creation timestamp */
+  createdAt: z.number(),
+})
+
+export type GraphEdge = z.infer<typeof GraphEdgeSchema>
+
+/**
+ * Entity extracted from text.
+ */
+export interface Entity {
+  name: string
+  type: EntityType
+}
+
+/**
+ * Search result with relevance score.
+ */
+export interface GraphSearchResult {
+  node: GraphNode
+  score: number
+  matchedOn: "content" | "entity" | "traversal" | "embedding"
+}
+
+/**
+ * Edge adjacency list for storage.
+ */
+export interface EdgeAdjacencyList {
+  outgoing: GraphEdge[]
+  incoming: GraphEdge[]
+}
+
+/**
+ * Type index mapping node types to node IDs.
+ */
+export type TypeIndex = Record<string, string[]>
+
+/**
+ * Entity index mapping entity names to node IDs.
+ */
+export type EntityIndex = Record<string, string[]>