pi-memoria 0.1.2 → 0.2.0

package/index.ts

@@ -25,49 +25,44 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { MemoriaRuntime } from "./src/runtime.ts";
 import { registerMemoriaTools } from "./src/tools.ts";
 import { registerMemoriaCommand, setStatus } from "./src/commands.ts";
-import { RECALL_CUSTOM_TYPE, buildRecallParts, renderRecallBlock, renderStatusLine, renderSystemSection, ripgrepNotice } from "./src/recall.ts";
-import { buildTranscriptText, harvestSession } from "./src/learn.ts";
+import { RECALL_CUSTOM_TYPE, cleanRecallPrompt, selectAutoRecallHits, recallFingerprint, visibleRecallFingerprints, buildRecallParts, renderRecallBlock, renderStatusLine, renderSystemSection, ripgrepNotice } from "./src/recall.ts";
 import { createModelReranker } from "./src/rerank.ts";
 import { tokenizeRaw } from "./src/tokenize.ts";
-import { oneLine } from "./src/util.ts";
+import { KeyedMutex, oneLine } from "./src/util.ts";
 
 const RECENT_PROMPT_LIMIT = 6;
 
 export default function memoria(pi: ExtensionAPI) {
 	let runtime: MemoriaRuntime | undefined;
 	let runtimeCwd: string | undefined;
-	let initPromise: Promise<void> | undefined;
+	const runtimeLock = new KeyedMutex();
 	let hotCache: { content: string; chars: number; limit: number; over: boolean; mtimeMs: number } | undefined;
 	let recentPrompts: string[] = [];
 	/** The missing-ripgrep warning is shown once per session, not on every prompt. */
 	let ripgrepWarned = false;
-	/** Auto-learn bookkeeping: user turns since the last extraction, and when. */
-	let turnsSinceLearn = 0;
-	let lastLearnAt = 0;
-	let learnInFlight = false;
-
 	/** Resolve (and lazily initialize) the runtime for this working directory. */
-	const getRuntime = async (ctx: ExtensionContext): Promise<MemoriaRuntime> => {
+	const getRuntime = (ctx: ExtensionContext): Promise<MemoriaRuntime> => runtimeLock.run("runtime", async () => {
 		if (!runtime || runtimeCwd !== ctx.cwd) {
-			await runtime?.dispose().catch(() => {});
+			const previous = runtime;
+			runtime = undefined;
+			runtimeCwd = undefined;
+			await previous?.dispose().catch(() => {});
 			// Follow pi's own agent directory (honours PI_CODING_AGENT_DIR) so the
 			// store lives at `<agent dir>/memoria`.
-			runtime = new MemoriaRuntime(ctx.cwd, { agentDir: getAgentDir() });
+			const next = new MemoriaRuntime(ctx.cwd, { agentDir: getAgentDir() });
+			try {
+				await next.init(true);
+			} catch (error) {
+				await next.dispose().catch(() => {});
+				throw error;
+			}
+			runtime = next;
 			runtimeCwd = ctx.cwd;
 			hotCache = undefined;
 			recentPrompts = [];
-			turnsSinceLearn = 0;
-			lastLearnAt = 0;
-			learnInFlight = false;
-			initPromise = runtime.init(true).catch((error) => {
-				// Allow a later attempt to retry instead of caching the rejection forever.
-				initPromise = undefined;
-				throw error;
-			});
 		}
-		await initPromise;
 		return runtime;
-	};
+	});
 
 	/** Read MEMORY.md, reusing the cached copy until its mtime changes. */
 	const readHotCached = async (memoria: MemoriaRuntime): Promise<{ content: string; chars: number; limit: number; over: boolean }> => {
@@ -114,7 +109,7 @@ export default function memoria(pi: ExtensionAPI) {
 
 			// Layer 1: stable system-prompt section with MEMORY.md + library map.
 			const hot = await readHotCached(memoria_);
-			const overview = await memoria_.overview(4);
+			const overview = await memoria_.overview(0);
 			event.systemPromptOptions.sections.memoria = renderSystemSection({
 				root: memoria_.roots.primary,
 				hotContent: hot.over ? hot.content.slice(0, hot.limit) : hot.content,
@@ -124,16 +119,14 @@ export default function memoria(pi: ExtensionAPI) {
 				categories: overview.categories,
 				totalDocs: overview.docs,
 				indexTookMs: 0,
-				recent: overview.recent,
 			});
 
 			// Reranking is opt-in and best-effort; the lexical order is the fallback.
 			memoria_.setReranker(memoria_.config.rerank ? createModelReranker(ctx) : undefined);
 
 			// Layer 2: per-prompt recall block.
-			turnsSinceLearn += 1;
 			if (!memoria_.config.autoRecall) return undefined;
-			const prompt = event.prompt ?? "";
+			const prompt = cleanRecallPrompt(event.prompt ?? "");
 			if (prompt.trimStart().startsWith("/")) return undefined;
 			const tokens = tokenizeRaw(prompt);
 			if (tokens.length < 2 && !/\d/.test(prompt)) return undefined;
@@ -145,10 +138,15 @@ export default function memoria(pi: ExtensionAPI) {
 				ctx.ui.notify(`memoria: ${rgNotice}.`, "warning");
 			}
 			recentPrompts = [...recentPrompts, prompt].slice(-RECENT_PROMPT_LIMIT);
-			const hits = result.hits.filter((hit) => hit.score >= memoria_.config.autoRecallMinScore);
+			const tables = await Promise.all([...new Set(result.hits.map(hit => hit.doc.root))].map(root => memoria_.synonymsFor(root)));
+			const synonyms: Record<string, string[]> = {};
+			for (const table of tables) for (const [term, values] of Object.entries(table)) synonyms[term] = [...(synonyms[term] ?? []), ...values];
+			const relevant = selectAutoRecallHits(result.hits, prompt, memoria_.config.autoRecallMinScore, memoria_.config.autoRecallMinRatio, synonyms);
+			const seen = visibleRecallFingerprints(ctx.sessionManager.buildContextEntries?.() ?? ctx.sessionManager.getBranch());
+			const hits = relevant.filter(hit => !seen.has(recallFingerprint(hit)));
 			// Nothing in the library? Show what earlier conversations said instead
 			// of leaving the model with nothing to go on.
-			const sessionHits = hits.length === 0 ? result.sessionHits : undefined;
+			const sessionHits = relevant.length === 0 ? result.sessionHits : undefined;
 			if (hits.length === 0 && (!sessionHits || sessionHits.length === 0)) return undefined;
 			const rendered = renderRecallBlock({
 				query: oneLine(prompt, 160),
@@ -160,12 +158,14 @@ export default function memoria(pi: ExtensionAPI) {
 				sessionHits,
 				sessionStats: result.sessionStats,
 			});
+			if (!rendered) return undefined;
+			const included = hits.filter(hit => rendered.includes(`- [${hit.doc.id}]`));
 			return {
 				message: {
 					customType: RECALL_CUSTOM_TYPE,
 					content: rendered,
 					display: true,
-					details: { ids: hits.map((hit) => hit.doc.id), tookMs: result.tookMs, sessionHits: sessionHits?.length ?? 0 },
+					details: { ids: included.map((hit) => hit.doc.id), fingerprints: included.map(recallFingerprint), tookMs: result.tookMs, sessionHits: sessionHits?.length ?? 0 },
 				},
 			};
 		} catch (error) {
@@ -175,75 +175,15 @@ export default function memoria(pi: ExtensionAPI) {
 		}
 	});
 
-	/**
-	 * Automatic session learning.
-	 *
-	 * Runs only when configured, only after enough conversation has accumulated,
-	 * and at most once per cooldown window. It never blocks the turn: extraction
-	 * happens after the agent loop ends.
-	 */
-	const maybeAutoLearn = async (ctx: ExtensionContext, trigger: "settle" | "shutdown"): Promise<void> => {
-		if (!runtime || learnInFlight) return;
-		const mode = runtime.config.autoLearn;
-		if (mode === "off") return;
-		if (mode === "on-settle" && trigger !== "settle") return;
-		if (mode === "on-shutdown" && trigger !== "shutdown") return;
-		if (turnsSinceLearn < runtime.config.autoLearnMinTurns) return;
-		const now = Date.now();
-		if (now - lastLearnAt < runtime.config.autoLearnCooldownMs) return;
-		const branch = ctx.sessionManager.getBranch() as ReadonlyArray<{ type?: string; message?: { role?: string; content?: unknown } }>;
-		// The character floor keeps a burst of tiny turns from triggering a model
-		// call that has nothing to extract from.
-		const transcriptChars = buildTranscriptText(branch, 40_000).length;
-		if (transcriptChars < runtime.config.autoLearnMinChars) return;
-		learnInFlight = true;
-		lastLearnAt = now;
-		turnsSinceLearn = 0;
-		try {
-			setStatus(ctx, "memoria: extracting memories...");
-			const result = await harvestSession(ctx, runtime, branch, {
-				chunkChars: runtime.config.learnChunkChars,
-				onProgress: (update) => {
-					if (update.total > 1) setStatus(ctx, `memoria: extracting memories... ${update.index}/${update.total}`);
-				},
-			});
-			const total = result.created.length + result.updated.length;
-			if (total > 0) {
-				ctx.ui.notify(`memoria: learned ${total} note${total === 1 ? "" : "s"} (${result.created.length} new, ${result.updated.length} updated)`, "info");
-			} else if (result.error) {
-				setStatus(ctx, undefined);
-			}
-		} catch (error) {
-			ctx.ui.notify(`memoria: auto-learn failed: ${(error as Error).message}`, "warning");
-		} finally {
-			learnInFlight = false;
-			try {
-				const stats = await runtime.stats();
-				const docs = stats.roots.reduce((sum, entry) => sum + entry.docs, 0);
-				setStatus(ctx, renderStatusLine(runtime.config, docs, stats.hot.chars, 0));
-			} catch {
-				setStatus(ctx, undefined);
-			}
-		}
-	};
-
-	pi.on("agent_end", async (_event, ctx) => {
-		await maybeAutoLearn(ctx, "settle").catch(() => {});
-	});
-
-	pi.on("session_shutdown", async (_event, ctx) => {
-		try {
-			await maybeAutoLearn(ctx, "shutdown");
-		} catch {
-			// Shutdown must never throw.
-		}
-		await runtime?.flushUsageNow().catch(() => {});
-		await runtime?.dispose().catch(() => {});
-		runtime = undefined;
-		runtimeCwd = undefined;
-		initPromise = undefined;
-		hotCache = undefined;
-		recentPrompts = [];
+	pi.on("session_shutdown", async (_event, _ctx) => {
+		await runtimeLock.run("runtime", async () => {
+			await runtime?.flushUsageNow().catch(() => {});
+			await runtime?.dispose().catch(() => {});
+			runtime = undefined;
+			runtimeCwd = undefined;
+			hotCache = undefined;
+			recentPrompts = [];
+		});
 	});
 
 	pi.registerMessageRenderer(RECALL_CUSTOM_TYPE, (message, options, theme) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-memoria",
-	"version": "0.1.2",
+	"version": "0.2.0",
 	"description": "Agent-first long-term memory for pi: a categorized markdown library with automatic, sub-millisecond recall.",
 	"type": "module",
 	"license": "MIT",

package/skills/memoria/SKILL.md

@@ -52,8 +52,8 @@ bad file name, or consolidating notes that describe the same thing.
 - **A note is wrong** — write the correction with `memoria_write` using the same
   topic, or `supersedes` the old note when it replaces a decision.
 - **Never something again** — `memoria_forget` (soft delete into `.trash/`).
-- **Backup or migrate** — `memoria_export` to JSONL, `memoria_import` to restore
-  (`dry_run: true` first, `mode: "merge"` unless you mean to replace).
+- **Backup or migrate** — copy the store directory (`~/.pi/agent/memoria/`);
+  notes are plain markdown and `.index/` is derived.
 - **Search feels weak** — add `synonyms.json`, or check `/memoria status`.
 
 ## Do not
@@ -63,3 +63,15 @@ bad file name, or consolidating notes that describe the same thing.
 - Do not store secrets, credentials or tokens in the library.
 - Do not create a note per fact, and do not inline a fact into MEMORY.md when a
   library note would do.
+
+
+## Before editing MEMORY.md
+
+Read the current briefing first. Include only verified standing context useful
+across most sessions. Consolidate existing statements rather than appending
+paraphrases. Apply explicit corrections in place, ask about ambiguous conflicts,
+and preserve unrelated standing facts. Keep dated history and redundant skill
+instructions in the library/skills. Never use direct file edits to bypass validation.
+Replace requires the complete intended briefing. Compact will not drop facts to
+meet the budget; author a tighter replacement instead. Every changed supported
+write preserves a previous version under `.history/`.

package/src/commands.ts

@@ -6,17 +6,15 @@
  */
 
 import { existsSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown, Text } from "@earendil-works/pi-tui";
 import type { MemoriaRuntime } from "./runtime.ts";
 import type { RuntimeGetter } from "./tools.ts";
-import { harvestSession } from "./learn.ts";
 import { ripgrepNotice } from "./recall.ts";
 import { formatSessionTime } from "./sessions.ts";
 import { describeAge } from "./usage.ts";
-import { atomicWriteFile, oneLine } from "./util.ts";
+import { oneLine } from "./util.ts";
 import type { Scope } from "./types.ts";
 
 export const COMMAND_ENTRY_TYPE = "memoria_command";
@@ -26,7 +24,7 @@ const SUBCOMMANDS: Array<{ value: string; label: string; description: string }>
 	{ value: "search", label: "search <query>", description: "Search long-term memory" },
 	{ value: "store", label: "store <text>", description: "Quickly save a memory to the inbox" },
 	{ value: "read", label: "read <id|path>", description: "Read a full memory note" },
-	{ value: "move", label: "move <ref> <topic>", description: "Re-file a note under a better broad topic" },
+	{ value: "move", label: "move <ref> <topic> [--merge]", description: "Re-file a note under a better broad topic" },
 	{ value: "hot", label: "hot", description: "Show MEMORY.md and its budget" },
 	{ value: "reindex", label: "reindex", description: "Rebuild the search index from disk" },
 	{ value: "index", label: "index", description: "Regenerate library/INDEX.md table of contents" },
@@ -34,9 +32,6 @@ const SUBCOMMANDS: Array<{ value: string; label: string; description: string }>
 	{ value: "topics", label: "topics", description: "Review notes: size, facts, usage, merge candidates" },
 	{ value: "diff", label: "diff [days]", description: "Show memories created or updated recently" },
 	{ value: "sessions", label: "sessions <query>", description: "Search earlier conversations (raw transcripts)" },
-	{ value: "export", label: "export [file]", description: "Dump the store to JSONL" },
-	{ value: "import", label: "import <file>", description: "Restore memories from a JSONL export" },
-	{ value: "learn", label: "learn", description: "Extract durable memories from the current session" },
 	{ value: "paths", label: "paths", description: "Print store paths" },
 	{ value: "forget", label: "forget <id>", description: "Move a memory to .trash" },
 ];
@@ -73,7 +68,7 @@ async function statusMarkdown(runtime: MemoriaRuntime): Promise<string> {
 		lines.push(`**Categories:** ${[...categories.entries()].sort((a, b) => b[1] - a[1]).map(([category, count]) => `${category} (${count})`).join(", ")}`);
 	}
 	lines.push("");
-	lines.push(`**Auto-recall:** ${runtime.config.autoRecall ? `on (limit ${runtime.config.autoRecallLimit}, min score ${runtime.config.autoRecallMinScore})` : "off"} | **auto-learn:** ${runtime.config.autoLearn}`);
+	lines.push(`**Auto-recall:** ${runtime.config.autoRecall ? `on (limit ${runtime.config.autoRecallLimit}, min score ${runtime.config.autoRecallMinScore})` : "off"}`);
 	lines.push(`**Index:** ${runtime.config.indexFormat} | **rerank:** ${runtime.config.rerank ? runtime.config.rerankModel || "session model" : "off"} | **synonym table:** ${Object.keys(runtime.config.synonyms).length} inline`);
 	lines.push(
 		`**Session recall:** ${runtime.config.sessionSearch ? (runtime.config.sessionFallback ? "on (falls back when memory is empty)" : "on (explicit only)") : "off"} | roots: ${runtime.sessionRoots().filter((root) => existsSync(root)).length}`,
@@ -183,12 +178,13 @@ export function registerMemoriaCommand(pi: ExtensionAPI, getRuntime: RuntimeGett
 				}
 				case "move": {
 					const [ref, ...rest] = remainder.split(/\s+/).filter(Boolean);
-					const topic = rest.join(" ").trim();
+					const merge = rest.includes("--merge");
+					const topic = rest.filter((word) => word !== "--merge").join(" ").trim();
 					if (!ref || !topic) {
-						ctx.ui.notify("Usage: /memoria move <id|path|alias> <new broad topic>", "warning");
+						ctx.ui.notify("Usage: /memoria move <id|path|alias> <new broad topic> [--merge]", "warning");
 						return;
 					}
-					const moved = await runtime.move(ref, { topic }, "all");
+					const moved = await runtime.move(ref, { topic, merge }, "all");
 					if (!moved) {
 						ctx.ui.notify(`Memory not found: ${ref}`, "error");
 						return;
@@ -272,7 +268,7 @@ export function registerMemoriaCommand(pi: ExtensionAPI, getRuntime: RuntimeGett
 						lines.push("**Merge candidates** (same subject, two files):");
 						for (const merge of merges) {
 							lines.push(
-								`- \`${merge.a.relPath}\` ↔ \`${merge.b.relPath}\` (${Math.round(merge.score * 100)}% overlap: ${merge.shared.join(", ")}) → \`/memoria move ${merge.b.id} ${merge.a.title}\``,
+								`- \`${merge.a.relPath}\` ↔ \`${merge.b.relPath}\` (${Math.round(merge.score * 100)}% overlap: ${merge.shared.join(", ")}) → \`/memoria move ${merge.b.id} ${merge.a.title} --merge\``,
 							);
 						}
 					}
@@ -353,78 +349,6 @@ export function registerMemoriaCommand(pi: ExtensionAPI, getRuntime: RuntimeGett
 					emit(pi, `memoria diff: last ${Number.isFinite(days) ? days : 7} days`, lines.join("\n"));
 					return;
 				}
-				case "export": {
-					const flags = remainder.split(/\s+/).filter(Boolean);
-					// `--hot` exports MEMORY.md alone as a readable "about me" document.
-					if (flags.includes("--hot")) {
-						const fileArg = flags.find((flag) => !flag.startsWith("--"));
-						const target = fileArg
-							? isAbsolute(fileArg)
-								? fileArg
-								: resolve(ctx.cwd, fileArg)
-							: resolve(ctx.cwd, "about-me.md");
-						const hot = await runtime.hotState();
-						await atomicWriteFile(target, `${hot.content.trim()}\n`);
-						emit(pi, "memoria export", `Wrote MEMORY.md (${hot.chars} chars) to \`${target}\`.`);
-						return;
-					}
-					const fileArg = flags.find((flag) => !flag.startsWith("--"));
-					const { jsonl, notes } = await runtime.exportJsonl({ scope: "all" });
-					const target = fileArg
-						? isAbsolute(fileArg)
-							? fileArg
-							: resolve(ctx.cwd, fileArg)
-						: resolve(ctx.cwd, `memoria-export-${new Date().toISOString().slice(0, 10)}.jsonl`);
-					await atomicWriteFile(target, jsonl);
-					emit(pi, "memoria export", `Exported ${notes} note(s) to \`${target}\` (${jsonl.length} bytes).`);
-					return;
-				}
-				case "import": {
-					if (!remainder) {
-						ctx.ui.notify("Usage: /memoria import <file> [--merge|--replace|--skip] [--dry-run]", "warning");
-						return;
-					}
-					const flags = remainder.split(/\s+/);
-					const fileArg = flags.find((flag) => !flag.startsWith("--"));
-					if (!fileArg) {
-						ctx.ui.notify("Usage: /memoria import <file> [--merge|--replace|--skip] [--dry-run]", "warning");
-						return;
-					}
-					const mode = flags.includes("--replace") ? "replace" : flags.includes("--skip") ? "skip" : "merge";
-					const dryRun = flags.includes("--dry-run");
-					const target = isAbsolute(fileArg) ? fileArg : resolve(ctx.cwd, fileArg);
-					const { readFile } = await import("node:fs/promises");
-					const payload = await readFile(target, "utf8");
-					const result = await runtime.importJsonl(payload, { mode, dryRun });
-					const lines = [
-						`${dryRun ? "Dry run:" : "Imported"} ${result.created.length} new, ${result.updated.length} updated, ${result.skipped} skipped.`,
-					];
-					if (result.hotImported) lines.push("MEMORY.md restored.");
-					if (result.errors.length > 0) lines.push("", "**Skipped records:**", ...result.errors.slice(0, 20).map((error) => `- ${error}`));
-					emit(pi, `memoria import: ${oneLine(fileArg, 60)}`, lines.join("\n"));
-					return;
-				}
-				case "learn": {
-					ctx.ui.notify("Extracting durable memories from this session...", "info");
-					const branch = ctx.sessionManager.getBranch() as ReadonlyArray<{ type?: string; message?: { role?: string; content?: unknown } }>;
-					const result = await harvestSession(ctx, runtime, branch, {
-						chunkChars: runtime.config.learnChunkChars,
-						onProgress: (update) => {
-							if (update.total > 1) {
-								setStatus(ctx, `memoria: extracting memories... ${update.index}/${update.total}`);
-								ctx.ui.notify(`Extracting memories (${update.index}/${update.total})...`, "info");
-							}
-						},
-					});
-					setStatus(ctx, undefined);
-					const lines: string[] = [];
-					if (result.error) lines.push(result.error);
-					if (result.created.length > 0) lines.push(`**Created ${result.created.length}:**\n${result.created.map((id) => `- \`${id}\``).join("\n")}`);
-					if (result.updated.length > 0) lines.push(`**Updated ${result.updated.length}:**\n${result.updated.map((id) => `- \`${id}\``).join("\n")}`);
-					if (result.skipped > 0) lines.push(`_${result.skipped} candidate(s) could not be merged._`);
-					emit(pi, "memoria learn", lines.join("\n\n") || "Nothing durable found in this session.");
-					return;
-				}
 				case "paths": {
 					const paths = runtime.paths();
 					emit(

package/src/config.ts

@@ -34,7 +34,8 @@ export const DEFAULT_CONFIG: MemoriaConfig = {
 	hotLimit: 5000,
 	snippetChars: 280,
 	autoRecall: true,
-	autoRecallLimit: 6,
+	autoRecallLimit: 3,
+	autoRecallMinRatio: 0.3,
 	autoRecallMinScore: 1.4,
 	autoRecallMaxChars: 2400,
 	autoRecallLastTurns: 1,
@@ -60,11 +61,6 @@ export const DEFAULT_CONFIG: MemoriaConfig = {
 	rerankModel: "",
 	rerankTopK: 12,
 	rerankTimeoutMs: 2500,
-	autoLearn: "off",
-	autoLearnMinTurns: 8,
-	autoLearnMinChars: 2000,
-	autoLearnCooldownMs: 21_600_000,
-	learnChunkChars: 12_000,
 	watcherSettleMs: 300,
 	indexFormat: "auto",
 	sessionSearch: true,
@@ -132,6 +128,7 @@ function coerceConfig(raw: unknown): Partial<MemoriaConfig> {
 	if (number(input.snippetChars) !== undefined) out.snippetChars = Math.max(80, number(input.snippetChars)!);
 	if (bool(input.autoRecall) !== undefined) out.autoRecall = bool(input.autoRecall);
 	if (number(input.autoRecallLimit) !== undefined) out.autoRecallLimit = Math.max(0, Math.min(20, number(input.autoRecallLimit)!));
+	if (number(input.autoRecallMinRatio) !== undefined) out.autoRecallMinRatio = Math.max(0, Math.min(1, number(input.autoRecallMinRatio)!));
 	if (number(input.autoRecallMinScore) !== undefined) out.autoRecallMinScore = Math.max(0, number(input.autoRecallMinScore)!);
 	if (number(input.autoRecallMaxChars) !== undefined) out.autoRecallMaxChars = Math.max(200, number(input.autoRecallMaxChars)!);
 	if (number(input.autoRecallLastTurns) !== undefined) out.autoRecallLastTurns = Math.max(0, Math.min(5, number(input.autoRecallLastTurns)!));
@@ -156,11 +153,6 @@ function coerceConfig(raw: unknown): Partial<MemoriaConfig> {
 	if (number(input.rerankTopK) !== undefined) out.rerankTopK = Math.max(1, Math.min(50, number(input.rerankTopK)!));
 	if (number(input.rerankTimeoutMs) !== undefined) out.rerankTimeoutMs = Math.max(250, Math.min(30_000, number(input.rerankTimeoutMs)!));
 	if (number(input.synonymWeight) !== undefined) out.synonymWeight = Math.max(0.1, Math.min(1, number(input.synonymWeight)!));
-	if (str(input.autoLearn) && ["off", "on-settle", "on-shutdown"].includes(input.autoLearn as string)) out.autoLearn = input.autoLearn as string;
-	if (number(input.autoLearnMinTurns) !== undefined) out.autoLearnMinTurns = Math.max(1, number(input.autoLearnMinTurns)!);
-	if (number(input.autoLearnMinChars) !== undefined) out.autoLearnMinChars = Math.max(200, number(input.autoLearnMinChars)!);
-	if (number(input.autoLearnCooldownMs) !== undefined) out.autoLearnCooldownMs = Math.max(0, number(input.autoLearnCooldownMs)!);
-	if (number(input.learnChunkChars) !== undefined) out.learnChunkChars = Math.max(2000, number(input.learnChunkChars)!);
 	if (number(input.watcherSettleMs) !== undefined) out.watcherSettleMs = Math.max(0, Math.min(5000, number(input.watcherSettleMs)!));
 	if (str(input.indexFormat) && ["auto", "json", "binary"].includes(input.indexFormat as string)) out.indexFormat = input.indexFormat as string;
 	if (bool(input.sessionSearch) !== undefined) out.sessionSearch = bool(input.sessionSearch);

package/src/index-engine.ts

@@ -42,6 +42,7 @@ export function isIgnoredWatchPath(relName: string): boolean {
 	const name = normalizeRelPath(relName);
 	if (!name) return true;
 	if (name === INDEX_DIR || name.startsWith(`${INDEX_DIR}/`)) return true;
+	if (name === ".history" || name.startsWith(".history/")) return true;
 	if (name === TRASH_DIR || name.startsWith(`${TRASH_DIR}/`)) return true;
 	if (basename(name) === GENERATED_INDEX) return true;
 	return false;
@@ -150,6 +151,8 @@ export class MemoryIndex {
 
 	private termIds = new Map<string, number>();
 	private idToIdx = new Map<string, number>();
+	/** Built only for lookups that miss canonical ids; aliases are not the hot path. */
+	private aliasToIdx: Map<string, number> | undefined;
 	private relPathToIdx = new Map<string, number>();
 	private bodyCache: BodyCache;
 	private trigramIndex: Map<string, number[]> | undefined;
@@ -237,7 +240,20 @@ export class MemoryIndex {
 	}
 
 	idxForId(id: string): number | undefined {
-		return this.idToIdx.get(id);
+		const direct = this.idToIdx.get(id);
+		if (direct !== undefined) return direct;
+		// Imports may have ids that do not use the mem_ prefix. A merge records the
+		// retired id as an alias, so every former id must remain usable.
+		if (!this.aliasToIdx) {
+			this.aliasToIdx = new Map();
+			for (let idx = 0; idx < this.docs.length; idx += 1) {
+				if (!this.alive[idx]) continue;
+				for (const alias of this.docs[idx].aliases) {
+					if (!this.aliasToIdx.has(alias)) this.aliasToIdx.set(alias, idx);
+				}
+			}
+		}
+		return this.aliasToIdx.get(id);
 	}
 
 	idxForRelPath(relPath: string): number {
@@ -323,6 +339,7 @@ export class MemoryIndex {
 		this.docTfs.push(tfs);
 		this.alive.push(true);
 		this.idToIdx.set(doc.id, idx);
+		this.aliasToIdx = undefined;
 		this.relPathToIdx.set(meta.relPath, idx);
 		this.bodyCache.set(doc.path, doc.body);
 		this.linkCache = undefined;
@@ -335,6 +352,7 @@ export class MemoryIndex {
 		const doc = this.docs[idx];
 		this.alive[idx] = false;
 		this.idToIdx.delete(doc.id);
+		this.aliasToIdx = undefined;
 		this.relPathToIdx.delete(doc.relPath);
 		this.bodyCache.delete(doc.path);
 		const termIds = this.docTerms[idx] ?? [];
@@ -414,6 +432,7 @@ export class MemoryIndex {
 		this.docTfs = newDocTfs;
 		this.alive = new Array(newDocs.length).fill(true);
 		this.idToIdx = new Map();
+		this.aliasToIdx = undefined;
 		this.relPathToIdx = new Map();
 		for (let i = 0; i < newDocs.length; i += 1) {
 			this.idToIdx.set(newDocs[i].id, i);
@@ -437,6 +456,7 @@ export class MemoryIndex {
 		this.alive = [];
 		this.termIds = new Map();
 		this.idToIdx = new Map();
+		this.aliasToIdx = undefined;
 		this.relPathToIdx = new Map();
 		this.trigramIndex = undefined;
 		this.fuzzyCache.clear();
@@ -505,10 +525,8 @@ export class MemoryIndex {
 		const resolve = (ref: string): number | undefined => {
 			const trimmed = ref.trim();
 			if (!trimmed) return undefined;
-			if (trimmed.startsWith("mem_")) {
-				const idx = this.idToIdx.get(trimmed);
-				if (idx !== undefined) return idx;
-			}
+			const byId = this.idxForId(trimmed);
+			if (byId !== undefined) return byId;
 			const byPath = this.relPathToIdx.get(normalizeRelPath(trimmed));
 			if (byPath !== undefined) return byPath;
 			return titles.get(trimmed.toLowerCase());
@@ -542,7 +560,7 @@ export class MemoryIndex {
 		const titles = this.links().titles;
 		const trimmed = ref.trim();
 		if (!trimmed) return undefined;
-		const byId = this.idToIdx.get(trimmed);
+		const byId = this.idxForId(trimmed);
 		if (byId !== undefined && this.alive[byId]) return byId;
 		const byPath = this.relPathToIdx.get(normalizeRelPath(trimmed));
 		if (byPath !== undefined && this.alive[byPath]) return byPath;
@@ -827,6 +845,7 @@ export class MemoryIndex {
 		}
 		this.alive = new Array(docCount).fill(true);
 		this.idToIdx = new Map();
+		this.aliasToIdx = undefined;
 		this.relPathToIdx = new Map();
 		for (let i = 0; i < docCount; i += 1) {
 			this.idToIdx.set(this.docs[i].id, i);
@@ -935,6 +954,14 @@ export class MemoryIndex {
 	async search(query: string, options: SearchOptions = {}): Promise<SearchResult> {
 		const started = performance.now();
 		await this.refresh(false);
+		const result = this.searchWarm(query, options);
+		this.lastSearchMs = Math.round((performance.now() - started) * 100) / 100;
+		return result;
+	}
+
+	/** Score an index the caller has already refreshed. */
+	searchWarm(query: string, options: SearchOptions = {}): SearchResult {
+		const started = performance.now();
 		const result = searchIndex(this, query, options);
 		this.lastSearchMs = Math.round((performance.now() - started) * 100) / 100;
 		return result;
@@ -986,7 +1013,7 @@ export class MemoryIndex {
 			if (recent.length < recentLimit) {
 				recent.push({ id: meta.id, title: meta.title, relPath: meta.relPath, created: meta.created });
 				recent.sort((a, b) => b.created - a.created);
-			} else if (meta.created > recent[recent.length - 1].created) {
+			} else if (recentLimit > 0 && meta.created > recent[recent.length - 1].created) {
 				recent[recent.length - 1] = { id: meta.id, title: meta.title, relPath: meta.relPath, created: meta.created };
 				recent.sort((a, b) => b.created - a.created);
 			}