@telvok/librarian-mcp 1.5.3 → 2.0.0

package/dist/library 2/manager.js

@@ -0,0 +1,218 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { glob } from 'glob';
+import { v4 as uuidv4 } from 'uuid';
+import { getLibraryPath, getLocalPath, getImportedPath, getArchivedPath, } from './storage.js';
+// ============================================================================
+// Library Manager
+// ============================================================================
+export class LibraryManager {
+    libraryPath;
+    constructor() {
+        this.libraryPath = getLibraryPath();
+    }
+    /**
+     * Initialize the library directory structure.
+     */
+    async initialize() {
+        const dirs = [
+            getLocalPath(this.libraryPath),
+            getImportedPath(this.libraryPath),
+            getArchivedPath(this.libraryPath),
+        ];
+        for (const dir of dirs) {
+            await fs.mkdir(dir, { recursive: true });
+        }
+    }
+    /**
+     * Get all entries from local library.
+     */
+    async getLocalEntries() {
+        const localPath = getLocalPath(this.libraryPath);
+        return this.readEntriesFromPath(localPath, 'local');
+    }
+    /**
+     * Get all entries from imported libraries.
+     */
+    async getImportedEntries() {
+        const importedPath = getImportedPath(this.libraryPath);
+        return this.readEntriesFromPath(importedPath, 'imported');
+    }
+    /**
+     * Get all archived entries.
+     */
+    async getArchivedEntries() {
+        const archivedPath = getArchivedPath(this.libraryPath);
+        return this.readEntriesFromPath(archivedPath, 'archived');
+    }
+    /**
+     * Query entries by topic.
+     */
+    async queryByTopic(topic) {
+        const [local, imported] = await Promise.all([
+            this.getLocalEntries(),
+            this.getImportedEntries(),
+        ]);
+        const allEntries = [...local, ...imported];
+        const searchTerm = topic.toLowerCase();
+        return allEntries.filter(entry => entry.topics.some(t => t.toLowerCase().includes(searchTerm)) ||
+            entry.content.toLowerCase().includes(searchTerm));
+    }
+    /**
+     * Record a new entry to local library.
+     */
+    async record(topics, content) {
+        const localPath = getLocalPath(this.libraryPath);
+        await fs.mkdir(localPath, { recursive: true });
+        const id = uuidv4();
+        const created = new Date().toISOString();
+        const entry = {
+            id,
+            topics,
+            content,
+            created,
+            source: 'local',
+            origin: 'manual',
+        };
+        // Generate filename
+        const slug = topics[0]
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '');
+        const timestamp = created.slice(0, 10);
+        let filename = `${slug}-${timestamp}.md`;
+        let filePath = path.join(localPath, filename);
+        // Handle collisions
+        let counter = 1;
+        while (await this.fileExists(filePath)) {
+            filename = `${slug}-${timestamp}-${counter}.md`;
+            filePath = path.join(localPath, filename);
+            counter++;
+        }
+        // Write file
+        const frontmatter = {
+            id,
+            topics,
+            created,
+            source: 'manual',
+        };
+        const fileContent = matter.stringify(content, frontmatter);
+        await fs.writeFile(filePath, fileContent, 'utf-8');
+        return {
+            entry,
+            path: path.relative(this.libraryPath, filePath),
+        };
+    }
+    /**
+     * Archive an entry (move to archived/).
+     */
+    async archive(entryId) {
+        const localPath = getLocalPath(this.libraryPath);
+        const archivedPath = getArchivedPath(this.libraryPath);
+        // Find the entry
+        const found = await this.findEntryById(localPath, entryId);
+        if (!found) {
+            return { success: false, message: `Entry not found: ${entryId}` };
+        }
+        await fs.mkdir(archivedPath, { recursive: true });
+        const filename = path.basename(found.filePath);
+        const newPath = path.join(archivedPath, filename);
+        await fs.rename(found.filePath, newPath);
+        return {
+            success: true,
+            message: `Archived to ${path.relative(this.libraryPath, newPath)}`,
+        };
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    async readEntriesFromPath(dirPath, source) {
+        const entries = [];
+        try {
+            const files = await glob(path.join(dirPath, '**/*.md'), { nodir: true });
+            for (const filePath of files) {
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const { data, content: body } = matter(content);
+                    let topics;
+                    if (Array.isArray(data.topics)) {
+                        topics = data.topics;
+                    }
+                    else if (data.topic) {
+                        topics = [data.topic];
+                    }
+                    else {
+                        topics = ['general'];
+                    }
+                    entries.push({
+                        id: data.id || uuidv4(),
+                        topics,
+                        content: body.trim(),
+                        created: data.created || new Date().toISOString(),
+                        source,
+                        origin: data.source,
+                        imported_from: data.imported_from,
+                    });
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist
+        }
+        return entries;
+    }
+    async findEntryById(dirPath, entryId) {
+        try {
+            const files = await glob(path.join(dirPath, '**/*.md'), { nodir: true });
+            for (const filePath of files) {
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const { data, content: body } = matter(content);
+                    if (data.id === entryId) {
+                        let topics;
+                        if (Array.isArray(data.topics)) {
+                            topics = data.topics;
+                        }
+                        else if (data.topic) {
+                            topics = [data.topic];
+                        }
+                        else {
+                            topics = ['general'];
+                        }
+                        return {
+                            entry: {
+                                id: data.id,
+                                topics,
+                                content: body.trim(),
+                                created: data.created || new Date().toISOString(),
+                                source: 'local',
+                                origin: data.source,
+                            },
+                            filePath,
+                        };
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist
+        }
+        return null;
+    }
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/library 2/parsers/cursor.d.ts

@@ -0,0 +1,15 @@
+import type { ParseResult } from './types.js';
+/**
+ * Parse a Cursor Memory Bank folder (.cursor-memory/).
+ *
+ * Cursor Memory Bank typically contains:
+ * - activeContext.md - Current working context
+ * - progress.md - Progress log
+ * - projectBrief.md - Project overview
+ * - systemPatterns.md - System patterns
+ * - decisionLog.md - Decision history
+ * - techStack.md - Technology stack info
+ *
+ * Can also contain JSON files and subdirectories.
+ */
+export declare function parseCursorMemory(dirPath: string): Promise<ParseResult>;

package/dist/library 2/parsers/cursor.js

@@ -0,0 +1,168 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+// ============================================================================
+// Cursor Memory Bank Parser
+// ============================================================================
+/**
+ * Parse a Cursor Memory Bank folder (.cursor-memory/).
+ *
+ * Cursor Memory Bank typically contains:
+ * - activeContext.md - Current working context
+ * - progress.md - Progress log
+ * - projectBrief.md - Project overview
+ * - systemPatterns.md - System patterns
+ * - decisionLog.md - Decision history
+ * - techStack.md - Technology stack info
+ *
+ * Can also contain JSON files and subdirectories.
+ */
+export async function parseCursorMemory(dirPath) {
+    const entries = [];
+    const errors = [];
+    let skipped = 0;
+    try {
+        const stats = await fs.stat(dirPath);
+        if (!stats.isDirectory()) {
+            errors.push(`${dirPath} is not a directory`);
+            return { entries, skipped, errors };
+        }
+        // Parse markdown files
+        const mdFiles = await glob(path.join(dirPath, '**/*.md'), { nodir: true });
+        for (const filePath of mdFiles) {
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const { data, content: body } = matter(content);
+                const trimmedBody = body.trim();
+                if (!trimmedBody) {
+                    skipped++;
+                    continue;
+                }
+                // Extract title from filename (convert camelCase/snake_case to Title Case)
+                const filename = path.basename(filePath, '.md');
+                const title = data.title || formatFilename(filename);
+                // Determine context based on filename
+                const context = data.context || inferContext(filename);
+                entries.push({
+                    title,
+                    content: trimmedBody,
+                    context,
+                    intent: data.intent,
+                    source: 'cursor',
+                    originalPath: filePath,
+                });
+            }
+            catch (fileError) {
+                errors.push(`${filePath}: ${fileError instanceof Error ? fileError.message : String(fileError)}`);
+                skipped++;
+            }
+        }
+        // Parse JSON files
+        const jsonFiles = await glob(path.join(dirPath, '**/*.json'), { nodir: true });
+        for (const filePath of jsonFiles) {
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const data = JSON.parse(content);
+                // Handle different JSON structures
+                if (Array.isArray(data)) {
+                    // Array of memory items
+                    for (const item of data) {
+                        if (typeof item === 'object' && item !== null) {
+                            const entry = extractFromJSON(item, filePath);
+                            if (entry) {
+                                entries.push(entry);
+                            }
+                            else {
+                                skipped++;
+                            }
+                        }
+                    }
+                }
+                else if (typeof data === 'object' && data !== null) {
+                    // Single memory object
+                    const entry = extractFromJSON(data, filePath);
+                    if (entry) {
+                        entries.push(entry);
+                    }
+                    else {
+                        skipped++;
+                    }
+                }
+            }
+            catch (fileError) {
+                errors.push(`${filePath}: ${fileError instanceof Error ? fileError.message : String(fileError)}`);
+                skipped++;
+            }
+        }
+    }
+    catch (dirError) {
+        errors.push(`Failed to access path: ${dirError instanceof Error ? dirError.message : String(dirError)}`);
+    }
+    return { entries, skipped, errors };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Convert filename to readable title.
+ * activeContext -> Active Context
+ * system_patterns -> System Patterns
+ */
+function formatFilename(filename) {
+    return filename
+        // Handle camelCase
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        // Handle snake_case
+        .replace(/_/g, ' ')
+        // Handle kebab-case
+        .replace(/-/g, ' ')
+        // Capitalize first letter of each word
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+/**
+ * Infer context from Cursor Memory Bank filename patterns.
+ */
+function inferContext(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.includes('context'))
+        return 'context';
+    if (lower.includes('progress'))
+        return 'progress';
+    if (lower.includes('brief') || lower.includes('overview'))
+        return 'project';
+    if (lower.includes('pattern'))
+        return 'patterns';
+    if (lower.includes('decision'))
+        return 'decisions';
+    if (lower.includes('stack') || lower.includes('tech'))
+        return 'technology';
+    return 'cursor-memory';
+}
+/**
+ * Extract a ParsedEntry from a JSON object.
+ */
+function extractFromJSON(obj, filePath) {
+    // Try various common keys for title
+    const title = obj.title ||
+        obj.name ||
+        obj.key ||
+        path.basename(filePath, '.json');
+    // Try various common keys for content
+    const content = obj.content ||
+        obj.description ||
+        obj.text ||
+        obj.value ||
+        obj.memory;
+    if (!content) {
+        return null;
+    }
+    return {
+        title,
+        content,
+        context: obj.context || obj.category || obj.type,
+        intent: obj.intent,
+        source: 'cursor',
+        originalPath: filePath,
+    };
+}

package/dist/library 2/parsers/index.d.ts

@@ -0,0 +1,6 @@
+export type { ParsedEntry, ParseResult } from './types.js';
+export { parseJSONL } from './jsonl.js';
+export { parseMarkdown } from './markdown.js';
+export { parseCursorMemory } from './cursor.js';
+export { parseJSON } from './json.js';
+export { parseSQLite } from './sqlite.js';

package/dist/library 2/parsers/index.js

@@ -0,0 +1,5 @@
+export { parseJSONL } from './jsonl.js';
+export { parseMarkdown } from './markdown.js';
+export { parseCursorMemory } from './cursor.js';
+export { parseJSON } from './json.js';
+export { parseSQLite } from './sqlite.js';

package/dist/library 2/parsers/json.d.ts

@@ -0,0 +1,11 @@
+import type { ParseResult } from './types.js';
+/**
+ * Parse a JSON file containing an array of memory entries.
+ *
+ * Supports various common structures:
+ * - Array of objects with title/content
+ * - Array of objects with name/description
+ * - Object with entries array
+ * - Object with memories array
+ */
+export declare function parseJSON(filePath: string): Promise<ParseResult>;

package/dist/library 2/parsers/json.js

@@ -0,0 +1,95 @@
+import * as fs from 'fs/promises';
+/**
+ * Parse a JSON file containing an array of memory entries.
+ *
+ * Supports various common structures:
+ * - Array of objects with title/content
+ * - Array of objects with name/description
+ * - Object with entries array
+ * - Object with memories array
+ */
+export async function parseJSON(filePath) {
+    const entries = [];
+    const errors = [];
+    let skipped = 0;
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        // Handle different JSON structures
+        let items = [];
+        if (Array.isArray(data)) {
+            // Direct array of entries
+            items = data;
+        }
+        else if (typeof data === 'object' && data !== null) {
+            // Object with entries/memories/items array
+            if (Array.isArray(data.entries)) {
+                items = data.entries;
+            }
+            else if (Array.isArray(data.memories)) {
+                items = data.memories;
+            }
+            else if (Array.isArray(data.items)) {
+                items = data.items;
+            }
+            else if (Array.isArray(data.data)) {
+                items = data.data;
+            }
+            else {
+                // Single object - treat as one entry
+                items = [data];
+            }
+        }
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            if (typeof item !== 'object' || item === null) {
+                skipped++;
+                continue;
+            }
+            // Extract title
+            const title = item.title || item.name || item.key || `Entry ${i + 1}`;
+            // Extract content
+            let entryContent = item.content ||
+                item.text ||
+                item.description ||
+                item.value ||
+                item.memory ||
+                item.observation;
+            // Handle observations array
+            if (!entryContent && item.observations && Array.isArray(item.observations)) {
+                entryContent = item.observations.join('\n\n');
+            }
+            if (!entryContent) {
+                skipped++;
+                continue;
+            }
+            // Extract context
+            let context;
+            if (item.context) {
+                context = item.context;
+            }
+            else if (item.category) {
+                context = item.category;
+            }
+            else if (item.type) {
+                context = item.type;
+            }
+            else if (item.tags && Array.isArray(item.tags)) {
+                context = item.tags.join(', ');
+            }
+            entries.push({
+                title: String(title),
+                content: String(entryContent),
+                context,
+                intent: item.intent ? String(item.intent) : undefined,
+                reasoning: item.reasoning ? String(item.reasoning) : undefined,
+                example: item.example ? String(item.example) : undefined,
+                source: 'json',
+            });
+        }
+    }
+    catch (error) {
+        errors.push(`Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { entries, skipped, errors };
+}

package/dist/library 2/parsers/jsonl.d.ts

@@ -0,0 +1,14 @@
+import type { ParseResult } from './types.js';
+/**
+ * Parse a JSONL file. Supports multiple formats:
+ *
+ * mcp-knowledge-graph:
+ * {"type":"entity","name":"Topic","observations":["fact 1","fact 2"]}
+ *
+ * Generic memory formats:
+ * {"title":"Topic","content":"..."}
+ * {"content":"...","timestamp":"..."}
+ * {"text":"...","metadata":{}}
+ * {"memory":"...","created_at":"..."}
+ */
+export declare function parseJSONL(filePath: string): Promise<ParseResult>;

package/dist/library 2/parsers/jsonl.js

@@ -0,0 +1,85 @@
+import * as fs from 'fs/promises';
+/**
+ * Parse a JSONL file. Supports multiple formats:
+ *
+ * mcp-knowledge-graph:
+ * {"type":"entity","name":"Topic","observations":["fact 1","fact 2"]}
+ *
+ * Generic memory formats:
+ * {"title":"Topic","content":"..."}
+ * {"content":"...","timestamp":"..."}
+ * {"text":"...","metadata":{}}
+ * {"memory":"...","created_at":"..."}
+ */
+export async function parseJSONL(filePath) {
+    const entries = [];
+    const errors = [];
+    let skipped = 0;
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const lines = content.trim().split('\n').filter(line => line.trim());
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            try {
+                const item = JSON.parse(line);
+                // Skip internal markers and relations
+                if (item.type === '_aim' || item.type === 'relation') {
+                    skipped++;
+                    continue;
+                }
+                // Extract title (try multiple fields)
+                const title = item.name || item.title || item.key || `Entry ${i + 1}`;
+                // Extract content (try multiple fields)
+                let entryContent;
+                // Check observations array first (mcp-knowledge-graph)
+                if (item.observations && Array.isArray(item.observations) && item.observations.length > 0) {
+                    entryContent = item.observations.join('\n\n');
+                }
+                // Fall back to common content fields
+                if (!entryContent) {
+                    entryContent = item.content || item.text || item.description ||
+                        item.value || item.memory || item.observation || item.body;
+                }
+                // Skip if no content found
+                if (!entryContent) {
+                    skipped++;
+                    continue;
+                }
+                // Extract context
+                let context;
+                if (item.entityType) {
+                    context = item.entityType;
+                }
+                else if (item.context) {
+                    context = item.context;
+                }
+                else if (item.category) {
+                    context = item.category;
+                }
+                else if (item.type && item.type !== 'entity' && item.type !== 'memory') {
+                    context = item.type;
+                }
+                else if (item.tags && Array.isArray(item.tags)) {
+                    context = item.tags.join(', ');
+                }
+                entries.push({
+                    title: String(title),
+                    content: String(entryContent),
+                    context,
+                    intent: item.intent ? String(item.intent) : undefined,
+                    reasoning: item.reasoning ? String(item.reasoning) : undefined,
+                    example: item.example ? String(item.example) : undefined,
+                    source: 'jsonl',
+                });
+            }
+            catch (parseError) {
+                errors.push(`Line ${i + 1}: Invalid JSON - ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+                skipped++;
+            }
+        }
+    }
+    catch (fileError) {
+        errors.push(`Failed to read file: ${fileError instanceof Error ? fileError.message : String(fileError)}`);
+    }
+    return { entries, skipped, errors };
+}

package/dist/library 2/parsers/markdown.d.ts

@@ -0,0 +1,15 @@
+import type { ParseResult } from './types.js';
+/**
+ * Parse a folder of markdown files (Basic Memory MCP / Obsidian / any .md).
+ *
+ * Input format:
+ * ---
+ * title: API Rate Limits
+ * tags: [api, performance]
+ * ---
+ *
+ * # API Rate Limits
+ *
+ * Always implement exponential backoff...
+ */
+export declare function parseMarkdown(dirPath: string): Promise<ParseResult>;