akm-cli 0.9.0-beta.5 → 0.9.0-beta.6

package/CHANGELOG.md

@@ -6,6 +6,54 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0-beta.6] - 2026-06-12
+
+Pipeline optimization: new per-process config fields wire up the consolidation
+and improve pipeline knobs exposed by the optimization report — incremental
+consolidation, pool caps, distill gating, and memory inference throttling.
+
+### Added
+
+- **`consolidate.incrementalSince`** — profile config field that narrows the
+  consolidation candidate pool to memories modified within the given window
+  (e.g. `"1h"`, `"4h"`) plus their graph neighbours. Enables frequent
+  consolidation passes (e.g. `quick-shredder` every 15 min) without full-pool
+  sweeps. Absent = full-pool sweep (correct for nightly runs).
+- **`consolidate.limit`** — hard cap on memories processed per consolidation
+  pass, applied after incremental narrowing. Prevents runaway full-pool sweeps
+  in the nightly default profile.
+- **`consolidate.neighborsPerChanged`** — configurable graph-neighbour count
+  per changed memory during incremental consolidation (was hardcoded to 5).
+  `quick-shredder` sets this to 3 for a 40% candidate reduction per burst.
+- **`distill.requirePlannedRefs`** — when `true`, the distill process is
+  skipped entirely for distill-only refs when the reflect phase produced zero
+  planned refs. Eliminates hundreds of `distill-skipped` events on quiet passes
+  where all refs are on reflect cooldown.
+- **`memoryInference.minPendingCount`** — minimum pending split-parent memory
+  count below which the inference pass is skipped entirely (zero LLM calls).
+  Prevents lock acquisition on passes where there is nothing to infer.
+- **`reflect.limit`** — per-process ref limit for the reflect/distill loop,
+  applied as the improve run limit when no CLI `--limit` is given.
+- **New `reflect-distill` improve profile** — dedicated reflect + distill + 
+  memoryInference + triage profile for the every-4h `akm-improve-frequent`
+  task. `reflect.limit: 25` bounds LLM cost per pass.
+
+### Changed
+
+- **`quick-shredder` profile tuned**: `incrementalSince` `4h` → `1h`,
+  `maxChunkSize` 25 → 35, added `minPoolSize: 10`, `neighborsPerChanged: 3`,
+  `memoryInference.minPendingCount: 5`. All `profile: "qwen-9b-shredder"`
+  process references removed — falls back to default LLM.
+- **`default` improve profile** (nightly): extract disabled (dedicated
+  `akm-extract` task runs at 01:48), consolidate gets `limit: 500`,
+  reflect gets `limit: 100` and `allowedTypes`, distill gets
+  `requirePlannedRefs: true`, triage enabled at 50 accepts/run,
+  graphExtraction explicitly enabled.
+- **Cron schedule optimised**: extract reverted to `8,28,48 * * * *` (3×/hr),
+  quick-shredder shifted to `4,19,34,49` (4-min extract gap), health-report
+  shifted to `:03` (avoids `:00` collision), `akm-improve-frequent` re-enabled
+  at `45 */4` with `reflect-distill` profile.
+
 ## [0.9.0-beta.3] - 2026-06-12
 
 Stabilization batch closing the remaining 0.9.0 milestone: DB-locking and

package/dist/commands/improve/consolidate.js

@@ -809,7 +809,7 @@ export async function akmConsolidate(opts = {}) {
         };
     }
     if (opts.incrementalSince) {
-        memories = narrowToIncrementalCandidates(memories, opts.incrementalSince, warnings);
+        memories = narrowToIncrementalCandidates(memories, opts.incrementalSince, warnings, opts.neighborsPerChanged);
         if (memories.length === 0) {
             return {
                 schemaVersion: 1,
@@ -828,6 +828,10 @@ export async function akmConsolidate(opts = {}) {
             };
         }
     }
+    if (opts.limit !== undefined && memories.length > opts.limit) {
+        warnings.push(`Consolidation: pool capped at ${opts.limit} memories (limit option).`);
+        memories = memories.slice(0, opts.limit);
+    }
     // Consolidation always uses the HTTP LLM client directly — never the agent
     // CLI. The agent CLI is for interactive agent sessions (reflect, propose);
     // structured JSON generation works better and faster via HTTP.
@@ -2004,7 +2008,7 @@ function parseSinceToIso(since) {
     const multiplier = { m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
     return new Date(Date.now() - parseInt(m[1], 10) * multiplier).toISOString();
 }
-export function narrowToIncrementalCandidates(memories, since, warnings) {
+export function narrowToIncrementalCandidates(memories, since, warnings, neighborsPerChanged = 5) {
     const sinceIso = parseSinceToIso(since);
     const isChanged = (m) => {
         try {
@@ -2019,7 +2023,6 @@ export function narrowToIncrementalCandidates(memories, since, warnings) {
         return [];
     if (changed.length === memories.length)
         return memories;
-    const NEIGHBORS_PER_CHANGED = 5;
     const byName = new Map(memories.map((m) => [m.name, m]));
     const keep = new Set(changed.map((m) => m.name));
     let db;
@@ -2029,7 +2032,7 @@ export function narrowToIncrementalCandidates(memories, since, warnings) {
             const id = findEntryIdByRef(db, `memory:${m.name}`);
             if (id === undefined)
                 continue;
-            for (const hit of getNeighborsByEntryId(db, id, NEIGHBORS_PER_CHANGED + 1)) {
+            for (const hit of getNeighborsByEntryId(db, id, neighborsPerChanged + 1)) {
                 if (hit.id === id)
                     continue;
                 const entry = getEntryById(db, hit.id);

package/dist/commands/improve/improve.js

@@ -20,7 +20,7 @@ import { closeDatabase, getAllEntries, getEntryCount, getRetrievalCounts, getUti
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
 import { akmIndex } from "../../indexer/indexer.js";
-import { runMemoryInferencePass } from "../../indexer/passes/memory-inference.js";
+import { collectPendingMemories, runMemoryInferencePass, } from "../../indexer/passes/memory-inference.js";
 import { runStalenessDetectionPass } from "../../indexer/passes/staleness-detect.js";
 import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { countUsageEventsByType } from "../../indexer/usage/usage-events.js";
@@ -471,7 +471,9 @@ export async function akmImprove(options = {}) {
     options = {
         ...options,
         autoAccept: options.autoAccept ?? improveProfile.autoAccept,
-        limit: options.limit ?? improveProfile.limit,
+        // Profile-level limit, then process-level reflect.limit as fallback.
+        // CLI --limit takes precedence over both.
+        limit: options.limit ?? improveProfile?.processes?.reflect?.limit ?? improveProfile.limit,
     };
     let primaryStashDir;
     try {
@@ -1385,13 +1387,13 @@ async function runConsolidationPass(args) {
             // Tie consolidate proposals back to this improve invocation so
             // accept-rate-per-run aggregation works. Mirrors reflect/propose/extract.
             sourceRun: `consolidate-${Date.now()}`,
-            // Full-pool sweep: consolidation only runs on the nightly default-profile
-            // pass (quick/frequent disable it), so a complete re-cluster is correct and
-            // affordable here. Do NOT pass incrementalSince — the time-window narrowing
-            // it triggers permanently excludes stale-but-unmerged duplicate clusters,
-            // starving merge recall and letting the pool grow unbounded. (The narrowing
-            // was a band-aid for an every-30-min consolidation cadence that the profile
-            // split has since eliminated.) lastConsolidateTs still gates whether we run.
+            // Pass profile-configured options. incrementalSince narrows the pool to
+            // recently-changed memories + graph neighbours — use this for frequent
+            // passes (quick-shredder). Leave absent in the nightly default profile for
+            // a full-pool sweep that catches stale-but-unmerged duplicates.
+            incrementalSince: improveProfile?.processes?.consolidate?.incrementalSince,
+            limit: improveProfile?.processes?.consolidate?.limit,
+            neighborsPerChanged: improveProfile?.processes?.consolidate?.neighborsPerChanged,
             maxChunkSize: improveProfile?.processes?.consolidate?.maxChunkSize,
             // Honor profile.autoAccept (already merged into options.autoAccept at the
             // top of akmImprove). The CLI parser always supplies 90 when --auto-accept
@@ -2067,6 +2069,14 @@ async function runImproveLoopStage(args) {
     // receives only its fair share of the wall-clock budget.
     const remainingBudgetMs = () => Math.max(0, budgetMs - (Date.now() - startMs));
     const RECENT_ERRORS_CAP = 3;
+    // requirePlannedRefs guard: when the distill profile sets this flag, skip
+    // distill for distill-only refs if the reflect phase produced no planned refs.
+    // Prevents the distill loop from generating hundreds of distill-skipped events
+    // on quiet passes (all refs on reflect cooldown, no new signal to distill).
+    const requirePlannedRefs = improveProfile?.processes?.distill?.requirePlannedRefs === true;
+    const _distillOnlyRefNames = new Set(distillOnlyRefs.map((r) => r.ref));
+    const hasReflectEligibleRefs = loopRefs.some((r) => !_distillOnlyRefNames.has(r.ref));
+    const skipDistillDueToRequirePlannedRefs = requirePlannedRefs && !hasReflectEligibleRefs;
     // R-2 / #389: Self-Consistency multi-sample voting helpers.
     // Wang et al. arXiv:2203.11171 — N=3 samples beat single-shot on reasoning tasks.
     const SC_THRESHOLD = options.selfConsistencyThreshold ?? 0.7;
@@ -2364,6 +2374,18 @@ async function runImproveLoopStage(args) {
                 info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
                 continue;
             }
+            // requirePlannedRefs guard: skip distill for distill-only refs when no
+            // reflect-eligible refs were planned this run, preventing mass skip events.
+            if (skipDistillDueToRequirePlannedRefs && isDistillOnly) {
+                actions.push({
+                    ref: planned.ref,
+                    mode: "distill-skipped",
+                    result: { ok: true, reason: "require_planned_refs" },
+                });
+                completedCount++;
+                info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
+                continue;
+            }
             // See `isDistillCandidateRef` — excludes `lesson:*` (and anything else in
             // DISTILL_REFUSED_INPUT_TYPES) so distill never gets queued for an input
             // it will refuse.
@@ -2634,9 +2656,23 @@ export async function runImproveMaintenancePasses(args) {
         // candidates from the filesystem-of-truth. The this-run set is still
         // logged as a hint but no longer used as a filter.
         const memoryInferenceDisabledByProfile = improveProfile?.processes?.memoryInference?.enabled === false;
+        const minPendingCount = improveProfile?.processes?.memoryInference?.minPendingCount;
+        const pendingBelowMinCount = (() => {
+            if (!primaryStashDir || minPendingCount === undefined || minPendingCount <= 0)
+                return false;
+            const pending = collectPendingMemories(primaryStashDir).length;
+            if (pending < minPendingCount) {
+                info(`[improve] memory inference skipped (${pending} pending < minPendingCount ${minPendingCount})`);
+                return true;
+            }
+            return false;
+        })();
         if (memoryInferenceDisabledByProfile) {
             info("[improve] memory inference skipped (disabled by improve profile)");
         }
+        else if (pendingBelowMinCount) {
+            // skipped — message already emitted above
+        }
         else {
             const hintRefs = memoryRefsForInference.size;
             info(hintRefs > 0

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

@@ -144,6 +144,20 @@ export const ImproveProcessConfigSchema = z
     // on the `extract` process.
     minContentChars: z.number().int().min(0).optional(),
     maxChunkSize: z.number().int().min(1).max(50).optional(),
+    // Consolidate process: narrow candidate pool to memories modified within
+    // this duration window plus their graph neighbours. Only meaningful on
+    // the `consolidate` process. Absent = full-pool sweep.
+    incrementalSince: z.string().optional(),
+    // Consolidate process: hard cap on memories processed per pass.
+    // Reflect/distill: max refs processed (same as profile-level `limit`).
+    limit: positiveInt.optional(),
+    // Consolidate process: graph neighbours per changed memory during
+    // incremental consolidation. Default 5. Only meaningful with incrementalSince.
+    neighborsPerChanged: z.number().int().min(1).optional(),
+    // Distill process: skip distill entirely when reflect produced zero planned refs.
+    requirePlannedRefs: z.boolean().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
     // sessions below which the extract pass skips entirely (emits an
     // `improve_skipped` event with `reason: "below_min_new_sessions"`). 0

package/dist/scripts/migrate-storage.js

@@ -15510,6 +15510,11 @@ var init_config_schema = __esm(() => {
     maxTotalChars: positiveInt.optional(),
     minContentChars: exports_external.number().int().min(0).optional(),
     maxChunkSize: exports_external.number().int().min(1).max(50).optional(),
+    incrementalSince: exports_external.string().optional(),
+    limit: positiveInt.optional(),
+    neighborsPerChanged: exports_external.number().int().min(1).optional(),
+    requirePlannedRefs: exports_external.boolean().optional(),
+    minPendingCount: exports_external.number().int().min(0).optional(),
     minNewSessions: exports_external.number().int().min(0).optional(),
     indexSessions: exports_external.boolean().optional(),
     minSessionDuration: exports_external.number().min(0).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.5",
+  "version": "0.9.0-beta.6",
   "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": [
@@ -51,7 +51,7 @@
   },
   "scripts": {
     "preinstall": "node -e \"var ua=process.env.npm_config_user_agent||'';var major=parseInt((process.versions.node||'0').split('.')[0],10);if(process.versions.bun||ua.startsWith('bun/')||process.env.BUN_INSTALL||major>=20){process.exit(0)}console.error('\\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh), Node.js >= 20, or the prebuilt binary.\\n  Install options:\\n    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\\n    2. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
-    "build": "rm -rf dist && bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
+    "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "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",