claudecode-rlm 1.0.0

package/src/search/patterns.ts

@@ -0,0 +1,139 @@
+/**
+ * Reference patterns for detecting context-related queries.
+ *
+ * These patterns trigger proactive context retrieval from the
+ * knowledge graph when detected in user messages.
+ */
+
+/**
+ * Explicit memory reference patterns.
+ * High confidence that user is referring to past context.
+ */
+export const EXPLICIT_MEMORY_PATTERNS: RegExp[] = [
+  // Direct memory references
+  /\bremember\s+(when|that|the|what|how)/i,
+  /\bdo\s+you\s+remember/i,
+  /\bcan\s+you\s+recall/i,
+  /\brecall\s+(when|that|the|what|how)/i,
+  /\byou\s+mentioned/i,
+  /\byou\s+said/i,
+  /\byou\s+told\s+me/i,
+  /\bwe\s+(discussed|talked\s+about)/i,
+
+  // Temporal references
+  /\bearlier\s+(you|we|I)/i,
+  /\bpreviously\s+(you|we|I)/i,
+  /\bbefore\s+(you|we|I)/i,
+  /\blast\s+time/i,
+  /\bthe\s+other\s+day/i,
+  /\ba\s+while\s+ago/i,
+  /\bsome\s+time\s+ago/i,
+
+  // Context continuation
+  /\bpick\s+up\s+where/i,
+  /\bcontinue\s+(from|where|with)/i,
+  /\bresume\s+(from|where)/i,
+  /\bback\s+to\s+(what|where)/i,
+  /\bgoing\s+back\s+to/i,
+]
+
+/**
+ * Extended patterns from PinkyClawd.
+ * Broader context references and conversational cues.
+ */
+export const EXTENDED_PATTERNS: RegExp[] = [
+  // Historical task references
+  /\bwhat\s+did\s+we\s+(do|try|use|build|create|implement|fix)/i,
+  /\bwhat\s+have\s+we\s+(done|tried|built|created|implemented|fixed)/i,
+  /\bwhere\s+were\s+we/i,
+  /\bwhere\s+did\s+we\s+(leave\s+off|stop)/i,
+  /\bhow\s+did\s+we\s+(do|handle|implement|fix|solve)/i,
+  /\bwhy\s+did\s+we\s+(decide|choose|use)/i,
+
+  // Continuation cues
+  /\blet's\s+(continue|resume|pick\s+up)/i,
+  /\blet's\s+go\s+back\s+to/i,
+  /\bcan\s+we\s+(continue|resume)/i,
+  /\bshall\s+we\s+(continue|resume)/i,
+
+  // Decision references
+  /\bthe\s+approach\s+we\s+(chose|decided|used)/i,
+  /\bthe\s+solution\s+we/i,
+  /\bthe\s+method\s+we/i,
+  /\bthe\s+way\s+we/i,
+  /\bour\s+(approach|solution|implementation)/i,
+
+  // Error/fix references
+  /\bthat\s+error\s+(we|you)/i,
+  /\bthe\s+bug\s+(we|you)/i,
+  /\bthe\s+issue\s+(we|you)/i,
+  /\bthe\s+problem\s+(we|you)/i,
+  /\bwhen\s+(it|that)\s+(broke|failed|crashed)/i,
+
+  // Feature references
+  /\bthe\s+feature\s+(we|you)/i,
+  /\bthat\s+functionality/i,
+  /\bthe\s+component\s+(we|you)/i,
+  /\bthe\s+module\s+(we|you)/i,
+
+  // Code references
+  /\bthat\s+function\s+(we|you)/i,
+  /\bthe\s+class\s+(we|you)/i,
+  /\bthat\s+file\s+(we|you)/i,
+  /\bthe\s+code\s+(we|you)/i,
+
+  // Discussion references
+  /\bas\s+we\s+(discussed|mentioned|said)/i,
+  /\blike\s+(we|you)\s+said/i,
+  /\baccording\s+to\s+(our|what\s+we)/i,
+  /\bbased\s+on\s+(our|what\s+we)/i,
+
+  // Session references
+  /\bin\s+our\s+(last|previous)\s+(session|conversation|chat)/i,
+  /\bearlier\s+in\s+this\s+(session|conversation)/i,
+  /\bfrom\s+our\s+(last|previous)/i,
+]
+
+/**
+ * Task completion patterns.
+ * Indicates a task may have been completed.
+ */
+export const TASK_COMPLETION_PATTERNS: RegExp[] = [
+  /\b(done|finished|completed|fixed|resolved|implemented|working\s+now)/i,
+  /\bthat\s+(should|seems\s+to)\s+(work|fix|solve)/i,
+  /\blet\s+me\s+know\s+if/i,
+  /\btry\s+(it|that)\s+(now|again)/i,
+  /\bshould\s+be\s+(good|fixed|working)/i,
+  /\bI've\s+(finished|completed|done|fixed)/i,
+  /\bthat's\s+(it|all|done)/i,
+  /\ball\s+(done|set|good)/i,
+]
+
+/**
+ * All patterns combined.
+ */
+export const ALL_PATTERNS: RegExp[] = [
+  ...EXPLICIT_MEMORY_PATTERNS,
+  ...EXTENDED_PATTERNS,
+]
+
+/**
+ * Check if a message contains reference patterns.
+ */
+export function detectsReference(message: string): boolean {
+  return ALL_PATTERNS.some((pattern) => pattern.test(message))
+}
+
+/**
+ * Get all matching patterns in a message.
+ */
+export function getMatchingPatterns(message: string): RegExp[] {
+  return ALL_PATTERNS.filter((pattern) => pattern.test(message))
+}
+
+/**
+ * Check if a message indicates task completion.
+ */
+export function detectsTaskCompletion(message: string): boolean {
+  return TASK_COMPLETION_PATTERNS.some((pattern) => pattern.test(message))
+}

package/src/tools/graph-query.ts

@@ -0,0 +1,257 @@
+/**
+ * Graph query tool for searching the knowledge graph.
+ *
+ * Allows the LLM to query the graph structure for:
+ * - Entity relationships
+ * - Chunk context expansion
+ * - Path finding between concepts
+ */
+
+import { z } from "zod"
+import type { ToolDefinition, ToolResult } from "../plugin-types.js"
+import {
+  GraphStorage,
+  GraphSearcher,
+  GraphTraverser,
+  NodeType,
+  type GraphNode,
+} from "../graph/index.js"
+
+/**
+ * Format a node for display.
+ */
+function formatNode(node: GraphNode, index: number): string {
+  const lines = [`[${index + 1}] ${node.type.toUpperCase()}: ${node.id}`]
+  lines.push(`    Content: ${node.content.slice(0, 200)}${node.content.length > 200 ? "..." : ""}`)
+  if (node.metadata && Object.keys(node.metadata).length > 0) {
+    lines.push(`    Metadata: ${JSON.stringify(node.metadata)}`)
+  }
+  return lines.join("\n")
+}
+
+/**
+ * Graph query tool definition.
+ */
+export const graphQueryTool: ToolDefinition = {
+  description: `Query the PinkyClawd knowledge graph to find related context and entities.
+
+Operations:
+- search: Find chunks matching a query (uses hybrid keyword + entity matching)
+- entity: Find all chunks mentioning a specific entity (code element, file, concept)
+- expand: Get related context around a specific node
+- path: Find connection path between two entities
+
+Use this tool when you need to:
+- Find where something was discussed or defined
+- Understand relationships between concepts
+- Get historical context about a topic
+- Navigate the conversation history structurally`,
+
+  args: {
+    operation: z
+      .enum(["search", "entity", "expand", "path"])
+      .describe("The operation to perform"),
+    query: z
+      .string()
+      .optional()
+      .describe("Search query or entity name (for search/entity operations)"),
+    nodeId: z
+      .string()
+      .optional()
+      .describe("Node ID to expand from (for expand operation)"),
+    startEntity: z
+      .string()
+      .optional()
+      .describe("Starting entity name (for path operation)"),
+    endEntity: z
+      .string()
+      .optional()
+      .describe("Ending entity name (for path operation)"),
+    limit: z
+      .number()
+      .optional()
+      .default(10)
+      .describe("Maximum results to return"),
+  },
+
+  execute: async (args, context): Promise<ToolResult> => {
+    const { operation, query, nodeId, startEntity, endEntity, limit = 10 } = args
+    const sessionID = context.sessionID
+
+    try {
+      switch (operation) {
+        case "search": {
+          if (!query) {
+            return {
+              title: "Graph Query - Search",
+              output: "Error: 'query' parameter is required for search operation",
+            }
+          }
+
+          const results = GraphSearcher.search(sessionID, query, {
+            limit,
+            expandContext: true,
+          })
+
+          if (results.length === 0) {
+            return {
+              title: "Graph Query - Search",
+              output: `No results found for query: "${query}"`,
+            }
+          }
+
+          const output = [
+            `Found ${results.length} results for "${query}":`,
+            "",
+            ...results.map((r, i) => formatNode(r.node, i)),
+          ].join("\n")
+
+          return {
+            title: "Graph Query - Search",
+            output,
+            metadata: { resultCount: results.length },
+          }
+        }
+
+        case "entity": {
+          if (!query) {
+            return {
+              title: "Graph Query - Entity",
+              output: "Error: 'query' parameter is required for entity operation",
+            }
+          }
+
+          const chunks = GraphTraverser.getEntityContext(sessionID, query, limit)
+
+          if (chunks.length === 0) {
+            return {
+              title: "Graph Query - Entity",
+              output: `No chunks found mentioning entity: "${query}"`,
+            }
+          }
+
+          const output = [
+            `Found ${chunks.length} chunks mentioning "${query}":`,
+            "",
+            ...chunks.map((node, i) => formatNode(node, i)),
+          ].join("\n")
+
+          return {
+            title: "Graph Query - Entity",
+            output,
+            metadata: { resultCount: chunks.length },
+          }
+        }
+
+        case "expand": {
+          if (!nodeId) {
+            return {
+              title: "Graph Query - Expand",
+              output: "Error: 'nodeId' parameter is required for expand operation",
+            }
+          }
+
+          const expanded = GraphTraverser.expandContext(
+            sessionID,
+            [nodeId],
+            2,
+            limit
+          )
+
+          if (expanded.length === 0) {
+            return {
+              title: "Graph Query - Expand",
+              output: `No context found around node: "${nodeId}"`,
+            }
+          }
+
+          const output = [
+            `Expanded context around "${nodeId}" (${expanded.length} nodes):`,
+            "",
+            ...expanded.map((node, i) => formatNode(node, i)),
+          ].join("\n")
+
+          return {
+            title: "Graph Query - Expand",
+            output,
+            metadata: { resultCount: expanded.length },
+          }
+        }
+
+        case "path": {
+          if (!startEntity || !endEntity) {
+            return {
+              title: "Graph Query - Path",
+              output: "Error: 'startEntity' and 'endEntity' parameters are required for path operation",
+            }
+          }
+
+          // Find entity nodes
+          const startNodes = GraphStorage.searchNodes(
+            sessionID,
+            startEntity,
+            NodeType.ENTITY,
+            1
+          )
+          const endNodes = GraphStorage.searchNodes(
+            sessionID,
+            endEntity,
+            NodeType.ENTITY,
+            1
+          )
+
+          if (startNodes.length === 0) {
+            return {
+              title: "Graph Query - Path",
+              output: `Start entity not found: "${startEntity}"`,
+            }
+          }
+
+          if (endNodes.length === 0) {
+            return {
+              title: "Graph Query - Path",
+              output: `End entity not found: "${endEntity}"`,
+            }
+          }
+
+          const path = GraphTraverser.findPath(
+            sessionID,
+            startNodes[0].id,
+            endNodes[0].id,
+            5
+          )
+
+          if (!path) {
+            return {
+              title: "Graph Query - Path",
+              output: `No path found between "${startEntity}" and "${endEntity}"`,
+            }
+          }
+
+          const output = [
+            `Path from "${startEntity}" to "${endEntity}" (${path.length} nodes):`,
+            "",
+            ...path.map((node, i) => formatNode(node, i)),
+          ].join("\n")
+
+          return {
+            title: "Graph Query - Path",
+            output,
+            metadata: { pathLength: path.length },
+          }
+        }
+
+        default:
+          return {
+            title: "Graph Query",
+            output: `Unknown operation: ${operation}`,
+          }
+      }
+    } catch (error) {
+      return {
+        title: "Graph Query - Error",
+        output: `Error executing graph query: ${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  },
+}

package/src/tools/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Tools module exports.
+ *
+ * Custom tools for graph query and memory search.
+ */
+
+export { graphQueryTool } from "./graph-query.js"
+export { memoryEnhancedTool, listEntitiesTool, graphStatsTool } from "./memory.js"

package/src/tools/memory.ts

@@ -0,0 +1,208 @@
+/**
+ * Memory-enhanced tools for context retrieval.
+ *
+ * Provides tools for searching archived context with
+ * enhanced scoring and entity awareness.
+ */
+
+import { z } from "zod"
+import type { ToolDefinition, ToolResult } from "../plugin-types.js"
+import { GraphStorage, GraphSearcher, NodeType, type GraphNode } from "../graph/index.js"
+import { EnhancedSearch } from "../search/index.js"
+
+/**
+ * Format a node for display.
+ */
+function formatNode(node: GraphNode, index: number): string {
+  const lines = [`[${index + 1}] ${node.type.toUpperCase()}`]
+  lines.push(`    ${node.content.slice(0, 300)}${node.content.length > 300 ? "..." : ""}`)
+  return lines.join("\n")
+}
+
+/**
+ * Memory enhanced search tool.
+ */
+export const memoryEnhancedTool: ToolDefinition = {
+  description: `Search archived conversation context with enhanced scoring.
+
+Features:
+- Keyword matching with recency weighting
+- Entity-aware boosting
+- Graph traversal for related context
+
+Use this tool when you need to:
+- Find past discussions about a topic
+- Recall specific decisions or implementations
+- Get context about entities (classes, files, concepts)`,
+
+  args: {
+    query: z.string().describe("Search query"),
+    limit: z.number().optional().default(5).describe("Maximum results"),
+    recencyWeight: z
+      .number()
+      .optional()
+      .default(0.3)
+      .describe("Weight for recency (0-1)"),
+  },
+
+  execute: async (args, context): Promise<ToolResult> => {
+    const { query, limit = 5, recencyWeight = 0.3 } = args
+    const sessionID = context.sessionID
+
+    try {
+      const results = EnhancedSearch.search(sessionID, query, {
+        limit,
+        recencyWeight,
+      })
+
+      if (results.length === 0) {
+        return {
+          title: "Memory Search",
+          output: `No archived context found for: "${query}"`,
+        }
+      }
+
+      const output = [
+        `Found ${results.length} relevant context blocks for "${query}":`,
+        "",
+        ...results.map((r, i) => {
+          const node = r.node
+          return [
+            `[${i + 1}] Score: ${r.finalScore.toFixed(2)} (recency: ${r.recencyScore.toFixed(2)})`,
+            `    ${node.content.slice(0, 300)}${node.content.length > 300 ? "..." : ""}`,
+          ].join("\n")
+        }),
+      ].join("\n")
+
+      return {
+        title: "Memory Search",
+        output,
+        metadata: { resultCount: results.length },
+      }
+    } catch (error) {
+      return {
+        title: "Memory Search - Error",
+        output: `Error searching memory: ${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  },
+}
+
+/**
+ * List entities tool.
+ */
+export const listEntitiesTool: ToolDefinition = {
+  description: `List entities (code elements, files, concepts) tracked in the knowledge graph.
+
+Use this to discover what entities have been discussed and can be queried.`,
+
+  args: {
+    filter: z.string().optional().describe("Filter entities by name"),
+    limit: z.number().optional().default(20).describe("Maximum entities"),
+  },
+
+  execute: async (args, context): Promise<ToolResult> => {
+    const { filter, limit = 20 } = args
+    const sessionID = context.sessionID
+
+    try {
+      let entities: GraphNode[]
+
+      if (filter) {
+        entities = GraphStorage.searchNodes(
+          sessionID,
+          filter,
+          NodeType.ENTITY,
+          limit
+        )
+      } else {
+        entities = GraphStorage.getNodesByType(sessionID, NodeType.ENTITY, limit)
+      }
+
+      if (entities.length === 0) {
+        return {
+          title: "List Entities",
+          output: filter
+            ? `No entities found matching: "${filter}"`
+            : "No entities tracked in the knowledge graph yet.",
+        }
+      }
+
+      // Group by entity type
+      const byType = new Map<string, GraphNode[]>()
+      for (const entity of entities) {
+        const type = (entity.metadata?.entityType as string) || "unknown"
+        if (!byType.has(type)) byType.set(type, [])
+        byType.get(type)!.push(entity)
+      }
+
+      const sections: string[] = [`Found ${entities.length} entities:`]
+
+      for (const [type, typeEntities] of byType) {
+        sections.push("")
+        sections.push(`${type.toUpperCase()}:`)
+        for (const entity of typeEntities) {
+          sections.push(`  - ${entity.content}`)
+        }
+      }
+
+      return {
+        title: "List Entities",
+        output: sections.join("\n"),
+        metadata: { entityCount: entities.length },
+      }
+    } catch (error) {
+      return {
+        title: "List Entities - Error",
+        output: `Error listing entities: ${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  },
+}
+
+/**
+ * Graph stats tool.
+ */
+export const graphStatsTool: ToolDefinition = {
+  description: `Get statistics about the knowledge graph.
+
+Shows counts of nodes, edges, and cache performance.`,
+
+  args: {},
+
+  execute: async (args, context): Promise<ToolResult> => {
+    const sessionID = context.sessionID
+
+    try {
+      const stats = GraphStorage.getStats(sessionID)
+
+      const output = [
+        "Knowledge Graph Statistics:",
+        "",
+        `Total nodes: ${stats.nodeCount}`,
+        `Total edges: ${stats.edgeCount}`,
+        "",
+        "Nodes by type:",
+        ...Object.entries(stats.nodesByType).map(
+          ([type, count]) => `  - ${type}: ${count}`
+        ),
+        "",
+        "Cache performance:",
+        `  - Hits: ${stats.cacheStats.hits}`,
+        `  - Misses: ${stats.cacheStats.misses}`,
+        `  - Hit rate: ${stats.cacheStats.hitRate}`,
+      ].join("\n")
+
+      return {
+        title: "Graph Stats",
+        output,
+        metadata: stats,
+      }
+    } catch (error) {
+      return {
+        title: "Graph Stats - Error",
+        output: `Error getting stats: ${error instanceof Error ? error.message : String(error)}`,
+      }
+    }
+  },
+}