myagentmemory 0.4.17 → 0.5.2

package/dist/completions.js

@@ -5,6 +5,12 @@ import { COMMAND_DESCRIPTIONS, COMMAND_OPTIONS, COMMANDS, GLOBAL_OPTIONS, OPTION
 function words(values) {
     return values.join(" ");
 }
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function powerShellSingleQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
 function zshOptionValue(command, option) {
     if (option === "--target") {
         return command === "read"
@@ -30,7 +36,7 @@ function zshOptionValue(command, option) {
 }
 function zshOptionSpecs(command, options = COMMAND_OPTIONS[command] ?? []) {
     return options
-        .map((option) => `'${option}[${optionDescription(option)}]${zshOptionValue(command, option)}'`)
+        .map((option) => shellSingleQuote(`${option}[${optionDescription(option)}]${zshOptionValue(command, option)}`))
         .join(" ");
 }
 function fishOption(command, condition, option) {
@@ -52,7 +58,7 @@ function fishOption(command, condition, option) {
         suggestions = " -a '(__fish_complete_directories)'";
     else if (spec?.value?.kind === "file")
         suggestions = " -F";
-    return `complete -c agent-memory -n '${condition}' -l ${option.slice(2)}${value}${suggestions} -d '${optionDescription(option)}'`;
+    return `complete -c agent-memory -n ${shellSingleQuote(condition)} -l ${option.slice(2)}${value}${suggestions} -d ${shellSingleQuote(optionDescription(option))}`;
 }
 function bashCompletion() {
     return `# agent-memory completion for Bash
@@ -141,12 +147,12 @@ _agent-memory() {
   local subcommand="$words[3]"
 	local action="$words[4]"
   local command_position=$CURRENT
-  commands=(${COMMANDS.map((command) => `'${command}:${COMMAND_DESCRIPTIONS[command] ?? command}'`).join(" ")})
-  plugin_commands=(${PLUGIN_COMMANDS.map((command) => `'${command}:${PLUGIN_COMMAND_DESCRIPTIONS[command]}'`).join(" ")})
-  worker_actions=(${WORKER_ACTIONS.map((action) => `'${action}:${WORKER_ACTION_DESCRIPTIONS[action]}'`).join(" ")})
-  scratchpad_actions=(${SCRATCHPAD_ACTIONS.map((action) => `'${action}:${SCRATCHPAD_ACTION_DESCRIPTIONS[action]}'`).join(" ")})
+  commands=(${COMMANDS.map((command) => shellSingleQuote(`${command}:${COMMAND_DESCRIPTIONS[command] ?? command}`)).join(" ")})
+  plugin_commands=(${PLUGIN_COMMANDS.map((command) => shellSingleQuote(`${command}:${PLUGIN_COMMAND_DESCRIPTIONS[command]}`)).join(" ")})
+  worker_actions=(${WORKER_ACTIONS.map((action) => shellSingleQuote(`${action}:${WORKER_ACTION_DESCRIPTIONS[action]}`)).join(" ")})
+  scratchpad_actions=(${SCRATCHPAD_ACTIONS.map((action) => shellSingleQuote(`${action}:${SCRATCHPAD_ACTION_DESCRIPTIONS[action]}`)).join(" ")})
   shells=(${Object.entries(SHELL_DESCRIPTIONS)
-        .map(([shell, description]) => `'${shell}:${description}'`)
+        .map(([shell, description]) => shellSingleQuote(`${shell}:${description}`))
         .join(" ")})
 
   _arguments -C \\
@@ -208,11 +214,11 @@ function fishCompletion() {
         "# Installed automatically by: agent-memory completion fish",
         "# Print this script instead with: agent-memory completion fish --stdout",
         "complete -c agent-memory -f",
-        ...COMMANDS.map((command) => `complete -c agent-memory -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command] ?? command}'`),
-        ...PLUGIN_COMMANDS.map((command) => `complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and not __fish_seen_subcommand_from ${words(PLUGIN_COMMANDS)}' -a '${command}' -d '${PLUGIN_COMMAND_DESCRIPTIONS[command]}'`),
-        ...WORKER_ACTIONS.map((action) => `complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and __fish_seen_subcommand_from worker; and not __fish_seen_subcommand_from ${words(WORKER_ACTIONS)}' -a '${action}' -d '${WORKER_ACTION_DESCRIPTIONS[action]}'`),
-        ...SCRATCHPAD_ACTIONS.map((action) => `complete -c agent-memory -n '__fish_seen_subcommand_from scratchpad; and not __fish_seen_subcommand_from ${words(SCRATCHPAD_ACTIONS)}' -a '${action}' -d '${SCRATCHPAD_ACTION_DESCRIPTIONS[action]}'`),
-        ...Object.entries(SHELL_DESCRIPTIONS).map(([shell, description]) => `complete -c agent-memory -n '__fish_seen_subcommand_from completion' -a '${shell}' -d '${description}'`),
+        ...COMMANDS.map((command) => `complete -c agent-memory -n '__fish_use_subcommand' -a '${command}' -d ${shellSingleQuote(COMMAND_DESCRIPTIONS[command] ?? command)}`),
+        ...PLUGIN_COMMANDS.map((command) => `complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and not __fish_seen_subcommand_from ${words(PLUGIN_COMMANDS)}' -a '${command}' -d ${shellSingleQuote(PLUGIN_COMMAND_DESCRIPTIONS[command])}`),
+        ...WORKER_ACTIONS.map((action) => `complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and __fish_seen_subcommand_from worker; and not __fish_seen_subcommand_from ${words(WORKER_ACTIONS)}' -a '${action}' -d ${shellSingleQuote(WORKER_ACTION_DESCRIPTIONS[action])}`),
+        ...SCRATCHPAD_ACTIONS.map((action) => `complete -c agent-memory -n '__fish_seen_subcommand_from scratchpad; and not __fish_seen_subcommand_from ${words(SCRATCHPAD_ACTIONS)}' -a '${action}' -d ${shellSingleQuote(SCRATCHPAD_ACTION_DESCRIPTIONS[action])}`),
+        ...Object.entries(SHELL_DESCRIPTIONS).map(([shell, description]) => `complete -c agent-memory -n '__fish_seen_subcommand_from completion' -a '${shell}' -d ${shellSingleQuote(description)}`),
         "complete -c agent-memory -l dir -r -a '(__fish_complete_directories)' -d 'override the active memory directory'",
         "complete -c agent-memory -l json -d 'emit command-specific structured JSON'",
         "complete -c agent-memory -s h -l help -d 'show help for the selected command'",
@@ -271,32 +277,32 @@ Register-ArgumentCompleter -Native -CommandName agent-memory -ScriptBlock {
   $shells = @('bash','zsh','fish','powershell')
   $commandDescriptions = @{
 ${Object.entries(COMMAND_DESCRIPTIONS)
-        .map(([command, description]) => `    '${command}' = '${description}'`)
+        .map(([command, description]) => `    '${command}' = ${powerShellSingleQuote(description)}`)
         .join("\n")}
   }
   $pluginCommandDescriptions = @{
 ${Object.entries(PLUGIN_COMMAND_DESCRIPTIONS)
-        .map(([command, description]) => `    '${command}' = '${description}'`)
+        .map(([command, description]) => `    '${command}' = ${powerShellSingleQuote(description)}`)
         .join("\n")}
   }
   $workerActionDescriptions = @{
 ${Object.entries(WORKER_ACTION_DESCRIPTIONS)
-        .map(([action, description]) => `    '${action}' = '${description}'`)
+        .map(([action, description]) => `    '${action}' = ${powerShellSingleQuote(String(description))}`)
         .join("\n")}
   }
   $scratchpadActionDescriptions = @{
 ${Object.entries(SCRATCHPAD_ACTION_DESCRIPTIONS)
-        .map(([action, description]) => `    '${action}' = '${description}'`)
+        .map(([action, description]) => `    '${action}' = ${powerShellSingleQuote(description)}`)
         .join("\n")}
   }
   $shellDescriptions = @{
 ${Object.entries(SHELL_DESCRIPTIONS)
-        .map(([shell, description]) => `    '${shell}' = '${description}'`)
+        .map(([shell, description]) => `    '${shell}' = ${powerShellSingleQuote(description)}`)
         .join("\n")}
   }
   $optionDescriptions = @{
 ${Object.keys(OPTION_SPECS)
-        .map((option) => `    '${option}' = '${optionDescription(option)}'`)
+        .map((option) => `    '${option}' = ${powerShellSingleQuote(optionDescription(option))}`)
         .join("\n")}
   }
   $globalOptions = @('${GLOBAL_OPTIONS.join("','")}')

package/dist/core.d.ts

@@ -20,6 +20,18 @@ export declare function getScratchpadFile(): string;
 export declare function getDailyDir(): string;
 /** Get the current topics directory path. */
 export declare function getTopicsDir(): string;
+export type HookMode = "stable" | "per-turn";
+/**
+ * Resolve the active hook mode.
+ * Precedence: `AGENT_MEMORY_HOOK_MODE` env var → `<memoryDir>/hook-config.json`
+ * → default `per-turn`. Invalid values fall through to the next source.
+ */
+export declare function readHookMode(): HookMode;
+/**
+ * Atomically persist the chosen hook mode. Called by `install-hooks` after a
+ * successful install pass so `doctor` and later invocations can report it.
+ */
+export declare function writeHookMode(mode: HookMode): void;
 export declare function ensureDirs(): void;
 export declare function todayStr(): string;
 export declare function yesterdayStr(): string;
@@ -69,7 +81,23 @@ export interface ScratchpadItem {
 }
 export declare function parseScratchpad(content: string): ScratchpadItem[];
 export declare function serializeScratchpad(items: ScratchpadItem[]): string;
+/**
+ * Full context: scratchpad + topics + today + search + MEMORY.md + yesterday.
+ * Used by `agent-memory context` and by SessionStart in stable mode.
+ */
 export declare function buildMemoryContext(searchResults?: string): string;
+/**
+ * Stable subset: scratchpad + topics + MEMORY.md. No daily logs, no search.
+ * Emitted at SessionStart in per-turn mode — the durable facts that survive
+ * across sessions and are unlikely to be affected by the current prompt.
+ */
+export declare function buildStableContext(): string;
+/**
+ * Dynamic subset: today's daily log + qmd search hits + yesterday's daily log.
+ * Emitted at UserPromptSubmit — turn-scoped context that can be scoped by the
+ * current query. Excludes MEMORY.md and scratchpad (already sent at SessionStart).
+ */
+export declare function buildDynamicContext(searchResults?: string, _query?: string): string;
 type ExecFileFn = typeof execFile;
 type SpawnFn = typeof spawn;
 /** Override execFile implementation (for testing). */
@@ -104,8 +132,12 @@ export declare function qmdInstallInstructions(): string;
 export declare function qmdCollectionInstructions(): string;
 /** Auto-create the qmd collection and path contexts. */
 export declare function setupQmdCollection(): Promise<boolean>;
-export declare function detectQmd(): Promise<boolean>;
-export declare function checkCollection(name?: string): Promise<boolean>;
+export declare function detectQmd(options?: {
+    signal?: AbortSignal;
+}): Promise<boolean>;
+export declare function checkCollection(name?: string, options?: {
+    signal?: AbortSignal;
+}): Promise<boolean>;
 export declare function getQmdUpdateMode(): "background" | "manual" | "off";
 export declare function ensureQmdAvailableForUpdate(): Promise<boolean>;
 export declare function getQmdEmbedMode(): "background" | "manual" | "off";
@@ -114,7 +146,9 @@ export declare function scheduleQmdEmbed(): void;
 export declare function scheduleQmdUpdate(): void;
 export declare function runQmdUpdateNow(): Promise<void>;
 export declare function runQmdEmbedNow(): Promise<boolean>;
-export declare function ensureQmdAvailableForSync(): Promise<boolean>;
+export declare function ensureQmdAvailableForSync(options?: {
+    signal?: AbortSignal;
+}): Promise<boolean>;
 export declare function runQmdSync(): Promise<{
     updateOk: boolean;
     embedOk: boolean;
@@ -169,7 +203,9 @@ export interface QmdHealthInfo {
 export declare function parseQmdStatus(stdout: string, collectionName: string): QmdHealthInfo;
 export declare function getQmdHealth(): Promise<QmdHealthInfo | null>;
 /** Search for memories relevant to the user's prompt. Returns formatted markdown or empty string on error. */
-export declare function searchRelevantMemories(prompt: string): Promise<string>;
+export declare function searchRelevantMemories(prompt: string, options?: {
+    signal?: AbortSignal;
+}): Promise<string>;
 export interface QmdSearchResult {
     path?: string;
     file?: string;
@@ -185,6 +221,8 @@ export declare function getQmdResultPath(r: QmdSearchResult): string | undefined
 export declare function getQmdResultText(r: QmdSearchResult): string;
 export declare function runQmdSearch(mode: "keyword" | "semantic" | "deep", query: string, limit: number, options?: {
     signal?: AbortSignal;
+    collection?: string;
+    index?: string;
 }): Promise<{
     results: QmdSearchResult[];
     stderr: string;

package/dist/core.js

@@ -48,6 +48,40 @@ export function getDailyDir() {
 export function getTopicsDir() {
     return TOPICS_DIR;
 }
+const HOOK_CONFIG_FILENAME = "hook-config.json";
+const HOOK_MODE_DEFAULT = "per-turn";
+function hookConfigPath() {
+    return path.join(MEMORY_DIR, HOOK_CONFIG_FILENAME);
+}
+/**
+ * Resolve the active hook mode.
+ * Precedence: `AGENT_MEMORY_HOOK_MODE` env var → `<memoryDir>/hook-config.json`
+ * → default `per-turn`. Invalid values fall through to the next source.
+ */
+export function readHookMode() {
+    const env = process.env.AGENT_MEMORY_HOOK_MODE;
+    if (env === "stable" || env === "per-turn")
+        return env;
+    try {
+        const raw = fs.readFileSync(hookConfigPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.mode === "stable" || parsed.mode === "per-turn")
+            return parsed.mode;
+    }
+    catch { }
+    return HOOK_MODE_DEFAULT;
+}
+/**
+ * Atomically persist the chosen hook mode. Called by `install-hooks` after a
+ * successful install pass so `doctor` and later invocations can report it.
+ */
+export function writeHookMode(mode) {
+    fs.mkdirSync(MEMORY_DIR, { recursive: true });
+    const target = hookConfigPath();
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify({ mode }, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, target);
+}
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
@@ -337,62 +371,89 @@ export function serializeScratchpad(items) {
 // ---------------------------------------------------------------------------
 // Context builder
 // ---------------------------------------------------------------------------
-export function buildMemoryContext(searchResults) {
-    ensureDirs();
-    // Priority order: scratchpad > topics > today's daily > search results > MEMORY.md > yesterday's daily
-    const sections = [];
+function scratchpadContextSection() {
     const scratchpad = readFileSafe(SCRATCHPAD_FILE);
-    if (scratchpad?.trim()) {
-        const openItems = parseScratchpad(scratchpad).filter((i) => !i.done);
-        if (openItems.length > 0) {
-            const serialized = filterMemoryForContext(serializeScratchpad(openItems));
-            const section = formatContextSection("## SCRATCHPAD.md (working context)", serialized, "start", CONTEXT_SCRATCHPAD_MAX_LINES, CONTEXT_SCRATCHPAD_MAX_CHARS);
-            if (section)
-                sections.push(section);
-        }
-    }
-    const topicsSection = buildTopicsContextSection();
-    if (topicsSection)
-        sections.push(topicsSection);
+    if (!scratchpad?.trim())
+        return null;
+    const openItems = parseScratchpad(scratchpad).filter((i) => !i.done);
+    if (openItems.length === 0)
+        return null;
+    const serialized = filterMemoryForContext(serializeScratchpad(openItems));
+    return formatContextSection("## SCRATCHPAD.md (working context)", serialized, "start", CONTEXT_SCRATCHPAD_MAX_LINES, CONTEXT_SCRATCHPAD_MAX_CHARS);
+}
+function todayContextSection() {
     const today = todayStr();
+    const content = readFileSafe(dailyPath(today));
+    const safe = content ? filterMemoryForContext(content) : "";
+    if (!safe)
+        return null;
+    return formatContextSection(`## Daily log: ${today} (today)`, safe, "middle", CONTEXT_DAILY_MAX_LINES, CONTEXT_DAILY_MAX_CHARS);
+}
+function yesterdayContextSection() {
     const yesterday = yesterdayStr();
-    const todayContent = readFileSafe(dailyPath(today));
-    const safeTodayContent = todayContent ? filterMemoryForContext(todayContent) : "";
-    if (safeTodayContent) {
-        const section = formatContextSection(`## Daily log: ${today} (today)`, safeTodayContent, "middle", CONTEXT_DAILY_MAX_LINES, CONTEXT_DAILY_MAX_CHARS);
-        if (section)
-            sections.push(section);
-    }
-    const safeSearchResults = searchResults ? filterMemoryForContext(searchResults) : "";
-    if (safeSearchResults) {
-        const section = formatContextSection("## Relevant memories (auto-retrieved)", safeSearchResults, "start", CONTEXT_SEARCH_MAX_LINES, CONTEXT_SEARCH_MAX_CHARS);
-        if (section)
-            sections.push(section);
-    }
+    const content = readFileSafe(dailyPath(yesterday));
+    const safe = content ? filterMemoryForContext(content) : "";
+    if (!safe)
+        return null;
+    return formatContextSection(`## Daily log: ${yesterday} (yesterday)`, safe, "end", CONTEXT_DAILY_MAX_LINES, CONTEXT_DAILY_MAX_CHARS);
+}
+function searchContextSection(searchResults) {
+    const safe = searchResults ? filterMemoryForContext(searchResults) : "";
+    if (!safe)
+        return null;
+    return formatContextSection("## Relevant memories (auto-retrieved)", safe, "start", CONTEXT_SEARCH_MAX_LINES, CONTEXT_SEARCH_MAX_CHARS);
+}
+function longTermContextSection() {
     const longTerm = readFileSafe(MEMORY_FILE);
-    const safeLongTerm = longTerm ? filterMemoryForContext(longTerm) : "";
-    if (safeLongTerm) {
-        const section = formatContextSection("## MEMORY.md (long-term)", safeLongTerm, "middle", CONTEXT_LONG_TERM_MAX_LINES, CONTEXT_LONG_TERM_MAX_CHARS);
-        if (section)
-            sections.push(section);
-    }
-    const yesterdayContent = readFileSafe(dailyPath(yesterday));
-    const safeYesterdayContent = yesterdayContent ? filterMemoryForContext(yesterdayContent) : "";
-    if (safeYesterdayContent) {
-        const section = formatContextSection(`## Daily log: ${yesterday} (yesterday)`, safeYesterdayContent, "end", CONTEXT_DAILY_MAX_LINES, CONTEXT_DAILY_MAX_CHARS);
-        if (section)
-            sections.push(section);
-    }
-    if (sections.length === 0) {
+    const safe = longTerm ? filterMemoryForContext(longTerm) : "";
+    if (!safe)
+        return null;
+    return formatContextSection("## MEMORY.md (long-term)", safe, "middle", CONTEXT_LONG_TERM_MAX_LINES, CONTEXT_LONG_TERM_MAX_CHARS);
+}
+function assembleContext(sections) {
+    const kept = sections.filter((s) => !!s);
+    if (kept.length === 0)
         return "";
-    }
-    const context = `# Memory\n\n${sections.join("\n\n---\n\n")}`;
+    const context = `# Memory\n\n${kept.join("\n\n---\n\n")}`;
     if (context.length > CONTEXT_MAX_CHARS) {
         const note = "\n\n[truncated overall context to 16000 chars]";
         return context.slice(0, CONTEXT_MAX_CHARS - note.length).trimEnd() + note;
     }
     return context;
 }
+/**
+ * Full context: scratchpad + topics + today + search + MEMORY.md + yesterday.
+ * Used by `agent-memory context` and by SessionStart in stable mode.
+ */
+export function buildMemoryContext(searchResults) {
+    ensureDirs();
+    return assembleContext([
+        scratchpadContextSection(),
+        buildTopicsContextSection(),
+        todayContextSection(),
+        searchContextSection(searchResults),
+        longTermContextSection(),
+        yesterdayContextSection(),
+    ]);
+}
+/**
+ * Stable subset: scratchpad + topics + MEMORY.md. No daily logs, no search.
+ * Emitted at SessionStart in per-turn mode — the durable facts that survive
+ * across sessions and are unlikely to be affected by the current prompt.
+ */
+export function buildStableContext() {
+    ensureDirs();
+    return assembleContext([scratchpadContextSection(), buildTopicsContextSection(), longTermContextSection()]);
+}
+/**
+ * Dynamic subset: today's daily log + qmd search hits + yesterday's daily log.
+ * Emitted at UserPromptSubmit — turn-scoped context that can be scoped by the
+ * current query. Excludes MEMORY.md and scratchpad (already sent at SessionStart).
+ */
+export function buildDynamicContext(searchResults, _query) {
+    ensureDirs();
+    return assembleContext([todayContextSection(), searchContextSection(searchResults), yesterdayContextSection()]);
+}
 function buildTopicsContextSection() {
     let topicFiles;
     try {
@@ -531,14 +592,22 @@ function findSkillsRoot() {
             dir = parent;
         }
     };
+    const realDirOf = (p) => {
+        try {
+            return path.dirname(fs.realpathSync(p));
+        }
+        catch {
+            return path.resolve(path.dirname(p));
+        }
+    };
     const argvPath = process.argv[1];
     if (argvPath) {
-        const found = scanUp(path.resolve(path.dirname(argvPath)));
+        const found = scanUp(realDirOf(argvPath));
         if (found)
             return found;
     }
-    const execDir = path.dirname(process.execPath);
-    const found = scanUp(path.resolve(execDir));
+    const execDir = realDirOf(process.execPath);
+    const found = scanUp(execDir);
     if (found)
         return found;
     return scanUp(path.resolve(process.cwd()));
@@ -603,18 +672,18 @@ export async function setupQmdCollection() {
     }
     return true;
 }
-export function detectQmd() {
+export function detectQmd(options = {}) {
     return new Promise((resolve) => {
         // qmd doesn't reliably support --version; use a fast command that exits 0 when available.
-        execFileFn("qmd", ["status"], { timeout: 5_000 }, (err) => {
+        execFileFn("qmd", ["status"], { timeout: 5_000, signal: options.signal }, (err) => {
             resolve(!err);
         });
     });
 }
-export function checkCollection(name) {
+export function checkCollection(name, options = {}) {
     const collName = name ?? QMD_COLLECTION_NAME;
     return new Promise((resolve) => {
-        execFileFn("qmd", ["collection", "list", "--json"], { timeout: 10_000 }, (err, stdout) => {
+        execFileFn("qmd", ["collection", "list", "--json"], { timeout: 10_000, signal: options.signal }, (err, stdout) => {
             if (err) {
                 resolve(false);
                 return;
@@ -723,10 +792,10 @@ export async function runQmdEmbedNow() {
         });
     });
 }
-export async function ensureQmdAvailableForSync() {
+export async function ensureQmdAvailableForSync(options = {}) {
     if (qmdAvailable)
         return true;
-    qmdAvailable = await detectQmd();
+    qmdAvailable = await detectQmd(options);
     return qmdAvailable;
 }
 export async function runQmdSync() {
@@ -988,18 +1057,41 @@ function qmdResultPassesSourcePolicy(filePath, snippet) {
     if (!source)
         return false;
     const activeSource = filterMemoryForContext(source);
+    // qmd truncates chunks with a trailing ellipsis, so requiring EVERY line to
+    // substring-match the source is too strict (it fails on any truncated line).
+    // We just need to verify the snippet came from THIS source and isn't stale.
+    // Require at least one substantive line to match, and reject if none do.
+    const stripTruncation = (line) => line
+        .trim()
+        .replace(/\s*\.\.\.\s*$/, "")
+        .replace(/…\s*$/, "")
+        .trim();
     const snippetLines = snippet
         .split("\n")
-        .map((line) => line.trim())
+        .map(stripTruncation)
         .filter((line) => line.length >= 8);
-    return snippetLines.length > 0 && snippetLines.every((line) => activeSource.includes(line));
+    if (snippetLines.length === 0)
+        return false;
+    return snippetLines.some((line) => activeSource.includes(line));
+}
+const RECALL_TIMEOUT_MS = 8_000;
+const RECALL_LIMIT = 3;
+// Widen upstream so post-filtering (system/plugins/**) still leaves candidates.
+const RECALL_QMD_WIDEN = 15;
+const RECALL_EXCLUDE_PATH_FRAGMENTS = ["/system/plugins/", "system/plugins/"];
+function qmdResultIsUserContent(r) {
+    const p = getQmdResultPath(r);
+    if (!p)
+        return true;
+    return !RECALL_EXCLUDE_PATH_FRAGMENTS.some((frag) => p.includes(frag));
 }
 /** Search for memories relevant to the user's prompt. Returns formatted markdown or empty string on error. */
-export async function searchRelevantMemories(prompt) {
+export async function searchRelevantMemories(prompt, options = {}) {
     if (!qmdAvailable || !prompt.trim())
         return "";
     let timer;
     const controller = new AbortController();
+    const abortFromCaller = () => controller.abort();
     // Sanitize: strip control chars, limit to 200 chars for the search query
     const sanitized = prompt
         // biome-ignore lint/suspicious/noControlCharactersInRegex: we intentionally strip control chars.
@@ -1008,22 +1100,31 @@ export async function searchRelevantMemories(prompt) {
         .slice(0, 200);
     if (!sanitized)
         return "";
+    if (options.signal?.aborted)
+        controller.abort();
+    else
+        options.signal?.addEventListener("abort", abortFromCaller, { once: true });
     try {
-        const hasCollection = await checkCollection();
+        const hasCollection = await checkCollection(undefined, { signal: controller.signal });
         if (!hasCollection)
             return "";
-        const results = await Promise.race([
-            runQmdSearch("keyword", sanitized, 3, { signal: controller.signal }),
+        // Single `qmd query --no-rerank "lex: q\nvec: q"` invocation: qmd runs BM25 +
+        // vector internally and fuses via RRF. ~1.5s vs 2.5s for two parallel calls.
+        // No LLM query expansion, no LLM rerank — those add 2-6s and hurt named-entity
+        // / temporal-reasoning recall (LongMemEval-S finding 2026-08-27).
+        const deepResult = await Promise.race([
+            runQmdSearch("deep", sanitized, RECALL_QMD_WIDEN, { signal: controller.signal }),
             new Promise((_, reject) => {
                 timer = setTimeout(() => {
                     controller.abort();
                     reject(new Error("timeout"));
-                }, 3_000);
+                }, RECALL_TIMEOUT_MS);
             }),
         ]);
-        if (!results || results.results.length === 0)
+        const fused = deepResult.results.filter(qmdResultIsUserContent).slice(0, RECALL_LIMIT);
+        if (fused.length === 0)
             return "";
-        const snippets = results.results
+        const snippets = fused
             .map((r) => {
             const text = filterMemoryForContext(getQmdResultText(r));
             if (!text)
@@ -1044,6 +1145,7 @@ export async function searchRelevantMemories(prompt) {
     }
     finally {
         clearTimeout(timer);
+        options.signal?.removeEventListener("abort", abortFromCaller);
     }
 }
 export function getQmdResultPath(r) {
@@ -1091,8 +1193,28 @@ function parseQmdJson(stdout) {
     return JSON.parse(jsonText);
 }
 export function runQmdSearch(mode, query, limit, options = {}) {
-    const subcommand = mode === "keyword" ? "search" : mode === "semantic" ? "vsearch" : "query";
-    const args = [subcommand, "--json", "-c", QMD_COLLECTION_NAME, "-n", String(limit), query];
+    // Route through qmd's typed-query interface (`qmd query --no-rerank "lex: q\nvec: q"`)
+    // so mode="deep" runs BM25 + vector in ONE qmd invocation (~1.5s) with internal
+    // RRF fusion — vs two parallel invocations (~2.5s wall). Keyword and semantic modes
+    // use the typed form too so behavior is uniform: no LLM query expansion, no
+    // LLM rerank. That was the source of 8-9s hybrid latency + the temporal-reasoning
+    // regression on LongMemEval-S (grep 83% vs expanded-hybrid 62%).
+    // qmd's `vec:` grammar treats a leading `-` on a token as negation, which
+    // blows up natural-language questions like "e-commerce" or "friends-and-
+    // family". lex tolerates negation intentionally, but for vec we normalize
+    // hyphens to spaces (and collapse whitespace) before injection.
+    const vecSafe = query.replace(/-/g, " ").replace(/\s+/g, " ").trim() || query;
+    let typedBody;
+    if (mode === "keyword")
+        typedBody = `lex: ${query}`;
+    else if (mode === "semantic")
+        typedBody = `vec: ${vecSafe}`;
+    else
+        typedBody = `lex: ${query}\nvec: ${vecSafe}`;
+    const args = [];
+    if (options.index)
+        args.push("--index", options.index);
+    args.push("query", "--json", "--no-rerank", "-c", options.collection ?? QMD_COLLECTION_NAME, "-n", String(limit), typedBody);
     return new Promise((resolve, reject) => {
         execFileFn("qmd", args, { timeout: 60_000, signal: options.signal }, (err, stdout, stderr) => {
             if (err) {
@@ -1149,6 +1271,47 @@ export async function probeEmbeddings() {
         clearTimeout(timer);
     }
 }
+const LONG_TERM_SOFT_LINE_CAP = 50;
+const LONG_TERM_DUPLICATE_THRESHOLD = 0.6;
+function significantWords(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/<!--.*?-->/gs, " ")
+        .replace(/[`*_#>[\]()]/g, " ")
+        .split(/\s+/)
+        .filter((word) => word.length > 2));
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const word of a) {
+        if (b.has(word))
+            intersection++;
+    }
+    return intersection / (a.size + b.size - intersection);
+}
+/** Cheap near-duplicate check against existing long_term entries — advisory only, never blocks the write. */
+function findSimilarLongTermEntry(existingContent, newContent) {
+    const newWords = significantWords(newContent);
+    if (newWords.size === 0)
+        return null;
+    const { entries } = splitLogicalMemoryEntries(existingContent);
+    for (const entry of entries) {
+        if (!entry.trim())
+            continue;
+        if (jaccardSimilarity(newWords, significantWords(entry)) >= LONG_TERM_DUPLICATE_THRESHOLD) {
+            return entry.trim();
+        }
+    }
+    return null;
+}
+function longTermLineCapWarning(finalContent) {
+    const lineCount = finalContent.split("\n").length;
+    if (lineCount <= LONG_TERM_SOFT_LINE_CAP)
+        return null;
+    return `MEMORY.md is now ${lineCount} lines, over the recommended ~${LONG_TERM_SOFT_LINE_CAP}-line cap — consider \`agent-memory distil\` to curate it back down.`;
+}
 export async function memoryWrite(params) {
     const memoryDir = params.directory ? path.resolve(params.directory) : getMemoryDir();
     fs.mkdirSync(memoryDir, { recursive: true });
@@ -1256,8 +1419,9 @@ export async function memoryWrite(params) {
         const stored = formatStoredEntry(content, `<!-- last updated: ${ts} [${sid}] -->`, params.sourceUri);
         fs.writeFileSync(memFile, stored.entry, "utf-8");
         await scheduleSearchRefresh();
+        const warnings = [longTermLineCapWarning(stored.entry)].filter((w) => w !== null);
         return {
-            text: `Overwrote MEMORY.md${existingSnippet}`,
+            text: `Overwrote MEMORY.md${warnings.length ? `\n\n${warnings.join("\n\n")}` : ""}${existingSnippet}`,
             details: {
                 path: memFile,
                 target,
@@ -1268,16 +1432,25 @@ export async function memoryWrite(params) {
                 redacted: stored.redacted,
                 qmdUpdateMode: getQmdUpdateMode(),
                 existingPreview,
+                warnings,
             },
         };
     }
     // append (default)
+    const similarEntry = findSimilarLongTermEntry(existing, content);
     const separator = existing.trim() ? "\n\n" : "";
     const stored = formatStoredEntry(content, `<!-- ${ts} [${sid}] -->`, params.sourceUri);
-    fs.writeFileSync(memFile, existing + separator + stored.entry, "utf-8");
+    const merged = existing + separator + stored.entry;
+    fs.writeFileSync(memFile, merged, "utf-8");
     await scheduleSearchRefresh();
+    const warnings = [
+        similarEntry
+            ? `Possible duplicate — an existing entry looks similar:\n${buildPreview(similarEntry, { maxLines: 4, maxChars: 300, mode: "start" }).preview}\nConsider \`--mode overwrite\` to curate instead of appending a near-duplicate.`
+            : null,
+        longTermLineCapWarning(merged),
+    ].filter((w) => w !== null);
     return {
-        text: `Appended to MEMORY.md${existingSnippet}`,
+        text: `Appended to MEMORY.md${warnings.length ? `\n\n${warnings.join("\n\n")}` : ""}${existingSnippet}`,
         details: {
             path: memFile,
             target,
@@ -1288,6 +1461,7 @@ export async function memoryWrite(params) {
             redacted: stored.redacted,
             qmdUpdateMode: getQmdUpdateMode(),
             existingPreview,
+            warnings,
         },
     };
 }