#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import {
chmodSync,
closeSync,
existsSync,
mkdirSync,
openSync,
readFileSync,
readSync,
renameSync,
readdirSync,
statSync,
unlinkSync,
writeFileSync,
} from "node:fs";
import { execSync } from "node:child_process";
import { dirname, join, basename } from "node:path";
import { homedir, tmpdir } from "node:os";
import { resolveProject as canonicalProject } from "../_project.js";
import { workspaceFromCursorDb } from "./cursor-db.js";
// Cursor does not hand hooks a trustworthy working directory: `cwd` can be
// `.cursor`, the IDE install path (via VSCODE_CWD), or absent entirely. This
// module is the Cursor-specific piece of the adapter — everything it exists
// to do is turn whatever Cursor sends into a real project directory, so the
// canonical hooks in src/hooks/*.ts can stay unchanged.
const HOME = homedir();
const CURSOR_PROJECTS_DIR = join(HOME, ".cursor", "projects");
const SESSION_CACHE_PATH = join(HOME, ".cursor", "hooks", ".agentmemory-session-cache.json");
const HOOK_PAYLOAD_DIR = join(HOME, ".cursor", "hooks", ".am-hook-payloads");
export interface Workspace {
project: string;
cwd: string;
}
export type HookData = Record<string, unknown> | null | undefined;
interface SessionCacheEntry {
project: string;
cwd: string;
updatedAt: string;
}
type SessionCache = Record<string, SessionCacheEntry>;
const SESSION_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
const SESSION_CACHE_MAX_ENTRIES = 200;
export function normalizePathSlashes(value: unknown): string {
return String(value).replace(/\\/g, "/");
}
export function isCursorMetadataPath(value: unknown): boolean {
if (!value || typeof value !== "string") return false;
const trimmed = normalizePathSlashes(value.trim());
if (trimmed === ".cursor") return true;
// ~/.cursor/worktrees/<name> is the exception: Cursor puts real git
// checkouts there for its background agents. Treating those as metadata
// sends the session to whatever the transcript scan guesses instead of to
// the repository the agent is actually editing.
if (/(^|\/)\.cursor\/worktrees\/[^/]/.test(trimmed)) return false;
return /(^|\/)\.cursor(\/|$)/.test(trimmed);
}
export function pathUnderHome(value: unknown): boolean {
if (typeof value !== "string") return false;
const homeNorm = normalizePathSlashes(HOME);
const valueNorm = normalizePathSlashes(value);
return valueNorm === homeNorm || valueNorm.startsWith(`${homeNorm}/`);
}
// VSCODE_CWD points at the Cursor install directory, which resolves to a
// project literally named "cursor" if it is allowed through.
function isIdeInstallPath(value: unknown): boolean {
if (!value || typeof value !== "string") return false;
const norm = normalizePathSlashes(value).toLowerCase();
return (
/(^|[\\/])(programs|program files|program files \(x86\))[\\/]cursor([\\/]|$)/i.test(norm) ||
/cursor\.app[\\/]contents/i.test(norm) ||
/(^|[\\/])microsoft vs code[\\/]resources[\\/]app([\\/]|$)/i.test(norm)
);
}
function isBadPath(value: unknown): boolean {
if (!value || typeof value !== "string") return true;
const trimmed = normalizePathSlashes(value.trim());
if (!trimmed || trimmed === "/" || trimmed === ".") return true;
// A bare drive root is never a project. Cursor emits a single-letter
// transcript slug for some legacy windows ("c"), which decodes to "C:".
if (/^[a-zA-Z]:\/?$/.test(trimmed)) return true;
if (isCursorMetadataPath(trimmed)) return true;
if (isIdeInstallPath(trimmed)) return true;
return false;
}
function sleepMs(ms: number): void {
const end = Date.now() + ms;
while (Date.now() < end) {
// Busy wait: this runs inside a lock retry loop in a short-lived hook
// process, where blocking is cheaper than an async scheduler hop.
}
}
function withSessionCacheLock<T>(fn: () => T): T | undefined {
const lockPath = `${SESSION_CACHE_PATH}.lock`;
mkdirSync(dirname(SESSION_CACHE_PATH), { recursive: true });
let fd: number | undefined;
for (let i = 0; i < 50; i++) {
try {
fd = openSync(lockPath, "wx");
break;
} catch {
sleepMs(10);
}
}
if (fd === undefined) return undefined;
try {
return fn();
} finally {
closeSync(fd);
try {
unlinkSync(lockPath);
} catch {}
}
}
function loadSessionCache(): SessionCache {
try {
const value: unknown = JSON.parse(readFileSync(SESSION_CACHE_PATH, "utf-8"));
return value && typeof value === "object" && !Array.isArray(value) ? value as SessionCache : {};
} catch {
return {};
}
}
// Every hook is a fresh process that parses this file, so it is kept small:
// stale sessions are dropped and only the most recent entries survive.
function pruneSessionCache(cache: SessionCache, now: number): SessionCache {
const fresh = Object.entries(cache).filter(([, entry]) => {
const updated = Date.parse(entry?.updatedAt ?? "");
return typeof entry?.project === "string" && typeof entry?.cwd === "string" && Number.isFinite(updated) && now - updated < SESSION_CACHE_MAX_AGE_MS;
});
fresh.sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt));
return Object.fromEntries(fresh.slice(0, SESSION_CACHE_MAX_ENTRIES));
}
function rememberSession(sessionId: string | undefined, project: string, cwd: string): void {
if (!sessionId || !project || project === ".cursor") return;
withSessionCacheLock(() => {
try {
const now = Date.now();
const previous = loadSessionCache();
delete previous[sessionId];
const cache = pruneSessionCache({ [sessionId]: { project, cwd, updatedAt: new Date(now).toISOString() }, ...previous }, now);
const tmp = `${SESSION_CACHE_PATH}.${process.pid}.${Date.now()}.tmp`;
writeFileSync(tmp, JSON.stringify(cache, null, 2));
renameSync(tmp, SESSION_CACHE_PATH);
} catch {}
});
}
function recallSession(sessionId: string | undefined): SessionCacheEntry | null {
if (!sessionId) return null;
const cache = pruneSessionCache(loadSessionCache(), Date.now());
return Object.hasOwn(cache, sessionId) ? cache[sessionId]! : null;
}
// Absolute paths that belong to the OS rather than to any user project. A
// stray /usr/lib/... or /etc/... reference inside tool_input must not be
// allowed to resolve to a project named "lib" or "etc".
const SYSTEM_PATH_PREFIXES = [
"/usr/",
"/etc/",
"/bin/",
"/sbin/",
"/lib/",
"/lib64/",
"/opt/",
"/var/",
"/proc/",
"/sys/",
"/dev/",
"/run/",
"/boot/",
"/snap/",
"/nix/",
];
function isSystemPath(value: string): boolean {
const norm = normalizePathSlashes(value);
const temp = normalizePathSlashes(tmpdir()).replace(/\/$/, "");
if (norm.startsWith(`${temp}/`)) return false;
return SYSTEM_PATH_PREFIXES.some((prefix) => norm.startsWith(prefix));
}
// tool_input carries whatever shape the tool used, so paths are harvested by
// walking the object. The filter has to be permissive enough to find the
// project and strict enough not to invent one.
function isCollectablePath(value: unknown): value is string {
if (typeof value !== "string" || isCursorMetadataPath(value)) return false;
if (pathUnderHome(value)) return true;
// Windows drive-absolute: HOME is regularly on C: while the checkout sits
// on D:, so a HOME-only rule loses every cross-drive project.
if (/^[a-zA-Z]:[\\/]/.test(value)) return true;
// POSIX-absolute outside $HOME: containers (Codespaces, devcontainers)
// check repos out at /workspaces/..., which a HOME-only rule silently
// rejects. existingDirectory() and the git lookup downstream validate it.
if (value.startsWith("/")) return !isSystemPath(value);
return false;
}
function collectPathStrings(value: unknown, out: string[] = []): string[] {
if (typeof value === "string") {
if (isCollectablePath(value)) out.push(value);
return out;
}
if (Array.isArray(value)) {
for (const item of value) collectPathStrings(item, out);
return out;
}
if (value && typeof value === "object") {
for (const v of Object.values(value)) collectPathStrings(v, out);
}
return out;
}
function pathExists(pathValue: string): boolean {
if (existsSync(pathValue)) return true;
if (process.platform === "win32") {
const native = pathValue.replace(/\//g, "\\");
if (native !== pathValue && existsSync(native)) return true;
}
return false;
}
const MAX_ANCESTOR_STEPS = 64;
// Payloads often carry a file path (tool_input.path) rather than a
// directory, and sometimes a path that no longer exists. Walk up until
// something real is found, then normalise a file down to its directory.
function existingAncestor(pathValue: string): string | null {
let current = pathValue;
for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
if (!current || current === HOME || current === "/") return null;
if (pathExists(current)) {
const resolved = process.platform === "win32" ? current.replace(/\//g, "\\") : current;
try {
if (statSync(resolved).isFile()) {
return dirname(resolved);
}
} catch {}
return resolved;
}
// dirname() is a fixed point at every filesystem root -- dirname("//") is
// "//", dirname("C:") is "C:", dirname("D:/") is "D:/" -- so climbing
// without a progress check spins forever. Nothing produced such an input
// while this only ever saw $HOME-prefixed paths; a general path scan
// produces them constantly, because every "https://host/x" in a
// transcript contains a "//host/x".
const parent = dirname(current);
if (parent === current) return null;
current = parent;
}
return null;
}
function gitRootFromPath(targetPath: string): string {
return execSync("git rev-parse --show-toplevel", {
cwd: targetPath,
encoding: "utf-8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 500,
}).trim();
}
// Filesystem-only equivalent of `git rev-parse --show-toplevel`, for hot
// paths that would otherwise spawn a process per candidate. `.git` is a
// directory in a normal clone and a file in a linked worktree, so a plain
// existence check covers both.
function gitRootNearby(startPath: string): string | null {
let current = startPath;
for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
if (!current || current === "/") return null;
if (pathExists(join(current, ".git"))) return current;
const parent = dirname(current);
if (parent === current) return null;
current = parent;
}
return null;
}
interface ResolvedProject {
name: string;
/** Whether the name came from a git toplevel rather than a bare directory. */
fromGitRoot: boolean;
}
function projectFromPath(targetPath: string): ResolvedProject {
try {
return { name: canonicalProject(gitRootFromPath(targetPath)), fromGitRoot: true };
} catch {
return { name: canonicalProject(targetPath), fromGitRoot: false };
}
}
// Cursor names each directory under ~/.cursor/projects after the workspace
// path with every separator flattened to "-", so the transcript directory for
// a session already encodes where that session was running. Decoding it is
// lossy in one direction only: a directory name may itself contain hyphens,
// which makes "d-Andrew-Code-cc-router" mean D:/Andrew/Code/cc-router and,
// just as validly on paper, D:/Andrew/Code/cc/router.
//
// The disambiguator is the filesystem. Try every way of grouping consecutive
// segments into one directory name, but only descend into groupings that
// actually exist -- pruning collapses what looks like a 2^segments search
// into the handful of real directories on the machine.
function decodeSlugCandidates(slug: string): string[] {
if (!slug || slug === "empty-window") return [];
// Cursor 3.x names workspace-less windows (started from the welcome screen)
// after a timestamp. Those never correspond to a path.
if (/^\d{10,}$/.test(slug)) return [];
const parts = slug.split("-");
if (!parts.length) return [];
const results = new Set<string>();
function walk(index: number, currentPath: string): void {
if (index >= parts.length) {
results.add(currentPath);
return;
}
for (let take = 1; index + take <= parts.length; take++) {
const next = `${currentPath}/${parts.slice(index, index + take).join("-")}`;
if (!pathExists(next)) continue;
walk(index + take, next);
}
}
// A single leading letter is a Windows drive: "d-Andrew-Code" -> D:/Andrew/Code.
// Without this branch the whole function returns nothing on Windows, which
// is where HOME and the checkout most often sit on different drives.
const first = parts[0];
if (first && /^[a-zA-Z]$/.test(first)) walk(1, `${first.toUpperCase()}:`);
// Otherwise the slug starts at the filesystem root: "Users-alice-src",
// "home-andrew-src", "workspaces-repo".
walk(0, "");
return [...results];
}
function pickBestCandidate(candidates: string[], preferredLabel: string): string | null {
if (!candidates.length) return null;
if (preferredLabel) {
const labelMatch = candidates.find((p) => basename(p) === preferredLabel);
if (labelMatch) return labelMatch;
}
const gitRoots: string[] = [];
for (const candidate of candidates) {
try {
gitRoots.push(gitRootFromPath(candidate));
} catch {}
}
const uniqueGitRoots = [...new Set(gitRoots)];
if (uniqueGitRoots.length === 1) return uniqueGitRoots[0] ?? null;
return candidates.sort((a, b) => b.length - a.length)[0] ?? null;
}
function findSessionTranscript(
sessionId: string,
): { slug: string; transcriptFile: string | null } | null {
if (!sessionId || !existsSync(CURSOR_PROJECTS_DIR)) return null;
for (const slug of readdirSync(CURSOR_PROJECTS_DIR)) {
const transcriptsRoot = join(CURSOR_PROJECTS_DIR, slug, "agent-transcripts");
if (!existsSync(transcriptsRoot)) continue;
for (const entry of readdirSync(transcriptsRoot)) {
if (entry === sessionId || entry.startsWith(`${sessionId}-`)) {
const transcriptFile = join(transcriptsRoot, entry, `${entry}.jsonl`);
return {
slug,
transcriptFile: existsSync(transcriptFile) ? transcriptFile : null,
};
}
}
}
return null;
}
const TRANSCRIPT_SCAN_BYTES = 250000;
const TRANSCRIPT_CANDIDATE_LIMIT = 120;
const TRANSCRIPT_MATCH_LIMIT = 4000;
const TRANSCRIPT_MIN_VOTES = 3;
// Paths are normalised to forward slashes before matching, so a Windows path
// looks like "D:/repo/src/a.ts" by the time these run.
//
// Both patterns are a single character class with one bounded quantifier, on
// purpose. The obvious formulation -- /\/(?:[\w.-]+\/)+[\w.-]*/ -- nests a
// quantifier inside a quantifier, and on a 250KB transcript full of
// slash-bearing strings that backtracks badly enough to hang the hook for
// minutes. There is no clever matching to do here anyway: grab anything
// path-shaped and let the existence check below decide.
const TRANSCRIPT_PATH_PATTERNS = [
/[a-zA-Z]:[A-Za-z0-9._@+\-/]{3,240}/g, // Windows drive-absolute
/\/[A-Za-z0-9._@+\-/]{3,240}/g, // POSIX absolute
];
// Last resort before environment variables: mine the session transcript for
// paths and take the directory that shows up across the most of them.
//
// This used to anchor its regex on $HOME, which quietly made the whole layer
// dead on the two most common non-trivial setups -- Windows with HOME on C:
// and the checkout on D:, and containers that check out under /workspaces.
// Match any absolute path shape instead and let existence plus the git lookup
// downstream throw out the noise (URLs, log fragments, OS paths).
function workspaceFromTranscriptFile(transcriptFile: string | null): string | null {
if (!transcriptFile || !existsSync(transcriptFile)) return null;
let chunk: string;
const fd = openSync(transcriptFile, "r");
try {
const buffer = Buffer.alloc(TRANSCRIPT_SCAN_BYTES);
const bytes = readSync(fd, buffer, 0, buffer.length, 0);
chunk = normalizePathSlashes(buffer.subarray(0, bytes).toString("utf8"));
} finally { closeSync(fd); }
const counts = new Map<string, number>();
const seen = new Set<string>();
// Bounded on both axes: every candidate costs filesystem walks, and a busy
// transcript can contain thousands of path-shaped strings.
for (const pattern of TRANSCRIPT_PATH_PATTERNS) {
pattern.lastIndex = 0;
let match: RegExpExecArray | null;
let scanned = 0;
while ((match = pattern.exec(chunk)) !== null) {
if (++scanned > TRANSCRIPT_MATCH_LIMIT) break;
if (seen.size >= TRANSCRIPT_CANDIDATE_LIMIT) break;
const value = match[0];
if (seen.has(value)) continue;
seen.add(value);
// "//host/path" is the tail of a URL, not a filesystem path.
if (value.startsWith("//")) continue;
if (isCursorMetadataPath(value) || isIdeInstallPath(value) || isSystemPath(value)) continue;
// Only paths that still exist vote, and they vote for their git root.
//
// Both halves matter. Letting a path climb to whatever ancestor still
// exists (existingAncestor) means a deleted D:/repo/pkg/src/a.ts votes
// for D:/repo, and a transcript is full of such paths, so the
// shallowest common directory always wins -- a session in
// D:/Andrew/Code/pkg resolves to the project "Code". Counting existing
// directories as themselves instead just moves the problem: the winner
// becomes whatever generic directory the conversation mentioned most,
// which in practice is "/bin" or "C:/Users". Requiring a repository
// root is what makes a vote mean "this is a project".
const existing = existingDirectory(value);
if (!existing || existing === HOME || isBadPath(existing)) continue;
const root = gitRootNearby(existing);
if (!root || root === HOME || isBadPath(root)) continue;
counts.set(root, (counts.get(root) || 0) + 1);
}
}
let best: string | null = null;
let bestCount = 0;
for (const [pathValue, count] of counts) {
if (count > bestCount) {
best = pathValue;
bestCount = count;
}
}
// One passing mention of a repository is not evidence that the session was
// running in it. This layer is a guess of last resort, and a wrong guess
// files a user's memories under someone else's project -- worse than
// admitting the workspace is unknown.
return bestCount >= TRANSCRIPT_MIN_VOTES ? best : null;
}
function workspaceFromSessionId(sessionId: string): string | null {
const hit = findSessionTranscript(sessionId);
if (!hit) return null;
// Slug first. It is a lossy encoding of the workspace path, but every
// candidate it produces is verified against the filesystem, so a result is
// a directory that really exists and really matches the name Cursor gave
// this session's transcript directory.
const preferredLabel = process.env["CURSOR_WORKSPACE_LABEL"] || "";
const fromSlug = pickBestCandidate(decodeSlugCandidates(hit.slug), preferredLabel);
if (fromSlug) return fromSlug;
// Transcript scan last: it answers "which directory is mentioned most in
// this conversation", which is a guess, not a fact. Asked first it will
// happily answer "agentmemory" for a session about agentmemory that was
// actually running somewhere else entirely. It stays because it is the only
// thing that can place a workspace-less window that was still working on
// real files.
return workspaceFromTranscriptFile(hit.transcriptFile);
}
export function readHookStdinComplete(maxWaitMs = 30000): Promise<string> {
return new Promise((resolve) => {
let input = "";
let done = false;
const finish = (): void => {
if (done) return;
done = true;
try {
process.stdin.destroy();
} catch {}
resolve(input);
};
const t = setTimeout(finish, maxWaitMs);
if (t.unref) t.unref();
process.stdin.on("data", (c) => {
input += c;
});
process.stdin.on("end", () => {
clearTimeout(t);
finish();
});
process.stdin.on("error", () => {
clearTimeout(t);
finish();
});
});
}
export function writeHookPayloadTemp(input: string): string {
mkdirSync(HOOK_PAYLOAD_DIR, { recursive: true });
try {
chmodSync(HOOK_PAYLOAD_DIR, 0o700);
} catch {}
const path = join(HOOK_PAYLOAD_DIR, `am-hook-${process.pid}-${Date.now()}.json`);
writeFileSync(path, input, { encoding: "utf-8", mode: 0o600 });
return path;
}
export function readWorkerHookPayload(): Record<string, unknown> | null {
const file = process.env["AM_HOOK_INPUT_FILE"];
if (!file) {
console.error("[agentmemory] missing AM_HOOK_INPUT_FILE in worker");
return null;
}
try {
const raw = readFileSync(file, "utf-8");
const value: unknown = JSON.parse(raw);
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
} catch (err) {
console.error("[agentmemory] failed to parse hook payload:", (err as Error).message);
return null;
} finally {
try {
unlinkSync(file);
} catch {}
}
}
// Sessions were landing under ".codex": a path pointing into an agent's state
// directory walked up to ~/.codex and that became the project name.
//
// Rejecting every dot-named directory would be wrong, though. Plenty of real
// projects are dot-named -- ~/.dotfiles, ~/.emacs.d, ~/.config kept under
// chezmoi, and GitHub's own convention of a repository literally named
// ".github". What separates those from ~/.codex or ~/.vscode is not the name,
// it is that a human deliberately version controls them. So the rule is "a
// dot-named directory that is not a repository", which needs no list of tool
// names to keep up to date as new agents ship.
function isMetadataProject(project: ResolvedProject): boolean {
return project.name.startsWith(".") && !project.fromGitRoot;
}
function isHomeDirectory(pathValue: string): boolean {
return normalizePathSlashes(pathValue) === normalizePathSlashes(HOME);
}
// The path exactly, or its parent when it points at a file. Unlike
// existingAncestor() this does not climb: for a workspace path that some
// source claims is authoritative, "the directory is gone" means the record is
// stale, not "use whatever ancestor still exists". Climbing there silently
// turns D:/Andrew/Code/cc-router (moved away) into the project "Code" and
// files the session's memories under it.
function existingDirectory(pathValue: string): string | null {
if (!pathExists(pathValue)) return null;
const resolved = process.platform === "win32" ? pathValue.replace(/\//g, "\\") : pathValue;
try {
return statSync(resolved).isFile() ? dirname(resolved) : resolved;
} catch {
return null;
}
}
function resolveFromPathCandidates(
candidates: unknown[],
sessionId: string | undefined,
options: { exact?: boolean; remember?: boolean } = {},
): Workspace | null {
for (const candidate of candidates) {
if (typeof candidate !== "string" || isBadPath(candidate)) continue;
const existing = options.exact ? existingDirectory(candidate) : existingAncestor(candidate);
if (!existing || isBadPath(existing)) continue;
const project = projectFromPath(existing);
// $HOME is what a hook sees when the agent was launched with no workspace
// at all. Accepting it invents a project named after the account -- real
// sessions were being filed under "Andrew" with cwd C:\Users\Andrew --
// when the honest answer is that there is no workspace. Same carve-out as
// the dot-directory rule: allowed when HOME is itself a repository, which
// is the dotfiles-checked-out-in-$HOME layout.
if (isHomeDirectory(existing) && !project.fromGitRoot) continue;
if (!isMetadataProject(project)) {
if (options.remember !== false) rememberSession(sessionId, project.name, existing);
return { project: project.name, cwd: existing };
}
}
return null;
}
// Which layer answered is the single most useful thing to know when a session
// lands under the wrong project, and it is invisible from the outside: every
// layer returns the same shape. Set AM_CURSOR_DEBUG=1 to have the resolver say
// so on stderr, which Cursor surfaces in its hook log.
function debugLayer(layer: string, result: Workspace | null): Workspace | null {
if (result && process.env["AM_CURSOR_DEBUG"] === "1") {
console.error(`[agentmemory] workspace resolved by ${layer}: ${result.project} (${result.cwd})`);
}
return result;
}
export function resolveWorkspace(data: HookData): Workspace {
const sessionId = [data?.["session_id"], data?.["sessionId"], data?.["conversation_id"]].find((value): value is string => typeof value === "string" && Boolean(value.trim()));
// A cached workspace that has since moved or been deleted is stale; fall
// through so the current payload can replace it.
const cached = recallSession(sessionId);
if (cached?.cwd && !isBadPath(cached.cwd) && existingDirectory(cached.cwd)) {
return { project: canonicalProject(cached.cwd), cwd: cached.cwd };
}
const payloadCandidates: unknown[] = [
...(Array.isArray(data?.["workspace_roots"]) ? (data["workspace_roots"] as unknown[]) : []),
...(Array.isArray(data?.["workspace_folders"]) ? (data["workspace_folders"] as unknown[]) : []),
data?.["workspace_folder"],
data?.["workspaceFolder"],
data?.["workspace"],
data?.["cwd"],
data?.["root_path"],
data?.["project_path"],
];
const fromPayload = debugLayer("payload", resolveFromPathCandidates(payloadCandidates, sessionId));
if (fromPayload) return fromPayload;
const toolPaths = collectPathStrings(data?.["tool_input"] ?? data?.["toolArgs"])
.map(existingDirectory)
.filter((p): p is string => Boolean(p) && !isIdeInstallPath(p));
const fromTools = debugLayer("tool_input", resolveFromPathCandidates(toolPaths, sessionId));
if (fromTools) return fromTools;
if (sessionId) {
// Cursor's own record of where this session was running. Exact, so it is
// tried before the inference layers below -- it costs one indexed SQLite
// read (~5ms) and, because the result is cached per session, happens at
// most once per session rather than once per hook.
const fromDb = debugLayer(
"cursor-db",
resolveFromPathCandidates([workspaceFromCursorDb(sessionId)], sessionId, { exact: true }),
);
if (fromDb) return fromDb;
// Same validation as every other layer: both sources here already
// verified the directory exists, so `exact` keeps a stale one from
// silently climbing to a parent.
const fromSession = debugLayer(
"transcript-dir",
resolveFromPathCandidates([workspaceFromSessionId(sessionId)], sessionId, { exact: true }),
);
if (fromSession) return fromSession;
}
// Env comes last. CURSOR_PROJECT_DIR is Cursor's documented workspace root
// for hooks; the other two are explicit user overrides. Those are cached.
const authoritativeEnv: unknown[] = [
process.env["CURSOR_PROJECT_DIR"],
process.env["CURSOR_WORKSPACE_ROOT"],
process.env["CURSOR_WORKSPACE_FOLDER"],
];
const fromEnv = debugLayer("env", resolveFromPathCandidates(authoritativeEnv, sessionId));
if (fromEnv) return fromEnv;
// PWD and VSCODE_CWD only describe where the hook process was launched
// (VSCODE_CWD is often the IDE install directory), so they are used for
// this hook but never cached: later hooks with real evidence must win.
const launchEnv: unknown[] = [process.env["PWD"], process.env["VSCODE_CWD"]];
const fromLaunch = debugLayer(
"launch-env",
resolveFromPathCandidates(launchEnv, sessionId, { remember: false }),
);
if (fromLaunch) return fromLaunch;
const label = process.env["CURSOR_WORKSPACE_LABEL"];
if (label) return { project: label, cwd: label };
return { project: "unknown-project", cwd: "unknown-project" };
}
export function resolveProject(data: HookData): string {
return resolveWorkspace(data).project;
}