stellavault 0.2.0 → 0.2.1

package/packages/core/dist/mcp/tools/agentic-graph.d.ts

@@ -0,0 +1,87 @@
+import type { VectorStore } from '../../store/types.js';
+import type { Embedder } from '../../indexer/embedder.js';
+export declare function createAgenticGraphTools(store: VectorStore, embedder: Embedder, vaultPath: string): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            type: {
+                type: string;
+                description: string;
+            };
+            folder: {
+                type: string;
+                description: string;
+            };
+            sourceTitle?: undefined;
+            targetTitle?: undefined;
+            context?: undefined;
+        };
+        required: string[];
+    };
+    handler(args: {
+        title: string;
+        content: string;
+        tags?: string[];
+        type?: string;
+        folder?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            sourceTitle: {
+                type: string;
+                description: string;
+            };
+            targetTitle: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            content?: undefined;
+            tags?: undefined;
+            type?: undefined;
+            folder?: undefined;
+        };
+        required: string[];
+    };
+    handler(args: {
+        sourceTitle: string;
+        targetTitle: string;
+        context?: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+})[];
+//# sourceMappingURL=agentic-graph.d.ts.map

package/packages/core/dist/mcp/tools/agentic-graph.js

@@ -0,0 +1,88 @@
+// Agentic Graph Construction (P3-F23)
+// AI가 MCP 세션 중 실시간으로 그래프 노드/엣지 생성
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export function createAgenticGraphTools(store, embedder, vaultPath) {
+    return [
+        {
+            name: 'create-knowledge-node',
+            description: 'Create a new knowledge note in the vault. AI agents use this to capture decisions, insights, or summaries during a conversation. The note is automatically indexed and appears in the knowledge graph.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Note title' },
+                    content: { type: 'string', description: 'Note content (markdown)' },
+                    tags: { type: 'array', items: { type: 'string' }, description: 'Tags for categorization' },
+                    type: { type: 'string', description: 'Note type: note, decision, insight, summary' },
+                    folder: { type: 'string', description: 'Vault subfolder (default: 01_Knowledge)' },
+                },
+                required: ['title', 'content'],
+            },
+            async handler(args) {
+                const { title, content, tags = [], type = 'note', folder = '01_Knowledge' } = args;
+                // frontmatter 생성
+                const date = new Date().toISOString().slice(0, 10);
+                const fm = [
+                    '---',
+                    `title: "${title}"`,
+                    `type: ${type}`,
+                    `source: agent`,
+                    `tags: [${tags.map(t => `"${t}"`).join(', ')}]`,
+                    `created: ${date}`,
+                    `auto_generated: true`,
+                    '---',
+                ].join('\n');
+                const fullContent = `${fm}\n\n# ${title}\n\n${content}`;
+                // vault에 파일 저장
+                const safeTitle = title.replace(/[<>:"/\\|?*]/g, '').replace(/\s+/g, ' ').trim().slice(0, 80);
+                const dir = join(vaultPath, folder);
+                mkdirSync(dir, { recursive: true });
+                const filePath = join(dir, `${safeTitle}.md`);
+                writeFileSync(filePath, fullContent, 'utf-8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Created knowledge node: "${title}" at ${folder}/${safeTitle}.md\nTags: ${tags.join(', ') || 'none'}\nType: ${type}\n\nRun 'stellavault index' to add to the graph.`,
+                        }],
+                };
+            },
+        },
+        {
+            name: 'create-knowledge-link',
+            description: 'Create a link between two existing notes by adding a wiki-link reference. Strengthens connections in the knowledge graph.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sourceTitle: { type: 'string', description: 'Title of the source note' },
+                    targetTitle: { type: 'string', description: 'Title of the target note to link to' },
+                    context: { type: 'string', description: 'Why these notes are related (added as a comment)' },
+                },
+                required: ['sourceTitle', 'targetTitle'],
+            },
+            async handler(args) {
+                const docs = await store.getAllDocuments();
+                const source = docs.find(d => d.title.toLowerCase().includes(args.sourceTitle.toLowerCase()));
+                if (!source) {
+                    return { content: [{ type: 'text', text: `Source note "${args.sourceTitle}" not found.` }] };
+                }
+                // 소스 노트에 링크 추가
+                const { readFileSync } = await import('node:fs');
+                const fullPath = join(vaultPath, source.filePath);
+                let existing = '';
+                try {
+                    existing = readFileSync(fullPath, 'utf-8');
+                }
+                catch { /* new file */ }
+                const linkSection = `\n\n## Related\n\n- [[${args.targetTitle}]]${args.context ? ` — ${args.context}` : ''}\n`;
+                writeFileSync(fullPath, existing + linkSection, 'utf-8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Linked "${source.title}" → "${args.targetTitle}"${args.context ? ` (${args.context})` : ''}`,
+                        }],
+                };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=agentic-graph.js.map

package/packages/core/dist/mcp/tools/brief.d.ts

@@ -0,0 +1,31 @@
+import type { DecayEngine } from '../../intelligence/decay-engine.js';
+import type { VectorStore } from '../../store/types.js';
+export declare const getMorningBriefToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+export declare function handleGetMorningBrief(decayEngine: DecayEngine, store: VectorStore): Promise<{
+    greeting: string;
+    summary: {
+        totalDocs: number;
+        averageR: number;
+        decaying: number;
+        critical: number;
+    };
+    reviewSuggestions: {
+        title: string;
+        retrievability: number;
+        daysSinceAccess: number;
+    }[];
+    unhealthyClusters: {
+        label: string;
+        avgR: number;
+        count: number;
+    }[];
+    tip: string;
+}>;
+//# sourceMappingURL=brief.d.ts.map

package/packages/core/dist/mcp/tools/brief.js

@@ -0,0 +1,39 @@
+// MCP tool: get-morning-brief — Claude 세션 시작 시 자동 브리핑
+export const getMorningBriefToolDef = {
+    name: 'get-morning-brief',
+    description: '오늘의 지식 브리핑을 제공합니다. 감쇠 상태, 리뷰 대상, 최근 활동을 요약합니다. 세션 시작 시 호출하면 유용합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+};
+export async function handleGetMorningBrief(decayEngine, store) {
+    const stats = await store.getStats();
+    const report = await decayEngine.computeAll();
+    const reviewList = report.topDecaying.slice(0, 5).map(d => ({
+        title: d.title,
+        retrievability: Math.round(d.retrievability * 100) / 100,
+        daysSinceAccess: d.daysSinceAccess,
+    }));
+    const unhealthyClusters = report.clusterHealth
+        .filter(c => c.avgR < 0.6)
+        .slice(0, 3)
+        .map(c => ({ label: c.label, avgR: c.avgR, count: c.count }));
+    return {
+        greeting: `📚 ${stats.documentCount}개 노트, 전체 건강도 R=${report.averageR}`,
+        summary: {
+            totalDocs: stats.documentCount,
+            averageR: report.averageR,
+            decaying: report.decayingCount,
+            critical: report.criticalCount,
+        },
+        reviewSuggestions: reviewList,
+        unhealthyClusters,
+        tip: report.criticalCount > 0
+            ? `⚠️ ${report.criticalCount}개 노트가 위험 수준입니다. 'stellavault review'로 리뷰하세요.`
+            : report.decayingCount > 0
+                ? `📋 ${report.decayingCount}개 노트가 감쇠 중입니다.`
+                : '✨ 모든 지식이 건강합니다!',
+    };
+}
+//# sourceMappingURL=brief.js.map

package/packages/core/dist/mcp/tools/decay.d.ts

@@ -0,0 +1,33 @@
+import type { DecayEngine } from '../../intelligence/decay-engine.js';
+export declare const getDecayStatusToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            threshold: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function handleGetDecayStatus(decayEngine: DecayEngine, args: {
+    threshold?: number;
+    limit?: number;
+}): Promise<{
+    count: number;
+    threshold: number;
+    notes: {
+        title: string;
+        retrievability: number;
+        stability: number;
+        lastAccess: string;
+    }[];
+    tip: string;
+}>;
+//# sourceMappingURL=decay.d.ts.map

package/packages/core/dist/mcp/tools/decay.js

@@ -0,0 +1,32 @@
+// Design Ref: §4.2 — MCP tool: get-decay-status
+// Plan SC: SC-04
+export const getDecayStatusToolDef = {
+    name: 'get-decay-status',
+    description: '잊어가는 지식 노트를 조회합니다. 기억 강도(retrievability)가 낮은 노트 목록을 반환하여 리마인드합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            threshold: { type: 'number', description: '감쇠 임계값 (0~1, default: 0.5). 이 값 이하인 노트를 반환' },
+            limit: { type: 'number', description: '반환할 최대 노트 수 (default: 20)' },
+        },
+    },
+};
+export async function handleGetDecayStatus(decayEngine, args) {
+    const threshold = args.threshold ?? 0.5;
+    const limit = args.limit ?? 20;
+    const decaying = await decayEngine.getDecaying(threshold, limit);
+    return {
+        count: decaying.length,
+        threshold,
+        notes: decaying.map(d => ({
+            title: d.title,
+            retrievability: Math.round(d.retrievability * 100) / 100,
+            stability: Math.round(d.stability * 10) / 10,
+            lastAccess: d.lastAccess,
+        })),
+        tip: decaying.length > 0
+            ? `${decaying.length}개의 노트를 잊어가고 있습니다. 리뷰를 권장합니다.`
+            : '모든 지식이 건강한 상태입니다!',
+    };
+}
+//# sourceMappingURL=decay.js.map

package/packages/core/dist/mcp/tools/decision-journal.d.ts

@@ -0,0 +1,78 @@
+export declare const logDecisionToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            decision: {
+                type: string;
+                description: string;
+            };
+            alternatives: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            reasoning: {
+                type: string;
+                description: string;
+            };
+            project: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const findDecisionsToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleLogDecision(vaultPath: string, args: {
+    title: string;
+    context?: string;
+    decision: string;
+    alternatives?: string[];
+    reasoning: string;
+    project?: string;
+}): Promise<{
+    saved: string;
+    fileName: string;
+}>;
+export declare function handleFindDecisions(vaultPath: string, args: {
+    query: string;
+}): Promise<{
+    decisions: never[];
+    message: string;
+    total?: undefined;
+} | {
+    decisions: {
+        file: string;
+        content: string;
+        score: number;
+    }[];
+    total: number;
+    message?: undefined;
+}>;
+//# sourceMappingURL=decision-journal.d.ts.map

package/packages/core/dist/mcp/tools/decision-journal.js

@@ -0,0 +1,79 @@
+// Design Ref: §12.1 F14 — 결정 저널 (기술 결정 자동 기록)
+import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const logDecisionToolDef = {
+    name: 'log-decision',
+    description: '기술적 결정을 구조화하여 기록합니다. 나중에 "왜 이 선택을 했지?"에 답변할 수 있습니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            title: { type: 'string', description: '결정 제목 (예: Zustand 대신 Jotai 선택)' },
+            context: { type: 'string', description: '결정 배경/상황' },
+            decision: { type: 'string', description: '선택한 내용' },
+            alternatives: { type: 'array', items: { type: 'string' }, description: '고려한 대안들' },
+            reasoning: { type: 'string', description: '선택 이유' },
+            project: { type: 'string', description: '관련 프로젝트명' },
+        },
+        required: ['title', 'decision', 'reasoning'],
+    },
+};
+export const findDecisionsToolDef = {
+    name: 'find-decisions',
+    description: '과거 기술 결정을 검색합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: '검색 쿼리' },
+        },
+        required: ['query'],
+    },
+};
+export async function handleLogDecision(vaultPath, args) {
+    const decisionsDir = join(vaultPath, 'decisions');
+    mkdirSync(decisionsDir, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const slug = args.title.replace(/[^a-zA-Z가-힣0-9\s-]/g, '').replace(/\s+/g, '-').slice(0, 50);
+    if (!slug)
+        throw new Error('Invalid decision title');
+    const fileName = `${date}-${slug}.md`;
+    const content = [
+        '---',
+        `title: "${args.title}"`,
+        `date: ${date}`,
+        `project: "${args.project ?? ''}"`,
+        'type: decision',
+        '---',
+        '',
+        `# ${args.title}`,
+        '',
+        args.context ? `## 배경\n\n${args.context}\n` : '',
+        `## 결정\n\n${args.decision}\n`,
+        args.alternatives?.length
+            ? `## 고려한 대안\n\n${args.alternatives.map(a => `- ${a}`).join('\n')}\n`
+            : '',
+        `## 이유\n\n${args.reasoning}\n`,
+    ].filter(Boolean).join('\n');
+    const filePath = resolve(decisionsDir, fileName);
+    if (!filePath.startsWith(resolve(decisionsDir))) {
+        throw new Error('Path traversal detected');
+    }
+    writeFileSync(filePath, content, 'utf-8');
+    return { saved: filePath, fileName };
+}
+export async function handleFindDecisions(vaultPath, args) {
+    const decisionsDir = join(vaultPath, 'decisions');
+    if (!existsSync(decisionsDir))
+        return { decisions: [], message: 'No decisions directory' };
+    const files = readdirSync(decisionsDir).filter(f => f.endsWith('.md'));
+    const query = args.query.toLowerCase();
+    const matches = files
+        .map(f => {
+        const content = readFileSync(join(decisionsDir, f), 'utf-8');
+        const score = content.toLowerCase().includes(query) ? 1 : 0;
+        return { file: f, content: content.slice(0, 300), score };
+    })
+        .filter(m => m.score > 0)
+        .slice(0, 10);
+    return { decisions: matches, total: files.length };
+}
+//# sourceMappingURL=decision-journal.js.map

package/packages/core/dist/mcp/tools/export.d.ts

@@ -0,0 +1,29 @@
+import type { VectorStore } from '../../store/types.js';
+export declare const exportToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            outputPath: {
+                type: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleExport(store: VectorStore, args: {
+    outputPath: string;
+    format?: string;
+}): Promise<{
+    exported: number;
+    path: string;
+    format: string;
+}>;
+//# sourceMappingURL=export.d.ts.map

package/packages/core/dist/mcp/tools/export.js

@@ -0,0 +1,60 @@
+// Design Ref: §12.1 F20 — 지식 내보내기 포맷 (락인 방지)
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+const ALLOWED_EXPORT_DIRS = [
+    resolve(homedir(), '.stellavault'),
+    resolve('.'),
+];
+function validateExportPath(outputPath) {
+    const resolved = resolve(outputPath);
+    const isAllowed = ALLOWED_EXPORT_DIRS.some(dir => resolved.startsWith(resolve(dir)));
+    if (!isAllowed) {
+        throw new Error(`Export path must be within current directory or ~/.stellavault/. Got: ${resolved}`);
+    }
+    return resolved;
+}
+export const exportToolDef = {
+    name: 'export',
+    description: '벡터 DB의 문서와 메타데이터를 JSON 파일로 내보냅니다. 다른 도구로 이전 가능.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            outputPath: { type: 'string', description: '출력 파일 경로 (예: ./export.json)' },
+            format: { type: 'string', enum: ['json', 'csv'], description: '출력 포맷 (기본: json)' },
+        },
+        required: ['outputPath'],
+    },
+};
+export async function handleExport(store, args) {
+    const docs = await store.getAllDocuments();
+    const stats = await store.getStats();
+    const topics = await store.getTopics();
+    const safePath = validateExportPath(args.outputPath);
+    mkdirSync(dirname(safePath), { recursive: true });
+    if (args.format === 'csv') {
+        const header = 'id,filePath,title,tags,lastModified,contentHash';
+        const rows = docs.map(d => `"${d.id}","${d.filePath}","${d.title.replace(/"/g, '""')}","${d.tags.join(';')}","${d.lastModified}","${d.contentHash}"`);
+        writeFileSync(safePath, [header, ...rows].join('\n'), 'utf-8');
+    }
+    else {
+        const exported = {
+            exportedAt: new Date().toISOString(),
+            version: '1.0',
+            stats,
+            topics,
+            documents: docs.map(d => ({
+                id: d.id,
+                filePath: d.filePath,
+                title: d.title,
+                tags: d.tags,
+                frontmatter: d.frontmatter,
+                lastModified: d.lastModified,
+                contentLength: d.content.length,
+            })),
+        };
+        writeFileSync(safePath, JSON.stringify(exported, null, 2), 'utf-8');
+    }
+    return { exported: docs.length, path: safePath, format: args.format ?? 'json' };
+}
+//# sourceMappingURL=export.js.map

package/packages/core/dist/mcp/tools/federated-search.d.ts

@@ -0,0 +1,29 @@
+import type { FederatedSearch } from '../../federation/search.js';
+export declare function createFederatedSearchTool(federatedSearch: FederatedSearch | null): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: {
+        query: string;
+        limit?: number;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=federated-search.d.ts.map

package/packages/core/dist/mcp/tools/federated-search.js

@@ -0,0 +1,36 @@
+// MCP Tool: federated-search (Federation Phase 1b)
+// AI 에이전트가 연합 네트워크를 검색
+export function createFederatedSearchTool(federatedSearch) {
+    return {
+        name: 'federated-search',
+        description: 'Search across all connected Federation peers. Returns results from other Stellavault nodes in the P2P network. Only titles, similarity scores, and 50-char snippets are shared — no raw text leaves any node.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                limit: { type: 'number', description: 'Max results per peer (default: 5)' },
+            },
+            required: ['query'],
+        },
+        async handler(args) {
+            if (!federatedSearch) {
+                return { content: [{ type: 'text', text: 'Federation not active. Run `sv federate join` first.' }] };
+            }
+            const results = await federatedSearch.search(args.query, { limit: args.limit ?? 5 });
+            if (results.length === 0) {
+                return { content: [{ type: 'text', text: 'No results from federation peers. Either no peers connected or no matching documents.' }] };
+            }
+            const lines = [
+                `🌐 Federation Search: "${args.query}" — ${results.length} results from ${new Set(results.map(r => r.peerId)).size} peers`,
+                '',
+            ];
+            for (const r of results) {
+                lines.push(`**${r.title}** (${Math.round(r.similarity * 100)}%) [${r.peerName}]`);
+                lines.push(`  ${r.snippet}...`);
+                lines.push('');
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        },
+    };
+}
+//# sourceMappingURL=federated-search.js.map

package/packages/core/dist/mcp/tools/generate-claude-md.d.ts

@@ -0,0 +1,35 @@
+import type { SearchEngine } from '../../search/index.js';
+import type { VectorStore } from '../../store/types.js';
+export declare const generateClaudeMdToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectName: {
+                type: string;
+                description: string;
+            };
+            topics: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGenerateClaudeMd(searchEngine: SearchEngine, store: VectorStore, args: {
+    projectName: string;
+    topics?: string[];
+}): Promise<{
+    content: string;
+    stats: {
+        queriesRun: number;
+        uniqueResults: number;
+        sections: string[];
+    };
+}>;
+//# sourceMappingURL=generate-claude-md.d.ts.map