claudecode-rlm 1.0.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "claudecode-rlm",
+  "version": "1.0.0",
+  "description": "Advanced RLM (Recursive Language Model) plugin for Claude Code - Knowledge graph-based context storage with 74x faster reads",
+  "type": "module",
+  "license": "MIT",
+  "author": "Michael Thornton <tekcin@yahoo.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tekcin/claudecode-rlm"
+  },
+  "homepage": "https://github.com/tekcin/claudecode-rlm#readme",
+  "bugs": {
+    "url": "https://github.com/tekcin/claudecode-rlm/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claudecode",
+    "plugin",
+    "rlm",
+    "context",
+    "knowledge-graph",
+    "ai",
+    "llm",
+    "anthropic"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "node test/benchmark.cjs",
+    "test:optimized": "node test/benchmark-optimized.cjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-code": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-code": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,111 @@
+/**
+ * Plugin configuration schema.
+ *
+ * Configuration is loaded from .claude/claudecode.jsonc under the
+ * "claudecode-rlm" key.
+ */
+
+import { z } from "zod"
+
+/**
+ * Graph configuration schema.
+ */
+export const GraphConfigSchema = z.object({
+  /** Whether graph features are enabled */
+  enabled: z.boolean().default(true),
+  /** Whether to automatically ingest archived context into graph */
+  auto_ingest: z.boolean().default(true),
+  /** Maximum nodes to traverse in a search */
+  max_traversal_nodes: z.number().default(50),
+  /** Maximum depth for graph traversal */
+  max_traversal_depth: z.number().default(3),
+})
+
+/**
+ * Enhanced search configuration schema.
+ */
+export const EnhancedSearchConfigSchema = z.object({
+  /** Use additional reference patterns from PinkyClawd */
+  additional_patterns: z.boolean().default(true),
+  /** Weight for recency in scoring (0-1) */
+  recency_weight: z.number().min(0).max(1).default(0.3),
+  /** Weight for entity matches in scoring (0-1) */
+  entity_boost: z.number().min(0).max(1).default(0.2),
+  /** Maximum age in days for recency scoring */
+  max_age_days: z.number().default(30),
+  /** Minimum score threshold for results */
+  min_score_threshold: z.number().default(0.3),
+})
+
+/**
+ * Task detection configuration schema.
+ */
+export const TaskDetectionConfigSchema = z.object({
+  /** Archive context when task completion is detected */
+  auto_archive_on_completion: z.boolean().default(true),
+})
+
+/**
+ * Full plugin configuration schema.
+ */
+export const PluginConfigSchema = z.object({
+  /** Graph-based context storage */
+  graph: GraphConfigSchema.default({}),
+  /** Enhanced search settings */
+  enhanced_search: EnhancedSearchConfigSchema.default({}),
+  /** Task detection settings */
+  task_detection: TaskDetectionConfigSchema.default({}),
+})
+
+export type PluginConfig = z.infer<typeof PluginConfigSchema>
+
+/**
+ * Default configuration.
+ */
+export const DEFAULT_CONFIG: PluginConfig = {
+  graph: {
+    enabled: true,
+    auto_ingest: true,
+    max_traversal_nodes: 50,
+    max_traversal_depth: 3,
+  },
+  enhanced_search: {
+    additional_patterns: true,
+    recency_weight: 0.3,
+    entity_boost: 0.2,
+    max_age_days: 30,
+    min_score_threshold: 0.3,
+  },
+  task_detection: {
+    auto_archive_on_completion: true,
+  },
+}
+
+/**
+ * Parse and validate configuration.
+ */
+export function parseConfig(config: unknown): PluginConfig {
+  try {
+    return PluginConfigSchema.parse(config ?? {})
+  } catch {
+    // Return defaults on parse error
+    return DEFAULT_CONFIG
+  }
+}
+
+/**
+ * Merge partial config with defaults.
+ */
+export function mergeConfig(partial: Partial<PluginConfig>): PluginConfig {
+  return {
+    graph: { ...DEFAULT_CONFIG.graph, ...partial.graph },
+    enhanced_search: {
+      ...DEFAULT_CONFIG.enhanced_search,
+      ...partial.enhanced_search,
+    },
+    task_detection: {
+      ...DEFAULT_CONFIG.task_detection,
+      ...partial.task_detection,
+    },
+  }
+}

package/src/graph/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Graph module exports.
+ *
+ * RLM-Graph: Knowledge graph-based context storage and retrieval.
+ */
+
+export * from "./types.js"
+export { GraphStorage } from "./storage.js"
+export { EntityExtractor, ContentChunker, GraphIngester } from "./ingestion.js"
+export { GraphTraverser, GraphSearcher } from "./traversal.js"

package/src/graph/ingestion.ts

@@ -0,0 +1,528 @@
+/**
+ * Graph ingestion: Entity extraction and content chunking.
+ *
+ * Provides utilities for processing text content:
+ * - EntityExtractor: Identifies named entities and code elements
+ * - ContentChunker: Splits content into hierarchical chunks
+ * - GraphIngester: Converts content into graph structure
+ */
+
+import * as crypto from "crypto"
+import {
+  type GraphNode,
+  type GraphEdge,
+  type Entity,
+  NodeType,
+  RelationType,
+  EntityType,
+} from "./types.js"
+import { GraphStorage } from "./storage.js"
+
+/**
+ * Stopwords to filter from keyword extraction.
+ */
+const STOPWORDS = new Set([
+  // Basic articles and prepositions
+  "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "must", "shall", "can", "need", "dare",
+  "ought", "used", "to", "of", "in", "for", "on", "with", "at", "by",
+  "from", "as", "into", "through", "during", "before", "after", "above",
+  "below", "between", "under", "again", "further", "then", "once", "here",
+  "there", "when", "where", "why", "how", "all", "each", "few", "more",
+  "most", "other", "some", "such", "no", "nor", "not", "only", "own",
+  "same", "so", "than", "too", "very", "just", "and", "but", "if", "or",
+  "because", "until", "while", "about", "against",
+  // Pronouns
+  "i", "me", "my", "myself", "we", "our", "ours", "ourselves",
+  "you", "your", "yours", "yourself", "yourselves",
+  "he", "him", "his", "himself", "she", "her", "hers", "herself",
+  "it", "its", "itself", "they", "them", "their", "theirs", "themselves",
+  "what", "which", "who", "whom", "this", "that", "these", "those",
+  // Common verbs
+  "am", "having", "doing", "going", "coming", "getting", "making",
+  "taking", "using", "trying", "saying", "seeing", "wanting", "needing",
+  "knowing", "thinking", "looking", "giving", "finding", "telling",
+  "asking", "working", "seeming", "feeling", "leaving", "calling",
+  // Fillers
+  "please", "thanks", "okay", "ok", "yes", "yeah", "no", "nope",
+  "right", "sure", "great", "good", "nice", "cool", "fine", "alright",
+  "hello", "hi", "hey", "bye", "goodbye",
+  // RLM-specific
+  "remember", "recall", "earlier", "previously", "discussed", "mentioned",
+  "said", "decided", "talked", "worked", "think", "know", "like",
+])
+
+/**
+ * Extracts entities from text content.
+ */
+export namespace EntityExtractor {
+  // Code-related regex patterns
+  const CODE_PATTERNS = [
+    // Classes ending with Error, Exception, Handler, etc.
+    /\b([A-Z][a-zA-Z0-9]*(?:Error|Exception|Handler|Manager|Service|Controller|Factory|Builder))\b/g,
+    // Function calls: functionName(
+    /\b([a-z_][a-z0-9_]*)\s*\(/g,
+    // Constants: MAX_TIMEOUT, DEBUG_MODE
+    /\b([A-Z_][A-Z0-9_]{2,})\b/g,
+    // Inline code: `variable`
+    /`([^`]+)`/g,
+    // Type definitions: class User, interface Config
+    /(?:class|interface|type|struct)\s+([A-Z][a-zA-Z0-9]*)/g,
+  ]
+
+  /**
+   * Extract entities from text.
+   */
+  export function extract(text: string): Entity[] {
+    const entities = new Map<string, EntityType>()
+
+    // Extract capitalized terms (potential proper nouns)
+    const capitalizedPattern = /\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\b/g
+    let match: RegExpExecArray | null
+    while ((match = capitalizedPattern.exec(text)) !== null) {
+      const term = match[1]
+      if (!STOPWORDS.has(term.toLowerCase()) && term.length > 2) {
+        entities.set(term, EntityType.PROPER_NOUN)
+      }
+    }
+
+    // Extract code elements
+    for (const pattern of CODE_PATTERNS) {
+      pattern.lastIndex = 0
+      while ((match = pattern.exec(text)) !== null) {
+        const term = match[1]
+        if (term && !STOPWORDS.has(term.toLowerCase()) && term.length > 1) {
+          entities.set(term, EntityType.CODE_ELEMENT)
+        }
+      }
+    }
+
+    // Extract markdown links
+    const linkPattern = /\[([^\]]+)\]\([^)]+\)/g
+    while ((match = linkPattern.exec(text)) !== null) {
+      const linkText = match[1]
+      if (!STOPWORDS.has(linkText.toLowerCase())) {
+        entities.set(linkText, EntityType.REFERENCE)
+      }
+    }
+
+    // Extract file paths
+    const pathPattern = /(?:^|\s)([./]?(?:[a-zA-Z0-9_-]+\/)+[a-zA-Z0-9_.-]+)/g
+    while ((match = pathPattern.exec(text)) !== null) {
+      entities.set(match[1], EntityType.FILE_PATH)
+    }
+
+    return Array.from(entities.entries()).map(([name, type]) => ({
+      name,
+      type,
+    }))
+  }
+
+  /**
+   * Extract top keywords based on frequency.
+   */
+  export function extractKeywords(text: string, topN: number = 10): string[] {
+    const wordPattern = /\b[a-zA-Z]{3,}\b/g
+    const wordCounts = new Map<string, number>()
+
+    let match: RegExpExecArray | null
+    while ((match = wordPattern.exec(text)) !== null) {
+      const word = match[0].toLowerCase()
+      if (!STOPWORDS.has(word)) {
+        wordCounts.set(word, (wordCounts.get(word) || 0) + 1)
+      }
+    }
+
+    return Array.from(wordCounts.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, topN)
+      .map(([word]) => word)
+  }
+}
+
+/**
+ * Splits content into hierarchical chunks.
+ */
+export namespace ContentChunker {
+  const DEFAULT_SECTION_MIN_CHARS = 500
+  const DEFAULT_CHUNK_TARGET_CHARS = 300
+  const DEFAULT_CHUNK_OVERLAP = 50
+
+  /**
+   * Split content into sections.
+   */
+  export function splitIntoSections(
+    content: string,
+    minChars: number = DEFAULT_SECTION_MIN_CHARS
+  ): Array<{ title: string; content: string }> {
+    const sections: Array<{ title: string; content: string }> = []
+
+    // Try to split by markdown headers
+    const headerPattern = /(?:^|\n)(#{1,3})\s+(.+?)(?:\n|$)/g
+    const matches: Array<{ level: number; title: string; index: number; end: number }> = []
+
+    let match: RegExpExecArray | null
+    while ((match = headerPattern.exec(content)) !== null) {
+      matches.push({
+        level: match[1].length,
+        title: match[2].trim(),
+        index: match.index,
+        end: headerPattern.lastIndex,
+      })
+    }
+
+    if (matches.length > 0) {
+      for (let i = 0; i < matches.length; i++) {
+        const start = matches[i].end
+        const end = i + 1 < matches.length ? matches[i + 1].index : content.length
+        const sectionContent = content.slice(start, end).trim()
+
+        if (sectionContent) {
+          sections.push({
+            title: matches[i].title,
+            content: sectionContent,
+          })
+        }
+      }
+    } else {
+      // Fall back to paragraph-based splitting
+      const paragraphs = content.split("\n\n")
+      let currentSection: string[] = []
+      let currentLength = 0
+
+      for (const para of paragraphs) {
+        currentSection.push(para)
+        currentLength += para.length
+
+        if (currentLength >= minChars) {
+          const sectionText = currentSection.join("\n\n")
+          const firstLine = sectionText.split("\n")[0].slice(0, 50)
+          sections.push({
+            title: firstLine,
+            content: sectionText,
+          })
+          currentSection = []
+          currentLength = 0
+        }
+      }
+
+      if (currentSection.length > 0) {
+        const sectionText = currentSection.join("\n\n")
+        const firstLine = sectionText.split("\n")[0].slice(0, 50)
+        sections.push({
+          title: firstLine,
+          content: sectionText,
+        })
+      }
+    }
+
+    return sections
+  }
+
+  /**
+   * Split content into overlapping chunks.
+   */
+  export function splitIntoChunks(
+    content: string,
+    targetChars: number = DEFAULT_CHUNK_TARGET_CHARS,
+    overlap: number = DEFAULT_CHUNK_OVERLAP
+  ): string[] {
+    if (content.length <= targetChars) {
+      return [content]
+    }
+
+    const chunks: string[] = []
+    const sentences = content.split(/(?<=[.!?])\s+/)
+    let currentChunk: string[] = []
+    let currentLength = 0
+
+    for (const sentence of sentences) {
+      const sentenceLen = sentence.length
+
+      if (currentLength + sentenceLen > targetChars && currentChunk.length > 0) {
+        chunks.push(currentChunk.join(" "))
+
+        // Keep overlap
+        const overlapChunk: string[] = []
+        let overlapLen = 0
+        for (let i = currentChunk.length - 1; i >= 0; i--) {
+          if (overlapLen + currentChunk[i].length <= overlap) {
+            overlapChunk.unshift(currentChunk[i])
+            overlapLen += currentChunk[i].length
+          } else {
+            break
+          }
+        }
+
+        currentChunk = overlapChunk
+        currentLength = overlapLen
+      }
+
+      currentChunk.push(sentence)
+      currentLength += sentenceLen
+    }
+
+    if (currentChunk.length > 0) {
+      chunks.push(currentChunk.join(" "))
+    }
+
+    return chunks
+  }
+}
+
+/**
+ * Ingests content into the knowledge graph.
+ */
+export namespace GraphIngester {
+  /**
+   * Generate a unique node ID.
+   */
+  function generateNodeID(nodeType: string, content: string): string {
+    const uuid = crypto.randomUUID().slice(0, 8)
+    const contentHash = crypto
+      .createHash("md5")
+      .update(content)
+      .digest("hex")
+      .slice(0, 8)
+    return `${nodeType}_${uuid}_${contentHash}`
+  }
+
+  /**
+   * Context block interface (compatible with Claude Code RLM types).
+   */
+  export interface ContextBlock {
+    id: string
+    sessionID: string
+    content: string
+    tokens: number
+    summary?: string
+    taskID?: string
+    taskDescription?: string
+    createdAt: number
+  }
+
+  /**
+   * Ingest a context block into the graph.
+   */
+  export function ingestContextBlock(block: ContextBlock): GraphNode {
+    const now = Date.now()
+
+    // Create document node
+    const docNode: GraphNode = {
+      id: generateNodeID("doc", block.id),
+      sessionID: block.sessionID,
+      type: NodeType.DOCUMENT,
+      content: block.summary || block.content.slice(0, 200),
+      metadata: {
+        blockID: block.id,
+        taskID: block.taskID,
+        taskDescription: block.taskDescription,
+        tokens: block.tokens,
+      },
+      createdAt: now,
+    }
+
+    GraphStorage.addNode(docNode)
+
+    // Split into sections
+    const sections = ContentChunker.splitIntoSections(block.content)
+
+    for (const section of sections) {
+      const sectionNode = ingestSection(
+        docNode.id,
+        block.sessionID,
+        section.title,
+        section.content,
+        now
+      )
+
+      // Link document -> section
+      const edge: GraphEdge = {
+        sourceID: docNode.id,
+        targetID: sectionNode.id,
+        relationship: RelationType.HAS_SECTION,
+        weight: 1.0,
+        metadata: {},
+        createdAt: now,
+      }
+      GraphStorage.addEdgeWithSession(block.sessionID, edge)
+    }
+
+    return docNode
+  }
+
+  /**
+   * Ingest a section and its chunks.
+   */
+  function ingestSection(
+    parentID: string,
+    sessionID: string,
+    title: string,
+    content: string,
+    timestamp: number
+  ): GraphNode {
+    const sectionNode: GraphNode = {
+      id: generateNodeID("sec", content),
+      sessionID,
+      type: NodeType.SECTION,
+      content: title,
+      metadata: { fullContent: content.slice(0, 500) },
+      createdAt: timestamp,
+    }
+
+    GraphStorage.addNode(sectionNode)
+
+    // Split into chunks
+    const chunks = ContentChunker.splitIntoChunks(content)
+    let prevChunkID: string | null = null
+
+    for (const chunkContent of chunks) {
+      const chunkNode = ingestChunk(sessionID, chunkContent, timestamp)
+
+      // Link section -> chunk
+      const edge: GraphEdge = {
+        sourceID: sectionNode.id,
+        targetID: chunkNode.id,
+        relationship: RelationType.HAS_CHUNK,
+        weight: 1.0,
+        metadata: {},
+        createdAt: timestamp,
+      }
+      GraphStorage.addEdgeWithSession(sessionID, edge)
+
+      // Link previous chunk -> current chunk (temporal order)
+      if (prevChunkID) {
+        const followsEdge: GraphEdge = {
+          sourceID: prevChunkID,
+          targetID: chunkNode.id,
+          relationship: RelationType.FOLLOWS,
+          weight: 1.0,
+          metadata: {},
+          createdAt: timestamp,
+        }
+        GraphStorage.addEdgeWithSession(sessionID, followsEdge)
+      }
+
+      prevChunkID = chunkNode.id
+    }
+
+    return sectionNode
+  }
+
+  /**
+   * Ingest a chunk and extract entities.
+   */
+  function ingestChunk(
+    sessionID: string,
+    content: string,
+    timestamp: number
+  ): GraphNode {
+    const chunkNode: GraphNode = {
+      id: generateNodeID("chunk", content),
+      sessionID,
+      type: NodeType.CHUNK,
+      content,
+      metadata: {},
+      createdAt: timestamp,
+    }
+
+    GraphStorage.addNode(chunkNode)
+
+    // Extract and link entities
+    const entities = EntityExtractor.extract(content)
+    const entityCache = new Map<string, string>()
+
+    for (const entity of entities) {
+      let entityID: string
+
+      if (entityCache.has(entity.name)) {
+        entityID = entityCache.get(entity.name)!
+      } else {
+        entityID = getOrCreateEntity(sessionID, entity.name, entity.type, timestamp)
+        entityCache.set(entity.name, entityID)
+      }
+
+      // Link chunk -> entity
+      const edge: GraphEdge = {
+        sourceID: chunkNode.id,
+        targetID: entityID,
+        relationship: RelationType.MENTIONS,
+        weight: 1.0,
+        metadata: {},
+        createdAt: timestamp,
+      }
+      GraphStorage.addEdgeWithSession(sessionID, edge)
+    }
+
+    return chunkNode
+  }
+
+  /**
+   * Get existing entity or create new one.
+   */
+  function getOrCreateEntity(
+    sessionID: string,
+    name: string,
+    entityType: EntityType,
+    timestamp: number
+  ): string {
+    // Search for existing entity with same name
+    const existing = GraphStorage.searchNodes(
+      sessionID,
+      name,
+      NodeType.ENTITY,
+      1
+    )
+
+    if (existing.length > 0 && existing[0].content === name) {
+      return existing[0].id
+    }
+
+    // Create new entity
+    const entityNode: GraphNode = {
+      id: generateNodeID("ent", name),
+      sessionID,
+      type: NodeType.ENTITY,
+      content: name,
+      metadata: { entityType },
+      createdAt: timestamp,
+    }
+
+    GraphStorage.addNode(entityNode)
+    return entityNode.id
+  }
+
+  /**
+   * Ingest messages into the graph.
+   */
+  export function ingestMessages(
+    sessionID: string,
+    messages: Array<{
+      role: string
+      content: string
+    }>
+  ): GraphNode | null {
+    if (messages.length === 0) {
+      return null
+    }
+
+    // Build content from messages
+    const contentParts = messages.map(
+      (msg) => `${msg.role.toUpperCase()}: ${msg.content}`
+    )
+    const content = contentParts.join("\n\n")
+
+    // Create a temporary context block
+    const block: ContextBlock = {
+      id: `msg_${crypto.randomUUID().slice(0, 12)}`,
+      sessionID,
+      content,
+      summary: content.slice(0, 200),
+      tokens: Math.ceil(content.length / 4),
+      createdAt: Date.now(),
+    }
+
+    return ingestContextBlock(block)
+  }
+}