site-memory

name	site-memory
description	Persistent memory for repeated browser work. Use when an agent revisits the same sites or flows and should load a few relevant notes up front, then save durable site knowledge after the task finishes.

site-memory

This skill adds a reusable note loop to browser automation.

Its job is intentionally narrow:

• load a small number of high-value notes before acting
• write back reusable lessons after the task completes

It does not define business schemas. It does not own the browser driver. Pair it with whatever browser control tool you already trust.

Runtime location

Memory is global and shared across all projects. Notes about a website learned in one project are automatically available in every other project.

The default location is ~/.site-memory/. Override with SITE_MEMORY_HOME or --runtime-base <path>.

Resolve it with:

node ./scripts/resolve-runtime-root.mjs

Initialize it with:

node ./scripts/init-memory-root.mjs

Memory shape

The runtime root contains:

• INDEX.md as a compact index
• topic files with frontmatter and reusable details

Supported note kinds:

• operator
• guidance
• context
• reference

Use them this way:

• operator: collaboration preferences, pause points, tolerance for automation
• guidance: reusable rules, warnings, and tactics
• context: surrounding deadlines or constraints that matter across runs
• reference: stable selectors, URL patterns, routes, and site structure

Lookup workflow

1. Build the lookup inputs:

node ./scripts/build-recall-input.mjs --task "<current task>"

2. Use the generated selector prompt to choose only the notes that are likely to save real exploration time.

3. Open only the chosen files:

node ./scripts/read-recalled-files.mjs --files "reference/foo.md,guidance/bar.md"

4. Treat recalled notes as leads, not ground truth. Re-check selectors, button labels, URLs, and flows against the live page before relying on them.

Capture workflow

After the browser task ends, build the write-back prompt:

node ./scripts/build-distill-input.mjs --message-count <n>

The output contains a prompt field. You MUST execute that prompt as an after-action pass. This pass can:

• read memory files
• search memory files
• update files only inside the memory root

That pass should:

• update an existing topic file when possible
• create a new topic file only when the lesson is genuinely new
• keep INDEX.md short
• avoid storing one-off outputs, secrets, or temporary task state

Design rules

• Keep notes generic and reusable.
• Save only information that should make a future visit cheaper or safer.
• Prefer revising topic notes over appending session logs.
• Load only a few notes per task; too much memory becomes noise.
• If a remembered selector or route may be stale, verify it before use.

Browser automation

A CDP-based browser control skill is bundled at ./vendor/chrome-cdp-skill/. Read its instructions before first use:

cat ./vendor/chrome-cdp-skill/skills/chrome-cdp/SKILL.md

Use node ./scripts/cdp-proxy.mjs <command> [args] for browser interaction.

Commands

All commands use ./scripts/cdp-proxy.mjs. The <target> is a unique targetId prefix from list.

list                              List open pages
shot <target> [file]              Viewport screenshot
snap <target>                     Accessibility tree snapshot
nav  <target> <url>               Navigate and wait for load
click <target> <selector>         Click by CSS selector
clickxy <target> <x> <y>          Click at CSS pixel coordinates
type <target> <text>              Type text at current focus
eval <target> <expr>              Evaluate JavaScript
html <target> [selector]          Full page or element HTML
open [url]                        Open new tab

Coordinates

shot saves at native resolution: image pixels = CSS pixels x DPR. CDP input events use CSS pixels: CSS px = screenshot px / DPR.

Tips

• Prefer snap --compact over html for page structure
• Use type (not eval) to enter text in cross-origin iframes
• Chrome shows an "Allow debugging" modal once per tab on first access

Browser task workflow

For repeated browser work, follow these phases in order:

1. Prepare the runtime

node ./scripts/init-memory-root.mjs

2. Load likely-helpful notes

node ./scripts/build-recall-input.mjs --task "<url> <objective>"

Read the manifest from the output, choose the strongest matches, then open only those notes:

node ./scripts/read-recalled-files.mjs --files "file1.md,file2.md"

3. Browse and verify

Use the browser tool to accomplish the objective. If notes mention selectors or routes, verify them on the live page before depending on them.

4. Capture durable findings

After the task, save only the parts that should help a future visit. For site knowledge, a reference note often benefits from a body structure like:

## What this site is
## How the site works
## Verified selectors
## Pitfalls
## Successful paths

Update INDEX.md after writing. If the task produced no durable lesson, skip the write-back.