Skip to content

Home

Jump to bottom
Stewart F edited this page Feb 7, 2026 · 4 revisions

Welcome to the CursorOOM-OutOfMemory-ClearCacheScript wiki!

Clear Cursor Cache Script — Wiki Home

Quick links: What is this? · Why use it? (OOM) · Benefits · Quick start · Options at a glance · Important notes · Full guide

What is this?

The Clear Cursor Cache script is an interactive PowerShell tool that helps you free disk space and reduce memory use in Cursor by:

  • Cleaning caches — Cache, CachedData, Code Cache, GPUCache, logs.
  • Pruning state databases — Shrinking Cursor’s SQLite state.vscdb files (workspace and global) with safe VACUUM or targeted key deletion.

You get a simple menu (5 options) and, when you choose “Analyze”, the ability to delete specific data (e.g. old chat bubbles, checkpoints, agent blobs) with an option to keep the last N items so you don’t lose everything.

Script: scripts/clear-cursor-cache.ps1
Dependencies: PowerShell, Node.js (for options 2, 3, 5), SQLite (sqlite3 for pruning/deleting).

Why use it? (OOM crashes)

Cursor stores a lot of data locally:

  • Cache directories — Built up over time and can use a lot of disk and memory when scanned.
  • Global state database — A single SQLite file (state.vscdb) that holds:
    • Chat bubbles (Composer/chat content)
    • Composer checkpoints (session snapshots)
    • Agent/blob cache (model outputs, context)
    • Extension and UI state

As you use Cursor over weeks or months, this file can grow to 500 MB–1 GB+. Cursor loads and queries it often; when it gets very large, that can contribute to:

  • Out of Memory (OOM) errors
  • Repeated Cursor crashes (especially after long sessions or many conversations)
  • Slow startup or freezes

Using this script helps by:

  1. Clearing caches — Frees disk and reduces in-memory cache pressure.
  2. Shrinking the state database — VACUUM reclaims space; optional deletion of old bubbles/checkpoints/blobs can free hundreds of MB and reduce load on Cursor.

If you are repeatedly hitting OOM or Cursor is crashing, running the script (with Cursor closed) is a practical first step to get back to a stable state.

Benefits

Benefit Description
Fewer OOM and crashes Smaller state.vscdb and cleared caches reduce memory and disk pressure so Cursor is less likely to run out of memory or crash.
Targeted cleanup You choose what to remove: only caches, only VACUUM, or specific data (bubbles, checkpoints, blobs) with optional “keep last N”.
Transparency “Analyze” shows exactly what is using space (tables and top keys by size) so you can decide what to prune.
Graduated options From safest (VACUUM only, no row deletion) to light (caches only) to full (caches + workspace/history) to key-level deletion.
Your code is safe Only Cursor’s own cache and state files are touched. Your projects and source code are not modified or deleted.
Integrity check The underlying script can run SQLite integrity checks on state.vscdb so you can verify the file is healthy before or after pruning.

Quick start

  1. Close Cursor (and Cursor Agent/Helper if running).
  2. Open PowerShell and go to your repo root (parent of scripts/).
  3. Run: 
    powershell -ExecutionPolicy Bypass -File .\scripts\clear-cursor-cache.ps1
    Or: .\scripts\clear-cursor-cache.ps1 if you’re already in the repo root.
  4. Choose an option (see Options at a glance below).
  5. Recommended for OOM: Choose 5 (Analyze) to see what’s large, then optionally run a sub-option (e.g. 4 for agent blobs) and choose A (all) or K (keep last N).
  6. Restart Cursor. If you see a run-time error when connecting after deleting bubbles/checkpoints/blobs, create a “New Agent” in Cursor to continue.

Requirements: Windows, PowerShell, Node.js, and SQLite (sqlite3) for options 2, 3, and 5. Install SQLite e.g. via choco install sqlite or sqlite.org.

Options at a glance

# Option Best for Impact
1 Full cache cleanup Maximum space free; you’re OK losing recent workspaces list and local file history Stops Cursor, deletes caches + workspaceStorage + History. Settings/extensions kept.
2 Prune workspace state.vscdb This project’s state DB is large VACUUM only. Safe, no row deletion.
3 Prune global state.vscdb Global DB is large; you want the safest shrink VACUUM only. Safe, no row deletion. Good first step for OOM.
4 Light cleanup (caches only) Free space but keep workspaces list and file history Stops Cursor, deletes only cache dirs.
5 Analyze global state.vscdb See what’s using space; then optionally delete by pattern (bubbles, checkpoints, blobs, etc.) Read-only report, then optional sub-menu: delete all or keep last N. Use this when you need big reductions (100–400+ MB).

After option 5 you can choose sub-options (1–4 for cursorDiskKV data). If you fully prune those, the script shows a Final Note: after restart you may need to create a “New Agent” in Cursor.

Important notes

  • Close Cursor before running options 1–5 for reliable results and to avoid file locks.
  • Option 1 is the only option that removes workspaceStorage and History (recent workspaces list and local file history). Use option 4 if you want to keep those.
  • Sub-options 1–4 (under option 5) delete Cursor-stored conversation/checkpoint/blob data. Your code and projects are not touched.
  • If SQLite is not installed, options 2, 3, and 5 (prune/delete) will fail. Install sqlite3 and ensure it’s on PATH or in a standard Windows location.

More information

  • Full product spec & user guide: README_CLEAR_CURSOR_CACHE.md — Prerequisites, all features, risks & mitigations, outputs, technical details, FAQ.
  • Scripts:
    • clear-cursor-cache.ps1 — Interactive menu (run this).
    • prune-state-vscdb.ts — Underlying logic (VACUUM, analyze, delete by pattern, integrity check); can be run directly with npx tsx scripts/prune-state-vscdb.ts and flags.

This wiki page is the main entry point for the Clear Cursor Cache script. Use it when Cursor is repeatedly hitting OOM or crashing due to large state databases and caches.

Clone this wiki locally