akm-cli 0.5.0 → 0.6.0-rc1

package/dist/providers/static-index.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, toErrorMessage } from "../common";
+import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../common";
 import { asString } from "../github";
 import { getRegistryIndexCacheDir } from "../paths";
 import { registerProvider } from "../registry-factory";
@@ -23,8 +23,8 @@ class StaticIndexProvider {
             const index = await loadIndex(this.config);
             if (index) {
                 const regName = this.config.name;
-                for (const kit of index.kits) {
-                    allKits.push({ kit, registryName: regName });
+                for (const stash of index.stashes) {
+                    allKits.push({ stash, registryName: regName });
                 }
             }
         }
@@ -58,7 +58,9 @@ async function loadIndex(entry) {
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}`);
         }
-        const data = (await response.json());
+        // Cap at 50 MB — registry indexes can grow large but unbounded
+        // responses from a compromised server would OOM us.
+        const data = await jsonWithByteCap(response, 50 * 1024 * 1024);
         const index = parseRegistryIndex(data);
         if (index) {
             writeCachedIndex(cachePath, index);
@@ -120,20 +122,20 @@ export function parseRegistryIndex(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
         return null;
     const obj = data;
-    if (typeof obj.version !== "number" || (obj.version !== 1 && obj.version !== 2))
+    if (typeof obj.version !== "number" || obj.version !== 3)
         return null;
     if (typeof obj.updatedAt !== "string")
         return null;
-    if (!Array.isArray(obj.kits))
+    if (!Array.isArray(obj.stashes))
         return null;
-    const kits = obj.kits.flatMap((raw) => {
-        const kit = parseKitEntry(raw);
-        return kit ? [kit] : [];
+    const stashes = obj.stashes.flatMap((raw) => {
+        const stash = parseStashEntry(raw);
+        return stash ? [stash] : [];
     });
-    return { version: obj.version, updatedAt: obj.updatedAt, kits };
+    return { version: obj.version, updatedAt: obj.updatedAt, stashes };
 }
-// ── Kit entry parsing ───────────────────────────────────────────────────────
-function parseKitEntry(raw) {
+// ── Stash entry parsing ───────────────────────────────────────────────────────
+function parseStashEntry(raw) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw))
         return null;
     const obj = raw;
@@ -160,23 +162,23 @@ function parseKitEntry(raw) {
     };
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
-function scoreKits(kits, query, limit) {
+function scoreKits(stashes, query, limit) {
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const scored = [];
-    for (const { kit, registryName } of kits) {
-        const score = scoreKit(kit, tokens);
+    for (const { stash, registryName } of stashes) {
+        const score = scoreStash(stash, tokens);
         if (score > 0) {
-            scored.push({ kit, registryName, score });
+            scored.push({ stash, registryName, score });
         }
     }
     scored.sort((a, b) => b.score - a.score);
-    return scored.slice(0, limit).map(({ kit, registryName, score }) => toSearchHit(kit, score, registryName));
+    return scored.slice(0, limit).map(({ stash, registryName, score }) => toSearchHit(stash, score, registryName));
 }
-function scoreKit(kit, tokens) {
+function scoreStash(stash, tokens) {
     let score = 0;
-    const nameLower = kit.name.toLowerCase();
-    const descLower = (kit.description ?? "").toLowerCase();
-    const tagsLower = (kit.tags ?? []).map((t) => t.toLowerCase());
+    const nameLower = stash.name.toLowerCase();
+    const descLower = (stash.description ?? "").toLowerCase();
+    const tagsLower = (stash.tags ?? []).map((t) => t.toLowerCase());
     for (const token of tokens) {
         // Exact name match is strongest signal
         if (nameLower === token) {
@@ -197,34 +199,34 @@ function scoreKit(kit, tokens) {
             score += 0.2;
         }
         // Author match
-        if (kit.author?.toLowerCase().includes(token)) {
+        if (stash.author?.toLowerCase().includes(token)) {
             score += 0.15;
         }
     }
     // Normalize by token count so multi-word queries don't inflate scores
     return tokens.length > 0 ? score / tokens.length : 0;
 }
-function toSearchHit(kit, score, registryName) {
+function toSearchHit(stash, score, registryName) {
     const metadata = {};
-    if (kit.latestVersion)
-        metadata.version = kit.latestVersion;
-    if (kit.author)
-        metadata.author = kit.author;
-    if (kit.license)
-        metadata.license = kit.license;
-    if (kit.assetTypes?.length)
-        metadata.assetTypes = kit.assetTypes.join(", ");
+    if (stash.latestVersion)
+        metadata.version = stash.latestVersion;
+    if (stash.author)
+        metadata.author = stash.author;
+    if (stash.license)
+        metadata.license = stash.license;
+    if (stash.assetTypes?.length)
+        metadata.assetTypes = stash.assetTypes.join(", ");
     return {
-        source: kit.source,
-        id: kit.id,
-        title: kit.name,
-        description: kit.description,
-        ref: kit.ref,
-        installRef: buildInstallRef(kit.source, kit.ref),
-        homepage: kit.homepage,
+        source: stash.source,
+        id: stash.id,
+        title: stash.name,
+        description: stash.description,
+        ref: stash.ref,
+        installRef: buildInstallRef(stash.source, stash.ref),
+        homepage: stash.homepage,
         score: Math.round(score * 1000) / 1000,
         metadata,
-        curated: kit.curated,
+        curated: stash.curated,
         registryName,
     };
 }
@@ -255,16 +257,16 @@ function parseAssetEntry(raw) {
     };
 }
 // ── Asset-level scoring ─────────────────────────────────────────────────────
-function scoreAssets(kits, query, limit) {
+function scoreAssets(stashes, query, limit) {
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     if (tokens.length === 0)
         return [];
     const scored = [];
-    for (const { kit, registryName } of kits) {
-        if (!kit.assets || kit.assets.length === 0)
+    for (const { stash, registryName } of stashes) {
+        if (!stash.assets || stash.assets.length === 0)
             continue;
-        const installRef = buildInstallRef(kit.source, kit.ref);
-        for (const asset of kit.assets) {
+        const installRef = buildInstallRef(stash.source, stash.ref);
+        for (const asset of stash.assets) {
             const score = scoreAsset(asset, tokens);
             if (score > 0) {
                 scored.push({
@@ -274,7 +276,7 @@ function scoreAssets(kits, query, limit) {
                         assetName: asset.name,
                         description: asset.description,
                         estimatedTokens: asset.estimatedTokens,
-                        kit: { id: kit.id, name: kit.name },
+                        stash: { id: stash.id, name: stash.name },
                         registryName,
                         action: `akm add ${installRef}`,
                         score: Math.round(score * 1000) / 1000,

package/dist/registry-build-index.js

@@ -1,18 +1,19 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fetchWithRetry } from "./common";
+import { fetchWithRetry, jsonWithByteCap } from "./common";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
-import { copyIncludedPaths, findNearestIncludeConfig } from "./kit-include";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { parseRegistryIndex } from "./providers/static-index";
-import { detectStashRoot, extractTarGzSecure } from "./registry-install";
+import { copyIncludedPaths, findNearestIncludeConfig } from "./stash-include";
+import { detectStashRoot } from "./stash-providers/provider-utils";
+import { extractTarGzSecure } from "./stash-providers/tar-utils";
 import { walkStashFlat } from "./walker";
 const DEFAULT_NPM_REGISTRY_BASE = "https://registry.npmjs.org";
 const DEFAULT_MANUAL_ENTRIES_PATH = path.resolve("manual-entries.json");
 const DEFAULT_OUTPUT_PATH = path.resolve("index.json");
-const REQUIRED_KEYWORDS = ["akm-kit"];
-const GITHUB_TOPICS = ["akm-kit"];
+const REQUIRED_KEYWORDS = ["akm-stash"];
+const GITHUB_TOPICS = ["akm-stash"];
 const EXCLUDED_REPOS = new Set(["itlackey/akm"]);
 const EXCLUDED_NPM_PACKAGES = new Set(["akm-cli"]);
 const EMPTY_INSPECTION = {};
@@ -25,11 +26,11 @@ export async function buildRegistryIndex(options) {
         scanNpm(npmRegistryBase),
         scanGithub(githubApiBase),
     ]);
-    const kits = deduplicateKits([...manualKits, ...npmKits, ...githubKits]).sort((a, b) => a.name.localeCompare(b.name));
+    const stashes = deduplicateStashes([...manualKits, ...npmKits, ...githubKits]).sort((a, b) => a.name.localeCompare(b.name));
     const index = {
-        version: 2,
+        version: 3,
         updatedAt: new Date().toISOString(),
-        kits,
+        stashes,
     };
     return {
         index,
@@ -37,7 +38,7 @@ export async function buildRegistryIndex(options) {
             manual: manualKits.length,
             npm: npmKits.length,
             github: githubKits.length,
-            total: kits.length,
+            total: stashes.length,
         },
         paths: {
             manualEntriesPath,
@@ -51,7 +52,7 @@ export function writeRegistryIndex(index, outPath) {
     return resolved;
 }
 async function scanNpm(npmRegistryBase) {
-    const kits = [];
+    const stashes = [];
     const seen = new Set();
     for (const keyword of REQUIRED_KEYWORDS) {
         let offset = 0;
@@ -83,7 +84,7 @@ async function scanNpm(npmRegistryBase) {
                 }
                 const inspection = await inspectNpmPackage(npmRegistryBase, latestMetadata).catch(() => EMPTY_INSPECTION);
                 const tags = mergeStrings((pkg.keywords ?? []).filter((value) => !REQUIRED_KEYWORDS.includes(value.toLowerCase())), inspection.tags);
-                kits.push(normalizeKit({
+                stashes.push(normalizeStash({
                     id,
                     name: pkg.name,
                     description: inspection.description ?? pkg.description,
@@ -103,7 +104,7 @@ async function scanNpm(npmRegistryBase) {
             offset += size;
         }
     }
-    return kits;
+    return stashes;
 }
 async function inspectNpmPackage(_npmRegistryBase, latestMetadata) {
     const dist = asRecord(latestMetadata.dist);
@@ -121,7 +122,7 @@ async function inspectNpmPackage(_npmRegistryBase, latestMetadata) {
     };
 }
 async function scanGithub(githubApiBase) {
-    const kits = [];
+    const stashes = [];
     const seen = new Set();
     const headers = githubHeaders();
     for (const topic of GITHUB_TOPICS) {
@@ -140,7 +141,7 @@ async function scanGithub(githubApiBase) {
                 seen.add(id);
                 const inspection = await inspectArchive(`${githubApiBase}/repos/${repo.full_name}/tarball/${encodeURIComponent(repo.default_branch)}`, headers).catch(() => EMPTY_INSPECTION);
                 const topics = repo.topics.filter((value) => !GITHUB_TOPICS.includes(value));
-                kits.push(normalizeKit({
+                stashes.push(normalizeStash({
                     id,
                     name: repo.name,
                     description: inspection.description ?? repo.description ?? undefined,
@@ -160,7 +161,7 @@ async function scanGithub(githubApiBase) {
             page += 1;
         }
     }
-    return kits;
+    return stashes;
 }
 async function inspectArchive(url, headers) {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-registry-build-"));
@@ -269,36 +270,42 @@ function applyIncludeConfigForInspection(stashRoot, tempDir, searchRoot) {
 async function loadManualEntries(manualEntriesPath) {
     try {
         const raw = JSON.parse(fs.readFileSync(manualEntriesPath, "utf8"));
-        const candidateKits = Array.isArray(raw) ? raw : asRecord(raw).kits;
-        const parsed = parseRegistryIndex({ version: 2, updatedAt: new Date().toISOString(), kits: candidateKits });
+        const candidateKits = Array.isArray(raw) ? raw : asRecord(raw).stashes;
+        const parsed = parseRegistryIndex({ version: 3, updatedAt: new Date().toISOString(), stashes: candidateKits });
         if (!parsed)
             return [];
-        return parsed.kits.map((kit) => normalizeKit({ ...kit, curated: kit.curated ?? true }));
+        return parsed.stashes.map((stash) => normalizeStash({ ...stash, curated: stash.curated ?? true }));
     }
     catch {
         return [];
     }
 }
+// npm / GitHub API JSON pages; 25 MB cap covers the largest realistic
+// search result set while still bounding memory against a malicious or
+// misconfigured upstream that streams unbounded JSON.
+const BUILD_INDEX_JSON_BYTE_CAP = 25 * 1024 * 1024;
 async function fetchJson(url, headers) {
     const response = await fetchWithRetry(url, headers ? { headers } : undefined, { timeout: 30_000 });
     if (!response.ok) {
+        // Error-body sampling is intentionally small; 4 KB is plenty to
+        // include upstream hints in the thrown error.
         const body = await response.text().catch(() => "");
         throw new Error(`HTTP ${response.status} from ${url}: ${body.slice(0, 200)}`);
     }
-    return (await response.json());
+    return jsonWithByteCap(response, BUILD_INDEX_JSON_BYTE_CAP);
 }
-function deduplicateKits(kits) {
+function deduplicateStashes(stashes) {
     const byId = new Map();
-    for (const kit of kits) {
-        const existing = byId.get(kit.id);
-        byId.set(kit.id, existing ? mergeEntries(existing, kit) : kit);
+    for (const stash of stashes) {
+        const existing = byId.get(stash.id);
+        byId.set(stash.id, existing ? mergeEntries(existing, stash) : stash);
     }
     return [...byId.values()];
 }
 function mergeEntries(a, b) {
     const assets = mergeAssets(a.assets, b.assets);
     const assetTypes = mergeStrings(a.assetTypes, b.assetTypes, assets ? deriveAssetTypes(assets) : undefined);
-    return normalizeKit({
+    return normalizeStash({
         id: a.id,
         name: a.name,
         description: a.description ?? b.description,
@@ -343,12 +350,12 @@ function extractNonReservedKeywords(value) {
         .filter((item) => !REQUIRED_KEYWORDS.includes(item.toLowerCase()));
     return filtered.length > 0 ? filtered : undefined;
 }
-function normalizeKit(kit) {
-    const assets = kit.assets ? sortAssets(kit.assets) : undefined;
+function normalizeStash(stash) {
+    const assets = stash.assets ? sortAssets(stash.assets) : undefined;
     return {
-        ...kit,
-        ...(kit.tags && kit.tags.length > 0 ? { tags: kit.tags } : {}),
-        ...(kit.assetTypes && kit.assetTypes.length > 0 ? { assetTypes: kit.assetTypes } : {}),
+        ...stash,
+        ...(stash.tags && stash.tags.length > 0 ? { tags: stash.tags } : {}),
+        ...(stash.assetTypes && stash.assetTypes.length > 0 ? { assetTypes: stash.assetTypes } : {}),
         ...(assets && assets.length > 0 ? { assets } : {}),
     };
 }

package/dist/registry-factory.js

@@ -4,9 +4,9 @@
  * Maps registry provider type identifiers (e.g. "static-index", "skills-sh")
  * to factory functions that create RegistryProvider instances.
  *
- * "Registry" here refers to the kit discovery registries (npm, GitHub, static
+ * "Registry" here refers to the stash discovery registries (npm, GitHub, static
  * index files) — not to be confused with the stash provider factory map in
- * stash-provider-factory.ts or the installed-kit operations in installed-kits.ts.
+ * stash-provider-factory.ts or the installed-stash operations in installed-stashes.ts.
  */
 import { createProviderRegistry } from "./create-provider-registry";
 // ── Factory map ─────────────────────────────────────────────────────────────

package/dist/registry-resolve.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { fetchWithRetry } from "./common";
+import { fetchWithRetry, jsonWithByteCap } from "./common";
 import { UsageError } from "./errors";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
 /**
@@ -451,7 +451,7 @@ function fileUriToPath(ref) {
 /**
  * Build a human-readable local ID from an absolute path.
  *   /home/user/akm/skills     → ~/akm/skills
- *   /tmp/my-kit               → /tmp/my-kit
+ *   /tmp/my-stash               → /tmp/my-stash
  */
 function toReadableLocalId(absolutePath) {
     const home = os.homedir();
@@ -571,16 +571,20 @@ export function maxSatisfying(versions, range) {
     candidates.sort((a, b) => compareSemver(b.parsed, a.parsed));
     return candidates[0].version;
 }
+// Cap JSON responses at 10 MB — npm package manifests and GitHub API
+// responses are typically a few KB; a compromised registry streaming
+// tens of MB of JSON is a DoS surface, not a feature.
+const REGISTRY_JSON_BYTE_CAP = 10 * 1024 * 1024;
 async function fetchJson(url, headers) {
     const response = await fetchWithRetry(url, { headers });
     if (!response.ok) {
         throw new Error(`Request failed (${response.status}) for ${url}`);
     }
-    return (await response.json());
+    return jsonWithByteCap(response, REGISTRY_JSON_BYTE_CAP);
 }
 async function tryFetchJson(url, headers) {
     const response = await fetchWithRetry(url, { headers });
     if (!response.ok)
         return null;
-    return (await response.json());
+    return jsonWithByteCap(response, REGISTRY_JSON_BYTE_CAP);
 }

package/dist/registry-search.js

@@ -2,8 +2,7 @@ import { toErrorMessage } from "./common";
 import { DEFAULT_CONFIG, loadConfig } from "./config";
 import { resolveProviderFactory } from "./registry-factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
-import "./providers/static-index";
-import "./providers/skills-sh";
+import "./providers/index";
 // ── Public API ──────────────────────────────────────────────────────────────
 export async function searchRegistry(query, options) {
     const trimmed = query.trim();
@@ -33,9 +32,28 @@ export async function searchRegistry(query, options) {
         const value = result.value;
         if (!value)
             continue;
-        allHits.push(...value.hits);
-        if (value.assetHits)
-            allAssetHits.push(...value.assetHits);
+        let dropped = 0;
+        for (const hit of value.hits) {
+            if (isCompleteHit(hit)) {
+                allHits.push(hit);
+            }
+            else {
+                dropped++;
+            }
+        }
+        if (value.assetHits) {
+            for (const hit of value.assetHits) {
+                if (isCompleteAssetHit(hit)) {
+                    allAssetHits.push(hit);
+                }
+                else {
+                    dropped++;
+                }
+            }
+        }
+        if (dropped > 0) {
+            warnings.push(`Registry returned ${dropped} incomplete hit(s); dropped from response.`);
+        }
         if (value.warnings)
             warnings.push(...value.warnings);
     }
@@ -97,3 +115,42 @@ function clampLimit(limit) {
         return 20;
     return Math.min(100, Math.max(1, Math.trunc(limit)));
 }
+// A complete hit must have the fields downstream consumers (CLI rendering,
+// `akm add`) rely on. Providers that return partial records would otherwise
+// surface as `{}` in the JSON output.
+function isCompleteHit(hit) {
+    if (!hit || typeof hit !== "object")
+        return false;
+    return (typeof hit.source === "string" &&
+        typeof hit.id === "string" &&
+        hit.id.length > 0 &&
+        typeof hit.title === "string" &&
+        hit.title.length > 0 &&
+        typeof hit.ref === "string" &&
+        hit.ref.length > 0 &&
+        typeof hit.installRef === "string" &&
+        hit.installRef.length > 0);
+}
+function isCompleteAssetHit(hit) {
+    if (!hit || typeof hit !== "object")
+        return false;
+    if (hit.type !== "registry-asset" ||
+        typeof hit.assetType !== "string" ||
+        hit.assetType.length === 0 ||
+        typeof hit.assetName !== "string" ||
+        hit.assetName.length === 0 ||
+        typeof hit.action !== "string") {
+        return false;
+    }
+    // `stash` is required by the consumer (output shaping + asset-action display);
+    // rejecting incomplete stashes here keeps malformed objects out of the JSON
+    // output. Flagged in PR #168 review (#9).
+    const stash = hit.stash;
+    if (!stash || typeof stash !== "object")
+        return false;
+    if (typeof stash.id !== "string" || stash.id.length === 0)
+        return false;
+    if (typeof stash.name !== "string" || stash.name.length === 0)
+        return false;
+    return true;
+}

package/dist/remember.js

@@ -0,0 +1,172 @@
+/**
+ * Memory-specific helpers for `akm remember`.
+ *
+ * Extracted from `src/cli.ts` so the domain logic (frontmatter assembly,
+ * heuristic derivation, LLM enrichment) is testable in isolation and the
+ * CLI entry point stays focused on argument parsing + output routing.
+ */
+import { stringify as yamlStringify } from "yaml";
+import { tryReadStdinText } from "./common";
+import { loadConfig } from "./config";
+import { UsageError } from "./errors";
+import { warn } from "./warn";
+/**
+ * Parse a shorthand duration string to a number of milliseconds.
+ * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
+ */
+export function parseDuration(s) {
+    const match = s.trim().match(/^(\d+)([dhm])$/i);
+    if (!match)
+        throw new UsageError(`Invalid --expires format "${s}". Use shorthand like 30d, 12h, or 6m.`);
+    const n = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    if (unit === "d")
+        return n * 24 * 60 * 60 * 1000;
+    if (unit === "h")
+        return n * 60 * 60 * 1000;
+    // 'm' = months, approximated as 30 days
+    return n * 30 * 24 * 60 * 60 * 1000;
+}
+/**
+ * Build a YAML frontmatter block from memory metadata.
+ *
+ * Uses `yaml.stringify` so values containing newlines, colons, or other
+ * YAML metacharacters are safely quoted. The previous implementation
+ * interpolated user input directly into `key: value` lines, which let a
+ * `description` containing `\n` + `tags: [x]` inject additional keys into
+ * the frontmatter — that is no longer possible here.
+ *
+ * Only includes fields that are present (non-empty).
+ */
+export function buildMemoryFrontmatter(fields) {
+    const obj = {};
+    if (fields.description && fields.description.trim())
+        obj.description = fields.description;
+    if (fields.tags && fields.tags.length > 0)
+        obj.tags = fields.tags;
+    if (fields.source && fields.source.trim())
+        obj.source = fields.source;
+    if (fields.observed_at && fields.observed_at.trim())
+        obj.observed_at = fields.observed_at;
+    if (fields.expires && fields.expires.trim())
+        obj.expires = fields.expires;
+    if (fields.subjective)
+        obj.subjective = true;
+    // No fields populated → emit a bare delimiter pair so callers don't
+    // produce `---\n{}\n---` (the YAML serializer's empty-object form).
+    if (Object.keys(obj).length === 0)
+        return "---\n---";
+    const serialized = yamlStringify(obj).trimEnd();
+    return `---\n${serialized}\n---`;
+}
+/**
+ * Read memory content from the positional arg or stdin.
+ * Throws {@link UsageError} if neither is populated.
+ */
+export function readMemoryContent(contentArg) {
+    const content = contentArg ?? tryReadStdinText();
+    if (!content?.trim()) {
+        throw new UsageError("Memory content is required. Pass quoted text or pipe markdown into stdin.");
+    }
+    return content;
+}
+/**
+ * Run heuristic analysis on memory body text. Returns derived metadata
+ * fields without modifying any files. Pure TS, zero network, zero latency.
+ */
+export function runAutoHeuristics(body) {
+    const tags = [];
+    // Fenced code block present → tag "code"
+    if (/^```/m.test(body)) {
+        tags.push("code");
+    }
+    // First-person pronoun → subjective
+    const subjective = /\b(I|we|my|our)\b/.test(body) ? true : undefined;
+    // First URL-shaped token → source
+    const urlMatch = body.match(/https?:\/\/[^\s)>'"]+/);
+    const source = urlMatch ? urlMatch[0] : undefined;
+    // ISO date token or obvious relative date phrase → observed_at
+    let observed_at;
+    const isoMatch = body.match(/\b(\d{4}-\d{2}-\d{2})\b/);
+    if (isoMatch) {
+        observed_at = isoMatch[1];
+    }
+    else {
+        const relMatch = body.match(/\b(today|yesterday|last\s+week|last\s+month)\b/i);
+        if (relMatch) {
+            const phrase = relMatch[1].toLowerCase();
+            const now = new Date();
+            if (phrase === "today") {
+                observed_at = now.toISOString().slice(0, 10);
+            }
+            else if (phrase === "yesterday") {
+                const d = new Date(now);
+                d.setDate(d.getDate() - 1);
+                observed_at = d.toISOString().slice(0, 10);
+            }
+            else if (phrase.startsWith("last week")) {
+                const d = new Date(now);
+                d.setDate(d.getDate() - 7);
+                observed_at = d.toISOString().slice(0, 10);
+            }
+            else if (phrase.startsWith("last month")) {
+                const d = new Date(now);
+                d.setMonth(d.getMonth() - 1);
+                observed_at = d.toISOString().slice(0, 10);
+            }
+        }
+    }
+    return { tags, source, observed_at, subjective };
+}
+/** Hard timeout for the `--enrich` LLM call. Write-path must not block on a misbehaving endpoint. */
+const LLM_ENRICH_TIMEOUT_MS = 10_000;
+/**
+ * Attempt LLM enrichment of memory metadata. Returns merged metadata
+ * fields on success. On timeout, unreachable, or invalid JSON — returns
+ * empty result and emits a warning. Never throws; always resolves.
+ */
+export async function runLlmEnrich(body) {
+    const config = loadConfig();
+    if (!config.llm) {
+        warn("Warning: --enrich requires an LLM to be configured. Run `akm config set llm` to configure one.");
+        return { tags: [] };
+    }
+    const { chatCompletion, parseJsonResponse } = await import("./llm.js");
+    const prompt = `You are a memory tagger for a developer knowledge base.
+Given the memory text below, return ONLY a JSON object with these fields:
+- "tags": array of 1-5 short lowercase keyword tags
+- "description": one-sentence summary (optional)
+- "observed_at": ISO date (YYYY-MM-DD) if the text references a specific date (optional)
+
+Memory text:
+${body.slice(0, 2000)}
+
+Return ONLY the JSON object, no prose, no markdown fences.`;
+    try {
+        const result = await Promise.race([
+            chatCompletion(config.llm, [
+                { role: "system", content: "Return only valid JSON. No prose." },
+                { role: "user", content: prompt },
+            ], { maxTokens: 256, temperature: 0.1 }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("LLM enrichment timed out")), LLM_ENRICH_TIMEOUT_MS)),
+        ]);
+        const parsed = parseJsonResponse(result);
+        if (!parsed) {
+            warn("Warning: --enrich received invalid JSON from the LLM. Writing memory without enrichment.");
+            return { tags: [] };
+        }
+        const tags = Array.isArray(parsed.tags)
+            ? parsed.tags.filter((t) => typeof t === "string" && t.trim().length > 0)
+            : [];
+        const description = typeof parsed.description === "string" && parsed.description.trim() ? parsed.description.trim() : undefined;
+        const observed_at = typeof parsed.observed_at === "string" && /^\d{4}-\d{2}-\d{2}$/.test(parsed.observed_at.trim())
+            ? parsed.observed_at.trim()
+            : undefined;
+        return { tags, description, observed_at };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        warn(`Warning: --enrich failed (${msg}). Writing memory without enrichment.`);
+        return { tags: [] };
+    }
+}