mcp-learning-memory 0.2.0

package/dist/tools.js

@@ -0,0 +1,559 @@
+/**
+ * Tool implementations for MCP server
+ */
+import { loadMemory, saveMemory } from './storage.js';
+import { validateInsightInput, normalizeTags, generateId, levenshteinDistance, validateListIndexParams, validateSearchQuery, } from './validation.js';
+import { log } from './logger.js';
+// Simple mutex to prevent concurrent read-modify-write races
+class Mutex {
+    locked = false;
+    queue = [];
+    async acquire() {
+        if (!this.locked) {
+            this.locked = true;
+            return;
+        }
+        await new Promise(resolve => this.queue.push(resolve));
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this.locked = false;
+        }
+    }
+    async runExclusive(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+const memoryMutex = new Mutex();
+/**
+ * Calculate trust score based on helpful and harmful feedback
+ * Formula: (helpful - harmful * 2) / (helpful + harmful + 1)
+ */
+function calculateTrustScore(helpful, harmful) {
+    return Number(((helpful - harmful * 2) / (helpful + harmful + 1)).toFixed(2));
+}
+export async function addInsight(title, tags, content, overwrite = false, sourceUrl) {
+    try {
+        // Validate input
+        const validationError = validateInsightInput(title, tags, content, sourceUrl);
+        if (validationError) {
+            return {
+                success: false,
+                message: validationError,
+            };
+        }
+        // Normalize tags and title
+        const normalizedTags = normalizeTags(tags);
+        const trimmedTitle = title.trim();
+        let resultId = '';
+        let wasOverwritten = false;
+        // Load, update, and save memory with mutex protection
+        await memoryMutex.runExclusive(async () => {
+            const memory = await loadMemory();
+            // Check for duplicate or similar title using Levenshtein distance
+            let existingIndex = -1;
+            let similarTitle = '';
+            for (let i = 0; i < memory.insights.length; i++) {
+                const insight = memory.insights[i];
+                const isExactMatch = insight.title.toLowerCase() === trimmedTitle.toLowerCase();
+                // For very short titles (< 3 chars), only check exact match to avoid false positives
+                // For longer titles (>= 3 chars), use Levenshtein distance < 3 (catches typos)
+                // Examples: "Bug Fix" → "Bux Fix" (distance=2), "Test" → "Fest" (distance=1)
+                const minLength = Math.min(insight.title.length, trimmedTitle.length);
+                let isSimilar = false;
+                if (isExactMatch) {
+                    isSimilar = true;
+                }
+                else if (minLength >= 3) {
+                    const distance = levenshteinDistance(insight.title, trimmedTitle);
+                    isSimilar = distance < 3;
+                }
+                if (isSimilar) {
+                    existingIndex = i;
+                    similarTitle = insight.title;
+                    break;
+                }
+            }
+            if (existingIndex !== -1) {
+                if (!overwrite) {
+                    const error = new Error(`Similar title found: "${similarTitle}" is too similar to "${trimmedTitle}". Use overwrite=true to replace.`);
+                    error.duplicate = true;
+                    error.existingId = memory.insights[existingIndex].id;
+                    error.existingTitle = similarTitle;
+                    throw error;
+                }
+                // Overwrite: keep ID and created date, update everything else
+                const existing = memory.insights[existingIndex];
+                existing.title = trimmedTitle;
+                existing.tags = normalizedTags;
+                existing.content = content.trim();
+                existing.lastUsed = new Date().toISOString();
+                existing.sourceUrl = sourceUrl?.trim();
+                resultId = existing.id;
+                wasOverwritten = true;
+            }
+            else {
+                // Calculate next ID number
+                let maxNum = 0;
+                for (const insight of memory.insights) {
+                    const match = insight.id.match(/^ace-(\d+)$/);
+                    if (match) {
+                        const num = parseInt(match[1], 10);
+                        if (num > maxNum)
+                            maxNum = num;
+                    }
+                }
+                const nextNum = maxNum + 1;
+                // Create new insight
+                const now = new Date().toISOString();
+                const insight = {
+                    id: generateId(nextNum),
+                    title: trimmedTitle,
+                    tags: normalizedTags,
+                    content: content.trim(),
+                    helpful: 0,
+                    harmful: 0,
+                    created: now,
+                    lastUsed: now,
+                    sourceUrl: sourceUrl?.trim(),
+                };
+                memory.insights.push(insight);
+                resultId = insight.id;
+            }
+            await saveMemory(memory);
+        });
+        log.info(`${wasOverwritten ? 'Updated' : 'Added'} insight: ${resultId}`);
+        return {
+            success: true,
+            message: wasOverwritten
+                ? `Insight updated successfully (ID: ${resultId})`
+                : `Insight added successfully with ID: ${resultId}`,
+            data: { id: resultId, overwritten: wasOverwritten },
+        };
+    }
+    catch (error) {
+        log.error('Error adding insight:', error);
+        // Check if this is a duplicate error
+        const err = error;
+        if (err.duplicate) {
+            return {
+                success: false,
+                message: err.message,
+                data: {
+                    duplicate: true,
+                    existingId: err.existingId,
+                    existingTitle: err.existingTitle,
+                },
+            };
+        }
+        return {
+            success: false,
+            message: `Failed to add insight: ${err.message}`,
+        };
+    }
+}
+export async function listIndex(params = {}) {
+    try {
+        // Validate parameters
+        const validationError = validateListIndexParams(params);
+        if (validationError) {
+            return {
+                success: false,
+                message: validationError,
+            };
+        }
+        const memory = await loadMemory();
+        // Normalize filter tags to lowercase for consistent matching
+        const filterTags = params.tags ? normalizeTags(params.tags) : undefined;
+        const minHelpful = params.minHelpful ?? 0;
+        const sortBy = params.sortBy ?? 'lastUsed';
+        const limit = params.limit ?? 50;
+        const PREVIEW_LIMIT = 100;
+        let index = memory.insights.map(insight => {
+            const trustScore = calculateTrustScore(insight.helpful, insight.harmful);
+            const entry = {
+                id: insight.id,
+                title: insight.title,
+                tags: insight.tags,
+                helpful: insight.helpful,
+                harmful: insight.harmful,
+                created: insight.created,
+                lastUsed: insight.lastUsed,
+                contentPreview: insight.content.substring(0, PREVIEW_LIMIT),
+                contentTruncated: insight.content.length > PREVIEW_LIMIT,
+                sourceUrl: insight.sourceUrl,
+                trustScore,
+            };
+            if (trustScore < 0) {
+                entry.warning = 'Low trust score';
+            }
+            return entry;
+        });
+        // Apply tag filters (AND logic - insight must have ALL filter tags)
+        if (filterTags && filterTags.length > 0) {
+            index = index.filter(insight => filterTags.every(filterTag => insight.tags.some(insightTag => insightTag === filterTag)));
+        }
+        // Apply minHelpful filter
+        if (minHelpful > 0) {
+            index = index.filter(insight => insight.helpful >= minHelpful);
+        }
+        // Sort by specified field
+        if (sortBy === 'created') {
+            index.sort((a, b) => new Date(b.created).getTime() - new Date(a.created).getTime());
+        }
+        else if (sortBy === 'helpful') {
+            index.sort((a, b) => b.helpful - a.helpful);
+        }
+        else {
+            // Default: sort by lastUsed
+            index.sort((a, b) => new Date(b.lastUsed).getTime() - new Date(a.lastUsed).getTime());
+        }
+        // Apply limit
+        const totalResults = index.length;
+        index = index.slice(0, limit);
+        const isFiltered = filterTags !== undefined || minHelpful > 0;
+        const isLimited = totalResults > index.length;
+        let message;
+        if (isFiltered && isLimited) {
+            message = `Found ${totalResults} insights (filtered, showing ${index.length})`;
+        }
+        else if (isFiltered) {
+            message = `Found ${totalResults} insights (filtered)`;
+        }
+        else if (isLimited) {
+            message = `Found ${totalResults} insights (showing ${index.length})`;
+        }
+        else {
+            message = `Found ${index.length} insights`;
+        }
+        return {
+            success: true,
+            message,
+            data: index,
+        };
+    }
+    catch (error) {
+        log.error('Error listing index:', error);
+        return {
+            success: false,
+            message: `Failed to list index: ${error.message}`,
+        };
+    }
+}
+export async function getDetail(id) {
+    try {
+        let insightData;
+        // Load, update, and save memory with mutex protection
+        await memoryMutex.runExclusive(async () => {
+            const memory = await loadMemory();
+            const insight = memory.insights.find(i => i.id === id);
+            if (!insight) {
+                return;
+            }
+            // Update lastUsed timestamp on every access
+            // NOTE: This writes to disk on every getDetail call. For current requirements
+            // (< 10 ops/min, single user) this is acceptable. For high-frequency access,
+            // consider adding debounce or batching lastUsed updates.
+            insight.lastUsed = new Date().toISOString();
+            await saveMemory(memory);
+            insightData = insight;
+        });
+        if (!insightData) {
+            return {
+                success: false,
+                message: `Insight not found: ${id}`,
+            };
+        }
+        return {
+            success: true,
+            message: 'Insight retrieved successfully',
+            data: insightData,
+        };
+    }
+    catch (error) {
+        log.error('Error getting detail:', error);
+        return {
+            success: false,
+            message: `Failed to get detail: ${error.message}`,
+        };
+    }
+}
+export async function markHelpful(id) {
+    try {
+        let helpfulCount = 0;
+        let found = false;
+        // Load, update, and save memory with mutex protection
+        await memoryMutex.runExclusive(async () => {
+            const memory = await loadMemory();
+            const insight = memory.insights.find(i => i.id === id);
+            if (!insight) {
+                return;
+            }
+            insight.helpful += 1;
+            // Update lastUsed on feedback (acceptable for current load)
+            insight.lastUsed = new Date().toISOString();
+            await saveMemory(memory);
+            helpfulCount = insight.helpful;
+            found = true;
+        });
+        if (!found) {
+            return {
+                success: false,
+                message: `Insight not found: ${id}`,
+            };
+        }
+        log.info(`Marked helpful: ${id}`);
+        return {
+            success: true,
+            message: `Insight marked as helpful (count: ${helpfulCount})`,
+            data: { helpful: helpfulCount },
+        };
+    }
+    catch (error) {
+        log.error('Error marking helpful:', error);
+        return {
+            success: false,
+            message: `Failed to mark helpful: ${error.message}`,
+        };
+    }
+}
+export async function markHarmful(id) {
+    try {
+        let harmfulCount = 0;
+        let found = false;
+        // Load, update, and save memory with mutex protection
+        await memoryMutex.runExclusive(async () => {
+            const memory = await loadMemory();
+            const insight = memory.insights.find(i => i.id === id);
+            if (!insight) {
+                return;
+            }
+            insight.harmful += 1;
+            // Update lastUsed on feedback (acceptable for current load)
+            insight.lastUsed = new Date().toISOString();
+            await saveMemory(memory);
+            harmfulCount = insight.harmful;
+            found = true;
+        });
+        if (!found) {
+            return {
+                success: false,
+                message: `Insight not found: ${id}`,
+            };
+        }
+        log.info(`Marked harmful: ${id}`);
+        return {
+            success: true,
+            message: `Insight marked as harmful (count: ${harmfulCount})`,
+            data: { harmful: harmfulCount },
+        };
+    }
+    catch (error) {
+        log.error('Error marking harmful:', error);
+        return {
+            success: false,
+            message: `Failed to mark harmful: ${error.message}`,
+        };
+    }
+}
+export async function searchInsights(query, limit = 5) {
+    try {
+        // Validate query
+        const validationError = validateSearchQuery(query);
+        if (validationError) {
+            return {
+                success: false,
+                message: validationError,
+            };
+        }
+        const memory = await loadMemory();
+        // Normalize query
+        const normalizedQuery = query.trim().toLowerCase();
+        // Score each insight
+        const PREVIEW_LIMIT = 100;
+        const scoredInsights = memory.insights.map(insight => {
+            let baseScore = 0;
+            const normalizedTitle = insight.title.toLowerCase();
+            const normalizedContent = insight.content.toLowerCase();
+            // Title scoring
+            if (normalizedTitle === normalizedQuery) {
+                baseScore += 10; // Exact match in title
+            }
+            else if (normalizedTitle.includes(normalizedQuery)) {
+                baseScore += 5; // Partial match in title
+            }
+            // Content scoring
+            if (normalizedContent.includes(normalizedQuery)) {
+                baseScore += 3; // Match in content
+            }
+            // Tags scoring
+            // Note: tags are already normalized to lowercase during storage
+            for (const tag of insight.tags) {
+                if (tag.includes(normalizedQuery)) {
+                    baseScore += 2; // Match in tag
+                }
+            }
+            // Helpful count bonus
+            baseScore += insight.helpful;
+            // Recent usage bonus (within 7 days)
+            const lastUsedDate = new Date(insight.lastUsed);
+            const now = new Date();
+            const daysDiff = (now.getTime() - lastUsedDate.getTime()) / (1000 * 60 * 60 * 24);
+            if (daysDiff >= 0 && daysDiff <= 7) {
+                baseScore += 3;
+            }
+            // Calculate trust score and add to ranking
+            const trustScore = calculateTrustScore(insight.helpful, insight.harmful);
+            baseScore += trustScore * 5;
+            // Apply decay factor based on days since last used
+            // Decay from 1.0 to 0.1 over 90 days
+            const daysSinceUsed = Math.max(0, daysDiff);
+            const decayFactor = Math.max(0.1, 1 - daysSinceUsed / 90);
+            const effectiveScore = baseScore * decayFactor;
+            const entry = {
+                id: insight.id,
+                title: insight.title,
+                tags: insight.tags,
+                helpful: insight.helpful,
+                harmful: insight.harmful,
+                created: insight.created,
+                lastUsed: insight.lastUsed,
+                contentPreview: insight.content.substring(0, PREVIEW_LIMIT),
+                contentTruncated: insight.content.length > PREVIEW_LIMIT,
+                sourceUrl: insight.sourceUrl,
+                trustScore,
+                score: effectiveScore,
+            };
+            if (trustScore < 0) {
+                entry.warning = 'Low trust score';
+            }
+            return entry;
+        });
+        // Filter insights with score > 0
+        const matchedInsights = scoredInsights.filter(insight => insight.score > 0);
+        // Sort by score descending
+        matchedInsights.sort((a, b) => b.score - a.score);
+        // Apply limit
+        const limitedInsights = matchedInsights.slice(0, limit);
+        // Remove score field before returning
+        const results = limitedInsights.map(({ score, ...rest }) => rest);
+        if (results.length === 0) {
+            return {
+                success: true,
+                message: `No insights found matching query: "${query}"`,
+                data: [],
+            };
+        }
+        return {
+            success: true,
+            message: `Found ${results.length} insights matching query: "${query}"`,
+            data: results,
+        };
+    }
+    catch (error) {
+        log.error('Error searching insights:', error);
+        return {
+            success: false,
+            message: `Failed to search insights: ${error.message}`,
+        };
+    }
+}
+export async function deleteInsight(id) {
+    try {
+        let found = false;
+        // Load, update, and save memory with mutex protection
+        await memoryMutex.runExclusive(async () => {
+            const memory = await loadMemory();
+            const index = memory.insights.findIndex(i => i.id === id);
+            if (index === -1) {
+                return;
+            }
+            memory.insights.splice(index, 1);
+            await saveMemory(memory);
+            found = true;
+        });
+        if (!found) {
+            return {
+                success: false,
+                message: 'Insight not found',
+            };
+        }
+        log.info(`Deleted insight: ${id}`);
+        return {
+            success: true,
+            message: `Deleted ${id}`,
+        };
+    }
+    catch (error) {
+        log.error('Error deleting insight:', error);
+        return {
+            success: false,
+            message: `Failed to delete insight: ${error.message}`,
+        };
+    }
+}
+export async function exportMemory(format = 'json') {
+    try {
+        const memory = await loadMemory();
+        let data;
+        if (format === 'markdown') {
+            // Format as readable markdown
+            const lines = [
+                '# Learning Memory Export',
+                '',
+                `> Exported: ${new Date().toISOString()}`,
+                `> Total insights: ${memory.insights.length}`,
+                '',
+                '---',
+                '',
+            ];
+            for (const insight of memory.insights) {
+                const trustScore = calculateTrustScore(insight.helpful, insight.harmful);
+                lines.push(`## ${insight.title}`);
+                lines.push('');
+                lines.push(`**ID:** ${insight.id}`);
+                lines.push(`**Tags:** ${insight.tags.join(', ')}`);
+                lines.push(`**Stats:** Helpful ${insight.helpful} / Harmful ${insight.harmful} (Trust: ${trustScore})`);
+                lines.push(`**Created:** ${insight.created}`);
+                lines.push(`**Last Used:** ${insight.lastUsed}`);
+                if (insight.sourceUrl) {
+                    lines.push(`**Source:** ${insight.sourceUrl}`);
+                }
+                lines.push('');
+                lines.push('### Content');
+                lines.push('');
+                lines.push(insight.content);
+                lines.push('');
+                lines.push('---');
+                lines.push('');
+            }
+            data = lines.join('\n');
+        }
+        else {
+            // Format as JSON
+            data = JSON.stringify(memory, null, 2);
+        }
+        return {
+            success: true,
+            message: `Exported ${memory.insights.length} insights as ${format}`,
+            data: { data, count: memory.insights.length },
+        };
+    }
+    catch (error) {
+        log.error('Error exporting memory:', error);
+        return {
+            success: false,
+            message: `Failed to export memory: ${error.message}`,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Core data structures for ACE Flash Memory MCP
+ */
+export interface Insight {
+    id: string;
+    title: string;
+    tags: string[];
+    content: string;
+    helpful: number;
+    harmful: number;
+    created: string;
+    lastUsed: string;
+    sourceUrl?: string;
+}
+export interface Memory {
+    insights: Insight[];
+}
+export interface IndexEntry {
+    id: string;
+    title: string;
+    tags: string[];
+    helpful: number;
+    harmful: number;
+    created: string;
+    lastUsed: string;
+    contentPreview: string;
+    contentTruncated: boolean;
+    sourceUrl?: string;
+    trustScore: number;
+    warning?: string;
+}
+export interface ToolResponse {
+    success: boolean;
+    message: string;
+    data?: unknown;
+}
+export interface ListIndexParams {
+    tags?: string[];
+    minHelpful?: number;
+    sortBy?: 'created' | 'lastUsed' | 'helpful';
+    limit?: number;
+}
+export interface SearchInsightsParams {
+    query: string;
+    limit?: number;
+}
+export interface ScoredInsight extends IndexEntry {
+    score: number;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core data structures for ACE Flash Memory MCP
+ */
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Input validation and normalization
+ */
+export declare const LIMITS: {
+    readonly TITLE_MAX: 200;
+    readonly TAGS_MAX: 10;
+    readonly TAG_LENGTH_MAX: 50;
+    readonly CONTENT_MAX: 10000;
+    readonly SOURCE_URL_MAX: 2000;
+};
+export declare function validateInsightInput(title: string, tags: string[], content: string, sourceUrl?: string): string | null;
+export declare function normalizeTags(tags: string[]): string[];
+export declare function generateId(nextNumber: number): string;
+/**
+ * Calculate Levenshtein distance between two strings (case-insensitive)
+ * Used for detecting similar titles in auto-deduplication
+ */
+export declare function levenshteinDistance(str1: string, str2: string): number;
+/**
+ * Validate parameters for list_index tool
+ */
+export declare function validateListIndexParams(params: {
+    tags?: string[];
+    minHelpful?: number;
+    sortBy?: string;
+    limit?: number;
+}): string | null;
+/**
+ * Validate search query for search_insights tool
+ */
+export declare function validateSearchQuery(query: string): string | null;