@prih/mcp-graph-memory 1.0.3

package/dist/api/tools/docs/list-snippets.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    const graph = mgr.graph;
+    server.registerTool('list_snippets', {
+        description: 'List code snippets extracted from documentation files. ' +
+            'Returns code block nodes with language, symbols, and a content preview. ' +
+            'Supports filtering by file, language, and content substring. ' +
+            'Use this to discover what code examples exist in the docs.',
+        inputSchema: {
+            fileId: zod_1.z.string().optional().describe('Filter by file, e.g. "docs/auth.md"'),
+            filter: zod_1.z.string().optional().describe('Case-insensitive substring match on content'),
+            language: zod_1.z.string().optional().describe('Filter by language, e.g. "typescript"'),
+            limit: zod_1.z.number().optional().describe('Max results to return (default 20)'),
+        },
+    }, async ({ fileId, filter, language, limit = 20 }) => {
+        const lowerFilter = filter?.toLowerCase();
+        const lowerLang = language?.toLowerCase();
+        const results = [];
+        graph.forEachNode((id, attrs) => {
+            if (results.length >= limit)
+                return;
+            if (attrs.language === undefined)
+                return; // skip text chunks
+            if (fileId && attrs.fileId !== fileId)
+                return;
+            if (lowerLang && attrs.language !== lowerLang)
+                return;
+            if (lowerFilter && !attrs.content.toLowerCase().includes(lowerFilter))
+                return;
+            results.push({
+                id,
+                fileId: attrs.fileId,
+                language: attrs.language,
+                symbols: attrs.symbols,
+                preview: attrs.content.length > 200 ? attrs.content.slice(0, 200) + '…' : attrs.content,
+            });
+        });
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: 'No code snippets found matching the criteria.' }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/list-topics.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('list_topics', {
+        description: 'List indexed documentation files. ' +
+            'Optionally filter by file name substring (case-insensitive) and limit results. ' +
+            'Returns an array of { fileId, title, chunks }. ' +
+            'Pass a fileId to get_toc to see its structure, or to search to query it.',
+        inputSchema: {
+            filter: zod_1.z.string().optional().describe('Case-insensitive substring to match against file paths, e.g. "auth" or "api"'),
+            limit: zod_1.z.number().optional().describe('Maximum number of results to return (default 20)'),
+        },
+    }, async ({ filter, limit }) => ({
+        content: [{ type: 'text', text: JSON.stringify(mgr.listFiles(filter, limit), null, 2) }],
+    }));
+}

package/dist/api/tools/docs/search-files.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('search_topic_files', {
+        description: 'Semantic search over indexed documentation files. ' +
+            'Finds the most relevant files by matching query against file-level embeddings ' +
+            '(file path + title/content summary) using vector similarity. ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'fileId, title, chunks, score. ' +
+            'Use this to discover which doc files are relevant before diving into content with search or get_toc.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language search query, e.g. "authentication setup" or "API endpoints"'),
+            topK: zod_1.z.number().optional().describe('Maximum number of results to return (default 10)'),
+            minScore: zod_1.z.number().min(0).max(1).optional().describe('Minimum relevance score 0–1 (default 0.3)'),
+        },
+    }, async ({ query, topK, minScore }) => {
+        const results = await mgr.searchFiles(query, { topK, minScore });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/search-snippets.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    const graph = mgr.graph;
+    server.registerTool('search_snippets', {
+        description: 'Semantic search over code snippets extracted from documentation. ' +
+            'Finds the most relevant code examples using vector similarity. ' +
+            'Only searches nodes that are fenced code blocks (have a language tag). ' +
+            'Use this when looking for code examples by description, e.g. "authentication example" or "database query". ' +
+            'Returns code block nodes sorted by relevance score.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language search query'),
+            topK: zod_1.z.number().optional().describe('Max results to return (default 10)'),
+            minScore: zod_1.z.number().min(0).max(1).optional().describe('Minimum relevance score 0–1 (default 0.3)'),
+            language: zod_1.z.string().optional().describe('Filter by language, e.g. "typescript", "python"'),
+        },
+    }, async ({ query, topK = 10, minScore = 0.3, language }) => {
+        // Search all nodes via mgr.search (no BFS expansion), then filter to code blocks only
+        const allResults = await mgr.search(query, { topK: topK * 3, maxResults: topK * 5, minScore, bfsDepth: 0 });
+        const filtered = allResults.filter(r => {
+            const attrs = graph.getNodeAttributes(r.id);
+            if (attrs.language === undefined)
+                return false;
+            if (language && attrs.language !== language.toLowerCase())
+                return false;
+            return true;
+        }).slice(0, topK);
+        const results = filtered.map(r => {
+            const attrs = graph.getNodeAttributes(r.id);
+            return {
+                id: r.id,
+                fileId: attrs.fileId,
+                language: attrs.language,
+                symbols: attrs.symbols,
+                content: attrs.content,
+                score: r.score,
+            };
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/search.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('search', {
+        description: 'Semantic search over the indexed documentation. ' +
+            'Finds the most relevant sections using vector similarity, then expands results ' +
+            'by traversing links between documents (graph walk). ' +
+            'Returns an array of chunks sorted by relevance score (0–1), each with: ' +
+            'id, fileId, title, content, level, score. ' +
+            'Use the id from results to fetch full content with get_node. ' +
+            'Prefer this tool when looking for information without knowing which file contains it.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language search query'),
+            topK: zod_1.z.number().optional().describe('How many top similar sections to use as seeds for graph expansion (default 5)'),
+            bfsDepth: zod_1.z.number().optional().describe('How many hops to follow cross-document links from each seed (default 1; 0 = no expansion)'),
+            maxResults: zod_1.z.number().optional().describe('Maximum number of results to return (default 20)'),
+            minScore: zod_1.z.number().min(0).max(1).optional().describe('Minimum relevance score threshold 0–1; lower values return more results (default 0.5)'),
+            bfsDecay: zod_1.z.number().min(0).max(1).optional().describe('Score multiplier applied per graph hop; controls how quickly relevance fades with distance (default 0.8)'),
+            searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional().describe('Search mode: hybrid (default, BM25 + vector), vector (embedding only), keyword (BM25 only)'),
+        },
+    }, async ({ query, topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode }) => {
+        const results = await mgr.search(query, { topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/file-index/get-file-info.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_file_info', {
+        description: 'Get full metadata for a specific file or directory by path. ' +
+            'For files: returns filePath, kind, fileName, directory, extension, language, mimeType, size, mtime, and crossLinks (notes/tasks linking to this file). ' +
+            'For directories: returns filePath, kind, fileName, directory, fileCount, size (total of direct children). ' +
+            'Use "." for the project root.',
+        inputSchema: {
+            filePath: zod_1.z.string().describe('Relative file or directory path (e.g. "src/lib/config.ts" or "src/lib")'),
+        },
+    }, async ({ filePath }) => {
+        const info = mgr.getFileInfo(filePath);
+        if (!info) {
+            return { content: [{ type: 'text', text: `File or directory not found: ${filePath}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
+    });
+}

package/dist/api/tools/file-index/list-all-files.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('list_all_files', {
+        description: 'List all indexed project files and directories with optional filters. ' +
+            'When directory is set, returns immediate children (files + subdirectories) — use this to browse the project tree. ' +
+            'Without directory, returns all files matching filters (no directories in flat listing). ' +
+            'Returns an array of { filePath, kind, fileName, extension, language, mimeType, size, fileCount }. ' +
+            'Use search_all_files for semantic search or get_file_info for detailed metadata on a specific path.',
+        inputSchema: {
+            directory: zod_1.z.string().optional()
+                .describe('List immediate children of this directory (e.g. ".", "src/lib"). Default: lists all files'),
+            extension: zod_1.z.string().optional()
+                .describe('Filter by extension (e.g. ".ts", ".md", ".png")'),
+            language: zod_1.z.string().optional()
+                .describe('Filter by language (e.g. "typescript", "markdown", "json")'),
+            filter: zod_1.z.string().optional()
+                .describe('Substring filter on file path (case-insensitive)'),
+            limit: zod_1.z.number().optional().default(50)
+                .describe('Max results (default 50)'),
+        },
+    }, async ({ directory, extension, language, filter, limit }) => {
+        const results = mgr.listAllFiles({ directory, extension, language, filter, limit });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/file-index/search-all-files.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('search_all_files', {
+        description: 'Semantic search over all indexed project files by file path. ' +
+            'Finds the most relevant files by matching query against file path embeddings using vector similarity. ' +
+            'Searches file nodes only (not directories). ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'filePath, fileName, extension, language, size, score. ' +
+            'Use this to discover which project files are relevant to a topic.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Search query'),
+            topK: zod_1.z.number().optional().default(10)
+                .describe('Max results (default 10)'),
+            minScore: zod_1.z.number().optional().default(0.3)
+                .describe('Minimum cosine similarity score (default 0.3)'),
+        },
+    }, async ({ query, topK, minScore }) => {
+        const results = await mgr.search(query, { topK, minScore });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/add-attachment.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('add_note_attachment', {
+        description: 'Attach a file to a note. Provide the absolute path to a local file. ' +
+            'The file is copied into the note directory (.notes/{noteId}/). ' +
+            'Returns attachment metadata (filename, mimeType, size).',
+        inputSchema: {
+            noteId: zod_1.z.string().describe('ID of the note to attach the file to'),
+            filePath: zod_1.z.string().describe('Absolute path to the file on disk'),
+        },
+    }, async ({ noteId, filePath }) => {
+        if (!fs_1.default.existsSync(filePath)) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'File not found' }) }], isError: true };
+        }
+        const data = fs_1.default.readFileSync(filePath);
+        const filename = path_1.default.basename(filePath);
+        const meta = mgr.addAttachment(noteId, filename, data);
+        if (!meta) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'Note not found or no project dir' }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(meta, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/create-note.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('create_note', {
+        description: 'Create a new note or fact in the knowledge graph. ' +
+            'The note is automatically embedded for semantic search. ' +
+            'Returns the generated noteId (slug from title). ' +
+            'Use create_relation to link notes together.',
+        inputSchema: {
+            title: zod_1.z.string().describe('Short title for the note, e.g. "Auth uses JWT tokens"'),
+            content: zod_1.z.string().describe('Full text content of the note'),
+            tags: zod_1.z.array(zod_1.z.string()).optional().describe('Optional tags for filtering, e.g. ["architecture", "decision"]'),
+        },
+    }, async ({ title, content, tags }) => {
+        const noteId = await mgr.createNote(title, content, tags ?? []);
+        return { content: [{ type: 'text', text: JSON.stringify({ noteId }, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/create-relation.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('create_relation', {
+        description: 'Create a directed relation from a note to another note or to a node in the docs/code/files graph. ' +
+            'The kind is a free-form string describing the relationship, ' +
+            'e.g. "relates_to", "depends_on", "contradicts", "supports", "part_of", "references". ' +
+            'Set targetGraph to "docs", "code", "files", or "tasks" to link to a doc chunk, code symbol, file/directory, or task.',
+        inputSchema: {
+            fromId: zod_1.z.string().describe('Source note ID'),
+            toId: zod_1.z.string().describe('Target note ID, or target node ID in docs/code/files/tasks graph'),
+            kind: zod_1.z.string().describe('Relation type, e.g. "depends_on", "references"'),
+            targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'tasks']).optional()
+                .describe('Set to "docs", "code", "files", or "tasks" to create a cross-graph link instead of note-to-note'),
+            projectId: zod_1.z.string().optional().describe('Project ID that the target node belongs to. Defaults to the current project.'),
+        },
+    }, async ({ fromId, toId, kind, targetGraph, projectId }) => {
+        const created = mgr.createRelation(fromId, toId, kind, targetGraph, projectId);
+        if (!created) {
+            const msg = targetGraph
+                ? 'Could not create cross-graph relation — note not found, target not found in ' + targetGraph + ' graph, or relation already exists.'
+                : 'Could not create relation — one or both notes not found, or relation already exists.';
+            return { content: [{ type: 'text', text: msg }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ fromId, toId, kind, targetGraph, created: true }, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/delete-note.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('delete_note', {
+        description: 'Delete a note from the knowledge graph. ' +
+            'Also removes all relations (edges) connected to this note.',
+        inputSchema: {
+            noteId: zod_1.z.string().describe('ID of the note to delete'),
+        },
+    }, async ({ noteId }) => {
+        const deleted = mgr.deleteNote(noteId);
+        if (!deleted) {
+            return { content: [{ type: 'text', text: `Note not found: ${noteId}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ noteId, deleted: true }, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/delete-relation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('delete_relation', {
+        description: 'Delete a directed relation between a note and another note or a cross-graph target. ' +
+            'Set targetGraph to "docs", "code", "files", or "tasks" when deleting a cross-graph link.',
+        inputSchema: {
+            fromId: zod_1.z.string().describe('Source note ID'),
+            toId: zod_1.z.string().describe('Target note ID, or target node ID in docs/code/files/tasks graph'),
+            targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'tasks']).optional()
+                .describe('Set to "docs", "code", "files", or "tasks" when deleting a cross-graph link'),
+            projectId: zod_1.z.string().optional().describe('Project ID that the target node belongs to. Defaults to the current project.'),
+        },
+    }, async ({ fromId, toId, targetGraph, projectId }) => {
+        const deleted = mgr.deleteRelation(fromId, toId, targetGraph, projectId);
+        if (!deleted) {
+            return { content: [{ type: 'text', text: 'Relation not found.' }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ fromId, toId, targetGraph, deleted: true }, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/find-linked-notes.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('find_linked_notes', {
+        description: 'Find all notes in the knowledge graph that link to a specific node in the docs, code, files, or tasks graph. ' +
+            'This is a reverse lookup — given a target (e.g. a file, a code symbol, or a doc section), ' +
+            'returns all notes that reference it via cross-graph relations. ' +
+            'Returns an array of { noteId, title, kind, tags }. ' +
+            'Use get_note to fetch full content of a returned note.',
+        inputSchema: {
+            targetId: zod_1.z.string().describe('Target node ID in the external graph (e.g. "src/config.ts", "src/auth.ts::login", "docs/api.md::Setup")'),
+            targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'tasks']).describe('Which graph the target belongs to: "docs", "code", "files", or "tasks"'),
+            kind: zod_1.z.string().optional().describe('Filter by relation kind (e.g. "references", "depends_on"). If omitted, returns all relations.'),
+            projectId: zod_1.z.string().optional().describe('Project ID that the target node belongs to. Defaults to the current project.'),
+        },
+    }, async ({ targetId, targetGraph, kind, projectId }) => {
+        const results = mgr.findLinkedNotes(targetGraph, targetId, kind, projectId);
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: `No notes linked to ${targetGraph}::${targetId}` }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/get-note.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_note', {
+        description: 'Return the full content of a note by its ID. ' +
+            'Returns id, title, content, tags, createdAt, updatedAt, and relations (including cross-graph links from/to tasks, docs, code, files).',
+        inputSchema: {
+            noteId: zod_1.z.string().describe('Note ID, e.g. "auth-uses-jwt-tokens"'),
+        },
+    }, async ({ noteId }) => {
+        const note = mgr.getNote(noteId);
+        if (!note) {
+            return { content: [{ type: 'text', text: `Note not found: ${noteId}` }], isError: true };
+        }
+        const { embedding: _embedding, ...rest } = note;
+        return { content: [{ type: 'text', text: JSON.stringify(rest, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/list-notes.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('list_notes', {
+        description: 'List notes in the knowledge graph. ' +
+            'Optionally filter by title/id substring and/or tag. ' +
+            'Returns an array of { id, title, tags, updatedAt } sorted by most recently updated.',
+        inputSchema: {
+            filter: zod_1.z.string().optional().describe('Case-insensitive substring to match against note title or ID'),
+            tag: zod_1.z.string().optional().describe('Filter by tag (exact match, case-insensitive)'),
+            limit: zod_1.z.number().optional().describe('Maximum number of results (default 20)'),
+        },
+    }, async ({ filter, tag, limit }) => ({
+        content: [{ type: 'text', text: JSON.stringify(mgr.listNotes(filter, tag, limit), null, 2) }],
+    }));
+}

package/dist/api/tools/knowledge/list-relations.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('list_relations', {
+        description: 'List all relations (incoming and outgoing) for a note. ' +
+            'Returns an array of { fromId, toId, kind, targetGraph? }. ' +
+            'Cross-graph links include targetGraph ("docs", "code", "files", or "tasks") and resolve the real node ID.',
+        inputSchema: {
+            noteId: zod_1.z.string().describe('Note ID to list relations for'),
+        },
+    }, async ({ noteId }) => {
+        const relations = mgr.listRelations(noteId);
+        return { content: [{ type: 'text', text: JSON.stringify(relations, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/remove-attachment.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('remove_note_attachment', {
+        description: 'Remove an attachment from a note. The file is deleted from disk.',
+        inputSchema: {
+            noteId: zod_1.z.string().describe('ID of the note'),
+            filename: zod_1.z.string().describe('Filename of the attachment to remove'),
+        },
+    }, async ({ noteId, filename }) => {
+        const ok = mgr.removeAttachment(noteId, filename);
+        if (!ok) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'Attachment not found' }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ deleted: filename }) }] };
+    });
+}

package/dist/api/tools/knowledge/search-notes.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('search_notes', {
+        description: 'Semantic search over the knowledge graph (facts and notes). ' +
+            'Finds the most relevant notes using vector similarity, then expands results ' +
+            'by traversing relations between notes (graph walk). ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'id, title, content, tags, score.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language search query'),
+            topK: zod_1.z.number().optional().describe('How many top similar notes to use as seeds (default 5)'),
+            bfsDepth: zod_1.z.number().optional().describe('How many hops to follow relations from each seed (default 1; 0 = no expansion)'),
+            maxResults: zod_1.z.number().optional().describe('Maximum number of results to return (default 20)'),
+            minScore: zod_1.z.number().min(0).max(1).optional().describe('Minimum relevance score 0–1 (default 0.5)'),
+            bfsDecay: zod_1.z.number().min(0).max(1).optional().describe('Score multiplier per hop (default 0.8)'),
+            searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional().describe('Search mode: hybrid (default, BM25 + vector), vector (embedding only), keyword (BM25 only)'),
+        },
+    }, async ({ query, topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode }) => {
+        const results = await mgr.searchNotes(query, { topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/knowledge/update-note.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+const manager_types_1 = require("../../../graphs/manager-types");
+function register(server, mgr) {
+    server.registerTool('update_note', {
+        description: 'Update an existing note in the knowledge graph. ' +
+            'Only the provided fields are changed; others remain unchanged. ' +
+            'Re-embeds automatically if title or content changes. ' +
+            'Pass expectedVersion to enable optimistic locking.',
+        inputSchema: {
+            noteId: zod_1.z.string().describe('ID of the note to update'),
+            title: zod_1.z.string().optional().describe('New title'),
+            content: zod_1.z.string().optional().describe('New content'),
+            tags: zod_1.z.array(zod_1.z.string()).optional().describe('New tags (replaces existing)'),
+            expectedVersion: zod_1.z.number().int().positive().optional().describe('Current version for optimistic locking — request fails with version_conflict if the note has been updated since'),
+        },
+    }, async ({ noteId, title, content, tags, expectedVersion }) => {
+        try {
+            const updated = await mgr.updateNote(noteId, { title, content, tags }, expectedVersion);
+            if (!updated) {
+                return { content: [{ type: 'text', text: `Note not found: ${noteId}` }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify({ noteId, updated: true }, null, 2) }] };
+        }
+        catch (err) {
+            if (err instanceof manager_types_1.VersionConflictError) {
+                return { content: [{ type: 'text', text: JSON.stringify({ error: 'version_conflict', current: err.current, expected: err.expected }) }], isError: true };
+            }
+            throw err;
+        }
+    });
+}

package/dist/api/tools/skills/add-attachment.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('add_skill_attachment', {
+        description: 'Attach a file to a skill. Provide the absolute path to a local file. ' +
+            'The file is copied into the skill directory (.skills/{skillId}/). ' +
+            'Returns attachment metadata (filename, mimeType, size).',
+        inputSchema: {
+            skillId: zod_1.z.string().describe('ID of the skill to attach the file to'),
+            filePath: zod_1.z.string().describe('Absolute path to the file on disk'),
+        },
+    }, async ({ skillId, filePath }) => {
+        if (!fs_1.default.existsSync(filePath)) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'File not found' }) }], isError: true };
+        }
+        const data = fs_1.default.readFileSync(filePath);
+        const filename = path_1.default.basename(filePath);
+        const meta = mgr.addAttachment(skillId, filename, data);
+        if (!meta) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'Skill not found or no project dir' }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(meta, null, 2) }] };
+    });
+}

package/dist/api/tools/skills/bump-usage.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('bump_skill_usage', {
+        description: 'Record that a skill was used. Increments usageCount and updates lastUsedAt timestamp. ' +
+            'Call this after successfully applying a skill.',
+        inputSchema: {
+            skillId: zod_1.z.string().describe('Skill ID to bump usage for'),
+        },
+    }, async ({ skillId }) => {
+        const ok = mgr.bumpUsage(skillId);
+        if (!ok) {
+            return { content: [{ type: 'text', text: `Skill "${skillId}" not found.` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ skillId, bumped: true }, null, 2) }] };
+    });
+}

package/dist/api/tools/skills/create-skill-link.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('create_skill_link', {
+        description: 'Link a skill to a node in the docs, code, files, knowledge, or tasks graph. ' +
+            'Creates a cross-graph relation from the skill to the target node. ' +
+            'The kind is a free-form string, e.g. "references", "implements", "documents".',
+        inputSchema: {
+            skillId: zod_1.z.string().describe('Source skill ID'),
+            targetId: zod_1.z.string().describe('Target node ID in the external graph (e.g. "src/auth.ts::login", "api.md::Setup", "my-note", "my-task")'),
+            targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'knowledge', 'tasks'])
+                .describe('Which graph the target belongs to'),
+            kind: zod_1.z.string().describe('Relation type, e.g. "references", "implements", "documents"'),
+            projectId: zod_1.z.string().optional().describe('Project ID that the target node belongs to. Defaults to the current project.'),
+        },
+    }, async ({ skillId, targetId, targetGraph, kind, projectId }) => {
+        const created = mgr.createCrossLink(skillId, targetId, targetGraph, kind, projectId);
+        if (!created) {
+            return { content: [{ type: 'text', text: `Could not create cross-graph link — skill not found, target not found in ${targetGraph} graph, or link already exists.` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ skillId, targetId, targetGraph, kind, created: true }, null, 2) }] };
+    });
+}