akm-cli 0.7.5 → 0.8.0-rc.3

package/dist/indexer/graph-dedup.js

@@ -0,0 +1,99 @@
+/**
+ * Pure graph deduplication utility — no LLM calls, no I/O.
+ *
+ * Extracted from src/llm/graph-extract.ts so it can be imported by
+ * src/indexer/graph-extraction.ts without being replaced by test mocks
+ * that stub the LLM layer.
+ */
+function normalizeRelationType(raw) {
+    const normalized = raw?.trim().toLowerCase().replace(/\s+/g, " ") ?? "";
+    if (!normalized)
+        return "";
+    if (normalized === "use" || normalized === "utilizes")
+        return "uses";
+    if (normalized === "depend on" || normalized === "depends")
+        return "depends on";
+    if (normalized === "integrates" || normalized === "integration with")
+        return "integrates with";
+    return normalized;
+}
+function normalizeConfidence(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return undefined;
+    return Math.max(0, Math.min(1, raw));
+}
+/**
+ * Merge and deduplicate entities and relations from multiple per-asset
+ * GraphExtraction results into one canonical graph.
+ *
+ * Entities are keyed on their lowercased, trimmed form. The first-seen
+ * casing is preserved as canonical. Relations are keyed on
+ * `(from, to, type)` (all lowercased). Dangling relations — those whose
+ * `from` or `to` is absent from the deduplicated entity set — are dropped.
+ */
+export function deduplicateGraph(extractions, assetRefs) {
+    const entityCanonical = new Map();
+    const entitySources = new Map();
+    for (let i = 0; i < extractions.length; i++) {
+        const ref = assetRefs?.[i] ?? "unknown";
+        for (const raw of extractions[i].entities) {
+            const trimmed = raw.trim();
+            if (!trimmed)
+                continue;
+            const normalized = trimmed.toLowerCase();
+            if (!entityCanonical.has(normalized)) {
+                entityCanonical.set(normalized, trimmed);
+                entitySources.set(normalized, [ref]);
+            }
+            else {
+                const srcs = entitySources.get(normalized);
+                if (srcs && !srcs.includes(ref))
+                    srcs.push(ref);
+            }
+        }
+    }
+    const entities = Array.from(entityCanonical.values());
+    const entityNormSet = new Set(entityCanonical.keys());
+    const relSeenKey = new Map();
+    const relationIndexByKey = new Map();
+    const relations = [];
+    for (let i = 0; i < extractions.length; i++) {
+        const ref = assetRefs?.[i] ?? "unknown";
+        for (const rel of extractions[i].relations) {
+            const fromNorm = rel.from.trim().toLowerCase();
+            const toNorm = rel.to.trim().toLowerCase();
+            const typeNorm = normalizeRelationType(rel.type);
+            if (!entityNormSet.has(fromNorm) || !entityNormSet.has(toNorm))
+                continue;
+            const key = `${fromNorm}\0${toNorm}\0${typeNorm}`;
+            if (!relSeenKey.has(key)) {
+                relSeenKey.set(key, [ref]);
+                const canonical = {
+                    from: entityCanonical.get(fromNorm) ?? rel.from,
+                    to: entityCanonical.get(toNorm) ?? rel.to,
+                };
+                if (typeNorm)
+                    canonical.type = typeNorm;
+                const confidence = normalizeConfidence(rel.confidence);
+                if (confidence !== undefined)
+                    canonical.confidence = confidence;
+                relationIndexByKey.set(key, relations.length);
+                relations.push(canonical);
+            }
+            else {
+                const srcs = relSeenKey.get(key);
+                if (srcs && !srcs.includes(ref))
+                    srcs.push(ref);
+                const idx = relationIndexByKey.get(key);
+                const nextConfidence = normalizeConfidence(rel.confidence);
+                if (idx !== undefined && nextConfidence !== undefined) {
+                    const current = normalizeConfidence(relations[idx]?.confidence) ?? 0;
+                    if (nextConfidence > current && relations[idx])
+                        relations[idx].confidence = nextConfidence;
+                }
+            }
+        }
+    }
+    const relationSources = new Map(relSeenKey);
+    return { entities, relations, entitySources, relationSources };
+}

package/dist/indexer/graph-extraction.js

@@ -3,8 +3,8 @@
  *
  * Walks the primary stash for `memory:` and `knowledge:` assets, asks the
  * configured LLM to extract entities and relations from each one, and
- * persists the result to a single stash-local artifact at
- * `<stashRoot>/.akm/graph.json`. The artifact is consumed by the search
+ * persists the result to stash-local SQLite graph tables keyed by stash root.
+ * The artifact is consumed by the search
  * pipeline (see `src/indexer/graph-boost.ts`) as a single boost component
  * inside the existing FTS5+boosts loop — there is NO second SearchHit
  * scorer and no parallel ranking track.
@@ -19,13 +19,13 @@
  *   3. `index.graph.llm !== false` — the per-pass opt-out layer (#208).
  *      Set to `false` to skip just this pass while leaving other passes
  *      that share the same `llm` block enabled.
- *   Toggling any one off does NOT delete the existing `graph.json` — the
+ *   Toggling any one off does NOT delete the existing persisted graph — the
  *   user keeps the boost component they already have, it just stops
  *   refreshing.
  *
  * Locked v1 contract:
  *   - LLM access is exclusively via `resolveIndexPassLLM("graph", config)`.
- *   - The `graph.json` file is an indexer artifact, NOT a user-visible
+ *   - The graph rows are an indexer artifact, NOT a user-visible
  *     asset. It does not have an asset ref, does not appear in search
  *     hits, and is not addressable via `akm show`. Direct `fs.writeFile`
  *     is therefore the correct primitive — `writeAssetToSource` is
@@ -33,25 +33,169 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { TYPE_DIRS } from "../core/asset-spec";
+import { concurrentMap } from "../core/concurrent";
 import { parseFrontmatter } from "../core/frontmatter";
 import { warn } from "../core/warn";
-import { extractGraphFromBody } from "../llm/graph-extract";
+import * as graphExtract from "../llm/graph-extract";
 import { resolveIndexPassLLM } from "../llm/index-passes";
+import { computeBodyHash, GRAPH_SCHEMA_VERSION, getLlmCacheEntry, upsertLlmCacheEntry } from "./db";
+import { loadStoredGraphSnapshot, replaceStoredGraph } from "./graph-db";
+import { deduplicateGraph } from "./graph-dedup";
+import { withLlmCache } from "./llm-cache";
+import { walkMarkdownFiles } from "./walker";
 /** Schema version for the persisted artifact — bumps trigger a full rebuild. */
-export const GRAPH_FILE_SCHEMA_VERSION = 1;
-/** Path scheme — kept stable so consumers (search-time boost) can find it. */
-export const GRAPH_FILE_RELATIVE_PATH = path.join(".akm", "graph.json");
-/** Public path resolver — exported so the search-side reader and tests share the rule. */
-export function getGraphFilePath(stashRoot) {
-    return path.join(stashRoot, GRAPH_FILE_RELATIVE_PATH);
-}
+export const GRAPH_FILE_SCHEMA_VERSION = GRAPH_SCHEMA_VERSION;
+const EMPTY_QUALITY = {
+    consideredFiles: 0,
+    extractedFiles: 0,
+    entityCount: 0,
+    relationCount: 0,
+    extractionCoverage: 0,
+    density: 0,
+};
 const EMPTY_RESULT = {
     considered: 0,
     extracted: 0,
     totalEntities: 0,
     totalRelations: 0,
     written: false,
+    quality: { ...EMPTY_QUALITY },
 };
+function roundMetric(value) {
+    return Number(value.toFixed(4));
+}
+function computeGraphQualityTelemetry(consideredFiles, extractedFiles, entityCount, relationCount) {
+    const extractionCoverage = consideredFiles > 0 ? extractedFiles / consideredFiles : 0;
+    const maxEdges = entityCount > 1 ? (entityCount * (entityCount - 1)) / 2 : 0;
+    const density = maxEdges > 0 ? relationCount / maxEdges : 0;
+    return {
+        consideredFiles,
+        extractedFiles,
+        entityCount,
+        relationCount,
+        extractionCoverage: roundMetric(extractionCoverage),
+        density: roundMetric(density),
+    };
+}
+export const DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES = ["memory", "knowledge"];
+const SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES = new Set([
+    "memory",
+    "knowledge",
+    "skill",
+    "command",
+    "agent",
+    "workflow",
+    "lesson",
+    "task",
+    "wiki",
+]);
+function normalizeConfidence(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return undefined;
+    return Math.max(0, Math.min(1, raw));
+}
+export function getGraphExtractionIncludeTypes(config) {
+    const configured = config.index?.graph?.graphExtractionIncludeTypes;
+    if (!configured || configured.length === 0)
+        return [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES];
+    const out = [];
+    const seen = new Set();
+    for (const rawType of configured) {
+        const type = rawType.trim().toLowerCase();
+        if (!type || seen.has(type))
+            continue;
+        if (!SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES.has(type))
+            continue;
+        seen.add(type);
+        out.push(type);
+    }
+    return out.length > 0 ? out : [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES];
+}
+function validateGraphCacheShape(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const obj = raw;
+    if (!Array.isArray(obj.entities) || !obj.entities.every((e) => typeof e === "string"))
+        return undefined;
+    if (obj.relations !== undefined &&
+        (!Array.isArray(obj.relations) ||
+            !obj.relations.every((r) => {
+                if (!r || typeof r !== "object")
+                    return false;
+                const rel = r;
+                if (typeof rel.from !== "string" || typeof rel.to !== "string")
+                    return false;
+                if (rel.type !== undefined && typeof rel.type !== "string")
+                    return false;
+                if (rel.confidence !== undefined && (typeof rel.confidence !== "number" || !Number.isFinite(rel.confidence))) {
+                    return false;
+                }
+                return true;
+            }))) {
+        return undefined;
+    }
+    return {
+        entities: obj.entities,
+        relations: Array.isArray(obj.relations) ? obj.relations : [],
+        confidence: normalizeConfidence(obj.confidence),
+    };
+}
+function loadGraphFile(stashRoot, db) {
+    if (!db)
+        return { files: [] };
+    const graph = loadStoredGraphSnapshot(stashRoot, db);
+    if (!graph)
+        return { files: [] };
+    const out = [];
+    for (const node of graph.files) {
+        const cacheShape = validateGraphCacheShape({ entities: node.entities, relations: node.relations });
+        if (!cacheShape)
+            continue;
+        out.push({
+            path: node.path,
+            type: node.type,
+            bodyHash: node.bodyHash,
+            entities: cacheShape.entities,
+            relations: cacheShape.relations,
+            confidence: normalizeConfidence(node.confidence),
+        });
+    }
+    return { files: out };
+}
+function mergeGraphNodes(previousNodes, refreshedNodes, candidatePaths) {
+    if (!candidatePaths)
+        return refreshedNodes;
+    const refreshedByPath = new Map(refreshedNodes.map((node) => [node.path, node]));
+    const merged = [];
+    for (const node of previousNodes) {
+        if (candidatePaths.has(node.path))
+            continue;
+        merged.push(node);
+    }
+    for (const node of refreshedNodes)
+        merged.push(refreshedByPath.get(node.path) ?? node);
+    return merged;
+}
+function reuseGraphNode(previousNodes, candidate, bodyHash) {
+    const node = previousNodes.get(candidate.absPath);
+    if (!node)
+        return undefined;
+    if (node.type !== candidate.type)
+        return undefined;
+    if (typeof node.bodyHash !== "string" || node.bodyHash.length === 0)
+        return undefined;
+    if (node.bodyHash !== bodyHash)
+        return undefined;
+    const validated = validateGraphCacheShape({ entities: node.entities, relations: node.relations });
+    if (!validated)
+        return undefined;
+    return {
+        entities: validated.entities,
+        relations: validated.relations,
+        confidence: normalizeConfidence(node.confidence),
+    };
+}
 /**
  * Top-level entry point. Returns a no-op result when the pass is disabled.
  *
@@ -67,10 +211,14 @@ const EMPTY_RESULT = {
  *      `false`, the indexer simply skips this pass for the current run.
  *
  * If any of the three is missing or `false`, this function short-circuits
- * to an empty no-op result, leaving any existing `graph.json` untouched on
- * disk.
+ * to an empty no-op result, leaving any existing persisted graph untouched.
+ *
+ * When `config.index.graph.graphExtractionBatchSize > 1`, eligible files are
+ * chunked into batches and each chunk is processed with a single LLM call via
+ * `extractGraphFromBodies`. Default batch size is 1 (one call per asset —
+ * preserves existing behaviour, fully opt-in).
  */
-export async function runGraphExtractionPass(config, sources, signal) {
+export async function runGraphExtractionPass(config, sources, signal, db, reEnrich, onProgress, options = {}) {
     // Gate 1 — locked feature flag (§14). Defaults to enabled; only an
     // explicit `false` disables the pass entirely.
     if (config.llm?.features?.graph_extraction === false)
@@ -86,58 +234,263 @@ export async function runGraphExtractionPass(config, sources, signal) {
     const primary = sources[0];
     if (!primary)
         return { ...EMPTY_RESULT };
-    const eligible = collectEligibleFiles(primary.path);
+    const eligible = collectEligibleFiles(primary.path, getGraphExtractionIncludeTypes(config)).filter((candidate) => !options.candidatePaths || options.candidatePaths.has(candidate.absPath));
     const considered = eligible.length;
     if (considered === 0)
         return { ...EMPTY_RESULT };
+    const previousGraph = loadGraphFile(primary.path, db);
+    const previousNodes = new Map(previousGraph.files.map((node) => [node.path, node]));
     const nodes = [];
     let totalEntities = 0;
     let totalRelations = 0;
-    for (const candidate of eligible) {
-        if (signal?.aborted)
-            break;
-        const extraction = await extractGraphFromBody(llmConfig, candidate.body, signal);
-        if (extraction.entities.length === 0)
+    let processed = 0;
+    let extracted = 0;
+    onProgress?.({ processed, total: considered, extracted, totalEntities, totalRelations });
+    // Read the configured batch size. Default of 1 preserves the existing
+    // per-asset behaviour and is fully opt-in.
+    const batchSize = config.index?.graph?.graphExtractionBatchSize ?? 1;
+    const onFallback = (evt) => {
+        warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
+    };
+    let extractionResults;
+    if (batchSize <= 1) {
+        // ── Original per-asset path (with incremental cache) ─────────────────
+        extractionResults = await concurrentMap(eligible, async (candidate) => {
+            if (signal?.aborted)
+                return undefined;
+            const bodyHash = computeBodyHash(candidate.body);
+            let cached;
+            if (db) {
+                // withLlmCache handles hash computation, cache lookup, LLM call, and cache write.
+                // When cache misses and this run is not forced, attempt graph-node reuse before LLM.
+                cached = await withLlmCache(db, candidate.absPath, candidate.body, reEnrich ?? false, async () => {
+                    if (!(reEnrich ?? false)) {
+                        const reused = reuseGraphNode(previousNodes, candidate, bodyHash);
+                        if (reused)
+                            return reused;
+                    }
+                    const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, config, onFallback);
+                    // Cache empty results too so we skip on next run.
+                    return {
+                        entities: extraction.entities,
+                        relations: extraction.relations,
+                        ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
+                    };
+                }, validateGraphCacheShape);
+            }
+            else if (!(reEnrich ?? false)) {
+                cached = reuseGraphNode(previousNodes, candidate, bodyHash);
+            }
+            if (!cached) {
+                const extraction = await graphExtract.extractGraphFromBody(llmConfig, candidate.body, signal, config, onFallback);
+                cached = {
+                    entities: extraction.entities,
+                    relations: extraction.relations,
+                    ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
+                };
+            }
+            if (!cached || cached.entities.length === 0)
+                return undefined;
+            return {
+                absPath: candidate.absPath,
+                type: candidate.type,
+                bodyHash,
+                entities: cached.entities,
+                relations: cached.relations,
+                ...(cached.confidence !== undefined ? { confidence: cached.confidence } : {}),
+            };
+        }, 
+        // Default concurrency of 4 for cloud APIs. Set `llm.concurrency: 1`
+        // in config.json for local model servers (LM Studio, Ollama).
+        llmConfig.concurrency ?? 1);
+    }
+    else {
+        // ── Batched path (with incremental cache) ────────────────────────────
+        // Chunk eligible files into groups of `batchSize` and call
+        // `extractGraphFromBodies` once per chunk. Cache hits are resolved
+        // before chunking so they don't consume LLM tokens in the batch call.
+        const rawResults = new Array(eligible.length).fill(undefined);
+        const chunkStarts = [];
+        for (let start = 0; start < eligible.length; start += batchSize)
+            chunkStarts.push(start);
+        await concurrentMap(chunkStarts, async (start) => {
+            if (signal?.aborted)
+                return;
+            const chunk = eligible.slice(start, start + batchSize);
+            // Pre-resolve cache hits for this chunk; track which positions need LLM.
+            const bodyHashes = chunk.map((c) => computeBodyHash(c.body));
+            const needsLlm = chunk.map((c, j) => {
+                if (!db || reEnrich)
+                    return true;
+                const cached = getLlmCacheEntry(db, c.absPath, bodyHashes[j] ?? "");
+                if (!cached)
+                    return true;
+                try {
+                    const parsed = validateGraphCacheShape(JSON.parse(cached.resultJson));
+                    if (!parsed)
+                        return true;
+                    const entities = parsed.entities;
+                    rawResults[start + j] =
+                        entities.length > 0
+                            ? {
+                                absPath: c.absPath,
+                                type: c.type,
+                                bodyHash: bodyHashes[j] ?? "",
+                                entities,
+                                relations: parsed.relations,
+                                ...(parsed.confidence !== undefined ? { confidence: parsed.confidence } : {}),
+                            }
+                            : undefined;
+                    return false;
+                }
+                catch {
+                    return true;
+                }
+            });
+            // Secondary incremental path: reuse previous graph nodes when the body hash
+            // still matches and DB cache is missing/stale/unavailable.
+            if (!(reEnrich ?? false)) {
+                for (let j = 0; j < chunk.length; j++) {
+                    if (!needsLlm[j])
+                        continue;
+                    const candidate = chunk[j];
+                    if (!candidate)
+                        continue;
+                    const reused = reuseGraphNode(previousNodes, candidate, bodyHashes[j] ?? "");
+                    if (!reused)
+                        continue;
+                    rawResults[start + j] =
+                        reused.entities.length > 0
+                            ? {
+                                absPath: candidate.absPath,
+                                type: candidate.type,
+                                bodyHash: bodyHashes[j] ?? "",
+                                entities: reused.entities,
+                                relations: reused.relations,
+                                ...(reused.confidence !== undefined ? { confidence: reused.confidence } : {}),
+                            }
+                            : undefined;
+                    if (db) {
+                        upsertLlmCacheEntry(db, candidate.absPath, bodyHashes[j] ?? "", JSON.stringify(reused));
+                    }
+                    needsLlm[j] = false;
+                }
+            }
+            const uncachedChunk = chunk.filter((_, j) => needsLlm[j]);
+            if (uncachedChunk.length === 0)
+                return;
+            const bodies = uncachedChunk.map((c) => c.body);
+            // extractGraphFromBodies always returns an array of the same length
+            // as bodies (it falls back per-asset for any missing indices).
+            const batchExtractions = await graphExtract.extractGraphFromBodies(llmConfig, bodies, signal, config, onFallback);
+            // Map LLM results back to original positions and write cache entries.
+            let llmIdx = 0;
+            for (let j = 0; j < chunk.length; j++) {
+                if (!needsLlm[j])
+                    continue;
+                const candidate = chunk[j];
+                const extraction = batchExtractions[llmIdx++];
+                if (!candidate || !extraction)
+                    continue;
+                if (db) {
+                    upsertLlmCacheEntry(db, candidate.absPath, bodyHashes[j] ?? "", JSON.stringify({
+                        entities: extraction.entities,
+                        relations: extraction.relations,
+                        ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
+                    }));
+                }
+                if (extraction.entities.length === 0) {
+                    rawResults[start + j] = undefined;
+                }
+                else {
+                    rawResults[start + j] = {
+                        absPath: candidate.absPath,
+                        type: candidate.type,
+                        bodyHash: bodyHashes[j] ?? "",
+                        entities: extraction.entities,
+                        relations: extraction.relations,
+                        ...(extraction.confidence !== undefined ? { confidence: extraction.confidence } : {}),
+                    };
+                }
+            }
+        }, llmConfig.concurrency ?? 1);
+        extractionResults = rawResults;
+    }
+    for (const result of extractionResults) {
+        if (!result)
             continue;
         nodes.push({
-            path: candidate.absPath,
-            type: candidate.type,
-            // Lower-case once at write time so the search-time boost can do a
-            // single case-folded comparison without re-canonicalising on every
-            // query.
-            entities: extraction.entities.map((e) => e.toLowerCase()),
-            relations: extraction.relations.map((r) => ({
-                from: r.from.toLowerCase(),
-                to: r.to.toLowerCase(),
-                ...(r.type ? { type: r.type.toLowerCase() } : {}),
-            })),
+            path: result.absPath,
+            type: result.type,
+            bodyHash: result.bodyHash,
+            entities: [...new Set(result.entities.map((entity) => entity.trim()).filter(Boolean))],
+            relations: result.relations
+                .map((r) => ({
+                from: r.from.trim(),
+                to: r.to.trim(),
+                ...(r.type ? { type: r.type.trim() } : {}),
+                ...(normalizeConfidence(r.confidence) !== undefined ? { confidence: normalizeConfidence(r.confidence) } : {}),
+            }))
+                .filter((relation) => relation.from && relation.to),
+            ...(normalizeConfidence(result.confidence) !== undefined
+                ? { confidence: normalizeConfidence(result.confidence) }
+                : {}),
+        });
+    }
+    processed = 0;
+    extracted = 0;
+    totalEntities = 0;
+    totalRelations = 0;
+    for (let i = 0; i < extractionResults.length; i++) {
+        const result = extractionResults[i];
+        processed += 1;
+        if (result) {
+            extracted += 1;
+            totalEntities += result.entities.length;
+            totalRelations += result.relations.length;
+        }
+        onProgress?.({
+            processed,
+            total: considered,
+            extracted,
+            totalEntities,
+            totalRelations,
+            currentPath: eligible[i]?.absPath,
         });
-        totalEntities += extraction.entities.length;
-        totalRelations += extraction.relations.length;
     }
-    if (nodes.length === 0) {
-        warn("graph extraction: all extractions failed or returned no entities; leaving existing graph.json untouched.");
+    const mergedNodes = mergeGraphNodes(previousGraph.files, nodes, options.candidatePaths);
+    const assetRefs = mergedNodes.map((node) => node.path);
+    const deduped = deduplicateGraph(mergedNodes.map((node) => ({ entities: node.entities, relations: node.relations })), assetRefs);
+    if (mergedNodes.length === 0) {
+        warn("graph extraction: all extractions failed or returned no entities; leaving existing graph rows untouched.");
         return {
             considered,
             extracted: 0,
             totalEntities: 0,
             totalRelations: 0,
             written: false,
+            quality: computeGraphQualityTelemetry(considered, 0, 0, 0),
         };
     }
+    const qualityConsidered = options.candidatePaths ? mergedNodes.length : considered;
+    const quality = computeGraphQualityTelemetry(qualityConsidered, mergedNodes.length, deduped.entities.length, deduped.relations.length);
     const graph = {
         schemaVersion: GRAPH_FILE_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
         stashRoot: primary.path,
-        files: nodes,
+        files: mergedNodes,
+        entities: deduped.entities,
+        relations: deduped.relations,
+        quality,
     };
-    const written = writeGraphFile(primary.path, graph);
+    const written = writeGraphFile(primary.path, graph, db);
     return {
         considered,
-        extracted: nodes.length,
+        extracted,
         totalEntities,
         totalRelations,
         written,
+        quality,
     };
 }
 /**
@@ -151,10 +504,16 @@ export async function runGraphExtractionPass(config, sources, signal) {
  *
  * Exported for direct unit testing.
  */
-export function collectEligibleFiles(stashRoot) {
+export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES]) {
     const out = [];
-    for (const type of ["memory", "knowledge"]) {
-        const dir = path.join(stashRoot, `${type === "memory" ? "memories" : "knowledge"}`);
+    for (const rawType of includeTypes) {
+        const type = rawType.trim().toLowerCase();
+        if (!SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES.has(type))
+            continue;
+        const stashDir = TYPE_DIRS[type];
+        if (!stashDir)
+            continue;
+        const dir = path.join(stashRoot, stashDir);
         if (!fs.existsSync(dir))
             continue;
         for (const filePath of walkMarkdownFiles(dir)) {
@@ -178,47 +537,21 @@ export function collectEligibleFiles(stashRoot) {
     }
     return out;
 }
-function* walkMarkdownFiles(root) {
-    let entries;
-    try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const full = path.join(root, entry.name);
-        if (entry.isDirectory()) {
-            yield* walkMarkdownFiles(full);
-        }
-        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-            yield full;
-        }
-    }
-}
 // ── Persistence ─────────────────────────────────────────────────────────────
 /**
- * Write `graph.json` atomically to `<stashRoot>/.akm/graph.json`.
- *
- * Direct `fs.writeFile` is intentional. The graph artifact is an indexer
- * cache — not a user-visible asset — so it does not have an asset ref and
- * `writeAssetToSource` (which routes through the asset-spec rendering
- * layer) is the wrong primitive here. See CLAUDE.md / spec §10 step 5 for
- * the carve-out: kind-branching writes for asset content live in
- * `src/core/write-source.ts`; opaque indexer artifacts may write directly.
+ * Persist graph rows into the SQLite index DB.
  */
-function writeGraphFile(stashRoot, graph) {
-    const target = getGraphFilePath(stashRoot);
-    const dir = path.dirname(target);
+function writeGraphFile(stashRoot, graph, db) {
+    if (!db) {
+        warn("graph extraction: no database handle available; skipping graph persistence.");
+        return false;
+    }
     try {
-        fs.mkdirSync(dir, { recursive: true });
-        const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-        fs.writeFileSync(tmp, `${JSON.stringify(graph, null, 2)}\n`, "utf8");
-        fs.renameSync(tmp, target);
+        replaceStoredGraph(db, graph);
         return true;
     }
     catch (err) {
-        warn(`graph extraction: failed to write ${target}: ${err instanceof Error ? err.message : String(err)}`);
+        warn(`graph extraction: failed to persist graph for ${stashRoot}: ${err instanceof Error ? err.message : String(err)}`);
         return false;
     }
 }