agentic-browser 1.2.0 → 1.3.0

package/README.md

@@ -92,10 +92,12 @@ Default profile locations per platform:
 
 These options can also be set via environment variables (CLI flags take precedence):
 
-| Variable                       | Example                        | Description                     |
-| ------------------------------ | ------------------------------ | ------------------------------- |
-| `AGENTIC_BROWSER_CDP_URL`      | `http://127.0.0.1:9222`       | Connect to a running Chrome     |
-| `AGENTIC_BROWSER_USER_PROFILE` | `default` or an absolute path  | Launch with a real profile      |
+| Variable                       | Example                        | Description                          |
+| ------------------------------ | ------------------------------ | ------------------------------------ |
+| `AGENTIC_BROWSER_CDP_URL`      | `http://127.0.0.1:9222`       | Connect to a running Chrome          |
+| `AGENTIC_BROWSER_USER_PROFILE` | `default` or an absolute path  | Launch with a real profile           |
+| `AGENTIC_BROWSER_HEADLESS`     | `true`                         | Run Chrome in headless mode          |
+| `AGENTIC_BROWSER_USER_AGENT`   | `MyBot/1.0`                    | Override the browser user-agent      |
 
 ## Agent Commands (Recommended for LLMs)
 
@@ -105,6 +107,8 @@ The `agent` subcommand manages session state, auto-restarts on disconnect, gener
 agentic-browser agent start
 agentic-browser agent start --cdp-url http://127.0.0.1:9222
 agentic-browser agent start --user-profile default
+agentic-browser agent start --headless
+agentic-browser agent start --user-agent "MyBot/1.0"
 agentic-browser agent status
 agentic-browser agent run navigate '{"url":"https://example.com"}'
 agentic-browser agent run interact '{"action":"click","selector":"#login"}'
@@ -184,6 +188,8 @@ For direct control without session state management:
 agentic-browser session:start
 agentic-browser session:start --cdp-url http://127.0.0.1:9222
 agentic-browser session:start --user-profile default
+agentic-browser session:start --headless
+agentic-browser session:start --user-agent "MyBot/1.0"
 ```
 
 ### 2. Read Session Status

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as createCliRuntime } from "../runtime-D6awVhGy.mjs";
+import { r as createCliRuntime } from "../runtime-Dvmv5Xi_.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -243,9 +243,11 @@ async function main() {
 	const runtime = createCliRuntime();
 	const program = new Command();
 	program.name("agentic-browser").description("Agentic browser CLI");
-	program.command("session:start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").action(async (options) => {
+	program.command("session:start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").option("--headless", "run Chrome in headless mode (no visible window)").option("--user-agent <string>", "override the browser user-agent string").action(async (options) => {
 		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
 		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
+		if (options.headless) runtime.context.config.headless = true;
+		if (options.userAgent) runtime.context.config.userAgent = options.userAgent;
 		const result = await runSessionStart(runtime, { browser: "chrome" });
 		console.log(JSON.stringify(result));
 	});
@@ -310,9 +312,11 @@ async function main() {
 		console.log(JSON.stringify(result));
 	});
 	const agent = program.command("agent").description("Stateful agent wrapper with session persistence and auto-retry");
-	agent.command("start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").action(async (options) => {
+	agent.command("start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").option("--headless", "run Chrome in headless mode (no visible window)").option("--user-agent <string>", "override the browser user-agent string").action(async (options) => {
 		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
 		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
+		if (options.headless) runtime.context.config.headless = true;
+		if (options.userAgent) runtime.context.config.userAgent = options.userAgent;
 		const result = await agentStart(runtime);
 		console.log(JSON.stringify(result));
 	});

package/dist/index.mjs

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-D6awVhGy.mjs";
+import { i as createMockAgenticBrowserCore, n as createAgenticBrowserCore, t as AgenticBrowserCore } from "./runtime-Dvmv5Xi_.mjs";
 
 export { AgenticBrowserCore, createAgenticBrowserCore, createMockAgenticBrowserCore };

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-D6awVhGy.mjs";
+import { n as createAgenticBrowserCore } from "../runtime-Dvmv5Xi_.mjs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/{runtime-D6awVhGy.mjs → runtime-Dvmv5Xi_.mjs}

@@ -101,12 +101,34 @@ async function getJson(url) {
 	if (!response.ok) throw new Error(`HTTP ${response.status}: ${url}`);
 	return await response.json();
 }
+/** Check if the debug port is accepting TCP connections (faster than an HTTP fetch). */
+function probePort(port) {
+	return new Promise((resolve) => {
+		const socket = net.createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve(true);
+		});
+		socket.once("error", () => {
+			socket.destroy();
+			resolve(false);
+		});
+	});
+}
 async function waitForDebugger(port) {
-	for (let i = 0; i < 60; i += 1) try {
-		await getJson(`http://127.0.0.1:${port}/json/version`);
-		return;
-	} catch {
-		await new Promise((resolve) => setTimeout(resolve, 250));
+	const maxMs = 15e3;
+	const start = Date.now();
+	let delay = 50;
+	while (Date.now() - start < maxMs) {
+		if (await probePort(port)) try {
+			await getJson(`http://127.0.0.1:${port}/json/version`);
+			return;
+		} catch {}
+		await new Promise((resolve) => setTimeout(resolve, delay));
+		delay = Math.min(delay * 2, 250);
 	}
 	throw new Error("Chrome debug endpoint did not become ready in time");
 }
@@ -128,6 +150,15 @@ async function createTarget(cdpUrl, url = "about:blank") {
 	} catch {}
 	return await ensurePageWebSocketUrl(cdpUrl);
 }
+async function applyUserAgent(targetWsUrl, userAgent) {
+	const conn = await CdpConnection.connect(targetWsUrl);
+	try {
+		await conn.send("Network.enable");
+		await conn.send("Network.setUserAgentOverride", { userAgent });
+	} finally {
+		conn.close();
+	}
+}
 async function evaluateExpression(targetWsUrl, expression) {
 	const conn = await CdpConnection.connect(targetWsUrl);
 	try {
@@ -199,13 +230,14 @@ var ChromeCdpBrowserController = class {
 	closeConnection(targetWsUrl) {
 		this.dropConnection(targetWsUrl);
 	}
-	async connect(cdpUrl) {
+	async connect(cdpUrl, options) {
 		const parsed = new URL(cdpUrl);
 		const port = Number.parseInt(parsed.port, 10);
 		if (!port) throw new Error(`Invalid CDP URL: could not extract port from ${cdpUrl}`);
 		await waitForDebugger(port);
 		const targetWsUrl = await createTarget(cdpUrl);
 		await evaluateExpression(targetWsUrl, "window.location.href");
+		if (options?.userAgent) await applyUserAgent(targetWsUrl, options.userAgent);
 		return {
 			pid: 0,
 			cdpUrl,
@@ -224,7 +256,8 @@ var ChromeCdpBrowserController = class {
 			cached.enabled.runtime = true;
 		}
 	}
-	async launch(sessionId, explicitPath, userProfileDir) {
+	async launch(sessionId, options) {
+		const { executablePath: explicitPath, userProfileDir, headless, userAgent } = options ?? {};
 		const executablePath = discoverChrome(explicitPath);
 		const extension = loadControlExtension();
 		let profileDir;
@@ -234,7 +267,10 @@ var ChromeCdpBrowserController = class {
 		fs.mkdirSync(profileDir, { recursive: true });
 		const lockFile = path.join(profileDir, "SingletonLock");
 		if (fs.existsSync(lockFile)) throw new Error(`Chrome profile is already in use (lock file exists: ${lockFile}). Quit the running Chrome instance first, or use --cdp-url to connect to it instead.`);
-		const launchAttempts = [
+		const launchAttempts = headless ? [{
+			withExtension: false,
+			headless: true
+		}] : [
 			{
 				withExtension: true,
 				headless: false
@@ -271,6 +307,7 @@ var ChromeCdpBrowserController = class {
 				const targetWsUrl = await createTarget(cdpUrl, "about:blank");
 				await evaluateExpression(targetWsUrl, "window.location.href");
 				if (!child.pid) throw new Error("Failed to launch Chrome process");
+				if (userAgent) await applyUserAgent(targetWsUrl, userAgent);
 				return {
 					pid: child.pid,
 					cdpUrl,
@@ -285,36 +322,31 @@ var ChromeCdpBrowserController = class {
 		}
 		throw new Error(lastError?.message ?? "Unable to launch Chrome");
 	}
-	async navigate(targetWsUrl, url) {
+	/** Execute fn with a pooled connection; on failure drop connection and retry once. */
+	async withRetry(targetWsUrl, fn) {
 		let conn = await this.getConnection(targetWsUrl);
 		try {
-			await this.ensureEnabled(targetWsUrl);
-			const loadPromise = Promise.race([conn.waitForEvent("Page.loadEventFired", 6e3), conn.waitForEvent("Page.frameStoppedLoading", 6e3)]);
-			await conn.send("Page.navigate", { url });
-			try {
-				await loadPromise;
-			} catch {}
-			return (await conn.send("Runtime.evaluate", {
-				expression: "window.location.href",
-				returnByValue: true
-			})).result.value ?? url;
+			return await fn(conn);
 		} catch {
 			this.dropConnection(targetWsUrl);
 			conn = await this.getConnection(targetWsUrl);
+			return await fn(conn);
+		}
+	}
+	async navigate(targetWsUrl, url) {
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
+			const navigatedPromise = conn.waitForEvent("Page.frameNavigated", 6e3).catch(() => void 0);
 			const loadPromise = Promise.race([conn.waitForEvent("Page.loadEventFired", 6e3), conn.waitForEvent("Page.frameStoppedLoading", 6e3)]);
 			await conn.send("Page.navigate", { url });
+			const navigatedEvent = await navigatedPromise;
 			try {
 				await loadPromise;
 			} catch {}
-			return (await conn.send("Runtime.evaluate", {
-				expression: "window.location.href",
-				returnByValue: true
-			})).result.value ?? url;
-		}
+			return navigatedEvent?.frame?.url ?? url;
+		});
 	}
 	async interact(targetWsUrl, payload) {
-		let conn = await this.getConnection(targetWsUrl);
 		const expression = `(async () => {
       const payload = ${JSON.stringify(payload)};
       if (payload.action === 'click') {
@@ -373,31 +405,25 @@ var ChromeCdpBrowserController = class {
       }
       throw new Error('Unsupported interact action');
     })()`;
-		const execute = async (c) => {
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
-			const value = (await c.send("Runtime.evaluate", {
+			const value = (await conn.send("Runtime.evaluate", {
 				expression,
 				returnByValue: true,
 				awaitPromise: true
 			})).result.value ?? "";
 			if (payload.action === "click" && value === "clicked") try {
-				await c.waitForEvent("Page.frameStoppedLoading", 500);
+				await conn.waitForEvent("Page.frameNavigated", 50);
+				try {
+					await Promise.race([conn.waitForEvent("Page.loadEventFired", 3e3), conn.waitForEvent("Page.frameStoppedLoading", 3e3)]);
+				} catch {}
 			} catch {}
 			return value;
-		};
-		try {
-			return await execute(conn);
-		} catch {
-			this.dropConnection(targetWsUrl);
-			conn = await this.getConnection(targetWsUrl);
-			return await execute(conn);
-		}
+		});
 	}
 	async getContent(targetWsUrl, options) {
-		const o = JSON.stringify(options);
-		let conn = await this.getConnection(targetWsUrl);
 		const expression = `(() => {
-      const options = ${o};
+      const options = ${JSON.stringify(options)};
       if (options.mode === 'title') return document.title ?? '';
       if (options.mode === 'html') {
         if (options.selector) {
@@ -412,7 +438,7 @@ var ChromeCdpBrowserController = class {
       }
       return document.body?.innerText ?? '';
     })()`;
-		try {
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
 			const content = (await conn.send("Runtime.evaluate", {
 				expression,
@@ -422,25 +448,11 @@ var ChromeCdpBrowserController = class {
 				mode: options.mode,
 				content
 			};
-		} catch {
-			this.dropConnection(targetWsUrl);
-			conn = await this.getConnection(targetWsUrl);
-			await this.ensureEnabled(targetWsUrl);
-			const content = (await conn.send("Runtime.evaluate", {
-				expression,
-				returnByValue: true
-			})).result.value ?? "";
-			return {
-				mode: options.mode,
-				content
-			};
-		}
+		});
 	}
 	async getInteractiveElements(targetWsUrl, options) {
-		const o = JSON.stringify(options);
-		let conn = await this.getConnection(targetWsUrl);
 		const expression = `(() => {
-      const options = ${o};
+      const options = ${JSON.stringify(options)};
       const visibleOnly = options.visibleOnly !== false;
       const limit = options.limit ?? 50;
       const scopeSelector = options.selector;
@@ -649,21 +661,13 @@ var ChromeCdpBrowserController = class {
 			if (v && typeof v === "object" && Array.isArray(v.elements)) return v;
 			return emptyResult;
 		};
-		try {
-			await this.ensureEnabled(targetWsUrl);
-			return extract(await conn.send("Runtime.evaluate", {
-				expression,
-				returnByValue: true
-			}));
-		} catch {
-			this.dropConnection(targetWsUrl);
-			conn = await this.getConnection(targetWsUrl);
+		return await this.withRetry(targetWsUrl, async (conn) => {
 			await this.ensureEnabled(targetWsUrl);
 			return extract(await conn.send("Runtime.evaluate", {
 				expression,
 				returnByValue: true
 			}));
-		}
+		});
 	}
 	terminate(pid) {
 		if (pid === 0) return;
@@ -674,7 +678,7 @@ var ChromeCdpBrowserController = class {
 };
 var MockBrowserController = class {
 	pages = /* @__PURE__ */ new Map();
-	async launch(sessionId) {
+	async launch(sessionId, _options) {
 		const cdpUrl = `mock://${sessionId}`;
 		const targetWsUrl = cdpUrl;
 		this.pages.set(cdpUrl, {
@@ -689,7 +693,7 @@ var MockBrowserController = class {
 			targetWsUrl
 		};
 	}
-	async connect(cdpUrl) {
+	async connect(cdpUrl, _options) {
 		this.pages.set(cdpUrl, {
 			url: "about:blank",
 			title: "about:blank",
@@ -825,7 +829,12 @@ var SessionManager = class {
 		if (active && active.session.status !== "terminated") throw new Error("A managed session is already active");
 		const sessionId = crypto.randomUUID();
 		const token = this.ctx.tokenService.issue(sessionId);
-		const launched = this.ctx.config.cdpUrl ? await this.browser.connect(this.ctx.config.cdpUrl) : await this.browser.launch(sessionId, this.ctx.config.browserExecutablePath, this.ctx.config.userProfileDir);
+		const launched = this.ctx.config.cdpUrl ? await this.browser.connect(this.ctx.config.cdpUrl, { userAgent: this.ctx.config.userAgent }) : await this.browser.launch(sessionId, {
+			executablePath: this.ctx.config.browserExecutablePath,
+			userProfileDir: this.ctx.config.userProfileDir,
+			headless: this.ctx.config.headless,
+			userAgent: this.ctx.config.userAgent
+		});
 		const session = {
 			sessionId,
 			status: "ready",
@@ -960,7 +969,12 @@ var SessionManager = class {
 		if (this.browser.closeConnection) try {
 			this.browser.closeConnection(record.targetWsUrl);
 		} catch {}
-		const relaunched = await this.browser.launch(sessionId, this.ctx.config.browserExecutablePath);
+		const relaunched = await this.browser.launch(sessionId, {
+			executablePath: this.ctx.config.browserExecutablePath,
+			userProfileDir: this.ctx.config.userProfileDir,
+			headless: this.ctx.config.headless,
+			userAgent: this.ctx.config.userAgent
+		});
 		const restarted = {
 			...record.session,
 			status: "ready",
@@ -1187,7 +1201,9 @@ function loadConfig(env = process.env) {
 		logDir: env.AGENTIC_BROWSER_LOG_DIR ?? path.resolve(process.cwd(), ".agentic-browser"),
 		browserExecutablePath: env.AGENTIC_BROWSER_CHROME_PATH,
 		cdpUrl: env.AGENTIC_BROWSER_CDP_URL,
-		userProfileDir
+		userProfileDir,
+		headless: env.AGENTIC_BROWSER_HEADLESS === "true" || env.AGENTIC_BROWSER_HEADLESS === "1",
+		userAgent: env.AGENTIC_BROWSER_USER_AGENT || void 0
 	};
 }
 
@@ -1345,29 +1361,64 @@ function selectorSignal(insight) {
 	const evidenceStrength = Math.min(selectorEvidence / 5, 1);
 	return .7 * recipeCoverage + .3 * evidenceStrength;
 }
+function scoreInsight(insight, normalizedIntent, normalizedDomain) {
+	const insightIntent = normalize(insight.taskIntent);
+	const intentMatch = insightIntent === normalizedIntent ? 1 : 0;
+	const intentPartial = intentMatch === 1 || insightIntent.includes(normalizedIntent) || normalizedIntent.includes(insightIntent) ? .65 : 0;
+	const domainMatch = normalizedDomain && normalize(insight.siteDomain) === normalizedDomain ? 1 : normalizedDomain ? 0 : .6;
+	const reliability = .6 * confidenceFromCounts(insight.successCount, insight.failureCount) + .4 * freshnessWeight(insight.freshness);
+	const selectorQuality = selectorSignal(insight);
+	const score = .5 * Math.max(intentMatch, intentPartial) + .2 * domainMatch + .15 * reliability + .15 * selectorQuality;
+	return {
+		insightId: insight.insightId,
+		taskIntent: insight.taskIntent,
+		siteDomain: insight.siteDomain,
+		confidence: insight.confidence,
+		freshness: insight.freshness,
+		lastVerifiedAt: insight.lastVerifiedAt,
+		selectorHints: buildSelectorHints(insight),
+		score
+	};
+}
 var MemoryIndex = class {
+	/** Domain → insights index, rebuilt lazily when insight list changes. */
+	domainIndex = /* @__PURE__ */ new Map();
+	indexedInsights = null;
+	indexedLength = 0;
+	/** Rebuild the domain index when the underlying array or its size changes. */
+	ensureIndex(insights) {
+		if (this.indexedInsights === insights && this.indexedLength === insights.length) return;
+		this.domainIndex.clear();
+		for (const insight of insights) {
+			const domain = normalize(insight.siteDomain);
+			let bucket = this.domainIndex.get(domain);
+			if (!bucket) {
+				bucket = [];
+				this.domainIndex.set(domain, bucket);
+			}
+			bucket.push(insight);
+		}
+		this.indexedInsights = insights;
+		this.indexedLength = insights.length;
+	}
 	search(insights, input) {
 		const normalizedIntent = normalize(input.taskIntent);
 		const normalizedDomain = input.siteDomain ? normalize(input.siteDomain) : void 0;
 		const limit = input.limit ?? 10;
-		return insights.map((insight) => {
-			const intentMatch = normalize(insight.taskIntent) === normalizedIntent ? 1 : 0;
-			const intentPartial = intentMatch === 1 || normalize(insight.taskIntent).includes(normalizedIntent) || normalizedIntent.includes(normalize(insight.taskIntent)) ? .65 : 0;
-			const domainMatch = normalizedDomain && normalize(insight.siteDomain) === normalizedDomain ? 1 : normalizedDomain ? 0 : .6;
-			const reliability = .6 * confidenceFromCounts(insight.successCount, insight.failureCount) + .4 * freshnessWeight(insight.freshness);
-			const selectorQuality = selectorSignal(insight);
-			const score = .5 * Math.max(intentMatch, intentPartial) + .2 * domainMatch + .15 * reliability + .15 * selectorQuality;
-			return {
-				insightId: insight.insightId,
-				taskIntent: insight.taskIntent,
-				siteDomain: insight.siteDomain,
-				confidence: insight.confidence,
-				freshness: insight.freshness,
-				lastVerifiedAt: insight.lastVerifiedAt,
-				selectorHints: buildSelectorHints(insight),
-				score
-			};
-		}).filter((result) => result.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
+		this.ensureIndex(insights);
+		const candidates = normalizedDomain ? this.domainIndex.get(normalizedDomain) ?? [] : insights;
+		if (limit === 1 && normalizedDomain) {
+			let best;
+			for (const insight of candidates) {
+				const result = scoreInsight(insight, normalizedIntent, normalizedDomain);
+				if (result.score > 0 && (!best || result.score > best.score)) {
+					best = result;
+					if (best.score >= .95) break;
+				}
+			}
+			return best ? [best] : [];
+		}
+		return candidates.map((insight) => scoreInsight(insight, normalizedIntent, normalizedDomain)).filter((result) => result.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
 	}
 };
 
@@ -1464,8 +1515,13 @@ const MemoryStateSchema = z.object({ insights: z.array(TaskInsightSchema) });
 //#endregion
 //#region src/memory/task-insight-store.ts
 const EMPTY_STATE = { insights: [] };
+const FLUSH_DELAY_MS = 500;
 var TaskInsightStore = class {
 	filePath;
+	/** In-memory cache – authoritative after first load. */
+	cached = null;
+	dirty = false;
+	flushTimer = null;
 	constructor(baseDir) {
 		const memoryDir = path.join(baseDir, "memory");
 		fs.mkdirSync(memoryDir, { recursive: true });
@@ -1474,27 +1530,66 @@ var TaskInsightStore = class {
 		try {
 			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
 		} catch {}
-		if (!fs.existsSync(this.filePath)) this.write(EMPTY_STATE);
+		if (!fs.existsSync(this.filePath)) this.writeDisk(EMPTY_STATE);
+		const onExit = () => this.flushSync();
+		process.on("exit", onExit);
+		process.on("SIGINT", () => {
+			this.flushSync();
+			process.exit(0);
+		});
+		process.on("SIGTERM", () => {
+			this.flushSync();
+			process.exit(0);
+		});
 	}
 	list() {
-		return this.read().insights;
+		return this.getCache();
 	}
 	get(insightId) {
-		return this.read().insights.find((insight) => insight.insightId === insightId);
+		return this.getCache().find((insight) => insight.insightId === insightId);
 	}
 	upsert(insight) {
 		TaskInsightSchema.parse(insight);
-		const state = this.read();
-		const index = state.insights.findIndex((entry) => entry.insightId === insight.insightId);
-		if (index >= 0) state.insights[index] = insight;
-		else state.insights.push(insight);
-		this.write(state);
+		const insights = this.getCache();
+		const index = insights.findIndex((entry) => entry.insightId === insight.insightId);
+		if (index >= 0) insights[index] = insight;
+		else insights.push(insight);
+		this.markDirty();
 	}
 	replaceMany(insights) {
 		for (const insight of insights) TaskInsightSchema.parse(insight);
-		this.write({ insights });
+		this.cached = insights;
+		this.markDirty();
+	}
+	/** Force an immediate synchronous flush (used at shutdown). */
+	flushSync() {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (this.dirty && this.cached) {
+			this.writeDisk({ insights: this.cached });
+			this.dirty = false;
+		}
 	}
-	read() {
+	/** Return the in-memory cache, loading from disk on first access. */
+	getCache() {
+		if (this.cached) return this.cached;
+		this.cached = this.readDisk().insights;
+		return this.cached;
+	}
+	markDirty() {
+		this.dirty = true;
+		if (!this.flushTimer) {
+			this.flushTimer = setTimeout(() => {
+				this.flushTimer = null;
+				this.flushSync();
+			}, FLUSH_DELAY_MS);
+			if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) this.flushTimer.unref();
+		}
+	}
+	/** Read and validate from disk (only on first load or corruption recovery). */
+	readDisk() {
 		let raw;
 		try {
 			raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
@@ -1511,7 +1606,7 @@ var TaskInsightStore = class {
 				if (salvaged.length > 0) {
 					const state = { insights: salvaged };
 					this.backupAndReset();
-					this.write(state);
+					this.writeDisk(state);
 					return state;
 				}
 			}
@@ -1525,7 +1620,7 @@ var TaskInsightStore = class {
 			fs.copyFileSync(this.filePath, corruptPath);
 		} catch {}
 	}
-	write(state) {
+	writeDisk(state) {
 		const tempPath = `${this.filePath}.tmp`;
 		fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), "utf8");
 		fs.renameSync(tempPath, this.filePath);
@@ -1534,15 +1629,31 @@ var TaskInsightStore = class {
 
 //#endregion
 //#region src/memory/memory-service.ts
+const SEARCH_CACHE_TTL_MS = 2e3;
 var MemoryService = class {
 	store;
 	index;
+	/** Simple TTL cache for search results keyed by intent+domain+limit. */
+	searchCache = /* @__PURE__ */ new Map();
 	constructor(baseDir) {
 		this.store = new TaskInsightStore(baseDir);
 		this.index = new MemoryIndex();
 	}
 	search(input) {
-		return this.index.search(this.store.list(), input);
+		const cacheKey = `${input.taskIntent}\0${input.siteDomain ?? ""}\0${input.limit ?? 10}`;
+		const now = Date.now();
+		const cached = this.searchCache.get(cacheKey);
+		if (cached && now - cached.ts < SEARCH_CACHE_TTL_MS) return cached.results;
+		const results = this.index.search(this.store.list(), input);
+		this.searchCache.set(cacheKey, {
+			results,
+			ts: now
+		});
+		return results;
+	}
+	/** Invalidate search cache when data changes. */
+	invalidateSearchCache() {
+		this.searchCache.clear();
 	}
 	inspect(insightId) {
 		const insight = this.store.get(insightId);
@@ -1573,6 +1684,7 @@ var MemoryService = class {
 			updatedAt: now
 		};
 		this.store.upsert(verified);
+		this.invalidateSearchCache();
 		return verified;
 	}
 	recordSuccess(input) {
@@ -1600,6 +1712,7 @@ var MemoryService = class {
 				evidence: [evidence]
 			};
 			this.store.upsert(created);
+			this.invalidateSearchCache();
 			return created;
 		}
 		const refreshed = applySuccess({
@@ -1620,9 +1733,11 @@ var MemoryService = class {
 				updatedAt: now
 			};
 			this.store.upsert(versioned);
+			this.invalidateSearchCache();
 			return versioned;
 		}
 		this.store.upsert(refreshed);
+		this.invalidateSearchCache();
 		return refreshed;
 	}
 	recordFailure(input, errorMessage) {
@@ -1637,6 +1752,7 @@ var MemoryService = class {
 			evidence: [...matched.evidence.slice(-49), evidence]
 		}, signal);
 		this.store.upsert(failed);
+		this.invalidateSearchCache();
 		return failed;
 	}
 	findBestExactMatch(insights, taskIntent, siteDomain) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-browser",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",