@lotargo/memory_plugin 1.0.3 → 1.1.1

package/mcp-server/ingest/chunker.js

@@ -0,0 +1,337 @@
+import { splitSentencesMultilingual } from "./sentence_segmenter.js";
+
+export function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+// 1. BIG LEVEL: Heading & Section Hierarchy Parser
+export function parseSections(markdown, docTitle = "Document") {
+  const lines = markdown.split("\n");
+  const sections = [];
+  const headerStack = [];
+
+  let currentHeading = docTitle;
+  let currentLines = [];
+
+  function pushCurrentSection() {
+    const content = currentLines.join("\n").trim();
+    if (content.length > 0) {
+      const breadcrumbs = [docTitle, ...headerStack.map((h) => h.text)].join(" > ");
+      sections.push({
+        heading: currentHeading,
+        breadcrumbs,
+        content,
+        token_count: estimateTokens(content),
+      });
+    }
+    currentLines = [];
+  }
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+
+    if (headingMatch) {
+      pushCurrentSection();
+
+      const level = headingMatch[1].length;
+      const text = headingMatch[2].trim();
+
+      while (headerStack.length > 0 && headerStack[headerStack.length - 1].level >= level) {
+        headerStack.pop();
+      }
+
+      headerStack.push({ level, text });
+      currentHeading = text;
+    } else {
+      currentLines.push(line);
+    }
+  }
+
+  pushCurrentSection();
+
+  if (sections.length === 0) {
+    sections.push({
+      heading: docTitle,
+      breadcrumbs: docTitle,
+      content: markdown.trim(),
+      token_count: estimateTokens(markdown),
+    });
+  }
+
+  return sections;
+}
+
+// 2. MEDIUM LEVEL: Logical Paragraphs & Structural Block Extractor
+export function extractMediumBlocks(section, sectionId, docId) {
+  const content = section.content;
+  if (!content || content.trim().length === 0) return [];
+
+  const lines = content.split("\n");
+  const mediumBlocks = [];
+  let blockIndex = 0;
+
+  let currentLines = [];
+  let currentBlockType = "paragraph"; // 'paragraph', 'code', 'table', 'list', 'blockquote'
+
+  function pushCurrentBlock() {
+    const blockContent = currentLines.join("\n").trim();
+    if (blockContent.length > 0) {
+      mediumBlocks.push({
+        id: `${sectionId}_m${blockIndex++}`,
+        section_id: sectionId,
+        doc_id: docId,
+        breadcrumbs: section.breadcrumbs,
+        content: blockContent,
+        block_type: currentBlockType,
+        token_count: estimateTokens(blockContent),
+      });
+    }
+    currentLines = [];
+    currentBlockType = "paragraph";
+  }
+
+  let inFencedCode = false;
+  let codeFenceMarker = "";
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Check code fence
+    const fenceMatch = line.match(/^(\s*)(```|~~~)/);
+    if (fenceMatch) {
+      if (!inFencedCode) {
+        if (currentLines.length > 0) pushCurrentBlock();
+        inFencedCode = true;
+        codeFenceMarker = fenceMatch[2];
+        currentBlockType = "code";
+        currentLines.push(line);
+      } else {
+        currentLines.push(line);
+        if (line.includes(codeFenceMarker)) {
+          inFencedCode = false;
+          pushCurrentBlock();
+        }
+      }
+      continue;
+    }
+
+    if (inFencedCode) {
+      currentLines.push(line);
+      continue;
+    }
+
+    // Check table line
+    const isTableLine = /^\s*\|.*\|\s*$/.test(line);
+    if (isTableLine) {
+      if (currentBlockType !== "table" && currentLines.length > 0) {
+        pushCurrentBlock();
+      }
+      currentBlockType = "table";
+      currentLines.push(line);
+      continue;
+    } else if (currentBlockType === "table") {
+      pushCurrentBlock();
+    }
+
+    // Check list item line
+    const isListLine = /^\s*([*+-]|\d+\.)\s+/.test(line);
+    if (isListLine) {
+      if (currentBlockType !== "list" && currentBlockType !== "paragraph" && currentLines.length > 0) {
+        pushCurrentBlock();
+      }
+      currentBlockType = "list";
+      currentLines.push(line);
+      continue;
+    }
+
+    // Check empty line
+    if (line.trim().length === 0) {
+      if (currentLines.length > 0) {
+        pushCurrentBlock();
+      }
+      continue;
+    }
+
+    currentLines.push(line);
+  }
+
+  pushCurrentBlock();
+  return mediumBlocks;
+}
+
+// 3. SMALL LEVEL: Sentence & Smart AST/Table Chunk Extractor
+export function createSmallChunks(mediumBlock, sectionId, docId) {
+  const content = mediumBlock.content;
+  const tokenCount = mediumBlock.token_count || estimateTokens(content);
+  const smallChunks = [];
+  let smallIdx = 0;
+
+  function makeChunk(chunkText, extraMeta = {}) {
+    if (!chunkText || chunkText.trim().length === 0) return;
+    smallChunks.push({
+      id: `${mediumBlock.id}_s${smallIdx++}`,
+      medium_id: mediumBlock.id,
+      section_id: sectionId,
+      doc_id: docId,
+      content: chunkText.trim(),
+      breadcrumbs: mediumBlock.breadcrumbs,
+      token_count: estimateTokens(chunkText),
+      ...extraMeta,
+    });
+  }
+
+  // RULE FOR TABLES
+  if (mediumBlock.block_type === "table") {
+    if (tokenCount <= 350) {
+      makeChunk(content);
+      return smallChunks;
+    }
+
+    const lines = content.split("\n");
+    const headerLines = [];
+    const dataLines = [];
+
+    for (const l of lines) {
+      if (headerLines.length < 2 && (l.includes("|---") || l.includes("|:--") || headerLines.length === 0)) {
+        headerLines.push(l);
+      } else {
+        dataLines.push(l);
+      }
+    }
+
+    const headerStr = headerLines.join("\n");
+    const chunkSize = 8;
+    for (let i = 0; i < dataLines.length; i += chunkSize) {
+      const rowBatch = dataLines.slice(i, i + chunkSize);
+      const tableChunkText = `${headerStr}\n${rowBatch.join("\n")}`;
+      makeChunk(tableChunkText);
+    }
+    return smallChunks;
+  }
+
+  // RULE FOR CODE BLOCKS
+  if (mediumBlock.block_type === "code") {
+    if (tokenCount <= 350) {
+      makeChunk(content);
+      return smallChunks;
+    }
+
+    const codeLines = content.split("\n");
+    const firstLine = codeLines[0] || "";
+    const lastLine = codeLines[codeLines.length - 1] || "";
+    const isFenced = firstLine.startsWith("```") || firstLine.startsWith("~~~");
+    const fenceHeader = isFenced ? firstLine : "";
+    const fenceFooter = isFenced && (lastLine.startsWith("```") || lastLine.startsWith("~~~")) ? lastLine : "";
+
+    const bodyLines = isFenced ? codeLines.slice(1, -1) : codeLines;
+
+    const astBlocks = [];
+    let currentAstBlock = [];
+
+    for (const line of bodyLines) {
+      const isBoundary = /^\s*(?:export\s+|async\s+)?(?:function|class|def|pub\s+fn|fn|struct|interface|enum)\s+/.test(line);
+      if (isBoundary && currentAstBlock.length > 0) {
+        astBlocks.push(currentAstBlock.join("\n"));
+        currentAstBlock = [];
+      }
+      currentAstBlock.push(line);
+    }
+    if (currentAstBlock.length > 0) {
+      astBlocks.push(currentAstBlock.join("\n"));
+    }
+
+    for (const block of astBlocks) {
+      const fullChunk = fenceHeader ? `${fenceHeader}\n${block}\n${fenceFooter}` : block;
+      makeChunk(fullChunk);
+    }
+    return smallChunks;
+  }
+
+  // STANDARD SENTENCE SEGMENTATION WITH SAFE SENTENCE-WINDOWING (100-180 TOKENS, 1 SENTENCE OVERLAP)
+  const sentences = splitSentencesMultilingual(content);
+  if (sentences.length === 0 || tokenCount <= 180) {
+    makeChunk(content);
+    return smallChunks;
+  }
+
+  const TARGET_WINDOW_TOKENS = 150;
+  let currentWindow = [];
+  let currentTokens = 0;
+
+  for (let i = 0; i < sentences.length; i++) {
+    const sentence = sentences[i];
+    const sTokens = estimateTokens(sentence);
+
+    if (currentTokens + sTokens > TARGET_WINDOW_TOKENS && currentWindow.length > 0) {
+      makeChunk(currentWindow.join(" "));
+      
+      // Safe Overlap: Keep the last sentence of the previous window if available
+      const lastSentence = currentWindow[currentWindow.length - 1];
+      currentWindow = [lastSentence, sentence];
+      currentTokens = estimateTokens(lastSentence) + sTokens;
+    } else {
+      currentWindow.push(sentence);
+      currentTokens += sTokens;
+    }
+  }
+
+  if (currentWindow.length > 0) {
+    makeChunk(currentWindow.join(" "));
+  }
+
+  return smallChunks;
+}
+
+export function createMicroChunks(section, sectionId, docId) {
+  const mediumBlocks = extractMediumBlocks(section, sectionId, docId);
+  const microChunks = [];
+  for (const med of mediumBlocks) {
+    const smalls = createSmallChunks(med, sectionId, docId);
+    microChunks.push(...smalls);
+  }
+  return microChunks;
+}
+
+// 4. TRIPLE HIERARCHY BUILDER: Big -> Medium -> Small Reference Tree
+export function buildTripleHierarchy(markdown, docId, docTitle = "Document") {
+  const sectionsData = parseSections(markdown, docTitle);
+  const sections = [];
+  const mediumChunks = [];
+  const microChunks = [];
+  const tocTree = [];
+
+  sectionsData.forEach((sec, idx) => {
+    const sectionId = `${docId}_s${idx}`;
+    const sectionObj = {
+      id: sectionId,
+      doc_id: docId,
+      heading: sec.heading,
+      breadcrumbs: sec.breadcrumbs,
+      content: sec.content,
+      token_count: sec.token_count,
+    };
+    sections.push(sectionObj);
+
+    tocTree.push({
+      section_id: sectionId,
+      heading: sec.heading,
+      breadcrumbs: sec.breadcrumbs,
+    });
+
+    const mediums = extractMediumBlocks(sec, sectionId, docId);
+    mediumChunks.push(...mediums);
+
+    for (const med of mediums) {
+      const smalls = createSmallChunks(med, sectionId, docId);
+      microChunks.push(...smalls);
+    }
+  });
+
+  return {
+    toc: JSON.stringify(tocTree),
+    sections,
+    mediumChunks,
+    microChunks,
+  };
+}

package/mcp-server/ingest/exporter.js

@@ -0,0 +1,80 @@
+import { getDatabase } from "../db/database.js";
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { MEMORY_DIR } from "../memory.js";
+
+export const EXPORTS_DIR = join(MEMORY_DIR, "exports");
+
+export function ensureExportsDir() {
+  if (!existsSync(EXPORTS_DIR)) {
+    mkdirSync(EXPORTS_DIR, { recursive: true });
+  }
+  return EXPORTS_DIR;
+}
+
+export function exportDocumentData(docIdOrPath, customDb = null) {
+  const db = customDb || getDatabase();
+  const doc = db.prepare("SELECT * FROM documents WHERE id = ? OR path = ?").get(docIdOrPath, docIdOrPath);
+  if (!doc) {
+    throw new Error(`Document not found for ID or path: ${docIdOrPath}`);
+  }
+
+  let toc = null;
+  try {
+    toc = doc.toc_json ? JSON.parse(doc.toc_json) : null;
+  } catch {
+    toc = doc.toc_json;
+  }
+
+  let metadata = null;
+  try {
+    metadata = doc.metadata_json ? JSON.parse(doc.metadata_json) : null;
+  } catch {
+    metadata = doc.metadata_json;
+  }
+
+  const sections = db.prepare("SELECT id, heading, breadcrumbs, content, token_count FROM sections WHERE doc_id = ?").all(doc.id);
+  const mediumChunks = db.prepare("SELECT id, section_id, content, block_type, token_count, created_at FROM medium_chunks WHERE doc_id = ?").all(doc.id);
+  const microChunks = db.prepare("SELECT id, medium_id, section_id, content, token_count FROM micro_chunks WHERE doc_id = ?").all(doc.id);
+  const graphEdges = db.prepare("SELECT source_id, target_id, relation_type, metadata_json FROM graph_edges WHERE source_id = ? OR target_id = ?").all(doc.id, doc.id);
+
+  return {
+    document: {
+      id: doc.id,
+      path: doc.path,
+      title: doc.title,
+      blob_hash: doc.blob_hash,
+      checksum: doc.checksum,
+      toc,
+      metadata,
+      created_at: doc.created_at,
+      updated_at: doc.updated_at,
+    },
+    counts: {
+      sections: sections.length,
+      medium_chunks: mediumChunks.length,
+      micro_chunks: microChunks.length,
+      graph_edges: graphEdges.length,
+    },
+    sections,
+    medium_chunks: mediumChunks,
+    micro_chunks: microChunks,
+    graph_edges: graphEdges,
+  };
+}
+
+export function exportDocumentToJsonString(docIdOrPath, customDb = null) {
+  const data = exportDocumentData(docIdOrPath, customDb);
+  return JSON.stringify(data, null, 2);
+}
+
+export function exportDocumentToFile(docIdOrPath, outputPath = null, customDb = null) {
+  const targetDir = ensureExportsDir();
+  const db = customDb || getDatabase();
+  const data = exportDocumentData(docIdOrPath, db);
+  const jsonStr = JSON.stringify(data, null, 2);
+
+  const finalPath = outputPath || join(targetDir, `doc_export_${data.document.id}.json`);
+  writeFileSync(finalPath, jsonStr, "utf-8");
+  return finalPath;
+}

package/mcp-server/ingest/normalizer.js

@@ -0,0 +1,104 @@
+import { basename, extname } from "node:path";
+
+export function cleanHtml(html) {
+  if (!html) return "";
+
+  let cleaned = html.replace(/<(script|style|nav|header|footer|svg|noscript)[^>]*>[\s\S]*?<\/\1>/gi, "");
+
+  cleaned = cleaned.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n# $1\n");
+  cleaned = cleaned.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n## $1\n");
+  cleaned = cleaned.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n### $1\n");
+  cleaned = cleaned.replace(/<h[4-6][^>]*>([\s\S]*?)<\/h[4-6]>/gi, "\n#### $1\n");
+
+  cleaned = cleaned.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "\n- $1");
+  cleaned = cleaned.replace(/<(p|div|br)[^>]*>/gi, "\n");
+
+  cleaned = cleaned.replace(/<[^>]+>/g, "");
+
+  cleaned = cleaned
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+
+  cleaned = cleaned.replace(/\n\s*\n\s*\n/g, "\n\n").trim();
+  return cleaned;
+}
+
+export function extractTitle(markdown, fallbackName = "Untitled Document") {
+  const h1Match = markdown.match(/^#\s+(.+)$/m);
+  if (h1Match && h1Match[1].trim()) {
+    return h1Match[1].trim();
+  }
+  return fallbackName;
+}
+
+export function stripMarkdownBadgesAndNoise(text) {
+  if (!text) return "";
+  let cleaned = text;
+
+  // 1. Remove markdown link-wrapped badges: [![alt](image_url)](link_url)
+  cleaned = cleaned.replace(/\[\s*!\[[^\]]*\]\([^)]+\)\s*\]\([^)]+\)/g, "");
+
+  // 2. Remove standalone markdown image badges: ![alt](https://img.shields.io/...) or badge URLs
+  cleaned = cleaned.replace(/!\[[^\]]*\]\([^)]*(?:shields\.io|badge|actions\/workflows|codecov|travis-ci)[^)]*\)/gi, "");
+
+  // 3. Remove raw HTML img badge tags
+  cleaned = cleaned.replace(/<img[^>]*(?:shields\.io|badge|workflows|badge\.svg)[^>]*>/gi, "");
+
+  // 4. Remove empty HTML anchor containers often surrounding badges
+  cleaned = cleaned.replace(/<a[^>]*>\s*<\/a>/gi, "");
+
+  // 5. Normalize excessive blank lines
+  cleaned = cleaned.replace(/\n\s*\n\s*\n+/g, "\n\n").trim();
+  return cleaned;
+}
+
+export function normalizeContent({ content, type = "text", path = null, title = null }) {
+  let markdown = "";
+  let docTitle = title;
+  const fileName = path ? basename(path) : "document";
+
+  if (type === "url" || (typeof content === "string" && /<html|<body|<div/i.test(content))) {
+    markdown = cleanHtml(content);
+    docTitle = title || extractTitle(markdown, fileName);
+  } else if (type === "file" && path) {
+    const ext = extname(path).toLowerCase();
+    const codeLangs = {
+      ".js": "javascript",
+      ".ts": "typescript",
+      ".py": "python",
+      ".json": "json",
+      ".yaml": "yaml",
+      ".yml": "yaml",
+      ".css": "css",
+      ".html": "html",
+    };
+
+    if (codeLangs[ext]) {
+      markdown = `# ${fileName}\n\n\`\`\`${codeLangs[ext]}\n${content.trim()}\n\`\`\``;
+      docTitle = title || fileName;
+    } else {
+      markdown = content.trim();
+      docTitle = title || extractTitle(markdown, fileName);
+    }
+  } else {
+    markdown = typeof content === "string" ? content.trim() : String(content);
+    docTitle = title || extractTitle(markdown, "Direct Note");
+  }
+
+  // Apply noise and badge stripping to all developer documentation
+  markdown = stripMarkdownBadgesAndNoise(markdown);
+
+  return {
+    markdown,
+    title: docTitle,
+    metadata: {
+      source_type: type,
+      original_path: path || null,
+      char_count: markdown.length,
+    },
+  };
+}

package/mcp-server/ingest/pipeline.js

@@ -0,0 +1,164 @@
+import { randomUUID } from "node:crypto";
+import { getDatabase, BLOBS_DIR } from "../db/database.js";
+import { saveBlob, deleteBlob } from "../storage/blob_store.js";
+import { normalizeContent } from "./normalizer.js";
+import { buildTripleHierarchy } from "./chunker.js";
+import { embedText, vectorToBuffer } from "../ml/model_manager.js";
+import { buildGraphEdges, saveGraphEdges } from "../graph/graph_extractor.js";
+
+export async function ingestDocument({
+  content,
+  type = "text",
+  path = null,
+  title = null,
+  customDb = null,
+  customBlobDir = BLOBS_DIR,
+  generateEmbeddings = true,
+}) {
+  const db = customDb || getDatabase();
+
+  const { markdown, title: docTitle, metadata } = normalizeContent({ content, type, path, title });
+
+  const blobRes = await saveBlob(markdown, customBlobDir);
+  const blobHash = blobRes.hash;
+
+  const docId = `doc_${randomUUID().replace(/-/g, "").substring(0, 12)}`;
+  const docPath = path || `virtual://${type}/${docId}`;
+  const now = Date.now();
+
+  const hierarchy = buildTripleHierarchy(markdown, docId, docTitle);
+
+  if (generateEmbeddings) {
+    for (const micro of hierarchy.microChunks) {
+      const contextualText = micro.breadcrumbs
+        ? `${micro.content}\n\nContext: ${docTitle} > ${micro.breadcrumbs}`
+        : `${micro.content}\n\nContext: ${docTitle}`;
+      const vec = await embedText(contextualText, false);
+      micro.vector = vectorToBuffer(vec);
+    }
+  } else {
+    for (const micro of hierarchy.microChunks) {
+      micro.vector = Buffer.alloc(384 * 4);
+    }
+  }
+
+  db.exec("BEGIN IMMEDIATE;");
+  try {
+    const existingDoc = db.prepare("SELECT id FROM documents WHERE path = ?").get(docPath);
+    if (existingDoc) {
+      const microChunks = db.prepare("SELECT id FROM micro_chunks WHERE doc_id = ?").all(existingDoc.id);
+      for (const mc of microChunks) {
+        try {
+          db.prepare("DELETE FROM micro_chunks_fts WHERE id = ?").run(mc.id);
+        } catch {}
+      }
+      db.prepare("DELETE FROM graph_edges WHERE source_id = ? OR target_id = ?").run(existingDoc.id, existingDoc.id);
+      db.prepare("DELETE FROM documents WHERE id = ?").run(existingDoc.id);
+    }
+
+    db.prepare(`
+      INSERT INTO documents (id, path, blob_hash, title, checksum, toc_json, metadata_json, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?);
+    `).run(
+      docId,
+      docPath,
+      blobHash,
+      docTitle,
+      blobHash,
+      hierarchy.toc,
+      JSON.stringify(metadata),
+      now,
+      now
+    );
+
+    const insertSectionStmt = db.prepare(`
+      INSERT INTO sections (id, doc_id, heading, breadcrumbs, content, token_count)
+      VALUES (?, ?, ?, ?, ?, ?);
+    `);
+    for (const sec of hierarchy.sections) {
+      insertSectionStmt.run(sec.id, sec.doc_id, sec.heading, sec.breadcrumbs, sec.content, sec.token_count);
+    }
+
+    if (hierarchy.mediumChunks && hierarchy.mediumChunks.length > 0) {
+      const insertMediumStmt = db.prepare(`
+        INSERT INTO medium_chunks (id, section_id, doc_id, content, block_type, token_count, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?);
+      `);
+      for (const med of hierarchy.mediumChunks) {
+        insertMediumStmt.run(med.id, med.section_id, med.doc_id, med.content, med.block_type, med.token_count, now);
+      }
+    }
+
+    const insertMicroStmt = db.prepare(`
+      INSERT INTO micro_chunks (id, section_id, doc_id, content, vector, token_count, medium_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?);
+    `);
+    const insertFtsStmt = db.prepare(`
+      INSERT INTO micro_chunks_fts (id, content, breadcrumbs)
+      VALUES (?, ?, ?);
+    `);
+
+    for (const micro of hierarchy.microChunks) {
+      insertMicroStmt.run(micro.id, micro.section_id, micro.doc_id, micro.content, micro.vector, micro.token_count, micro.medium_id || null);
+      insertFtsStmt.run(micro.id, micro.content, micro.breadcrumbs);
+    }
+
+    const edges = buildGraphEdges(docId, hierarchy);
+    saveGraphEdges(db, edges);
+
+    db.exec("COMMIT;");
+  } catch (err) {
+    db.exec("ROLLBACK;");
+    throw new Error(`Ingestion transaction failed: ${err.message}`);
+  }
+
+  return {
+    docId,
+    doc_id: docId,
+    path: docPath,
+    blobHash,
+    blob_hash: blobHash,
+    title: docTitle,
+    sectionsCount: hierarchy.sections.length,
+    sections_count: hierarchy.sections.length,
+    microChunksCount: hierarchy.microChunks.length,
+    micro_chunks_count: hierarchy.microChunks.length,
+    deduplicated: blobRes.deduplicated,
+  };
+}
+
+export async function deleteDocument(docIdOrPath, customDb = null, customBlobDir = BLOBS_DIR) {
+  const db = customDb || getDatabase();
+  const doc = db.prepare("SELECT * FROM documents WHERE id = ? OR path = ?").get(docIdOrPath, docIdOrPath);
+  if (!doc) {
+    return { deleted: false, reason: "Document not found" };
+  }
+
+  const microChunks = db.prepare("SELECT id FROM micro_chunks WHERE doc_id = ?").all(doc.id);
+
+  db.exec("BEGIN IMMEDIATE;");
+  try {
+    for (const mc of microChunks) {
+      try {
+        db.prepare("DELETE FROM micro_chunks_fts WHERE id = ?").run(mc.id);
+      } catch {}
+    }
+
+    db.prepare("DELETE FROM graph_edges WHERE source_id = ? OR target_id = ?").run(doc.id, doc.id);
+    db.prepare("DELETE FROM documents WHERE id = ?").run(doc.id);
+
+    db.exec("COMMIT;");
+  } catch (err) {
+    db.exec("ROLLBACK;");
+    throw err;
+  }
+
+  if (doc.blob_hash) {
+    const refCount = db.prepare("SELECT COUNT(*) as cnt FROM documents WHERE blob_hash = ?").get(doc.blob_hash).cnt;
+    if (refCount === 0) {
+      await deleteBlob(doc.blob_hash, customBlobDir);
+    }
+  }
+
+  return { deleted: true, docId: doc.id, title: doc.title };
+}