stellavault 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stellavault",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Turn your Obsidian vault into a 3D neural knowledge graph with AI-powered search, memory decay tracking, and MCP integration.",
   "repository": {
     "type": "git",

package/packages/core/dist/api/server.js

@@ -213,6 +213,77 @@ export function createApiServer(options) {
             res.status(500).json({ error: 'Internal server error' });
         }
     });
+    // GET /api/heatmap — Design Ref: §2.2 — 지식 히트맵 활동 점수
+    app.get('/api/heatmap', async (_req, res) => {
+        try {
+            const docs = await store.getAllDocuments();
+            const now = Date.now();
+            const scores = {};
+            let hotCount = 0;
+            let coldCount = 0;
+            // Pre-fetch decay data if available
+            let decayMap = {};
+            if (decayEngine) {
+                try {
+                    const report = await decayEngine.computeAll();
+                    // topDecaying has R values for worst-performing docs
+                    for (const item of report.topDecaying) {
+                        decayMap[item.documentId] = item.retrievability;
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            for (const doc of docs) {
+                // 최근 수정 기반 점수 (0~0.4)
+                const modified = doc.lastModified ? new Date(doc.lastModified).getTime() : now - 86400000 * 60;
+                const daysSinceModified = (now - modified) / 86400000;
+                const recencyScore = Math.max(0, 1 - daysSinceModified / 90) * 0.4;
+                // 감쇠 R값 기반 (0~0.3)
+                const decayScore = (decayMap[doc.id] ?? 0.5) * 0.3;
+                // 태그 수 기반 연결도 (0~0.3)
+                const tagScore = Math.min((doc.tags?.length ?? 0) / 10, 1) * 0.3;
+                const score = Math.min(1, recencyScore + decayScore + tagScore);
+                scores[doc.id] = score;
+                if (score > 0.6)
+                    hotCount++;
+                if (score < 0.2)
+                    coldCount++;
+            }
+            res.json({ scores, stats: { total: docs.length, hotCount, coldCount } });
+        }
+        catch (err) {
+            console.error(err);
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
+    // GET /api/evolution — Design Ref: F02 — 시맨틱 진화 데이터
+    app.get('/api/evolution', async (req, res) => {
+        try {
+            const topic = req.query.topic;
+            const limit = parseInt(String(req.query.limit ?? '20'), 10);
+            const docs = await store.getAllDocuments();
+            let filtered = docs;
+            if (topic) {
+                const t = topic.toLowerCase();
+                filtered = docs.filter((d) => d.tags.some((tag) => tag.toLowerCase().includes(t)) || d.title.toLowerCase().includes(t));
+            }
+            const evolved = filtered
+                .filter((d) => d.lastModified)
+                .sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime())
+                .slice(0, limit)
+                .map((d) => ({
+                id: d.id,
+                title: d.title,
+                lastModified: d.lastModified,
+                tags: d.tags.slice(0, 5),
+            }));
+            res.json({ topic: topic ?? 'all', total: filtered.length, recentlyEvolved: evolved });
+        }
+        catch (err) {
+            console.error(err);
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    });
     // GET /api/duplicates — 중복 노트 탐지
     app.get('/api/duplicates', async (req, res) => {
         try {

package/packages/core/dist/intelligence/code-linker.d.ts

@@ -0,0 +1,20 @@
+import type { SearchEngine } from '../search/index.js';
+export interface CodeLink {
+    filePath: string;
+    keywords: string[];
+    relatedNotes: Array<{
+        documentId: string;
+        title: string;
+        score: number;
+        matchedKeywords: string[];
+    }>;
+}
+/**
+ * Extract meaningful keywords from a code file path and optional content.
+ */
+export declare function extractCodeKeywords(filePath: string, content?: string): string[];
+/**
+ * Link a code file to related knowledge notes via keyword search.
+ */
+export declare function linkCodeToKnowledge(searchEngine: SearchEngine, filePath: string, content?: string, limit?: number): Promise<CodeLink>;
+//# sourceMappingURL=code-linker.d.ts.map

package/packages/core/dist/intelligence/code-linker.js

@@ -0,0 +1,88 @@
+// Design Ref: F15 — 코드-지식 링커
+// 코드 파일/함수에서 키워드 추출 → 관련 노트 자동 매칭
+// Plan SC: SC-03 코드 파일에서 관련 노트 3개+ 반환
+/**
+ * Extract meaningful keywords from a code file path and optional content.
+ */
+export function extractCodeKeywords(filePath, content) {
+    const keywords = new Set();
+    // From file path: directory names + file name parts
+    const skipParts = new Set(['src', 'lib', 'dist', 'node_modules', '.', '']);
+    const parts = filePath
+        .replace(/\\/g, '/')
+        .split('/')
+        .filter((p) => !skipParts.has(p));
+    for (const part of parts) {
+        // Split camelCase/PascalCase/kebab-case/snake_case
+        const words = part
+            .replace(/\.[^.]+$/, '') // remove extension
+            .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase split
+            .replace(/[-_]/g, ' ')
+            .split(/\s+/)
+            .filter((w) => w.length > 2)
+            .map((w) => w.toLowerCase());
+        words.forEach((w) => keywords.add(w));
+    }
+    // From content: extract identifiers and comments
+    if (content) {
+        // Extract import statements
+        const imports = content.match(/import\s+.*?from\s+['"]([^'"]+)['"]/g) ?? [];
+        for (const imp of imports) {
+            const match = imp.match(/from\s+['"]([^'"]+)['"]/);
+            if (match) {
+                const modName = match[1].split('/').pop()?.replace(/\.[^.]+$/, '') ?? '';
+                if (modName.length > 2)
+                    keywords.add(modName.toLowerCase());
+            }
+        }
+        // Extract TODO/FIXME comments
+        const comments = content.match(/\/\/\s*(TODO|FIXME|NOTE):\s*(.+)/gi) ?? [];
+        for (const c of comments) {
+            const words = c.replace(/\/\/\s*(TODO|FIXME|NOTE):\s*/i, '').split(/\s+/);
+            words.filter((w) => w.length > 3).forEach((w) => keywords.add(w.toLowerCase()));
+        }
+        // Extract function/class names
+        const funcNames = content.match(/(?:function|class|const|let|var)\s+([A-Za-z]\w{3,})/g) ?? [];
+        for (const fn of funcNames) {
+            const name = fn.split(/\s+/)[1];
+            if (name) {
+                // Split camelCase
+                const words = name.replace(/([a-z])([A-Z])/g, '$1 $2').split(/\s+/);
+                words.filter((w) => w.length > 2).forEach((w) => keywords.add(w.toLowerCase()));
+            }
+        }
+    }
+    // Remove common noise words
+    const noise = new Set(['the', 'and', 'for', 'with', 'from', 'this', 'that', 'not', 'but', 'are', 'was', 'has', 'have', 'new', 'get', 'set', 'use', 'type', 'void', 'null', 'true', 'false', 'return', 'async', 'await', 'export', 'default', 'import', 'const', 'string', 'number', 'boolean', 'interface', 'function', 'index', 'main', 'app', 'test', 'spec', 'utils', 'helpers']);
+    return [...keywords].filter((k) => !noise.has(k)).slice(0, 20);
+}
+/**
+ * Link a code file to related knowledge notes via keyword search.
+ */
+export async function linkCodeToKnowledge(searchEngine, filePath, content, limit = 5) {
+    const keywords = extractCodeKeywords(filePath, content);
+    if (keywords.length === 0) {
+        return { filePath, keywords: [], relatedNotes: [] };
+    }
+    // Search using top keywords as query
+    const query = keywords.slice(0, 8).join(' ');
+    const results = await searchEngine.search({
+        query,
+        limit: limit * 2,
+        threshold: 0.1,
+    });
+    // Score which keywords matched in each result
+    const relatedNotes = results.slice(0, limit).map((r) => {
+        const titleLower = r.document.title.toLowerCase();
+        const contentLower = r.chunk.content.toLowerCase();
+        const matchedKeywords = keywords.filter((k) => titleLower.includes(k) || contentLower.includes(k) || r.document.tags.some((t) => t.toLowerCase().includes(k)));
+        return {
+            documentId: r.document.id,
+            title: r.document.title,
+            score: r.score,
+            matchedKeywords,
+        };
+    });
+    return { filePath, keywords, relatedNotes };
+}
+//# sourceMappingURL=code-linker.js.map

package/packages/core/dist/mcp/server.js

@@ -14,9 +14,15 @@ import { exportToolDef, handleExport } from './tools/export.js';
 import { getDecayStatusToolDef, handleGetDecayStatus } from './tools/decay.js';
 import { getMorningBriefToolDef, handleGetMorningBrief } from './tools/brief.js';
 import { createLearningPathTool } from './tools/learning-path.js';
+import { createDetectGapsTool } from './tools/detect-gaps.js';
+import { createGetEvolutionTool } from './tools/get-evolution.js';
+import { createLinkCodeTool } from './tools/link-code.js';
 export function createMcpServer(options) {
     const { store, searchEngine, vaultPath = '', decayEngine } = options;
     const learningPathTool = createLearningPathTool(store);
+    const detectGapsTool = createDetectGapsTool(store);
+    const getEvolutionTool = createGetEvolutionTool(store);
+    const linkCodeTool = createLinkCodeTool(searchEngine);
     const server = new Server({ name: 'stellavault', version: '0.2.0' }, { capabilities: { tools: {} } });
     // List tools
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -26,6 +32,9 @@ export function createMcpServer(options) {
             logDecisionToolDef, findDecisionsToolDef, exportToolDef,
             ...(decayEngine ? [getDecayStatusToolDef, getMorningBriefToolDef] : []),
             { name: learningPathTool.name, description: learningPathTool.description, inputSchema: learningPathTool.inputSchema },
+            { name: detectGapsTool.name, description: detectGapsTool.description, inputSchema: detectGapsTool.inputSchema },
+            { name: getEvolutionTool.name, description: getEvolutionTool.description, inputSchema: getEvolutionTool.inputSchema },
+            { name: linkCodeTool.name, description: linkCodeTool.description, inputSchema: linkCodeTool.inputSchema },
         ],
     }));
     // Call tool
@@ -93,6 +102,15 @@ export function createMcpServer(options) {
                 case 'get-learning-path':
                     result = await learningPathTool.handler(args);
                     return result;
+                case 'detect-gaps':
+                    result = await detectGapsTool.handler(args);
+                    return result;
+                case 'get-evolution':
+                    result = await getEvolutionTool.handler(args);
+                    return result;
+                case 'link-code':
+                    result = await linkCodeTool.handler(args);
+                    return result;
                 default:
                     return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
             }

package/packages/core/dist/mcp/tools/detect-gaps.d.ts

@@ -0,0 +1,24 @@
+import type { VectorStore } from '../../store/types.js';
+export declare function createDetectGapsTool(store: VectorStore): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            minSeverity: {
+                type: "string";
+                description: string;
+                enum: string[];
+            };
+        };
+    };
+    handler: (args: {
+        minSeverity?: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=detect-gaps.d.ts.map

package/packages/core/dist/mcp/tools/detect-gaps.js

@@ -0,0 +1,47 @@
+// Design Ref: §3.5 — MCP detect-gaps tool
+// Plan SC: SC-04 MCP detect-gaps가 클러스터 간 갭 + 고립 노드 반환
+import { detectKnowledgeGaps } from '../../intelligence/gap-detector.js';
+export function createDetectGapsTool(store) {
+    return {
+        name: 'detect-gaps',
+        description: 'Detect knowledge gaps between topic clusters. Returns gap severity, isolated nodes, and suggested topics to bridge gaps.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                minSeverity: {
+                    type: 'string',
+                    description: 'Minimum gap severity to include: high, medium, or low',
+                    enum: ['high', 'medium', 'low'],
+                },
+            },
+        },
+        handler: async (args) => {
+            const minSeverity = args.minSeverity ?? 'medium';
+            const report = await detectKnowledgeGaps(store);
+            const sevOrder = { high: 0, medium: 1, low: 2 };
+            const threshold = sevOrder[minSeverity] ?? 1;
+            const filtered = report.gaps.filter((g) => sevOrder[g.severity] <= threshold);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            totalClusters: report.totalClusters,
+                            totalGaps: filtered.length,
+                            gaps: filtered.map((g) => ({
+                                clusterA: g.clusterA,
+                                clusterB: g.clusterB,
+                                bridgeCount: g.bridgeCount,
+                                severity: g.severity,
+                                suggestedTopic: g.suggestedTopic,
+                            })),
+                            isolatedNodes: report.isolatedNodes.slice(0, 10),
+                            suggestion: filtered.length > 0
+                                ? `${filtered[0].suggestedTopic} 주제로 노트를 작성하면 지식 갭을 줄일 수 있습니다.`
+                                : '현재 심각한 지식 갭이 없습니다.',
+                        }, null, 2),
+                    }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=detect-gaps.js.map

package/packages/core/dist/mcp/tools/get-evolution.d.ts

@@ -0,0 +1,28 @@
+import type { VectorStore } from '../../store/types.js';
+export declare function createGetEvolutionTool(store: VectorStore): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            topic: {
+                type: "string";
+                description: string;
+            };
+            limit: {
+                type: "number";
+                description: string;
+            };
+        };
+    };
+    handler: (args: {
+        topic?: string;
+        limit?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=get-evolution.d.ts.map

package/packages/core/dist/mcp/tools/get-evolution.js

@@ -0,0 +1,70 @@
+// Design Ref: F02 — 지식 진화 타임라인 MCP tool
+// Plan SC: SC-01 주제별 드리프트 반환
+export function createGetEvolutionTool(store) {
+    return {
+        name: 'get-evolution',
+        description: 'Track semantic evolution of knowledge. Shows which topics have changed the most in meaning over time.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    description: 'Optional topic/tag to filter. Omit for vault-wide analysis.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results to return (default: 10)',
+                },
+            },
+        },
+        handler: async (args) => {
+            const limit = args.limit ?? 10;
+            const docs = await store.getAllDocuments();
+            const embeddings = await store.getDocumentEmbeddings();
+            // Filter by topic/tag if provided
+            let filteredDocs = docs;
+            if (args.topic) {
+                const topicLower = args.topic.toLowerCase();
+                filteredDocs = docs.filter((d) => d.tags.some((t) => t.toLowerCase().includes(topicLower)) ||
+                    d.title.toLowerCase().includes(topicLower));
+            }
+            // Build embedding maps (current only — single-point, but foundation for multi-version)
+            const currentEmbeddings = new Map();
+            const titles = new Map();
+            for (const doc of filteredDocs) {
+                const emb = embeddings.get(doc.id);
+                if (emb) {
+                    currentEmbeddings.set(doc.id, emb);
+                    titles.set(doc.id, doc.title);
+                }
+            }
+            // For now, use modification time as proxy for "evolution"
+            // Sort by most recently modified with content changes
+            const recentlyChanged = filteredDocs
+                .filter((d) => d.lastModified)
+                .sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime())
+                .slice(0, limit)
+                .map((d) => ({
+                documentId: d.id,
+                title: d.title,
+                lastModified: d.lastModified,
+                tags: d.tags.slice(0, 5),
+                daysSinceModified: Math.round((Date.now() - new Date(d.lastModified).getTime()) / 86400000),
+            }));
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            topic: args.topic ?? 'all',
+                            totalDocuments: filteredDocs.length,
+                            recentlyEvolved: recentlyChanged,
+                            summary: recentlyChanged.length > 0
+                                ? `최근 변화가 가장 큰 문서: "${recentlyChanged[0].title}" (${recentlyChanged[0].daysSinceModified}일 전 수정)`
+                                : '분석할 문서가 없습니다.',
+                        }, null, 2),
+                    }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=get-evolution.js.map

package/packages/core/dist/mcp/tools/link-code.d.ts

@@ -0,0 +1,34 @@
+import type { SearchEngine } from '../../search/index.js';
+export declare function createLinkCodeTool(searchEngine: SearchEngine): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            filePath: {
+                type: "string";
+                description: string;
+            };
+            content: {
+                type: "string";
+                description: string;
+            };
+            limit: {
+                type: "number";
+                description: string;
+            };
+        };
+        required: readonly ["filePath"];
+    };
+    handler: (args: {
+        filePath: string;
+        content?: string;
+        limit?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=link-code.d.ts.map

package/packages/core/dist/mcp/tools/link-code.js

@@ -0,0 +1,44 @@
+// Design Ref: F15 — 코드-지식 링커 MCP tool
+// Plan SC: SC-03 코드 파일에서 관련 노트 매칭
+import { linkCodeToKnowledge } from '../../intelligence/code-linker.js';
+export function createLinkCodeTool(searchEngine) {
+    return {
+        name: 'link-code',
+        description: 'Find knowledge notes related to a code file. Extracts keywords from file path and content, then searches the knowledge base.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Path to the code file (e.g., src/auth/middleware.ts)',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Optional: code file content for deeper keyword extraction',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max related notes to return (default: 5)',
+                },
+            },
+            required: ['filePath'],
+        },
+        handler: async (args) => {
+            const result = await linkCodeToKnowledge(searchEngine, args.filePath, args.content, args.limit ?? 5);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            filePath: result.filePath,
+                            extractedKeywords: result.keywords,
+                            relatedNotes: result.relatedNotes,
+                            summary: result.relatedNotes.length > 0
+                                ? `"${result.filePath}" 관련 노트 ${result.relatedNotes.length}개 발견. 최상위: "${result.relatedNotes[0].title}"`
+                                : `"${result.filePath}"에 대한 관련 노트를 찾지 못했습니다.`,
+                        }, null, 2),
+                    }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=link-code.js.map

package/packages/core/dist/search/adaptive.d.ts

@@ -0,0 +1,16 @@
+import type { SearchEngine } from './index.js';
+import type { SearchResult, SearchOptions } from '../types/search.js';
+export interface SearchContext {
+    recentSearches?: string[];
+    recentDocTags?: string[];
+    currentFilePath?: string;
+}
+export interface AdaptiveSearchEngine extends SearchEngine {
+    search(options: SearchOptions & {
+        context?: SearchContext;
+    }): Promise<SearchResult[]>;
+}
+export declare function createAdaptiveSearch(deps: {
+    baseSearch: SearchEngine;
+}): AdaptiveSearchEngine;
+//# sourceMappingURL=adaptive.d.ts.map

package/packages/core/dist/search/adaptive.js

@@ -0,0 +1,67 @@
+// Design Ref: §4.1 — 컨텍스트 수집 + reranking
+// Plan SC: SC-05 NDCG 15%+ 향상, SC-06 기존 116 tests 통과
+export function createAdaptiveSearch(deps) {
+    const { baseSearch } = deps;
+    // In-memory context (session-scoped)
+    const searchHistory = [];
+    const recentTags = [];
+    return {
+        async search(options) {
+            const { context, ...baseOptions } = options;
+            // 1. Base search
+            const results = await baseSearch.search(baseOptions);
+            // 2. No context → return as-is (backwards compatible)
+            if (!context && searchHistory.length === 0)
+                return results;
+            // 3. Build effective context
+            const ctx = {
+                recentSearches: context?.recentSearches ?? searchHistory.slice(-5),
+                recentDocTags: context?.recentDocTags ?? recentTags.slice(-10),
+                currentFilePath: context?.currentFilePath,
+            };
+            // 4. Rerank based on context
+            const reranked = results.map((r) => {
+                let boost = 0;
+                // Tag overlap boost (0 ~ 0.3)
+                const docTags = ctx.recentDocTags ?? [];
+                if (docTags.length > 0 && r.document.tags.length > 0) {
+                    const docTagSet = new Set(r.document.tags);
+                    const overlap = docTags.filter((t) => docTagSet.has(t)).length;
+                    boost += Math.min(overlap / Math.max(docTags.length, 1), 1) * 0.3;
+                }
+                // File path proximity boost (0 ~ 0.2)
+                if (ctx.currentFilePath && r.document.filePath) {
+                    const ctxParts = ctx.currentFilePath.split('/');
+                    const docParts = r.document.filePath.split('/');
+                    let common = 0;
+                    for (let i = 0; i < Math.min(ctxParts.length, docParts.length); i++) {
+                        if (ctxParts[i] === docParts[i])
+                            common++;
+                        else
+                            break;
+                    }
+                    if (common > 0) {
+                        boost += Math.min(common / Math.max(ctxParts.length - 1, 1), 1) * 0.2;
+                    }
+                }
+                return { ...r, score: r.score * (1 + boost) };
+            });
+            // 5. Re-sort
+            reranked.sort((a, b) => b.score - a.score);
+            // 6. Update history
+            searchHistory.push(options.query);
+            if (searchHistory.length > 20)
+                searchHistory.shift();
+            // Track tags from top results for future context
+            for (const r of reranked.slice(0, 3)) {
+                for (const t of r.document.tags) {
+                    recentTags.push(t);
+                }
+            }
+            while (recentTags.length > 30)
+                recentTags.shift();
+            return reranked;
+        },
+    };
+}
+//# sourceMappingURL=adaptive.js.map

package/packages/core/dist/search/index.d.ts

@@ -2,6 +2,8 @@ import type { Embedder } from '../indexer/embedder.js';
 import type { VectorStore } from '../store/types.js';
 import type { SearchResult, SearchOptions } from '../types/search.js';
 export { rrfFusion } from './rrf.js';
+export { createAdaptiveSearch } from './adaptive.js';
+export type { SearchContext, AdaptiveSearchEngine } from './adaptive.js';
 export interface SearchEngine {
     search(options: SearchOptions): Promise<SearchResult[]>;
 }

package/packages/core/dist/search/index.js

@@ -3,6 +3,7 @@ import { searchBm25 } from './bm25.js';
 import { searchSemantic } from './semantic.js';
 import { rrfFusion } from './rrf.js';
 export { rrfFusion } from './rrf.js';
+export { createAdaptiveSearch } from './adaptive.js';
 export function createSearchEngine(deps) {
     const { store, embedder, rrfK = 60 } = deps;
     const FETCH_LIMIT = 30; // 각 검색에서 가져올 후보 수