@graphmemory/server 1.1.0

package/dist/api/rest/websocket.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachWebSocket = attachWebSocket;
+const ws_1 = require("ws");
+/**
+ * Attach a WebSocket server to the HTTP server at /api/ws.
+ * Broadcasts all ProjectManager events to connected clients.
+ * Each event includes projectId — clients filter on their side.
+ */
+function attachWebSocket(httpServer, projectManager) {
+    const wss = new ws_1.WebSocketServer({ noServer: true });
+    // Handle upgrade requests for /api/ws
+    httpServer.on('upgrade', (req, socket, head) => {
+        if (req.url !== '/api/ws') {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            ws.on('error', (err) => {
+                process.stderr.write(`[ws] Client error: ${err}\n`);
+            });
+            wss.emit('connection', ws, req);
+        });
+    });
+    // Broadcast helper
+    function broadcast(event) {
+        const msg = JSON.stringify(event);
+        for (const client of wss.clients) {
+            if (client.readyState === ws_1.WebSocket.OPEN) {
+                client.send(msg, (err) => {
+                    if (err)
+                        process.stderr.write(`[ws] Send error: ${err}\n`);
+                });
+            }
+        }
+    }
+    // Subscribe to ProjectManager events
+    const events = [
+        'note:created', 'note:updated', 'note:deleted',
+        'note:attachment:added', 'note:attachment:deleted',
+        'task:created', 'task:updated', 'task:deleted', 'task:moved',
+        'task:attachment:added', 'task:attachment:deleted',
+        'skill:created', 'skill:updated', 'skill:deleted',
+        'skill:attachment:added', 'skill:attachment:deleted',
+        'project:indexed',
+    ];
+    for (const eventType of events) {
+        projectManager.on(eventType, (data) => {
+            broadcast({ projectId: data.projectId, type: eventType, data });
+        });
+    }
+    // Debounced graph:updated from indexer
+    let graphUpdateTimer;
+    let pendingGraphUpdates = new Map();
+    projectManager.on('graph:updated', (data) => {
+        const key = data.projectId;
+        if (!pendingGraphUpdates.has(key))
+            pendingGraphUpdates.set(key, []);
+        pendingGraphUpdates.get(key).push(data.file);
+        if (!graphUpdateTimer) {
+            graphUpdateTimer = setTimeout(() => {
+                for (const [projectId, files] of pendingGraphUpdates) {
+                    broadcast({ projectId, type: 'graph:updated', data: { files } });
+                }
+                pendingGraphUpdates = new Map();
+                graphUpdateTimer = undefined;
+            }, 1000);
+        }
+    });
+    return wss;
+}

package/dist/api/tools/code/get-file-symbols.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_file_symbols', {
+        description: 'Return all symbols (functions, classes, types, etc.) declared in a specific file. ' +
+            'Use this to understand the structure of a file before reading individual symbols. ' +
+            'Returns an array of { id, kind, name, signature, startLine, endLine, isExported }. ' +
+            'Pass an id to get_symbol to fetch full content including body and docComment.',
+        inputSchema: {
+            fileId: zod_1.z.string().describe('File path relative to code dir, e.g. "src/lib/graph.ts"'),
+        },
+    }, async ({ fileId }) => {
+        const symbols = mgr.getFileSymbols(fileId);
+        if (symbols.length === 0) {
+            return { content: [{ type: 'text', text: `File not found: ${fileId}` }], isError: true };
+        }
+        const result = symbols.map(s => ({
+            id: s.id,
+            kind: s.kind,
+            name: s.name,
+            signature: s.signature,
+            startLine: s.startLine,
+            endLine: s.endLine,
+            isExported: s.isExported,
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/api/tools/code/get-symbol.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('get_symbol', {
+        description: 'Return the full content of a specific code symbol. ' +
+            'Use this after search_code or get_file_symbols to read the full implementation. ' +
+            'Node IDs have the form "fileId::symbolName" or "fileId::ClassName::methodName". ' +
+            'Returns id, fileId, kind, name, signature, docComment, body, startLine, endLine, isExported, and crossLinks (notes/tasks linking to this symbol).',
+        inputSchema: {
+            nodeId: zod_1.z.string().describe('Symbol ID from search_code or get_file_symbols, e.g. "src/lib/graph.ts::updateFile"'),
+        },
+    }, async ({ nodeId }) => {
+        const symbol = mgr.getSymbol(nodeId);
+        if (!symbol) {
+            return { content: [{ type: 'text', text: `Symbol not found: ${nodeId}` }], isError: true };
+        }
+        const { embedding: _embedding, mtime: _mtime, ...rest } = symbol;
+        return { content: [{ type: 'text', text: JSON.stringify(rest, null, 2) }] };
+    });
+}

package/dist/api/tools/code/list-files.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_files', {
+        description: 'List indexed source files in the code graph. ' +
+            'Optionally filter by file name substring (case-insensitive) and limit results. ' +
+            'Returns an array of { fileId, symbolCount }. ' +
+            'Pass a fileId to get_file_symbols to see all its declarations.',
+        inputSchema: {
+            filter: zod_1.z.string().optional().describe('Case-insensitive substring to match against file paths, e.g. "graph" or "src/lib"'),
+            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/code/search-code.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_code', {
+        description: 'Semantic search over the indexed source code. ' +
+            'Finds the most relevant symbols (functions, classes, types) by matching ' +
+            'against their signatures and doc comments using vector similarity, ' +
+            'then expands results by following graph edges (imports, contains, extends). ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'id, fileId, kind, name, signature, docComment, startLine, endLine, score. ' +
+            'Pass an id to get_symbol to read the full implementation.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language or code search query, e.g. "function that loads the graph from disk"'),
+            topK: zod_1.z.number().optional().describe('How many top similar symbols to use as seeds (default 5)'),
+            bfsDepth: zod_1.z.number().optional().describe('How many hops to follow graph edges 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; lower values return more results (default 0.5)'),
+            bfsDecay: zod_1.z.number().min(0).max(1).optional().describe('Score multiplier per graph 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.search(query, { topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/code/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_files', {
+        description: 'Semantic search over indexed source code files. ' +
+            'Finds the most relevant files by matching query against file-level embeddings ' +
+            '(file path) using vector similarity. ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'fileId, symbolCount, score. ' +
+            'Use this to discover which source files are relevant before diving into symbols with get_file_symbols or search_code.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language or path search query, e.g. "graph persistence" or "search module"'),
+            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/context/get-context.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+function register(server, ctx) {
+    server.registerTool('get_context', {
+        description: 'Returns the current project and workspace context. ' +
+            'Use this to discover which project you are connected to, whether it is part of a workspace, ' +
+            'and which other projects are available in the workspace (for cross-graph links with projectId).',
+        inputSchema: {},
+    }, async () => {
+        const result = {
+            projectId: ctx?.projectId ?? null,
+            workspaceId: ctx?.workspaceId ?? null,
+            workspaceProjects: ctx?.workspaceProjects ?? null,
+            hasWorkspace: !!ctx?.workspaceId,
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/cross-references.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, docMgr, codeMgr) {
+    const docGraph = docMgr.graph;
+    const codeGraph = codeMgr.graph;
+    server.registerTool('cross_references', {
+        description: 'Find all references to a symbol across both code and documentation graphs. ' +
+            'Returns: definitions (from CodeGraph — where the symbol is defined), ' +
+            'documentation (text sections in docs that contain examples using the symbol), ' +
+            'and examples (code blocks in docs that contain the symbol). ' +
+            'This is the most comprehensive way to understand a symbol — combining source code, docs, and examples.',
+        inputSchema: {
+            symbol: zod_1.z.string().describe('Symbol name to look up, e.g. "createUser", "AuthService"'),
+        },
+    }, async ({ symbol }) => {
+        // 1. Search CodeGraph for definitions
+        const definitions = [];
+        codeGraph.forEachNode((id, attrs) => {
+            if (attrs.name === symbol) {
+                definitions.push({
+                    id,
+                    fileId: attrs.fileId,
+                    kind: attrs.kind,
+                    name: attrs.name,
+                    signature: attrs.signature,
+                    docComment: attrs.docComment,
+                    startLine: attrs.startLine,
+                    endLine: attrs.endLine,
+                });
+            }
+        });
+        // 2. Search DocGraph for code blocks containing the symbol
+        const examples = [];
+        const documentation = [];
+        const seenDocs = new Set();
+        docGraph.forEachNode((id, attrs) => {
+            if (attrs.symbols.length === 0)
+                return;
+            if (!attrs.symbols.includes(symbol))
+                return;
+            examples.push({
+                id,
+                fileId: attrs.fileId,
+                language: attrs.language,
+                symbols: attrs.symbols,
+                content: attrs.content,
+            });
+            // Find parent text section for documentation context
+            for (const neighbor of docGraph.inNeighbors(id)) {
+                if (seenDocs.has(neighbor))
+                    continue;
+                const nAttrs = docGraph.getNodeAttributes(neighbor);
+                if (nAttrs.fileId === attrs.fileId && nAttrs.language === undefined && nAttrs.level < attrs.level) {
+                    seenDocs.add(neighbor);
+                    documentation.push({
+                        id: neighbor,
+                        fileId: nAttrs.fileId,
+                        title: nAttrs.title,
+                        content: nAttrs.content,
+                    });
+                }
+            }
+        });
+        if (definitions.length === 0 && examples.length === 0) {
+            return { content: [{ type: 'text', text: `No references found for symbol: ${symbol}` }] };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ definitions, documentation, examples }, null, 2),
+                }],
+        };
+    });
+}

package/dist/api/tools/docs/explain-symbol.js

@@ -0,0 +1,55 @@
+"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('explain_symbol', {
+        description: 'Find documentation that explains a specific symbol. ' +
+            'Searches code blocks in docs for the symbol, then returns both the code example ' +
+            'and the surrounding text section that provides context/explanation. ' +
+            'Use this to understand what a function, class, or type does based on documentation.',
+        inputSchema: {
+            symbol: zod_1.z.string().describe('Symbol name to look up, e.g. "createUser", "AuthService"'),
+            limit: zod_1.z.number().optional().describe('Max results to return (default 10)'),
+        },
+    }, async ({ symbol, limit = 10 }) => {
+        const results = [];
+        graph.forEachNode((id, attrs) => {
+            if (results.length >= limit)
+                return;
+            if (attrs.symbols.length === 0)
+                return;
+            if (!attrs.symbols.includes(symbol))
+                return;
+            // Find the parent text section
+            const parent = findParentTextSection(graph, id, attrs);
+            results.push({
+                codeBlock: {
+                    id,
+                    language: attrs.language,
+                    symbols: attrs.symbols,
+                    content: attrs.content,
+                },
+                explanation: parent
+                    ? { id: parent.id, title: parent.title, content: parent.content }
+                    : null,
+                fileId: attrs.fileId,
+            });
+        });
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: `No documentation found for symbol: ${symbol}` }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}
+function findParentTextSection(graph, nodeId, attrs) {
+    // The code block's in-neighbor with same fileId, lower level, and no language = parent text section
+    for (const neighbor of graph.inNeighbors(nodeId)) {
+        const nAttrs = graph.getNodeAttributes(neighbor);
+        if (nAttrs.fileId === attrs.fileId && nAttrs.language === undefined && nAttrs.level < attrs.level) {
+            return { id: neighbor, title: nAttrs.title, content: nAttrs.content };
+        }
+    }
+    return null;
+}

package/dist/api/tools/docs/find-examples.js

@@ -0,0 +1,52 @@
+"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('find_examples', {
+        description: 'Find code examples in documentation that contain a specific symbol (function, class, interface, etc.). ' +
+            'Searches the `symbols` array extracted from fenced code blocks via AST parsing. ' +
+            'Use this to find usage examples of a known symbol in the docs. ' +
+            'Returns matching code block nodes with id, fileId, language, symbols, content, and the parent section context.',
+        inputSchema: {
+            symbol: zod_1.z.string().describe('Symbol name to search for, e.g. "createUser", "UserService"'),
+            limit: zod_1.z.number().optional().describe('Max results to return (default 20)'),
+        },
+    }, async ({ symbol, limit = 20 }) => {
+        const results = [];
+        graph.forEachNode((id, attrs) => {
+            if (results.length >= limit)
+                return;
+            if (attrs.symbols.length === 0)
+                return;
+            if (!attrs.symbols.includes(symbol))
+                return;
+            // Find parent text section (previous node with lower level and no language)
+            const parentId = findParentSection(graph, id, attrs);
+            results.push({
+                id,
+                fileId: attrs.fileId,
+                language: attrs.language,
+                symbols: attrs.symbols,
+                content: attrs.content,
+                parentId,
+                parentTitle: parentId ? graph.getNodeAttribute(parentId, 'title') : undefined,
+            });
+        });
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: `No code examples found containing symbol: ${symbol}` }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}
+function findParentSection(graph, nodeId, attrs) {
+    // Walk inNeighbors (sibling edges point forward, so the parent is an inNeighbor)
+    for (const neighbor of graph.inNeighbors(nodeId)) {
+        const nAttrs = graph.getNodeAttributes(neighbor);
+        if (nAttrs.fileId === attrs.fileId && nAttrs.language === undefined && nAttrs.level < attrs.level) {
+            return neighbor;
+        }
+    }
+    return undefined;
+}

package/dist/api/tools/docs/get-node.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('get_node', {
+        description: 'Return the full content of a specific node (file root or section). ' +
+            'Use this after search or get_toc to read the full text of a result. ' +
+            'Node IDs have two forms: ' +
+            '"docs/auth.md" for the file root (intro text before any headings), ' +
+            '"docs/auth.md::Overview" for a named section. ' +
+            'Returns id, fileId, title, content, level, links, mtime, and crossLinks (notes/tasks linking to this node).',
+        inputSchema: {
+            nodeId: zod_1.z.string().describe('Node ID from search results or get_toc, e.g. "docs/auth.md" or "docs/auth.md::Overview"'),
+        },
+    }, async ({ nodeId }) => {
+        const node = mgr.getNode(nodeId);
+        if (!node) {
+            return { content: [{ type: 'text', text: `Node not found: ${nodeId}` }], isError: true };
+        }
+        const { embedding: _embedding, ...rest } = node;
+        return { content: [{ type: 'text', text: JSON.stringify(rest, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/get-toc.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('get_toc', {
+        description: 'Return the table of contents (headings hierarchy) for a specific file. ' +
+            'Use this to understand the structure of a file before deciding which sections to read. ' +
+            'Returns an array of { id, title, level } objects. ' +
+            'The id field is a node ID you can pass directly to get_node to fetch full content.',
+        inputSchema: {
+            fileId: zod_1.z.string().describe('File path relative to docs dir, e.g. "docs/auth.md"'),
+        },
+    }, async ({ fileId }) => {
+        const chunks = mgr.getFileChunks(fileId);
+        if (chunks.length === 0) {
+            return { content: [{ type: 'text', text: `File not found: ${fileId}` }], isError: true };
+        }
+        const toc = chunks.map(c => ({ id: c.id, title: c.title, level: c.level }));
+        return { content: [{ type: 'text', text: JSON.stringify(toc, null, 2) }] };
+    });
+}

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) }] };
+    });
+}