@knowledgine/core 0.4.1 → 0.5.0

package/dist/storage/knowledge-repository.js

@@ -1,10 +1,25 @@
 import { ValidationError, DatabaseError, KnowledgeNotFoundError } from "../errors.js";
 import { createHash } from "crypto";
+const SUMMARY_COLUMNS = `id, file_path, title, created_at, updated_at, content_hash,
+  version, supersedes, valid_from, deprecated, deprecation_reason,
+  extracted_at, code_location_json`;
 export class KnowledgeRepository {
     db;
+    _stmtCache = new Map();
     constructor(db) {
         this.db = db;
     }
+    stmt(sql) {
+        let s = this._stmtCache.get(sql);
+        if (!s) {
+            s = this.db.prepare(sql);
+            this._stmtCache.set(sql, s);
+        }
+        return s;
+    }
+    clearStatementCache() {
+        this._stmtCache.clear();
+    }
     computeHash(content) {
         return createHash("sha256").update(content).digest("hex");
     }
@@ -34,23 +49,21 @@ export class KnowledgeRepository {
                 if (existing.content_hash === contentHash) {
                     return existing.id;
                 }
-                const stmt = this.db.prepare(`
+                this.stmt(`
           UPDATE knowledge_notes
           SET title = ?, content = ?, frontmatter_json = ?,
               updated_at = ?, content_hash = ?, code_location_json = ?
           WHERE id = ?
-        `);
-                stmt.run(data.title, data.content, frontmatterJson, now, contentHash, codeLocationJson, existing.id);
+        `).run(data.title, data.content, frontmatterJson, now, contentHash, codeLocationJson, existing.id);
                 return existing.id;
             }
             else {
-                const stmt = this.db.prepare(`
+                const info = this.stmt(`
           INSERT INTO knowledge_notes (
             file_path, title, content, frontmatter_json,
             created_at, updated_at, content_hash, code_location_json
           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-        `);
-                const info = stmt.run(data.filePath, data.title, data.content, frontmatterJson, data.createdAt || now, now, contentHash, codeLocationJson);
+        `).run(data.filePath, data.title, data.content, frontmatterJson, data.createdAt || now, now, contentHash, codeLocationJson);
                 return Number(info.lastInsertRowid);
             }
         }
@@ -61,12 +74,10 @@ export class KnowledgeRepository {
         }
     }
     getNoteById(id) {
-        const stmt = this.db.prepare("SELECT * FROM knowledge_notes WHERE id = ?");
-        return stmt.get(id);
+        return this.stmt("SELECT * FROM knowledge_notes WHERE id = ?").get(id);
     }
     getNoteByPath(filePath) {
-        const stmt = this.db.prepare("SELECT * FROM knowledge_notes WHERE file_path = ?");
-        return stmt.get(filePath);
+        return this.stmt("SELECT * FROM knowledge_notes WHERE file_path = ?").get(filePath);
     }
     getNoteByIdOrThrow(id) {
         const note = this.getNoteById(id);
@@ -82,26 +93,23 @@ export class KnowledgeRepository {
     }
     searchNotes(query, limit = 50) {
         try {
-            const stmt = this.db.prepare(`
+            return this.stmt(`
         SELECT n.*
         FROM knowledge_notes n
         JOIN knowledge_notes_fts fts ON n.id = fts.rowid
         WHERE knowledge_notes_fts MATCH ?
         ORDER BY rank
         LIMIT ?
-      `);
-            return stmt.all(query, limit);
+      `).all(query, limit);
         }
         catch {
             // FTS5失敗時はLIKEフォールバック（不正なクエリ構文への耐性）
-            const stmt = this.db.prepare(`SELECT * FROM knowledge_notes WHERE title LIKE ? OR content LIKE ? LIMIT ?`);
-            return stmt.all(`%${query}%`, `%${query}%`, limit);
+            return this.stmt(`SELECT * FROM knowledge_notes WHERE title LIKE ? OR content LIKE ? LIMIT ?`).all(`%${query}%`, `%${query}%`, limit);
         }
     }
     deleteNoteById(id) {
         try {
-            const stmt = this.db.prepare("DELETE FROM knowledge_notes WHERE id = ?");
-            const info = stmt.run(id);
+            const info = this.stmt("DELETE FROM knowledge_notes WHERE id = ?").run(id);
             return info.changes > 0;
         }
         catch (error) {
@@ -110,8 +118,7 @@ export class KnowledgeRepository {
     }
     deleteNoteByPath(path) {
         try {
-            const stmt = this.db.prepare("DELETE FROM knowledge_notes WHERE file_path = ?");
-            const info = stmt.run(path);
+            const info = this.stmt("DELETE FROM knowledge_notes WHERE file_path = ?").run(path);
             return info.changes > 0;
         }
         catch (error) {
@@ -126,18 +133,20 @@ export class KnowledgeRepository {
             throw new ValidationError("patterns", patterns, "Patterns must be an array");
         }
         try {
-            const deleteStmt = this.db.prepare("DELETE FROM extracted_patterns WHERE note_id = ?");
-            deleteStmt.run(noteId);
-            const insertStmt = this.db.prepare(`
-        INSERT INTO extracted_patterns (
-          note_id, pattern_type, content, confidence,
-          context, line_number, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?)
-      `);
             const now = new Date().toISOString();
-            for (const pattern of patterns) {
-                insertStmt.run(noteId, pattern.type, pattern.content, pattern.confidence, pattern.context ?? null, pattern.lineNumber ?? null, now);
-            }
+            const savePatternsTransaction = this.db.transaction(() => {
+                this.stmt("DELETE FROM extracted_patterns WHERE note_id = ?").run(noteId);
+                const insertSql = `
+          INSERT INTO extracted_patterns (
+            note_id, pattern_type, content, confidence,
+            context, line_number, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        `;
+                for (const pattern of patterns) {
+                    this.stmt(insertSql).run(noteId, pattern.type, pattern.content, pattern.confidence, pattern.context ?? null, pattern.lineNumber ?? null, now);
+                }
+            });
+            savePatternsTransaction();
         }
         catch (error) {
             if (error instanceof ValidationError)
@@ -146,42 +155,38 @@ export class KnowledgeRepository {
         }
     }
     getPatternsByNoteId(noteId) {
-        const stmt = this.db.prepare("SELECT * FROM extracted_patterns WHERE note_id = ? ORDER BY line_number");
-        return stmt.all(noteId);
+        return this.stmt("SELECT * FROM extracted_patterns WHERE note_id = ? ORDER BY line_number").all(noteId);
     }
     saveProblemSolutionPairs(pairs) {
-        const stmt = this.db.prepare(`
-      INSERT INTO problem_solution_pairs (
-        problem_pattern_id, solution_pattern_id, relevance_score, created_at
-      ) VALUES (?, ?, ?, ?)
-    `);
         const now = new Date().toISOString();
         for (const pair of pairs) {
-            stmt.run(pair.problemPatternId, pair.solutionPatternId, pair.relevanceScore, now);
+            this.stmt(`
+        INSERT INTO problem_solution_pairs (
+          problem_pattern_id, solution_pattern_id, relevance_score, created_at
+        ) VALUES (?, ?, ?, ?)
+      `).run(pair.problemPatternId, pair.solutionPatternId, pair.relevanceScore, now);
         }
     }
     saveNoteLinks(links) {
-        const stmt = this.db.prepare(`
-      INSERT OR REPLACE INTO note_links (
-        source_note_id, target_note_id, link_type, similarity, created_at
-      ) VALUES (?, ?, ?, ?, ?)
-    `);
         const now = new Date().toISOString();
         for (const link of links) {
-            stmt.run(link.sourceNoteId, link.targetNoteId, link.linkType, link.similarity ?? null, now);
+            this.stmt(`
+        INSERT OR REPLACE INTO note_links (
+          source_note_id, target_note_id, link_type, similarity, created_at
+        ) VALUES (?, ?, ?, ?, ?)
+      `).run(link.sourceNoteId, link.targetNoteId, link.linkType, link.similarity ?? null, now);
         }
     }
     getNoteLinks(noteId) {
-        const stmt = this.db.prepare(`
+        return this.stmt(`
       SELECT target_note_id as targetNoteId, link_type as linkType, similarity
       FROM note_links WHERE source_note_id = ?
       ORDER BY similarity DESC
-    `);
-        return stmt.all(noteId);
+    `).all(noteId);
     }
     getProblemSolutionPairsByNoteId(noteId) {
         // Join through extracted_patterns to find pairs associated with this note's patterns
-        const stmt = this.db.prepare(`
+        return this.stmt(`
       SELECT psp.id,
         ep_problem.note_id as problemNoteId,
         ep_solution.note_id as solutionNoteId,
@@ -192,8 +197,7 @@ export class KnowledgeRepository {
       JOIN extracted_patterns ep_problem ON psp.problem_pattern_id = ep_problem.id
       JOIN extracted_patterns ep_solution ON psp.solution_pattern_id = ep_solution.id
       WHERE ep_problem.note_id = ? OR ep_solution.note_id = ?
-    `);
-        return stmt.all(noteId, noteId);
+    `).all(noteId, noteId);
     }
     findNotesByTagSimilarity(noteId, tags, limit) {
         // Search notes that share tags via frontmatter_json
@@ -227,31 +231,36 @@ export class KnowledgeRepository {
         return stmt.all(noteId, createdAt, days, createdAt, limit);
     }
     getStats() {
-        const totalNotes = this.db.prepare("SELECT COUNT(*) as count FROM knowledge_notes").get().count;
-        const totalPatterns = this.db.prepare("SELECT COUNT(*) as count FROM extracted_patterns").get().count;
-        const totalLinks = this.db.prepare("SELECT COUNT(*) as count FROM note_links").get().count;
-        const totalPairs = this.db.prepare("SELECT COUNT(*) as count FROM problem_solution_pairs").get().count;
-        const typeRows = this.db
-            .prepare("SELECT pattern_type, COUNT(*) as count FROM extracted_patterns GROUP BY pattern_type")
-            .all();
+        const totalNotes = this.stmt("SELECT COUNT(*) as count FROM knowledge_notes").get().count;
+        const totalPatterns = this.stmt("SELECT COUNT(*) as count FROM extracted_patterns").get().count;
+        const totalLinks = this.stmt("SELECT COUNT(*) as count FROM note_links").get().count;
+        const totalPairs = this.stmt("SELECT COUNT(*) as count FROM problem_solution_pairs").get().count;
+        const typeRows = this.stmt("SELECT pattern_type, COUNT(*) as count FROM extracted_patterns GROUP BY pattern_type").all();
         const patternsByType = {};
         for (const row of typeRows) {
             patternsByType[row.pattern_type] = row.count;
         }
-        return { totalNotes, totalPatterns, totalLinks, totalPairs, patternsByType };
+        // Source breakdown (source_type may be NULL for pre-migration notes)
+        const sourceRows = this.db
+            .prepare("SELECT COALESCE(source_type, 'markdown') as source, COUNT(*) as count FROM knowledge_notes GROUP BY COALESCE(source_type, 'markdown')")
+            .all();
+        const notesBySource = {};
+        for (const row of sourceRows) {
+            notesBySource[row.source] = row.count;
+        }
+        return { totalNotes, totalPatterns, totalLinks, totalPairs, patternsByType, notesBySource };
     }
     /**
      * コードファイルパスで code_location_json を持つノートを検索する
      * path パラメータを含む code_location_json が NULL でないノートを返す
      */
     searchByCodeLocation(path) {
-        const stmt = this.db.prepare(`
+        return this.stmt(`
       SELECT * FROM knowledge_notes
       WHERE code_location_json IS NOT NULL
         AND code_location_json LIKE ?
       ORDER BY created_at DESC
-    `);
-        return stmt.all(`%${path}%`);
+    `).all(`%${path}%`);
     }
     /**
      * ノートの埋め込みベクトルを保存する（upsert）
@@ -259,31 +268,29 @@ export class KnowledgeRepository {
     saveEmbedding(noteId, embedding, modelName) {
         try {
             const now = new Date().toISOString();
-            const embBuf = Buffer.from(embedding.buffer);
-            // note_embeddings テーブルに upsert
-            const upsertStmt = this.db.prepare(`
-        INSERT INTO note_embeddings (note_id, embedding, model_name, dimensions, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?)
-        ON CONFLICT(note_id) DO UPDATE SET
-          embedding = excluded.embedding,
-          model_name = excluded.model_name,
-          dimensions = excluded.dimensions,
-          updated_at = excluded.updated_at
-      `);
-            upsertStmt.run(noteId, embBuf, modelName, embedding.length, now, now);
-            // note_embeddings_vec (vec0) が存在する場合は手動で同期
-            // vec0 は ON CONFLICT をサポートしないため DELETE + INSERT を使う
-            try {
-                this.db
-                    .prepare("DELETE FROM note_embeddings_vec WHERE note_id = CAST(? AS INTEGER)")
-                    .run(noteId);
-                this.db
-                    .prepare("INSERT INTO note_embeddings_vec(note_id, embedding) VALUES (CAST(? AS INTEGER), ?)")
-                    .run(noteId, embBuf);
-            }
-            catch {
-                // note_embeddings_vec が存在しない場合は無視（graceful degradation）
-            }
+            const embBuf = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+            const saveEmbeddingTransaction = this.db.transaction(() => {
+                // note_embeddings テーブルに upsert
+                this.stmt(`
+          INSERT INTO note_embeddings (note_id, embedding, model_name, dimensions, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?)
+          ON CONFLICT(note_id) DO UPDATE SET
+            embedding = excluded.embedding,
+            model_name = excluded.model_name,
+            dimensions = excluded.dimensions,
+            updated_at = excluded.updated_at
+        `).run(noteId, embBuf, modelName, embedding.length, now, now);
+                // note_embeddings_vec (vec0) が存在する場合は手動で同期
+                // vec0 は ON CONFLICT をサポートしないため DELETE + INSERT を使う
+                try {
+                    this.stmt("DELETE FROM note_embeddings_vec WHERE note_id = CAST(? AS INTEGER)").run(noteId);
+                    this.stmt("INSERT INTO note_embeddings_vec(note_id, embedding) VALUES (CAST(? AS INTEGER), ?)").run(noteId, embBuf);
+                }
+                catch {
+                    // note_embeddings_vec が存在しない場合は無視（graceful degradation）
+                }
+            });
+            saveEmbeddingTransaction();
         }
         catch (error) {
             if (error instanceof DatabaseError)
@@ -291,21 +298,96 @@ export class KnowledgeRepository {
             throw new DatabaseError("saveEmbedding", error, { noteId });
         }
     }
+    /**
+     * 複数ノートの埋め込みベクトルをバッチ保存する
+     * 100件単位のチャンクトランザクションで処理し、チャンク失敗時は1件ずつフォールバック
+     */
+    saveEmbeddingBatch(items) {
+        if (items.length === 0)
+            return { saved: 0, failed: 0 };
+        // vec0 利用可否を事前に1回だけチェック
+        let vec0Available = true;
+        try {
+            this.db.prepare("SELECT COUNT(*) FROM note_embeddings_vec").get();
+        }
+        catch {
+            vec0Available = false;
+        }
+        const CHUNK_SIZE = 100;
+        let saved = 0;
+        let failed = 0;
+        const now = new Date().toISOString();
+        const upsertStmt = this.stmt(`
+      INSERT INTO note_embeddings (note_id, embedding, model_name, dimensions, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(note_id) DO UPDATE SET
+        embedding = excluded.embedding,
+        model_name = excluded.model_name,
+        dimensions = excluded.dimensions,
+        updated_at = excluded.updated_at
+    `);
+        const vecDeleteStmt = vec0Available
+            ? this.stmt("DELETE FROM note_embeddings_vec WHERE note_id = CAST(? AS INTEGER)")
+            : null;
+        const vecInsertStmt = vec0Available
+            ? this.stmt("INSERT INTO note_embeddings_vec(note_id, embedding) VALUES (CAST(? AS INTEGER), ?)")
+            : null;
+        const saveOne = (item) => {
+            const embBuf = Buffer.from(item.embedding.buffer, item.embedding.byteOffset, item.embedding.byteLength);
+            upsertStmt.run(item.noteId, embBuf, item.modelName, item.embedding.length, now, now);
+            if (vec0Available && vecDeleteStmt && vecInsertStmt) {
+                try {
+                    vecDeleteStmt.run(item.noteId);
+                    vecInsertStmt.run(item.noteId, embBuf);
+                }
+                catch {
+                    // vec0 操作失敗は無視（graceful degradation）
+                }
+            }
+        };
+        for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+            const chunk = items.slice(i, i + CHUNK_SIZE);
+            try {
+                const chunkTransaction = this.db.transaction(() => {
+                    for (const item of chunk) {
+                        saveOne(item);
+                    }
+                });
+                chunkTransaction();
+                saved += chunk.length;
+            }
+            catch {
+                // チャンク失敗時は1件ずつフォールバック
+                for (const item of chunk) {
+                    try {
+                        const singleTransaction = this.db.transaction(() => {
+                            saveOne(item);
+                        });
+                        singleTransaction();
+                        saved++;
+                    }
+                    catch {
+                        failed++;
+                    }
+                }
+            }
+        }
+        return { saved, failed };
+    }
     /**
      * ベクトル類似度検索（note_embeddings_vec を使用）
      * sqlite-vec が利用できない場合は空配列を返す
      */
     searchByVector(embedding, limit = 10) {
         try {
-            const buf = Buffer.from(embedding.buffer);
-            const stmt = this.db.prepare(`
+            const buf = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+            return this.stmt(`
         SELECT note_id, distance
         FROM note_embeddings_vec
         WHERE embedding MATCH ?
         ORDER BY distance
         LIMIT ?
-      `);
-            return stmt.all(buf, limit);
+      `).all(buf, limit);
         }
         catch {
             // vec0テーブルが存在しない場合（sqlite-vec未ロード）は空を返す
@@ -324,72 +406,96 @@ export class KnowledgeRepository {
             dateParams.push(dateFrom);
         if (dateTo)
             dateParams.push(dateTo);
+        // CJK文字を含むクエリはtrigramテーブルを優先使用（trigramは最低3文字必要）
+        const hasCjk = /[\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF]/.test(query);
+        const useTrigram = hasCjk && query.length >= 3;
+        const ftsTable = useTrigram ? "knowledge_notes_fts_trigram" : "knowledge_notes_fts";
         try {
-            const stmt = this.db.prepare(`
-        SELECT n.*, fts.rank
+            const rows = this.stmt(`
+        SELECT n.*, bm25(${ftsTable}, 10.0, 1.0) AS rank
         FROM knowledge_notes n
-        JOIN knowledge_notes_fts fts ON n.id = fts.rowid
-        WHERE knowledge_notes_fts MATCH ?
+        JOIN ${ftsTable} fts ON n.id = fts.rowid
+        WHERE ${ftsTable} MATCH ?
         ${deprecatedFilter}
         ${dateFromFilter}
         ${dateToFilter}
         ORDER BY rank
         LIMIT ?
-      `);
-            const rows = stmt.all(query, ...dateParams, limit);
+      `).all(query, ...dateParams, limit);
+            // CJKクエリでunicode61が0件の場合はLIKEフォールバック（短いCJKトークンの救済）
+            if (rows.length === 0 && hasCjk) {
+                return this.searchNotesWithLike(query, limit, includeDeprecated, dateFrom, dateTo);
+            }
             return rows.map(({ rank, ...note }) => ({ note: note, rank }));
         }
         catch {
-            // FTS5失敗時はLIKEフォールバック（不正なクエリ構文への耐性）
-            const deprecatedClause = includeDeprecated ? "" : "AND n.deprecated = 0";
-            const fallbackStmt = this.db.prepare(`SELECT n.* FROM knowledge_notes n WHERE (n.title LIKE ? OR n.content LIKE ?) ${deprecatedClause} ${dateFromFilter} ${dateToFilter} LIMIT ?`);
-            const fallbackRows = fallbackStmt.all(`%${query}%`, `%${query}%`, ...dateParams, limit);
-            return fallbackRows.map((row) => ({ note: row, rank: 0 }));
+            return this.searchNotesWithLike(query, limit, includeDeprecated, dateFrom, dateTo);
         }
     }
+    searchNotesWithLike(query, limit, includeDeprecated, dateFrom, dateTo) {
+        const deprecatedClause = includeDeprecated ? "" : "AND n.deprecated = 0";
+        const dateFromFilter = dateFrom ? "AND n.created_at >= ?" : "";
+        const dateToFilter = dateTo ? "AND n.created_at <= ?" : "";
+        const dateParams = [];
+        if (dateFrom)
+            dateParams.push(dateFrom);
+        if (dateTo)
+            dateParams.push(dateTo);
+        const fallbackRows = this.stmt(`SELECT n.* FROM knowledge_notes n WHERE (n.title LIKE ? OR n.content LIKE ?) ${deprecatedClause} ${dateFromFilter} ${dateToFilter} LIMIT ?`).all(`%${query}%`, `%${query}%`, ...dateParams, limit);
+        return fallbackRows.map((row) => ({ note: row, rank: 0 }));
+    }
     /**
      * 埋め込みがまだ生成されていないノートを取得する
      */
     getNotesWithoutEmbeddings() {
-        const stmt = this.db.prepare(`
+        return this.stmt(`
       SELECT n.* FROM knowledge_notes n
       WHERE NOT EXISTS (SELECT 1 FROM note_embeddings e WHERE e.note_id = n.id)
-    `);
-        return stmt.all();
+    `).all();
     }
     /**
      * content_hashが変更されて埋め込みが古くなったノートを取得する
      */
     getNotesWithStaleEmbeddings() {
         // note_embeddingsのupdated_atとknowledge_notesのupdated_atを比較
-        const stmt = this.db.prepare(`
+        return this.stmt(`
       SELECT n.* FROM knowledge_notes n
       JOIN note_embeddings e ON e.note_id = n.id
       WHERE n.updated_at IS NOT NULL AND n.updated_at > e.created_at
-    `);
-        return stmt.all();
+    `).all();
     }
     /**
      * 指定プレフィックスで始まる file_path を持つノートを取得する
      */
     getNotesWithPrefix(prefix, limit = 100) {
-        const stmt = this.db.prepare("SELECT * FROM knowledge_notes WHERE file_path LIKE ? ORDER BY created_at DESC LIMIT ?");
-        return stmt.all(`${prefix}%`, limit);
+        return this.stmt("SELECT * FROM knowledge_notes WHERE file_path LIKE ? ORDER BY created_at DESC LIMIT ?").all(`${prefix}%`, limit);
     }
     /**
      * 全ノートを取得する
      */
     getAllNotes() {
-        const stmt = this.db.prepare("SELECT * FROM knowledge_notes");
-        return stmt.all();
+        return this.stmt("SELECT * FROM knowledge_notes").all();
+    }
+    /**
+     * 全ノートの ID のみを取得する（content をロードしないため OOM 対策）
+     */
+    getAllNoteIds() {
+        return this.stmt("SELECT id FROM knowledge_notes").pluck().all();
+    }
+    /**
+     * 埋め込みがまだ生成されていないノートの ID のみを取得する（OOM 対策）
+     */
+    getNotesWithoutEmbeddingIds() {
+        return this.stmt("SELECT n.id FROM knowledge_notes n WHERE NOT EXISTS (SELECT 1 FROM note_embeddings e WHERE e.note_id = n.id)")
+            .pluck()
+            .all();
     }
     /**
      * 特定のソースプラグインで作成されたノートを取得する
      * frontmatter_json 内の source_plugin フィールドで絞り込む
      */
     getNotesBySourcePlugin(pluginId) {
-        const stmt = this.db.prepare(`SELECT * FROM knowledge_notes WHERE frontmatter_json LIKE ?`);
-        return stmt.all(`%"source_plugin":"${pluginId}"%`);
+        return this.stmt(`SELECT * FROM knowledge_notes WHERE frontmatter_json LIKE ?`).all(`%"source_plugin":"${pluginId}"%`);
     }
     /**
      * 指定IDリストのノートを一括削除する
@@ -398,8 +504,9 @@ export class KnowledgeRepository {
         if (ids.length === 0)
             return 0;
         const placeholders = ids.map(() => "?").join(",");
-        const stmt = this.db.prepare(`DELETE FROM knowledge_notes WHERE id IN (${placeholders})`);
-        const info = stmt.run(...ids);
+        const info = this.db
+            .prepare(`DELETE FROM knowledge_notes WHERE id IN (${placeholders})`)
+            .run(...ids);
         return info.changes;
     }
     /**
@@ -407,68 +514,60 @@ export class KnowledgeRepository {
      */
     updateExtractedAt(noteId) {
         const now = new Date().toISOString();
-        this.db.prepare("UPDATE knowledge_notes SET extracted_at = ? WHERE id = ?").run(now, noteId);
+        this.stmt("UPDATE knowledge_notes SET extracted_at = ? WHERE id = ?").run(now, noteId);
     }
     /**
      * sourceUri プレフィックスでノートを取得する
      * file_path が sourceUri として使われている（normalizer.ts の仕様）
      */
     getNotesBySourceUriPrefix(prefix) {
-        const stmt = this.db.prepare("SELECT * FROM knowledge_notes WHERE file_path LIKE ? ORDER BY created_at ASC");
-        return stmt.all(`${prefix}%`);
+        return this.stmt("SELECT * FROM knowledge_notes WHERE file_path LIKE ? ORDER BY created_at ASC").all(`${prefix}%`);
     }
     /**
      * 既存リンクチェック後に note_links へ INSERT する（冪等）
      * 同じ source/target ペアが既に存在する場合は false を返す
      */
     saveNoteLinkIfNotExists(sourceNoteId, targetNoteId, linkType, similarity) {
-        const existing = this.db
-            .prepare("SELECT id FROM note_links WHERE source_note_id = ? AND target_note_id = ?")
-            .get(sourceNoteId, targetNoteId);
+        const existing = this.stmt("SELECT id FROM note_links WHERE source_note_id = ? AND target_note_id = ?").get(sourceNoteId, targetNoteId);
         if (existing)
             return false;
         const now = new Date().toISOString();
-        this.db
-            .prepare("INSERT INTO note_links (source_note_id, target_note_id, link_type, similarity, created_at) VALUES (?, ?, ?, ?, ?)")
-            .run(sourceNoteId, targetNoteId, linkType, similarity ?? null, now);
+        this.stmt("INSERT INTO note_links (source_note_id, target_note_id, link_type, similarity, created_at) VALUES (?, ?, ?, ?, ?)").run(sourceNoteId, targetNoteId, linkType, similarity ?? null, now);
         return true;
     }
     /**
      * 指定ノートに関するリンクをすべて取得する（source または target）
      */
     getLinksForNote(noteId) {
-        const stmt = this.db.prepare(`
+        return this.stmt(`
       SELECT id, source_note_id as sourceNoteId, target_note_id as targetNoteId,
              link_type as linkType, similarity, created_at as createdAt
       FROM note_links
       WHERE source_note_id = ? OR target_note_id = ?
       ORDER BY created_at DESC
-    `);
-        return stmt.all(noteId, noteId);
+    `).all(noteId, noteId);
     }
     /**
      * サジェスト結果へのフィードバックを保存する
      */
     saveSuggestFeedback(noteId, query, isUseful, context) {
         const now = new Date().toISOString();
-        const stmt = this.db.prepare(`
+        const info = this.stmt(`
       INSERT INTO suggest_feedback (note_id, query, is_useful, context, created_at)
       VALUES (?, ?, ?, ?, ?)
-    `);
-        const info = stmt.run(noteId, query, isUseful ? 1 : 0, context ?? null, now);
+    `).run(noteId, query, isUseful ? 1 : 0, context ?? null, now);
         return Number(info.lastInsertRowid);
     }
     /**
      * 特定ノートのサジェストフィードバック一覧を取得する（新しい順）
      */
     getSuggestFeedbackForNote(noteId) {
-        const stmt = this.db.prepare(`
+        const rows = this.stmt(`
       SELECT id, query, is_useful as isUseful, context, created_at as createdAt
       FROM suggest_feedback
       WHERE note_id = ?
       ORDER BY id DESC
-    `);
-        const rows = stmt.all(noteId);
+    `).all(noteId);
         return rows.map((row) => ({ ...row, isUseful: row.isUseful === 1 }));
     }
     /**
@@ -478,9 +577,7 @@ export class KnowledgeRepository {
         const note = this.getNoteById(noteId);
         if (!note)
             throw new KnowledgeNotFoundError(noteId, "id");
-        this.db
-            .prepare("UPDATE knowledge_notes SET deprecated = 1, deprecation_reason = ? WHERE id = ?")
-            .run(reason, noteId);
+        this.stmt("UPDATE knowledge_notes SET deprecated = 1, deprecation_reason = ? WHERE id = ?").run(reason, noteId);
     }
     /**
      * ノートの deprecated フラグを解除する
@@ -489,9 +586,7 @@ export class KnowledgeRepository {
         const note = this.getNoteById(noteId);
         if (!note)
             throw new KnowledgeNotFoundError(noteId, "id");
-        this.db
-            .prepare("UPDATE knowledge_notes SET deprecated = 0, deprecation_reason = NULL WHERE id = ?")
-            .run(noteId);
+        this.stmt("UPDATE knowledge_notes SET deprecated = 0, deprecation_reason = NULL WHERE id = ?").run(noteId);
     }
     /**
      * 既存ノートの新バージョンを作成する
@@ -514,23 +609,61 @@ export class KnowledgeRepository {
         const versionedPath = `${existing.file_path}#v${newVersion}`;
         const createNewVersion = this.db.transaction(() => {
             // deprecated にマーク
-            this.db
-                .prepare("UPDATE knowledge_notes SET deprecated = 1, deprecation_reason = ? WHERE id = ?")
-                .run(`Superseded by version ${newVersion}`, noteId);
+            this.stmt("UPDATE knowledge_notes SET deprecated = 1, deprecation_reason = ? WHERE id = ?").run(`Superseded by version ${newVersion}`, noteId);
             // 新バージョンを INSERT
-            const stmt = this.db.prepare(`
+            const info = this.stmt(`
         INSERT INTO knowledge_notes (
           file_path, title, content, frontmatter_json,
           created_at, updated_at, content_hash,
           version, supersedes, valid_from, deprecated
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
-      `);
-            const info = stmt.run(versionedPath, title, content, frontmatterJson, existing.created_at, now, contentHash, newVersion, noteId, now);
+      `).run(versionedPath, title, content, frontmatterJson, existing.created_at, now, contentHash, newVersion, noteId, now);
             return Number(info.lastInsertRowid);
         });
         return createNewVersion();
     }
+    /**
+     * 指定IDリストのノートをサマリー形式（content, frontmatter_jsonを除く）で一括取得する
+     * SQLITE_MAX_VARIABLE_NUMBER 対策として 500件ずつチャンク処理する
+     *
+     * **注意**: 返り順は入力 ids の順序と一致しない。順序が重要な場合は
+     * 呼び出し元で id→note の Map を構築してマッピングすること。
+     */
+    getNotesSummaryByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const CHUNK = 500;
+        const results = [];
+        for (let i = 0; i < ids.length; i += CHUNK) {
+            const chunk = ids.slice(i, i + CHUNK);
+            const placeholders = chunk.map(() => "?").join(",");
+            const stmt = this.db.prepare(`SELECT ${SUMMARY_COLUMNS} FROM knowledge_notes WHERE id IN (${placeholders})`);
+            results.push(...stmt.all(...chunk));
+        }
+        return results;
+    }
+    /**
+     * 指定IDリストのノートを全カラムで一括取得する
+     * SQLITE_MAX_VARIABLE_NUMBER 対策として 500件ずつチャンク処理する
+     *
+     * **注意**: 返り順は入力 ids の順序と一致しない。順序が重要な場合は
+     * 呼び出し元で id→note の Map を構築してマッピングすること。
+     */
+    getNotesByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const CHUNK = 500;
+        const results = [];
+        for (let i = 0; i < ids.length; i += CHUNK) {
+            const chunk = ids.slice(i, i + CHUNK);
+            const placeholders = chunk.map(() => "?").join(",");
+            const stmt = this.db.prepare(`SELECT * FROM knowledge_notes WHERE id IN (${placeholders})`);
+            results.push(...stmt.all(...chunk));
+        }
+        return results;
+    }
     close() {
+        this._stmtCache.clear();
         this.db.close();
     }
 }