claude-memory-layer 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-layer",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Claude Code plugin that learns from conversations to provide personalized assistance",
   "main": "dist/index.js",
   "bin": {

package/src/core/index.ts

@@ -30,3 +30,9 @@ export * from './graduation.js';
 
 // Task Entity System
 export * from './task/index.js';
+
+// Shared Store (Cross-Project Knowledge)
+export * from './shared-event-store.js';
+export * from './shared-store.js';
+export * from './shared-vector-store.js';
+export * from './shared-promoter.js';

package/src/core/retriever.ts

@@ -7,7 +7,9 @@ import { EventStore } from './event-store.js';
 import { VectorStore, SearchResult } from './vector-store.js';
 import { Embedder } from './embedder.js';
 import { Matcher } from './matcher.js';
-import type { MemoryEvent, MatchResult, Config } from './types.js';
+import { SharedStore } from './shared-store.js';
+import { SharedVectorStore } from './shared-vector-store.js';
+import type { MemoryEvent, MatchResult, Config, SharedTroubleshootingEntry } from './types.js';
 
 export interface RetrievalOptions {
   topK: number;
@@ -30,6 +32,15 @@ export interface MemoryWithContext {
   sessionContext?: string;
 }
 
+export interface UnifiedRetrievalOptions extends RetrievalOptions {
+  includeShared?: boolean;
+  projectHash?: string;
+}
+
+export interface UnifiedRetrievalResult extends RetrievalResult {
+  sharedMemories?: SharedTroubleshootingEntry[];
+}
+
 const DEFAULT_OPTIONS: RetrievalOptions = {
   topK: 5,
   minScore: 0.7,
@@ -37,22 +48,40 @@ const DEFAULT_OPTIONS: RetrievalOptions = {
   includeSessionContext: true
 };
 
+export interface SharedStoreOptions {
+  sharedStore?: SharedStore;
+  sharedVectorStore?: SharedVectorStore;
+}
+
 export class Retriever {
   private readonly eventStore: EventStore;
   private readonly vectorStore: VectorStore;
   private readonly embedder: Embedder;
   private readonly matcher: Matcher;
+  private sharedStore?: SharedStore;
+  private sharedVectorStore?: SharedVectorStore;
 
   constructor(
     eventStore: EventStore,
     vectorStore: VectorStore,
     embedder: Embedder,
-    matcher: Matcher
+    matcher: Matcher,
+    sharedOptions?: SharedStoreOptions
   ) {
     this.eventStore = eventStore;
     this.vectorStore = vectorStore;
     this.embedder = embedder;
     this.matcher = matcher;
+    this.sharedStore = sharedOptions?.sharedStore;
+    this.sharedVectorStore = sharedOptions?.sharedVectorStore;
+  }
+
+  /**
+   * Set shared stores after construction
+   */
+  setSharedStores(sharedStore: SharedStore, sharedVectorStore: SharedVectorStore): void {
+    this.sharedStore = sharedStore;
+    this.sharedVectorStore = sharedVectorStore;
   }
 
   /**
@@ -94,6 +123,93 @@ export class Retriever {
     };
   }
 
+  /**
+   * Retrieve with unified search (project + shared)
+   */
+  async retrieveUnified(
+    query: string,
+    options: Partial<UnifiedRetrievalOptions> = {}
+  ): Promise<UnifiedRetrievalResult> {
+    // Get project-local results first
+    const projectResult = await this.retrieve(query, options);
+
+    // If shared search is not requested or stores not available, return project results only
+    if (!options.includeShared || !this.sharedStore || !this.sharedVectorStore) {
+      return projectResult;
+    }
+
+    try {
+      // Generate query embedding (reuse if possible)
+      const queryEmbedding = await this.embedder.embed(query);
+
+      // Vector search in shared store
+      const sharedVectorResults = await this.sharedVectorStore.search(
+        queryEmbedding.vector,
+        {
+          limit: options.topK || 5,
+          minScore: options.minScore || 0.7,
+          excludeProjectHash: options.projectHash
+        }
+      );
+
+      // Get full entries from shared store
+      const sharedMemories: SharedTroubleshootingEntry[] = [];
+      for (const result of sharedVectorResults) {
+        const entry = await this.sharedStore.get(result.entryId);
+        if (entry) {
+          // Exclude entries from current project if specified
+          if (!options.projectHash || entry.sourceProjectHash !== options.projectHash) {
+            sharedMemories.push(entry);
+            // Record usage for ranking
+            await this.sharedStore.recordUsage(entry.entryId);
+          }
+        }
+      }
+
+      // Build unified context
+      const unifiedContext = this.buildUnifiedContext(projectResult, sharedMemories);
+
+      return {
+        ...projectResult,
+        context: unifiedContext,
+        totalTokens: this.estimateTokens(unifiedContext),
+        sharedMemories
+      };
+    } catch (error) {
+      // If shared search fails, return project results only
+      console.error('Shared search failed:', error);
+      return projectResult;
+    }
+  }
+
+  /**
+   * Build unified context combining project and shared memories
+   */
+  private buildUnifiedContext(
+    projectResult: RetrievalResult,
+    sharedMemories: SharedTroubleshootingEntry[]
+  ): string {
+    let context = projectResult.context;
+
+    if (sharedMemories.length > 0) {
+      context += '\n\n## Cross-Project Knowledge\n\n';
+      for (const memory of sharedMemories.slice(0, 3)) {
+        context += `### ${memory.title}\n`;
+        if (memory.symptoms.length > 0) {
+          context += `**Symptoms:** ${memory.symptoms.join(', ')}\n`;
+        }
+        context += `**Root Cause:** ${memory.rootCause}\n`;
+        context += `**Solution:** ${memory.solution}\n`;
+        if (memory.technologies && memory.technologies.length > 0) {
+          context += `**Technologies:** ${memory.technologies.join(', ')}\n`;
+        }
+        context += `_Confidence: ${(memory.confidence * 100).toFixed(0)}%_\n\n`;
+      }
+    }
+
+    return context;
+  }
+
   /**
    * Retrieve memories from a specific session
    */

package/src/core/shared-event-store.ts

@@ -0,0 +1,114 @@
+/**
+ * SharedEventStore - Global database for cross-project knowledge
+ * Location: ~/.claude-code/memory/shared/
+ */
+
+import {
+  createDatabase,
+  dbRun,
+  dbClose,
+  type Database
+} from './db-wrapper.js';
+
+export class SharedEventStore {
+  private db: Database;
+  private initialized = false;
+
+  constructor(private dbPath: string) {
+    this.db = createDatabase(dbPath);
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    // Shared troubleshooting entries table
+    await dbRun(this.db, `
+      CREATE TABLE IF NOT EXISTS shared_troubleshooting (
+        entry_id VARCHAR PRIMARY KEY,
+        source_project_hash VARCHAR NOT NULL,
+        source_entry_id VARCHAR NOT NULL,
+        title VARCHAR NOT NULL,
+        symptoms JSON NOT NULL,
+        root_cause TEXT NOT NULL,
+        solution TEXT NOT NULL,
+        topics JSON NOT NULL,
+        technologies JSON,
+        confidence REAL NOT NULL DEFAULT 0.8,
+        usage_count INTEGER DEFAULT 0,
+        last_used_at TIMESTAMP,
+        promoted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        UNIQUE(source_project_hash, source_entry_id)
+      )
+    `);
+
+    // Future extensibility: best practices table
+    await dbRun(this.db, `
+      CREATE TABLE IF NOT EXISTS shared_best_practices (
+        entry_id VARCHAR PRIMARY KEY,
+        source_project_hash VARCHAR NOT NULL,
+        source_entry_id VARCHAR NOT NULL,
+        title VARCHAR NOT NULL,
+        content_json JSON NOT NULL,
+        topics JSON NOT NULL,
+        confidence REAL NOT NULL DEFAULT 0.8,
+        usage_count INTEGER DEFAULT 0,
+        promoted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        UNIQUE(source_project_hash, source_entry_id)
+      )
+    `);
+
+    // Future extensibility: common errors table
+    await dbRun(this.db, `
+      CREATE TABLE IF NOT EXISTS shared_common_errors (
+        entry_id VARCHAR PRIMARY KEY,
+        source_project_hash VARCHAR NOT NULL,
+        source_entry_id VARCHAR NOT NULL,
+        title VARCHAR NOT NULL,
+        error_pattern TEXT NOT NULL,
+        solution TEXT NOT NULL,
+        topics JSON NOT NULL,
+        technologies JSON,
+        confidence REAL NOT NULL DEFAULT 0.8,
+        usage_count INTEGER DEFAULT 0,
+        promoted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        UNIQUE(source_project_hash, source_entry_id)
+      )
+    `);
+
+    // Indexes for troubleshooting
+    await dbRun(this.db, `
+      CREATE INDEX IF NOT EXISTS idx_shared_ts_confidence
+      ON shared_troubleshooting(confidence DESC)
+    `);
+    await dbRun(this.db, `
+      CREATE INDEX IF NOT EXISTS idx_shared_ts_usage
+      ON shared_troubleshooting(usage_count DESC)
+    `);
+    await dbRun(this.db, `
+      CREATE INDEX IF NOT EXISTS idx_shared_ts_source
+      ON shared_troubleshooting(source_project_hash)
+    `);
+
+    this.initialized = true;
+  }
+
+  getDatabase(): Database {
+    return this.db;
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  async close(): Promise<void> {
+    await dbClose(this.db);
+    this.initialized = false;
+  }
+}
+
+export function createSharedEventStore(dbPath: string): SharedEventStore {
+  return new SharedEventStore(dbPath);
+}

package/src/core/shared-promoter.ts

@@ -0,0 +1,249 @@
+/**
+ * SharedPromoter - Handles auto-promotion of verified troubleshooting entries
+ * Promotes entries from project-local storage to cross-project shared storage
+ */
+
+import { randomUUID } from 'crypto';
+import { SharedStore } from './shared-store.js';
+import { SharedVectorStore } from './shared-vector-store.js';
+import { Embedder } from './embedder.js';
+import type { Entry, SharedTroubleshootingInput, SharedStoreConfig } from './types.js';
+
+export interface TroubleshootingContent {
+  symptoms?: string[];
+  rootCause?: string;
+  solution?: string;
+  technologies?: string[];
+}
+
+export interface PromotionResult {
+  success: boolean;
+  entryId?: string;
+  error?: string;
+  skipped?: boolean;
+  skipReason?: string;
+}
+
+export class SharedPromoter {
+  constructor(
+    private sharedStore: SharedStore,
+    private sharedVectorStore: SharedVectorStore,
+    private embedder: Embedder,
+    private config?: SharedStoreConfig
+  ) {}
+
+  /**
+   * Check if an entry is eligible for promotion
+   */
+  isEligibleForPromotion(entry: Entry): boolean {
+    // Must be troubleshooting type
+    if (entry.entryType !== 'troubleshooting') {
+      return false;
+    }
+
+    // Must be at least 'verified' stage
+    if (entry.stage !== 'verified' && entry.stage !== 'certified') {
+      return false;
+    }
+
+    // Must be active status
+    if (entry.status !== 'active') {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Promote a verified troubleshooting entry to shared storage
+   */
+  async promoteEntry(
+    entry: Entry,
+    projectHash: string
+  ): Promise<PromotionResult> {
+    // Validate eligibility
+    if (!this.isEligibleForPromotion(entry)) {
+      return {
+        success: false,
+        skipped: true,
+        skipReason: `Entry not eligible: type=${entry.entryType}, stage=${entry.stage}, status=${entry.status}`
+      };
+    }
+
+    // Check if already promoted
+    const exists = await this.sharedStore.exists(projectHash, entry.entryId);
+    if (exists) {
+      return {
+        success: true,
+        skipped: true,
+        skipReason: 'Entry already exists in shared store'
+      };
+    }
+
+    try {
+      const content = entry.contentJson as TroubleshootingContent;
+      const confidence = this.calculateConfidence(entry);
+
+      // Check minimum confidence threshold
+      const minConfidence = this.config?.minConfidenceForPromotion ?? 0.8;
+      if (confidence < minConfidence) {
+        return {
+          success: false,
+          skipped: true,
+          skipReason: `Confidence ${confidence} below threshold ${minConfidence}`
+        };
+      }
+
+      const input: SharedTroubleshootingInput = {
+        sourceProjectHash: projectHash,
+        sourceEntryId: entry.entryId,
+        title: entry.title,
+        symptoms: content.symptoms || [],
+        rootCause: content.rootCause || '',
+        solution: content.solution || '',
+        topics: this.extractTopics(entry),
+        technologies: content.technologies || [],
+        confidence
+      };
+
+      // Promote to shared store
+      const entryId = await this.sharedStore.promoteEntry(input);
+
+      // Create embedding for vector search
+      const embeddingContent = this.createEmbeddingContent(input);
+      const embedding = await this.embedder.embed(embeddingContent);
+
+      await this.sharedVectorStore.upsert({
+        id: randomUUID(),
+        entryId,
+        entryType: 'troubleshooting',
+        content: embeddingContent,
+        vector: embedding.vector,
+        topics: input.topics,
+        sourceProjectHash: projectHash
+      });
+
+      return {
+        success: true,
+        entryId
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+
+  /**
+   * Batch promote multiple entries
+   */
+  async promoteEntries(
+    entries: Entry[],
+    projectHash: string
+  ): Promise<Map<string, PromotionResult>> {
+    const results = new Map<string, PromotionResult>();
+
+    for (const entry of entries) {
+      const result = await this.promoteEntry(entry, projectHash);
+      results.set(entry.entryId, result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Extract topics from entry
+   */
+  private extractTopics(entry: Entry): string[] {
+    const topics: string[] = [];
+
+    // Extract from title (meaningful words)
+    const titleWords = entry.title
+      .toLowerCase()
+      .split(/[\s\-_]+/)
+      .filter(w => w.length > 3 && !this.isStopWord(w));
+    topics.push(...titleWords);
+
+    // Extract from content if available
+    const content = entry.contentJson as Record<string, unknown>;
+    if (content.topics && Array.isArray(content.topics)) {
+      topics.push(...content.topics.map(t => String(t).toLowerCase()));
+    }
+
+    // Extract technologies as topics
+    if (content.technologies && Array.isArray(content.technologies)) {
+      topics.push(...content.technologies.map(t => String(t).toLowerCase()));
+    }
+
+    // Dedupe and return
+    return [...new Set(topics)];
+  }
+
+  /**
+   * Check if word is a stop word
+   */
+  private isStopWord(word: string): boolean {
+    const stopWords = new Set([
+      'the', 'and', 'for', 'with', 'this', 'that', 'from', 'have', 'been',
+      'were', 'are', 'was', 'had', 'has', 'will', 'would', 'could', 'should',
+      'when', 'where', 'what', 'which', 'while', 'error', 'problem', 'issue'
+    ]);
+    return stopWords.has(word);
+  }
+
+  /**
+   * Calculate confidence score for entry
+   */
+  private calculateConfidence(entry: Entry): number {
+    let confidence = 0.8; // Base confidence for verified entries
+
+    // Boost if certified
+    if (entry.stage === 'certified') {
+      confidence = 0.95;
+    }
+
+    // Could add more factors:
+    // - Number of evidence items
+    // - Age of entry (older verified entries may be more reliable)
+    // - Usage count if tracked
+
+    return Math.min(confidence, 1.0);
+  }
+
+  /**
+   * Create embedding content from input
+   */
+  private createEmbeddingContent(input: SharedTroubleshootingInput): string {
+    const parts: string[] = [];
+
+    parts.push(`Problem: ${input.title}`);
+
+    if (input.symptoms.length > 0) {
+      parts.push(`Symptoms: ${input.symptoms.join(', ')}`);
+    }
+
+    if (input.rootCause) {
+      parts.push(`Root Cause: ${input.rootCause}`);
+    }
+
+    if (input.solution) {
+      parts.push(`Solution: ${input.solution}`);
+    }
+
+    if (input.technologies && input.technologies.length > 0) {
+      parts.push(`Technologies: ${input.technologies.join(', ')}`);
+    }
+
+    return parts.join('\n');
+  }
+}
+
+export function createSharedPromoter(
+  sharedStore: SharedStore,
+  sharedVectorStore: SharedVectorStore,
+  embedder: Embedder,
+  config?: SharedStoreConfig
+): SharedPromoter {
+  return new SharedPromoter(sharedStore, sharedVectorStore, embedder, config);
+}