claude-cognitive 0.3.2 → 0.4.0

package/dist/mind.js

@@ -9,8 +9,9 @@ import { HindsightClient } from "./client.js";
 import { loadConfig } from "./config.js";
 import { HindsightError } from "./errors.js";
 import { TypedEventEmitter } from "./events.js";
-import { PromotionManager, DEFAULT_PROMOTION_THRESHOLD } from "./promotion.js";
-import { SemanticMemory } from "./semantic.js";
+import { createFeedbackService } from "./feedback/index.js";
+import { OfflineFeedbackQueue } from "./feedback/offline-queue.js";
+import { OfflineMemoryStore } from "./offline.js";
 // ============================================
 // Default Values
 // ============================================
@@ -63,10 +64,14 @@ export class Mind extends TypedEventEmitter {
     bankId = "";
     disposition = DEFAULT_DISPOSITION;
     background;
-    /** Path to semantic memory file. Used in Phase 3. */
-    semanticPath = ".claude/memory.md";
     // Client (nullable for graceful degradation)
     client = null;
+    // Offline memory store (always available)
+    offlineStore = null;
+    // Feedback service (optional, enabled via config)
+    feedbackService = null;
+    // Offline feedback queue (for degraded mode)
+    feedbackQueue = null;
     // State
     initialized = false;
     initializing = false;
@@ -74,11 +79,12 @@ export class Mind extends TypedEventEmitter {
     sessionActive = false;
     /** Session start time. Used for duration tracking. */
     sessionStartTime = null;
+    /** Current session ID for feedback tracking */
+    sessionId = null;
     // Agent templates (loaded in init())
     customAgents = [];
-    // Semantic memory (loaded in init())
-    semantic = null;
-    promotionManager = null;
+    // Context settings
+    recentMemoryLimit = 3;
     /**
      * Create a new Mind instance.
      *
@@ -138,9 +144,6 @@ export class Mind extends TypedEventEmitter {
             if (this.pendingOptions.background !== undefined) {
                 overrides.background = this.pendingOptions.background;
             }
-            if (this.pendingOptions.semanticPath !== undefined) {
-                overrides.semantic = { path: this.pendingOptions.semanticPath };
-            }
             // Load config with pending options as overrides
             const config = await loadConfig(this.projectPath, overrides);
             // Resolve configuration
@@ -149,7 +152,7 @@ export class Mind extends TypedEventEmitter {
             if (config.background) {
                 this.background = config.background;
             }
-            this.semanticPath = config.semantic?.path ?? ".claude/memory.md";
+            this.recentMemoryLimit = config.context?.recentMemoryLimit ?? 3;
             // Create HindsightClient
             const clientOptions = {
                 host: config.hindsight.host,
@@ -173,21 +176,17 @@ export class Mind extends TypedEventEmitter {
             }
             // Load custom agents from .claude/agents/
             this.customAgents = await loadCustomAgents(this.projectPath);
-            // Load semantic memory
-            this.semantic = new SemanticMemory(this.projectPath, this.semanticPath);
-            try {
-                await this.semantic.load();
-            }
-            catch (error) {
-                // Semantic memory is optional - emit error but continue
-                this.emit("error", error instanceof Error ? error : new Error(String(error)));
-            }
-            // Initialize promotion manager
-            if (this.semantic.isLoaded()) {
-                this.promotionManager = new PromotionManager(this.semantic, this, {
-                    threshold: DEFAULT_PROMOTION_THRESHOLD,
+            // Initialize offline store (always available)
+            this.offlineStore = new OfflineMemoryStore({
+                projectPath: this.projectPath,
+            });
+            // Initialize feedback service if enabled
+            if (config.feedback?.enabled) {
+                this.feedbackService = createFeedbackService(config.feedback, this.projectPath);
+                // Initialize offline feedback queue alongside the service
+                this.feedbackQueue = new OfflineFeedbackQueue({
+                    projectPath: this.projectPath,
                 });
-                this.promotionManager.startListening();
             }
             // Mark initialized
             this.initialized = true;
@@ -273,30 +272,43 @@ export class Mind extends TypedEventEmitter {
         }
         this.sessionActive = true;
         this.sessionStartTime = new Date();
+        this.sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         const contextParts = [];
         // Add agent orchestration instructions
         const agentInstructions = this.formatAgentInstructions();
         if (agentInstructions.trim().length > 0) {
             contextParts.push(agentInstructions);
         }
-        // Load semantic memory context
-        if (this.semantic?.isLoaded()) {
-            const semanticContext = this.semantic.toContext();
-            if (semanticContext.trim().length > 0) {
-                contextParts.push(semanticContext);
-            }
-        }
-        // Recall recent experiences (if not degraded)
-        if (!this.degraded && this.client) {
-            try {
-                const recent = await this.client.recent(this.bankId, 7);
-                if (recent.length > 0) {
-                    this.emit("memory:recalled", recent);
-                    contextParts.push(this.formatRecentMemories(recent));
+        // Recall recent experiences
+        // Only fetch a small number (default 3) to keep context small
+        if (this.recentMemoryLimit > 0) {
+            if (!this.degraded && this.client) {
+                // Online mode: fetch from Hindsight
+                try {
+                    const recent = await this.client.recent(this.bankId, this.recentMemoryLimit);
+                    if (recent.length > 0) {
+                        this.emit("memory:recalled", recent);
+                        contextParts.push(this.formatRecentMemories(recent));
+                    }
+                }
+                catch (error) {
+                    this.handleError(error, "onSessionStart recall");
+                    // Fall through to offline on error
                 }
             }
-            catch (error) {
-                this.handleError(error, "onSessionStart recall");
+            // Offline/degraded mode: fetch from local storage
+            if (this.degraded && this.offlineStore) {
+                try {
+                    const offlineRecent = await this.offlineStore.getRecent(this.recentMemoryLimit);
+                    if (offlineRecent.length > 0) {
+                        const memories = offlineRecent.map(OfflineMemoryStore.toMemory);
+                        this.emit("memory:recalled", memories);
+                        contextParts.push(this.formatRecentMemories(memories));
+                    }
+                }
+                catch (error) {
+                    this.emit("error", error instanceof Error ? error : new Error(String(error)));
+                }
             }
         }
         return contextParts.join("\n\n");
@@ -305,8 +317,8 @@ export class Mind extends TypedEventEmitter {
      * Called at session end. Reflects on session and stores observations.
      *
      * This method:
-     * 1. Retains transcript if provided
-     * 2. Reflects on the session
+     * 1. Retains transcript if provided (online or offline)
+     * 2. Reflects on the session (online only)
      * 3. Emits opinion events
      *
      * @param transcript - Optional session transcript to store
@@ -315,20 +327,80 @@ export class Mind extends TypedEventEmitter {
     async onSessionEnd(transcript) {
         this.assertInitialized();
         // Retain transcript if provided
-        if (transcript && !this.degraded && this.client) {
+        if (transcript) {
+            if (!this.degraded && this.client) {
+                // Online mode: store to Hindsight
+                try {
+                    await this.client.retain({
+                        bankId: this.bankId,
+                        content: transcript,
+                        context: "Session transcript",
+                    });
+                    this.emit("memory:retained", transcript);
+                }
+                catch (error) {
+                    this.handleError(error, "onSessionEnd retain");
+                    // Fall through to offline on error
+                }
+            }
+            // Degraded/offline mode: store locally
+            if (this.degraded && this.offlineStore) {
+                try {
+                    await this.offlineStore.retain(transcript, "experience", {
+                        context: "Session transcript",
+                    });
+                    this.emit("memory:retained", transcript);
+                    this.emit("offline:stored", {
+                        content: transcript,
+                        factType: "experience",
+                    });
+                }
+                catch (error) {
+                    this.emit("error", error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        }
+        // Process feedback if enabled
+        if (this.feedbackService && this.sessionId && transcript) {
             try {
-                await this.client.retain(this.bankId, transcript, "Session transcript");
-                this.emit("memory:retained", transcript);
+                const feedbackResult = await this.feedbackService.processFeedback(this.sessionId, {
+                    conversationText: transcript,
+                });
+                if (feedbackResult.success && feedbackResult.feedback.length > 0) {
+                    if (!this.degraded && this.client) {
+                        // Online mode: Submit feedback signals to Hindsight
+                        await this.client.signal({
+                            bankId: this.bankId,
+                            signals: feedbackResult.feedback,
+                        });
+                        this.emit("feedback:processed", {
+                            sessionId: this.sessionId,
+                            summary: feedbackResult.summary,
+                        });
+                    }
+                    else if (this.feedbackQueue) {
+                        // Degraded mode: Queue signals for later sync
+                        await this.feedbackQueue.enqueueBatch(feedbackResult.feedback);
+                        this.emit("feedback:queued", {
+                            sessionId: this.sessionId,
+                            count: feedbackResult.feedback.length,
+                        });
+                    }
+                }
             }
             catch (error) {
-                this.handleError(error, "onSessionEnd retain");
+                // Silently ignore feedback processing errors - non-critical
+                this.emit("error", error instanceof Error ? error : new Error("Feedback processing failed"));
             }
         }
         // Reflect on session (if not degraded)
         let result = null;
         if (!this.degraded && this.client) {
             try {
-                result = await this.client.reflect(this.bankId, "What insights can I draw from this session?");
+                result = await this.client.reflect({
+                    bankId: this.bankId,
+                    query: "What insights can I draw from this session?",
+                });
                 // Emit opinion events
                 for (const opinion of result.opinions) {
                     this.emit("opinion:formed", opinion);
@@ -338,13 +410,10 @@ export class Mind extends TypedEventEmitter {
                 this.handleError(error, "onSessionEnd reflect");
             }
         }
-        // Clear promotion cache for next session
-        if (this.promotionManager) {
-            this.promotionManager.clearCache();
-        }
         // Reset session state
         this.sessionActive = false;
         this.sessionStartTime = null;
+        this.sessionId = null;
         return result;
     }
     // ============================================
@@ -353,7 +422,7 @@ export class Mind extends TypedEventEmitter {
     /**
      * Search memories for relevant context.
      *
-     * In degraded mode, returns an empty array.
+     * In degraded mode, searches offline storage (text-based).
      *
      * @param query - What to search for
      * @param options - Search options (budget, factType, etc.)
@@ -361,19 +430,67 @@ export class Mind extends TypedEventEmitter {
      */
     async recall(query, options) {
         this.assertInitialized();
-        // Degraded mode: return empty array
-        if (this.degraded || !this.client) {
-            return [];
-        }
-        try {
-            const memories = await this.client.recall(this.bankId, query, options);
-            this.emit("memory:recalled", memories);
-            return memories;
+        // Online mode: use Hindsight
+        if (!this.degraded && this.client) {
+            try {
+                // Build recall input, only including defined properties
+                const recallInput = {
+                    bankId: this.bankId,
+                    query,
+                };
+                if (options?.budget !== undefined)
+                    recallInput.budget = options.budget;
+                if (options?.factType !== undefined)
+                    recallInput.factType = options.factType;
+                if (options?.maxTokens !== undefined)
+                    recallInput.maxTokens = options.maxTokens;
+                if (options?.includeEntities !== undefined)
+                    recallInput.includeEntities = options.includeEntities;
+                if (options?.boostByUsefulness !== undefined)
+                    recallInput.boostByUsefulness = options.boostByUsefulness;
+                if (options?.usefulnessWeight !== undefined)
+                    recallInput.usefulnessWeight = options.usefulnessWeight;
+                if (options?.minUsefulness !== undefined)
+                    recallInput.minUsefulness = options.minUsefulness;
+                const memories = await this.client.recall(recallInput);
+                this.emit("memory:recalled", memories);
+                // Track recall for feedback if enabled
+                if (this.feedbackService && this.sessionId && memories.length > 0) {
+                    try {
+                        await this.feedbackService.trackRecall(this.sessionId, query, memories);
+                    }
+                    catch {
+                        // Silently ignore feedback tracking errors
+                    }
+                }
+                return memories;
+            }
+            catch (error) {
+                this.handleError(error, "recall");
+                // Fall through to offline on error
+            }
         }
-        catch (error) {
-            this.handleError(error, "recall");
-            return [];
+        // Degraded/offline mode: use local storage
+        if (this.offlineStore) {
+            try {
+                const recallOptions = {
+                    limit: options?.maxTokens ? Math.floor(options.maxTokens / 100) : 10,
+                };
+                if (options?.factType) {
+                    recallOptions.factType = options.factType;
+                }
+                const offlineMemories = await this.offlineStore.recall(query, recallOptions);
+                const memories = offlineMemories.map(OfflineMemoryStore.toMemory);
+                if (memories.length > 0) {
+                    this.emit("memory:recalled", memories);
+                }
+                return memories;
+            }
+            catch (error) {
+                this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            }
         }
+        return [];
     }
     /**
      * Reason about accumulated knowledge and form opinions.
@@ -388,30 +505,78 @@ export class Mind extends TypedEventEmitter {
         if (this.degraded || !this.client) {
             throw new HindsightError("reflect() requires Hindsight connection", "HINDSIGHT_UNAVAILABLE", { isRetryable: false });
         }
-        const result = await this.client.reflect(this.bankId, query);
+        const result = await this.client.reflect({
+            bankId: this.bankId,
+            query,
+        });
         // Emit opinion events
         for (const opinion of result.opinions) {
             this.emit("opinion:formed", opinion);
         }
         return result;
     }
+    /**
+     * Submit feedback signals for recalled facts.
+     *
+     * @param signals - Array of signal items with factId, signalType, etc.
+     * @returns Signal result
+     * @throws {HindsightError} If in degraded mode (signal requires Hindsight)
+     */
+    async signal(signals) {
+        this.assertInitialized();
+        if (this.degraded || !this.client) {
+            throw new HindsightError("signal() requires Hindsight connection", "HINDSIGHT_UNAVAILABLE", { isRetryable: false });
+        }
+        return this.client.signal({
+            bankId: this.bankId,
+            signals,
+        });
+    }
     /**
      * Store content in memory.
      *
-     * In degraded mode, skips silently and emits an error event.
+     * In degraded mode, stores to offline storage for later sync.
      *
      * @param content - Content to store
      * @param context - Optional additional context
+     * @param factType - Memory type (default: experience)
      */
-    async retain(content, context) {
+    async retain(content, context, factType = "experience") {
         this.assertInitialized();
-        // Degraded mode: skip silently
-        if (this.degraded || !this.client) {
-            this.emit("error", new Error("retain() skipped: Hindsight unavailable"));
-            return;
+        // Online mode: use Hindsight
+        if (!this.degraded && this.client) {
+            try {
+                // Build retain input, only including defined properties
+                const retainInput = {
+                    bankId: this.bankId,
+                    content,
+                };
+                if (context !== undefined)
+                    retainInput.context = context;
+                await this.client.retain(retainInput);
+                this.emit("memory:retained", content);
+                return;
+            }
+            catch (error) {
+                this.handleError(error, "retain");
+                // Fall through to offline on error
+            }
+        }
+        // Degraded/offline mode: store locally
+        if (this.offlineStore) {
+            try {
+                const retainOptions = {};
+                if (context) {
+                    retainOptions.context = context;
+                }
+                await this.offlineStore.retain(content, factType, retainOptions);
+                this.emit("memory:retained", content);
+                this.emit("offline:stored", { content, factType });
+            }
+            catch (error) {
+                this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            }
         }
-        await this.client.retain(this.bankId, content, context);
-        this.emit("memory:retained", content);
     }
     // ============================================
     // Learn Operation
@@ -522,6 +687,7 @@ ${template.outputFormat}
     }
     /**
      * Attempt to recover from degraded mode.
+     * If successful, syncs offline memories to Hindsight.
      *
      * @returns True if recovery was successful
      */
@@ -533,10 +699,112 @@ ${template.outputFormat}
         if (health.healthy) {
             this.exitDegradedMode();
             await this.ensureBank();
+            // Auto-sync offline memories
+            await this.syncOfflineMemories();
+            // Auto-sync offline feedback signals
+            await this.syncOfflineFeedback();
             return true;
         }
         return false;
     }
+    /**
+     * Sync offline memories to Hindsight.
+     * Called automatically on recovery from degraded mode.
+     *
+     * @returns Number of memories synced
+     */
+    async syncOfflineMemories() {
+        if (!this.client || this.degraded || !this.offlineStore) {
+            return 0;
+        }
+        try {
+            await this.offlineStore.recordSyncAttempt();
+            const unsynced = await this.offlineStore.getUnsynced();
+            if (unsynced.length === 0) {
+                return 0;
+            }
+            const syncedIds = [];
+            for (const memory of unsynced) {
+                try {
+                    // Build retain input, only including defined properties
+                    const retainInput = {
+                        bankId: this.bankId,
+                        content: memory.text,
+                    };
+                    if (memory.context !== undefined)
+                        retainInput.context = memory.context;
+                    await this.client.retain(retainInput);
+                    syncedIds.push(memory.id);
+                }
+                catch (error) {
+                    // Stop on error - don't want to skip memories
+                    this.emit("error", error instanceof Error
+                        ? error
+                        : new Error(`Failed to sync memory ${memory.id}`));
+                    break;
+                }
+            }
+            if (syncedIds.length > 0) {
+                await this.offlineStore.markSynced(syncedIds);
+                this.emit("offline:synced", { count: syncedIds.length });
+                // Clear synced memories to save space
+                await this.offlineStore.clearSynced();
+            }
+            return syncedIds.length;
+        }
+        catch (error) {
+            this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            return 0;
+        }
+    }
+    /**
+     * Sync offline feedback signals to Hindsight.
+     * Called automatically on recovery from degraded mode.
+     *
+     * @returns Number of feedback signals synced
+     */
+    async syncOfflineFeedback() {
+        if (!this.client || this.degraded || !this.feedbackQueue) {
+            return 0;
+        }
+        try {
+            await this.feedbackQueue.recordSyncAttempt();
+            const unsynced = await this.feedbackQueue.getUnsynced();
+            if (unsynced.length === 0) {
+                return 0;
+            }
+            // Convert offline signals back to SignalItem format
+            const signals = unsynced.map(OfflineFeedbackQueue.toSignalItem);
+            // Submit all signals in one batch
+            await this.client.signal({
+                bankId: this.bankId,
+                signals,
+            });
+            // Mark all as synced
+            const ids = unsynced.map((s) => s.id);
+            await this.feedbackQueue.markSynced(ids);
+            this.emit("feedback:synced", { count: ids.length });
+            // Clear synced signals to save space
+            await this.feedbackQueue.clearSynced();
+            return ids.length;
+        }
+        catch (error) {
+            this.emit("error", error instanceof Error ? error : new Error(String(error)));
+            return 0;
+        }
+    }
+    /**
+     * Get offline feedback queue (for CLI commands).
+     */
+    getOfflineFeedbackQueue() {
+        return this.feedbackQueue;
+    }
+    /**
+     * Get offline memory store (for CLI commands).
+     */
+    getOfflineStore() {
+        return this.offlineStore;
+    }
     /**
      * Enter degraded mode.
      * @internal
@@ -603,28 +871,6 @@ ${template.outputFormat}
     isSessionActive() {
         return this.sessionActive;
     }
-    /**
-     * Get the path to semantic memory file.
-     */
-    getSemanticPath() {
-        return this.semanticPath;
-    }
-    /**
-     * Get the SemanticMemory instance.
-     *
-     * @returns SemanticMemory or null if not initialized
-     */
-    getSemanticMemory() {
-        return this.semantic;
-    }
-    /**
-     * Get the PromotionManager instance.
-     *
-     * @returns PromotionManager or null if not initialized
-     */
-    getPromotionManager() {
-        return this.promotionManager;
-    }
     /**
      * Get the session start time, or null if no session is active.
      */
@@ -642,15 +888,18 @@ ${template.outputFormat}
     }
     /**
      * Format recent memories as context string.
+     * Shows fuller context since we only fetch a few memories.
      * @internal
      */
     formatRecentMemories(memories) {
         if (memories.length === 0)
             return "";
-        const lines = ["### Recent Context"];
-        for (const mem of memories.slice(0, 5)) {
+        const lines = ["## Recent Activity"];
+        for (const mem of memories) {
             const date = new Date(mem.createdAt).toLocaleDateString();
-            const text = mem.text.length > 100 ? `${mem.text.slice(0, 100)}...` : mem.text;
+            // Show more text since we're fetching fewer memories
+            const maxLen = 200;
+            const text = mem.text.length > maxLen ? `${mem.text.slice(0, maxLen)}...` : mem.text;
             lines.push(`- ${date}: ${text}`);
         }
         return lines.join("\n");
@@ -714,19 +963,17 @@ ${template.outputFormat}
      * After calling dispose(), the Mind instance should not be used.
      */
     dispose() {
-        // Stop promotion manager event listeners
-        if (this.promotionManager) {
-            this.promotionManager.stopListening();
-            this.promotionManager = null;
-        }
         // Clear references
-        this.semantic = null;
         this.client = null;
+        this.offlineStore = null;
+        this.feedbackService = null;
+        this.feedbackQueue = null;
         this.customAgents = [];
         // Reset state
         this.initialized = false;
         this.sessionActive = false;
         this.sessionStartTime = null;
+        this.sessionId = null;
         this.degraded = false;
     }
 }