@pharaoh-so/mcp 0.3.59 → 0.3.61

package/project-memory/graph-cues.mjs

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { gitBefore, sessionKey, updateWorktreeCueState } from "./local.mjs";
+
+const MAP_TOOL = "mcp__pharaoh__get_codebase_map";
+const SHA = /^(?!0{40}$)[a-f0-9]{40}$/i;
+const DIGEST = /^[a-f0-9]{64}$/;
+const MAPPED_FILE = /\.(?:[cm]?[jt]s|[jt]sx|py)$/i;
+const STATE_TTL = 12 * 60 * 60 * 1000;
+const MAX_SCOPES = 8;
+const MAX_SEARCHES = 2;
+const MAX_WARNED = 8;
+const MAX_EDIT_PATHS = 20;
+const MAX_SOURCE_BYTES = 512 * 1024;
+
+function digest(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function responseText(value) {
+	if (typeof value === "string") {
+		if (/^\s*[[{]/.test(value)) {
+			try {
+				return responseText(JSON.parse(value));
+			} catch {
+				return [];
+			}
+		}
+		return [value];
+	}
+	if (value?.isError || value?.is_error) return [];
+	const content = Array.isArray(value) ? value : value?.content;
+	return Array.isArray(content)
+		? content.flatMap((block) =>
+				block?.type === "text" && typeof block.text === "string" ? [block.text] : [],
+			)
+		: [];
+}
+
+function mappedRevision(input, target, repos) {
+	const requested = input.tool_input?.repo;
+	if (typeof requested !== "string") return;
+	const full = target.repo.toLowerCase();
+	const short = full.split("/")[1];
+	if (requested.toLowerCase() !== full) {
+		if (requested.toLowerCase() !== short) return;
+		const matches = new Set(
+			repos
+				.filter((repo) => typeof repo === "string")
+				.map((repo) => repo.toLowerCase())
+				.filter((repo) => repo.split("/").at(-1) === short),
+		);
+		if (matches.size !== 1 || !matches.has(full)) return;
+	}
+	const maps = responseText(input.tool_response).filter((text) =>
+		text
+			.split(/\r?\n/)
+			.some((line) =>
+				[`# ${short} codebase map`, `# ${full} codebase map`].includes(line.toLowerCase()),
+			),
+	);
+	if (maps.length !== 1) return;
+	const revisions = [...maps[0].matchAll(/^Indexed commit: ([^\r\n]+)\r?$/gm)];
+	const revision = revisions.length === 1 && revisions[0][1];
+	if (revision && SHA.test(revision)) return revision.toLowerCase();
+}
+
+function editedPaths(input, client, root) {
+	let paths;
+	if (client === "codex") {
+		if (input.tool_name !== "apply_patch") return [];
+		const patch = input.tool_input?.command;
+		const succeeded = responseText(input.tool_response).some((text) =>
+			/^Success\. Updated the following files:/m.test(text),
+		);
+		if (!succeeded || typeof patch !== "string" || !patch.startsWith("*** Begin Patch\n"))
+			return [];
+		paths = [
+			...patch.matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/gm),
+		].map((match) => match[1]);
+	} else {
+		if (!["Edit", "Write", "MultiEdit"].includes(input.tool_name)) return [];
+		paths = [input.tool_input?.file_path];
+	}
+	if (paths.length > MAX_EDIT_PATHS) return [];
+	const inCheckout = paths.flatMap((path) => {
+		if (typeof path !== "string" || path.length > 512 || !MAPPED_FILE.test(path)) return [];
+		const absolute = resolve(input.cwd ?? root, path);
+		let parent;
+		try {
+			parent = realpathSync(dirname(absolute));
+		} catch {
+			return [];
+		}
+		const local = relative(root, join(parent, basename(absolute)));
+		if (!local || local === ".." || local.startsWith(`..${sep}`) || isAbsolute(local)) return [];
+		return [local];
+	});
+	return [...new Set(inCheckout)];
+}
+
+function worktreeBlob(path, remaining) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	} catch (error) {
+		return error.code === "ENOENT" ? null : undefined;
+	}
+	try {
+		const before = fstatSync(fd);
+		if (!before.isFile() || before.size > remaining) return;
+		const bytes = Buffer.alloc(before.size);
+		if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) return;
+		const after = fstatSync(fd);
+		if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) return;
+		return {
+			size: bytes.length,
+			oid: createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex"),
+		};
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function changedPaths(root, revision, paths, deadline, git) {
+	const comparisonDeadline = Math.min(deadline, performance.now() + 700);
+	const run = (...args) =>
+		git(
+			root,
+			Math.min(comparisonDeadline, performance.now() + 300),
+			"--literal-pathspecs",
+			...args,
+		);
+	try {
+		// Git reads tree and index metadata only. Hash raw regular-file bytes
+		// locally so checkout attributes cannot invoke an executable filter.
+		const tree = run("ls-tree", "-rz", revision, "--", ...paths);
+		const indexed = new Map(
+			tree
+				.split("\0")
+				.filter(Boolean)
+				.map((entry) => {
+					const tab = entry.indexOf("\t");
+					const [mode, type, oid] = entry.slice(0, tab).split(" ");
+					return [
+						entry.slice(tab + 1),
+						/^100(?:644|755)$/.test(mode) && type === "blob" && SHA.test(oid) ? oid : null,
+					];
+				}),
+		);
+		const added = paths.filter((path) => !indexed.has(path));
+		const visible = added.length
+			? new Set(
+					run("ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...added).split(
+						"\0",
+					),
+				)
+			: new Set();
+		let remaining = MAX_SOURCE_BYTES;
+		const changed = [];
+		for (const path of paths) {
+			if (performance.now() >= comparisonDeadline) return [];
+			const previous = indexed.get(path);
+			if (!previous && !visible.has(path)) continue;
+			const local = worktreeBlob(join(root, path), remaining);
+			if (local === undefined) continue;
+			remaining -= local?.size ?? 0;
+			if ((local?.oid ?? undefined) !== previous) changed.push(digest(path));
+		}
+		if (performance.now() >= comparisonDeadline) return [];
+		return changed;
+	} catch {
+		// A missing revision or failed comparison leaves the cue available for a later edit.
+		return [];
+	}
+}
+
+function validEntry(entry, now) {
+	return (
+		DIGEST.test(entry?.key ?? "") &&
+		Number.isFinite(entry.expires) &&
+		entry.expires > now &&
+		entry.expires <= now + STATE_TTL &&
+		(entry.revision === undefined || SHA.test(entry.revision)) &&
+		Array.isArray(entry.searches) &&
+		entry.searches.length <= MAX_SEARCHES &&
+		entry.searches.every((item) => typeof item === "string" && DIGEST.test(item)) &&
+		Array.isArray(entry.warned) &&
+		entry.warned.length <= MAX_WARNED &&
+		entry.warned.every((item) => typeof item === "string" && DIGEST.test(item))
+	);
+}
+
+/** Process local hook evidence without dispatching tools or retaining their payloads. */
+export function worktreeCue(
+	input,
+	{
+		client,
+		target,
+		binding,
+		repos = [],
+		stateDirectory,
+		structuralSearch,
+		deadline = Infinity,
+		git = gitBefore,
+		now = Date.now(),
+	},
+) {
+	const session = sessionKey(client, input.session_id);
+	if (!session || !binding || performance.now() >= deadline) return;
+	const event = input.hook_event_name;
+	const search = event === "PreToolUse" && structuralSearch;
+	const revision =
+		event === "PostToolUse" && input.tool_name === MAP_TOOL && mappedRevision(input, target, repos);
+	const paths = event === "PostToolUse" ? editedPaths(input, client, target.root) : [];
+	if (!search && !revision && !paths.length) return;
+	const key = digest(`${binding}\0${session}\0${target.root}\0${target.repo.toLowerCase()}`);
+
+	const context = updateWorktreeCueState(
+		stateDirectory,
+		(state) => {
+			if (state !== undefined && (state?.version !== 1 || !Array.isArray(state.entries))) return;
+			const entries = (state?.entries ?? [])
+				.filter((entry) => validEntry(entry, now))
+				.slice(0, MAX_SCOPES);
+			const existing = entries.find((entry) => entry.key === key);
+			const current = existing ? { ...existing } : { key, searches: [], warned: [] };
+			let notice;
+			if (revision) {
+				if (current.revision === revision) return;
+				current.revision = revision;
+				current.warned = [];
+			} else if (search) {
+				if (current.revision || current.searches.length >= MAX_SEARCHES) return;
+				const head = git(
+					target.root,
+					Math.min(deadline, performance.now() + 300),
+					"rev-parse",
+					"HEAD",
+				);
+				if (!SHA.test(head)) return;
+				const requested = digest(`${head}\0${search.tool}\0${search.symbol}`);
+				if (current.searches.includes(requested)) return;
+				current.searches = [...current.searches, requested];
+				notice = `For structural evidence on ${search.symbol}, try Pharaoh's ${search.tool}. The graph covers the indexed default branch. Use the current worktree for local changes.`;
+			} else {
+				if (!current.revision || current.warned.length >= MAX_WARNED) return;
+				const changed = changedPaths(target.root, current.revision, paths, deadline, git);
+				const unseen = changed.filter((path) => !current.warned.includes(path));
+				if (!unseen.length) return;
+				current.warned = [...current.warned, ...unseen].slice(0, MAX_WARNED);
+				notice = `The Pharaoh evidence consulted earlier reflects the indexed default branch at ${current.revision.slice(0, 12)}. This edited scope differs from that revision. Check the local diff or source before relying on that evidence.`;
+			}
+			if (performance.now() >= deadline) return;
+			current.expires = now + STATE_TTL;
+			return {
+				state: {
+					version: 1,
+					entries: [current, ...entries.filter((entry) => entry.key !== key)].slice(0, MAX_SCOPES),
+				},
+				context: notice,
+			};
+		},
+		now,
+	);
+	if (context) return { hookSpecificOutput: { hookEventName: event, additionalContext: context } };
+}

package/project-memory/hook-config.mjs

@@ -7,6 +7,7 @@ const EVENTS = {
 };
 const GLOBAL_MARKER = "# pharaoh-project-memory:user-v1";
 const LEGACY_MARKER = / # pharaoh-project-memory:[a-f0-9]{64}$/;
+const TOOL_EVENTS = ["PreToolUse", "PostToolUse"];
 
 function isObject(value) {
 	return value && typeof value === "object" && !Array.isArray(value);
@@ -33,14 +34,14 @@ function matchesUserHook(value) {
 }
 
 /** Keep unrelated handlers even when they share an event group with ours. */
-function replaceHooks(config, client, matches, command, installEvents = EVENTS[client]) {
+function replaceHooks(config, events, matches, additions) {
 	if (!isObject(config) || (config.hooks !== undefined && !isObject(config.hooks))) {
 		throw new Error("The existing hooks configuration is not a JSON object.");
 	}
 	const hooks = { ...config.hooks };
-	for (const event of EVENTS[client]) {
+	for (const event of events) {
 		const current = hooks[event];
-		const install = command && installEvents.includes(event);
+		const install = additions[event];
 		if (!install && (current === undefined || (Array.isArray(current) && !current.length)))
 			continue;
 		if (
@@ -54,7 +55,7 @@ function replaceHooks(config, client, matches, command, installEvents = EVENTS[c
 			if (rest.length === group.hooks.length) return [group];
 			return rest.length ? [{ ...group, hooks: rest }] : [];
 		});
-		if (install) kept.push({ hooks: [{ type: "command", command, timeout: 3 }] });
+		if (install) kept.push(install);
 		if (kept.length) hooks[event] = kept;
 		else delete hooks[event];
 	}
@@ -63,24 +64,50 @@ function replaceHooks(config, client, matches, command, installEvents = EVENTS[c
 		: { ...config, hooks };
 }
 
+function group(command, matcher) {
+	return { ...(matcher && { matcher }), hooks: [{ type: "command", command, timeout: 3 }] };
+}
+
 export function updateHooks(config, client, target, remove, hookPath, node = process.execPath) {
 	const marker = legacyMarker(client, target.root);
 	if (!remove && !hookPath) throw new Error("A pinned project memory hook is required.");
 	const command = remove
 		? null
 		: `${[node, hookPath, client, target.root, target.repo].map(shellWord).join(" ")} ${marker}`;
-	return replaceHooks(config, client, matchesLegacyHook(client, target.root), command);
+	const events = EVENTS[client];
+	const additions = command
+		? Object.fromEntries(events.map((event) => [event, group(command)]))
+		: {};
+	return replaceHooks(config, events, matchesLegacyHook(client, target.root), additions);
 }
 
-export function updateUserHooks(config, client, hookPath, node = process.execPath) {
-	const command = hookPath
-		? `${[node, hookPath, client, "--user"].map(shellWord).join(" ")} ${GLOBAL_MARKER}`
-		: null;
-	return replaceHooks(config, client, matchesUserHook, command, ["UserPromptSubmit"]);
+export function updateUserHooks(
+	config,
+	client,
+	hookPath,
+	node = process.execPath,
+	graphCues = false,
+) {
+	const additions = {};
+	if (hookPath) {
+		const command = (mode) =>
+			`${[node, hookPath, client, mode].map(shellWord).join(" ")} ${GLOBAL_MARKER}`;
+		additions.UserPromptSubmit = group(command("--user"));
+		if (graphCues) {
+			const graph = command("--graph");
+			const edit = client === "codex" ? "apply_patch" : "Edit|Write|MultiEdit";
+			additions.PreToolUse = group(graph, "^Bash$");
+			additions.PostToolUse = group(graph, `^(?:${edit}|mcp__pharaoh__get_codebase_map)$`);
+		}
+	}
+	const toolEvents = TOOL_EVENTS.filter(
+		(event) => additions[event] || hasHooks(config, [event], matchesUserHook),
+	);
+	return replaceHooks(config, [...EVENTS[client], ...toolEvents], matchesUserHook, additions);
 }
 
-function hasHooks(config, client, matches) {
-	return EVENTS[client].some((event) => {
+function hasHooks(config, events, matches) {
+	return events.some((event) => {
 		const groups = config?.hooks?.[event];
 		return (
 			Array.isArray(groups) &&
@@ -93,9 +120,9 @@ function hasHooks(config, client, matches) {
 }
 
 export function hasLegacyHooks(config, client, root) {
-	return hasHooks(config, client, matchesLegacyHook(client, root));
+	return hasHooks(config, EVENTS[client], matchesLegacyHook(client, root));
 }
 
 export function hasUserHooks(config, client) {
-	return hasHooks(config, client, matchesUserHook);
+	return hasHooks(config, [...EVENTS[client], ...TOOL_EVENTS], matchesUserHook);
 }

package/project-memory/hook-events.mjs

@@ -52,7 +52,7 @@ export function memoryReminder(repo) {
 	return {
 		hookSpecificOutput: {
 			hookEventName: "UserPromptSubmit",
-			additionalContext: `For work in ${repo}, use pharaoh_memory_recall if prior decisions may matter. Use pharaoh_memory_expand if you need the full record, and pharaoh_memory_capture for one supported candidate when the task permits. Mention memory only when it changes a decision.`,
+			additionalContext: `For work in ${repo}, call pharaoh_memory_recall before source inspection when prior decisions could matter. Use specific, non-sensitive terms. Use pharaoh_memory_expand only for needed evidence and pharaoh_memory_capture for one supported candidate when the user permits a write. Mention memory only if it changes a decision.`,
 		},
 	};
 }

package/project-memory/local.mjs

@@ -252,6 +252,35 @@ function recoverLock(path, now) {
 	return true;
 }
 
+function acquireLocalLock(directory, path, now) {
+	return (
+		acquireLock(directory, path, now) ??
+		(recoverLock(path, now) ? acquireLock(directory, path, now) : undefined)
+	);
+}
+
+/** Update only the bounded worktree cue metadata. Concurrent events can skip. */
+export function updateWorktreeCueState(directory, update, now = Date.now()) {
+	makePrivateDirectory(directory);
+	const release = acquireLocalLock(directory, join(directory, "worktree-cues.lock"), now);
+	if (!release) return;
+	try {
+		const path = join(directory, "worktree-cues.json");
+		const file = lstatSync(path, { throwIfNoEntry: false });
+		if (file && file.uid !== process.getuid?.()) return;
+		const before = file ? readJson(path) : undefined;
+		if (file && before === undefined) return;
+		const change = update(before);
+		if (!change) return;
+		const data = JSON.stringify(change.state);
+		if (Buffer.byteLength(data) > 8192) return;
+		atomicWrite(path, data);
+		return change.context;
+	} finally {
+		release();
+	}
+}
+
 /** Serialize local state transitions only; network operations never hold this lock. */
 export function turnStore(home = homedir(), now = Date.now) {
 	const directory = join(home, ".pharaoh", "project-memory-turns-v2");
@@ -276,9 +305,7 @@ export function turnStore(home = homedir(), now = Date.now) {
 		if (!TOKEN.test(key)) return;
 		const path = join(directory, `${key}.lock`);
 		const time = now();
-		const release =
-			acquireLock(directory, path, time) ??
-			(recoverLock(path, time) ? acquireLock(directory, path, time) : undefined);
+		const release = acquireLocalLock(directory, path, time);
 		if (!release) return onBusy?.();
 		try {
 			const stored = readJson(overlapPath(key));

package/project-memory/pharaoh-memory-hook.mjs

@@ -4,6 +4,8 @@ import { handleEvent, memoryReminder, skipMemoryPrompt } from "./hook-events.mjs
 import { readStdin } from "./local.mjs";
 import {
 	activeMemoryRuntime,
+	memoryClientRoot,
+	projectMemorySession,
 	readMemoryCredentials,
 	resolveMemoryHookTarget,
 } from "./user-target.mjs";
@@ -16,19 +18,49 @@ try {
 	const [client, root, repo] = process.argv.slice(2);
 	const input = await readStdin(1024 * 1024);
 	let result;
-	if (root === "--user") {
+	if (root === "--user" || root === "--graph") {
+		const reminder = root === "--user";
+		const event = input?.hook_event_name;
+		if (
+			reminder
+				? event !== "UserPromptSubmit" || skipMemoryPrompt(input.prompt)
+				: event !== "PreToolUse" && event !== "PostToolUse"
+		)
+			process.exit(0);
+		let structuralSearch;
+		if (event === "PreToolUse") {
+			if (input.tool_name !== "Bash") process.exit(0);
+			const { classifyBashGrep } = await import("./route-grep.mjs");
+			structuralSearch = classifyBashGrep(input.tool_input?.command);
+			if (!structuralSearch) process.exit(0);
+		}
 		const runtime = dirname(fileURLToPath(import.meta.url));
 		if (!activeMemoryRuntime(client, runtime)) process.exit(0);
-		if (input?.hook_event_name !== "UserPromptSubmit" || skipMemoryPrompt(input.prompt))
-			process.exit(0);
+		const { readHookPreferences } = await import("./preferences.mjs");
+		const choice = readHookPreferences()[client];
+		if (choice?.memory === false || (!reminder && choice?.graph === false)) process.exit(0);
+		const credentials = await readMemoryCredentials();
 		const eligible = await resolveMemoryHookTarget(
 			client,
 			input?.cwd,
-			await readMemoryCredentials(),
-			true,
+			credentials,
+			reminder,
 			deadline,
 		);
-		if (eligible && performance.now() < deadline) result = memoryReminder(eligible.repo);
+		if (!eligible || performance.now() >= deadline) process.exit(0);
+		if (reminder) result = memoryReminder(eligible.repo);
+		else {
+			const { worktreeCue } = await import("./graph-cues.mjs");
+			result = worktreeCue(input, {
+				client,
+				target: eligible,
+				binding: projectMemorySession(credentials),
+				repos: credentials?.repos,
+				stateDirectory: memoryClientRoot(),
+				structuralSearch,
+				deadline,
+			});
+		}
 	} else {
 		result = handleEvent(input, {
 			client,
@@ -38,7 +70,7 @@ try {
 			deadline,
 		});
 	}
-	if (result) process.stdout.write(JSON.stringify(result));
+	if (result && performance.now() < deadline) process.stdout.write(JSON.stringify(result));
 } catch {
 	// Project memory never blocks ordinary work or opens a continuation.
 } finally {

package/project-memory/preferences.d.mts

@@ -0,0 +1,12 @@
+export type MemoryHookClient = "claude-code" | "codex";
+export type HookPreferences = Partial<
+	Record<MemoryHookClient, { memory?: boolean; graph?: boolean }>
+>;
+export const MEMORY_HOOK_CLIENTS: readonly MemoryHookClient[];
+export function readHookPreferences(home?: string): HookPreferences;
+export function writeHookPreferences(
+	clients: HookPreferences,
+	home?: string,
+	expected?: HookPreferences,
+): void;
+export function resetHookPreferences(disable: boolean, home?: string): void;

package/project-memory/preferences.mjs

@@ -0,0 +1,70 @@
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { privateMemoryPath } from "./bundle.mjs";
+import { atomicWrite } from "./local.mjs";
+import { memoryClientRoot } from "./user-target.mjs";
+
+export const MEMORY_HOOK_CLIENTS = ["claude-code", "codex"];
+const FILE = "hook-preferences-v1.json";
+
+export function readHookPreferences(home = homedir()) {
+	const root = memoryClientRoot(home);
+	const path = join(root, FILE);
+	try {
+		privateMemoryPath(root, true);
+		if (privateMemoryPath(path, false).size > 1024)
+			throw new Error("Project memory preferences are too large.");
+		const { version, clients } = JSON.parse(readFileSync(path, "utf8"));
+		if (version !== 1 || !clients || typeof clients !== "object" || Array.isArray(clients))
+			throw new Error("Project memory preferences have an unknown format.");
+		for (const client of MEMORY_HOOK_CLIENTS) {
+			if (!Object.hasOwn(clients, client)) continue;
+			const choice = clients[client];
+			if (
+				!choice ||
+				typeof choice !== "object" ||
+				Array.isArray(choice) ||
+				["memory", "graph"].some(
+					(key) => Object.hasOwn(choice, key) && typeof choice[key] !== "boolean",
+				)
+			)
+				throw new Error("Project memory preferences contain an invalid choice.");
+		}
+		return clients;
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		throw error;
+	}
+}
+
+export function writeHookPreferences(clients, home = homedir(), expected) {
+	const previous = readHookPreferences(home);
+	if (expected && JSON.stringify(expected) !== JSON.stringify(previous))
+		throw new Error("Project memory preferences changed while setup was asking.");
+	if (JSON.stringify(clients) === JSON.stringify(previous)) return;
+	const root = memoryClientRoot(home);
+	const path = join(root, FILE);
+	if (Object.keys(clients).length === 0) {
+		rmSync(path, { force: true });
+		return;
+	}
+	mkdirSync(root, { recursive: true, mode: 0o700 });
+	privateMemoryPath(root, true);
+	atomicWrite(path, `${JSON.stringify({ version: 1, clients })}\n`);
+}
+
+export function resetHookPreferences(disable, home = homedir()) {
+	if (typeof process.getuid !== "function") return;
+	const choices = readHookPreferences(home);
+	for (const client of MEMORY_HOOK_CLIENTS) {
+		const choice = choices[client];
+		if (disable) choices[client] = { memory: false, graph: false };
+		else if (choice) {
+			if (choice.memory === true) delete choice.memory;
+			if (choice.graph === true) delete choice.graph;
+			if (Object.keys(choice).length === 0) delete choices[client];
+		}
+	}
+	writeHookPreferences(choices, home);
+}

package/project-memory/setup.d.mts

@@ -1,14 +1,40 @@
-export function syncMemoryHooks(options?: {
-	credentials?: {
-		sse_url: string;
-		project_memory?: Array<{ repo: string; revision: string | null }>;
-		project_memory_status?: "unavailable";
-	};
-	clients?: string[];
-	enable?: boolean;
+type MemoryCredentials = {
+	sse_url: string;
+	project_memory?: Array<{ repo: string; revision: string | null }>;
+	project_memory_status?: "unavailable";
+};
+
+type MemoryHookChoices = {
+	accepted: string[];
+	declined: string[];
+	graphClients: string[];
+	notices: string[];
+	removeUnentitled?: boolean;
+};
+
+type MemoryHookSetup = {
+	credentials?: MemoryCredentials;
 	home?: string;
 	env?: NodeJS.ProcessEnv;
 	cwd?: string;
 	node?: string;
 	packageRoot?: URL;
-}): string[];
+};
+
+export function chooseMemoryHooks(options: {
+	credentials?: MemoryCredentials;
+	clients: string[];
+	requested?: boolean;
+	ask: (question: string, defaultAnswer: boolean) => Promise<boolean | null>;
+	home?: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<MemoryHookChoices>;
+
+export function applyMemoryHookChoices(
+	decision: MemoryHookChoices,
+	options?: MemoryHookSetup,
+): string[];
+
+export function syncMemoryHooks(
+	options?: MemoryHookSetup & { clients?: string[]; graphClients?: string[]; enable?: boolean },
+): string[];