AMW Memory Operator

Use this skill when the user wants to run, debug, or evolve browser automation in

agent-memory-workbench

Scope

Replay-first execution from stored trajectories
Fallback exploration and trajectory persistence
Artifact extraction (markdown, screenshot, image copy, QR capture)
Run-log based debugging with minimal JSON edits

Trajectory Governance (Required)

Directory policy (do not mix):

```
examples/
```
(optional local) Local-only scratch examples; not distributed from Git by default.
```
trajectories/ready/
```
User-verified reusable trajectories. This is the primary grep/search target.
```
trajectories/tmp/
```
AI-generated or in-test trajectories. Temporary only. Do not treat as stable memory.
```
trajectories/archive/
```
Deprecated but kept versions for rollback/reference.

Lifecycle policy:

New trajectory starts in
```
trajectories/tmp/
```
.
Run
```
validate
```
and execute with
```
--disable-replay true
```
.
After repeated success, promote to
```
trajectories/ready/
```
.
If replaced, move old version to
```
trajectories/archive/
```
.

Hard constraints:

Do not create new user-generated JSON directly under
```
examples/
```
for distribution.
Do not commit temporary trajectories from
```
trajectories/tmp/
```
.
If a JSON is created in the wrong place, move it and explain the move.
Keep Baidu download experiments local-only in
```
trajectories/tmp/
```
(do not distribute under
```
examples/
```
).

ACK protocol before generating/modifying trajectory files:

Governance ACK: new JSON -> trajectories/tmp, reusable JSON -> trajectories/ready, grep default -> trajectories/ready.

Hard Rule: Max Two Branches

Only allow:

Normal branch
Human-verification branch (captcha/QR/real-person check)

Do not introduce multi-level branch trees unless the user explicitly asks.

Resource Map

Contract and reserved branch schema:
```
references/json-two-branch-contract.md
```
Replay/debug checklist:
```
references/replay-debug-checklist.md
```
JSON demos:
```
assets/json-demos/*.json
```
Skill UI metadata:
```
agents/openai.yaml
```
Reusable trajectories:
```
trajectories/ready/**/*.json
```
Temporary trajectories:
```
trajectories/tmp/*.json
```

Always copy the nearest demo JSON from

assets/json-demos/

and minimally adapt selectors/vars.

Install / Run

Runtime Bootstrap (Required Before First Use)

agent-memory-workbench

is missing in current workspace, bootstrap runtime first.

PowerShell:

if (!(Test-Path ./agent-memory-workbench/package.json)) { git clone https://github.com/insogao/amw.git agent-memory-workbench }

Install dependencies:

npm --prefix ./agent-memory-workbench install

Local

cd <your-workspace>/agent-memory-workbench

```
npm install
```

Use:

```
npm run amw -- list --store-dir ./data
```
```
npm run amw -- run ...
```

npm run amw -- validate --steps-file ./trajectories/tmp/<file>.json

If running outside project root:

npm --prefix <path-to-agent-memory-workbench> run amw -- <command>

Example from parent workspace:

npm --prefix ./agent-memory-workbench run amw -- <command>

Profile defaults to

main

(persistent login identity). Use

--profile <name>

to switch identities. Browser mode defaults to

headed=true

(visible browser window). Use

--headed false

only when the user explicitly asks for headless. Use

--disable-replay true

when validating new fallback steps and you need to bypass memory hits.

Headed debug mode

Use:

--headed true --hold-open-ms 30000

Optional npx distribution (future)

Current mode is local-first. For distribution later:

Publish package with
```
bin
```
pointing to
```
src-node/cli.js
```
Keep runtime dependency on
```
agent-browser
```
Run via
```
npx <your-package> run ...
```

Core Paths

CLI:
```
src-node/cli.js
```

Adapter/actions:

src-node/agentBrowserAdapter.js

src-node/actionRegistry.js

Reusable trajectories:
```
trajectories/ready/
```
Temporary trajectories:
```
trajectories/tmp/
```
Archived trajectories:
```
trajectories/archive/
```
Artifacts:
```
artifacts/
```

Runs:

data/<store>/runs/<run_id>/events.jsonl

and

summary.json

Memory DB:
```
data/<store>/memory.db
```

Meta Capabilities (JSON Actions)

Navigation/input:
```
open
```
,
```
click
```
,
```
click_text
```
,
```
fill
```
,
```
type
```
,
```
press
```
,
```
wait
```
Extraction:
```
eval_js
```
,
```
get_url
```
,
```
snapshot
```
Image/text ops:
- ```
copy_text
```
  ,
```
paste_text
```
- ```
copy_image
```
  (element/clip screenshot)
- ```
copy_image_original
```
  (prefer original image bytes)
- ```
paste_image
```

Output/validation:

```
write_markdown
```
,
```
append_markdown_section
```
```
assert_markdown
```
,
```
assert_file
```

Human takeover:
```
human_handoff
```

Screenshot granularity:

Full page (
```
full_page: true
```
)
Selector crop (
```
selector
```
)
Coordinate crop (
```
clip: {x,y,width,height}
```
)

Prefer

copy_image_original

whenever the user asks to "save original image" rather than screenshot.

Retrieval and Replay Workflow

Normalize intent into
```
{site, task_type, intent, vars}
```
Run replay-first
If replay misses/fails, run fallback steps
On success, persist trajectory
Compare
```
summary.json
```
```
mode
```
and latency (
```
replay
```
vs
```
explore
```
)
For grep-first manual selection, search
```
trajectories/ready/
```
first.

JSON Editing Policy

Edit the smallest possible segment
Keep selectors stable and robust
Keep variable input externalized (
```
{{vars.xxx}}
```
)
Keep branch count <= 2
Keep
```
assert_*
```
checks at the tail

Single-Line Match Field (Required)

For grep-first low-token retrieval, each JSON should include one reserved single-line field:

json

"amw_match_line": "amw site:example.com task:example_task flow:example_v1 key:foo key:bar key:<zh_keyword>"

Strict rules:

```
amw_match_line
```
must stay on one physical line (no
```
\n
```
or wrapped multi-line values).
Use ASCII tags only:
```
site:
```
,
```
task:
```
,
```
flow:
```
,
```
key:
```
.
Chinese is allowed in
```
key:
```
values when files are UTF-8 encoded.
Do not remove
```
amw
```
anchor token.
Prefer adding new
```
key:
```
tokens instead of changing
```
flow:
```
unless behavior truly changes.

For human verification:

Detect blocker (
```
eval_js
```
or error symptoms)
Save required artifact (
```
copy_image_original
```
preferred)
Pause with
```
human_handoff
```
Resume normal flow

For reserved branch fields, follow

references/json-two-branch-contract.md

Debug Protocol

On failure, inspect in order:

```
summary.json
```
(
```
failed_step_id
```
,
```
reason
```
,
```
mode
```
)
```
events.jsonl
```
(
```
step_error
```
, timeout, guard failure)
Artifact correctness in
```
artifacts/
```

Patch only the failed segment, then re-run once in headed mode. For fallback verification, add

--disable-replay true

so replay memory does not mask issues.

Command Templates

Run:

npm run amw -- run --site <site> --task-type <task_type> --intent "<intent>" --fallback-steps-file ./trajectories/ready/<file>.json --store-dir ./data/<store> --session <session> --headed true --hold-open-ms 30000

Run (force fallback):

npm run amw -- run --site <site> --task-type <task_type> --intent "<intent>" --fallback-steps-file ./trajectories/tmp/<file>.json --store-dir ./data/<store> --disable-replay true

Validate JSON:

npm run amw -- validate --steps-file ./trajectories/tmp/<file>.json

Inspect:

npm run amw -- list --store-dir ./data/<store>

npm run amw -- search --site <site> --task-type <task_type> --intent "<intent>" --store-dir ./data/<store>

Grep-first retrieval (AND by chain):

rg -n --glob "*.json" "\"amw_match_line\"\\s*:\\s*\".*\"" trajectories/ready | rg -i "amw" | rg -i "site:<domain>" | rg -i "task:<task_type>" | rg -i "<keyword_or_zh_keyword>"

amw-memory-operator

NPX Install

Tags

SKILL.md Content