akm-cli 0.9.0-beta.53 → 0.9.0-beta.55

package/dist/commands/read/curate.js

@@ -58,7 +58,7 @@ const CURATE_REFERENCE_QUERY_RE = /\b(?:reference|docs?|guide|how|explain|learn|
  * Fire-and-forget: log a curate event to the usage_events table and events.jsonl.
  * Never blocks the caller; errors are silently ignored.
  */
-function logCurateEvent(query, result) {
+function logCurateEvent(query, result, eventSource = "user") {
     const itemRefs = result.items.map((item) => ("ref" in item ? item.ref : `registry:${item.id}`));
     appendEvent({
         eventType: "curate",
@@ -73,7 +73,7 @@ function logCurateEvent(query, result) {
                     itemCount: result.items.length,
                     itemRefs,
                 }),
-                source: "user",
+                source: eventSource,
             });
             for (const item of result.items) {
                 if (!("ref" in item) || typeof item.ref !== "string")
@@ -82,7 +82,7 @@ function logCurateEvent(query, result) {
                     event_type: "curate",
                     query,
                     entry_ref: item.ref,
-                    source: "user",
+                    source: eventSource,
                 });
             }
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
@@ -106,7 +106,7 @@ export async function akmCurate(options) {
             source,
         }));
     const result = await curateSearchResults(options.query, searchResponse, limit, options.type);
-    logCurateEvent(options.query, result);
+    logCurateEvent(options.query, result, options.eventSource);
     return result;
 }
 export async function curateSearchResults(query, result, limit, selectedType) {

package/dist/commands/read/remember-cli.js

@@ -1,8 +1,8 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { defineCommand } from "citty";
-import { output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "../remember.js";
@@ -26,7 +26,7 @@ async function fetchSimilarMemories(query, excludeRef) {
     }
 }
 // ── Command definition ────────────────────────────────────────────────────────
-export const rememberCommand = defineCommand({
+export const rememberCommand = defineJsonCommand({
     meta: {
         name: "remember",
         description: "Record a memory in the default stash",
@@ -102,141 +102,42 @@ export const rememberCommand = defineCommand({
         },
     },
     async run({ args }) {
-        return runWithJsonErrors(async () => {
-            const body = readMemoryContent(resolveRememberContentArg(args.content));
-            // `--name` is a flat name; subdirectory placement is `--path`'s job.
-            assertFlatAssetName(args.name);
-            // Determine if the user has requested any structured metadata mode.
-            // Collect all --tag occurrences directly from process.argv because citty
-            // only exposes the last value for repeated string flags.
-            const rawTags = parseAllFlagValues("--tag");
-            // Collect scope flags. Scope alone counts as structured metadata so we
-            // emit frontmatter, but it does NOT trigger the "tags required" check —
-            // memory + scope (no tags) is a valid combination for multi-tenant use.
-            const scopeFields = {};
-            if (typeof args.user === "string" && args.user.trim())
-                scopeFields.user = args.user.trim();
-            if (typeof args.agent === "string" && args.agent.trim())
-                scopeFields.agent = args.agent.trim();
-            if (typeof args.run === "string" && args.run.trim())
-                scopeFields.run = args.run.trim();
-            if (typeof args.channel === "string" && args.channel.trim())
-                scopeFields.channel = args.channel.trim();
-            const hasScope = Object.keys(scopeFields).length > 0;
-            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
-            const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
-            if (!hasStructuredArgs) {
-                // Phase 1B / Rec 7: even the zero-flag hot-path emits
-                // `captureMode: hot` + `beliefState: asserted` so user-supplied
-                // memories outrank background-derived ones during ranking.
-                const frontmatterBlock = buildMemoryFrontmatter({
-                    captureMode: "hot",
-                    beliefState: "asserted",
-                });
-                const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
-                // Derive the asset slug from the body (not the frontmatter block);
-                // otherwise inferAssetName would key off the leading `---` delimiter.
-                const result = await writeMarkdownAsset({
-                    type: "memory",
-                    content: contentWithFrontmatter,
-                    name: args.name,
-                    fallbackPrefix: "memory",
-                    preferredName: inferAssetName(body, "memory"),
-                    force: args.force,
-                    target: args.target,
-                    path: args.path,
-                });
-                appendEvent({
-                    eventType: "remember",
-                    ref: result.ref,
-                    metadata: { path: result.path, force: args.force === true },
-                });
-                if (args.showSimilar) {
-                    const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
-                    output("remember", { ok: true, ...result, similar });
-                }
-                else {
-                    output("remember", { ok: true, ...result });
-                }
-                return;
-            }
-            // ── Accumulate metadata from all three modes ──────────────────────────
-            // Start with CLI args (Mode 1: always)
-            const tags = [...rawTags];
-            // --description is persisted as-is; LLM enrichment may fill it if absent.
-            let description = args.description || undefined;
-            let source = args.source;
-            let observed_at;
-            let expires;
-            let subjective;
-            // Resolve --expires to an ISO date string
-            if (args.expires) {
-                const durationMs = parseDuration(args.expires);
-                const expiresDate = new Date(Date.now() + durationMs);
-                expires = expiresDate.toISOString().slice(0, 10);
-            }
-            // Mode 2: --auto heuristics
-            if (args.auto) {
-                const auto = runAutoHeuristics(body);
-                for (const t of auto.tags) {
-                    if (!tags.includes(t))
-                        tags.push(t);
-                }
-                if (!source && auto.source)
-                    source = auto.source;
-                if (!observed_at && auto.observed_at)
-                    observed_at = auto.observed_at;
-                if (!subjective && auto.subjective)
-                    subjective = auto.subjective;
-            }
-            // Mode 3: --enrich LLM (fail-soft)
-            if (args.enrich) {
-                const enriched = await runLlmEnrich(body);
-                for (const t of enriched.tags) {
-                    if (!tags.includes(t))
-                        tags.push(t);
-                }
-                if (!description && enriched.description)
-                    description = enriched.description;
-                if (!observed_at && enriched.observed_at)
-                    observed_at = enriched.observed_at;
-            }
-            // ── Required-field check (before any write) ───────────────────────────
-            // Tags remain required when the user explicitly asked for tag-bearing
-            // metadata (--tag / --enrich / --description / --source / --expires).
-            // `--auto` alone is allowed even when its heuristics derive zero tags.
-            // Scope-only writes (`akm remember "..." --user u1`) also skip this
-            // check — scope is independent metadata and a memory with only scope is
-            // valid.
-            const missing = [];
-            if (hasTagRequiringArgs && tags.length === 0)
-                missing.push("tags");
-            if (missing.length > 0) {
-                throw new UsageError(`Memory is missing required frontmatter field(s): ${missing.join(", ")}. ` +
-                    "Provide them via --tag <value>, --auto (heuristics), or --enrich (LLM).");
-            }
-            // ── Build frontmatter and write ───────────────────────────────────────
-            // Phase 1B / Rec 7: the hot-path CLI write always marks the memory as
-            // `captureMode: hot` and `beliefState: asserted`. Ranking applies a
-            // hot-capture boost so user-supplied memories outrank otherwise-equal
-            // background-derived ones.
+        const body = readMemoryContent(resolveRememberContentArg(args.content));
+        // `--name` is a flat name; subdirectory placement is `--path`'s job.
+        assertFlatAssetName(args.name);
+        // Determine if the user has requested any structured metadata mode.
+        // Collect all --tag occurrences directly from process.argv because citty
+        // only exposes the last value for repeated string flags.
+        const rawTags = parseAllFlagValues("--tag");
+        // Collect scope flags. Scope alone counts as structured metadata so we
+        // emit frontmatter, but it does NOT trigger the "tags required" check —
+        // memory + scope (no tags) is a valid combination for multi-tenant use.
+        const scopeFields = {};
+        for (const k of ["user", "agent", "run", "channel"]) {
+            const v = getStringArg(args, k);
+            if (v)
+                scopeFields[k] = v;
+        }
+        const hasScope = Object.keys(scopeFields).length > 0;
+        const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
+        const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
+        if (!hasStructuredArgs) {
+            // Phase 1B / Rec 7: even the zero-flag hot-path emits
+            // `captureMode: hot` + `beliefState: asserted` so user-supplied
+            // memories outrank background-derived ones during ranking.
             const frontmatterBlock = buildMemoryFrontmatter({
-                description,
-                tags,
-                source,
-                observed_at,
-                expires,
-                subjective,
                 captureMode: "hot",
                 beliefState: "asserted",
-                ...(hasScope ? { scope: scopeFields } : {}),
             });
             const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+            // Derive the asset slug from the body (not the frontmatter block);
+            // otherwise inferAssetName would key off the leading `---` delimiter.
             const result = await writeMarkdownAsset({
                 type: "memory",
                 content: contentWithFrontmatter,
                 name: args.name,
                 fallbackPrefix: "memory",
+                preferredName: inferAssetName(body, "memory"),
                 force: args.force,
                 target: args.target,
                 path: args.path,
@@ -244,22 +145,116 @@ export const rememberCommand = defineCommand({
             appendEvent({
                 eventType: "remember",
                 ref: result.ref,
-                metadata: {
-                    path: result.path,
-                    force: args.force === true,
-                    tagCount: tags.length,
-                    enriched: args.enrich === true,
-                    auto: args.auto === true,
-                    ...(hasScope ? { scope: scopeFields } : {}),
-                },
+                metadata: { path: result.path, force: args.force === true },
             });
             if (args.showSimilar) {
-                const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+                const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
                 output("remember", { ok: true, ...result, similar });
             }
             else {
                 output("remember", { ok: true, ...result });
             }
+            return;
+        }
+        // ── Accumulate metadata from all three modes ──────────────────────────
+        // Start with CLI args (Mode 1: always)
+        const tags = [...rawTags];
+        // --description is persisted as-is; LLM enrichment may fill it if absent.
+        let description = args.description || undefined;
+        let source = args.source;
+        let observed_at;
+        let expires;
+        let subjective;
+        // Resolve --expires to an ISO date string
+        if (args.expires) {
+            const durationMs = parseDuration(args.expires);
+            const expiresDate = new Date(Date.now() + durationMs);
+            expires = expiresDate.toISOString().slice(0, 10);
+        }
+        // Mode 2: --auto heuristics
+        if (args.auto) {
+            const auto = runAutoHeuristics(body);
+            for (const t of auto.tags) {
+                if (!tags.includes(t))
+                    tags.push(t);
+            }
+            if (!source && auto.source)
+                source = auto.source;
+            if (!observed_at && auto.observed_at)
+                observed_at = auto.observed_at;
+            if (!subjective && auto.subjective)
+                subjective = auto.subjective;
+        }
+        // Mode 3: --enrich LLM (fail-soft)
+        if (args.enrich) {
+            const enriched = await runLlmEnrich(body);
+            for (const t of enriched.tags) {
+                if (!tags.includes(t))
+                    tags.push(t);
+            }
+            if (!description && enriched.description)
+                description = enriched.description;
+            if (!observed_at && enriched.observed_at)
+                observed_at = enriched.observed_at;
+        }
+        // ── Required-field check (before any write) ───────────────────────────
+        // Tags remain required when the user explicitly asked for tag-bearing
+        // metadata (--tag / --enrich / --description / --source / --expires).
+        // `--auto` alone is allowed even when its heuristics derive zero tags.
+        // Scope-only writes (`akm remember "..." --user u1`) also skip this
+        // check — scope is independent metadata and a memory with only scope is
+        // valid.
+        const missing = [];
+        if (hasTagRequiringArgs && tags.length === 0)
+            missing.push("tags");
+        if (missing.length > 0) {
+            throw new UsageError(`Memory is missing required frontmatter field(s): ${missing.join(", ")}. ` +
+                "Provide them via --tag <value>, --auto (heuristics), or --enrich (LLM).");
+        }
+        // ── Build frontmatter and write ───────────────────────────────────────
+        // Phase 1B / Rec 7: the hot-path CLI write always marks the memory as
+        // `captureMode: hot` and `beliefState: asserted`. Ranking applies a
+        // hot-capture boost so user-supplied memories outrank otherwise-equal
+        // background-derived ones.
+        const frontmatterBlock = buildMemoryFrontmatter({
+            description,
+            tags,
+            source,
+            observed_at,
+            expires,
+            subjective,
+            captureMode: "hot",
+            beliefState: "asserted",
+            ...(hasScope ? { scope: scopeFields } : {}),
+        });
+        const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+        const result = await writeMarkdownAsset({
+            type: "memory",
+            content: contentWithFrontmatter,
+            name: args.name,
+            fallbackPrefix: "memory",
+            force: args.force,
+            target: args.target,
+            path: args.path,
+        });
+        appendEvent({
+            eventType: "remember",
+            ref: result.ref,
+            metadata: {
+                path: result.path,
+                force: args.force === true,
+                tagCount: tags.length,
+                enriched: args.enrich === true,
+                auto: args.auto === true,
+                ...(hasScope ? { scope: scopeFields } : {}),
+            },
         });
+        if (args.showSimilar) {
+            const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+            output("remember", { ok: true, ...result, similar });
+        }
+        else {
+            output("remember", { ok: true, ...result });
+        }
     },
 });

package/dist/commands/read/search-cli.js

@@ -21,13 +21,15 @@ import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../outpu
 import { akmCurate } from "./curate.js";
 import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
-// AKM_EVENT_SOURCE attributes a query to a `user` invocation or the internal
-// `improve` loop so the event log can distinguish them; any other value is
-// treated as unset.
+// AKM_EVENT_SOURCE attributes a query to a `user` invocation, the internal
+// `improve` loop, or the `task` runner so the event log can distinguish
+// genuine demand from machine traffic; any other value is treated as unset.
 function resolveEventSource() {
     const raw = process.env.AKM_EVENT_SOURCE;
     if (raw === "improve")
         return "improve";
+    if (raw === "task")
+        return "task";
     if (raw === "user")
         return "user";
     return undefined;
@@ -84,7 +86,7 @@ export const searchCommand = defineJsonCommand({
         const includeProposed = args["include-proposed"] === true;
         const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
         const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
-        const includeSessions = getHyphenatedBoolean(args, "include-sessions");
+        const includeSessions = args["include-sessions"];
         const result = await akmSearch({
             query,
             type,
@@ -129,7 +131,7 @@ export const curateCommand = defineJsonCommand({
         const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
         const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
         const source = parseSearchSource(args.source ?? "stash");
-        const curated = await akmCurate({ query: args.query, type, limit, source });
+        const curated = await akmCurate({ query: args.query, type, limit, source, eventSource: resolveEventSource() });
         output("curate", curated);
     },
 });

package/dist/commands/read/search.js

@@ -16,8 +16,8 @@ import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { isTransientStashPath } from "../../core/paths.js";
 import { bumpUtilityScoresBatch, getEntryIdByFilePath } from "../../indexer/db/db.js";
+import { resolveReadSources } from "../../indexer/read-preflight.js";
 import { searchLocal } from "../../indexer/search/db-search.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
@@ -57,7 +57,7 @@ export async function akmSearch(input) {
     else {
         source = parsedSource;
     }
-    let allSources = resolveSourceEntries(undefined, config);
+    let allSources = resolveReadSources(undefined, config).sources;
     // When a named source was requested, narrow the sources list to just that entry.
     // `resolveSourceEntries` sets `registryId` to `entry.name` for each config source.
     if (namedSourceName !== undefined) {
@@ -243,7 +243,11 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
             }
             // Bump utility scores for all resolved entries (MemRL retrieval signal).
             // The indexer overwrites these at next reindex; bumps are temporary hints.
-            const resolvedIds = resolved.map((r) => r.entryId).filter((id) => id !== undefined);
+            // Gated to user-sourced events: pipeline searches (improve probes, task
+            // runner) must not feed the utility signal (meta-review 05 DRIFT-6 —
+            // the bump previously fired unconditionally, so even correctly-tagged
+            // machine traffic inflated utility).
+            const resolvedIds = eventSource === "user" ? resolved.map((r) => r.entryId).filter((id) => id !== undefined) : [];
             if (resolvedIds.length > 0) {
                 let scopeKey;
                 try {

package/dist/commands/read/show.js

@@ -28,10 +28,10 @@ import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../co
 import { appendEvent, readEvents } from "../../core/events.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 { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.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";
@@ -147,10 +147,8 @@ export async function akmShowUnified(input) {
         }
     }
     // Auto-index when stale so the index is current before lookup.
-    const allSources = resolveSourceEntries();
-    if (allSources.length > 0) {
-        await ensureIndex(allSources[0].path);
-    }
+    const { primarySource } = resolveReadSources();
+    await ensurePrimaryIndexForRead(primarySource);
     // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
     // Scope filter narrows resolution: if --scope was supplied, the asset's