stellavault 0.2.0 → 0.2.1

package/packages/core/dist/intelligence/contradiction-detector.js

@@ -0,0 +1,115 @@
+// Contradiction Detector (F-A12)
+// Finds potentially contradicting statements across notes
+// Uses embedding similarity + negation pattern detection
+// Negation/opposition patterns
+const NEGATION_PAIRS = [
+    ['should', 'should not'], ['must', 'must not'], ['always', 'never'],
+    ['best', 'worst'], ['good', 'bad'], ['correct', 'incorrect'],
+    ['true', 'false'], ['increase', 'decrease'], ['enable', 'disable'],
+    ['recommended', 'not recommended'], ['use', 'avoid'],
+    ['prefer', 'avoid'], ['do', "don't"], ['is', "isn't"],
+    ['can', "can't"], ['will', "won't"], ['important', 'unimportant'],
+    ['필요', '불필요'], ['해야', '하면 안'], ['좋', '나쁜'], ['맞', '틀'],
+];
+function extractKeyStatements(content) {
+    return content
+        .split(/[.\n!?]/)
+        .map(s => s.trim())
+        .filter(s => s.length > 20 && s.length < 200)
+        .filter(s => {
+        const lower = s.toLowerCase();
+        return /should|must|always|never|best|important|recommend|prefer|avoid|필요|해야|좋|나쁜/.test(lower);
+    })
+        .slice(0, 10); // max 10 statements per document
+}
+function detectNegationConflict(stmtA, stmtB) {
+    const a = stmtA.toLowerCase();
+    const b = stmtB.toLowerCase();
+    // Check negation pairs
+    for (const [pos, neg] of NEGATION_PAIRS) {
+        if ((a.includes(pos) && b.includes(neg)) || (a.includes(neg) && b.includes(pos))) {
+            // Check if they're talking about the same subject (share words)
+            const wordsA = new Set(a.split(/\s+/).filter(w => w.length > 3));
+            const wordsB = new Set(b.split(/\s+/).filter(w => w.length > 3));
+            const overlap = [...wordsA].filter(w => wordsB.has(w)).length;
+            const minSize = Math.min(wordsA.size, wordsB.size) || 1;
+            const subjectOverlap = overlap / minSize;
+            if (subjectOverlap > 0.2) {
+                return { isConflict: true, confidence: Math.min(0.5 + subjectOverlap * 0.5, 0.95), type: 'negation' };
+            }
+        }
+    }
+    // Check numeric value conflicts (e.g., "timeout should be 30s" vs "timeout should be 5s")
+    const numsA = a.match(/\d+/g);
+    const numsB = b.match(/\d+/g);
+    if (numsA && numsB) {
+        const wordsA = new Set(a.replace(/\d+/g, '').split(/\s+/).filter(w => w.length > 3));
+        const wordsB = new Set(b.replace(/\d+/g, '').split(/\s+/).filter(w => w.length > 3));
+        const overlap = [...wordsA].filter(w => wordsB.has(w)).length;
+        if (overlap >= 2 && numsA[0] !== numsB[0]) {
+            return { isConflict: true, confidence: 0.6, type: 'value_conflict' };
+        }
+    }
+    return { isConflict: false, confidence: 0, type: 'semantic' };
+}
+export async function detectContradictions(store, limit = 20) {
+    const docs = await store.getAllDocuments();
+    const embeddings = await store.getDocumentEmbeddings();
+    if (docs.length < 2)
+        return [];
+    // Build document vectors + key statements
+    const docData = new Map();
+    for (const doc of docs) {
+        const vec = embeddings.get(doc.id);
+        if (!vec)
+            continue;
+        const statements = extractKeyStatements(doc.content);
+        if (statements.length === 0)
+            continue;
+        docData.set(doc.id, { vec: Array.from(vec), title: doc.title, filePath: doc.filePath, statements });
+    }
+    const ids = [...docData.keys()];
+    const results = [];
+    // Compare documents with moderate similarity (same topic, possibly conflicting)
+    for (let i = 0; i < ids.length && results.length < limit * 3; i++) {
+        for (let j = i + 1; j < ids.length && results.length < limit * 3; j++) {
+            const a = docData.get(ids[i]);
+            const b = docData.get(ids[j]);
+            const sim = cosineSim(a.vec, b.vec);
+            // Sweet spot: similar enough to be same topic, not identical
+            if (sim < 0.3 || sim > 0.9)
+                continue;
+            // Compare statements
+            for (const stmtA of a.statements) {
+                for (const stmtB of b.statements) {
+                    const { isConflict, confidence, type } = detectNegationConflict(stmtA, stmtB);
+                    if (isConflict && confidence >= 0.5) {
+                        results.push({
+                            docA: { id: ids[i], title: a.title, filePath: a.filePath, statement: stmtA },
+                            docB: { id: ids[j], title: b.title, filePath: b.filePath, statement: stmtB },
+                            similarity: Math.round(sim * 1000) / 1000,
+                            confidence: Math.round(confidence * 100) / 100,
+                            type,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return results
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, limit);
+}
+function cosineSim(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const d = Math.sqrt(na) * Math.sqrt(nb);
+    return d === 0 ? 0 : dot / d;
+}
+//# sourceMappingURL=contradiction-detector.js.map

package/packages/core/dist/intelligence/decay-engine.d.ts

@@ -0,0 +1,27 @@
+import type { Database } from 'better-sqlite3';
+import type { DecayState, AccessEvent, DecayReport } from './types.js';
+export declare class DecayEngine {
+    private db;
+    constructor(db: Database);
+    private ensureTables;
+    /**
+     * Record an access event and update decay state.
+     */
+    recordAccess(event: AccessEvent): Promise<void>;
+    /**
+     * Batch compute retrievability for all documents.
+     */
+    computeAll(): Promise<DecayReport>;
+    private computeClusterHealth;
+    /**
+     * Get documents below decay threshold.
+     */
+    getDecaying(threshold?: number, limit?: number): Promise<Array<DecayState & {
+        title: string;
+    }>>;
+    /**
+     * Initialize decay state for documents that don't have one yet.
+     */
+    initializeNewDocuments(): Promise<number>;
+}
+//# sourceMappingURL=decay-engine.d.ts.map

package/packages/core/dist/intelligence/decay-engine.js

@@ -0,0 +1,190 @@
+// Design Ref: §3.2 — 감쇠 엔진 (DB 연동)
+// Plan SC: SC-01, SC-02, SC-04
+import { computeRetrievability, updateStability, estimateInitialStability, elapsedDays, FSRS_PARAMS, } from './fsrs.js';
+export class DecayEngine {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.ensureTables();
+    }
+    ensureTables() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS access_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        document_id TEXT NOT NULL,
+        access_type TEXT NOT NULL,
+        accessed_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_access_log_doc ON access_log(document_id);
+      CREATE INDEX IF NOT EXISTS idx_access_log_time ON access_log(accessed_at);
+
+      CREATE TABLE IF NOT EXISTS decay_state (
+        document_id TEXT PRIMARY KEY,
+        stability REAL NOT NULL DEFAULT 7.0,
+        difficulty REAL NOT NULL DEFAULT 5.0,
+        last_access TEXT NOT NULL,
+        retrievability REAL NOT NULL DEFAULT 1.0,
+        updated_at TEXT NOT NULL
+      );
+    `);
+    }
+    /**
+     * Record an access event and update decay state.
+     */
+    async recordAccess(event) {
+        const now = event.timestamp || new Date().toISOString();
+        // Log the event
+        this.db.prepare('INSERT INTO access_log (document_id, access_type, accessed_at) VALUES (?, ?, ?)').run(event.documentId, event.type, now);
+        // Get or create decay state
+        const existing = this.db.prepare('SELECT * FROM decay_state WHERE document_id = ?').get(event.documentId);
+        if (existing) {
+            const elapsed = elapsedDays(existing.last_access, now);
+            const currentR = computeRetrievability(existing.stability, elapsed);
+            const newS = updateStability(existing.stability, existing.difficulty, currentR);
+            this.db.prepare(`
+        UPDATE decay_state SET stability = ?, last_access = ?, retrievability = 1.0, updated_at = ?
+        WHERE document_id = ?
+      `).run(newS, now, now, event.documentId);
+        }
+        else {
+            // New document — estimate initial stability
+            const doc = this.db.prepare('SELECT content FROM documents WHERE id = ?').get(event.documentId);
+            const contentLen = doc?.content?.length ?? 500;
+            const connCount = this.db.prepare('SELECT COUNT(*) as c FROM chunks WHERE document_id = ?').get(event.documentId)?.c ?? 1;
+            const initS = estimateInitialStability(contentLen, connCount);
+            this.db.prepare(`
+        INSERT INTO decay_state (document_id, stability, difficulty, last_access, retrievability, updated_at)
+        VALUES (?, ?, ?, ?, 1.0, ?)
+      `).run(event.documentId, initS, FSRS_PARAMS.difficulty, now, now);
+        }
+    }
+    /**
+     * Batch compute retrievability for all documents.
+     */
+    async computeAll() {
+        const now = new Date().toISOString();
+        // Initialize documents that don't have decay state yet
+        await this.initializeNewDocuments();
+        // Compute R for all
+        const states = this.db.prepare('SELECT * FROM decay_state').all();
+        const docs = this.db.prepare('SELECT id, title FROM documents').all();
+        const titleMap = new Map(docs.map((d) => [d.id, d.title]));
+        const updated = [];
+        const updateStmt = this.db.prepare('UPDATE decay_state SET retrievability = ?, updated_at = ? WHERE document_id = ?');
+        const tx = this.db.transaction(() => {
+            for (const s of states) {
+                const elapsed = elapsedDays(s.last_access, now);
+                const r = computeRetrievability(s.stability, elapsed);
+                updateStmt.run(r, now, s.document_id);
+                updated.push({
+                    documentId: s.document_id,
+                    stability: s.stability,
+                    difficulty: s.difficulty,
+                    lastAccess: s.last_access,
+                    retrievability: r,
+                });
+            }
+        });
+        tx();
+        // Build report
+        const decaying = updated.filter(s => s.retrievability < 0.5);
+        const critical = updated.filter(s => s.retrievability < 0.3);
+        const avgR = updated.length > 0
+            ? updated.reduce((sum, s) => sum + s.retrievability, 0) / updated.length
+            : 1.0;
+        // Top decaying (sorted by R ascending)
+        const topDecaying = [...decaying]
+            .sort((a, b) => a.retrievability - b.retrievability)
+            .slice(0, 20)
+            .map(s => ({
+            ...s,
+            title: titleMap.get(s.documentId) ?? s.documentId,
+            daysSinceAccess: Math.round(elapsedDays(s.lastAccess, now)),
+        }));
+        // Cluster health
+        const clusterData = this.db.prepare(`
+      SELECT ds.document_id, ds.retrievability
+      FROM decay_state ds
+      JOIN documents d ON d.id = ds.document_id
+    `).all();
+        // Get cluster info from graph data cache (simplified: group by first folder)
+        const clusterHealth = this.computeClusterHealth(clusterData);
+        return {
+            totalDocuments: updated.length,
+            decayingCount: decaying.length,
+            criticalCount: critical.length,
+            averageR: Math.round(avgR * 100) / 100,
+            topDecaying,
+            clusterHealth,
+        };
+    }
+    computeClusterHealth(data) {
+        // Group by document's top-level folder as proxy for cluster
+        const groups = new Map();
+        for (const row of data) {
+            const doc = this.db.prepare('SELECT file_path FROM documents WHERE id = ?').get(row.document_id);
+            const folder = doc?.file_path?.split('/')[0] ?? 'unknown';
+            if (!groups.has(folder))
+                groups.set(folder, []);
+            groups.get(folder).push(row.retrievability);
+        }
+        return [...groups.entries()]
+            .map(([label, rs]) => ({
+            label,
+            avgR: Math.round((rs.reduce((a, b) => a + b, 0) / rs.length) * 100) / 100,
+            count: rs.length,
+        }))
+            .sort((a, b) => a.avgR - b.avgR);
+    }
+    /**
+     * Get documents below decay threshold.
+     */
+    async getDecaying(threshold = 0.5, limit = 20) {
+        await this.computeAll(); // refresh R values
+        const rows = this.db.prepare(`
+      SELECT ds.*, d.title FROM decay_state ds
+      JOIN documents d ON d.id = ds.document_id
+      WHERE ds.retrievability < ?
+      ORDER BY ds.retrievability ASC
+      LIMIT ?
+    `).all(threshold, limit);
+        return rows.map(r => ({
+            documentId: r.document_id,
+            stability: r.stability,
+            difficulty: r.difficulty,
+            lastAccess: r.last_access,
+            retrievability: r.retrievability,
+            title: r.title,
+        }));
+    }
+    /**
+     * Initialize decay state for documents that don't have one yet.
+     */
+    async initializeNewDocuments() {
+        const missing = this.db.prepare(`
+      SELECT d.id, d.content, d.last_modified
+      FROM documents d
+      LEFT JOIN decay_state ds ON d.id = ds.document_id
+      WHERE ds.document_id IS NULL
+    `).all();
+        if (missing.length === 0)
+            return 0;
+        const insert = this.db.prepare(`
+      INSERT OR IGNORE INTO decay_state (document_id, stability, difficulty, last_access, retrievability, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        const tx = this.db.transaction(() => {
+            for (const doc of missing) {
+                const contentLen = doc.content?.length ?? 500;
+                const initS = estimateInitialStability(contentLen, 1);
+                const lastAccess = doc.last_modified || new Date().toISOString();
+                const elapsed = elapsedDays(lastAccess);
+                const r = computeRetrievability(initS, elapsed);
+                insert.run(doc.id, initS, FSRS_PARAMS.difficulty, lastAccess, r, new Date().toISOString());
+            }
+        });
+        tx();
+        return missing.length;
+    }
+}
+//# sourceMappingURL=decay-engine.js.map

package/packages/core/dist/intelligence/duplicate-detector.d.ts

@@ -0,0 +1,20 @@
+import type { VectorStore } from '../store/types.js';
+export interface DuplicatePair {
+    docA: {
+        id: string;
+        title: string;
+        filePath: string;
+    };
+    docB: {
+        id: string;
+        title: string;
+        filePath: string;
+    };
+    similarity: number;
+}
+/**
+ * 벡터 유사도 기반 중복 노트 탐지.
+ * 문서별 평균 임베딩을 비교하여 threshold 이상인 쌍을 반환.
+ */
+export declare function detectDuplicates(store: VectorStore, threshold?: number, limit?: number): Promise<DuplicatePair[]>;
+//# sourceMappingURL=duplicate-detector.d.ts.map

package/packages/core/dist/intelligence/duplicate-detector.js

@@ -0,0 +1,55 @@
+// Design Ref: 중복/유사 노트 탐지
+// 기존 벡터 임베딩의 cosine similarity 활용
+/**
+ * 벡터 유사도 기반 중복 노트 탐지.
+ * 문서별 평균 임베딩을 비교하여 threshold 이상인 쌍을 반환.
+ */
+export async function detectDuplicates(store, threshold = 0.88, limit = 20) {
+    const docs = await store.getAllDocuments();
+    const embeddings = await store.getDocumentEmbeddings();
+    if (docs.length < 2)
+        return [];
+    // 문서별 평균 임베딩 계산
+    const docVecs = new Map();
+    for (const doc of docs) {
+        const vec = embeddings.get(doc.id);
+        if (!vec || vec.length === 0)
+            continue;
+        docVecs.set(doc.id, { vec: Array.from(vec), title: doc.title, filePath: doc.filePath });
+    }
+    const ids = [...docVecs.keys()];
+    const pairs = [];
+    // O(n²) — 1,200 문서면 ~720K 비교, 수 초 이내
+    for (let i = 0; i < ids.length; i++) {
+        for (let j = i + 1; j < ids.length; j++) {
+            const a = docVecs.get(ids[i]);
+            const b = docVecs.get(ids[j]);
+            const sim = cosineSimilarity(a.vec, b.vec);
+            if (sim >= threshold) {
+                pairs.push({
+                    docA: { id: ids[i], title: a.title, filePath: a.filePath },
+                    docB: { id: ids[j], title: b.title, filePath: b.filePath },
+                    similarity: Math.round(sim * 1000) / 1000,
+                });
+            }
+        }
+        if (pairs.length >= limit * 2)
+            break; // 충분히 찾으면 중단
+    }
+    return pairs
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, limit);
+}
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+//# sourceMappingURL=duplicate-detector.js.map

package/packages/core/dist/intelligence/fsrs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * FSRS parameters tuned for knowledge notes (not flashcards).
+ * Knowledge notes have longer natural retention than flashcards.
+ */
+export declare const FSRS_PARAMS: {
+    readonly initialStability: 7;
+    readonly difficulty: 5;
+    readonly a: 0.4;
+    readonly b: 0.6;
+    readonly c: 0.2;
+    readonly d: 1;
+    readonly sizeFactor: 0.5;
+    readonly connectionFactor: 1;
+};
+/**
+ * Compute retrievability R(t) using FSRS power forgetting curve.
+ * R(t) = (1 + t / (9 * S))^(-1)
+ *
+ * @param stabilityDays - Stability S (days until R drops to ~0.9)
+ * @param elapsedDays - Days since last access
+ * @returns Retrievability 0~1
+ */
+export declare function computeRetrievability(stabilityDays: number, elapsedDays: number): number;
+/**
+ * Update stability after an access event (successful recall).
+ * S' = S * (1 + a * D^(-b) * S^(-c) * (e^(d*(1-R)) - 1))
+ *
+ * @param currentS - Current stability
+ * @param difficulty - Note difficulty (1~10)
+ * @param currentR - Retrievability at access time
+ * @returns New stability (always >= currentS)
+ */
+export declare function updateStability(currentS: number, difficulty: number, currentR: number): number;
+/**
+ * Estimate initial stability based on note characteristics.
+ * Longer notes and more connected notes are more stable.
+ */
+export declare function estimateInitialStability(contentLength: number, connectionCount: number): number;
+/**
+ * Compute elapsed days between two ISO timestamps.
+ */
+export declare function elapsedDays(from: string, to?: string): number;
+//# sourceMappingURL=fsrs.d.ts.map

package/packages/core/dist/intelligence/fsrs.js

@@ -0,0 +1,70 @@
+// Design Ref: §1 — FSRS-6 알고리즘 (순수 함수)
+// Plan SC: SC-01 (R값 계산), SC-02 (stability 업데이트)
+/**
+ * FSRS parameters tuned for knowledge notes (not flashcards).
+ * Knowledge notes have longer natural retention than flashcards.
+ */
+export const FSRS_PARAMS = {
+    initialStability: 7.0, // 7 days for new notes
+    difficulty: 5.0, // default difficulty (1~10)
+    // Stability growth factors
+    a: 0.4,
+    b: 0.6,
+    c: 0.2,
+    d: 1.0,
+    // Stability bonus for large/connected notes
+    sizeFactor: 0.5, // additional days per 1000 chars
+    connectionFactor: 1.0, // additional days per connection
+};
+/**
+ * Compute retrievability R(t) using FSRS power forgetting curve.
+ * R(t) = (1 + t / (9 * S))^(-1)
+ *
+ * @param stabilityDays - Stability S (days until R drops to ~0.9)
+ * @param elapsedDays - Days since last access
+ * @returns Retrievability 0~1
+ */
+export function computeRetrievability(stabilityDays, elapsedDays) {
+    if (elapsedDays <= 0)
+        return 1.0;
+    if (stabilityDays <= 0)
+        return 0.0;
+    return Math.pow(1 + elapsedDays / (9 * stabilityDays), -1);
+}
+/**
+ * Update stability after an access event (successful recall).
+ * S' = S * (1 + a * D^(-b) * S^(-c) * (e^(d*(1-R)) - 1))
+ *
+ * @param currentS - Current stability
+ * @param difficulty - Note difficulty (1~10)
+ * @param currentR - Retrievability at access time
+ * @returns New stability (always >= currentS)
+ */
+export function updateStability(currentS, difficulty, currentR) {
+    const { a, b, c, d } = FSRS_PARAMS;
+    const growth = a
+        * Math.pow(difficulty, -b)
+        * Math.pow(currentS, -c)
+        * (Math.exp(d * (1 - currentR)) - 1);
+    const newS = currentS * (1 + Math.max(0, growth));
+    // Cap at 365 days (1 year max stability)
+    return Math.min(newS, 365);
+}
+/**
+ * Estimate initial stability based on note characteristics.
+ * Longer notes and more connected notes are more stable.
+ */
+export function estimateInitialStability(contentLength, connectionCount) {
+    const base = FSRS_PARAMS.initialStability;
+    const sizeBonus = Math.min(contentLength / 1000, 10) * FSRS_PARAMS.sizeFactor;
+    const connBonus = Math.min(connectionCount, 10) * FSRS_PARAMS.connectionFactor;
+    return base + sizeBonus + connBonus;
+}
+/**
+ * Compute elapsed days between two ISO timestamps.
+ */
+export function elapsedDays(from, to = new Date().toISOString()) {
+    const msPerDay = 86400000;
+    return Math.max(0, (new Date(to).getTime() - new Date(from).getTime()) / msPerDay);
+}
+//# sourceMappingURL=fsrs.js.map

package/packages/core/dist/intelligence/gap-detector.d.ts

@@ -0,0 +1,25 @@
+import type { VectorStore } from '../store/types.js';
+export interface KnowledgeGap {
+    clusterA: string;
+    clusterB: string;
+    bridgeCount: number;
+    suggestedTopic: string;
+    severity: 'high' | 'medium' | 'low';
+}
+export interface GapReport {
+    totalClusters: number;
+    totalGaps: number;
+    gaps: KnowledgeGap[];
+    isolatedNodes: Array<{
+        id: string;
+        title: string;
+        connections: number;
+    }>;
+}
+/**
+ * 그래프 데이터에서 지식 갭을 탐지.
+ * - 클러스터 간 연결이 약한 영역
+ * - 고립된 노드 (연결 0~1개)
+ */
+export declare function detectKnowledgeGaps(store: VectorStore, graphData?: any): Promise<GapReport>;
+//# sourceMappingURL=gap-detector.d.ts.map

package/packages/core/dist/intelligence/gap-detector.js

@@ -0,0 +1,78 @@
+// Design Ref: F01 — 지식 갭 탐지기
+// 클러스터 간 브릿지 노드 부족 영역 식별
+/**
+ * 그래프 데이터에서 지식 갭을 탐지.
+ * - 클러스터 간 연결이 약한 영역
+ * - 고립된 노드 (연결 0~1개)
+ */
+export async function detectKnowledgeGaps(store, graphData) {
+    const docs = await store.getAllDocuments();
+    const embeddings = await store.getDocumentEmbeddings();
+    // 그래프 데이터가 없으면 간단히 계산
+    if (!graphData) {
+        const { buildGraphData } = await import('../api/graph-data.js');
+        graphData = await buildGraphData(store);
+    }
+    const { nodes, edges, clusters } = graphData;
+    // 1. 클러스터 간 연결 수 매트릭스
+    const clusterEdges = new Map();
+    for (const edge of edges) {
+        const nodeA = nodes.find((n) => n.id === edge.source);
+        const nodeB = nodes.find((n) => n.id === edge.target);
+        if (!nodeA || !nodeB || nodeA.clusterId === nodeB.clusterId)
+            continue;
+        const key = [
+            Math.min(nodeA.clusterId, nodeB.clusterId),
+            Math.max(nodeA.clusterId, nodeB.clusterId),
+        ].join('-');
+        clusterEdges.set(key, (clusterEdges.get(key) ?? 0) + 1);
+    }
+    // 2. 갭 식별 (클러스터 쌍 중 연결이 적은 것)
+    const gaps = [];
+    const clusterLabels = new Map(clusters.map((c) => [c.id, c.label]));
+    for (let i = 0; i < clusters.length; i++) {
+        for (let j = i + 1; j < clusters.length; j++) {
+            const key = `${Math.min(clusters[i].id, clusters[j].id)}-${Math.max(clusters[i].id, clusters[j].id)}`;
+            const bridgeCount = clusterEdges.get(key) ?? 0;
+            // 연결이 3개 미만이면 갭
+            if (bridgeCount < 3) {
+                const labelA = clusterLabels.get(clusters[i].id) ?? `Cluster ${clusters[i].id}`;
+                const labelB = clusterLabels.get(clusters[j].id) ?? `Cluster ${clusters[j].id}`;
+                // 제안 주제: 두 클러스터 이름에서 추출
+                const nameA = labelA.replace(/\s*\(\d+\)$/, '');
+                const nameB = labelB.replace(/\s*\(\d+\)$/, '');
+                gaps.push({
+                    clusterA: labelA,
+                    clusterB: labelB,
+                    bridgeCount,
+                    suggestedTopic: `${nameA} + ${nameB} 연결 지식`,
+                    severity: bridgeCount === 0 ? 'high' : bridgeCount < 2 ? 'medium' : 'low',
+                });
+            }
+        }
+    }
+    // 3. 고립 노드 (연결 1개 이하)
+    const connectionCounts = new Map();
+    for (const edge of edges) {
+        connectionCounts.set(edge.source, (connectionCounts.get(edge.source) ?? 0) + 1);
+        connectionCounts.set(edge.target, (connectionCounts.get(edge.target) ?? 0) + 1);
+    }
+    const isolatedNodes = nodes
+        .filter((n) => (connectionCounts.get(n.id) ?? 0) <= 1)
+        .map((n) => ({
+        id: n.id,
+        title: n.label,
+        connections: connectionCounts.get(n.id) ?? 0,
+    }))
+        .slice(0, 20);
+    return {
+        totalClusters: clusters.length,
+        totalGaps: gaps.filter(g => g.severity !== 'low').length,
+        gaps: gaps.sort((a, b) => {
+            const sev = { high: 0, medium: 1, low: 2 };
+            return sev[a.severity] - sev[b.severity];
+        }).slice(0, 15),
+        isolatedNodes,
+    };
+}
+//# sourceMappingURL=gap-detector.js.map

package/packages/core/dist/intelligence/learning-path.d.ts

@@ -0,0 +1,31 @@
+import type { DecayReport } from './types.js';
+export interface LearningItem {
+    documentId: string;
+    title: string;
+    reason: string;
+    priority: 'critical' | 'important' | 'suggested';
+    score: number;
+    category: 'review' | 'explore' | 'bridge';
+}
+export interface LearningPath {
+    items: LearningItem[];
+    summary: {
+        reviewCount: number;
+        exploreCount: number;
+        bridgeCount: number;
+        estimatedMinutes: number;
+    };
+    generatedAt: string;
+}
+export interface LearningPathInput {
+    decayReport: DecayReport;
+    gaps?: Array<{
+        clusterA: string;
+        clusterB: string;
+        severity: string;
+        suggestedTopic: string;
+    }>;
+    recentSearches?: string[];
+}
+export declare function generateLearningPath(input: LearningPathInput, limit?: number): LearningPath;
+//# sourceMappingURL=learning-path.d.ts.map