docs · concepts
Architecture
One idea drives everything: a repeated site action should be figured out once, written down as a skill, and replayed by every agent after that — instead of re-derived from the raw page on every run.
The skill loop
Every task that touches a website starts the same way: look in the catalog before touching the page. What happens next depends on whether a skill exists.
- Search first. The meta-skill teaches your agent to check the catalog before exploring a site by hand — most popular sites already have a green lane.
- A skill returns data, not instructions. Running one produces structured JSON; any decision over that data stays with the agent.
- Learning happens once, out of band. New skills are authored from a working exploration and land in the catalog through a curation pipeline — never as a public write API.
First run vs every run after
Without a skill, the agent derives the page live — and pays in time and tokens on every single run. With one, the same task is a recipe replay:
| Without a skill | With a skill | |
|---|---|---|
| Per-step page reads | Screenshot + DOM snapshot, every step | None — the recipe is already known |
| What the model sees | Raw pages, thousands of tokens each | Structured JSON fields |
| Latency per task | Minutes of derive-and-retry | Seconds — about 20× faster |
| Token cost | Paid again on every run | Roughly 4× fewer tokens |
| Behavior | Probabilistic, varies run to run | Deterministic replay |
The self-repairing catalog
Sites change markup and APIs constantly, so any skill can break overnight. Because every agent shares one catalog, a break is fixed exactly once:
Prefer the network, not the UI
The most stable skills don’t click through the interface at all. While a site is being explored, the network log usually reveals the direct in-page endpoint behind the UI — so the skill ships one authenticated fetch plus parsing instead of a chain of clicks. Markup changes weekly; internal APIs rarely. That is a big part of why replays stay stable, and why most catalog skills declare only needs: [navigate, evaluate].
What leaves your machine
bmem is consume-only: it downloads skill files and registers them. The skill itself executes inside your browser:
| Stays local | Comes from the catalog |
|---|---|
| Cookies and logged-in sessions (in your browser profile) | Skill files: selectors, request shapes, intent |
| The browsing itself — pages, results, form input | Index entries when you search |
| Anything typed during a manual login | Nothing else — the API is read-only |
Skills with auth: session ride on the session already in your browser profile. If it expired, log in manually and re-run — the skill itself is still valid. Never automate the login.
Components
| Component | Runs | Role |
|---|---|---|
| bmem CLI | Your machine (Node) | Search the catalog, download skills, register them natively |
skills installer | Your machine (via npx) | Detects your agent and writes the skill where it looks for skills |
| Your browser | Wherever it already runs | Executes the recipe; holds every session and cookie |
| Catalog API | api.browser-memory.com | Read-only index of curated skills per site |
| Skill storage | Hosted (public bucket) | The SKILL.md bodies the CLI downloads |
The catalog can be self-hosted and pointed at with one environment variable — see self-hosting.