feat(browser): add site memory for persistent cross-session knowledge

[shubh24]

Summary

• Adds a site memory system to the browser skill that remembers page structures, selectors, and interaction patterns across Claude Code sessions
• On repeat visits to a site, Claude reads cached selectors from ${CLAUDE_SKILL_DIR}/memory/<domain>.md and uses them directly — skipping the browse snapshot step entirely
• Memory files are stored inside the skill directory itself (~/.claude/skills/browser/memory/), making them global across projects with no permission issues

How it works

1. Before browsing: Claude runs a setup block that checks for a memory file for the target domain
2. If memory exists: Claude uses cached selectors directly (e.g., browse click ".titleline > a") without snapshotting
3. If no memory / selector fails: Falls back to browse snapshot as usual
4. After browsing: Claude writes/updates the memory file with elements, selectors, patterns, and notes

Key changes to SKILL.md

• allowed-tools: Bash → Bash Read Write Edit Glob (needed for memory file I/O)
• Restructured as Step 1 (setup + memory read) → Step 2 (browse) → Step 3 (memory write)
• Added concrete code examples showing cached selector usage
• All existing CLI features (env local/remote, --auto-connect, --context-id, --persist) preserved

Why this matters

Every browse snapshot call costs ~200ms CDP + 2-5s LLM reasoning about the page tree. With site memory, repeat visits can skip both — Claude already knows the selectors. This is especially impactful for:

• Internal tools teams visit daily
• Multi-page flows (login → dashboard → settings)
• CI/automation where the same sites are browsed repeatedly

Test plan

• Fresh session: browse a site → verify memory file is created at ~/.claude/skills/browser/memory/<domain>.md
• Warm session: browse the same site → verify Claude reads memory first and attempts cached selectors before snapshotting
• Stale selector: manually break a selector in the memory file → verify Claude falls back to snapshot and updates the file
• Multi-site: browse two different sites → verify separate memory files are created

🤖 Generated with Claude Code

---

Note

Medium Risk
Primarily updates the browser skill documentation/workflow, but it also expands allowed-tools to include filesystem read/write/edit/glob access, which increases the blast radius if misused.

Overview
Adds a site memory workflow to the browser skill instructions: a mandatory pre-flight step to check ${CLAUDE_SKILL_DIR}/memory/<domain>.md, preferentially use cached selectors to avoid browse snapshot, and a mandatory post-task step to write/update per-domain memory files with stable selectors and interaction patterns.

Updates the recommended browsing workflow/examples and troubleshooting to reflect the new memory-first behavior, and expands allowed-tools from Bash to Bash Read Write Edit Glob to support maintaining these memory files.

^{Reviewed by Cursor Bugbot for commit efee8bf. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Memory feature uses CSS selectors with ref-only click command
  • Updated the browser skill memory guidance and example so cached CSS selectors are used only with selector-based commands while browse click explicitly requires snapshot refs.

Or push these changes by commenting:

@cursor push d75a9f3a40

Preview (d75a9f3a40)

diff --git a/skills/browser/SKILL.md b/skills/browser/SKILL.md
--- a/skills/browser/SKILL.md
+++ b/skills/browser/SKILL.md
@@ -33,15 +33,15 @@
 
 Replace MEMORY_FILE with the domain, using dashes for dots/colons/slashes (e.g., `news-ycombinator-com`, `github-com`, `localhost-3000`).
 
-**If site memory exists**: You have selectors from previous visits. After `browse open`, use them IMMEDIATELY. Do NOT run `browse snapshot`. Example:
+**If site memory exists**: You have selectors from previous visits. After `browse open`, use them IMMEDIATELY for selector-based commands. If you need to click, run `browse snapshot` first to get refs. Example:
 
 ```bash
 # Memory says story titles use ".titleline > a" — use it directly:
 browse open https://news.ycombinator.com
-browse click ".titleline > a"              # ← use cached selector, NO snapshot
+browse get text ".titleline > a"           # ← use cached selector, NO snapshot

-Only run browse snapshot if a cached selector FAILS (returns an error). Trust the memory.
+Run browse snapshot when you need click refs or if a cached selector fails (returns an error). Trust the memory.

If no memory exists: After browse open, use browse snapshot to discover the page.

@@ -151,7 +151,7 @@

Rules for memory files:
-- Record **stable selectors**: `input[name="email"]`, `[data-testid="..."]`, `button[type="submit"]` — NOT just snapshot refs like `@0-5`
+- Record **stable selectors** for selector-based commands (`get`, `fill`, `is`, `highlight`): `input[name="email"]`, `[data-testid="..."]`, `button[type="submit"]` — NOT just snapshot refs like `@0-5`
- Use **URL patterns**: `/users/:id` not `/users/123` when pages share structure
- Note **async behavior**: "table loads after ~2s", "button disabled until form valid"
- Be **generous**: record all interactive elements, not just the ones you used
@@ -163,8 +163,8 @@

1. **Read site memory** (MANDATORY): `cat ${CLAUDE_SKILL_DIR}/memory/<domain>.md`
2. `browse open <url>` — navigate to the page
-3. If memory had selectors, use them directly. Otherwise: `browse snapshot`
-4. Interact: `browse click` / `browse type` / `browse fill`
+3. If memory had selectors, use them directly for selector-based commands. If you need to click (or have no memory): `browse snapshot`
+4. Interact: `browse click` (ref from snapshot) / `browse type` / `browse fill`
5. `browse snapshot` to confirm (if needed)
6. Repeat 3-5
7. **Write site memory** (MANDATORY): update `${CLAUDE_SKILL_DIR}/memory/<domain>.md`
@@ -208,7 +208,7 @@
1. **ALWAYS read site memory before browsing** — this is not optional
2. **ALWAYS write site memory after browsing** — this is not optional
3. **Choose the local strategy deliberately**: `browse env local` for clean state, `--auto-connect` for existing credentials, `remote` for protected sites
-4. **Use `browse snapshot`** only when no memory exists or cached selectors fail
+4. **Use `browse snapshot`** when no memory exists, when cached selectors fail, or when you need refs for `browse click`
5. **Only screenshot when visual context is needed** (layout checks, images, debugging)
6. **Use refs from snapshot** to click/interact — e.g., `browse click @0-5`
7. **`browse stop`** when done to clean up the browser session and clear the env override

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit efee8bf. Configure here.}

[cursor]

Memory feature uses CSS selectors with ref-only click command

High Severity

The memory feature's core optimization — caching CSS selectors and using them directly to skip snapshots — is built on the assumption that browse click accepts CSS selectors. However, per the REFERENCE.md and every example in EXAMPLES.md, browse click only accepts snapshot refs (e.g., @0-5), not CSS selectors. The example browse click ".titleline > a" will fail. The memory system instructs recording "stable selectors" like input[name="email"] and [data-testid="..."], but these cannot be used with the primary interaction command.

Additional Locations (2)

• skills/browser/SKILL.md#L153-L154
• skills/browser/SKILL.md#L102-L103

 

^{Reviewed by Cursor Bugbot for commit efee8bf. Configure here.}