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

package/dist/indexer/passes/memory-inference.js

@@ -119,6 +119,26 @@ export async function runMemoryInferencePass(ctx) {
         // 2026-05-26).
         if (signal?.aborted)
             return { aborted: true };
+        // Pre-check (#588): when `<parent>.derived.md` is already on disk the
+        // inference is by definition complete — the parent only looks pending
+        // because `markParentProcessed` never ran (process killed between the
+        // child write and the mark) or the child was created externally (e.g.
+        // consolidation). Skip the LLM/cache call entirely and mark the parent
+        // so it never re-pends. Before this check, production measurements
+        // showed ~55% of the pass's LLM budget re-deriving such parents only to
+        // discover the existing child after the fact.
+        if (fs.existsSync(derivedChildPath(record))) {
+            markParentProcessed(record);
+            return {
+                skipped: false,
+                splitParent: false,
+                written: 0,
+                fromCache: false,
+                retryAttempts: 0,
+                childExists: true,
+                precheck: true,
+            };
+        }
         // Incremental cache: skip LLM call when body hash is unchanged and
         // --re-enrich was not requested. The cache ref is the absolute file path.
         const validate = (raw) => {
@@ -171,23 +191,30 @@ export async function runMemoryInferencePass(ctx) {
             return { skipped: false, splitParent: true, written: writeOutcome.written, fromCache, retryAttempts };
         }
         // LLM produced a valid derived draft but no file was written — either
-        // because `<parent>.derived.md` already exists on disk or
-        // `writeAssetToSource` threw. Categorise as `childExists` so the
-        // attempt is accounted for in health metrics rather than vanishing
-        // into the freshAttempts denominator.
+        // because `<parent>.derived.md` appeared on disk after the pre-check
+        // above (a rare mid-flight race) or `writeAssetToSource` threw.
+        // Categorise as `childExists` so the consumed attempt is accounted for
+        // in health metrics rather than vanishing into the freshAttempts
+        // denominator.
         //
-        // When the child already exists on disk the inference is, by definition,
-        // already complete — so mark the parent processed here too (#550).
-        // Without this, `isPendingMemory()` re-queues the same parent every run
-        // (the `written > 0` path was previously the only site that marks it),
-        // causing permanent re-queueing and wasted LLM calls. A genuine write
-        // *failure* (`writeAssetToSource` threw) must NOT mark the parent — it
-        // should be retried next run — so we key off the explicit `childExists`
-        // outcome rather than the conflated `written === 0`.
+        // When the child exists the inference is, by definition, complete — so
+        // mark the parent processed here too (#550), otherwise
+        // `isPendingMemory()` re-queues the same parent every run. A genuine
+        // write *failure* (`writeAssetToSource` threw) must NOT mark the parent
+        // — it should be retried next run — so we key off the explicit
+        // `childExists` outcome rather than the conflated `written === 0`.
         if (writeOutcome.childExists) {
             markParentProcessed(record);
         }
-        return { skipped: false, splitParent: false, written: 0, fromCache, retryAttempts, childExists: true };
+        return {
+            skipped: false,
+            splitParent: false,
+            written: 0,
+            fromCache,
+            retryAttempts,
+            childExists: true,
+            precheck: false,
+        };
     }, 
     // Default concurrency of 4 for cloud APIs. Set `llm.concurrency: 1`
     // in config.json for local model servers (LM Studio, Ollama).
@@ -224,11 +251,16 @@ export async function runMemoryInferencePass(ctx) {
             result.writtenFacts += res.written;
         }
         else if ("childExists" in res && res.childExists) {
-            // LLM call was consumed but the derived file already existed (or the
-            // write threw). Track separately so this category is observable in
-            // health output and stops bleeding into the freshAttempts denominator.
+            // Derived child already on disk. Track separately so this category is
+            // observable in health output and stops bleeding into the
+            // freshAttempts denominator. Pre-check skips (#588) are the routine
+            // self-healing path — no LLM attempt was consumed and the parent has
+            // been marked processed — so only the rare post-LLM case (mid-flight
+            // race or write failure) warrants a per-ref warning.
             result.skippedChildExists += 1;
-            warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+            if (!res.precheck) {
+                warn(`memory inference: derived child for ${pending[i]?.ref ?? "<unknown>"} already existed or write failed; counted as skippedChildExists`);
+            }
         }
         else {
             // The per-record state machine should cover every outcome. A hit here
@@ -324,6 +356,14 @@ function toMemoryName(memoriesDir, filePath) {
     // user has organised under memories/.
     return rel.replace(/\\/g, "/").replace(/\.md$/i, "");
 }
+/**
+ * Absolute path of the derived child for a parent memory. Single source of
+ * truth for the `<parent>.derived.md` naming convention — used both by the
+ * pre-LLM existence check (#588) and the write path.
+ */
+function derivedChildPath(parent) {
+    return path.join(parent.stashRoot, "memories", `${parent.name}.derived.md`);
+}
 async function writeDerivedMemory(parent, derived) {
     const writeTarget = {
         kind: "filesystem",
@@ -338,11 +378,10 @@ async function writeDerivedMemory(parent, derived) {
     };
     const childName = `${parent.name}.derived`;
     const childRefStr = `memory:${childName}`;
-    const childPath = path.join(parent.stashRoot, "memories", `${childName}.md`);
-    if (fs.existsSync(childPath)) {
-        // The derived child is already on disk — inference for this parent is
-        // complete. Report `childExists` so the caller marks the parent processed
-        // (#550) instead of re-queueing it forever.
+    if (fs.existsSync(derivedChildPath(parent))) {
+        // The derived child appeared on disk after the caller's pre-check (#588)
+        // — a rare mid-flight race. Report `childExists` so the caller marks the
+        // parent processed (#550) instead of re-queueing it forever.
         return { written: 0, childExists: true };
     }
     try {
@@ -386,10 +425,17 @@ function markParentProcessed(parent) {
         warn(`memory inference: failed to re-read parent ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
     const block = parseFrontmatterBlock(raw);
-    const body = block?.content ?? raw;
-    const next = assembleAsset(updatedFm, body);
+    if (!block) {
+        // Cannot safely rewrite malformed frontmatter — skip marking so the memory
+        // is retried on the next run once the frontmatter is repaired. Writing with
+        // `body = raw` would wrap the entire file (including the bad frontmatter)
+        // in a new block, producing a duplicate-frontmatter corruption.
+        warn(`memory inference: skipping markParentProcessed for ${parent.filePath} — could not parse frontmatter block`);
+        return;
+    }
+    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
+    const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
     }

package/dist/indexer/passes/staleness-detect.js

@@ -44,6 +44,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import stalenessDetectSystemPrompt from "../../assets/prompts/staleness-detect-system.md" with { type: "text" };
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
 import { concurrentMap } from "../../core/concurrent.js";
@@ -319,11 +320,7 @@ function pickSimilar(candidate, all) {
     return scored.slice(0, TOP_K_SIMILAR).map((s) => s.snap);
 }
 // ── LLM dispatch ────────────────────────────────────────────────────────────
-const SYSTEM_PROMPT = "You are a belief-state classifier for a memory store. Given a candidate memory and a list of more-recent similar memories from the same store, decide whether the candidate is still current or has been superseded.\n\n" +
-    "Respond on the first line with exactly YES or NO.\n" +
-    "If YES, the second line MUST be of the form `SUPERSEDED_BY: <ref>` where <ref> is the exact ref of the superseding memory from the list provided. Do NOT invent refs.\n" +
-    "If NO, do not include any additional lines.\n" +
-    "No prose, no preamble, no markdown.";
+const SYSTEM_PROMPT = stalenessDetectSystemPrompt;
 async function askValidator(connection, candidate, allMemories, signal, timeoutMs) {
     const similar = pickSimilar(candidate, allMemories);
     if (similar.length === 0) {

package/dist/indexer/search/db-search.js

@@ -65,6 +65,7 @@ export async function searchLocal(input) {
     const includeProposed = input.includeProposed === true;
     const beliefFilter = input.beliefFilter ?? "all";
     const restrictToSources = input.restrictToSources === true;
+    const includeExcludedTypes = input.includeExcludedTypes === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -114,7 +115,7 @@ export async function searchLocal(input) {
                 mode: "keyword",
             };
         }
-        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources);
+        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes);
         return {
             hits,
             tip: hits.length === 0
@@ -131,14 +132,19 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false) {
     const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
+    // #627 — resolve the default type-exclusion policy. It applies ONLY on the
+    // untyped ('any') path and only when the caller did not opt back in via
+    // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
+    // ['session'] is applied; an explicit empty list disables exclusion.
+    const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
     // returning an empty result set from FTS.
     if (!hasSearchableTokens) {
         const typeFilter = searchType === "any" ? undefined : searchType;
-        const allEntries = getAllEntries(db, typeFilter);
+        const allEntries = getAllEntries(db, typeFilter, defaultExcludes);
         // Deduplicate by file path — multiple entries can share the same file
         const seenFilePaths = new Set();
         const uniqueEntries = allEntries.filter((ie) => {
@@ -187,7 +193,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const typeFilter = searchType === "any" ? undefined : searchType;
     const tEmbed0 = Date.now();
     const embeddingPromise = tryVecScores(db, query, limit * 3, config);
-    const ftsResults = searchFts(db, query, limit * 3, typeFilter);
+    const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
     const embeddingScores = await embeddingPromise;
     const embedMs = Date.now() - tEmbed0;
     const tRank0 = Date.now();
@@ -208,6 +214,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         embedScoreMap,
         getEntryById: (id) => getEntryById(db, id) ?? undefined,
         typeFilter,
+        // #627 — also exclude default-hidden types from the vector-only branch so a
+        // session asset that is a top-k vector neighbor (but not an FTS match) does
+        // not leak into default ('any') results. defaultExcludes is already []
+        // unless this is the untyped path without includeExcludedTypes.
+        excludeTypes: defaultExcludes,
     });
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase

package/dist/indexer/search/ranking.js

@@ -20,6 +20,7 @@ export function normalizeFtsScores(results) {
 export function combineSearchScores(options) {
     const FTS_WEIGHT = 0.7;
     const VEC_WEIGHT = 0.3;
+    const excludeTypeSet = options.excludeTypes && options.excludeTypes.length > 0 ? new Set(options.excludeTypes) : null;
     const scored = [];
     const seenIds = new Set();
     for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
@@ -42,6 +43,9 @@ export function combineSearchScores(options) {
             continue;
         if (options.typeFilter && found.entry.type !== options.typeFilter)
             continue;
+        // #627 — drop vector-only neighbors whose type is excluded on the default path.
+        if (excludeTypeSet?.has(found.entry.type))
+            continue;
         scored.push({
             id,
             entry: found.entry,

package/dist/integrations/harnesses/claude/session-log.js

@@ -5,7 +5,19 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
-const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+/**
+ * Root directory holding Claude Code's per-project JSONL session logs.
+ *
+ * Resolved per call (not memoized at module load) so the `AKM_CLAUDE_PROJECTS_DIR`
+ * override can be set after import. The override exists so tests — and the
+ * isolated-storage sandbox — can point the scan at an empty fixture directory
+ * instead of the real `~/.claude/projects`, which on an actively-used machine
+ * holds many large session files and would make `akm health` (which scans it
+ * synchronously) slow and non-hermetic.
+ */
+function claudeProjectsDir() {
+    return process.env.AKM_CLAUDE_PROJECTS_DIR ?? path.join(os.homedir(), ".claude", "projects");
+}
 /**
  * Parse a single Claude Code JSONL event into a normalized {@link SessionEvent}.
  * Returns `undefined` for events that don't carry textual content (file
@@ -93,11 +105,21 @@ export class ClaudeCodeProvider {
     // HARNESS_BY_ID.get("claude").runtimeId.
     name = "claude-code";
     isAvailable() {
-        return fs.existsSync(CLAUDE_PROJECTS_DIR);
+        return fs.existsSync(claudeProjectsDir());
+    }
+    /**
+     * Directory holding Claude Code's per-project session JSONL files
+     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
+     * when the directory does not exist on this machine. See {@link
+     * SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const dir = claudeProjectsDir();
+        return fs.existsSync(dir) ? [dir] : [];
     }
     *readEvents(input) {
         try {
-            for (const jsonlPath of this.#walkJsonl(CLAUDE_PROJECTS_DIR)) {
+            for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {
                 const stat = fs.statSync(jsonlPath);
                 if (stat.mtimeMs < input.sinceMs)
                     continue;
@@ -128,7 +150,7 @@ export class ClaudeCodeProvider {
         }
     }
     listSessions(input = {}) {
-        const root = input.location ?? CLAUDE_PROJECTS_DIR;
+        const root = input.location ?? claudeProjectsDir();
         const sinceMs = input.sinceMs ?? 0;
         const summaries = [];
         try {
@@ -286,7 +308,7 @@ export class ClaudeCodeProvider {
                 const full = path.join(dir, entry.name);
                 if (entry.isDirectory())
                     yield* this.#walkJsonl(full);
-                else if (entry.name.endsWith(".jsonl"))
+                else if (entry.name.endsWith(".jsonl") && entry.name !== "journal.jsonl")
                     yield full;
             }
         }

package/dist/integrations/harnesses/opencode/session-log.js

@@ -26,6 +26,15 @@ export class OpenCodeProvider {
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /**
+     * Directory holding opencode's per-project session metadata files
+     * (`<base>/storage/session`). Returns `[]` when it does not exist on this
+     * machine. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        return fs.existsSync(sessionRoot) ? [sessionRoot] : [];
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without

package/dist/integrations/session-logs/index.js

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)

package/dist/llm/client.js

@@ -14,6 +14,7 @@ import { fetchWithTimeout } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
 import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse.js";
 import { warnVerbose } from "../core/warn.js";
+import { emitLlmUsage, extractUsageTokens } from "./usage-telemetry.js";
 // Re-export shared parse utilities so existing importers of `client.ts` continue
 // to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
 export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse.js";
@@ -118,9 +119,23 @@ function looksLikeContextOverflow(message) {
 /**
  * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
  * retry. Retryable: HTTP 5xx (`provider_error` with statusCode >= 500) and
- * `network_error` whose message looks like a transient connection reset
- * (ECONNRESET / EPIPE / "fetch failed"). NOT retryable: 4xx, `rate_limited`
- * (429), `timeout`, `parse_error`, and context-overflow-classified errors.
+ * `network_error` whose message looks like a transient connection drop.
+ * NOT retryable: 4xx, `rate_limited` (429), `timeout`, `parse_error`, and
+ * context-overflow-classified errors.
+ *
+ * The connection-drop heuristic covers the substrings emitted across runtimes
+ * for a mid-flight socket close:
+ *  - `ECONNRESET` / `EPIPE` — Node/libuv socket reset codes
+ *  - `fetch failed` — undici's generic wrapper message
+ *  - `socket connection was closed` — Bun's message for a dropped connection
+ *    (e.g. "The socket connection was closed unexpectedly.")
+ *  - `terminated` / `other side closed` — undici's phrasings for the same
+ *
+ * These all describe a transient transport failure where a second attempt can
+ * legitimately succeed, which is exactly the case a single bounded retry is
+ * meant to absorb. Before this list was widened, Bun's "socket connection was
+ * closed unexpectedly" fell through unretried and surfaced as a recurring
+ * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
     if (looksLikeContextOverflow(err.message))
@@ -130,7 +145,12 @@ function isRetryable(err) {
     }
     if (err.code === "network_error") {
         const lower = err.message.toLowerCase();
-        return lower.includes("econnreset") || lower.includes("epipe") || lower.includes("fetch failed");
+        return (lower.includes("econnreset") ||
+            lower.includes("epipe") ||
+            lower.includes("fetch failed") ||
+            lower.includes("socket connection was closed") ||
+            lower.includes("terminated") ||
+            lower.includes("other side closed"));
     }
     return false;
 }
@@ -179,6 +199,10 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     const responseFormat = options?.responseSchema && config.supportsJsonSchema
         ? { response_format: { type: "json_schema", json_schema: { schema: options.responseSchema, strict: true } } }
         : {};
+    // Wall-clock start for per-call usage telemetry (#576). Captured here so the
+    // emitted duration covers the full request/response/parse cycle of a single
+    // attempt, not the retry-wrapping `chatCompletion`.
+    const requestStartedAt = Date.now();
     let response;
     try {
         response = await fetchWithTimeout(config.endpoint, {
@@ -241,6 +265,16 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     catch {
         throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactErrorBody(rawOkBody)}`, "parse_error", response.status);
     }
+    // Per-call usage telemetry (#576). Best-effort and fully isolated: a missing
+    // or garbled usage block still records duration + model, and a throwing sink
+    // can never fail the call (emitLlmUsage swallows its own errors). The stage
+    // is supplied ambiently by emitLlmUsage; no `stage` param is threaded here.
+    emitLlmUsage({
+        model: typeof json.model === "string" && json.model ? json.model : config.model,
+        durationMs: Date.now() - requestStartedAt,
+        finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
+        ...extractUsageTokens(json.usage),
+    });
     const content = (json.choices?.[0]?.message?.content ?? "").trim();
     const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
     return content || reasoning;

package/dist/llm/embedder.js

@@ -2,7 +2,7 @@
 // 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 { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
-import { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
@@ -52,7 +52,8 @@ export async function embed(text, embeddingConfig, signal) {
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for the local transformer pipeline.
+ * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
+ * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
@@ -60,8 +61,13 @@ export async function embedBatch(texts, embeddingConfig, signal) {
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
-    // Local transformer: process sequentially (pipeline handles one at a time)
+    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // When a localModel override is set we cannot share the singleton (which uses
+    // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
+    if (!localModel) {
+        return getLocalEmbedder().embedBatch(texts, signal);
+    }
     const results = [];
     for (const text of texts) {
         if (signal?.aborted) {
@@ -77,6 +83,24 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
 export { cosineSimilarity } from "./embedders/types.js";
+// ── Model ID resolution ─────────────────────────────────────────────────────
+/**
+ * Derive a stable string identifier for the embedding model in use.
+ * This is the `model_id` stored in `body_embeddings` (and used for the
+ * drop-all-on-mismatch purge when the model changes).
+ *
+ * Rules:
+ *   - Remote endpoint: use `config.model` (the API-level model name).
+ *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
+ */
+export function resolveEmbeddingModelId(embeddingConfig) {
+    if (!embeddingConfig)
+        return DEFAULT_LOCAL_MODEL;
+    if (hasRemoteEndpoint(embeddingConfig))
+        return embeddingConfig.model ?? "remote";
+    return embeddingConfig.localModel ?? DEFAULT_LOCAL_MODEL;
+}
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.

package/dist/llm/embedders/local.js

@@ -19,8 +19,24 @@ import { getDirname, resolveModule } from "../../runtime.js";
  * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
  */
 export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+/** Type-guard: true when the value looks like a batch Tensor (has .dims). */
+function isBatchTensor(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        "data" in v &&
+        "dims" in v &&
+        Array.isArray(v.dims) &&
+        v.dims.length >= 2);
+}
 const LOCAL_EMBEDDER_DTYPE = "fp32";
 const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
+/**
+ * Maximum texts per batch for the local transformers pipeline. The pipeline
+ * can run genuine batched inference over a string array; 32 is a safe default
+ * that fits well inside most model context budgets while providing 10–50×
+ * throughput improvement over one-at-a-time calls on the cold minority.
+ */
+const LOCAL_BATCH_SIZE = 32;
 /**
  * Return the local model name that will be used for embedding.
  * When `overrideModel` is provided it takes precedence; otherwise
@@ -77,15 +93,63 @@ export class LocalEmbedder {
         }
         return this.embedWithModel(text, this.defaultModel);
     }
+    /**
+     * Embed a batch of texts. Processes in chunks of `LOCAL_BATCH_SIZE` (32) so
+     * the transformers pipeline can run genuine batched inference rather than one
+     * call per text. Falls back to one-at-a-time if the pipeline does not support
+     * array input (older versions of @huggingface/transformers). Each chunk is
+     * checked against the AbortSignal between calls.
+     */
     async embedBatch(texts, signal) {
         if (texts.length === 0)
             return [];
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+        }
+        const pipeline = await this.getPipeline(this.defaultModel);
         const results = [];
-        for (const text of texts) {
+        for (let i = 0; i < texts.length; i += LOCAL_BATCH_SIZE) {
             if (signal?.aborted) {
                 throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
             }
-            results.push(await this.embedWithModel(text, this.defaultModel));
+            const chunk = texts.slice(i, i + LOCAL_BATCH_SIZE);
+            try {
+                // @huggingface/transformers feature-extraction pipeline accepts a
+                // string[] and returns a batch Tensor (NOT an Array<{data}>).
+                // The Tensor has .data (flat Float32Array, length = batch * dim) and
+                // .dims = [batch, dim]. Slice .data into per-row vectors using .dims.
+                const batchResult = await pipeline(chunk, {
+                    pooling: "mean",
+                    normalize: true,
+                });
+                if (isBatchTensor(batchResult)) {
+                    const dim = batchResult.dims[1];
+                    for (let row = 0; row < chunk.length; row++) {
+                        results.push(Array.from(batchResult.data.subarray(row * dim, (row + 1) * dim)));
+                    }
+                }
+                else if (Array.isArray(batchResult)) {
+                    // Older versions of @huggingface/transformers returned Array<{data}>.
+                    for (const r of batchResult) {
+                        results.push(Array.from(r.data));
+                    }
+                }
+                else {
+                    // Single-text result returned for a chunk — should not happen for
+                    // string[] input, but handle defensively.
+                    throw new Error("unexpected pipeline return shape for batch input");
+                }
+            }
+            catch {
+                // Fallback: process one-at-a-time (older pipeline versions or mismatched
+                // return type). Fail-open per text: a single failure aborts the chunk.
+                for (const text of chunk) {
+                    if (signal?.aborted) {
+                        throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+                    }
+                    results.push(await this.embedWithModel(text, this.defaultModel));
+                }
+            }
         }
         return results;
     }

package/dist/llm/graph-extract.js

@@ -20,6 +20,7 @@
  * the connection via `resolveIndexPassLLM("graph", config)` and pass it
  * straight through.
  */
+import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn, warnVerbose } from "../core/warn.js";
@@ -41,7 +42,7 @@ const NON_ARRAY_BATCH_DISABLE_THRESHOLD = 2;
 const MAX_ENTITIES_PER_ASSET = 32;
 /** Hard cap on relations returned per asset. */
 const MAX_RELATIONS_PER_ASSET = 32;
-const SYSTEM_PROMPT = "You extract a knowledge graph from developer notes. Return ONLY valid JSON — no prose, no markdown fences, no preamble.";
+const SYSTEM_PROMPT = systemPromptTemplate;
 const USER_PROMPT_PREFIX = userPromptTemplate
     .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
     .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));

package/dist/llm/memory-infer.js

@@ -18,20 +18,16 @@
  * the connection via `resolveIndexPassLLM("memory", config)` and pass it
  * straight through.
  */
+import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
+import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn } from "../core/warn.js";
 import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 /** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
 const MAX_BODY_CHARS = 4000;
-const SYSTEM_PROMPT = "You compress a developer memory into one high-signal derived memory for later retrieval. " +
-    "Return only valid JSON. No prose outside the JSON object. No markdown fences.";
-const USER_PROMPT_PREFIX = `Compress the memory below into one derived memory. Output ONLY JSON:
-{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
-Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
-
-Memory:
-`;
+const SYSTEM_PROMPT = memoryInferSystemPrompt;
+const USER_PROMPT_PREFIX = memoryInferUserPrompt;
 /**
  * Strict JSON Schema for the derived-memory payload. Sent to providers that
  * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client

package/dist/llm/metadata-enhance.js

@@ -1,9 +1,17 @@
 // 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/.
+/**
+ * LLM-driven metadata enhancement for stash entries.
+ *
+ * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
+ * improve descriptions/tags/searchHints) lives separately from the low-level
+ * transport client in `client.ts`.
+ */
+import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
 import { chatCompletion, parseJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
-const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
+const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.