lemma-mcp 0.8.2 → 0.8.4

package/dist/server/handlers.js

@@ -2,28 +2,36 @@ import * as core from "../memory/index.js";
 import * as guides from "../guides/index.js";
 import * as sessions from "../sessions/index.js";
 import * as virtualSession from "../sessions/virtual.js";
+import { logger } from "../logger.js";
 let activeSessionId = null;
 let _notifyChange = null;
 export function setNotifyChange(fn) {
     _notifyChange = fn;
+    logger.debug("setNotifyChange", "notification handler registered");
 }
 function notifyMemoryChange() {
-    if (_notifyChange)
+    if (_notifyChange) {
+        logger.notify("memory_change", "sending");
         _notifyChange();
+    }
 }
 export async function handleSessionStart(args) {
     const taskType = args?.task_type;
     const technologies = args?.technologies || [];
     const initialApproach = args?.initial_approach || null;
+    logger.flow("session_start", "start", { task_type: taskType, technologies, has_initial_approach: !!initialApproach });
     if (!taskType) {
+        logger.warn("session_start validation failed", { reason: "missing task_type" });
         return {
             content: [{ type: "text", text: "Error: 'task_type' parameter is required" }],
             isError: true,
         };
     }
+    logger.data("sessions.json", "load");
     const allSessions = sessions.loadSessions();
     const existing = sessions.findActiveSession(allSessions);
     if (existing) {
+        logger.flow("session_start", "abandon_existing", { session_id: existing.session_id, task_type: existing.task_type });
         existing.status = "abandoned";
         existing.task_outcome = "abandoned";
     }
@@ -31,18 +39,24 @@ export async function handleSessionStart(args) {
     session.initial_approach = initialApproach;
     activeSessionId = session.session_id;
     allSessions.push(session);
+    logger.data("sessions.json", "save", { session_id: session.session_id, total_sessions: allSessions.length });
     sessions.saveSessions(allSessions);
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const taskDesc = [taskType, ...technologies].join(" ");
     const suggestions = guides.suggestGuides(taskDesc, allGuides);
+    logger.flow("session_start", "guide_suggestions", { task_desc: taskDesc, relevant: suggestions.relevant.length, suggested: suggestions.suggested.length });
     const formattedSuggestions = guides.formatSuggestions(suggestions);
+    logger.data("memory.json", "load");
     const allMemory = core.loadMemory();
     const projectMemory = core.filterByProject(allMemory, core.detectProject());
     const relevantResults = core.searchAndSortFragments(projectMemory, taskDesc, 3);
+    logger.flow("session_start", "preload_memories", { relevant_count: relevantResults.length, project_memory_count: projectMemory.length });
     for (const frag of relevantResults) {
         const boosted = core.boostOnAccess(frag);
         Object.assign(frag, boosted);
     }
+    logger.data("memory.json", "save", { reason: "boost_preloaded", boosted_count: relevantResults.length });
     core.saveMemory(allMemory);
     let response = `Session started: ${session.session_id} (${taskType})\n`;
     if (technologies.length > 0) {
@@ -57,6 +71,7 @@ export async function handleSessionStart(args) {
         }
     }
     response += `\n${formattedSuggestions}`;
+    logger.flow("session_start", "complete", { session_id: session.session_id, task_type: taskType, suggestions: suggestions.relevant.length + suggestions.suggested.length, preloaded: relevantResults.length });
     return {
         content: [{ type: "text", text: response }],
     };
@@ -65,26 +80,33 @@ export async function handleSessionEnd(args) {
     const outcome = args?.outcome;
     const finalApproach = args?.final_approach || null;
     const lessons = args?.lessons || [];
+    logger.flow("session_end", "start", { outcome, has_final_approach: !!finalApproach, lesson_count: lessons.length });
     if (!outcome) {
+        logger.warn("session_end validation failed", { reason: "missing outcome" });
         return {
             content: [{ type: "text", text: "Error: 'outcome' parameter is required" }],
             isError: true,
         };
     }
+    logger.data("sessions.json", "load");
     const allSessions = sessions.loadSessions();
     const session = activeSessionId
         ? sessions.findSession(allSessions, activeSessionId)
         : sessions.findActiveSession(allSessions);
     if (!session) {
+        logger.warn("session_end no active session", { activeSessionId });
         return {
             content: [{ type: "text", text: "Error: No active session to end." }],
             isError: true,
         };
     }
+    logger.flow("session_end", "session_found", { session_id: session.session_id, task_type: session.task_type });
     sessions.endSession(session, outcome, finalApproach, lessons);
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const improvementLines = [];
     if (session.guides_used && session.guides_used.length > 0) {
+        logger.flow("session_end", "evaluating_guides", { guides_used: session.guides_used, outcome });
         for (const guideName of session.guides_used) {
             const guide = guides.findGuide(allGuides, guideName);
             if (guide) {
@@ -97,14 +119,17 @@ export async function handleSessionEnd(args) {
                     if (total >= 3) {
                         const rate = guide.success_count / total;
                         if (rate < 0.4) {
+                            logger.warn("session_end low guide success rate", { guide: guideName, success_rate: rate.toFixed(2), total });
                             improvementLines.push(`  [!] Guide "${guideName}" success rate is ${rate.toFixed(2)} (${guide.success_count}/${total}). Consider refining with guide_update.`);
                         }
                     }
                 }
             }
         }
+        logger.data("guides.json", "save", { reason: "guide_success_tracking", guides_updated: session.guides_used.length });
         guides.saveGuides(allGuides);
     }
+    logger.data("sessions.json", "save", { session_id: session.session_id, outcome });
     sessions.saveSessions(allSessions);
     activeSessionId = null;
     let response = `Session ${session.session_id} ended: ${outcome}\n`;
@@ -115,6 +140,7 @@ export async function handleSessionEnd(args) {
     if (improvementLines.length > 0) {
         response += `\nIMPROVEMENT SUGGESTIONS:\n${improvementLines.join("\n")}\n`;
     }
+    logger.flow("session_end", "complete", { session_id: session.session_id, outcome, improvement_suggestions: improvementLines.length });
     return {
         content: [{ type: "text", text: response }],
     };
@@ -125,9 +151,12 @@ export async function handleMemoryRead(args) {
     const detailId = args?.id || null;
     const context = args?.context || null;
     const showAll = args?.all === true;
+    logger.flow("memory_read", "start", { project: currentProject, query, id: detailId, ids: args?.ids?.length, all: showAll, context });
     let memory = core.loadMemory();
+    logger.data("memory.json", "load", { total_fragments: memory.length });
     const detailIds = args?.ids || null;
     if (detailIds && Array.isArray(detailIds) && detailIds.length > 0) {
+        logger.debug("memory_read batch_ids", { ids: detailIds });
         const results = [];
         for (const did of detailIds) {
             const fragment = memory.find((f) => f.id === did);
@@ -137,18 +166,23 @@ export async function handleMemoryRead(args) {
                 results.push(core.formatMemoryDetail(fragment));
             }
             else {
+                logger.warn("memory_read batch_id not_found", { id: did });
                 results.push(`Fragment [${did}] not found.`);
             }
         }
+        logger.data("memory.json", "save", { reason: "boost_batch_ids", count: detailIds.length });
         core.saveMemory(memory);
         notifyMemoryChange();
+        logger.flow("memory_read", "complete_batch", { ids_requested: detailIds.length });
         return {
             content: [{ type: "text", text: results.join("\n\n") }],
         };
     }
     if (detailId) {
+        logger.flow("memory_read", "single_id_lookup", { id: detailId });
         const fragment = memory.find((f) => f.id === detailId);
         if (!fragment) {
+            logger.warn("memory_read id not_found", { id: detailId });
             return {
                 content: [{ type: "text", text: `Error: Fragment with ID '${detailId}' not found` }],
                 isError: true,
@@ -156,8 +190,10 @@ export async function handleMemoryRead(args) {
         }
         const boosted = core.boostOnAccess(fragment, context);
         Object.assign(fragment, boosted);
+        logger.data("memory.json", "save", { reason: "boost_single", id: detailId });
         core.saveMemory(memory);
         notifyMemoryChange();
+        logger.flow("memory_read", "complete_single", { id: detailId, confidence: fragment.confidence?.toFixed(2) });
         return {
             content: [{ type: "text", text: core.formatMemoryDetail(fragment) }],
         };
@@ -165,12 +201,14 @@ export async function handleMemoryRead(args) {
     const filteredMemory = showAll
         ? memory
         : core.filterByProject(memory, currentProject);
+    logger.debug("memory_read filter", { showAll, project: currentProject, before_filter: memory.length, after_filter: filteredMemory.length });
     let results = core.searchAndSortFragments(filteredMemory, query, 30);
     results = core.filterFragments(results, {
         minConfidence: args?.minConfidence,
         afterDate: args?.afterDate,
         beforeDate: args?.beforeDate,
     });
+    logger.flow("memory_read", "search_results", { query, result_count: results.length, minConfidence: args?.minConfidence });
     const resultIds = new Set(results.map((r) => r.id));
     for (const frag of memory) {
         if (resultIds.has(frag.id)) {
@@ -180,8 +218,10 @@ export async function handleMemoryRead(args) {
     }
     const scopeInfo = showAll ? "all projects" : currentProject || "global";
     const formatted = core.formatMemoryForLLM(results, scopeInfo);
+    logger.data("memory.json", "save", { reason: "boost_search_results", boosted_count: resultIds.size });
     core.saveMemory(memory);
     notifyMemoryChange();
+    logger.flow("memory_read", "complete_search", { query, results: results.length, scope: scopeInfo });
     return {
         content: [{ type: "text", text: formatted }],
     };
@@ -192,15 +232,19 @@ export async function handleMemoryAdd(args) {
     const description = args?.description || null;
     const project = args?.project === undefined ? null : args.project;
     const source = (args?.source || "ai");
+    logger.flow("memory_add", "start", { title, project, source, has_description: !!description, fragment_length: fragment?.length });
     if (!fragment || typeof fragment !== "string") {
+        logger.warn("memory_add validation failed", { reason: "missing or invalid fragment" });
         return {
             content: [{ type: "text", text: "Error: 'fragment' parameter is required and must be a string" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const similarMatch = core.findSimilarFragment(memory, fragment, project);
     if (similarMatch) {
+        logger.warn("memory_add duplicate_detected", { similar_id: similarMatch.id, similar_title: similarMatch.title });
         return {
             content: [{
                     type: "text",
@@ -209,25 +253,35 @@ export async function handleMemoryAdd(args) {
             isError: true,
         };
     }
+    logger.flow("memory_add", "secret_detection", { confirm: args?.confirm });
     const { redacted, found } = core.redactSecrets(fragment);
     const hasSecrets = found.length > 0;
     const finalFragment = hasSecrets && !args?.confirm ? redacted : fragment;
+    if (hasSecrets) {
+        logger.warn("memory_add secrets_detected", { secret_types: found.map(f => f.type), confirmed: !!args?.confirm });
+    }
     const newFragment = core.createFragment(finalFragment, source, title, project, description);
+    logger.flow("memory_add", "fragment_created", { id: newFragment.id, title: newFragment.title });
     if (activeSessionId) {
+        logger.data("sessions.json", "load");
         const allSessions = sessions.loadSessions();
         const session = sessions.findSession(allSessions, activeSessionId);
         if (session) {
+            logger.flow("memory_add", "session_link", { session_id: activeSessionId, task_type: session.task_type });
             newFragment.session_id = activeSessionId;
             newFragment.task_type = session.task_type;
             session.memories_created = session.memories_created || [];
             session.memories_created.push(newFragment.id);
+            logger.data("sessions.json", "save", { reason: "link_memory", session_id: activeSessionId });
             sessions.saveSessions(allSessions);
         }
     }
     memory.push(newFragment);
+    logger.data("memory.json", "save", { reason: "add_fragment", id: newFragment.id, total: memory.length });
     core.saveMemory(memory);
     notifyMemoryChange();
     const overlaps = core.findTopicOverlaps(memory, finalFragment, project, 5);
+    logger.flow("memory_add", "overlap_check", { overlap_count: overlaps.length });
     const scopeInfo = newFragment.project ? ` (project: ${newFragment.project})` : " (global)";
     let response = `Added fragment [${newFragment.id}]${scopeInfo}: "${newFragment.title}"\nSummary: ${newFragment.description}`;
     if (hasSecrets) {
@@ -240,6 +294,7 @@ export async function handleMemoryAdd(args) {
         }
         response += `\nConsider: Does this update or contradict existing knowledge? Use memory_update to refine or memory_merge to consolidate.`;
     }
+    logger.flow("memory_add", "complete", { id: newFragment.id, title: newFragment.title, overlaps: overlaps.length });
     return {
         content: [{ type: "text", text: response }],
     };
@@ -249,15 +304,19 @@ export async function handleMemoryUpdate(args) {
     const title = args?.title;
     const fragment = args?.fragment;
     const confidence = args?.confidence;
+    logger.flow("memory_update", "start", { id, has_title: title !== undefined, has_fragment: fragment !== undefined, has_confidence: confidence !== undefined });
     if (!id || typeof id !== "string") {
+        logger.warn("memory_update validation failed", { reason: "missing or invalid id" });
         return {
             content: [{ type: "text", text: "Error: 'id' parameter is required and must be a string" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const targetIndex = memory.findIndex((f) => f.id === id);
     if (targetIndex === -1) {
+        logger.warn("memory_update fragment not_found", { id });
         return {
             content: [{ type: "text", text: `Error: Fragment with ID '${id}' not found` }],
             isError: true,
@@ -265,57 +324,71 @@ export async function handleMemoryUpdate(args) {
     }
     if (title !== undefined) {
         if (typeof title !== "string") {
+            logger.warn("memory_update validation failed", { reason: "title not string" });
             return {
                 content: [{ type: "text", text: "Error: 'title' must be a string" }],
                 isError: true,
             };
         }
+        logger.debug("memory_update updating_title", { id, new_title: title });
         memory[targetIndex].title = title;
     }
     if (fragment !== undefined) {
         if (typeof fragment !== "string") {
+            logger.warn("memory_update validation failed", { reason: "fragment not string" });
             return {
                 content: [{ type: "text", text: "Error: 'fragment' must be a string" }],
                 isError: true,
             };
         }
+        logger.debug("memory_update updating_fragment", { id });
         memory[targetIndex].fragment = fragment;
         memory[targetIndex].accessed++;
     }
     if (confidence !== undefined) {
         if (typeof confidence !== "number" || confidence < 0 || confidence > 1) {
+            logger.warn("memory_update validation failed", { reason: "confidence out of range", confidence });
             return {
                 content: [{ type: "text", text: "Error: 'confidence' must be a number between 0 and 1" }],
                 isError: true,
             };
         }
+        logger.debug("memory_update updating_confidence", { id, new_confidence: confidence });
         memory[targetIndex].confidence = confidence;
     }
+    logger.data("memory.json", "save", { reason: "update_fragment", id });
     core.saveMemory(memory);
     notifyMemoryChange();
+    logger.flow("memory_update", "complete", { id, title: memory[targetIndex].title });
     return {
         content: [{ type: "text", text: `Updated fragment [${id}]: "${memory[targetIndex].title}"` }],
     };
 }
 export async function handleMemoryForget(args) {
     const id = args?.id;
+    logger.flow("memory_forget", "start", { id });
     if (!id || typeof id !== "string") {
+        logger.warn("memory_forget validation failed", { reason: "missing or invalid id" });
         return {
             content: [{ type: "text", text: "Error: 'id' parameter is required and must be a string" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const initialLength = memory.length;
     const filtered = memory.filter((f) => f.id !== id);
     if (filtered.length === initialLength) {
+        logger.warn("memory_forget fragment not_found", { id });
         return {
             content: [{ type: "text", text: `Error: Fragment with ID '${id}' not found` }],
             isError: true,
         };
     }
+    logger.data("memory.json", "save", { reason: "forget_fragment", id, before: initialLength, after: filtered.length });
     core.saveMemory(filtered, { force: true });
     notifyMemoryChange();
+    logger.flow("memory_forget", "complete", { id });
     return {
         content: [{ type: "text", text: `Forgot fragment with ID: ${id}` }],
     };
@@ -323,21 +396,26 @@ export async function handleMemoryForget(args) {
 export async function handleMemoryFeedback(args) {
     const id = args?.id;
     const useful = args?.useful;
+    logger.flow("memory_feedback", "start", { id, useful });
     if (!id || typeof id !== "string") {
+        logger.warn("memory_feedback validation failed", { reason: "missing or invalid id" });
         return {
             content: [{ type: "text", text: "Error: 'id' parameter is required" }],
             isError: true,
         };
     }
     if (typeof useful !== "boolean") {
+        logger.warn("memory_feedback validation failed", { reason: "missing or invalid useful" });
         return {
             content: [{ type: "text", text: "Error: 'useful' parameter is required and must be a boolean" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const targetIndex = memory.findIndex((f) => f.id === id);
     if (targetIndex === -1) {
+        logger.warn("memory_feedback fragment not_found", { id });
         return {
             content: [{ type: "text", text: `Error: Fragment with ID '${id}' not found` }],
             isError: true,
@@ -347,8 +425,10 @@ export async function handleMemoryFeedback(args) {
         const boosted = core.boostOnAccess(memory[targetIndex]);
         Object.assign(memory[targetIndex], boosted);
         memory[targetIndex].positive_feedback = (memory[targetIndex].positive_feedback || 0) + 1;
+        logger.data("memory.json", "save", { reason: "positive_feedback", id, new_confidence: memory[targetIndex].confidence?.toFixed(2) });
         core.saveMemory(memory);
         notifyMemoryChange();
+        logger.flow("memory_feedback", "complete_positive", { id, confidence: memory[targetIndex].confidence?.toFixed(2) });
         return {
             content: [{ type: "text", text: `Positive feedback recorded for [${id}]. Confidence boosted to ${memory[targetIndex].confidence.toFixed(2)}.` }],
         };
@@ -357,8 +437,10 @@ export async function handleMemoryFeedback(args) {
         const penalized = core.recordNegativeHit(memory[targetIndex]);
         Object.assign(memory[targetIndex], penalized);
         memory[targetIndex].negative_feedback = (memory[targetIndex].negative_feedback || 0) + 1;
+        logger.data("memory.json", "save", { reason: "negative_feedback", id, new_confidence: memory[targetIndex].confidence?.toFixed(2) });
         core.saveMemory(memory);
         notifyMemoryChange();
+        logger.flow("memory_feedback", "complete_negative", { id, confidence: memory[targetIndex].confidence?.toFixed(2) });
         return {
             content: [{ type: "text", text: `Negative feedback recorded for [${id}]. Confidence reduced to ${memory[targetIndex].confidence.toFixed(2)}.` }],
         };
@@ -369,38 +451,47 @@ export async function handleMemoryMerge(args) {
     const title = args?.title;
     const fragment = args?.fragment;
     const project = args?.project === undefined ? null : args.project;
+    logger.flow("memory_merge", "start", { ids, title, project });
     if (!ids || !Array.isArray(ids) || ids.length < 2) {
+        logger.warn("memory_merge validation failed", { reason: "ids must be array with at least 2 elements" });
         return {
             content: [{ type: "text", text: "Error: 'ids' must be an array with at least 2 fragment IDs" }],
             isError: true,
         };
     }
     if (!title || typeof title !== "string") {
+        logger.warn("memory_merge validation failed", { reason: "title required" });
         return {
             content: [{ type: "text", text: "Error: 'title' is required and must be a string" }],
             isError: true,
         };
     }
     if (!fragment || typeof fragment !== "string") {
+        logger.warn("memory_merge validation failed", { reason: "fragment required" });
         return {
             content: [{ type: "text", text: "Error: 'fragment' is required and must be a string" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const notFound = ids.filter((id) => !memory.find((f) => f.id === id));
     if (notFound.length > 0) {
+        logger.warn("memory_merge fragments not_found", { missing: notFound });
         return {
             content: [{ type: "text", text: `Error: Fragment(s) not found: ${notFound.join(", ")}` }],
             isError: true,
         };
     }
     const newFragment = core.createFragment(fragment, "ai", title, project);
+    logger.flow("memory_merge", "merged_fragment_created", { new_id: newFragment.id, title });
     memory.push(newFragment);
     const mergedMemory = memory.filter((f) => !ids.includes(f.id));
+    logger.data("memory.json", "save", { reason: "merge_fragments", new_id: newFragment.id, removed_ids: ids, before: memory.length, after: mergedMemory.length });
     core.saveMemory(mergedMemory);
     notifyMemoryChange();
     const scopeInfo = newFragment.project ? ` (project: ${newFragment.project})` : " (global)";
+    logger.flow("memory_merge", "complete", { new_id: newFragment.id, merged_count: ids.length });
     return {
         content: [{ type: "text", text: `Merged ${ids.length} fragments into [${newFragment.id}]${scopeInfo}: "${newFragment.title}"\nRemoved IDs: ${ids.join(", ")}` }],
     };
@@ -410,7 +501,9 @@ export async function handleMemoryRelate(args) {
     const targetId = args?.targetId;
     const type = args?.type;
     const note = args?.note;
+    logger.flow("memory_relate", "start", { sourceId, targetId, type, has_note: !!note });
     if (!sourceId || !targetId || !type) {
+        logger.warn("memory_relate validation failed", { reason: "missing required params" });
         return {
             content: [{ type: "text", text: "Error: 'sourceId', 'targetId', and 'type' parameters are required" }],
             isError: true,
@@ -418,25 +511,30 @@ export async function handleMemoryRelate(args) {
     }
     const validTypes = ["contradicts", "supersedes", "supports", "related_to"];
     if (!validTypes.includes(type)) {
+        logger.warn("memory_relate validation failed", { reason: "invalid type", type });
         return {
             content: [{ type: "text", text: `Error: 'type' must be one of: ${validTypes.join(", ")}` }],
             isError: true,
         };
     }
     if (sourceId === targetId) {
+        logger.warn("memory_relate validation failed", { reason: "sourceId equals targetId" });
         return {
             content: [{ type: "text", text: "Error: sourceId and targetId cannot be the same" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     if (!memory.find((f) => f.id === sourceId)) {
+        logger.warn("memory_relate source not_found", { sourceId });
         return {
             content: [{ type: "text", text: `Error: Source fragment [${sourceId}] not found` }],
             isError: true,
         };
     }
     if (!memory.find((f) => f.id === targetId)) {
+        logger.warn("memory_relate target not_found", { targetId });
         return {
             content: [{ type: "text", text: `Error: Target fragment [${targetId}] not found` }],
             isError: true,
@@ -444,13 +542,16 @@ export async function handleMemoryRelate(args) {
     }
     const success = core.addRelation(memory, sourceId, targetId, type, note || undefined);
     if (!success) {
+        logger.warn("memory_relate relation_exists", { sourceId, targetId, type });
         return {
             content: [{ type: "text", text: `Relation already exists between [${sourceId}] and [${targetId}] with type '${type}'` }],
             isError: true,
         };
     }
+    logger.data("memory.json", "save", { reason: "add_relation", sourceId, targetId, type });
     core.saveMemory(memory);
     notifyMemoryChange();
+    logger.flow("memory_relate", "complete", { sourceId, targetId, type });
     return {
         content: [{ type: "text", text: `Created relation: [${sourceId}] --${type}--> [${targetId}]${note ? ` (${note})` : ""}` }],
     };
@@ -459,16 +560,21 @@ export async function handleGuideGet(args) {
     const category = args?.category || null;
     const guideName = args?.guide || null;
     const task = args?.task || null;
+    logger.flow("guide_get", "start", { category, guide: guideName, task });
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     if (task) {
         const result = guides.suggestGuides(task, allGuides);
+        logger.flow("guide_get", "task_suggestions", { task, relevant: result.relevant.length, suggested: result.suggested.length });
         const formatted = guides.formatSuggestions(result);
         return {
             content: [{ type: "text", text: formatted }],
         };
     }
     if (guideName) {
+        logger.flow("guide_get", "single_guide_lookup", { guide: guideName });
         const guide = guides.findGuide(allGuides, guideName);
+        logger.flow("guide_get", "complete_single", { guide: guideName, found: !!guide });
         return {
             content: [{ type: "text", text: guides.formatGuideDetail(guide) }],
         };
@@ -476,6 +582,7 @@ export async function handleGuideGet(args) {
     const filtered = category
         ? guides.getGuidesByCategory(allGuides, category)
         : allGuides;
+    logger.flow("guide_get", "complete_list", { category, total: allGuides.length, filtered: filtered.length });
     const formatted = guides.formatGuidesForLLM(filtered);
     return {
         content: [{ type: "text", text: formatted }],
@@ -487,15 +594,21 @@ export async function handleGuidePractice(args) {
     const description = args?.description || "";
     const contexts = args?.contexts || [];
     const learnings = args?.learnings || [];
+    logger.flow("guide_practice", "start", { guide: guideName, category, outcome: args?.outcome, context_count: contexts.length, learning_count: learnings.length });
     if (!guideName || !category) {
+        logger.warn("guide_practice validation failed", { reason: "missing guide or category" });
         return {
             content: [{ type: "text", text: "Error: 'guide' and 'category' parameters are required" }],
             isError: true,
         };
     }
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
+    const preUsageCount = guides.findGuide(allGuides, guideName)?.usage_count || 0;
     const updated = guides.practiceGuide(allGuides, guideName, category, description, contexts, learnings, args?.outcome);
+    logger.flow("guide_practice", "guide_updated", { guide: guideName, usage_before: preUsageCount, usage_after: updated.usage_count });
     if (activeSessionId) {
+        logger.data("sessions.json", "load");
         const allSessions = sessions.loadSessions();
         const session = sessions.findSession(allSessions, activeSessionId);
         if (session) {
@@ -504,13 +617,16 @@ export async function handleGuidePractice(args) {
             if (!session.guides_used.includes(guideName.toLowerCase())) {
                 session.guides_used.push(guideName.toLowerCase());
             }
+            logger.data("sessions.json", "save", { reason: "track_guide_practice", session_id: activeSessionId, guide: guideName });
             sessions.saveSessions(allSessions);
         }
     }
+    logger.data("guides.json", "save", { reason: "practice_guide", guide: guideName });
     guides.saveGuides(allGuides);
     const isNew = updated.usage_count === 1;
     const action = isNew ? "Created" : "Updated";
     const response = `${action} guide "${updated.guide}" (${updated.category}): ${updated.usage_count}x usage, ${updated.learnings.length} learnings, ${updated.contexts.length} contexts`;
+    logger.flow("guide_practice", "complete", { guide: guideName, action, usage_count: updated.usage_count });
     return {
         content: [{ type: "text", text: response }],
     };
@@ -521,16 +637,21 @@ export async function handleGuideCreate(args) {
     const description = args?.description;
     const contexts = args?.contexts || [];
     const learnings = args?.learnings || [];
+    logger.flow("guide_create", "start", { guide: guideName, category, has_description: !!description });
     if (!guideName || !category || !description) {
+        logger.warn("guide_create validation failed", { reason: "missing guide, category, or description" });
         return {
             content: [{ type: "text", text: "Error: 'guide', 'category', and 'description' parameters are required" }],
             isError: true,
         };
     }
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const existing = guides.findSimilarGuide(allGuides, guideName);
     if (existing) {
+        logger.flow("guide_create", "updating_existing", { guide: guideName, existing_id: existing.guide });
         existing.description = description;
+        logger.data("guides.json", "save", { reason: "update_existing_guide", guide: guideName });
         guides.saveGuides(allGuides);
         return {
             content: [{ type: "text", text: `Updated manual for existing guide "${existing.guide}" (${existing.category})` }],
@@ -538,7 +659,9 @@ export async function handleGuideCreate(args) {
     }
     const newGuide = guides.createGuide(guideName, category, description, contexts, learnings);
     allGuides.push(newGuide);
+    logger.data("guides.json", "save", { reason: "create_new_guide", guide: guideName, total: allGuides.length });
     guides.saveGuides(allGuides);
+    logger.flow("guide_create", "complete", { guide: guideName, category, is_new: true });
     return {
         content: [{ type: "text", text: `Created new guide "${newGuide.guide}" (${newGuide.category}) with a detailed manual.` }],
     };
@@ -547,25 +670,33 @@ export async function handleGuideDistill(args) {
     const memoryId = args?.memory_id;
     const guideName = args?.guide;
     const category = args?.category || "dev-tool";
+    logger.flow("guide_distill", "start", { memory_id: memoryId, guide: guideName, category });
     if (!memoryId || !guideName) {
+        logger.warn("guide_distill validation failed", { reason: "missing memory_id or guide" });
         return {
             content: [{ type: "text", text: "Error: 'memory_id' and 'guide' parameters are required" }],
             isError: true,
         };
     }
+    logger.data("memory.json", "load");
     const allMemory = core.loadMemory();
     const fragment = allMemory.find((m) => m.id === memoryId);
     if (!fragment) {
+        logger.warn("guide_distill memory not_found", { memory_id: memoryId });
         return {
             content: [{ type: "text", text: `Error: Memory fragment with ID '${memoryId}' not found.` }],
             isError: true,
         };
     }
+    logger.flow("guide_distill", "fragment_found", { memory_id: memoryId, title: fragment.title });
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const updated = guides.promoteToGuide(allGuides, guideName, category, fragment.fragment, fragment.project || "global");
+    logger.data("guides.json", "save", { reason: "distill_memory_to_guide", memory_id: memoryId, guide: guideName });
     guides.saveGuides(allGuides);
     let response = `Successfully distilled memory [${memoryId}] into guide "${updated.guide}" (${updated.category}).\n\n`;
     response += guides.formatGuideDetail(updated);
+    logger.flow("guide_distill", "complete", { memory_id: memoryId, guide: guideName, category });
     return {
         content: [{ type: "text", text: response }],
     };
@@ -581,42 +712,55 @@ export async function handleGuideUpdate(args) {
         superseded_by: args?.superseded_by,
         deprecated: args?.deprecated,
     };
+    const fieldsToUpdate = Object.entries(updates).filter(([, v]) => v !== undefined).map(([k]) => k);
+    logger.flow("guide_update", "start", { guide: guideName, fields: fieldsToUpdate });
     if (!guideName) {
+        logger.warn("guide_update validation failed", { reason: "missing guide name" });
         return {
             content: [{ type: "text", text: "Error: 'guide' parameter is required" }],
             isError: true,
         };
     }
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const updated = guides.updateGuide(allGuides, guideName, updates);
     if (!updated) {
+        logger.warn("guide_update guide not_found", { guide: guideName });
         return {
             content: [{ type: "text", text: `Error: Guide "${guideName}" not found.` }],
             isError: true,
         };
     }
+    logger.data("guides.json", "save", { reason: "update_guide", guide: guideName });
     guides.saveGuides(allGuides);
+    logger.flow("guide_update", "complete", { guide: guideName, updated_fields: fieldsToUpdate });
     return {
         content: [{ type: "text", text: `Updated guide "${updated.guide}":\n${guides.formatGuideDetail(updated)}` }],
     };
 }
 export async function handleGuideForget(args) {
     const guideName = args?.guide;
+    logger.flow("guide_forget", "start", { guide: guideName });
     if (!guideName) {
+        logger.warn("guide_forget validation failed", { reason: "missing guide name" });
         return {
             content: [{ type: "text", text: "Error: 'guide' parameter is required" }],
             isError: true,
         };
     }
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const success = guides.deleteGuide(allGuides, guideName);
     if (!success) {
+        logger.warn("guide_forget guide not_found", { guide: guideName });
         return {
             content: [{ type: "text", text: `Error: Guide "${guideName}" not found.` }],
             isError: true,
         };
     }
+    logger.data("guides.json", "save", { reason: "forget_guide", guide: guideName, remaining: allGuides.length });
     guides.saveGuides(allGuides, { force: true });
+    logger.flow("guide_forget", "complete", { guide: guideName });
     return {
         content: [{ type: "text", text: `Successfully forgot guide: ${guideName}` }],
     };
@@ -628,18 +772,22 @@ export async function handleGuideMerge(args) {
     const description = args?.description || "";
     let contexts = args?.contexts;
     let learnings = args?.learnings;
+    logger.flow("guide_merge", "start", { guides: guideNames, new_guide: newGuideName, category });
     if (!guideNames || !Array.isArray(guideNames) || guideNames.length < 2) {
+        logger.warn("guide_merge validation failed", { reason: "guides must be array with at least 2 elements" });
         return {
             content: [{ type: "text", text: "Error: 'guides' must be an array with at least 2 guide names" }],
             isError: true,
         };
     }
     if (!newGuideName || !category) {
+        logger.warn("guide_merge validation failed", { reason: "missing guide name or category" });
         return {
             content: [{ type: "text", text: "Error: 'guide' and 'category' parameters are required" }],
             isError: true,
         };
     }
+    logger.data("guides.json", "load");
     const allGuides = guides.loadGuides();
     const sourceGuides = [];
     const notFound = [];
@@ -653,6 +801,7 @@ export async function handleGuideMerge(args) {
         }
     }
     if (notFound.length > 0) {
+        logger.warn("guide_merge guides not_found", { missing: notFound });
         return {
             content: [{ type: "text", text: `Error: Guide(s) not found: ${notFound.join(", ")}` }],
             isError: true,
@@ -667,39 +816,50 @@ export async function handleGuideMerge(args) {
     const antiPatterns = [...new Set(sourceGuides.flatMap((g) => g.anti_patterns || []))];
     const pitfalls = [...new Set(sourceGuides.flatMap((g) => g.known_pitfalls || []))];
     const totalUsage = sourceGuides.reduce((sum, g) => sum + g.usage_count, 0);
+    logger.flow("guide_merge", "source_stats", { source_count: sourceGuides.length, total_usage: totalUsage });
     const newGuide = guides.createGuide(newGuideName, category, description, contexts, learnings);
     newGuide.usage_count = totalUsage;
     newGuide.anti_patterns = antiPatterns;
     newGuide.known_pitfalls = pitfalls;
     allGuides.push(newGuide);
     const mergedGuides = allGuides.filter((g) => !guideNames.map((n) => n.toLowerCase()).includes(g.guide));
+    logger.data("guides.json", "save", { reason: "merge_guides", new_guide: newGuideName, removed: guideNames, total_usage: totalUsage });
     guides.saveGuides(mergedGuides);
     let response = `Merged ${guideNames.length} guides into "${newGuide.guide}" (${newGuide.category})\n`;
     response += `Total usage: ${totalUsage}x | Contexts: ${contexts.length} | Learnings: ${learnings.length}\n`;
     response += `Removed: ${guideNames.join(", ")}`;
+    logger.flow("guide_merge", "complete", { new_guide: newGuideName, merged_count: guideNames.length, total_usage: totalUsage });
     return {
         content: [{ type: "text", text: response }],
     };
 }
 export async function handleMemoryStats(args) {
     const project = args?.project || null;
+    logger.flow("memory_stats", "start", { project });
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const stats = core.calculateStats(memory, project);
+    logger.flow("memory_stats", "complete", { project, total: stats.total, avg_confidence: stats.avg_confidence?.toFixed(2) });
     return {
         content: [{ type: "text", text: core.formatStats(stats) }],
     };
 }
 export async function handleMemoryAudit(_args) {
+    logger.flow("memory_audit", "start");
+    logger.data("memory.json", "load");
     const memory = core.loadMemory();
     const result = core.auditMemory(memory);
+    logger.flow("memory_audit", "complete", { issues_count: result.issues?.length || 0 });
     return {
         content: [{ type: "text", text: core.formatAuditReport(result) }],
     };
 }
 export async function handleSessionStats(args) {
     const count = args?.count || 10;
+    logger.flow("session_stats", "start", { count });
     const recentSessions = virtualSession.getRecentSessions(count);
     const current = virtualSession.getCurrentVirtualSession();
+    logger.debug("session_stats data", { requested: count, recent_count: recentSessions.length, has_current: !!current });
     let output = `## Session Stats\n`;
     if (current) {
         output += `Active session: ${current.tool_calls.length} tool calls\n`;
@@ -721,60 +881,127 @@ export async function handleSessionStats(args) {
     else {
         output += `No past sessions recorded yet.\n`;
     }
+    logger.flow("session_stats", "complete", { count, recent_count: recentSessions.length, has_current: !!current });
     return { content: [{ type: "text", text: output }] };
 }
 export async function handleCallTool(request) {
     const { name, arguments: args } = request.params;
+    logger.request(name, args);
+    const startTime = Date.now();
     try {
         switch (name) {
-            case "session_start":
-                return await handleSessionStart(args);
-            case "session_end":
-                return await handleSessionEnd(args);
-            case "memory_read":
-                return await handleMemoryRead(args);
-            case "memory_add":
-                return await handleMemoryAdd(args);
-            case "memory_update":
-                return await handleMemoryUpdate(args);
-            case "memory_forget":
-                return await handleMemoryForget(args);
-            case "memory_feedback":
-                return await handleMemoryFeedback(args);
-            case "memory_merge":
-                return await handleMemoryMerge(args);
-            case "memory_relate":
-                return await handleMemoryRelate(args);
-            case "memory_stats":
-                return await handleMemoryStats(args);
-            case "memory_audit":
-                return await handleMemoryAudit(args);
-            case "guide_get":
-                return await handleGuideGet(args);
-            case "guide_practice":
-                return await handleGuidePractice(args);
-            case "guide_create":
-                return await handleGuideCreate(args);
-            case "guide_distill":
-                return await handleGuideDistill(args);
-            case "guide_update":
-                return await handleGuideUpdate(args);
-            case "guide_forget":
-                return await handleGuideForget(args);
-            case "guide_merge":
-                return await handleGuideMerge(args);
-            case "session_stats":
-                return await handleSessionStats(args);
-            default:
-                return {
+            case "session_start": {
+                const result = await handleSessionStart(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "session_end": {
+                const result = await handleSessionEnd(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_read": {
+                const result = await handleMemoryRead(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_add": {
+                const result = await handleMemoryAdd(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_update": {
+                const result = await handleMemoryUpdate(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_forget": {
+                const result = await handleMemoryForget(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_feedback": {
+                const result = await handleMemoryFeedback(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_merge": {
+                const result = await handleMemoryMerge(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_relate": {
+                const result = await handleMemoryRelate(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_stats": {
+                const result = await handleMemoryStats(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "memory_audit": {
+                const result = await handleMemoryAudit(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_get": {
+                const result = await handleGuideGet(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_practice": {
+                const result = await handleGuidePractice(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_create": {
+                const result = await handleGuideCreate(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_distill": {
+                const result = await handleGuideDistill(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_update": {
+                const result = await handleGuideUpdate(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_forget": {
+                const result = await handleGuideForget(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "guide_merge": {
+                const result = await handleGuideMerge(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            case "session_stats": {
+                const result = await handleSessionStats(args);
+                logger.response(name, !!result.isError, Date.now() - startTime);
+                return result;
+            }
+            default: {
+                logger.warn("handleCallTool unknown_tool", { tool: name });
+                const result = {
                     content: [{ type: "text", text: `Error: Unknown tool '${name}'` }],
                     isError: true,
                 };
+                logger.response(name, true, Date.now() - startTime);
+                return result;
+            }
         }
     }
     catch (error) {
+        const err = error;
+        logger.error("handleCallTool exception", { tool: name, error: err.message });
+        logger.response(name, true, Date.now() - startTime, { error: err.message });
         return {
-            content: [{ type: "text", text: `Error: ${error.message}` }],
+            content: [{ type: "text", text: `Error: ${err.message}` }],
             isError: true,
         };
     }