akm-cli 0.9.0-beta.26 → 0.9.0-beta.28

package/dist/commands/read/knowledge.js

@@ -11,7 +11,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
-import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
 import { isHttpUrl, isWithin, tryReadStdinText } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
@@ -109,7 +109,9 @@ export async function readKnowledgeInput(source) {
 }
 // ── Asset writing ────────────────────────────────────────────────────────────
 /**
- * Write a markdown asset (knowledge or memory) to the resolved write target.
+ * Write a markdown asset (knowledge, memory, or fact) to the resolved write
+ * target. The type's stash subdirectory is resolved from the asset registry
+ * (`TYPE_DIRS`), so adding a markdown type here needs no further changes.
  *
  * Resolves the write target via the v1 precedence chain (`--target` →
  * `defaultWriteTarget` → working stash), validates the path is within the
@@ -120,7 +122,7 @@ export async function writeMarkdownAsset(options) {
     const cfg = loadConfig();
     const target = resolveWriteTarget(cfg, options.target);
     const { source, config } = target;
-    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
+    const typeRoot = path.join(source.path, TYPE_DIRS[options.type] ?? options.type);
     // `--name` is the flat asset name; `--path` is the subdirectory under the
     // type root. Combine them into the nested name the path resolver expects.
     const subPath = normalizeCreateSubPath(options.path);
@@ -134,7 +136,8 @@ export async function writeMarkdownAsset(options) {
         throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
     }
     if (fs.existsSync(assetPath) && !options.force) {
-        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
+        const label = `${options.type.charAt(0).toUpperCase()}${options.type.slice(1)}`;
+        throw new UsageError(`${label} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
     const ref = { type: options.type, name: normalizedName };
     const result = await writeAssetToSource(source, config, ref, options.content);

package/dist/commands/read/show.js

@@ -22,18 +22,22 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
+import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { findEntryIdByRef } from "../../indexer/db/db.js";
+import { closeDatabase, computeBodyHash, findEntryIdByRef, openExistingDatabase } from "../../indexer/db/db.js";
+import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
+import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { lookup } from "../../indexer/indexer.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../../indexer/walk/file-context.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { resolveStorageLocations } from "../../storage/locations.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 // Eagerly import source providers to trigger self-registration.
 import "../../sources/providers/index.js";
@@ -383,6 +387,15 @@ export async function showLocal(input) {
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
+    // #624-P3: opt-in inline graph extraction. Default OFF — when the flag is
+    // unset this whole block is skipped (no hasGraphData check, no LLM call), so
+    // behavior is byte-identical to today. When ON, it extracts graph data for an
+    // ungraphed asset, but ONLY when a model is configured (model-available
+    // guard) and ALWAYS bounded by a 30s timeout so `show` can never hang. Any
+    // timeout/model-unavailable/error path returns the response unchanged.
+    if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction === true) {
+        await maybeExtractGraphInline(config, sourceStashDir, assetPath);
+    }
     if (input.detail === "brief") {
         return buildBriefResponse(fullResponse, assetPath);
     }
@@ -391,6 +404,58 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/**
+ * #624-P3 — opt-in inline graph extraction for `akm show`. Best-effort and
+ * timeout-bounded: never throws, never hangs, never mutates the response.
+ *
+ * Preconditions (caller already checked the flag): a model must be configured
+ * (model-available guard via {@link resolveIndexPassLLM}) and the asset must be
+ * ungraphed ({@link hasGraphData}). Extraction races a 30s timeout so `show`
+ * cannot block on a slow provider; any timeout/error/missing-model path is
+ * swallowed and `show` returns its already-assembled response unchanged.
+ */
+async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
+    try {
+        // Model-available guard — no provider configured ⇒ silent skip, no LLM call.
+        if (!resolveIndexPassLLM("graph", config))
+            return;
+        let alreadyGraphed = false;
+        let bodyHash;
+        try {
+            const raw = fs.readFileSync(assetPath, "utf8");
+            bodyHash = computeBodyHash(parseFrontmatter(raw).content.trim());
+        }
+        catch {
+            return; // file gone/unreadable ⇒ nothing to extract
+        }
+        withIndexDb((db) => {
+            alreadyGraphed = hasGraphData(db, sourceStashDir, assetPath);
+        });
+        if (alreadyGraphed)
+            return;
+        // Open the db for the async extraction ourselves: `withIndexDb` is
+        // synchronous and would close the connection the instant the async fn
+        // returns its Promise (before extraction completes). Close it explicitly
+        // after the race settles instead.
+        const db = openExistingDatabase(resolveStorageLocations().indexDb);
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, 30_000);
+        });
+        try {
+            await Promise.race([extractGraphForSingleFile(db, sourceStashDir, assetPath, bodyHash, { config }), timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            closeDatabase(db);
+        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // Any other failure: silently return the unchanged show response.
+    }
+}
 /**
  * Minimal `show`: ref → indexer lookup → file contents. Used by callers that
  * just need the raw file (e.g. clone, write-source) and don't want the full

package/dist/core/asset/asset-registry.js

@@ -29,6 +29,7 @@ export const TYPE_TO_RENDERER = {
     wiki: "wiki-md",
     task: "task-yaml",
     session: "session-md",
+    fact: "fact-md",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -45,6 +46,7 @@ export const ACTION_BUILDERS = {
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
     task: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
     session: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
+    fact: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`,
 };
 /**
  * Register a type-to-renderer mapping.

package/dist/core/asset/asset-spec.js

@@ -154,6 +154,20 @@ const ASSET_SPECS_INTERNAL = {
         rendererName: "session-md",
         actionBuilder: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
     },
+    // Durable stash-level semantic knowledge — facts about the user, team, or
+    // project (personal details, team tool stacks, coding conventions /
+    // "constitution", and stash-meta like naming conventions or the active
+    // projects list). Unlike `memory` (episodic, recency-decayed) these are
+    // mostly-static declarations meant to be reliably surfaced as context. A
+    // plain markdown spec; `category` frontmatter scopes the fact and
+    // `pinned: true` marks the small always-injected core. See
+    // docs/design/fact-asset-type.md.
+    fact: {
+        stashDir: "facts",
+        ...markdownSpec,
+        rendererName: "fact-md",
+        actionBuilder: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**

package/dist/core/config/config-schema.js

@@ -190,6 +190,11 @@ export const ImproveProcessConfigSchema = z
     // proactiveMaintenance process: top-N bound per run (default 25). Alias for
     // `limit`; `maxPerRun` wins when both are set.
     maxPerRun: positiveInt.optional(),
+    // graphExtraction process (#624 P2): when set, rank eligible files by
+    // utility_scores DESC and process only the top-N per run (incremental
+    // high-signal-first sweep). Unset = process all eligible (current
+    // behavior). Only meaningful on `graphExtraction`.
+    topN: positiveInt.optional(),
     // MemoryInference process: minimum pending memory count to run the pass.
     minPendingCount: z.number().int().min(0).optional(),
     // Extract process: minimum number of new (unseen, in-window) candidate
@@ -386,6 +391,10 @@ export const ImproveProfileConfigSchema = z
     processes: ImproveProfileProcessesSchema.optional(),
     autoAccept: nonNegativeNumber.optional(),
     limit: positiveInt.optional(),
+    // #616 — bounded multi-cycle phasing. Number of prep->loop->post-loop
+    // cycles per run. positiveInt forbids 0/negative. DEFAULT 1 => byte-identical
+    // single-pass behavior.
+    maxCycles: positiveInt.optional(),
     // #614 — symmetric valence weighting in the eligibility sort. When true,
     // the attention term becomes |valence| MAGNITUDE so BOTH strong positive
     // and strong negative feedback drive attention (utility stays dominant) and
@@ -608,6 +617,7 @@ const GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED = [
     "lesson",
     "task",
     "wiki",
+    "fact",
 ];
 const INDEX_PASS_PROVIDER_KEYS = new Set([
     "endpoint",
@@ -624,6 +634,7 @@ const INDEX_PASS_KNOWN_KEYS = new Set([
     "graphExtractionBatchSize",
     "graphExtractionIncludeTypes",
     "memoryInferenceBatchSize",
+    "lazyGraphExtraction",
 ]);
 /**
  * Per-pass `index.<pass>` entry. Uses preprocess + manual validation so we can
@@ -650,8 +661,8 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: `Unknown key \`${[...(ctx.path ?? []), key].join(".")}\`. Per-pass entries support \`llm\` ` +
-                    "(boolean opt-out), `graphExtractionBatchSize`, `graphExtractionIncludeTypes`, and " +
-                    "`memoryInferenceBatchSize`.",
+                    "(boolean opt-out), `graphExtractionBatchSize`, `graphExtractionIncludeTypes`, " +
+                    "`memoryInferenceBatchSize`, and `lazyGraphExtraction`.",
             });
             return raw;
         }
@@ -670,6 +681,7 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
     graphExtractionBatchSize: positiveInt.optional(),
     graphExtractionIncludeTypes: z.array(z.enum(GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED)).nonempty().optional(),
     memoryInferenceBatchSize: positiveInt.optional(),
+    lazyGraphExtraction: z.boolean().optional(),
 })
     .passthrough());
 const MetadataEnhanceSchema = z.object({ enabled: z.boolean().optional() }).strict();

package/dist/indexer/db/db.js

@@ -397,6 +397,22 @@ function ensureSchema(db, embeddingDim, options) {
       FOREIGN KEY (stash_root, file_path, body_hash)
         REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
     );
+
+    -- #624-P3: lazy graph-extraction queue. Standalone table (NO FK to
+    -- graph_files — a queued file by definition has no graph row yet).
+    -- Idempotent on (stash_root, file_path); drained highest-priority-first.
+    -- CREATE TABLE IF NOT EXISTS is the forward migration (no DB_VERSION bump).
+    CREATE TABLE IF NOT EXISTS graph_extraction_queue (
+      stash_root TEXT NOT NULL,
+      file_path  TEXT NOT NULL,
+      body_hash  TEXT NOT NULL,
+      queued_at  TEXT NOT NULL DEFAULT (datetime('now')),
+      priority   INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (stash_root, file_path)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_graph_extraction_queue_drain
+      ON graph_extraction_queue(stash_root, priority DESC, queued_at);
   `);
     // #624-P1 migration step 2: copy any renamed-aside legacy graph data into the
     // new-shape tables (just created above), then drop the legacy tables. No-op
@@ -516,6 +532,7 @@ function handleVersionUpgrade(db) {
     db.exec("DROP TABLE IF EXISTS index_dir_state");
     db.exec("DROP TABLE IF EXISTS llm_enrichment_cache");
     db.exec("DROP INDEX IF EXISTS idx_llm_cache_updated");
+    db.exec("DROP TABLE IF EXISTS graph_extraction_queue");
     db.exec("DROP TABLE IF EXISTS graph_file_relations");
     db.exec("DROP TABLE IF EXISTS graph_file_entities");
     db.exec("DROP TABLE IF EXISTS graph_files");

package/dist/indexer/db/graph-db.js

@@ -167,6 +167,54 @@ export function hasGraphData(db, stashRoot, filePath) {
         return false;
     }
 }
+/**
+ * #624-P3 — enqueue a file for lazy graph extraction. Idempotent on the
+ * (stash_root, file_path) PK: a second enqueue refreshes body_hash + queued_at
+ * and keeps the HIGHER priority. Non-blocking, no LLM call — the queued row is
+ * drained later by the graph-extraction pass. Tolerant of a missing table /
+ * db error (best-effort), but never masks the bun-test isolation guard.
+ */
+export function enqueueGraphExtraction(db, stashRoot, filePath, bodyHash, priority = 0) {
+    try {
+        db.prepare(`INSERT INTO graph_extraction_queue (stash_root, file_path, body_hash, priority)
+         VALUES (?, ?, ?, ?)
+       ON CONFLICT(stash_root, file_path) DO UPDATE SET
+         body_hash = excluded.body_hash,
+         priority  = MAX(graph_extraction_queue.priority, excluded.priority),
+         queued_at = datetime('now')`).run(stashRoot, filePath, bodyHash, priority);
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+    }
+}
+/**
+ * #624-P3 — drain up to `limit` queued files for a stash, highest-priority
+ * first (then oldest queued_at). The returned rows are DELETED from the queue
+ * in the SAME transaction (SELECT-then-DELETE-by-PK), so a drain is exactly
+ * once. Tolerant of a missing table / db error (returns []), but never masks
+ * the bun-test isolation guard.
+ */
+export function drainExtractionQueue(db, stashRoot, limit) {
+    try {
+        return db.transaction(() => {
+            const rows = db
+                .prepare(`SELECT file_path, body_hash, priority
+             FROM graph_extraction_queue
+             WHERE stash_root = ?
+             ORDER BY priority DESC, queued_at ASC
+             LIMIT ?`)
+                .all(stashRoot, limit);
+            const del = db.prepare("DELETE FROM graph_extraction_queue WHERE stash_root = ? AND file_path = ?");
+            for (const row of rows)
+                del.run(stashRoot, row.file_path);
+            return rows.map((row) => ({ filePath: row.file_path, bodyHash: row.body_hash, priority: row.priority }));
+        })();
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return [];
+    }
+}
 /**
  * Scoped loader — only the graph_meta row for a stash. Used by callers that
  * only need summary numbers (e.g. `akm graph summary`).

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

@@ -40,13 +40,14 @@ import path from "node:path";
 import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { concurrentMap } from "../../core/concurrent.js";
-import { getIndexPassConfig, resolveBatchSize } from "../../core/config/config.js";
+import { getIndexPassConfig, loadConfig, resolveBatchSize } from "../../core/config/config.js";
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { warn, warnVerbose } from "../../core/warn.js";
 import { isProcessEnabled } from "../../llm/feature-gate.js";
 import * as graphExtract from "../../llm/graph-extract.js";
 import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 import { computeBodyHash, GRAPH_SCHEMA_VERSION, getLlmCacheEntriesByRefs, getLlmCacheEntry, upsertLlmCacheEntry, } from "../db/db.js";
-import { loadStoredGraphSnapshot, replaceStoredGraph } from "../db/graph-db.js";
+import { drainExtractionQueue, loadStoredGraphSnapshot, replaceStoredGraph } from "../db/graph-db.js";
 import { walkMarkdownFiles } from "../walk/walker.js";
 import { deduplicateGraph } from "./graph-dedup.js";
 /** Schema version for the persisted artifact — bumps trigger a full rebuild. */
@@ -92,6 +93,12 @@ function computeGraphQualityTelemetry(consideredFiles, extractedFiles, entityCou
     };
 }
 export const DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES = ["memory", "knowledge"];
+/**
+ * Max number of lazy-extraction queue rows drained per pass (#624-P3). Bounds
+ * per-run work so a large backlog is spread across runs rather than processed
+ * all at once. Generous default — the queue is normally near-empty.
+ */
+const GRAPH_EXTRACTION_QUEUE_DRAIN_LIMIT = 100;
 const SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES = new Set([
     "memory",
     "knowledge",
@@ -291,8 +298,29 @@ export async function runGraphExtractionPass(ctx) {
         warnVerbose("graph extraction: skipped because no primary stash source is available.");
         return { ...EMPTY_RESULT };
     }
+    // #624-P3: drain the lazy-extraction queue BEFORE the ranked sweep, highest
+    // priority first. Queued paths are extracted individually (per-file merge,
+    // other files untouched) so they are processed even when they fall outside
+    // the normal candidate set. Default (empty queue) is a byte-identical no-op:
+    // drainExtractionQueue returns [] and the loop body never runs.
+    if (db) {
+        const drained = drainExtractionQueue(db, primary.path, GRAPH_EXTRACTION_QUEUE_DRAIN_LIMIT);
+        for (const queued of drained) {
+            if (signal?.aborted)
+                break;
+            await extractGraphForSingleFile(db, primary.path, queued.filePath, queued.bodyHash, { config, signal });
+        }
+    }
     const includeTypes = getGraphExtractionIncludeTypes(config);
-    const eligible = collectEligibleFiles(primary.path, includeTypes).filter((candidate) => !options.candidatePaths || options.candidatePaths.has(candidate.absPath));
+    let eligible = collectEligibleFiles(primary.path, includeTypes).filter((candidate) => !options.candidatePaths || options.candidatePaths.has(candidate.absPath));
+    // P2 (#624): when topN is set and a DB is available, rank the (already
+    // candidate-filtered) eligible set by utility_scores DESC and keep only the
+    // top-N. Default (topN unset) is byte-identical to today — no ranking query
+    // is issued and the eligible set is untouched. Ranking composes WITH the
+    // candidatePaths filter: scoped-then-ranked-then-sliced.
+    if (db && options.topN != null && options.topN >= 0) {
+        eligible = rankCandidatesByUtility(db, eligible, primary.path).slice(0, options.topN);
+    }
     const considered = eligible.length;
     if (considered === 0) {
         const scoped = options.candidatePaths ? ` matching ${options.candidatePaths.size} candidate path(s)` : "";
@@ -628,6 +656,178 @@ export async function runGraphExtractionPass(ctx) {
         warnings,
     };
 }
+/**
+ * Infer the asset type (`memory`, `knowledge`, …) for a path from the stash
+ * directory segment it lives under. Returns the matching include-type, or
+ * `undefined` when the path is not under a known graph-eligible type dir.
+ */
+function inferGraphTypeForPath(stashRoot, absPath) {
+    const rel = path.relative(stashRoot, absPath);
+    const firstSeg = rel.split(path.sep)[0];
+    if (!firstSeg)
+        return undefined;
+    for (const type of SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES) {
+        if (TYPE_DIRS[type] === firstSeg)
+            return type;
+    }
+    return undefined;
+}
+/**
+ * #624-P3 — extract graph data for a SINGLE file and merge it into the stored
+ * graph WITHOUT clobbering other files' rows.
+ *
+ * Re-reads the body from disk at call time (the queued body_hash is NOT trusted
+ * blindly — the file may have been deleted or changed since enqueue) and skips
+ * silently (returns `false`) when the file is gone or empty. Resolves the LLM
+ * via {@link resolveIndexPassLLM} (model-available guard: returns `false` when
+ * no provider is configured) UNLESS `opts.llmOverride` is supplied, in which
+ * case the override is the extractor seam (used by tests and by callers that
+ * already hold a resolved model).
+ *
+ * Returns `true` when a graph row was written for the file, `false` on any
+ * skip (missing file, empty body, unknown type, no model, or extraction error).
+ */
+export async function extractGraphForSingleFile(db, stashRoot, filePath, bodyHash, opts) {
+    try {
+        // Re-read from disk — never trust a stale queued body.
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            return false; // file gone / unreadable → silent skip
+        }
+        const parsed = parseFrontmatter(raw);
+        const body = parsed.content.trim();
+        if (!body)
+            return false;
+        const type = inferGraphTypeForPath(stashRoot, filePath) ?? "memory";
+        const effectiveHash = bodyHash ?? computeBodyHash(body);
+        // Extract — via the injected seam, or the real per-asset path.
+        let extraction;
+        if (opts?.llmOverride) {
+            const out = await opts.llmOverride(body);
+            extraction = {
+                entities: out.entities,
+                relations: out.relations,
+                ...(out.confidence !== undefined ? { confidence: out.confidence } : {}),
+            };
+        }
+        else {
+            const config = opts?.config ?? loadConfig();
+            if (!isProcessEnabled("index", "graph_extraction", config))
+                return false;
+            const llmConfig = resolveIndexPassLLM("graph", config);
+            if (!llmConfig)
+                return false; // model-available guard
+            const result = await graphExtract.extractGraphFromBody(llmConfig, body, opts?.signal, config);
+            extraction = {
+                entities: result.entities,
+                relations: result.relations,
+                ...(result.confidence !== undefined ? { confidence: result.confidence } : {}),
+            };
+        }
+        const entities = [...new Set(extraction.entities.map((e) => e.trim()).filter(Boolean))];
+        const relations = extraction.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((r) => r.from && r.to);
+        const node = {
+            path: filePath,
+            type,
+            bodyHash: effectiveHash,
+            entities,
+            relations,
+            ...(normalizeConfidence(extraction.confidence) !== undefined
+                ? { confidence: normalizeConfidence(extraction.confidence) }
+                : {}),
+            status: entities.length > 0 ? "extracted" : "empty",
+            reason: entities.length > 0 ? "none" : "no_graph_content",
+            extractionRunId: crypto.randomUUID(),
+        };
+        // Merge with the previously-stored nodes, scoping the refresh to JUST this
+        // path so other files' rows are preserved (and graph_meta counts refresh).
+        const previousGraph = loadGraphFile(stashRoot, db);
+        const candidatePaths = new Set([filePath]);
+        const mergedNodes = mergeGraphNodes(previousGraph.files, [node], candidatePaths);
+        const assetRefs = mergedNodes.map((n) => n.path);
+        const deduped = deduplicateGraph(mergedNodes.map((n) => ({ entities: n.entities, relations: n.relations })), assetRefs);
+        const qualityExtracted = mergedNodes.filter((n) => n.status === "extracted" && n.entities.length > 0).length;
+        const quality = computeGraphQualityTelemetry(mergedNodes.length, qualityExtracted, deduped.entities.length, deduped.relations.length);
+        const graph = {
+            schemaVersion: GRAPH_FILE_SCHEMA_VERSION,
+            generatedAt: new Date().toISOString(),
+            stashRoot,
+            files: mergedNodes,
+            entities: deduped.entities,
+            relations: deduped.relations,
+            quality,
+            ...(previousGraph.telemetry ? { telemetry: previousGraph.telemetry } : {}),
+        };
+        return writeGraphFile(stashRoot, graph, db);
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return false;
+    }
+}
+// ── Eligible-file detection ─────────────────────────────────────────────────
+/**
+ * Rank eligible graph-extraction candidates by their entry `utility_scores`,
+ * highest first, for the incremental high-signal-first sweep (P2 of #624).
+ *
+ * The join is READ-ONLY (`entries.file_path = candidate.absPath`, then
+ * `entries.id -> utility_scores.entry_id`) and does NOT re-couple the graph
+ * rows to `entries`. It reads the GLOBAL `utility_scores` table (not the
+ * per-scope `utility_scores_scoped`), so ranking is corpus-wide; `stashRoot`
+ * is accepted for call-site symmetry/future scoping but is not used to filter
+ * (the global table has no `stash_root` column).
+ *
+ * Candidates with no matching `entries` row, or an entry with no
+ * `utility_scores` row, get an effective utility of 0 (LEFT JOIN + COALESCE)
+ * and sort LAST — they are deprioritized, never dropped, so a `topN >= total`
+ * slice still includes them and they remain reachable on later runs.
+ *
+ * Ties (equal utility) break by `file_path` ASC for deterministic output.
+ * Returns a NEW array; the input is not mutated. SQLite's ~999 bound-parameter
+ * cap is respected by chunking the `IN (...)` lookup at 500.
+ *
+ * Exported for direct unit testing.
+ */
+export function rankCandidatesByUtility(db, candidates, _stashRoot) {
+    // Cannot rank without a DB → return the input unranked rather than throw.
+    // Keeps the DB-less code path (reuse-from-memory) working when topN is set.
+    if (!db || candidates.length === 0)
+        return candidates;
+    const utilityByPath = new Map();
+    const CHUNK = 500;
+    for (let start = 0; start < candidates.length; start += CHUNK) {
+        const chunk = candidates.slice(start, start + CHUNK);
+        const paths = chunk.map((c) => c.absPath);
+        const placeholders = paths.map(() => "?").join(", ");
+        const rows = db
+            .prepare(`SELECT e.file_path AS file_path, COALESCE(MAX(u.utility), 0) AS utility
+           FROM entries e
+           LEFT JOIN utility_scores u ON u.entry_id = e.id
+          WHERE e.file_path IN (${placeholders})
+          GROUP BY e.file_path`)
+            .all(...paths);
+        for (const row of rows) {
+            utilityByPath.set(row.file_path, row.utility ?? 0);
+        }
+    }
+    return [...candidates].sort((a, b) => {
+        const ua = utilityByPath.get(a.absPath) ?? 0;
+        const ub = utilityByPath.get(b.absPath) ?? 0;
+        if (ub !== ua)
+            return ub - ua; // utility DESC
+        return a.absPath < b.absPath ? -1 : a.absPath > b.absPath ? 1 : 0; // tie-break: path ASC
+    });
+}
 /**
  * Scan the primary stash for `memory:` and `knowledge:` markdown files
  * suitable for graph extraction. The directory layout convention is the

package/dist/indexer/search/ranking-contributors.js

@@ -9,6 +9,9 @@ const TYPE_BOOST = {
     agent: 0.3,
     script: 0.2,
     knowledge: 0.22,
+    // Facts are authoritative, durable declarations about the stash — rank them
+    // alongside knowledge so they surface reliably when relevant.
+    fact: 0.22,
     memory: -0.02,
 };
 const MAX_BOOST_SUM = 3.0;
@@ -206,6 +209,24 @@ const lessonStrengthContributor = {
         return Math.min(0.3, 0.06 * strength);
     },
 };
+/**
+ * Pinned-fact boost.
+ *
+ * Facts marked `pinned: true` form the small always-injected "core context"
+ * (see docs/design/fact-asset-type.md). The fact metadata contributor records
+ * a `pinned` search hint; here we give those facts a modest additive boost so
+ * the core outranks ordinary facts on otherwise-equal queries. Capped small so
+ * it cannot overpower an exact-name match.
+ */
+const pinnedFactRankingContributor = {
+    name: "pinned-fact-ranking",
+    appliesTo(item) {
+        return item.entry.type === "fact" && (item.entry.searchHints?.includes("pinned") ?? false);
+    },
+    adjust() {
+        return 0.15;
+    },
+};
 /**
  * Blend ratio for scoped vs. global utility signals.
  *
@@ -310,6 +331,7 @@ export const defaultRankingContributors = [
     graphRankingContributor,
     captureModeRankingContributor,
     lessonStrengthContributor,
+    pinnedFactRankingContributor,
     projectContextRankingContributor,
 ];
 export const defaultUtilityRankingContributors = [utilityRankingContributor];

package/dist/indexer/walk/matchers.js

@@ -78,6 +78,15 @@ const DIR_TYPE_MAP = [
         type: "session",
         test: (ext) => ext === ".md",
     },
+    {
+        // Durable stash-level facts live under `facts/<category>/<name>.md`.
+        // classifyByDirectory walks every ancestor dir, so nested category
+        // subdirs still match. Without this entry a fact file would fall through
+        // to classifyBySmartMd and be mistyped as `knowledge`.
+        dir: "facts",
+        type: "fact",
+        test: (ext) => ext === ".md",
+    },
 ];
 const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
 // Files that should never be treated as the typed asset for the surrounding

package/dist/integrations/agent/prompts.js

@@ -43,6 +43,7 @@ const TYPE_HINTS = {
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
     env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>` (the safe path — values never reach stdout/your context); do NOT run `akm env export` and read its output, as that prints values. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
+    fact: "fact assets are durable stash-level facts (personal/team/project details, coding conventions, stash-meta). Frontmatter SHOULD include `description` and a `category` (personal|team|project|convention|meta); set `pinned: true` only for the small always-injected core. Keep each fact short, high-signal, and self-contained — it is durable context, not an episodic note.",
 };
 function hintForType(type) {
     return TYPE_HINTS[type] ?? `assets of type "${type}" — produce sensible markdown with optional frontmatter.`;