pi-memoria 0.1.1 → 0.1.2

package/README.md

@@ -409,6 +409,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 +496,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

package/index.ts

@@ -25,7 +25,7 @@ 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";
@@ -39,6 +39,8 @@ export default function memoria(pi: ExtensionAPI) {
 	let initPromise: Promise<void> | undefined;
 	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;
@@ -137,6 +139,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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-memoria",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"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";
@@ -318,11 +319,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/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. */

package/src/runtime.ts

@@ -439,9 +439,12 @@ export class MemoriaRuntime {
 				// search budget; the explicit tool call can take longer.
 				budgetMs: Math.min(this.config.sessionScanMs, 400),
 			}).catch(() => undefined);
-			if (fallback && fallback.hits.length > 0) {
-				result.sessionHits = fallback.hits;
+			if (fallback) {
+				// Stats are kept even with no hits: they carry the ripgrep status the
+				// caller warns about, and the renderers only show the excerpts when
+				// `sessionHits` is non-empty.
 				result.sessionStats = fallback.stats;
+				if (fallback.hits.length > 0) result.sessionHits = fallback.hits;
 			}
 		}
 		const wanted = options.rerank ?? this.config.rerank;
@@ -583,12 +586,15 @@ export class MemoriaRuntime {
 	/** Lazily create the transcript store (keys on config + agent dir). */
 	private sessions(): SessionStore {
 		const roots = this.sessionRoots();
-		const key = `${roots.join("|")}::${this.config.sessionCacheBytes}::${this.config.sessionExcerptChars}`;
+		const key = `${roots.join("|")}::${this.config.sessionCacheBytes}::${this.config.sessionExcerptChars}::${this.config.sessionRipgrep}`;
 		if (!this.sessionStore || this.sessionStoreKey !== key) {
 			this.sessionStore = new SessionStore({
 				roots,
 				cacheBytes: this.config.sessionCacheBytes,
 				excerptChars: this.config.sessionExcerptChars,
+				rgPath: this.config.sessionRipgrep ? undefined : null,
+				// pi ships ripgrep under <agent dir>/bin and puts it on PATH.
+				rgCandidates: [join(this.pathContext.agentDir, "bin", process.platform === "win32" ? "rg.exe" : "rg")],
 			});
 			this.sessionStoreKey = key;
 		}

package/src/sessions.ts

@@ -23,15 +23,20 @@
  *    paths outside the configured roots.
  */
 
-import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { accessSync, constants, existsSync } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, join, relative, resolve, sep } from "node:path";
+import { basename, delimiter, join, relative, resolve, sep } from "node:path";
 import { isCjkChar, stem, tokenize } from "./tokenize.ts";
 import { oneLine, truncateChars } from "./util.ts";
 import type { SessionFile, SessionHit, SessionMessage, SessionReadResult, SessionScanStats, SessionSearchOptions, SessionSearchResult, SessionWindowMessage } from "./types.ts";
 
 /** Hard cap on a single extracted message, to keep the cache useful. */
 export const MAX_SESSION_MESSAGE_CHARS = 4000;
+/** Upper bound on ripgrep's file list, so a pathological match set cannot exhaust memory. */
+const MAX_RG_OUTPUT_CHARS = 16 * 1024 * 1024;
+/** ripgrep is killed after this long, even when the search itself has no budget. */
+const MAX_RG_TIMEOUT_MS = 10_000;
 /** Directories deeper than this under a root are ignored. */
 const MAX_WALK_DEPTH = 4;
 /** Files larger than this are skipped rather than read into memory. */
@@ -182,6 +187,53 @@ function cacheKey(path: string, includeTools: boolean): string {
 	return `${path}::${includeTools ? "all" : "core"}`;
 }
 
+/** Characters a ripgrep needle may contain: ASCII alphanumerics, `_` and CJK. */
+function needleSafe(word: string): boolean {
+	if (!word) return false;
+	for (const ch of word) {
+		if (/[a-z0-9_]/.test(ch) || isCjkChar(ch)) continue;
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Fixed-string needles for the ripgrep prefilter, or `undefined` when the query
+ * cannot be proven to be covered by them.
+ *
+ * A file is skipped only when ripgrep finds none of these strings, so they must
+ * cover everything the scorer can match: every scoring term (`tokenize` already
+ * lowercases) and — because a phrase match implies all of its words — the
+ * longest safe word of each exact phrase. Terms ending in `y` also probe the
+ * `…ies` surface form: that is the one stemmer rule which is not
+ * prefix-preserving, so query "party" must also match "parties". Non-ASCII,
+ * non-CJK words disable the prefilter rather than risk a normalization
+ * mismatch.
+ */
+export function ripgrepNeedles(phrases: string[], terms: string[]): string[] | undefined {
+	const needles = new Set<string>();
+	const add = (word: string): void => {
+		const normalized = word.toLowerCase();
+		if (!needleSafe(normalized)) return;
+		needles.add(normalized);
+		if (normalized.length >= 4 && normalized.endsWith("y")) needles.add(`${normalized.slice(0, -1)}ies`);
+	};
+	for (const term of terms) {
+		if (!needleSafe(term.toLowerCase())) return undefined;
+		add(term);
+	}
+	for (const phrase of phrases) {
+		// One word of a phrase is enough to witness it: a phrase match implies
+		// every word is present. The longest safe word is the most selective, and
+		// a short but common witness ("a", "out") would match nearly everything.
+		const words = phrase.split(" ").filter((word) => needleSafe(word.toLowerCase()));
+		if (words.length === 0) return undefined;
+		add(words.reduce((best, word) => (word.length > best.length ? word : best)));
+	}
+	if (needles.size === 0 || needles.size > 64) return undefined;
+	return [...needles];
+}
+
 export interface SessionStoreOptions {
 	/** Transcript roots to scan, in priority order. */
 	roots: string[];
@@ -189,6 +241,14 @@ export interface SessionStoreOptions {
 	cacheBytes?: number;
 	/** Default excerpt size. */
 	excerptChars?: number;
+	/**
+	 * Ripgrep binary used to find candidate transcripts before parsing. `null`
+	 * disables the accelerator, a path uses exactly that binary, and `undefined`
+	 * auto-detects from `rgCandidates` and then `PATH`.
+	 */
+	rgPath?: string | null;
+	/** Locations checked before `PATH` when auto-detecting (e.g. pi's bin dir). */
+	rgCandidates?: string[];
 }
 
 interface CachedFile {
@@ -206,14 +266,114 @@ interface CachedFile {
 export class SessionStore {
 	readonly roots: string[];
 	private cache = new Map<string, CachedFile>();
+	/** In-flight parses, so concurrent searches share one read/parse per file. */
+	private inflight = new Map<string, Promise<{ entry: CachedFile | undefined; skipped: number; rawBytes: number }>>();
 	private cacheBytes = 0;
 	private cacheBudget: number;
 	private excerptChars: number;
+	private rgPathOption: string | null | undefined;
+	private rgCandidates: string[];
+	/** Resolved once per store: a path, `null` (unavailable/disabled), or unknown. */
+	private rgLocated: string | null | undefined;
 
 	constructor(options: SessionStoreOptions) {
 		this.roots = options.roots;
 		this.cacheBudget = Math.max(0, options.cacheBytes ?? 32 * 1024 * 1024);
 		this.excerptChars = Math.max(80, options.excerptChars ?? 400);
+		this.rgPathOption = options.rgPath;
+		this.rgCandidates = options.rgCandidates ?? [];
+	}
+
+	/** Resolve the ripgrep binary once; `null` means the accelerator is off. */
+	private locateRipgrep(): string | null {
+		if (this.rgLocated !== undefined) return this.rgLocated;
+		const candidates: string[] = [];
+		if (typeof this.rgPathOption === "string") {
+			candidates.push(this.rgPathOption);
+		} else if (this.rgPathOption === undefined) {
+			candidates.push(...this.rgCandidates);
+			for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+				if (!dir) continue;
+				candidates.push(join(dir, process.platform === "win32" ? "rg.exe" : "rg"));
+			}
+		}
+		for (const candidate of candidates) {
+			try {
+				accessSync(candidate, constants.X_OK);
+				this.rgLocated = candidate;
+				return candidate;
+			} catch {
+				// Try the next location.
+			}
+		}
+		this.rgLocated = null;
+		return null;
+	}
+
+	/**
+	 * List the transcripts containing at least one needle with ripgrep.
+	 *
+	 * Returns matching paths, `"missing"` when no usable binary exists, or
+	 * `"error"` when ripgrep failed, timed out, or produced more output than the
+	 * caller can use. Both non-result outcomes make the caller fall back to the
+	 * full parse, so correctness never depends on the accelerator.
+	 */
+	private async ripgrepFiles(needles: string[], timeoutMs: number): Promise<Set<string> | "missing" | "error"> {
+		const binary = this.locateRipgrep();
+		if (!binary) return "missing";
+		const roots = this.roots.filter((root) => existsSync(root));
+		if (roots.length === 0) return new Set<string>();
+		const args = ["--files-with-matches", "--ignore-case", "--fixed-strings", "--no-messages", "--no-ignore", "--text", "--iglob", "*.jsonl"];
+		for (const needle of needles) args.push("-e", needle);
+		args.push("--", ...roots);
+		return await new Promise<Set<string> | "error">((settle) => {
+			let child;
+			try {
+				child = spawn(binary, args, { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+			} catch {
+				settle("error");
+				return;
+			}
+			let out = "";
+			let settled = false;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const finish = (value: Set<string> | "error"): void => {
+				if (settled) return;
+				settled = true;
+				if (timer) clearTimeout(timer);
+				settle(value);
+			};
+			const kill = (): void => {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// Already gone.
+				}
+			};
+			timer = setTimeout(() => {
+				kill();
+				finish("error");
+			}, timeoutMs);
+			child.stdout?.setEncoding("utf8");
+			child.stdout?.on("data", (chunk: string) => {
+				out += chunk;
+				if (out.length > MAX_RG_OUTPUT_CHARS) {
+					kill();
+					finish("error");
+				}
+			});
+			child.on("error", () => finish("error"));
+			child.on("close", (code) => {
+				if (code === 1) return finish(new Set<string>());
+				if (code !== 0) return finish("error");
+				const paths = new Set<string>();
+				for (const line of out.split("\n")) {
+					const path = line.trim();
+					if (path) paths.add(resolve(path));
+				}
+				finish(paths);
+			});
+		});
 	}
 
 	/** True when at least one root exists on disk. */
@@ -296,26 +456,18 @@ export class SessionStore {
 		}
 	}
 
-	/** Parse a transcript, reusing the cache when mtime and size are unchanged. */
-	async messagesFor(file: SessionFile, includeTools: boolean): Promise<{ messages: SessionMessage[]; cached: boolean; skipped: number; rawBytes: number; cwd?: string }> {
-		const key = cacheKey(file.path, includeTools);
-		// A full parse can serve the default view, but the default view cannot
-		// serve an includeTools search (it never extracted the tool text).
-		const cached = includeTools
-			? this.cache.get(cacheKey(file.path, true))
-			: (this.cache.get(cacheKey(file.path, false)) ?? this.cache.get(cacheKey(file.path, true)));
-		if (cached && cached.mtimeMs === file.mtimeMs && cached.size === file.size) {
-			// Touch for LRU ordering.
-			this.cache.delete(key);
-			this.cache.set(key, cached);
-			const visible = includeTools ? cached.messages : cached.messages.filter((message) => message.role !== "tool" && message.role !== "summary");
-			return { messages: visible, cached: true, skipped: 0, rawBytes: cached.rawBytes, cwd: cached.header.cwd };
-		}
+	/** Default-view projection of a parsed file (tool plumbing hidden unless asked). */
+	private view(entry: CachedFile, includeTools: boolean): SessionMessage[] {
+		return includeTools ? entry.messages : entry.messages.filter((message) => message.role !== "tool" && message.role !== "summary");
+	}
+
+	/** Read and parse one transcript, populating the cache (no in-flight handling). */
+	private async parseFile(file: SessionFile, includeTools: boolean): Promise<{ entry: CachedFile | undefined; skipped: number; rawBytes: number }> {
 		let raw: string;
 		try {
 			raw = await readFile(file.path, "utf8");
 		} catch {
-			return { messages: [], cached: false, skipped: 1, rawBytes: 0 };
+			return { entry: undefined, skipped: 1, rawBytes: 0 };
 		}
 		const messages: SessionMessage[] = [];
 		let skipped = 0;
@@ -380,8 +532,51 @@ export class SessionStore {
 			header: { cwd, startedAt: headerStarted || file.startedAt },
 		};
 		this.put(parsed, includeTools);
-		const visible = includeTools ? messages : messages.filter((message) => message.role !== "tool" && message.role !== "summary");
-		return { messages: visible, cached: false, skipped, rawBytes: raw.length, cwd };
+		return { entry: parsed, skipped, rawBytes: raw.length };
+	}
+
+	/**
+	 * Parse a transcript, reusing the cache when mtime and size are unchanged.
+	 *
+	 * Concurrent searches (the common case, since one assistant turn can issue
+	 * several `memoria_sessions` calls at once) share a single in-flight parse
+	 * per file, so parallel searches never multiply read/parse work on one event
+	 * loop and never lose older files to another search's wall-clock budget.
+	 */
+	async messagesFor(file: SessionFile, includeTools: boolean): Promise<{ messages: SessionMessage[]; cached: boolean; skipped: number; rawBytes: number; cwd?: string }> {
+		const key = cacheKey(file.path, includeTools);
+		const allKey = cacheKey(file.path, true);
+		// A full parse can serve the default view, but the default view cannot
+		// serve an includeTools search (it never extracted the tool text).
+		const cached = includeTools ? this.cache.get(allKey) : (this.cache.get(cacheKey(file.path, false)) ?? this.cache.get(allKey));
+		if (cached && cached.mtimeMs === file.mtimeMs && cached.size === file.size) {
+			// Touch for LRU ordering, under the key the entry actually lives on.
+			for (const candidate of [key, allKey]) {
+				if (this.cache.get(candidate) === cached) {
+					this.cache.delete(candidate);
+					this.cache.set(candidate, cached);
+					break;
+				}
+			}
+			return { messages: this.view(cached, includeTools), cached: true, skipped: 0, rawBytes: cached.rawBytes, cwd: cached.header.cwd };
+		}
+		// Join an in-flight parse when it can answer this request: the same
+		// variant always, or a full parse for a default-view request.
+		const pending = this.inflight.get(key) ?? (includeTools ? undefined : this.inflight.get(allKey));
+		if (pending) {
+			const { entry, skipped, rawBytes } = await pending;
+			if (!entry) return { messages: [], cached: false, skipped, rawBytes };
+			return { messages: this.view(entry, includeTools), cached: false, skipped, rawBytes: entry.rawBytes, cwd: entry.header.cwd };
+		}
+		const promise = this.parseFile(file, includeTools);
+		this.inflight.set(key, promise);
+		try {
+			const { entry, skipped, rawBytes } = await promise;
+			if (!entry) return { messages: [], cached: false, skipped, rawBytes };
+			return { messages: this.view(entry, includeTools), cached: false, skipped, rawBytes: entry.rawBytes, cwd: entry.header.cwd };
+		} finally {
+			this.inflight.delete(key);
+		}
 	}
 
 	private put(entry: CachedFile, includeTools: boolean): void {
@@ -448,6 +643,38 @@ export class SessionStore {
 		// could not be completed is reported as partial.
 		const listing = await this.listFiles({ deadline: budgetMs > 0 ? started + budgetMs : undefined });
 		if (listing.truncated) stats.partial = true;
+
+		// Ripgrep narrows the parse set to files that contain at least one query
+		// needle. Files outside that set are provably match-free, so they count as
+		// scanned without being read. Without a usable binary (or a query we cannot
+		// prefilter safely) every listed file is parsed exactly as before.
+		let parseFilter: Set<string> | undefined;
+		if (this.rgPathOption === null) {
+			stats.ripgrep = "disabled";
+		} else {
+			const needles = ripgrepNeedles(phrases, scoringTerms);
+			if (!needles) {
+				stats.ripgrep = "unsupported";
+			} else {
+				const remaining = budgetMs > 0 ? started + budgetMs - performance.now() : Number.POSITIVE_INFINITY;
+				if (listing.files.length === 0 || remaining <= 0) {
+					stats.ripgrep = "skipped";
+				} else {
+					// The accelerator is fast, but give it a hard cap so a hung binary
+					// or a pathological mount cannot stall a prompt. Overrunning the
+					// remaining budget only makes the parse below report `partial`.
+					const timeout = Number.isFinite(remaining) ? Math.min(MAX_RG_TIMEOUT_MS, Math.max(500, Math.round(remaining * 4))) : MAX_RG_TIMEOUT_MS;
+					const found = await this.ripgrepFiles(needles, timeout);
+					if (found === "missing") stats.ripgrep = "missing";
+					else if (found === "error") stats.ripgrep = "error";
+					else {
+						parseFilter = found;
+						stats.ripgrep = "used";
+					}
+				}
+			}
+		}
+
 		const candidates: Candidate[] = [];
 		for (const file of listing.files) {
 			if (since !== undefined && file.startedAt < since) continue;
@@ -458,6 +685,11 @@ export class SessionStore {
 				stats.partial = true;
 				break;
 			}
+			if (parseFilter && !parseFilter.has(resolve(file.path))) {
+				stats.files += 1;
+				stats.bytes += file.size;
+				continue;
+			}
 			const parsed = await this.messagesFor(file, includeTools);
 			stats.files += 1;
 			stats.bytes += parsed.rawBytes;

package/src/tools.ts

@@ -13,10 +13,10 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { Text } from "@earendil-works/pi-tui";
 import type { MemoriaRuntime } from "./runtime.ts";
 import { readStoreFile } from "./store.ts";
-import { renderSessionFallback } from "./recall.ts";
+import { renderSessionFallback, ripgrepNotice } from "./recall.ts";
 import { formatSessionTime } from "./sessions.ts";
 import { atomicWriteFile, oneLine, truncateChars } from "./util.ts";
-import type { Priority, Scope, SearchHit } from "./types.ts";
+import type { Priority, Scope, SearchHit, SessionScanStats } from "./types.ts";
 
 /** Inline export/import payload cap; larger dumps must use a file path. */
 const MAX_INLINE_TRANSFER_CHARS = 60_000;
@@ -762,17 +762,19 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 				userOnly: params.user_only,
 			});
 			const stats = result.stats;
+			const notice = ripgrepNotice(stats.ripgrep);
 			if (result.hits.length === 0) {
 				const where = stats.roots.length > 0 ? stats.roots.join(", ") : "(no session directory found)";
 				return {
 					content: text(
-						`No saved conversation matched "${oneLine(params.query, 120)}".\nSearched ${where}: ${stats.files} sessions, ${stats.messages} messages (${(stats.bytes / 1_048_576).toFixed(1)} MB) in ${result.tookMs}ms${stats.partial ? " (partial scan: budget reached, results may be incomplete)" : ""}${stats.skipped > 0 ? `, skipped ${stats.skipped} unreadable records` : ""}.\nTry different wording, a name or date, or include_tools: true for tool output and compaction summaries.`,
+						`No saved conversation matched "${oneLine(params.query, 120)}".\nSearched ${where}: ${stats.files} sessions, ${stats.messages} messages (${(stats.bytes / 1_048_576).toFixed(1)} MB) in ${result.tookMs}ms${stats.partial ? " (partial scan: budget reached, results may be incomplete)" : ""}${stats.skipped > 0 ? `, skipped ${stats.skipped} unreadable records` : ""}.${notice ? `\nNote: ${notice}.` : ""}\nTry different wording, a name or date, or include_tools: true for tool output and compaction summaries.`,
 					),
-					details: { kind: "session", count: 0, partial: stats.partial },
+					details: { kind: "session", count: 0, partial: stats.partial, ripgrep: stats.ripgrep },
 				};
 			}
 			const lines = [
 				`${result.hits.length} match${result.hits.length === 1 ? "" : "es"} for "${oneLine(params.query, 120)}" in saved conversations (${result.tookMs}ms, ${stats.files} sessions / ${stats.messages} messages scanned${stats.cachedFiles > 0 ? `, ${stats.cachedFiles} cached` : ""}${stats.partial ? ", PARTIAL: budget reached" : ""}).`,
+				...(notice ? [`Note: ${notice}.`] : []),
 				"Evidence from raw transcripts, not curated memory.",
 				"",
 			];
@@ -788,7 +790,7 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 			);
 			return {
 				content: text(lines.join("\n")),
-				details: { kind: "session", count: result.hits.length, partial: stats.partial },
+				details: { kind: "session", count: result.hits.length, partial: stats.partial, ripgrep: stats.ripgrep },
 			};
 		},
 		renderCall(args, theme) {
@@ -796,10 +798,11 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 			return new Text(theme.fg("toolTitle", theme.bold("memoria_sessions ")) + theme.fg("accent", label), 0, 0);
 		},
 		renderResult(result, options, theme) {
-			const details = result.details as { kind?: string; count?: number; line?: number; partial?: boolean } | undefined;
+			const details = result.details as { kind?: string; count?: number; line?: number; partial?: boolean; ripgrep?: SessionScanStats["ripgrep"] } | undefined;
 			if (details?.kind === "session_read") return new Text(theme.fg("success", `✓ window at line ${details.line ?? "?"}`), 0, 0);
 			if (!details?.count) return new Text(theme.fg("warning", details?.partial ? "no matches (partial scan)" : "no matches"), 0, 0);
-			const text = theme.fg("success", `✓ ${details.count} past-session matches`) + theme.fg("dim", details.partial ? " (partial)" : "");
+			const slow = details?.ripgrep === "missing" || details?.ripgrep === "error";
+			const text = theme.fg("success", `✓ ${details.count} past-session matches`) + theme.fg("dim", `${details.partial ? " (partial)" : ""}${slow ? " (slower fallback: no ripgrep)" : ""}`);
 			return new Text(text + (options.expanded ? `\n${theme.fg("dim", "see output for excerpts and file:line")}` : ""), 0, 0);
 		},
 	});

package/src/types.ts

@@ -430,6 +430,8 @@ export interface MemoriaConfig {
 	sessionCacheBytes: number;
 	/** Include tool calls, tool results and compaction summaries by default. */
 	sessionIncludeTools: boolean;
+	/** Use a ripgrep prefilter to skip match-free transcripts when `rg` exists. */
+	sessionRipgrep: boolean;
 }
 
 /* ------------------------------------------------------------------ */
@@ -497,6 +499,18 @@ export interface SessionHit {
 	excerpt: string;
 }
 
+/**
+ * How the ripgrep candidate prefilter contributed to a transcript scan.
+ *
+ * `used` means ripgrep listed the files containing at least one query needle
+ * and the rest were skipped without parsing. The others are fallbacks so the
+ * search still works without a usable `rg`:
+ * `missing` (no binary), `error` (spawn failure/timeout/bad exit),
+ * `disabled` (config), `unsupported` (query cannot be prefiltered safely),
+ * `skipped` (no budget left to try).
+ */
+export type SessionRipgrepStatus = "used" | "missing" | "error" | "disabled" | "unsupported" | "skipped";
+
 export interface SessionScanStats {
 	roots: string[];
 	files: number;
@@ -508,6 +522,8 @@ export interface SessionScanStats {
 	skipped: number;
 	/** True when the budget stopped the scan before every file was read. */
 	partial: boolean;
+	/** Ripgrep prefilter outcome, when a scan ran. */
+	ripgrep?: SessionRipgrepStatus;
 }
 
 export interface SessionSearchResult {