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

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.`;

package/dist/output/renderers.js

@@ -468,6 +468,44 @@ const sessionMdRenderer = {
         };
     },
 };
+// ── 9. fact-md ───────────────────────────────────────────────────────────────
+/**
+ * Renderer for the `fact` asset type. A fact is durable stash-level semantic
+ * knowledge (personal/team/project details, coding conventions, stash-meta).
+ * It carries `category` (personal|team|project|convention|meta) and an
+ * optional `pinned` flag marking it as part of the always-injected core. The
+ * renderer surfaces a one-liner (category + pinned marker) so an agent can tell
+ * at a glance what kind of fact it is and whether it is core context.
+ */
+const factMdRenderer = {
+    name: "fact-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
+        const fm = parsed.data;
+        const category = asNonEmptyString(fm.category);
+        const description = asNonEmptyString(fm.description);
+        const pinned = fm.pinned === true;
+        const headerParts = [
+            category ? `category: ${category}` : undefined,
+            pinned ? "pinned (core context)" : undefined,
+        ].filter((p) => !!p);
+        const action = [
+            "Durable stash fact — apply it as background context.",
+            headerParts.length > 0 ? headerParts.join("  ") : undefined,
+        ]
+            .filter((p) => !!p)
+            .join("\n");
+        return {
+            type: "fact",
+            name,
+            path: ctx.absPath,
+            action,
+            description,
+            content: parsed.content,
+        };
+    },
+};
 function applySessionMetadata(entry, ctx) {
     try {
         const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
@@ -501,6 +539,34 @@ function applyTocMetadata(entry, ctx) {
         // Non-fatal: skip TOC if file can't be read
     }
 }
+/**
+ * Fact metadata: surface `category` and the `pinned` core marker as tags +
+ * search hints (no dedicated DB columns — same encoding pattern as session /
+ * task). `pinned` is mirrored to both a `pinned` tag and a `pinned` search
+ * hint so the ranking contributor can detect it and queries can target it.
+ */
+function applyFactMetadata(entry, ctx) {
+    try {
+        const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
+        const tags = new Set([...(entry.tags ?? []), "fact"]);
+        const hints = new Set(entry.searchHints ?? []);
+        const category = asNonEmptyString(fm.category);
+        if (category) {
+            tags.add(category);
+            hints.add(`category:${category}`);
+        }
+        if (fm.pinned === true) {
+            tags.add("pinned");
+            hints.add("pinned");
+        }
+        entry.tags = Array.from(tags).filter(Boolean);
+        if (hints.size > 0)
+            entry.searchHints = Array.from(hints).filter(Boolean);
+    }
+    catch {
+        // Non-fatal: skip metadata extraction on parse error
+    }
+}
 /**
  * Parse frontmatter, apply description (if not already set) and merge tags
  * into `entry`. Returns the raw frontmatter data object so callers can access
@@ -660,6 +726,11 @@ registerMetadataContributor({
     appliesTo: ({ rendererName }) => rendererName === "session-md",
     contribute: (entry, ctx) => applySessionMetadata(entry, ctx.renderContext),
 });
+registerMetadataContributor({
+    name: "fact-md-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "fact-md",
+    contribute: (entry, ctx) => applyFactMetadata(entry, ctx.renderContext),
+});
 // ── Registration ─────────────────────────────────────────────────────────────
 /** All built-in renderers. */
 const builtinRenderers = [
@@ -676,6 +747,7 @@ const builtinRenderers = [
     secretFileRenderer,
     taskMdRenderer,
     sessionMdRenderer,
+    factMdRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -687,4 +759,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, envFileRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, secretFileRenderer, skillMdRenderer, wikiMdRenderer, workflowMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, envFileRenderer, factMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, secretFileRenderer, skillMdRenderer, wikiMdRenderer, workflowMdRenderer, };

package/dist/scripts/migrate-storage.js

@@ -8240,6 +8240,25 @@ function applyTocMetadata(entry, ctx) {
       entry.toc = toc.headings;
   } catch {}
 }
+function applyFactMetadata(entry, ctx) {
+  try {
+    const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
+    const tags = new Set([...entry.tags ?? [], "fact"]);
+    const hints = new Set(entry.searchHints ?? []);
+    const category = asNonEmptyString(fm.category);
+    if (category) {
+      tags.add(category);
+      hints.add(`category:${category}`);
+    }
+    if (fm.pinned === true) {
+      tags.add("pinned");
+      hints.add("pinned");
+    }
+    entry.tags = Array.from(tags).filter(Boolean);
+    if (hints.size > 0)
+      entry.searchHints = Array.from(hints).filter(Boolean);
+  } catch {}
+}
 function applyFrontmatterDescriptionAndTags(entry, ctx) {
   const parsed = parseFrontmatter(ctx.content());
   const fm = parsed.data;
@@ -8386,6 +8405,11 @@ var init_renderers = __esm(() => {
     appliesTo: ({ rendererName }) => rendererName === "session-md",
     contribute: (entry, ctx) => applySessionMetadata(entry, ctx.renderContext)
   });
+  registerMetadataContributor({
+    name: "fact-md-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "fact-md",
+    contribute: (entry, ctx) => applyFactMetadata(entry, ctx.renderContext)
+  });
 });
 
 // src/core/asset/asset-registry.ts
@@ -8520,6 +8544,12 @@ var init_asset_spec = __esm(() => {
       ...markdownSpec,
       rendererName: "session-md",
       actionBuilder: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``
+    },
+    fact: {
+      stashDir: "facts",
+      ...markdownSpec,
+      rendererName: "fact-md",
+      actionBuilder: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`
     }
   };
   TYPE_DIRS = Object.fromEntries(Object.entries(ASSET_SPECS_INTERNAL).map(([type, spec]) => [type, spec.stashDir]));
@@ -15822,6 +15852,7 @@ var init_config_schema = __esm(() => {
     requirePlannedRefs: exports_external.boolean().optional(),
     dueDays: exports_external.number().int().min(0).optional(),
     maxPerRun: positiveInt.optional(),
+    topN: positiveInt.optional(),
     minPendingCount: exports_external.number().int().min(0).optional(),
     minNewSessions: exports_external.number().int().min(0).optional(),
     maxSessionsPerRun: exports_external.number().int().min(0).optional(),
@@ -15920,6 +15951,7 @@ var init_config_schema = __esm(() => {
     processes: ImproveProfileProcessesSchema.optional(),
     autoAccept: nonNegativeNumber.optional(),
     limit: positiveInt.optional(),
+    maxCycles: positiveInt.optional(),
     symmetricValence: exports_external.boolean().optional(),
     sync: exports_external.object({
       enabled: exports_external.boolean().optional(),
@@ -16046,7 +16078,8 @@ var init_config_schema = __esm(() => {
     "workflow",
     "lesson",
     "task",
-    "wiki"
+    "wiki",
+    "fact"
   ];
   INDEX_PASS_PROVIDER_KEYS = new Set([
     "endpoint",
@@ -16062,7 +16095,8 @@ var init_config_schema = __esm(() => {
     "llm",
     "graphExtractionBatchSize",
     "graphExtractionIncludeTypes",
-    "memoryInferenceBatchSize"
+    "memoryInferenceBatchSize",
+    "lazyGraphExtraction"
   ]);
   IndexPassConfigSchema = exports_external.preprocess((raw, ctx) => {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -16080,7 +16114,7 @@ var init_config_schema = __esm(() => {
       if (!INDEX_PASS_KNOWN_KEYS.has(key)) {
         ctx.addIssue({
           code: exports_external.ZodIssueCode.custom,
-          message: `Unknown key \`${[...ctx.path ?? [], key].join(".")}\`. Per-pass entries support \`llm\` ` + "(boolean opt-out), `graphExtractionBatchSize`, `graphExtractionIncludeTypes`, and " + "`memoryInferenceBatchSize`."
+          message: `Unknown key \`${[...ctx.path ?? [], key].join(".")}\`. Per-pass entries support \`llm\` ` + "(boolean opt-out), `graphExtractionBatchSize`, `graphExtractionIncludeTypes`, " + "`memoryInferenceBatchSize`, and `lazyGraphExtraction`."
         });
         return raw;
       }
@@ -16097,7 +16131,8 @@ var init_config_schema = __esm(() => {
     llm: exports_external.boolean().optional(),
     graphExtractionBatchSize: positiveInt.optional(),
     graphExtractionIncludeTypes: exports_external.array(exports_external.enum(GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED)).nonempty().optional(),
-    memoryInferenceBatchSize: positiveInt.optional()
+    memoryInferenceBatchSize: positiveInt.optional(),
+    lazyGraphExtraction: exports_external.boolean().optional()
   }).passthrough());
   MetadataEnhanceSchema = exports_external.object({ enabled: exports_external.boolean().optional() }).strict();
   StalenessDetectionSchema = exports_external.object({
@@ -16968,6 +17003,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 \u2014 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);
   `);
   migrateGraphDataFromLegacy(db);
   db.exec(`
@@ -17035,6 +17086,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");
@@ -18058,6 +18110,8 @@ __export(exports_graph_db, {
   loadGraphFilesOnly: () => loadGraphFilesOnly,
   loadGraphEntitiesByPath: () => loadGraphEntitiesByPath,
   hasGraphData: () => hasGraphData,
+  enqueueGraphExtraction: () => enqueueGraphExtraction,
+  drainExtractionQueue: () => drainExtractionQueue,
   deleteStoredGraph: () => deleteStoredGraph
 });
 import fs13 from "fs";
@@ -18187,6 +18241,36 @@ function hasGraphData(db, stashRoot, filePath) {
     return false;
   }
 }
+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);
+  }
+}
+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 [];
+  }
+}
 function loadGraphMetaOnly(stashPath, db) {
   return loadStoredGraphMeta(stashPath, db);
 }

package/dist/scripts/migrations/import-fs-improve-runs-to-db.js

@@ -8126,6 +8126,25 @@ function applyTocMetadata(entry, ctx) {
       entry.toc = toc.headings;
   } catch {}
 }
+function applyFactMetadata(entry, ctx) {
+  try {
+    const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
+    const tags = new Set([...entry.tags ?? [], "fact"]);
+    const hints = new Set(entry.searchHints ?? []);
+    const category = asNonEmptyString(fm.category);
+    if (category) {
+      tags.add(category);
+      hints.add(`category:${category}`);
+    }
+    if (fm.pinned === true) {
+      tags.add("pinned");
+      hints.add("pinned");
+    }
+    entry.tags = Array.from(tags).filter(Boolean);
+    if (hints.size > 0)
+      entry.searchHints = Array.from(hints).filter(Boolean);
+  } catch {}
+}
 function applyFrontmatterDescriptionAndTags(entry, ctx) {
   const parsed = parseFrontmatter(ctx.content());
   const fm = parsed.data;
@@ -8272,6 +8291,11 @@ var init_renderers = __esm(() => {
     appliesTo: ({ rendererName }) => rendererName === "session-md",
     contribute: (entry, ctx) => applySessionMetadata(entry, ctx.renderContext)
   });
+  registerMetadataContributor({
+    name: "fact-md-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "fact-md",
+    contribute: (entry, ctx) => applyFactMetadata(entry, ctx.renderContext)
+  });
 });
 
 // src/core/asset/asset-registry.ts
@@ -8406,6 +8430,12 @@ var init_asset_spec = __esm(() => {
       ...markdownSpec,
       rendererName: "session-md",
       actionBuilder: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``
+    },
+    fact: {
+      stashDir: "facts",
+      ...markdownSpec,
+      rendererName: "fact-md",
+      actionBuilder: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`
     }
   };
   TYPE_DIRS = Object.fromEntries(Object.entries(ASSET_SPECS_INTERNAL).map(([type, spec]) => [type, spec.stashDir]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.26",
+  "version": "0.9.0-beta.27",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -56,12 +56,13 @@
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
     "check:changed": "bun test tests/output-baseline.test.ts tests/integration/e2e.test.ts tests/stash-search.test.ts && bun run lint && bunx tsc --noEmit",
     "sweep:tmp": "bun scripts/sweep-test-tmp.ts",
-    "test": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-12} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
-    "test:unit": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-12} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
-    "test:integration": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-12} --timeout=30000 ./tests/integration ./tests/commands ./tests/workflows",
+    "test": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-1} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
+    "test:unit": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-1} --timeout=30000 ./tests --path-ignore-patterns=tests/integration",
+    "test:integration": "bun run sweep:tmp && bun test --parallel=${TEST_PARALLEL:-1} --timeout=30000 ./tests/integration ./tests/commands ./tests/workflows",
+    "test:unit:shard": "bun run sweep:tmp && bun test --parallel=1 --timeout=30000 ./tests --path-ignore-patterns=tests/integration --shard=${SHARD:?set SHARD=k/N}",
+    "test:integration:shard": "bun run sweep:tmp && bun test --parallel=1 --timeout=30000 ./tests/integration ./tests/commands ./tests/workflows --shard=${SHARD:?set SHARD=k/N}",
     "test:node-smoke": "bun scripts/node-smoke.ts",
     "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
-    "test:sharded": "bun test ./tests --shard=1/4 & bun test ./tests --shard=2/4 & bun test ./tests --shard=3/4 & bun test ./tests --shard=4/4 & wait",
     "test:time": "bun scripts/test-timing-report.ts",
     "lint:isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:devto-posts": "bun scripts/lint-devto-posts.ts",