akm-cli 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -6,6 +6,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-05-05
+
+### Added
+
+- **`akm index --enrich` opt-in for LLM passes** — index-time enrichment work such as metadata enhancement, memory inference, and graph extraction now runs only when explicitly requested with `--enrich`. Default indexing is faster and no longer surprises operators with LLM-backed work during normal maintenance runs.
+- **Config backup snapshots before writes** — config writes now create AKM cache backups so setup/config flows have a recovery path if a config is overwritten or corrupted during development or testing.
+
+### Changed
+
+- **Setup wizard UX refresh** — `akm setup` now better reflects the real configured state: source prompts are ordered more sensibly, configured and preserved stash information is surfaced, agent defaults can be selected explicitly (including disabled), and post-setup indexing does not implicitly enable enrichment.
+- **CI workflows updated for current GitHub Actions runtimes** — CI, release, and publishing workflows now use current action majors (`checkout@v5`, `cache@v5`, `setup-node@v5`, `upload-artifact@v5`, `download-artifact@v6`) to stay off deprecated Node 20 action runtimes.
+- **Technical investigation notes updated** — the index investigation note now reflects the latest `.stash.json` migration status, current green CI runs, and the narrowed remaining compatibility surface ahead of `v0.8.0`.
+
+### Fixed
+
+- **Embedding-dimension drift on read-only DB opens** — read/telemetry paths no longer mutate the live index schema with the default embedding dimension. `akm info`, search/show parity paths, and related readers now preserve the configured embedding shape instead of downgrading vector tables.
+- **Incremental index churn across multiple source layouts** — incremental indexing is now significantly more stable for filename-less legacy metadata, wiki-root sources, repo-root git stash layouts, non-indexed companion files, and cross-source dedupe cases.
+- **Git source indexing for repo-root stashes** — git-backed sources no longer assume a `<repo>/content` subtree; repo-root stash layouts are indexed correctly and cached mirrors are treated as fresh instead of being needlessly refreshed.
+- **`show` metadata no longer depends on `.stash.json`** — command and skill summary/show metadata now comes from file-local frontmatter and renderer parsing rather than the deprecated disk fallback sidecar.
+- **`.stash.json` no longer drives incremental stale detection** — editing `.stash.json` alone no longer forces directories to rescan during incremental indexing.
+
+### Internal
+
+- **Ranking and scoring fixtures migrated toward file-local metadata** — routine benchmark and regression fixtures now prefer markdown frontmatter or inline script metadata, with `.stash.json` retained only for intentional legacy-compatibility coverage that still exercises explicit-file override behavior.
+- **Production-path ranking regression coverage** — ranking regression tests now build their fixture index through the production indexer rather than a custom `.stash.json` crawler, reducing fixture drift and improving confidence in the real indexing/search path.
+
+### Added
+
+- **One-shot URL ingest for `akm import` and `akm wiki stash`** — both commands now accept a single HTTP/HTTPS URL in addition to file paths and stdin. `akm import <url>` fetches the exact page, converts it to markdown, and writes it into `knowledge/` using a URL-path-derived default name. `akm wiki stash <wiki> <url>` fetches the exact page, converts it to markdown, and writes it into `wikis/<wiki>/raw/`. Neither command registers a persistent website source or crawls linked pages.
+
+### Changed
+
+- **Shared website ingest boundary** — website URL validation, single-page fetch/convert, and website mirror generation now live in a dedicated shared ingest module. The website source provider is a thin adapter, and `akm add`, `akm import`, and `akm wiki stash` all reuse the same core website-ingest path.
+- **`.stash.json` docs deprecation timeline** — the docs now explicitly state that `.stash.json` is deprecated, remains only as a 0.7.x compatibility bridge, and will be removed in v0.8.0 to match the current aggressive pre-release phase-out posture.
+
 ## [0.7.0]
 
 ### Added

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import fs from "node:fs";
 import path from "node:path";
+import * as p from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./commands/config-cli";
@@ -25,14 +26,14 @@ import { akmClone } from "./commands/source-clone";
 import { addStash } from "./commands/source-manage";
 import { parseAssetRef } from "./core/asset-ref";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./core/asset-spec";
-import { isWithin, resolveStashDir, tryReadStdinText } from "./core/common";
+import { isHttpUrl, isWithin, resolveStashDir, tryReadStdinText } from "./core/common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./core/config";
 import { ConfigError, NotFoundError, UsageError } from "./core/errors";
 import { appendEvent } from "./core/events";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./core/paths";
 import { setQuiet, setVerbose, warn } from "./core/warn";
 import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
-import { closeDatabase, findEntryIdByRef, openDatabase } from "./indexer/db";
+import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "./indexer/db";
 import { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
 import { insertUsageEvent } from "./indexer/usage-events";
@@ -44,6 +45,7 @@ import { buildRegistryIndex, writeRegistryIndex } from "./registry/build-index";
 import { resolveSourcesForOrigin } from "./registry/origin-resolve";
 import { saveGitStash } from "./sources/providers/git";
 import { resolveAssetPath } from "./sources/resolve";
+import { fetchWebsiteMarkdownSnapshot } from "./sources/website-ingest";
 import { pkgVersion } from "./version";
 import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "./workflows/authoring";
 import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "./workflows/cli";
@@ -138,15 +140,53 @@ const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
         full: { type: "boolean", description: "Force full reindex", default: false },
-        verbose: { type: "boolean", description: "Print indexing summary and phase progress to stderr", default: false },
+        enrich: { type: "boolean", description: "Enable LLM inference and enrichment passes", default: false },
+        verbose: { type: "boolean", description: "Print phase-by-phase indexing progress to stderr", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await akmIndex({
-                full: args.full,
-                onProgress: args.verbose ? ({ message }) => console.error(`[index] ${message}`) : undefined,
-            });
-            output("index", result);
+            const outputMode = getOutputMode();
+            const controller = new AbortController();
+            const abort = () => controller.abort(new Error("index interrupted"));
+            process.once("SIGINT", abort);
+            process.once("SIGTERM", abort);
+            const spin = !args.verbose && outputMode.format === "text" ? p.spinner() : null;
+            if (spin) {
+                spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
+            }
+            let latestMessage = "";
+            try {
+                const result = await akmIndex({
+                    full: args.full,
+                    enrich: args.enrich,
+                    onProgress: ({ message, processed, total }) => {
+                        latestMessage = message;
+                        const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
+                        if (args.verbose) {
+                            console.error(`[index] ${progressPrefix}${message}`);
+                        }
+                        else if (spin) {
+                            spin.stop(`${progressPrefix}${message}`);
+                            spin.start(`${progressPrefix}${message}`);
+                        }
+                    },
+                    signal: controller.signal,
+                });
+                if (spin) {
+                    spin.stop(`Indexed ${result.totalEntries} assets.`);
+                }
+                output("index", result);
+            }
+            catch (error) {
+                if (spin) {
+                    spin.stop(latestMessage ? `Indexing failed after: ${latestMessage}` : "Indexing failed.");
+                }
+                throw error;
+            }
+            finally {
+                process.off("SIGINT", abort);
+                process.off("SIGTERM", abort);
+            }
         });
     },
 });
@@ -939,7 +979,7 @@ const feedbackCommand = defineCommand({
             }
             const signal = args.positive ? "positive" : "negative";
             const metadata = args.note ? JSON.stringify({ note: args.note }) : undefined;
-            const db = openDatabase();
+            const db = openExistingDatabase();
             try {
                 const entryId = findEntryIdByRef(db, ref);
                 if (entryId === undefined) {
@@ -1057,6 +1097,12 @@ function readKnowledgeContent(source) {
         preferredName: path.basename(resolvedSource, path.extname(resolvedSource)),
     };
 }
+async function readKnowledgeInput(source) {
+    if (!isHttpUrl(source))
+        return readKnowledgeContent(source);
+    const snapshot = await fetchWebsiteMarkdownSnapshot(source);
+    return { content: snapshot.content, preferredName: snapshot.preferredName };
+}
 async function writeMarkdownAsset(options) {
     // Resolve write target via the v1 precedence chain (`--target` →
     // `defaultWriteTarget` → working stash). Per spec §10 step 5, this is the
@@ -1609,12 +1655,12 @@ function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
 const importKnowledgeCommand = defineCommand({
     meta: {
         name: "import",
-        description: "Import a knowledge document into the default stash",
+        description: "Import a knowledge document or URL into the default stash",
     },
     args: {
         source: {
             type: "positional",
-            description: 'Source file path, or "-" to read from stdin',
+            description: 'Source file path, URL, or "-" to read from stdin',
             required: true,
         },
         name: {
@@ -1633,11 +1679,11 @@ const importKnowledgeCommand = defineCommand({
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
-            const { content, preferredName } = readKnowledgeContent(args.source);
+            const { content, preferredName } = await readKnowledgeInput(args.source);
             const result = await writeMarkdownAsset({
                 type: "knowledge",
                 content,
-                name: args.name,
+                name: args.name ?? (isHttpUrl(args.source) ? preferredName : undefined),
                 fallbackPrefix: "knowledge",
                 preferredName,
                 force: args.force,
@@ -2227,17 +2273,17 @@ const wikiSearchCommand = defineCommand({
 const wikiStashCommand = defineCommand({
     meta: {
         name: "stash",
-        description: "Copy a source into wikis/<name>/raw/<slug>.md with frontmatter. Source may be a file path or '-' for stdin.",
+        description: "Copy a source into wikis/<name>/raw/<slug>.md with frontmatter. Source may be a file path, URL, or '-' for stdin.",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
-        source: { type: "positional", description: "Source file path, or '-' to read from stdin", required: true },
+        source: { type: "positional", description: "Source file path, URL, or '-' to read from stdin", required: true },
         as: { type: "string", description: "Preferred slug base (defaults to source filename or first-line slug)" },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { stashRaw } = await import("./wiki/wiki.js");
-            const { content, preferredName } = readKnowledgeContent(args.source);
+            const { content, preferredName } = await readKnowledgeInput(args.source);
             const stashDir = resolveStashDir();
             const result = stashRaw({
                 stashDir,

package/dist/commands/history.js

@@ -16,8 +16,7 @@
 import { parseAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
 import { readEvents } from "../core/events";
-import { closeDatabase, openDatabase } from "../indexer/db";
-import { ensureUsageEventsSchema } from "../indexer/usage-events";
+import { closeDatabase, openExistingDatabase } from "../indexer/db";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
 const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -106,13 +105,9 @@ export async function akmHistory(options = {}) {
         normalizedRef = trimmed;
     }
     const sinceNormalized = options.since !== undefined ? normalizeSince(options.since) : undefined;
-    const db = options.db ?? openDatabase();
+    const db = options.db ?? openExistingDatabase();
     const ownsDb = options.db === undefined;
     try {
-        // The schema is normally created during `akm index`; ensure it exists so
-        // `akm history` works on a freshly-initialised stash that has never been
-        // indexed (and just returns an empty list rather than an error).
-        ensureUsageEventsSchema(db);
         const conditions = [];
         const params = [];
         if (normalizedRef !== undefined) {

package/dist/commands/info.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { getAssetTypes } from "../core/asset-spec";
 import { loadConfig } from "../core/config";
 import { getDbPath } from "../core/paths";
-import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openDatabase } from "../indexer/db";
+import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openExistingDatabase } from "../indexer/db";
 import { getEffectiveSemanticStatus, readSemanticStatus } from "../indexer/semantic-status";
 import { pkgVersion } from "../version";
 /**
@@ -74,7 +74,7 @@ function readIndexStats(dbPath) {
     }
     let db;
     try {
-        db = openDatabase(resolvedPath);
+        db = openExistingDatabase(resolvedPath);
         const entryCount = getEntryCount(db);
         const lastBuiltAt = getMeta(db, "builtAt") ?? null;
         const vecAvailable = isVecAvailable(db);

package/dist/commands/installed-stashes.js

@@ -12,8 +12,9 @@ import { NotFoundError, UsageError } from "../core/errors";
 import { akmIndex } from "../indexer/indexer";
 import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
 import { parseRegistryRef } from "../registry/resolve";
+import { parseGitRepoUrl, syncMirroredRepo } from "../sources/providers/git";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
-import { ensureWebsiteMirror } from "../sources/providers/website";
+import { ensureWebsiteMirror } from "../sources/website-ingest";
 import { listWikis, resolveWikisRoot } from "../wiki/wiki";
 import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
@@ -173,6 +174,49 @@ export async function akmUpdate(input) {
         const stashes = config.sources ?? config.stashes ?? [];
         const isUrl = target.startsWith("http://") || target.startsWith("https://");
         const resolvedPath = !isUrl ? path.resolve(target) : undefined;
+        const gitMatch = stashes.find((s) => {
+            if (s.type !== "git")
+                return false;
+            if (isUrl && s.url === target)
+                return true;
+            if (resolvedPath && s.path && path.resolve(s.path) === resolvedPath)
+                return true;
+            if (s.name === target)
+                return true;
+            if (s.url) {
+                try {
+                    const repo = parseGitRepoUrl(s.url);
+                    if (repo.canonicalUrl === target)
+                        return true;
+                }
+                catch {
+                    // Ignore malformed config here; later provider sync will surface it.
+                }
+            }
+            return false;
+        });
+        if (gitMatch) {
+            await syncMirroredRepo(gitMatch, { force: true, writable: gitMatch.writable === true });
+            const index = await akmIndex({ stashDir, full: true });
+            const updatedConfig = loadConfig();
+            return {
+                schemaVersion: 1,
+                stashDir,
+                target,
+                all,
+                processed: [],
+                config: {
+                    sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+                    installedKitCount: updatedConfig.installed?.length ?? 0,
+                },
+                index: {
+                    mode: index.mode,
+                    totalEntries: index.totalEntries,
+                    directoriesScanned: index.directoriesScanned,
+                    directoriesSkipped: index.directoriesSkipped,
+                },
+            };
+        }
         const websiteMatch = stashes.find((s) => {
             if (s.type !== "website")
                 return false;

package/dist/commands/search.js

@@ -11,7 +11,7 @@
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { closeDatabase, openDatabase } from "../indexer/db";
+import { closeDatabase, openExistingDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
 // Eagerly import source providers to trigger self-registration before the
@@ -169,7 +169,7 @@ function logSearchEvent(query, response, existingDb) {
         metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
     });
     try {
-        const db = existingDb ?? openDatabase();
+        const db = existingDb ?? openExistingDatabase();
         try {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
             for (const { entryId, ref } of resolved) {

package/dist/commands/show.js

@@ -26,10 +26,9 @@ import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
-import { closeDatabase, findEntryIdByRef, openDatabase } from "../indexer/db";
+import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
 import { lookup } from "../indexer/indexer";
-import { loadStashFile } from "../indexer/metadata";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
 import { insertUsageEvent } from "../indexer/usage-events";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve";
@@ -203,7 +202,7 @@ function logShowEvent(ref, existingDb) {
     const parsed = parseAssetRef(ref);
     appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
     try {
-        const db = existingDb ?? openDatabase();
+        const db = existingDb ?? openExistingDatabase();
         try {
             insertUsageEvent(db, {
                 event_type: "show",
@@ -369,33 +368,19 @@ function buildBriefResponse(full, assetPath) {
  *
  * Strips content/template/prompt and returns only metadata fields:
  * type, name, path, description, tags, parameters, action.
- * Enriches description and tags from frontmatter or .stash.json when available.
+ * Enriches description and tags from rendered content when available.
  *
  * The resulting JSON should be under 200 tokens.
  */
 function buildSummaryResponse(full, assetPath) {
     let description = full.description;
-    let tags = full.tags;
+    const tags = full.tags;
     if (assetPath) {
         const textContent = full.content ?? full.template ?? full.prompt;
         if (textContent && !description) {
             const parsed = parseFrontmatter(textContent);
             description = toStringOrUndefined(parsed.data.description);
         }
-        const dir = path.dirname(assetPath);
-        const stashFile = loadStashFile(dir);
-        if (stashFile) {
-            const fileName = path.basename(assetPath);
-            const entry = stashFile.entries.find((e) => e.filename === fileName);
-            if (entry) {
-                if (!description && entry.description) {
-                    description = entry.description;
-                }
-                if (!tags && entry.tags) {
-                    tags = entry.tags;
-                }
-            }
-        }
     }
     const summary = {
         type: full.type,

package/dist/commands/source-add.js

@@ -9,7 +9,7 @@ import { upsertLockEntry } from "../integrations/lockfile";
 import { parseRegistryRef } from "../registry/resolve";
 import { detectStashRoot } from "../sources/providers/provider-utils";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
-import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../sources/providers/website";
+import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../sources/website-ingest";
 import { ensureWikiNameAvailable, validateWikiName } from "../wiki/wiki";
 import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);

package/dist/core/common.js

@@ -146,19 +146,34 @@ function normalizeFsPathForComparison(value) {
  * Fetch with an AbortController timeout.
  * Defaults to 30 seconds if no timeout is specified.
  */
-export async function fetchWithTimeout(url, opts, timeoutMs = 30_000) {
+export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const abortExternal = () => controller.abort(signal?.reason);
+    if (signal) {
+        if (signal.aborted) {
+            clearTimeout(timer);
+            controller.abort(signal.reason);
+        }
+        else {
+            signal.addEventListener("abort", abortExternal, { once: true });
+        }
+    }
     try {
         return await fetch(url, { ...opts, signal: controller.signal });
     }
     catch (err) {
         if (err instanceof DOMException && err.name === "AbortError") {
+            if (signal?.aborted) {
+                throw new Error(`Request aborted: ${url}`);
+            }
             throw new Error(`Request timed out after ${timeoutMs}ms: ${url}`);
         }
         throw err;
     }
     finally {
+        if (signal)
+            signal.removeEventListener("abort", abortExternal);
         clearTimeout(timer);
     }
 }

package/dist/core/config.js

@@ -4,14 +4,14 @@ import path from "node:path";
 import { parseAgentConfig } from "../integrations/agent/config";
 import { filterNonEmptyStrings } from "./common";
 import { ConfigError } from "./errors";
-import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
+import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath, getCacheDir } from "./paths";
 import { warn } from "./warn";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     semanticSearchMode: "auto",
     registries: [
-        { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" },
-        { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh" },
+        { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "akm-registry" },
+        { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh", enabled: false },
     ],
     output: {
         format: "json",
@@ -108,9 +108,21 @@ export function saveConfig(config) {
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
+    backupExistingConfig(configPath);
     const sanitized = sanitizeConfigForWrite(config);
     writeConfigObject(configPath, sanitized);
 }
+function backupExistingConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return;
+    const backupDir = path.join(getCacheDir(), "config-backups");
+    fs.mkdirSync(backupDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
+    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
+    fs.copyFileSync(configPath, backupPath);
+    const latestPath = path.join(backupDir, "config.latest.json");
+    fs.copyFileSync(configPath, latestPath);
+}
 /**
  * Strip apiKey fields before writing config to disk.
  * API keys should be provided via environment variables
@@ -509,6 +521,9 @@ function parseLlmConfig(value) {
         if (Object.keys(features).length > 0)
             result.features = features;
     }
+    if (typeof obj.extraParams === "object" && obj.extraParams !== null && !Array.isArray(obj.extraParams)) {
+        result.extraParams = obj.extraParams;
+    }
     return result;
 }
 /**

package/dist/indexer/db-search.js

@@ -17,7 +17,7 @@ import { defaultRendererRegistry } from "../core/asset-registry";
 import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openExistingDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
 import { computeGraphBoost, loadGraphBoostContext } from "./graph-boost";
 import { generateMetadataFlat, isProposedQuality, loadStashFile, shouldIndexStashFile, } from "./metadata";
@@ -69,8 +69,7 @@ export async function searchLocal(input) {
     const dbPath = getDbPath();
     try {
         if (fs.existsSync(dbPath)) {
-            const embeddingDim = config.embedding?.dimension;
-            const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+            const db = openExistingDatabase(dbPath);
             try {
                 const entryCount = getEntryCount(db);
                 const storedStashDir = getMeta(db, "stashDir");
@@ -269,7 +268,10 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         // If the query IS the asset name (or very close), this is almost certainly
         // what the user wants. This is the single most important ranking signal.
         const nameLower = entry.name.toLowerCase();
-        const nameBase = nameLower.split("/").pop() ?? nameLower; // last segment for path-based names
+        const rawNameBase = nameLower.split("/").pop() ?? nameLower; // last segment for path-based names
+        const nameBase = entry.type === "memory" && rawNameBase.endsWith(".derived")
+            ? rawNameBase.slice(0, -".derived".length)
+            : rawNameBase;
         if (nameBase === queryLower || nameLower === queryLower) {
             // Exact match: massive boost
             boostSum += 2.0;
@@ -301,6 +303,18 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             knowledge: 0,
         };
         boostSum += TYPE_BOOST[entry.type] ?? 0;
+        // ── 2.5. Derived-vs-raw memory preference ──
+        // Raw memories are user notes and may be incomplete or unvetted. Compressed
+        // `.derived` memories are the higher-signal retrieval target, but the
+        // preference should stay modest so stronger relevance signals still dominate.
+        if (entry.type === "memory") {
+            if (entry.name.toLowerCase().endsWith(".derived")) {
+                boostSum += 0.18;
+            }
+            else {
+                boostSum -= 0.08;
+            }
+        }
         // ── 3. Tag exact match ──
         // Exact tag equality is a strong signal — the author explicitly tagged
         // this asset with the user's search term.
@@ -691,44 +705,20 @@ async function indexAssets(stashDir, type, sources) {
             dirGroups.set(ctx.parentDirAbs, [ctx.absPath]);
     }
     for (const [dirPath, files] of dirGroups) {
-        let stash = loadStashFile(dirPath);
-        if (stash) {
-            const coveredFiles = new Set(stash.entries.map((entry) => entry.filename).filter((entry) => !!entry));
-            const uncoveredFiles = files.filter((file) => !coveredFiles.has(path.basename(file)));
-            if (uncoveredFiles.length > 0) {
-                const generated = await generateMetadataFlat(stashDir, uncoveredFiles);
-                if (generated.entries.length > 0) {
-                    stash = { entries: [...stash.entries, ...generated.entries] };
-                }
-            }
-        }
-        else {
-            const generated = await generateMetadataFlat(stashDir, files);
-            if (generated.entries.length === 0)
-                continue;
-            stash = generated;
-        }
-        // Build a lookup for matching filename-less entries to actual files
-        const fileBasenameMap = new Map();
-        for (const file of files) {
-            const base = path.basename(file, path.extname(file));
-            if (!fileBasenameMap.has(base))
-                fileBasenameMap.set(base, file);
-        }
+        const generated = await generateMetadataFlat(stashDir, files);
+        const legacyOverrides = loadStashFile(dirPath, { requireFilename: true });
+        const mergedEntries = legacyOverrides
+            ? generated.entries.map((entry) => mergeLegacyEntry(entry, legacyOverrides.entries))
+            : generated.entries;
+        const stash = mergedEntries.length > 0 ? { entries: mergedEntries } : legacyOverrides;
+        if (!stash || stash.entries.length === 0)
+            continue;
         for (const entry of stash.entries) {
             if (filterType && entry.type !== filterType)
                 continue;
-            let entryPath;
-            if (entry.filename) {
-                entryPath = path.join(dirPath, entry.filename);
-            }
-            else {
-                // Try matching entry name to a file by basename
-                entryPath =
-                    fileBasenameMap.get(entry.name) ??
-                        fileBasenameMap.get(entry.name.split("/").pop() ?? "") ??
-                        (files[0] || dirPath);
-            }
+            if (!entry.filename)
+                continue;
+            const entryPath = path.join(dirPath, entry.filename);
             if (!shouldIndexStashFile(stashDir, entryPath))
                 continue;
             assets.push({ entry, path: entryPath });
@@ -736,6 +726,10 @@ async function indexAssets(stashDir, type, sources) {
     }
     return assets;
 }
+function mergeLegacyEntry(entry, legacyEntries) {
+    const legacy = legacyEntries.find((candidate) => candidate.filename === entry.filename);
+    return legacy ? { ...entry, ...legacy, filename: entry.filename } : entry;
+}
 async function indexWikiRootAssets(wikiRoot, wikiName, type) {
     if (type !== "any" && type !== "wiki")
         return [];