akm-cli 0.6.1 → 0.7.0-rc1

package/dist/src/indexer/graph-extraction.js

@@ -0,0 +1,212 @@
+/**
+ * Graph-extraction pass for `akm index` (#207).
+ *
+ * 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
+ * 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.
+ *
+ * Disabling — three preconditions must ALL hold for the pass to run:
+ *   1. `akm.llm` must be configured (no provider = no extraction). When
+ *      absent, `resolveIndexPassLLM("graph", config)` returns `undefined`
+ *      and the pass short-circuits.
+ *   2. `llm.features.graph_extraction !== false` — the locked v1 spec §14
+ *      feature-flag layer. Set to `false` to block the pass at the
+ *      feature-gate layer (no network call may ever issue).
+ *   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
+ *   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
+ *     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
+ *     reserved for asset writes (CLAUDE.md / spec §10 step 5).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../core/frontmatter";
+import { warn } from "../core/warn";
+import { extractGraphFromBody } from "../llm/graph-extract";
+import { resolveIndexPassLLM } from "../llm/index-passes";
+/** 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);
+}
+const EMPTY_RESULT = {
+    considered: 0,
+    extracted: 0,
+    totalEntities: 0,
+    totalRelations: 0,
+    written: false,
+};
+/**
+ * Top-level entry point. Returns a no-op result when the pass is disabled.
+ *
+ * Three preconditions — ALL must hold for the pass to run:
+ *
+ *   1. **Provider configured** — `akm.llm` must be present. Without a
+ *      configured provider, `resolveIndexPassLLM("graph", config)` returns
+ *      `undefined` (the pass cannot run because there is no model to call).
+ *   2. **Feature gate** — `llm.features.graph_extraction` (defaults to
+ *      `true`). When `false`, no network call may issue regardless of
+ *      per-pass settings. This is the locked spec-§14 gate.
+ *   3. **Per-pass gate** — `index.graph.llm` (defaults to `true`). When
+ *      `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.
+ */
+export async function runGraphExtractionPass(config, sources) {
+    // Gate 1 — locked feature flag (§14). Defaults to enabled; only an
+    // explicit `false` disables the pass entirely.
+    if (config.llm?.features?.graph_extraction === false)
+        return { ...EMPTY_RESULT };
+    // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
+    // `undefined` when the pass should not run.
+    const llmConfig = resolveIndexPassLLM("graph", config);
+    if (!llmConfig)
+        return { ...EMPTY_RESULT };
+    // The pass only writes to the primary (working) stash. Read-only caches
+    // (git, npm, website) are deliberately untouched — the graph artifact for
+    // those sources would be clobbered by the next sync().
+    const primary = sources[0];
+    if (!primary)
+        return { ...EMPTY_RESULT };
+    const eligible = collectEligibleFiles(primary.path);
+    const considered = eligible.length;
+    if (considered === 0)
+        return { ...EMPTY_RESULT };
+    const nodes = [];
+    let totalEntities = 0;
+    let totalRelations = 0;
+    for (const candidate of eligible) {
+        const extraction = await extractGraphFromBody(llmConfig, candidate.body);
+        if (extraction.entities.length === 0)
+            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() } : {}),
+            })),
+        });
+        totalEntities += extraction.entities.length;
+        totalRelations += extraction.relations.length;
+    }
+    const graph = {
+        schemaVersion: GRAPH_FILE_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        stashRoot: primary.path,
+        files: nodes,
+    };
+    const written = writeGraphFile(primary.path, graph);
+    return {
+        considered,
+        extracted: nodes.length,
+        totalEntities,
+        totalRelations,
+        written,
+    };
+}
+/**
+ * Scan the primary stash for `memory:` and `knowledge:` markdown files
+ * suitable for graph extraction. The directory layout convention is the
+ * same one the rest of the indexer uses: `<stashRoot>/<type>/...`.
+ *
+ * Inferred-child memories (frontmatter `inferred: true`) are skipped — they
+ * are atomic facts already, with no internal graph structure worth
+ * extracting.
+ *
+ * Exported for direct unit testing.
+ */
+export function collectEligibleFiles(stashRoot) {
+    const out = [];
+    for (const type of ["memory", "knowledge"]) {
+        const dir = path.join(stashRoot, `${type === "memory" ? "memories" : "knowledge"}`);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const filePath of walkMarkdownFiles(dir)) {
+            let raw;
+            try {
+                raw = fs.readFileSync(filePath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const parsed = parseFrontmatter(raw);
+            // Skip inferred memory children — they are atomic and there's no
+            // graph to extract from a single-fact body.
+            if (type === "memory" && parsed.data.inferred === true)
+                continue;
+            const body = parsed.content.trim();
+            if (!body)
+                continue;
+            out.push({ absPath: filePath, type, body });
+        }
+    }
+    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.
+ */
+function writeGraphFile(stashRoot, graph) {
+    const target = getGraphFilePath(stashRoot);
+    const dir = path.dirname(target);
+    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);
+        return true;
+    }
+    catch (err) {
+        warn(`graph extraction: failed to write ${target}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}

package/dist/{indexer → src/indexer}/indexer.js

@@ -2,10 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common";
 import { getDbPath } from "../core/paths";
-import { warn } from "../core/warn";
+import { isVerbose, warn } from "../core/warn";
+import { resolveIndexPassLLM } from "../llm/index-passes";
 import { takeWorkflowDocument } from "../workflows/document-cache";
 import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
-import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
+import { runGraphExtractionPass } from "./graph-extraction";
+import { runMemoryInferencePass } from "./memory-inference";
+import { generateMetadataFlat, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./metadata";
 import { buildSearchText } from "./search-fields";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
 import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage-events";
@@ -41,7 +44,10 @@ export async function akmIndex(options) {
                 sourcesCount: allSourceDirs.length,
                 semanticSearchMode: config.semanticSearchMode,
                 embeddingProvider: getEmbeddingProvider(config.embedding),
-                llmEnabled: !!config.llm,
+                // Surface "llm enabled" only when at least one pass would actually
+                // run. Today that means the enrichment pass; future passes plug in
+                // via `resolveIndexPassLLM`.
+                llmEnabled: !!resolveIndexPassLLM("enrichment", config),
                 vecAvailable: isVecAvailable(db),
             }),
         });
@@ -76,6 +82,49 @@ export async function akmIndex(options) {
                 }
             }
         }
+        // Memory inference pass (#201). Runs before the walk so any atomic-fact
+        // children that get written are picked up by the walker in this same run
+        // and don't have to wait for the next `akm index`. Gated entirely by
+        // `resolveIndexPassLLM("memory", config)` — when the user has no
+        // `akm.llm` block or has set `index.memory.llm = false`, this is a no-op
+        // and existing inferred children are left in place.
+        try {
+            const inferenceResult = await runMemoryInferencePass(config, allSourceEntries);
+            if (inferenceResult.writtenFacts > 0) {
+                onProgress({
+                    phase: "llm",
+                    message: `Memory inference wrote ${inferenceResult.writtenFacts} atomic fact${inferenceResult.writtenFacts === 1 ? "" : "s"} from ${inferenceResult.splitParents} parent memor${inferenceResult.splitParents === 1 ? "y" : "ies"}.`,
+                });
+            }
+        }
+        catch (err) {
+            // Defensive — runMemoryInferencePass swallows per-memory failures.
+            // A thrown error here would only come from an unexpected programming
+            // bug; surface it as a warning rather than aborting the index run.
+            warn(`Memory inference pass aborted: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Graph extraction pass (#207). Runs after memory inference so any
+        // atomic-fact children that just got written are visible to the graph
+        // walk. Persists `<stashRoot>/.akm/graph.json` — an indexer artifact,
+        // NOT a user-visible asset, so it is not routed through
+        // writeAssetToSource. The artifact feeds the existing FTS5+boosts
+        // pipeline as a single boost component (see graph-boost.ts); there is
+        // no parallel scoring track. Disabled when either gate (the locked
+        // `llm.features.graph_extraction` feature flag or the per-pass
+        // `index.graph.llm` toggle) is off; the existing graph file is
+        // preserved on disk in that case.
+        try {
+            const graphResult = await runGraphExtractionPass(config, allSourceEntries);
+            if (graphResult.written) {
+                onProgress({
+                    phase: "llm",
+                    message: `Graph extraction wrote ${graphResult.totalEntities} entit${graphResult.totalEntities === 1 ? "y" : "ies"} and ${graphResult.totalRelations} relation${graphResult.totalRelations === 1 ? "" : "s"} from ${graphResult.extracted} file${graphResult.extracted === 1 ? "" : "s"}.`,
+                });
+            }
+        }
+        catch (err) {
+            warn(`Graph extraction pass aborted: ${err instanceof Error ? err.message : String(err)}`);
+        }
         const tWalkStart = Date.now();
         // Walk stash dirs and index entries.
         // doFullDelete=true merges the wipe into the same transaction as the
@@ -86,12 +135,26 @@ export async function akmIndex(options) {
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
         });
+        // Workflow validation noise gate (issue #273): per-spec stderr lines from
+        // `buildMetadataSkipWarning` are suppressed at default verbosity in
+        // `metadata.ts`. Replace them with a single summary line so operators
+        // running a cold-start search against a fresh registry-cloned source
+        // don't get the impression akm is broken. Verbose mode keeps the
+        // per-spec output instead of (not in addition to) the summary.
+        if (!isVerbose()) {
+            const skippedWorkflowCount = warnings.filter(isWorkflowSkipWarning).length;
+            if (skippedWorkflowCount > 0) {
+                const noun = skippedWorkflowCount === 1 ? "workflow spec" : "workflow specs";
+                warn(`${skippedWorkflowCount} ${noun} skipped due to validation errors; ` +
+                    "rerun with --verbose (or AKM_VERBOSE=1) to see details.");
+            }
+        }
         const tWalkEnd = Date.now();
         // Enhance entries with LLM if configured
         await enhanceDirsWithLlm(db, config, dirsNeedingLlm);
         onProgress({
             phase: "llm",
-            message: config.llm
+            message: resolveIndexPassLLM("enrichment", config)
                 ? `LLM enhancement reviewed ${dirsNeedingLlm.length} ${dirsNeedingLlm.length === 1 ? "directory" : "directories"}.`
                 : "LLM enhancement disabled.",
         });
@@ -373,7 +436,11 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
     return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
 async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
-    if (!config.llm || dirsNeedingLlm.length === 0)
+    // Resolve per-pass LLM config via the unified shim. Returns undefined when
+    // either no `akm.llm` is configured or the user opted this pass out via
+    // `index.enrichment.llm = false`. (#208)
+    const llmConfig = resolveIndexPassLLM("enrichment", config);
+    if (!llmConfig || dirsNeedingLlm.length === 0)
         return;
     // Aggregate per-entry failures so a misconfigured LLM endpoint surfaces
     // as a single visible warning instead of silently degrading every entry
@@ -385,7 +452,7 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
         if (generatedEntries.length === 0)
             continue;
         const generatedStash = { entries: generatedEntries };
-        const enhanced = await enhanceStashWithLlm(config.llm, generatedStash, files, summary);
+        const enhanced = await enhanceStashWithLlm(llmConfig, generatedStash, files, summary);
         // Re-upsert the enhanced entries in a single transaction so a crash
         // cannot leave half the entries updated and the rest stale.
         db.transaction(() => {

package/dist/src/indexer/memory-inference.js

@@ -0,0 +1,263 @@
+/**
+ * Memory inference pass for `akm index` (#201).
+ *
+ * Detects memories pending inference, asks the configured LLM to split each
+ * into atomic facts, and writes the results back as new memory files with
+ * frontmatter `inferred: true` + a `source:` backref to the parent memory.
+ *
+ * Pending predicate (see {@link isPendingMemory}):
+ *   - File lives under `<stashRoot>/memories/` and ends in `.md`.
+ *   - Frontmatter does NOT have `inferenceProcessed: true` (parent already split).
+ *   - Frontmatter does NOT have `inferred: true` (this is itself a child fact).
+ *
+ * Idempotency: after a successful split the parent's frontmatter is rewritten
+ * with `inferenceProcessed: true`. A subsequent `akm index` therefore skips
+ * the parent without re-running the LLM.
+ *
+ * Disabling — two orthogonal gates per v1 spec §14:
+ *   1. `llm.features.memory_inference = false` blocks the pass at the
+ *      locked feature-flag layer (no network call may ever issue).
+ *   2. `index.memory.llm = false` (or no `akm.llm` block at all) opts the
+ *      pass out at the per-pass layer (#208).
+ *   A pass runs iff both layers allow it. Existing inferred children are
+ *   NEVER deleted — the user keeps what was already produced.
+ *
+ * Locked v1 contract:
+ *   - LLM access is exclusively via `resolveIndexPassLLM("memory", config)`.
+ *   - All child memory writes go through `writeAssetToSource` in
+ *     `src/core/write-source.ts`. The parent's frontmatter rewrite is an
+ *     explicit narrow exception — see {@link markParentProcessed}.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { stringify as yamlStringify } from "yaml";
+import { parseAssetRef } from "../core/asset-ref";
+import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
+import { warn } from "../core/warn";
+import { writeAssetToSource } from "../core/write-source";
+import { resolveIndexPassLLM } from "../llm/index-passes";
+import { splitMemoryIntoAtomicFacts } from "../llm/memory-infer";
+/**
+ * Frontmatter keys this pass cares about. Constants so a future rename only
+ * needs to touch one site.
+ */
+const FM_INFERRED = "inferred";
+const FM_INFERENCE_PROCESSED = "inferenceProcessed";
+const FM_SOURCE = "source";
+/**
+ * Top-level entry point. Returns a no-op result when the pass is disabled.
+ *
+ * Two orthogonal gates per v1 spec §14:
+ *
+ *   1. **Feature gate** — `llm.features.memory_inference` (defaults to
+ *      `true`). When `false`, no network call may issue regardless of
+ *      per-pass settings. This is the locked spec-§14 gate.
+ *   2. **Per-pass gate** — `resolveIndexPassLLM("memory", config)` (which
+ *      reads `index.memory.llm`). When `false`, the indexer simply skips
+ *      this pass for the current run.
+ *
+ * Both must allow the call for the pass to run. Either set to `false`
+ * short-circuits to a no-op result.
+ */
+export async function runMemoryInferencePass(config, sources) {
+    const empty = {
+        considered: 0,
+        splitParents: 0,
+        writtenFacts: 0,
+        skippedNoFacts: 0,
+    };
+    // Gate 1 — locked feature flag (§14). Defaults to enabled; only an
+    // explicit `false` disables the pass entirely.
+    if (config.llm?.features?.memory_inference === false)
+        return empty;
+    // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
+    // `undefined` when the pass should not run.
+    const llmConfig = resolveIndexPassLLM("memory", config);
+    if (!llmConfig)
+        return empty;
+    // The pass only writes to the primary (working) stash. Read-only caches
+    // (git, npm, website) are deliberately untouched — writing inferred
+    // children there would be clobbered by the next sync().
+    const primary = sources[0];
+    if (!primary)
+        return empty;
+    const pending = collectPendingMemories(primary.path);
+    empty.considered = pending.length;
+    if (pending.length === 0)
+        return empty;
+    for (const record of pending) {
+        const facts = await splitMemoryIntoAtomicFacts(llmConfig, record.body);
+        if (facts.length === 0) {
+            empty.skippedNoFacts += 1;
+            // Intentionally NOT marked processed — a transient LLM failure should
+            // be retried on the next index run.
+            continue;
+        }
+        const written = await writeAtomicChildren(record, facts);
+        if (written > 0) {
+            markParentProcessed(record);
+            empty.splitParents += 1;
+            empty.writtenFacts += written;
+        }
+    }
+    return empty;
+}
+// ── Pending detection ───────────────────────────────────────────────────────
+/**
+ * Walk `<stashRoot>/memories/` (recursively) and return every memory that
+ * still needs inference. The directory may not exist on a fresh stash; that
+ * is treated as "no pending memories" rather than an error.
+ */
+export function collectPendingMemories(stashRoot) {
+    const memoriesDir = path.join(stashRoot, "memories");
+    if (!fs.existsSync(memoriesDir))
+        return [];
+    const out = [];
+    for (const filePath of walkMarkdownFiles(memoriesDir)) {
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseFrontmatter(raw);
+        if (!isPendingMemory(parsed.data))
+            continue;
+        const relName = toMemoryName(memoriesDir, filePath);
+        if (!relName)
+            continue;
+        out.push({
+            filePath,
+            stashRoot,
+            ref: `memory:${relName}`,
+            data: parsed.data,
+            body: parsed.content,
+        });
+    }
+    return out;
+}
+/**
+ * Predicate: true when the parsed frontmatter indicates the memory has not
+ * yet been split AND is not itself an inferred child.
+ *
+ * Exported for direct unit testing — keeping the predicate in one place
+ * avoids drift between the walker, tests, and any future consumers.
+ */
+export function isPendingMemory(frontmatter) {
+    if (frontmatter[FM_INFERRED] === true)
+        return false;
+    if (frontmatter[FM_INFERENCE_PROCESSED] === true)
+        return false;
+    return true;
+}
+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;
+        }
+    }
+}
+function toMemoryName(memoriesDir, filePath) {
+    const rel = path.relative(memoriesDir, filePath);
+    if (!rel || rel.startsWith(".."))
+        return undefined;
+    // Strip the `.md` extension; preserve any nested subdirectory layout the
+    // user has organised under memories/.
+    return rel.replace(/\\/g, "/").replace(/\.md$/i, "");
+}
+// ── Writing children + marking parent ───────────────────────────────────────
+async function writeAtomicChildren(parent, facts) {
+    const memoriesDir = path.join(parent.stashRoot, "memories");
+    // Sibling directory layout: <parentDir>/<parentBase>.facts/fact-N.md
+    // Keeps facts grouped near the parent without polluting the top level.
+    const parentRel = path.relative(memoriesDir, parent.filePath).replace(/\\/g, "/");
+    const parentBase = parentRel.replace(/\.md$/i, "");
+    const factsDirRel = `${parentBase}.facts`;
+    // Children are routed through writeAssetToSource — the single dispatch
+    // point for kind-branching writes (CLAUDE.md / spec §10 step 5). Memory
+    // assets resolve to `<source.path>/memories/<name>.md`, so a child name
+    // of `<parentBase>.facts/fact-N` lands at exactly the documented child
+    // path scheme.
+    const writeTarget = {
+        kind: "filesystem",
+        name: "stash",
+        path: parent.stashRoot,
+    };
+    const writeConfig = {
+        type: "filesystem",
+        name: "stash",
+        path: parent.stashRoot,
+        writable: true,
+    };
+    let written = 0;
+    for (let i = 0; i < facts.length; i++) {
+        const fact = facts[i];
+        const childName = `${factsDirRel}/fact-${i + 1}`;
+        const childRefStr = `memory:${childName}`;
+        const childPath = path.join(memoriesDir, `${childName}.md`);
+        // Idempotent re-writes: if a child already exists at this slot we skip
+        // it. The parent's `inferenceProcessed` marker is the primary idempotency
+        // guard (we never re-enter the splitter for a processed parent), but a
+        // partial previous run that crashed before the marker landed should not
+        // duplicate facts.
+        if (fs.existsSync(childPath)) {
+            continue;
+        }
+        try {
+            const content = renderChildMemory(fact, parent.ref);
+            const childRef = parseAssetRef(childRefStr);
+            await writeAssetToSource(writeTarget, writeConfig, childRef, content);
+            written += 1;
+        }
+        catch (err) {
+            warn(`memory inference: failed to write atomic child ${childName}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return written;
+}
+function renderChildMemory(fact, parentRef) {
+    const fm = {
+        [FM_INFERRED]: true,
+        [FM_SOURCE]: parentRef,
+    };
+    const yaml = yamlStringify(fm).trimEnd();
+    return `---\n${yaml}\n---\n\n${fact.trim()}\n`;
+}
+function markParentProcessed(parent) {
+    // Frontmatter-only rewrite of an existing asset: not a new asset write,
+    // so writeAssetToSource isn't a fit here (it would round-trip the body
+    // through the asset-spec rendering layer instead of preserving the
+    // user's original markdown bytes verbatim). The narrow exception is
+    // documented in v1 spec §10 step 5 and CLAUDE.md write-source rules.
+    let raw;
+    try {
+        raw = fs.readFileSync(parent.filePath, "utf8");
+    }
+    catch (err) {
+        warn(`memory inference: failed to re-read parent ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
+    const yaml = yamlStringify(updatedFm).trimEnd();
+    const block = parseFrontmatterBlock(raw);
+    const body = block?.content ?? raw;
+    const next = `---\n${yaml}\n---\n${body.startsWith("\n") ? "" : "\n"}${body}`;
+    try {
+        fs.writeFileSync(parent.filePath, next, "utf8");
+    }
+    catch (err) {
+        warn(`memory inference: failed to mark parent processed ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}