1. Bridging Live Browser Vision With Long-Term Agent Memory
AI assistants traditionally lose their footing in two predictable places: they cannot see the live web app running inside your signed-in browser, and they wake up with total amnesia every time you start a new session. Pairing Claude in Chrome with Anthropic’s Persistent Memory architecture closes both gaps in one seamless loop.
Quick Navigation
Why Spatial Sight and Temporal Memory Multiply Each Other
When you launch claude --chrome or steer Chrome from Claude Desktop, Claude reads real console errors, HTTP responses, and accessibility trees inside your existing browser logins. Once Claude solves a subtle staging quirk or learns your preferred component pattern, it writes a compact record into /memories or MEMORY.md so tomorrow’s session starts smarter instead of repeating yesterday’s debugging loop.
Architecture: Live Browser Telemetry to Consolidated Memory
MEMORY.md under 200 lines by storing deep details in topic files fetched just in time.
2. Setup, Extension Permissions & Memory Decision Matrix
Generally available across paid Claude plans (Pro, Max, Team, Ultra, and Enterprise), the Claude in Chrome extension pairs with both Claude Desktop and Claude Code while Anthropic’s memory stack separates human rules from learned state.
- Install Extension: Add Claude in Chrome from the Chrome Web Store, sign into the exact workspace org used by your CLI or app, and pin the side panel icon.
- Bridge Claude Code: Launch with
claude --chromeor run/chromeinside an active session to inspect pairing status and open tabs. - Bridge Claude Desktop: In Desktop settings, switch the Chrome extension policy from Block extension to Allow extension so Chat and Cowork sessions can drive tabs.
- macOS Host Tip: Desktop registers
com.anthropic.claude_browser_extensionwhile CLI usescom.anthropic.claude_code_browser_extension—keep the active bridge primary.
- Ask Before Acting (Manual): Pauses and asks Allow / Deny before clicking, submitting forms, or navigating—ideal for staging admin panels.
- Auto-Approve (Classifier-Screened): Runs multi-step flows smoothly while secondary background safety classifiers block risky actions or prompt on anomaly.
- Skip All Approvals: Bypasses prompts completely; reserve strictly for isolated local servers like
localhost:3000, never open web browsing. - Site Permissions: Manage approved domains in side-panel Settings → Permissions and Chrome’s
chrome://extensionssite-access selector.
claude --chrome in your project directory.
2. Type /chrome to verify the extension bridge is connected.
3. Type /memory to inspect loaded CLAUDE.md contracts and your active MEMORY.md index before testing a live tab.
Browser & Memory Architecture Decision Matrix
| Tool / Layer | Who Authorizes & Writes | When Loaded Into Context | Primary Guardrail | Best-Fit Job |
|---|---|---|---|---|
| Claude in Chrome GA Side Panel + MCP |
Extension reads live DOM, console, network; acts per approval mode. | On demand via tabs_context_mcp & page tools. |
Site allowlists, Dual classifiers & high-risk blocks. | Authenticated staging QA, UI parity, form & console debugging. |
| CLAUDE.md Static Contracts |
Humans edit and commit to Git repo or ~/.claude/CLAUDE.md. |
Loaded automatically in full at session startup. | Git PR code review before rules take effect. | Build commands, test targets, style standards, repo invariants. |
API Memory Toolmemory_20250818 |
Claude issues 6 CRUD calls; client app stores under /memories. |
Just-in-time: Claude calls view only when relevant. |
Canonical realpath root jail rejecting .. traversal. |
Long-running custom agents, user profiles & ticket scratchpads. |
| MEMORY.md + Dream Claude Code Auto-Memory |
Claude logs corrections; Auto-Dream prunes idle logs. | First 200 lines / ~25KB index loaded at boot. | 24h + 5-session gate; topic files keep index lean. | Cross-session fix history, developer preferences & workflow drift. |
| Playwright / Headless CI Test Runner |
Deterministic test scripts authored in repo suites. | Executed out-of-band via shell test runner. | Clean ephemeral browser profile per CI job. | Unattended nightly CI regressions & release gate suites. |
/memories or MEMORY.md.
3. Annotated Tour: Chrome Extension Bridge & Memory View
Inside a paired session, the Claude in Chrome side panel shares live tab context, console errors, and permission boundaries directly with your Claude Code terminal or Claude Desktop workspace and persistent /memories store.
TypeError: taxCode is undefined at CheckoutForm.tsx:142 • Network: POST /api/v2/checkout → 422
find("Submit Order") → form_input(#vat, "DE123456") → gif_creator saved 4-frame pass proof.
/checkout-smoke • Scheduled: Daily 08:30 • Tab Group: Indigo (3 tabs)
> memory.view("/memories/checkout_api.md")
> memory.str_replace(old="v1 payload", new="v2 taxCode object")
Run
pnpm test:e2e before commit; strict TypeScript mode.
Merged 6 staging notes; anchored tax API fix to 2026-11-14.
tabs_context_mcp): Discovers open tabs and isolates Claude inside color-coded tab groups so unrelated personal tabs stay untouched.
read_console_messages and failing API payloads via read_network_requests.
find, fills fields with form_input, and captures verification flows via gif_creator.
/ shortcuts and run them on daily or weekly schedules via the clock icon.
/memories CRUD: Inspects a lean index first, then reads or patches only relevant topic notes inside a path-jailed storage root.
CLAUDE.md Contracts vs. Idle Auto-Dream: Keep timeless human instructions in CLAUDE.md while background Auto-Dream cycles (triggered after 24+ hours and 5+ sessions) prune stale logs and keep MEMORY.md cleanly under 200 lines.
4. Live Chrome QA: Console Forensics & DOM Verification
Copy-pasting browser errors into chat wastes minutes and drops critical context. With claude --chrome or Claude Desktop connected to your extension, Claude drives the actual staging browser, catches runtime errors itself, patches your code, and re-tests immediately.
The 4-Stage Build-Verify Loop Inside Live Chrome
Run tabs_context_mcp to anchor Claude to your already-logged-in OAuth, SSO, or staging admin tab. Zero Playwright login boilerplate or expired cookie hacks needed.
Claude invokes read_console_messages and read_network_requests right after clicking submit, correlating React/Vue stack traces with exact 4xx/5xx JSON payloads.
Using read_page, find, and form_input, Claude exercises validation boundaries, checks desktop vs. mobile overflow, and verifies visual alignment against specs.
After editing source files in your terminal, Claude reloads the tab, confirms zero console errors remain, and optionally exports a quick gif_creator proof clip for PR review.
# Launch Claude Code with Chrome bridge active, verify status, and run a live forensic pass
$ claude --chrome
> /chrome
Bridge Status: Connected (Chrome Extension v1.x) | Active Tab Group: Staging-QA (2 tabs)
> Reproduce the EU VAT checkout failure on http://localhost:3000/checkout, read console & network
errors, fix CheckoutForm.tsx, re-submit with DE123456, and verify 200 OK with zero console logs.tabs_context_mcp keeps personal email, banking, or production dashboards safely excluded from its working tab group.
5. 5-Part Browser-to-Memory Anatomy & Chrome Shortcuts
Great browser workflows don’t stop at fixing one bug—they isolate the target tab, gather telemetry, verify the patch, save the earned lesson into /memories, and automate repeatable checks as saved Chrome / shortcuts.
The 5-Part Verified Debug & Persist Formula
| Component | What It Governs in Chrome & Memory | Failure Mode When Omitted |
|---|---|---|
| Tab & Origin Scope | Pins Claude to an explicit URL or color-coded MCP tab group. | Claude inspects the wrong tab or stalls waiting for tab selection. |
| Telemetry Probe | Requests concrete read_console_messages and read_network_requests proof. |
Agent guesses from visible UI copy instead of reading actual stack traces. |
| Patch & Re-Test | Forces an end-to-end live verification pass after code edits. | Edits compile locally but still crash inside real browser state. |
| Memory Persistence | Directs Claude to log durable facts via /memories CRUD tools. |
Same API quirk wastes another 20 minutes next week in a fresh session. |
| Safety Guardrail | Enforces Ask / Auto approval tiers and excludes prod or finance tabs. | Risky actions or accidental writes run on live customer accounts. |
/)
Save multi-step Chrome instructions (like smoke-testing forms or auditing PR preview URLs) as custom shortcuts in the side panel, then trigger them anytime by typing / followed by the shortcut name.
Click the clock icon in Chrome’s side panel to schedule any saved shortcut daily, weekly, monthly, or annually—compiling morning dashboard digests across multi-tab workspaces automatically.
# Example Saved Chrome Shortcut: /staging-smoke (Trigger manually or daily at 08:30 via Clock icon)
Scope: Open Staging-QA tab group (https://staging.acme.dev/dashboard, /billing-preview)
Steps: 1) Inspect get_page_text for banner alerts 2) Run read_console_messages(only_errors=true)
3) Flag any HTTP >= 400 from read_network_requests 4) Summarize deltas in side panelget_page_text, read_console_messages, read_network_requests) so unattended morning sweeps never submit forms or mutate live records.
6. Anthropic’s Native /memories Tool & Just-in-Time Recall
Instead of dumping sprawling chat histories into every prompt, Anthropic’s native Memory Tool (memory_20250818) gives Claude a structured /memories filesystem to manage long-term facts across sessions using just-in-time retrieval.
The 6 Native /memories File CRUD Commands
| Command | Exact Behavior & Parameters | Best-Practice Rule for Reliable Agents |
|---|---|---|
view |
Lists directory contents under /memories or reads file lines (supports optional view_range). |
Always invoke view at task start to orient on existing topic files before writing anything new. |
create |
Writes a brand-new file or overwrites an existing path using path + file_text. |
Call view first so Claude never clobbers valuable historical notes with an accidental overwrite. |
str_replace |
Replaces one exact unique match via old_str → new_str inside a target file. |
Prefer str_replace over create for surgical updates to preferences, API endpoints, or dates. |
insert |
Inserts insert_text right before 0-indexed insert_line inside an existing note. |
Ideal for appending new checklist items or dated changelog bullets without rewriting the whole file. |
delete |
Removes a single stale file or recursively deletes an obsolete folder under /memories. |
Prune retired experiments promptly and validate path boundaries strictly inside your client handler. |
rename |
Moves or renames old_path → new_path cleanly across your memory tree. |
Your server handler should throw an error if new_path already exists to prevent silent data loss. |
# Anthropic Messages API: Enable Native Memory Tool + Context Editing Beta Header
headers = {"anthropic-beta": "context-management-2025-06-27"}
tools = [{"type": "memory_20250818", "name": "memory"}]
# Claude emits structured client-side tool calls (read first, then patch surgically):
# 1) {"command": "view", "path": "/memories"}
# 2) {"command": "str_replace", "path": "/memories/api_contracts.md",
# "old_str": "Checkout endpoint: /api/v1/pay", "new_str": "Checkout endpoint: /api/v2/checkout"}Static Team Contracts vs. Dynamic Learned State
CLAUDE.md (Human-Authored Rules)- Committed in your repo root or
~/.claude/CLAUDE.mdand reviewed by teammates via Git PRs. - Defines canonical build/test commands, architecture invariants, and security boundaries.
- Loaded in full every session—keep it declarative and timeless.
/memories & MEMORY.md (Learned State)- Written dynamically by Claude (or stored under
~/.claude/projects/.../memory/) as it learns preferences and fixes. - 200-Line / ~25KB Boot Cap:
MEMORY.mdacts purely as an index; lines past 200 silently truncate! - Store rich notes in topic files fetched just in time via
view.
/memories/*.md file drops boot token bloat, reduces hallucinated stale rules, and pairs seamlessly with Anthropic’s context-editing tool-clearing beta.
7. Idle “Dreaming” Consolidation: Curing Agent Memory Rot
After fifteen or twenty busy sessions, raw auto-memory turns messy: yesterday’s workaround contradicts today’s refactor, relative phrases like “last Tuesday” lose meaning, and MEMORY.md overflows its 200-line ceiling. Inspired by biological REM sleep, Anthropic’s Auto-Dream reorganizes memory offline while you rest.
The 4-Phase Auto-Dream Cycle (Triggered at 24+ Hours & 5+ Sessions)
Surveys existing topic markdown files and checks line usage against MEMORY.md’s 200-line (~25KB) boot limit before touching anything.
Scans recent local .jsonl session transcripts using targeted grep queries for explicit user corrections and architectural decisions—skipping expensive full reads.
Resolves contradictions (keeping the latest verified rule), rewrites relative time like “yesterday” into ISO dates (2026-11-16), and deletes paths to removed code.
Moves detailed notes into focused topic files and rewrites MEMORY.md as a crisp table of contents well below 200 lines. Run anytime manually with /dream.
# Consolidated MEMORY.md Index (Kept Lean at 6 Lines vs. 200-Line Ceiling)
- [Staging Auth & Chrome QA](/memories/chrome_staging.md) — Verified 2026-11-14: use Staging-QA tab group
- [Checkout API v2 Migration](/memories/checkout_api.md) — Replaced Express handler with Fastify on 2026-11-10
- [User Coding Preferences](/memories/preferences.md) — Prefer pnpm, strict Zod schemas, zero inline mocks8. 5 Real-World Copy-Paste Chrome & Memory Recipes
Drop these battle-tested prompts straight into claude --chrome, Claude Desktop, Chrome side-panel shortcuts, or your custom API agent loop to pair live browser inspection with clean persistent memory updates.
| Recipe & Environment | Copy-Paste Prompt (Zero Ambiguous Placeholders) | Result & Memory Output |
|---|---|---|
1. Auth Bug → Console + Fix + Memoryclaude --chrome |
In our Staging-QA Chrome tab group on https://staging.acme.dev/checkout, submit the form with test VAT DE123456, capture console errors and failed network payloads, fix CheckoutForm.tsx, re-verify 200 OK in Chrome, and record the v2 payload schema in /memories/checkout_api.md using str_replace. |
Verified live fix + durable schema note preventing repeat regressions. |
2. Design Parity & GIF Proofclaude --chrome |
Open http://localhost:3000/pricing in Chrome, compare hero card spacing and button alignment at 1440px and 390px viewports against styles/tokens.css, patch any horizontal overflow, and use gif_creator to capture a 4-second click-through across plan toggles. |
Responsive CSS fix + shareable PR verification GIF without manual recording. |
| 3. Daily Multi-Tab Ops Digest Chrome / Shortcut + Clock |
Read all three tabs inside our Morning-Ops tab group (Sentry Triage, Vercel Deploys, Support Queue) using get_page_text without clicking destructive actions. Output a 6-bullet priority brief sorted by severity and store recurring flaky endpoint IDs in /memories/known_flakes.md. |
Hands-free 8:30 AM briefing across signed-in dashboards in 20 seconds. |
| 4. JIT API Memory Boot Messages API Harness |
Before answering this customer migration ticket, call memory.view on /memories to inspect available topic files, read only the matching database migration note, apply the user's updated Postgres 17 pooling limit via str_replace, and keep all other files untouched. |
Zero context bloat + atomic preference update via unique string replacement. |
| 5. Post-Sprint Consolidation Claude Code CLI |
Run /dream to orient on ~/.claude/projects/acme-web/memory/, gather signal from this week's .jsonl transcripts, convert relative dates to YYYY-MM-DD, delete references to retired src/legacy/ routes, and rebuild MEMORY.md cleanly under 120 lines. |
Contradiction-free index ready for fast next-sprint cold starts. |
# Drop Into Project Root CLAUDE.md: Enforce Memory Discipline + Chrome Verification
## Browser QA & Memory Rules
- Never store raw console logs in CLAUDE.md; write recurring environment findings to /memories/ via str_replace.
- Keep MEMORY.md purely as a concise index (<150 lines) linking focused topic markdown files.
- Before claiming any frontend bug fixed, verify zero console errors in Chrome via claude --chrome.create Defensiveview on a target /memories path before editing. Using str_replace or insert preserves older insights instead of wiping them with create.
9. Browser Security, Allowlists & Memory Hygiene
Because Claude in Chrome inherits your live cookies and MEMORY.md acts as high-authority startup guidance, browser security and memory sanitization belong in the same threat model.
- Semantic Trap: Malicious webpages, comments, or emails can hide text commands in white-on-white DOM nodes trying to hijack clicks or leak session data.
- Dual Safety Classifiers: Anthropic screens incoming page text and checks every automated browser action before execution, pausing or blocking risky steps.
- Patch Discipline: Keep Chrome and the Claude extension auto-updated (hardening origin allowlists & cross-extension boundaries against 2026 ShadowPrompt/ClaudeBleed vectors).
- High-Risk Category Blocks: Banking, crypto wallets, medical portals, and explicit domains are blocked by default so agents cannot transfer funds or alter records.
- Dedicated QA Chrome Profile: Run staging debugging inside a dedicated Chrome work profile—never alongside personal finance, password vaults, or production root consoles.
- Never Skip Approvals on Open Web: Reserve Skip all approvals strictly for offline/local builds; keep Ask or Auto enabled elsewhere.
Defense-in-Depth Boundary Matrix
| Attack / Drift Vector | How It Breaks Unprotected Workflows | Mandatory Hardening Control |
|---|---|---|
| DOM Prompt Injection | Untrusted GitHub issue or webpage tricks Claude into clicking transfer or exfiltration links. | Keep permission mode on Ask or Auto; restrict active sites in extension Settings → Permissions. |
Path Traversal in /memories |
Model emits ../../etc/passwd or /memories/../.env inside a client-side file handler. |
Canonicalize via realpath, strip/reject .., and assert path prefix stays inside root jail. |
CLAUDE.md / Memory Poisoning |
Untrusted PR or scraped page writes malicious shell directives into persistent memory files. | Never let web-reading workflows auto-edit CLAUDE.md; review MEMORY.md diffs before merging. |
# Python Client-Side /memories Path Jail (Prevents Directory Traversal Escapes)
from pathlib import Path
MEMORY_ROOT = Path("/srv/agent/workspaces/acme/memories").resolve()
def resolve_memory_path(raw_path: str) -> Path:
rel = raw_path.lstrip("/")
if not rel.startswith("memories"):
raise ValueError("Path must start with /memories")
candidate = (MEMORY_ROOT.parent / rel).resolve()
if candidate != MEMORY_ROOT and MEMORY_ROOT not in candidate.parents:
raise PermissionError(f"Blocked traversal outside jail: {raw_path}")
return candidateCLAUDE.md instructions.
10. Cross-Tool Synergy: Live Browser to Living Memory
When connected end to end, Claude in Chrome, Claude Desktop, Claude Code, /memories CRUD, and Auto-Dream form a closed engineering flywheel where every debugging session accelerates every session that follows.
Walking a Real Multi-Day Engineering Sprint Across All Layers
Start with claude --chrome inside your dedicated QA Chrome profile. Claude captures failing API headers via read_network_requests, fixes the bug, and verifies 200 OK with form_input.
Claude updates /memories/staging_quirks.md using str_replace while keeping timeless test commands inside human-reviewed CLAUDE.md.
A saved Chrome / shortcut runs on a daily clock schedule across your staging dashboards, reporting anomalies into Desktop Cowork without breaking focus.
Once 24+ hours and 5+ sessions pass, Auto-Dream sweeps .jsonl logs, anchors relative timestamps, deletes deprecated route notes, and keeps MEMORY.md crisp.
CLAUDE.md), just-in-time working facts (/memories), live visual verification (claude --chrome), and periodic pruning (/dream), every week makes your workspace faster rather than noisier.
11. Troubleshooting Clinic & Pre-Flight Checklist
Keep this rapid-diagnostic guide nearby whenever the Chrome extension drops its bridge, a site permission blocks unexpectedly, or MEMORY.md trims older facts—followed by your 6-point launch checklist.
| Symptom / Issue | Root Cause | 10-Second Fix |
|---|---|---|
| 1. “Browser extension is not connected” | Claude.app vs. CLI native messaging host conflict, or CLI and Chrome signed into different orgs. | Verify matching workspace orgs in extension & CLI, inspect /chrome status, or make com.anthropic.claude_code_browser_extension primary on macOS. |
| 2. Site blocked despite global “Allow all” | Hard safety block on banking/crypto/medical URLs, Desktop Block extension, or Chrome site access off. | Check Desktop settings (set to Allow extension), verify chrome://extensions site access, and note financial/medical sites remain protected by design. |
| 3. WebSocket bridge drops on corporate Wi-Fi | Enterprise TLS inspection intercepting bridge.claudeusercontent.com or local 127.0.0.1 sockets. |
Allowlist the Claude bridge endpoint with IT security or switch to an un-intercepted developer network profile. |
| 4. Agent keeps forgetting older repo notes | MEMORY.md exceeded its 200-line / ~25KB boot limit, causing silent tail truncation. |
Split verbose notes into dedicated topic files under /memories/, run /dream, and keep MEMORY.md strictly as a short pointer index. |
| 5. Memory edit wiped previous bullet points | Agent called create directly instead of inspecting existing lines and patching cleanly. |
Add a CLAUDE.md rule requiring view before edits and preferring str_replace or insert over full overwrites. |
| 6. Auto-Dream has not triggered automatically | Requires BOTH 24+ hours elapsed AND 5+ sessions since the last consolidation cycle. | Run /dream manually after major refactors, or inspect current index health anytime via /memory. |
7. /memories handler threw permission error |
Relative .. traversal path or destination collision during a rename operation. |
Ensure handler resolves paths via realpath inside root jail, rejects .., and checks destination existence before renaming. |
6-Point Chrome & Memory Pre-Flight Checklist
claude --chrome share one authenticated workspace.CLAUDE.md and session discoveries inside /memories.MEMORY.md under 200 lines (~25KB) and enforce canonical realpath root checks in API handlers./dream after major architecture shifts.