browser-memory

One MCP gateway that gives AI agents a real browser and a memory per website. It proxies every tool of Playwright MCP and adds what an agent learns on each site: shortcuts, fixes, dead ends, and the site's own internal API, observed from real traffic. The next agent that lands on the same site starts where the last one stopped.

עברית

A real run against a public sandbox site, with an isolated headless browser and an empty memory directory. Session 1 records two lessons. Session 2 is a fresh agent; when it navigates to the site, the gateway attaches the lessons to the navigation result on its own.

Why it is interesting

• Memory that arrives without being asked for. An agent that sees two servers has to decide by itself when to consult memory, and in practice it does not. A gateway sits in the path, so it injects what is known about a domain the first time the session reaches it.

• Learned, not written. Three seconds after each navigation the gateway reads the network log, drops telemetry, collapses ids to :id and keeps parameter names without values. A single visit to an admin panel maps its internal API (invoices, subscriptions, resources) with no one writing a line. Response bodies are never stored.

• Capture that does not depend on the agent remembering. In one measured session an agent worked 49 turns across three sites, recorded nothing, and reported that it had. The gateway sees every call and result underneath the agent's story and infers lessons from evidence: an endpoint that returned data, a call that failed and then succeeded after a change, a form flow that worked.

• Lessons become tools. Something that worked once can be saved as a procedure and shows up in the tool list as a regular, callable tool.

• Fixes that fire by themselves. Every error body is matched against known symptoms, and a fix whose trigger appears verbatim is attached to the error. A fix that failed in its last two runs is not offered.

• Measured, not assumed. npm run eval:compare runs the same real task against an empty memory and a mature one. On a two-site task (match every VPS on a hosting panel with every DNS zone on a CDN), four of four pairs moved the same way: median turns 15.5 → 12.5, time 105 s → 73.5 s, cost $0.91 → $0.74. The Hebrew README has the full tables, the ablation campaign, and what the numbers cannot claim (n = 4, overlapping ranges).

Related MCP server: orchords-web-pilot

Architecture

Chrome (one persistent profile, CDP 9222)
      ▲
playwright-mcp (HTTP)                  ← upstream, untouched
      ▲
browser-gateway (stdio)                ← the agent connects here, and only here
      │
      ├── memory/<domain>.json             lessons
      ├── memory/api/<domain>.json         the API observed on the wire
      ├── memory/procedures/<domain>.json  saved procedures, served as tools
      ├── memory/observations.jsonl        evidence for automatic capture
      ├── memory/audit.jsonl               every call, written underneath the agent
      └── memory/tabs.json                 tab ownership, survives a kill

src/
  gateway/     the MCP server: tool list, dispatch, the brief attached on arrival
  memory/      the store, relevance ranking, curation
  capture/     everything written without being asked: observe, evidence, API map, harvest
  browser/     reading and driving the page: aria, tabs, ask-the-user, diagnosis
  procedures/  saved procedures and how they run
  lib/         mechanism with no product opinion: locks, rotation, redaction, audit, trace
  report/      a measured run rendered as a dossier
eval/          real tasks for real agents, cold against warm

Lessons have kinds, ordered by how much time they save: fast-path (a snippet that fetches the data directly), recipe, fix (symptom → solution), dead-end, auth, landmark (stable selectors and paths) and fact.

The memory tools: domain_brief, domain_open, domain_unstick, domain_remember, domain_report, domain_forget, domain_index, domain_interface, domain_curate, procedure_draft, procedure_save, procedure_list, procedure_delete, and browser_ask_user for the moments only a person can handle (a CAPTCHA, a login code, a card number).

Running it

Requirements: Node.js 24 (the code is TypeScript run directly by Node) and a running Playwright MCP server.

npm ci

# An isolated headless browser for trying it out. Both processes must name
# the same output directory: the gateway reads the snapshots the upstream writes.
npx @playwright/mcp --port 8931 --headless --isolated --output-dir /tmp/bm-output

# The gateway, as an MCP server over stdio:
PLAYWRIGHT_MCP_URL=http://localhost:8931/mcp \
PLAYWRIGHT_MCP_OUTPUT_DIR=/tmp/bm-output \
BROWSER_MEMORY_DIR=./memory \
node src/gateway/index.ts

In this mode memory, the API map and capture all work. Tab ownership and browser_ask_user also talk to Chrome over CDP (BROWSER_CDP_URL); for those, run a persistent Chrome with --remote-debugging-port=9222 and point the upstream at it with --cdp-endpoint http://127.0.0.1:9222, the setup in the diagram above.

Add it to Claude Code (or any MCP client) as a stdio server:

claude mcp add browser -- node /path/to/browser-memory/src/gateway/index.ts

Tests and tools

npm run test:unit     # no browser needed
npm run test:browser  # against a live Chrome, under a lock
npm run typecheck

npm run watch         # the gateway's decisions, live, in a second terminal
npm run explain       # what is being served right now, grouped by origin
npm run eval:compare  # the same task against cold and warm memory

License

MIT