Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

9.8 KB
Raw Blame
/**
 * Exact session -> workspace lookup from Cursor's own SQLite storage.
 *
 * Everything else in the resolver infers the workspace: from payload fields
 * Cursor may or may not send, from paths that happen to appear in tool
 * arguments, from a transcript directory name whose path separators have been
 * flattened into hyphens. Those work, but they are inference, and inference
 * that lands on the wrong project writes a user's memories into the wrong
 * place without ever reporting an error.
 *
 * Cursor knows the answer exactly, and stores it. The layout (reverse
 * engineered; see integrations/cursor/README.md for the full picture):
 *
 *   <userdir>/globalStorage/state.vscdb
 *     ItemTable["composer.composerHeaders"]
 *       -> { allComposers: [ { composerId, workspaceIdentifier: {
 *              id, uri: { fsPath, ... } } } ] }
 *
 * A Cursor hook's `session_id` is the `composerId`, so one indexed lookup
 * gives the workspace path with no guessing.
 *
 * Two things stop this from being the only strategy:
 *
 *  - Cursor 3.0 (April 2026) moved this index from per-workspace databases
 *    into the global one, and the migration is lazy: a workspace migrates
 *    when it is next opened. Machines still on <=2.6, or with workspaces not
 *    opened since the upgrade, keep the old per-workspace `allComposers`
 *    array instead. Both shapes are handled below.
 *  - Reading SQLite needs a driver. `node:sqlite` only exists from Node 22.5,
 *    and this package supports Node >=20. better-sqlite3 is an optional
 *    dependency of the daemon, not something a hook can count on.
 *
 * So every failure path here returns null and the caller falls back to
 * inference. This module is an accuracy upgrade, never a requirement.
 */
import { createRequire } from "node:module";
import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";

const require = createRequire(import.meta.url);

interface Statement {
  get(...params: unknown[]): unknown;
}
interface DbHandle {
  prepare(sql: string): Statement;
  close(): void;
}
interface Driver {
  open(path: string): DbHandle;
}

// `undefined` = not probed yet, `null` = probed and unavailable.
let driverCache: Driver | null | undefined;

// node:sqlite is still flagged experimental and emits a process warning on
// load. Hook stderr is surfaced in Cursor's hook log, so that would put a
// paragraph about an implementation detail in front of the user on every
// session that reaches this module.
//
// The filter is installed once and left in place, rather than wrapped around
// the require, because process.emitWarning defers the actual emission to the
// next tick: restoring the original listeners in a `finally` happens before
// the warning is ever emitted, so the wrapping approach silences nothing. It
// is scoped as tightly as it can be -- only this one warning is dropped, and
// everything else is re-emitted untouched.
let warningFilterInstalled = false;

function suppressSqliteExperimentalWarning(): void {
  if (warningFilterInstalled) return;
  warningFilterInstalled = true;
  const previous = process.listeners("warning");
  process.removeAllListeners("warning");
  process.on("warning", (warning: Error) => {
    if (warning.name === "ExperimentalWarning" && /sqlite/i.test(warning.message)) return;
    for (const listener of previous) listener(warning);
  });
}

function requireQuietly<T>(id: string): T | null {
  suppressSqliteExperimentalWarning();
  try {
    return require(id) as T;
  } catch {
    return null;
  }
}

function loadDriver(): Driver | null {
  if (driverCache !== undefined) return driverCache;

  const nodeSqlite = requireQuietly<{ DatabaseSync: new (p: string, o?: object) => DbHandle }>(
    "node:sqlite",
  );
  if (nodeSqlite?.DatabaseSync) {
    driverCache = {
      open: (path) => new nodeSqlite.DatabaseSync(path, { readOnly: true }),
    };
    return driverCache;
  }

  // Same lazy-optional pattern the daemon uses for better-sqlite3 in
  // src/functions/migrate.ts -- used when installed, never required.
  const better = requireQuietly<new (p: string, o?: object) => DbHandle>("better-sqlite3");
  if (better) {
    driverCache = {
      open: (path) => new better(path, { readonly: true, fileMustExist: true }),
    };
    return driverCache;
  }

  driverCache = null;
  return driverCache;
}

/** Read one ItemTable value. Returns null for any failure, including a locked DB. */
function readItemTableValue(dbPath: string, key: string): string | null {
  if (!existsSync(dbPath)) return null;
  const driver = loadDriver();
  if (!driver) return null;

  let db: DbHandle | null = null;
  try {
    db = driver.open(dbPath);
    const row = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(key) as
      | { value?: unknown }
      | undefined;
    const value = row?.value;
    if (typeof value === "string") return value;
    if (value instanceof Uint8Array) return Buffer.from(value).toString("utf-8");
    return null;
  } catch {
    // Cursor holds the database open while running. Readers normally coexist
    // fine, but a locked or half-migrated file must not break the hook.
    return null;
  } finally {
    try {
      db?.close();
    } catch {}
  }
}

export interface CursorStorageRoots {
  globalStorage: string;
  workspaceStorage: string;
}

export function cursorStorageRoots(): CursorStorageRoots | null {
  const home = homedir();
  const bases: string[] = [];
  if (process.platform === "win32") {
    const appData = process.env["APPDATA"];
    if (appData) bases.push(join(appData, "Cursor", "User"));
    bases.push(join(home, "AppData", "Roaming", "Cursor", "User"));
  } else if (process.platform === "darwin") {
    bases.push(join(home, "Library", "Application Support", "Cursor", "User"));
  } else {
    const configHome = process.env["XDG_CONFIG_HOME"];
    if (configHome) bases.push(join(configHome, "Cursor", "User"));
    bases.push(join(home, ".config", "Cursor", "User"));
  }

  for (const base of bases) {
    const globalStorage = join(base, "globalStorage");
    if (existsSync(globalStorage)) {
      return { globalStorage, workspaceStorage: join(base, "workspaceStorage") };
    }
  }
  return null;
}

interface ComposerHeader {
  composerId?: unknown;
  workspaceIdentifier?: { uri?: { fsPath?: unknown; path?: unknown } };
}

function fsPathFromHeader(header: ComposerHeader | undefined): string | null {
  const uri = header?.workspaceIdentifier?.uri;
  const value = uri?.fsPath ?? uri?.path;
  return typeof value === "string" && value.trim() ? value : null;
}

/** Cursor 3.0+: one central index in the global database. */
function fromGlobalIndex(sessionId: string, roots: CursorStorageRoots): string | null {
  const raw = readItemTableValue(
    join(roots.globalStorage, "state.vscdb"),
    "composer.composerHeaders",
  );
  if (!raw) return null;
  try {
    const parsed = JSON.parse(raw) as { allComposers?: ComposerHeader[] };
    const hit = parsed.allComposers?.find((c) => c?.composerId === sessionId);
    // A hit with no uri is a workspace-less "empty window" chat -- Cursor
    // genuinely has no path for it, so neither do we.
    return fsPathFromHeader(hit);
  } catch {
    return null;
  }
}

/** `{"folder":"file:///d%3A/repo"}`, or a vscode-remote:// URI we cannot map. */
function folderFromWorkspaceJson(workspaceDir: string): string | null {
  const file = join(workspaceDir, "workspace.json");
  if (!existsSync(file)) return null;
  try {
    const parsed = JSON.parse(readFileSync(file, "utf-8")) as { folder?: unknown };
    const folder = parsed.folder;
    if (typeof folder !== "string" || !folder.startsWith("file://")) return null;
    return fileURLToPath(folder);
  } catch {
    return null;
  }
}

// Pre-3.0 lookup means opening one database per workspace, so it is ordered
// by recency and capped: the workspace a live session belongs to was touched
// moments ago and sits at the top. A full scan of ~120 workspaces measures
// around 200ms; this ordering turns the common case into one or two opens.
const LEGACY_SCAN_LIMIT = 40;

function fromLegacyWorkspaceDbs(sessionId: string, roots: CursorStorageRoots): string | null {
  if (!existsSync(roots.workspaceStorage)) return null;

  let dirs: Array<{ dir: string; mtime: number }>;
  try {
    dirs = readdirSync(roots.workspaceStorage)
      .map((dir) => {
        try {
          return { dir, mtime: statSync(join(roots.workspaceStorage, dir, "state.vscdb")).mtimeMs };
        } catch {
          return null;
        }
      })
      .filter((x): x is { dir: string; mtime: number } => x !== null)
      .sort((a, b) => b.mtime - a.mtime)
      .slice(0, LEGACY_SCAN_LIMIT);
  } catch {
    return null;
  }

  for (const { dir } of dirs) {
    const raw = readItemTableValue(
      join(roots.workspaceStorage, dir, "state.vscdb"),
      "composer.composerData",
    );
    if (!raw) continue;
    try {
      const parsed = JSON.parse(raw) as { allComposers?: Array<{ composerId?: unknown }> };
      // Migrated workspaces no longer carry allComposers; their sessions are
      // in the global index handled above.
      if (!Array.isArray(parsed.allComposers)) continue;
      if (!parsed.allComposers.some((c) => c?.composerId === sessionId)) continue;
      return folderFromWorkspaceJson(join(roots.workspaceStorage, dir));
    } catch {
      continue;
    }
  }
  return null;
}

/**
 * The workspace directory Cursor recorded for this session, or null when it
 * cannot be determined (no driver, no storage, workspace-less window, or a
 * remote URI that does not map to a local path).
 */
export function workspaceFromCursorDb(sessionId: string): string | null {
  if (!sessionId) return null;
  const roots = cursorStorageRoots();
  if (!roots) return null;
  return fromGlobalIndex(sessionId, roots) ?? fromLegacyWorkspaceDbs(sessionId, roots);
}