pi-memoria 0.1.1 → 0.1.3

package/README.md

@@ -1,4 +1,4 @@
-# memoria
+# pi-memoria
 
 Agent-first long-term memory for [pi](https://github.com/badlogic/pi-mono).
 
@@ -17,8 +17,8 @@ a millisecond.
 - **Broad topics, never fact files.** `likes-apples.md` is a defect; facts
   accumulate in `food-preferences.md`.
 - **Names are handles.** Aliases make every nickname, full name or former name
-  resolve to the same note, and notes can be re-filed later without breaking
-  references.
+  resolve to the same note. Re-filing or consolidating notes also keeps retired
+  note ids usable as references.
 - **Zero runtime dependencies.** No database, no server, no embedding service, no
   build step. Retrieval is a BM25 index kept in memory.
 
@@ -83,11 +83,11 @@ Pi discovers `extensions/memoria/index.ts` on the next start (or after
 ### Install as a pi package
 
 ```bash
-pi install git:github.com/rcsaquino/pi-memoria@v0.1.1
+pi install git:github.com/rcsaquino/pi-memoria@v0.1.3
 pi install npm:pi-memoria                 # if published to npm
 pi install ./path/to/pi-memoria           # or from a local checkout
 pi list
-pi remove git:github.com/rcsaquino/pi-memoria@v0.1.1
+pi remove git:github.com/rcsaquino/pi-memoria@v0.1.3
 ```
 
 `pi install` records the package in `~/.pi/agent/settings.json` (or
@@ -233,9 +233,10 @@ When the better name *is* known, `memoria_move` re-files the note:
 
 - Target free → the file is **renamed**; the note keeps its `id`, so ids read
   earlier in the session stay valid.
-- Target exists → facts are **merged** in (duplicates skipped, nothing
-  overwritten) and the old file goes to `.trash/`. `merge: false` reports the
-  conflict instead.
+- Target exists → the move reports a conflict. Set `merge: true` to combine the
+  facts and links (duplicates skipped, nothing overwritten) and move the old
+  file to `.trash/`. A merge refuses to discard aliases or links when their
+  limits are full.
 - The previous topic, title and file name are added to the target's aliases, so
   old references keep working.
 
@@ -308,7 +309,7 @@ folder). Unknown keys are preserved verbatim through updates.
 | `memoria_recall` | Search long-term memory. Filters by category, tags, priority, recency, scope; options for `include_body`, `min_score`, `explain`, `rerank`, `drop_superseded`, prefix/fuzzy control. |
 | `memoria_write` | Add a fact to a broad **topic note** (`topic`, `content`, optional `label`, category, tags, aliases, related, supersedes, summary, priority). Creates the note on first use and appends afterwards. |
 | `memoria_read` | Read a full note by id, path or alias, with its aliases, related notes and superseding notes. |
-| `memoria_move` | Re-file a note under a better broad topic (`from`, `topic`, optional `category`, `merge`, `keep_alias`). Renames when the target is free, merges when it is not. |
+| `memoria_move` | Re-file a note under a better broad topic (`from`, `topic`, optional `category`, `merge`, `keep_alias`). Renames when the target is free; set `merge: true` to combine with an occupied target. |
 | `memoria_sessions` | Search the transcripts of earlier conversations (`action: "search"`, plus `since_days`, `project`, `include_tools`, `user_only`) and read the surrounding dialogue (`action: "read"`, `path`, `line`, `window`) before quoting it. |
 | `memoria_hot` | Read/add/remove/replace/compact `MEMORY.md`, the always-in-context briefing. |
 | `memoria_list` | Browse categories, titles, ids, tags, aliases and summaries. |
@@ -326,7 +327,7 @@ have to ask.
 /memoria search <query>      Ranked results with snippets (--primary/--project/--all)
 /memoria store <text>        Quick capture into library/inbox
 /memoria read <id|path>      Print a full note
-/memoria move <ref> <topic>  Re-file a note under a better broad topic
+/memoria move <ref> <topic> [--merge]  Re-file a note; opt into merging an occupied target
 /memoria hot                 Show MEMORY.md
 /memoria topics              Review notes: facts, size, usage, merge candidates
 /memoria diff [days]         Memories created or updated recently (default 7 days)
@@ -409,6 +410,7 @@ back to the default rather than failing.
 | `sessionExcerptChars` | `400` | Context characters per transcript hit. |
 | `sessionCacheBytes` | `33554432` | In-memory budget for parsed transcripts. |
 | `sessionIncludeTools` | `false` | Include tool calls/results and compaction summaries by default. |
+| `sessionRipgrep` | `true` | Use a ripgrep prefilter to skip match-free transcripts when `rg` is available; without it the slower built-in scanner runs. |
 
 ## Scopes: personal, project, read-only
 
@@ -495,14 +497,30 @@ What it does and does not touch:
 | Content | User and assistant **text** by default. Thinking blocks are never extracted. Tool calls/results, compaction summaries and extension payloads only with `include_tools: true`. |
 | Output | Bounded excerpts plus `file:line`; never a whole transcript dump. |
 | Writes | None. Transcripts are read-only and `read` refuses paths outside the session roots. |
-| Cost | Full cold scan of 110 sessions / 13 MB ≈ 120 ms; repeat searches ≈ 5 ms from the parse cache. |
-| Coverage | Exhaustive unless a budget stops it. `partial` (shown in the tool output, the recall block and `/memoria sessions`) means the scan stopped early: the hits are real, but older sessions were not read. Newest sessions are scanned first, already-parsed files stay cached (so each retry gets further), and an explicit `memoria_sessions` call uses the larger `sessionScanMs` budget. |
+| Cost | With `rg`, only transcripts containing the query terms are parsed; without it, a full cold scan of 110 sessions / 13 MB ≈ 120 ms, repeats ≈ 5 ms from the parse cache. |
+| Coverage | Exhaustive unless a budget stops it. `partial` (shown in the tool output, the recall block and `/memoria sessions`) means the scan stopped early: the hits are real, but older sessions were not read. Newest sessions are scanned first, already-parsed files stay cached while they fit `sessionCacheBytes` (so retries get further on corpora that fit the cache), and concurrent searches share one in-flight parse per transcript (so several `memoria_sessions` calls in one turn do not multiply the work). An explicit `memoria_sessions` call uses the larger `sessionScanMs` budget. |
 | Privacy | Nothing leaves the machine; the excerpts go to the model only when the feature runs. |
 
 `sessionRoots` exists for archives or a second agent directory. Set
 `sessionSearch: false` to disable the feature entirely, or
 `sessionFallback: false` to keep the tool while never searching automatically.
 
+When `rg` is available (pi ships it and puts it on `PATH`), a selective search
+asks ripgrep which transcripts contain the query terms and parses only those, so
+even a gigabyte-scale history is answered within the normal budget. If `rg` is
+missing or fails, memoria falls back to reading every transcript itself and says
+so: the result carries a `ripgrep is not installed` note, and interactive mode
+shows it once per session. Large histories may then be only partially covered.
+
+Without `rg` (or for a deliberately disabled accelerator), the default
+`sessionScanMs` budget and `sessionCacheBytes` cache cover only part of a large
+corpus: searches report `partial`, and repeats are cold scans because the cache
+cannot retain the parsed files. Raise `sessionScanMs` so an explicit
+`memoria_sessions` call can cover the whole corpus in one pass, and
+`sessionCacheBytes` only if you have the RAM for the parsed messages (at this
+scale that means gigabytes). The automatic fallback remains capped at 400 ms,
+so on such a corpus it is always a partial scan.
+
 ## Backup and migration
 
 `memoria_export` writes JSONL — one record per line, notes plus `MEMORY.md` — to
@@ -554,10 +572,13 @@ a burst of edits costs one refresh.
 - **Files, not a database.** Memoria never owns your data: notes are markdown
   with frontmatter, deletes are soft (moved to `.trash/`), and the index is
   derived and can be rebuilt with `/memoria reindex`.
-- **Crash-safe moves.** Category moves and renames are journaled, so an
-  interrupted move is completed on the next start instead of leaving two copies.
+- **Crash-safe moves.** Category moves, renames and merges are journaled. On
+  restart, a merge only removes its source after the target has all its facts
+  and the source's former id.
 - **Atomic writes.** Every write goes through a temp file and rename; there is no
   window where a note is half-written.
+- **Scoped reads.** `memoria_read` only follows paths inside the memory library;
+  transcript window reads refuse paths or symlinks outside configured roots.
 - **Secrets:** memoria does not scan for credentials, and the learn prompt tells
   the model not to store them. If you keep secrets in the store anyway, remember
   that recall may surface them in model context — treat the store like your shell
@@ -583,7 +604,7 @@ a burst of edits costs one refresh.
 
 ```bash
 npm install            # dev-only: pi host packages + typescript
-npm test               # 144 tests, node:test, no build step
+npm test               # node:test, no build step
 npm run typecheck      # tsc --noEmit
 npm run eval           # recall@1/@5/MRR over the fixture corpus
 npm run bench          # latency at 1k and 5k notes
@@ -630,8 +651,8 @@ src/commands.ts     /memoria subcommands
    `"optional": true` in `peerDependenciesMeta`, keeping them in
    `devDependencies` for local tests only. Without that, npm installs a ~450 MB
    duplicate of pi into the package.
-4. Tag releases (`git tag v0.1.1 && git push --tags`) and install by tag:
-   `pi install git:github.com/<you>/pi-memoria@v0.1.1`.
+4. Tag releases (`git tag v<version> && git push --tags`) and install by tag:
+   `pi install git:github.com/<you>/pi-memoria@v<version>`.
 5. `npm pack --dry-run` should list only `index.ts`, `src/**`, `skills/**`,
    `README.md`, `LICENSE` and `package.json`.
 

package/index.ts

@@ -25,47 +25,53 @@ 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 } from "./src/recall.ts";
+import { RECALL_CUSTOM_TYPE, buildRecallParts, renderRecallBlock, renderStatusLine, renderSystemSection, ripgrepNotice } from "./src/recall.ts";
 import { buildTranscriptText, harvestSession } from "./src/learn.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 }> => {
@@ -137,6 +143,11 @@ export default function memoria(pi: ExtensionAPI) {
 			if (tokens.length < 2 && !/\d/.test(prompt)) return undefined;
 			const parts = buildRecallParts(prompt, recentPrompts, memoria_.config.autoRecallLastTurns, memoria_.config.autoRecallPriorWeight);
 			const result = await memoria_.recall(oneLine(prompt, 400), { limit: memoria_.config.autoRecallLimit, scope: "all", parts });
+			const rgNotice = ripgrepNotice(result.sessionStats?.ripgrep);
+			if (rgNotice && !ripgrepWarned) {
+				ripgrepWarned = true;
+				ctx.ui.notify(`memoria: ${rgNotice}.`, "warning");
+			}
 			recentPrompts = [...recentPrompts, prompt].slice(-RECENT_PROMPT_LIMIT);
 			const hits = result.hits.filter((hit) => hit.score >= memoria_.config.autoRecallMinScore);
 			// Nothing in the library? Show what earlier conversations said instead
@@ -230,13 +241,14 @@ export default function memoria(pi: ExtensionAPI) {
 		} catch {
 			// Shutdown must never throw.
 		}
-		await runtime?.flushUsageNow().catch(() => {});
-		await runtime?.dispose().catch(() => {});
-		runtime = undefined;
-		runtimeCwd = undefined;
-		initPromise = undefined;
-		hotCache = undefined;
-		recentPrompts = [];
+		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.1",
+	"version": "0.1.3",
 	"description": "Agent-first long-term memory for pi: a categorized markdown library with automatic, sub-millisecond recall.",
 	"type": "module",
 	"license": "MIT",

package/skills/memoria-sessions/SKILL.md

@@ -30,6 +30,9 @@ memoria_sessions { action: "search", query: "niri scale", include_tools: true, s
 - Every hit comes with a `file:` and `line:`, its role, project and score. If
   nothing matches, the result says how many sessions and messages were scanned —
   quote that when reporting, and try different wording before concluding.
+- If the result says ripgrep is not installed (or that a scan was `partial`),
+  the search used the slower built-in scanner and may not have reached the
+  oldest sessions. Say so when coverage matters, and prefer narrower queries.
 
 The extension also searches transcripts **automatically** when the memory
 library returns nothing and `sessionFallback` is on. That injection is a hint,

package/src/commands.ts

@@ -13,6 +13,7 @@ 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";
@@ -25,7 +26,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" },
@@ -182,12 +183,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;
@@ -271,7 +273,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\``,
 							);
 						}
 					}
@@ -318,11 +320,12 @@ export function registerMemoriaCommand(pi: ExtensionAPI, getRuntime: RuntimeGett
 					});
 					const stats = result.stats;
 					const header = `${result.hits.length} match${result.hits.length === 1 ? "" : "es"} in ${stats.files} sessions / ${stats.messages} messages (${result.tookMs}ms${stats.partial ? ", partial scan" : ""}${stats.skipped > 0 ? `, ${stats.skipped} unreadable records skipped` : ""}).`;
+					const notice = ripgrepNotice(stats.ripgrep);
 					if (result.hits.length === 0) {
-						emit(pi, `memoria sessions: ${oneLine(query, 60)}`, `${header}\n\nNo saved conversation matched. Try other wording, a name or a date.`);
+						emit(pi, `memoria sessions: ${oneLine(query, 60)}`, `${header}${notice ? `\n\n_Note: ${notice}._` : ""}\n\nNo saved conversation matched. Try other wording, a name or a date.`);
 						return;
 					}
-					const lines = [header, "", "_Evidence from raw transcripts, not curated memory._", ""];
+					const lines = [header, ...(notice ? [`_Note: ${notice}._`] : []), "", "_Evidence from raw transcripts, not curated memory._", ""];
 					for (const hit of result.hits) {
 						lines.push(`- **[${hit.role}] ${formatSessionTime(hit.timestamp)}** · ${hit.projectName} · score ${hit.score}${hit.exact ? " · exact" : ""}`);
 						lines.push(`  ${oneLine(hit.excerpt, 400)}`);

package/src/config.ts

@@ -74,6 +74,7 @@ export const DEFAULT_CONFIG: MemoriaConfig = {
 	sessionExcerptChars: 400,
 	sessionCacheBytes: 32 * 1024 * 1024,
 	sessionIncludeTools: false,
+	sessionRipgrep: true,
 };
 
 /** Filesystem context used to resolve store paths. */
@@ -168,6 +169,7 @@ function coerceConfig(raw: unknown): Partial<MemoriaConfig> {
 	if (number(input.sessionScanMs) !== undefined) out.sessionScanMs = Math.max(50, Math.min(60_000, number(input.sessionScanMs)!));
 	if (number(input.sessionExcerptChars) !== undefined) out.sessionExcerptChars = Math.max(80, Math.min(4000, number(input.sessionExcerptChars)!));
 	if (number(input.sessionCacheBytes) !== undefined) out.sessionCacheBytes = Math.max(0, number(input.sessionCacheBytes)!);
+	if (bool(input.sessionRipgrep) !== undefined) out.sessionRipgrep = bool(input.sessionRipgrep);
 	if (Array.isArray(input.sessionRoots)) out.sessionRoots = input.sessionRoots.filter((item): item is string => typeof item === "string");
 	if (input.synonyms && typeof input.synonyms === "object" && !Array.isArray(input.synonyms)) {
 		const table: Record<string, string[]> = {};

package/src/index-engine.ts

@@ -150,6 +150,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 +239,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 +338,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 +351,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 +431,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 +455,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 +524,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 +559,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 +844,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 +953,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;

package/src/recall.ts

@@ -87,11 +87,25 @@ export function renderSystemSection(input: SystemSectionInput): string {
  * Sessions are raw evidence rather than curated memory, so the block says so
  * explicitly and points at the verification step.
  */
-export function renderSessionFallback(hits: SessionHit[], stats?: Pick<SessionScanStats, "files" | "messages" | "partial">): string {
+/**
+ * Warn that transcript search fell back to the slower built-in scanner.
+ *
+ * `undefined` for every status where the fallback was intentional (`disabled`)
+ * or the accelerator was simply not applicable (`unsupported`, `skipped`).
+ */
+export function ripgrepNotice(status: SessionScanStats["ripgrep"]): string | undefined {
+	if (status === "missing") return "ripgrep is not installed, so transcripts are searched with the slower built-in scanner (large histories may be only partially covered)";
+	if (status === "error") return "ripgrep failed, so transcripts are searched with the slower built-in scanner";
+	return undefined;
+}
+
+export function renderSessionFallback(hits: SessionHit[], stats?: Pick<SessionScanStats, "files" | "messages" | "partial" | "ripgrep">): string {
 	const lines: string[] = [];
 	lines.push(
 		`No memory note matched. Found ${hits.length} possibly relevant message${hits.length === 1 ? "" : "s"} in saved earlier conversations${stats ? ` (scanned ${stats.files} sessions, ${stats.messages} messages${stats.partial ? ", partial scan" : ""})` : ""}:`,
 	);
+	const notice = stats ? ripgrepNotice(stats.ripgrep) : undefined;
+	if (notice) lines.push(`Note: ${notice}.`);
 	for (const hit of hits) {
 		lines.push(`- [${hit.role}, ${formatSessionTime(hit.timestamp)}] ${hit.projectName}: ${oneLine(hit.excerpt, 320)}`);
 		lines.push(`  file: ${hit.path}:${hit.line} (score ${hit.score}, matched: ${hit.matched.join(", ") || "-"})`);
@@ -113,7 +127,7 @@ export interface RecallRenderInput {
 	timeWindow?: TimeWindow;
 	/** Transcript excerpts returned when the library had no match. */
 	sessionHits?: SessionHit[];
-	sessionStats?: Pick<SessionScanStats, "files" | "messages" | "partial">;
+	sessionStats?: Pick<SessionScanStats, "files" | "messages" | "partial" | "ripgrep">;
 }
 
 /** Render the per-prompt recall block injected as a custom message. */