@agentmemory/agentmemory 0.9.30 → 0.9.31

package/dist/standalone.mjs

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import "picocolors";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/mcp/in-memory-kv.ts
 var InMemoryKV = class {
 	store = /* @__PURE__ */ new Map();
@@ -34,20 +35,23 @@ var InMemoryKV = class {
 		return entries ? Array.from(entries.values()) : [];
 	}
 	persist() {
-		if (!this.persistPath) return;
+		if (!this.persistPath) return false;
 		try {
 			const dir = dirname(this.persistPath);
 			if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 			const data = {};
 			for (const [scope, entries] of this.store) data[scope] = Object.fromEntries(entries);
 			writeFileSync(this.persistPath, JSON.stringify(data), "utf-8");
+			return true;
 		} catch (err) {
 			process.stderr.write(`[@agentmemory/mcp] Persist failed: ${err instanceof Error ? err.message : String(err)}\n`);
+			return false;
 		}
 	}
 };
 //#endregion
 //#region src/mcp/transport.ts
+let activeStdioTransports = 0;
 var JsonRpcError = class extends Error {
 	constructor(code, message) {
 		super(message);
@@ -200,6 +204,7 @@ function createMessageParser(onMessage, writeErr = (msg) => process.stderr.write
 function createStdioTransport(handler) {
 	let parser = null;
 	let queue = Promise.resolve();
+	let active = false;
 	const writeResponse = (response) => {
 		const formatted = formatResponse(response, parser?.isFramed() ?? false);
 		if (typeof formatted === "string") {
@@ -211,6 +216,10 @@ function createStdioTransport(handler) {
 	const onData = (chunk) => parser?.push(chunk);
 	return {
 		start() {
+			if (active) return;
+			active = true;
+			activeStdioTransports += 1;
+			process.env["AGENTMEMORY_MCP_STDIO__"] = "1";
 			parser = createMessageParser((message) => {
 				queue = queue.then(() => processLine(message, handler, writeResponse));
 				queue.catch((err) => {
@@ -221,6 +230,11 @@ function createStdioTransport(handler) {
 		},
 		stop() {
 			process.stdin.off("data", onData);
+			if (active) {
+				active = false;
+				activeStdioTransports -= 1;
+				if (activeStdioTransports === 0) delete process.env["AGENTMEMORY_MCP_STDIO__"];
+			}
 			parser = null;
 		}
 	};
@@ -230,7 +244,7 @@ function createStdioTransport(handler) {
 const CORE_TOOLS = [
 	{
 		name: "memory_recall",
-		description: "Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before.",
+		description: "Search stored memories and session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -248,7 +262,28 @@ const CORE_TOOLS = [
 				},
 				token_budget: {
 					type: "number",
-					description: "Optional token budget to trim returned results"
+					description: "Optional estimated content token budget; response includes truncation and recovery metadata"
+				},
+				targetLayer: {
+					type: "string",
+					enum: [
+						"all",
+						"memory",
+						"observation"
+					],
+					description: "Search all indexed layers (default), durable memories, or raw observations before ranking"
+				},
+				project: {
+					type: "string",
+					description: "Filter by project path"
+				},
+				cwd: {
+					type: "string",
+					description: "Filter by session working directory"
+				},
+				agentId: {
+					type: "string",
+					description: "Filter by owning agent; '*' reads across agents"
 				}
 			},
 			required: ["query"]
@@ -337,15 +372,32 @@ const CORE_TOOLS = [
 	},
 	{
 		name: "memory_sessions",
-		description: "List recent sessions with their status and observation counts.",
+		description: "List recent sessions with status, observation counts, summaries and a continuation cursor. Filters apply before pagination; retain them when requesting the next page.",
 		inputSchema: {
 			type: "object",
-			properties: {}
+			properties: {
+				project: {
+					type: "string",
+					description: "Exact project identifier used when sessions were started"
+				},
+				agentId: {
+					type: "string",
+					description: "Filter by owning agent; '*' reads across agents"
+				},
+				limit: {
+					type: "integer",
+					description: "Page size (default 20, max 100)"
+				},
+				cursor: {
+					type: "string",
+					description: "nextCursor from the previous page; omit for the first page"
+				}
+			}
 		}
 	},
 	{
 		name: "memory_smart_search",
-		description: "Hybrid semantic+keyword search with progressive disclosure.",
+		description: "Hybrid semantic+keyword search with progressive disclosure. Pass query to search, or expandIds to recover full results.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -355,14 +407,34 @@ const CORE_TOOLS = [
 				},
 				expandIds: {
 					type: "string",
-					description: "Comma-separated observation IDs to expand"
+					description: "Comma-separated memory or observation IDs to expand; query is optional when provided"
 				},
 				limit: {
 					type: "number",
 					description: "Max results (default 10)"
+				},
+				targetLayer: {
+					type: "string",
+					enum: [
+						"all",
+						"memory",
+						"observation"
+					],
+					description: "Search all indexed layers (default), durable memories, or raw observations before ranking"
+				},
+				project: {
+					type: "string",
+					description: "Filter by project path"
+				},
+				agentId: {
+					type: "string",
+					description: "Filter by owning agent; '*' reads across agents"
+				},
+				includeLessons: {
+					type: "boolean",
+					description: "Include lesson matches when targetLayer is all (default true)"
 				}
-			},
-			required: ["query"]
+			}
 		}
 	},
 	{
@@ -440,10 +512,31 @@ const CORE_TOOLS = [
 	},
 	{
 		name: "memory_export",
-		description: "Export all memory data as JSON.",
+		description: "Export memory data as JSON. Past the transport size limit the export is refused, so use the paging arguments on a large store.",
 		inputSchema: {
 			type: "object",
-			properties: {}
+			properties: {
+				maxSessions: {
+					type: "number",
+					description: "Sessions per page (with their observations)"
+				},
+				offset: {
+					type: "number",
+					description: "Session offset"
+				},
+				collectionLimit: {
+					type: "number",
+					description: "Rows per page for memories, summaries, graphNodes, lessons and the other top-level collections; access logs follow the memories on the page. Sessions and their observations are paged only by maxSessions and offset, so pass collections to leave them out of each page"
+				},
+				collectionOffset: {
+					type: "number",
+					description: "Row offset for the top-level collections"
+				},
+				collections: {
+					type: "string",
+					description: "Comma-separated collections to return, e.g. memories,lessons. Sessions and their observations come back only when the list names sessions, access logs only together with memories. Unknown names are ignored. Omit for everything. A paged or selected export cannot be imported with strategy replace."
+				}
+			}
 		}
 	},
 	{
@@ -1342,7 +1435,8 @@ function getAllTools() {
 		...V010_SLOTS_TOOLS
 	];
 }
-const ENV_FILE = join(join(homedir(), ".agentmemory"), ".env");
+process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
+const ENV_FILE = process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
 let envFileCache;
 function loadEnvFile() {
 	if (envFileCache) return envFileCache;
@@ -1350,7 +1444,10 @@ function loadEnvFile() {
 		envFileCache = {};
 		return envFileCache;
 	}
-	const content = readFileSync(ENV_FILE, "utf-8");
+	envFileCache = parseEnvContent(readFileSync(ENV_FILE, "utf-8"));
+	return envFileCache;
+}
+function parseEnvContent(content) {
 	const vars = {};
 	for (const line of content.split("\n")) {
 		const trimmed = line.trim();
@@ -1369,8 +1466,7 @@ function loadEnvFile() {
 		}
 		vars[key] = val;
 	}
-	envFileCache = vars;
-	return envFileCache;
+	return vars;
 }
 function getMergedEnv(overrides) {
 	return {
@@ -1379,12 +1475,298 @@ function getMergedEnv(overrides) {
 		...overrides
 	};
 }
+function loadAgentScope() {
+	const env = getMergedEnv();
+	const raw = env["AGENT_ID"];
+	if (!raw) return null;
+	const agentId = raw.trim().slice(0, 128);
+	if (!agentId) return null;
+	return {
+		agentId,
+		mode: env["AGENTMEMORY_AGENT_SCOPE"] === "isolated" ? "isolated" : "shared"
+	};
+}
+function getAgentId() {
+	return loadAgentScope()?.agentId;
+}
+function isAgentScopeIsolated() {
+	return loadAgentScope()?.mode === "isolated";
+}
 function getStandalonePersistPath() {
 	return getMergedEnv()["STANDALONE_PERSIST_PATH"] || join(homedir(), ".agentmemory", "standalone.json");
 }
 //#endregion
+//#region src/state/search-layer.ts
+function isSearchLayer(value) {
+	return value === "all" || value === "memory" || value === "observation";
+}
+//#endregion
+//#region src/state/memory-utils.ts
+function memoryToObservation(memory) {
+	return {
+		id: memory.id,
+		sessionId: memory.sessionIds?.[0] ?? "memory",
+		timestamp: memory.createdAt,
+		type: "decision",
+		title: memory.title,
+		facts: [memory.content],
+		narrative: memory.content,
+		concepts: memory.concepts,
+		files: memory.files,
+		importance: memory.strength,
+		...memory.agentId ? { agentId: memory.agentId } : {}
+	};
+}
+//#endregion
+//#region src/functions/recall-response.ts
+function estimateTokens(value) {
+	return Math.max(1, Math.ceil(JSON.stringify(value).length / 3));
+}
+function prefix(text, length) {
+	let end = Math.min(length, text.length);
+	if (end > 0 && end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+	return text.slice(0, end);
+}
+function fitText(text, budget, makeResult) {
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (estimateTokens(makeResult(prefix(text, middle))) <= budget) low = middle;
+		else high = middle - 1;
+	}
+	return makeResult(prefix(text, low));
+}
+function formatResult(result, format) {
+	if (format === "full") return result;
+	const observation = result.observation;
+	const compact = {
+		obsId: observation.id,
+		sessionId: result.sessionId,
+		title: observation.title,
+		type: observation.type,
+		score: result.score,
+		timestamp: observation.timestamp,
+		...result.layer !== void 0 && { layer: result.layer }
+	};
+	if (format === "compact") return compact;
+	const { type: _type, ...narrative } = compact;
+	return {
+		...narrative,
+		narrative: observation.narrative
+	};
+}
+function clipResult(result, format, budget) {
+	const observation = result.observation;
+	const layer = result.layer !== void 0 ? { layer: result.layer } : {};
+	if (format === "compact") {
+		const base = {
+			obsId: observation.id,
+			sessionId: result.sessionId,
+			title: "",
+			type: observation.type,
+			score: result.score,
+			timestamp: observation.timestamp,
+			...layer,
+			content_truncated: true
+		};
+		const minimum = estimateTokens(base);
+		if (minimum > budget) return { minimum };
+		return {
+			result: fitText(observation.title, budget, (title) => ({
+				...base,
+				title
+			})),
+			minimum
+		};
+	}
+	const makeResult = (title, narrative) => {
+		if (format === "narrative") return {
+			obsId: observation.id,
+			sessionId: result.sessionId,
+			title,
+			narrative,
+			score: result.score,
+			timestamp: observation.timestamp,
+			...layer,
+			content_truncated: true
+		};
+		return {
+			observation: {
+				id: observation.id,
+				sessionId: observation.sessionId,
+				timestamp: observation.timestamp,
+				type: observation.type,
+				title,
+				facts: [],
+				narrative,
+				concepts: [],
+				files: [],
+				importance: observation.importance,
+				...observation.confidence !== void 0 && { confidence: observation.confidence },
+				...observation.agentId !== void 0 && { agentId: observation.agentId },
+				...observation.origin && { origin: {
+					channel: observation.origin.channel,
+					capturedAt: observation.origin.capturedAt
+				} }
+			},
+			score: result.score,
+			sessionId: result.sessionId,
+			...layer,
+			content_truncated: true
+		};
+	};
+	const minimum = estimateTokens(makeResult("", ""));
+	if (minimum > budget) return { minimum };
+	const titleResult = fitText(prefix(observation.title, 120), budget, (title) => makeResult(title, ""));
+	const title = "observation" in titleResult ? titleResult.observation.title : titleResult.title;
+	return {
+		result: fitText(observation.narrative || observation.facts.join("\n"), budget, (text) => makeResult(title, text)),
+		minimum
+	};
+}
+function buildRecallResponse(results, format, tokenBudget) {
+	const selected = [];
+	let used = 0;
+	let clipped = false;
+	let minimumBudget;
+	for (const result of results) {
+		const formatted = formatResult(result, format);
+		const tokens = estimateTokens(formatted);
+		if (tokenBudget === void 0 || used + tokens <= tokenBudget) {
+			selected.push(formatted);
+			used += tokens;
+			continue;
+		}
+		if (selected.length === 0) {
+			const preview = clipResult(result, format, tokenBudget);
+			if (preview.result) {
+				selected.push(preview.result);
+				used = estimateTokens(preview.result);
+				clipped = true;
+				continue;
+			} else minimumBudget = Math.min(preview.minimum, tokens);
+		}
+		break;
+	}
+	const excluded = results.slice(selected.length);
+	const metadata = {
+		tokens_used: used,
+		tokens_budget: tokenBudget,
+		truncated: clipped || excluded.length > 0,
+		matched_count: results.length,
+		excluded_by_budget: excluded.length,
+		excluded_results: excluded.slice(0, 10).map((result) => ({
+			obsId: result.observation.id,
+			sessionId: result.sessionId,
+			title: prefix(result.observation.title, 120)
+		})),
+		excluded_results_truncated: excluded.length > 10,
+		...minimumBudget !== void 0 && { minimum_budget: minimumBudget }
+	};
+	if (format === "narrative") {
+		const narrativeResults = selected;
+		return {
+			...metadata,
+			format,
+			results: narrativeResults,
+			text: narrativeResults.map((result, index) => `${index + 1}. ${result.title}\n${result.narrative}`).join("\n\n")
+		};
+	}
+	if (format === "compact") return {
+		...metadata,
+		format,
+		results: selected
+	};
+	return {
+		...metadata,
+		format,
+		results: selected
+	};
+}
+//#endregion
+//#region src/mcp/search-arguments.ts
+function parseSearchExpansionIds(value) {
+	return (typeof value === "string" ? value.split(",") : Array.isArray(value) ? value : []).flatMap((entry) => {
+		if (typeof entry === "string") return entry.trim() ? [entry.trim()] : [];
+		if (!entry || typeof entry !== "object" || typeof entry.obsId !== "string" || !entry.obsId.trim()) return [];
+		const obsId = entry.obsId.trim();
+		return typeof entry.sessionId === "string" && entry.sessionId.trim() ? [{
+			obsId,
+			sessionId: entry.sessionId.trim()
+		}] : [obsId];
+	});
+}
+//#endregion
+//#region src/state/list-query.ts
+function encodeCursor(position) {
+	return Buffer.from(JSON.stringify(position), "utf-8").toString("base64url");
+}
+function decodeCursor(cursor) {
+	if (!cursor) return null;
+	try {
+		const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf-8"));
+		if (!parsed || typeof parsed !== "object") return null;
+		const position = {};
+		if (typeof parsed.key === "string") position.key = parsed.key;
+		if (typeof parsed.id === "string") position.id = parsed.id;
+		if (Number.isInteger(parsed.offset) && parsed.offset >= 0) position.offset = parsed.offset;
+		return position;
+	} catch {
+		return null;
+	}
+}
+function compareDesc(aKey, aId, bKey, bId) {
+	if (aKey !== bKey) return aKey < bKey ? 1 : -1;
+	if (aId === bId) return 0;
+	return aId < bId ? 1 : -1;
+}
+function sortByKeyDesc(items, keyOf, idOf) {
+	return items.sort((a, b) => compareDesc(keyOf(a), idOf(a), keyOf(b), idOf(b)));
+}
+function pageAfterCursor(sortedDesc, keyOf, idOf, cursor, limit) {
+	const position = decodeCursor(cursor);
+	let start = 0;
+	if (position?.key !== void 0 && position.id !== void 0) {
+		const { key, id } = position;
+		start = sortedDesc.findIndex((item) => compareDesc(keyOf(item), idOf(item), key, id) > 0);
+		if (start < 0) start = sortedDesc.length;
+	}
+	const page = sortedDesc.slice(start, start + limit);
+	const last = page[page.length - 1];
+	return {
+		page,
+		nextCursor: last !== void 0 && start + limit < sortedDesc.length ? encodeCursor({
+			key: keyOf(last),
+			id: idOf(last)
+		}) : null
+	};
+}
+//#endregion
+//#region src/mcp/session-arguments.ts
+function parseSessionArguments(args) {
+	const limit = args.limit === void 0 ? 20 : args.limit;
+	if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) throw new Error("limit must be a positive integer");
+	const query = { limit: String(Math.min(limit, 100)) };
+	for (const field of [
+		"project",
+		"agentId",
+		"cursor"
+	]) {
+		if (args[field] === void 0) continue;
+		if (field === "cursor" && typeof args[field] === "string" && !args[field].trim()) continue;
+		if (typeof args[field] !== "string" || !args[field].trim()) throw new Error(`${field} must be a non-empty string`);
+		query[field] = args[field].trim();
+	}
+	if (query.cursor) {
+		const position = decodeCursor(query.cursor);
+		if (!position || typeof position.key !== "string" || typeof position.id !== "string") throw new Error("cursor must be a session continuation token");
+	}
+	return query;
+}
+//#endregion
 //#region src/version.ts
-const VERSION = "0.9.30";
+const VERSION = "0.9.31";
 createRequire(import.meta.url);
 //#endregion
 //#region src/state/schema.ts
@@ -1393,6 +1775,7 @@ const KV = {
 	observations: (sessionId) => `mem:obs:${sessionId}`,
 	memories: "mem:memories",
 	summaries: "mem:summaries",
+	summaryRepairs: "mem:summary:repairs",
 	config: "mem:config",
 	metrics: "mem:metrics",
 	health: "mem:health",
@@ -1403,11 +1786,17 @@ const KV = {
 	profiles: "mem:profiles",
 	claudeBridge: "mem:claude-bridge",
 	graphNodes: "mem:graph:nodes",
+	graphControl: "mem:graph:control",
 	graphEdges: "mem:graph:edges",
 	graphSnapshot: "mem:graph:snapshot",
 	graphNameIndex: "mem:graph:name-index",
 	graphEdgeKey: "mem:graph:edge-key",
 	graphNodeDegree: "mem:graph:node-degree",
+	graphMembership: "mem:graph:membership",
+	graphRetrievalControl: "mem:graph:retrieval-control",
+	graphRetrievalData: "mem:graph:retrieval-data",
+	graphIndexMigration: "mem:graph:index-migration",
+	graphIndexManifest: "mem:graph:index-manifest",
 	semantic: "mem:semantic",
 	procedural: "mem:procedural",
 	teamShared: (teamId) => `mem:team:${teamId}:shared`,
@@ -1452,6 +1841,7 @@ function generateId(prefix) {
 	return `${prefix}_${Date.now().toString(36)}_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
 }
 process.env["AGENTMEMORY_VERBOSE"] === "1" || process.env["AGENTMEMORY_VERBOSE"];
+new AsyncLocalStorage();
 KV.auditMonths;
 const AUDIT_MIGRATION_STATE_KEY = "migration";
 async function readAuditMigrationState(kv) {
@@ -1530,7 +1920,7 @@ async function queryAudit(kv, filter) {
 //#region src/secret-store.ts
 const SECRET_KEY = "AGENTMEMORY_SECRET";
 function agentmemoryHomeDir() {
-	return join(homedir(), ".agentmemory");
+	return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
 }
 function secretFilePath() {
 	return join(agentmemoryHomeDir(), "secret");
@@ -1554,7 +1944,7 @@ function unquote(value) {
 function readEnvFileSecret() {
 	let content;
 	try {
-		content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+		content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
 	} catch {
 		return "";
 	}
@@ -1570,13 +1960,29 @@ function readEnvFileSecret() {
 	}
 	return found;
 }
-function readStoredSecret() {
+function readSecretFile(path) {
 	try {
-		return usable(readFileSync(secretFilePath(), "utf-8"));
+		return usable(readFileSync(path, "utf-8"));
 	} catch {
 		return "";
 	}
 }
+function legacyDataDirSecretPaths(env = process.env) {
+	const dataDir = env["AGENTMEMORY_DATA_DIR"];
+	if (!dataDir) return [];
+	const paths = [
+		join(dataDir, "secret"),
+		join(dataDir, ".hmac"),
+		join(dataDir, "..", ".hmac")
+	];
+	return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+	const canonicalPath = canonicalSecretPath();
+	const localPath = secretFilePath();
+	const legacyPaths = legacyDataDirSecretPaths(env);
+	return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
 function isLoopbackUrl(url) {
 	let hostname;
 	try {
@@ -1590,8 +1996,12 @@ function isLoopbackUrl(url) {
 function resolveClientSecret(baseUrl, env = process.env) {
 	const fromEnv = usable(env[SECRET_KEY]);
 	if (fromEnv) return fromEnv;
+	if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
 	if (!isLoopbackUrl(baseUrl)) return "";
-	return readEnvFileSecret() || readStoredSecret();
+	return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+	return join(homedir(), ".agentmemory", "secret");
 }
 //#endregion
 //#region src/mcp/rest-proxy.ts
@@ -1605,7 +2015,7 @@ function probeTimeoutMs() {
 	const n = Number(raw);
 	return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_HEALTH_PROBE_TIMEOUT_MS;
 }
-function forceProxy() {
+function isProxyRequired() {
 	const raw = process.env["AGENTMEMORY_FORCE_PROXY"];
 	return raw === "1" || raw === "true";
 }
@@ -1620,6 +2030,7 @@ var ProxyCallError = class extends Error {
 	}
 };
 let cached = null;
+let cachedUrl = null;
 let cachedAt = 0;
 let probeInFlight = null;
 function resolveEnvOrEmpty(name) {
@@ -1629,17 +2040,25 @@ function resolveEnvOrEmpty(name) {
 	return raw;
 }
 function baseUrl() {
-	return (resolveEnvOrEmpty("AGENTMEMORY_URL") || DEFAULT_URL).replace(/\/+$/, "");
+	const value = resolveEnvOrEmpty("AGENTMEMORY_URL") || DEFAULT_URL;
+	try {
+		const parsed = new URL(value);
+		if (!["http:", "https:"].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password || /[?#\s]/.test(value)) throw new Error();
+		return value.replace(/\/+$/, "");
+	} catch {
+		throw new Error("AGENTMEMORY_URL must be an HTTP(S) URL without credentials, query, or fragment");
+	}
 }
-function authHeader() {
-	const secret = resolveClientSecret(baseUrl());
+function authHeader(url) {
+	const secret = resolveClientSecret(url);
 	return secret ? { authorization: `Bearer ${secret}` } : {};
 }
 const defaultLivezProbe = async (url, timeoutMs, headers) => {
 	const res = await fetch(`${url}/agentmemory/livez`, {
 		method: "GET",
 		headers,
-		signal: AbortSignal.timeout(timeoutMs)
+		signal: AbortSignal.timeout(timeoutMs),
+		redirect: "error"
 	});
 	return {
 		ok: res.ok,
@@ -1651,7 +2070,7 @@ let livezProbe = defaultLivezProbe;
 async function probe(url) {
 	const timeout = probeTimeoutMs();
 	try {
-		const res = await livezProbe(url, timeout, authHeader());
+		const res = await livezProbe(url, timeout, authHeader(url));
 		if (!res.ok) process.stderr.write(`[@agentmemory/mcp] livez probe ${url}/agentmemory/livez -> ${res.status ?? "?"} ${res.statusText ?? ""}; falling back to local InMemoryKV (set AGENTMEMORY_FORCE_PROXY=1 to skip the probe)\n`);
 		return res.ok;
 	} catch (err) {
@@ -1661,33 +2080,38 @@ async function probe(url) {
 }
 function invalidateHandle() {
 	cached = null;
+	cachedUrl = null;
 	cachedAt = 0;
 }
 async function resolveHandle() {
 	const now = Date.now();
+	const url = baseUrl();
+	if (cached && (cachedUrl !== url || cached.mode === "local" && isProxyRequired())) invalidateHandle();
 	if (cached) if (cached.mode === "local" && now - cachedAt >= LOCAL_MODE_TTL_MS) {
 		cached = null;
 		cachedAt = 0;
 	} else return cached;
-	if (probeInFlight) return probeInFlight;
-	const url = baseUrl();
-	const skipProbe = forceProxy();
-	probeInFlight = (async () => {
+	const skipProbe = isProxyRequired();
+	if (probeInFlight?.url === url && probeInFlight.forceProxy === skipProbe) return probeInFlight.promise;
+	const pending = (async () => {
 		const up = skipProbe ? true : await probe(url);
+		if (baseUrl() !== url || isProxyRequired() !== skipProbe) return resolveHandle();
 		if (skipProbe) process.stderr.write(`[@agentmemory/mcp] AGENTMEMORY_FORCE_PROXY set; skipping livez probe and trusting ${url}\n`);
 		if (up) {
 			const handle = {
 				mode: "proxy",
 				baseUrl: url,
 				call: async (path, init) => {
+					if (baseUrl() !== url) throw new Error("AgentMemory endpoint changed; resolve a new proxy handle before retrying.");
 					const res = await fetch(`${url}${path}`, {
 						...init,
 						headers: {
 							"content-type": "application/json",
-							...authHeader(),
+							...authHeader(url),
 							...init?.headers
 						},
-						signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
+						signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+						redirect: "error"
 					});
 					if (!res.ok) {
 						const errText = await res.text().catch(() => "");
@@ -1704,18 +2128,25 @@ async function resolveHandle() {
 				}
 			};
 			cached = handle;
+			cachedUrl = url;
 			cachedAt = Date.now();
 			return handle;
 		}
 		const local = { mode: "local" };
 		cached = local;
+		cachedUrl = url;
 		cachedAt = Date.now();
 		return local;
 	})();
+	probeInFlight = {
+		url,
+		forceProxy: skipProbe,
+		promise: pending
+	};
 	try {
-		return await probeInFlight;
+		return await pending;
 	} finally {
-		probeInFlight = null;
+		if (probeInFlight?.promise === pending) probeInFlight = null;
 	}
 }
 //#endregion
@@ -1775,6 +2206,9 @@ function textResponse(payload, pretty = false) {
 		text: JSON.stringify(payload, null, pretty ? 2 : 0)
 	}] };
 }
+function isAuthenticationError(error) {
+	return error instanceof ProxyCallError && (error.status === 401 || error.status === 403);
+}
 function validate(toolName, args) {
 	if (!IMPLEMENTED_TOOLS.has(toolName)) throw new Error(`Unknown tool: ${toolName}`);
 	const v = { tool: toolName };
@@ -1792,22 +2226,41 @@ function validate(toolName, args) {
 		}
 		case "memory_recall":
 		case "memory_smart_search": {
+			if (args.targetLayer !== void 0 && !isSearchLayer(args.targetLayer)) throw new Error("targetLayer must be one of: all, memory, observation");
+			v.targetLayer = args.targetLayer ?? "all";
+			for (const field of [
+				"project",
+				"cwd",
+				"agentId",
+				"sessionId",
+				"source"
+			]) {
+				if (args[field] !== void 0 && typeof args[field] !== "string") throw new Error(`${field} must be a string`);
+				if (typeof args[field] === "string" && args[field].trim()) v[field] = args[field].trim();
+			}
+			if (toolName === "memory_smart_search") {
+				v.expandIds = parseSearchExpansionIds(args.expandIds);
+				if (typeof args.includeLessons === "boolean") v.includeLessons = args.includeLessons;
+			}
 			const query = args["query"];
-			if (typeof query !== "string" || !query.trim()) throw new Error("query is required");
-			v.query = query.trim();
+			if (typeof query !== "string" || !query.trim()) {
+				if (!v.expandIds?.length) throw new Error("query is required unless expandIds is provided");
+			} else v.query = query.trim();
 			v.limit = parseLimit(args["limit"]);
-			const fmt = args["format"];
-			if (typeof fmt === "string" && fmt.trim()) v.format = fmt.trim().toLowerCase();
-			const budget = args["token_budget"];
-			if (typeof budget === "number" && Number.isFinite(budget) && budget > 0) v.tokenBudget = Math.floor(budget);
-			else if (typeof budget === "string" && budget.trim()) {
-				const n = Number(budget);
-				if (Number.isFinite(n) && n > 0) v.tokenBudget = Math.floor(n);
+			if (toolName === "memory_recall") {
+				const format = typeof args.format === "string" ? args.format.trim().toLowerCase() : args.format ?? "full";
+				if (format !== "full" && format !== "compact" && format !== "narrative") throw new Error("format must be one of: full, compact, narrative");
+				v.format = format;
+				if (args.token_budget !== void 0) {
+					const budget = typeof args.token_budget === "string" ? Number(args.token_budget) : args.token_budget;
+					if (typeof budget !== "number" || !Number.isInteger(budget) || budget < 1) throw new Error("token_budget must be a positive integer");
+					v.tokenBudget = budget;
+				}
 			}
 			return v;
 		}
 		case "memory_sessions":
-			v.limit = parseLimit(args["limit"], 20);
+			v.sessionQuery = parseSessionArguments(args);
 			return v;
 		case "memory_governance_delete": {
 			const ids = normalizeList(args["memoryIds"]);
@@ -1816,7 +2269,22 @@ function validate(toolName, args) {
 			v.reason = args["reason"] || "plugin skill request";
 			return v;
 		}
-		case "memory_export": return v;
+		case "memory_export": {
+			const query = new URLSearchParams();
+			for (const key of [
+				"maxSessions",
+				"offset",
+				"collectionLimit",
+				"collectionOffset"
+			]) {
+				const n = Number(args[key]);
+				const min = key === "maxSessions" || key === "collectionLimit" ? 1 : 0;
+				if (args[key] !== void 0 && Number.isInteger(n) && n >= min) query.set(key, String(n));
+			}
+			if (typeof args["collections"] === "string") query.set("collections", args["collections"]);
+			v.exportQuery = query.toString();
+			return v;
+		}
 		case "memory_audit":
 			v.limit = parseLimit(args["limit"], 50);
 			return v;
@@ -1840,7 +2308,11 @@ async function handleProxy(v, handle) {
 			const body = {
 				query: v.query,
 				limit: v.limit,
-				format: v.format ?? "full"
+				format: v.format ?? "full",
+				targetLayer: v.targetLayer,
+				project: v.project,
+				cwd: v.cwd,
+				agentId: v.agentId
 			};
 			if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget;
 			return textResponse(await handle.call("/agentmemory/search", {
@@ -1851,16 +2323,21 @@ async function handleProxy(v, handle) {
 		case "memory_smart_search": {
 			const body = {
 				query: v.query,
-				limit: v.limit
+				limit: v.limit,
+				targetLayer: v.targetLayer,
+				project: v.project,
+				agentId: v.agentId,
+				expandIds: v.expandIds,
+				sessionId: v.sessionId,
+				source: v.source,
+				includeLessons: v.includeLessons
 			};
-			if (v.format != null) body["format"] = v.format;
-			if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget;
 			return textResponse(await handle.call("/agentmemory/smart-search", {
 				method: "POST",
 				body: JSON.stringify(body)
 			}), true);
 		}
-		case "memory_sessions": return textResponse(await handle.call(`/agentmemory/sessions?limit=${v.limit}`, { method: "GET" }), true);
+		case "memory_sessions": return textResponse(await handle.call(`/agentmemory/sessions?${new URLSearchParams(v.sessionQuery)}`, { method: "GET" }), true);
 		case "memory_governance_delete": return textResponse(await handle.call("/agentmemory/governance/memories", {
 			method: "DELETE",
 			body: JSON.stringify({
@@ -1869,15 +2346,22 @@ async function handleProxy(v, handle) {
 			})
 		}));
 		case "memory_export": try {
-			return textResponse(await handle.call("/agentmemory/export", { method: "GET" }), true);
+			return textResponse(await handle.call(`/agentmemory/export${v.exportQuery ? `?${v.exportQuery}` : ""}`, { method: "GET" }), true);
 		} catch (err) {
-			if (err instanceof ProxyCallError && err.body != null && typeof err.body === "object" && err.body.oversized === true) return textResponse(err.body, true);
+			if (err instanceof ProxyCallError && err.status === 413 && err.body != null && typeof err.body === "object" && err.body.oversized === true) return textResponse(err.body, true);
 			throw err;
 		}
 		case "memory_audit": return textResponse(await handle.call(`/agentmemory/audit?limit=${v.limit}`, { method: "GET" }), true);
 		default: throw new Error(`Unknown tool: ${v.tool}`);
 	}
 }
+function localFallbackNotice(persisted) {
+	const store = persisted ? "the local fallback file, which the server does not read" : "this process's in-memory fallback store, which is lost when the process exits";
+	return {
+		storage: "local",
+		warning: `agentmemory server at ${displayAgentmemoryUrl()} did not confirm this call, so it ran against ${store}.`
+	};
+}
 async function handleLocal(v, kvInstance) {
 	switch (v.tool) {
 		case "memory_save": {
@@ -1895,34 +2379,96 @@ async function handleLocal(v, kvInstance) {
 				strength: 7,
 				version: 1,
 				isLatest: true,
-				sessionIds: []
+				sessionIds: [],
+				...v.project !== void 0 && { project: v.project },
+				...(v.agentId ?? getAgentId()) !== void 0 && { agentId: v.agentId ?? getAgentId() }
+			});
+			return textResponse({
+				saved: id,
+				...localFallbackNotice(kvInstance.persist())
 			});
-			kvInstance.persist();
-			return textResponse({ saved: id });
 		}
 		case "memory_recall":
 		case "memory_smart_search": {
+			const isolated = isAgentScopeIsolated();
+			const agentId = v.agentId === "*" ? void 0 : v.agentId ?? (isolated ? getAgentId() : void 0);
+			if (isolated && v.agentId !== "*" && !agentId) throw new Error("AGENTMEMORY_AGENT_SCOPE=isolated requires an agentId; pass '*' to read across agents");
 			const query = (v.query || "").toLowerCase();
 			const limit = v.limit ?? DEFAULT_LIMIT;
+			const all = v.targetLayer === "observation" ? [] : await kvInstance.list("mem:memories");
+			const sessions = v.project || v.cwd ? await kvInstance.list("mem:sessions") : [];
+			const sessionsById = new Map(sessions.map((session) => [session.id, session]));
+			const scoped = all.filter((memory) => {
+				if (memory.isLatest === false || agentId && memory.agentId !== agentId) return false;
+				const linkedSessions = (memory.sessionIds ?? []).map((id) => sessionsById.get(id));
+				if (v.project && (memory.project ? memory.project !== v.project : !linkedSessions.some((session) => session?.project === v.project))) return false;
+				if (v.cwd && !linkedSessions.some((session) => session?.cwd === v.cwd)) return false;
+				return true;
+			});
+			if (v.tool === "memory_smart_search" && v.expandIds?.length) {
+				const ids = v.expandIds.map((entry) => typeof entry === "string" ? entry : entry.obsId);
+				const byId = new Map(scoped.map((memory) => [memory.id, memory]));
+				const eligible = ids.filter((id) => byId.has(id));
+				return textResponse({
+					mode: "expanded",
+					results: eligible.slice(0, 20).map((id) => {
+						const observation = memoryToObservation(byId.get(id));
+						return {
+							obsId: id,
+							sessionId: observation.sessionId,
+							observation,
+							layer: "memory"
+						};
+					}),
+					truncated: eligible.length > 20
+				}, true);
+			}
+			const results = scoped.filter((memory) => {
+				const text = [
+					memory.title,
+					memory.content,
+					...memory.files ?? [],
+					...memory.concepts ?? [],
+					...memory.sessionIds ?? [],
+					memory.id
+				].join(" ").toLowerCase();
+				return query.split(/\s+/).every((word) => text.includes(word));
+			}).slice(0, limit);
+			if (v.tool === "memory_recall") return textResponse(buildRecallResponse(results.map((memory) => {
+				const observation = memoryToObservation(memory);
+				return {
+					sessionId: observation.sessionId,
+					observation,
+					score: 1,
+					layer: "memory"
+				};
+			}), v.format ?? "full", v.tokenBudget), true);
 			return textResponse({
 				mode: "compact",
-				results: (await kvInstance.list("mem:memories")).filter((m) => {
-					const text = [
-						typeof m["title"] === "string" ? m["title"] : "",
-						typeof m["content"] === "string" ? m["content"] : "",
-						Array.isArray(m["files"]) ? m["files"].join(" ") : "",
-						Array.isArray(m["concepts"]) ? m["concepts"].join(" ") : "",
-						Array.isArray(m["sessionIds"]) ? m["sessionIds"].join(" ") : "",
-						typeof m["id"] === "string" ? m["id"] : ""
-					].join(" ").toLowerCase();
-					return query.split(/\s+/).every((word) => text.includes(word));
-				}).slice(0, limit)
+				results: results.map((memory) => ({
+					...memory,
+					obsId: memory.id,
+					sessionId: memory.sessionIds?.[0] ?? "memory",
+					layer: "memory"
+				}))
 			}, true);
 		}
 		case "memory_sessions": {
-			const sessions = await kvInstance.list("mem:sessions");
-			const limit = v.limit ?? 20;
-			return textResponse({ sessions: sessions.slice(0, limit) }, true);
+			const query = v.sessionQuery;
+			const agentId = query.agentId === "*" ? void 0 : query.agentId ?? (isAgentScopeIsolated() ? getAgentId() : void 0);
+			const sessions = (await kvInstance.list("mem:sessions")).filter((session) => session && typeof session.id === "string" && session.id.length > 0).filter((session) => !query.project || session.project === query.project).filter((session) => !agentId || session.agentId === agentId);
+			const key = (session) => session.startedAt || "";
+			const { page, nextCursor } = pageAfterCursor(sortByKeyDesc(sessions, key, (session) => session.id), key, (session) => session.id, query.cursor, Number(query.limit));
+			return textResponse({
+				sessions: await Promise.all(page.map(async (session) => {
+					const summary = await kvInstance.get("mem:summaries", session.id);
+					return summary ? {
+						...session,
+						summary
+					} : session;
+				})),
+				nextCursor
+			}, true);
 		}
 		case "memory_governance_delete": {
 			let deleted = 0;
@@ -1930,11 +2476,12 @@ async function handleLocal(v, kvInstance) {
 				await kvInstance.delete("mem:memories", id);
 				deleted++;
 			}
-			kvInstance.persist();
+			const persisted = kvInstance.persist();
 			return textResponse({
 				deleted,
 				requested: (v.memoryIds || []).length,
-				reason: v.reason
+				reason: v.reason,
+				...localFallbackNotice(persisted)
 			});
 		}
 		case "memory_export": return textResponse({
@@ -1974,6 +2521,10 @@ async function handleToolCall(toolName, args, kvInstance = kv) {
 	if (handle.mode === "proxy") try {
 		return await handleProxy(validated, handle);
 	} catch (err) {
+		if (toolName === "memory_sessions" || isAuthenticationError(err) || isProxyRequired()) {
+			invalidateHandle();
+			throw err;
+		}
 		process.stderr.write(`[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}; invalidating handle and falling back to local KV\n`);
 		invalidateHandle();
 	}
@@ -1994,10 +2545,12 @@ async function handleToolsList() {
 			if (debug) process.stderr.write(`[@agentmemory/mcp] tools/list: returning ${remote.tools.length} tools from server\n`);
 			return { tools: remote.tools };
 		}
+		if (isProxyRequired()) throw new Error("AgentMemory returned an invalid tool inventory");
 		process.stderr.write(`[@agentmemory/mcp] tools/list: server returned unexpected shape (no .tools array); falling back to local IMPLEMENTED_TOOLS list. Set AGENTMEMORY_DEBUG=1 to inspect response.\n`);
 	} catch (err) {
-		process.stderr.write(`[@agentmemory/mcp] tools/list proxy failed: ${err instanceof Error ? err.message : String(err)}; falling back to local list\n`);
 		invalidateHandle();
+		if (isAuthenticationError(err) || isProxyRequired()) throw err;
+		process.stderr.write(`[@agentmemory/mcp] tools/list proxy failed: ${err instanceof Error ? err.message : String(err)}; falling back to local list\n`);
 	}
 	const fallback = getAllTools().filter((t) => IMPLEMENTED_TOOLS.has(t.name));
 	if (debug) process.stderr.write(`[@agentmemory/mcp] tools/list: returning ${fallback.length} local fallback tools (${fallback.map((t) => t.name).join(",")})\n`);