actions.json.storage

actions.json.storage is a user-owned file workspace for website operating memory.

An actions.json file tells an agent how to operate a website. Storage keeps the durable context that makes those actions useful over time:

site action maps;
page and product knowledge;
observations captured from browser sessions;
run logs and lessons;
generated overlays and reports;
shared or public maps that can be reviewed and reused.

The reference storage format uses ordinary files in Git repositories so users can read, diff, branch, review, and share the memory that agents use.

When To Use Storage

Use storage when an agent learns something that should survive the current browser session.

Examples:

A site guide learns what every menu page contains.
A product guide stores product descriptions, buying advice, and cart actions.
A carousel scan stores every item it saw, including items that later scroll out of view.
A navigation action fails and the corrected selector should be remembered.
A generated overlay should be available next time the same site is opened.

Workspace Layout

The recommended root checkout is:

actions.json.storage/
  README.md
  storage.json
  scopes/
    private/
    shared/
    public/

The root repository is the workspace and mount table. Each visibility scope can be a separate repository mounted under scopes/.

Separate scope repositories help because:

private browsing observations do not need the same access rules as public examples;
shared site maps can be given to a specific website owner or collaborator;
public maps can be published without exposing private history;
Git history stays reviewable by audience.

Scope Layout

Each mounted scope should use the same internal shape:

scopes/shared/example-owner/
  scope.json
  agents/
    chrome-extension.json
    codex.json
  sites/
    example.com/
      actions.json
      observations/
      items/
      runs/
      overlays/
      reports/

Use the same layout under scopes/private/ and scopes/public/ so artifacts can move between scopes without being reshaped.

Root Manifest

storage.json describes the workspace and mounted scopes.

{
  "protocol": "actions.json.storage",
  "version": "0.1.0",
  "owner": {
    "type": "person",
    "id": "local-user"
  },
  "default_mount": "private",
  "mounts": {
    "private": {
      "path": "scopes/private",
      "mount_type": "git_submodule",
      "visibility": "private"
    },
    "public": {
      "path": "scopes/public",
      "mount_type": "git_submodule",
      "visibility": "public"
    }
  }
}

The manifest should describe where scopes live. Raw browsing data belongs inside the scope repositories, not in the root manifest.

Site Folders

A site folder is the unit the browser runtime uploads, reads, and updates.

sites/example.com/
  actions.json
  context/
    overview.md
  observations/
    2026-06-07T140000Z.jsonl
  items/
    products.items.json
  runs/
    2026-06-07T141500Z.json
  overlays/
    product-guide.overlay.json
  reports/
    product-guide.html

The exact artifact set depends on the site. A simple site may only need actions.json; a product or content site may need context, product inventory, navigation maps, overlays, and run history.

Data Classes

Action Maps

actions.json stores reusable actions and context for the site.

Good action maps include:

what the site is for;
important pages and sections;
reliable navigation actions;
product or content explanations;
when to use point-based actions versus DOM inspection;
any site policy limits, such as blocked page JavaScript.

Action maps guide future automation, so edits should be reviewed before they are shared or published.

Observations

Observations are raw facts captured from a page at a time. They are usually append-only JSONL.

{
  "type": "observation",
  "observed_at": "2026-06-07T14:00:00Z",
  "site": "example.com",
  "surface": "products",
  "source_url": "https://example.com/products",
  "items": [
    {
      "title": "Example product",
      "url": "https://example.com/products/example"
    }
  ]
}

Observations answer: what did the agent see?

Items

Item indexes deduplicate observations into stable memory.

{
  "type": "item_index",
  "surface": "products",
  "items": {
    "product:https://example.com/products/example": {
      "title": "Example product",
      "url": "https://example.com/products/example",
      "first_seen_at": "2026-06-07T14:00:00Z",
      "last_seen_at": "2026-06-07T14:00:00Z"
    }
  }
}

Items answer: what do we remember across sessions?

Overlay Templates And Data

Reusable overlays should separate layout from private results:

scopes/public/sites/example.com/overlays/report/template.html
scopes/private/sites/example.com/overlays/report/data.json

The template holds HTML, CSS, and rendering code. The data file holds the current scan result. This lets a hosted agent refresh the report by updating data.json without rewriting the template, and it lets users share templates without sharing private data.

For the full workflow, see Overlay Templates And Data.

Runs

Runs record what an agent did and what happened.

{
  "type": "run",
  "run_id": "2026-06-07T141500Z-example-navigation",
  "site": "example.com",
  "actions_taken": [
    {
      "action": "navigation.open_products",
      "result": "products_page_visible"
    }
  ],
  "lessons": [
    {
      "type": "navigation",
      "text": "The products page should be opened by link URL, not by approximate scroll position."
    }
  ]
}

Runs answer: what did the agent do, what failed, and what should improve?

Reports And Overlays

Reports and overlays are human-facing views generated from stored data.

reports/product-guide.html
overlays/product-guide.overlay.json

The canonical source should remain structured actions, observations, items, and runs. Generated views can be rebuilt from that source.

Upload And Download In The Extension

The Chrome extension can upload a local actions.json.storage checkout into browser storage. The hosted agent can then use actions.site to read matching site maps without a local bridge.

Typical workflow:

Pull the storage repository and its mounted scope repositories.
Open the target website in Chrome.
Open the extension actions.json menu.
Open Settings.
Press Upload and choose the root actions.json.storage folder.
Start or restart the hosted agent.
Ask what actions are available for the current site.
After the agent creates or updates useful artifacts, press Download to write them back to the selected local checkout.
Review and commit the storage changes.

The upload should send the whole storage checkout, not a single site folder, so the runtime can resolve scopes and related sites.

Bridge Sync

External coding agents can also load storage through the MCP-shaped bridge. Use this path when a coding agent outside the extension is authoring, testing, or validating maps.

The bridge path and extension upload path should produce the same current-site catalog for actions.site.

Write Policy

Recommended default policy:

Data	Default write mode	Reason
`observations/*.jsonl`	Direct append	Captures what was seen; easy to audit.
`runs/*.json`	Direct write	Captures one execution trace.
`items/*.json`	Deterministic merge	Derived memory from observations.
`reports/*`	Generated artifact	Human-facing view.
`overlays/*`	Generated or reviewed artifact	May be shown to the user.
`actions.json`	Review before sharing	Changes future automation behavior.
`schemas/*.json`	Review before sharing	Changes compatibility and validation.

Use scopes to decide who should see the memory:

private: personal observations, debugging runs, private browsing memory;
shared: maps or overlays prepared for a specific collaborator or website owner;
public: reviewed examples intended for broad reuse.

Do not publish internal development notes, private customer observations, or unreviewed browser logs as public storage.

Security Rules

Never store:

passwords;
cookies;
access tokens;
session storage;
payment data;
private keys;
private messages or personal data that the user did not intend to preserve.

The browser runtime should not need credentials from storage. It operates the page that the user has already opened and authorized.

Verify Storage Is Working

Upload the storage root from the extension Settings tab.
Open a website that has a matching site folder.
Start the hosted agent.
Ask it what actions are available.
If you inspect the log, confirm the agent used actions.site and received site-specific actions.
Create or update one harmless artifact.
Press Download and confirm the local checkout changed.

If actions are missing, see Troubleshooting.

actions.json.storage

When To Use Storage

Workspace Layout

Scope Layout

Root Manifest

Site Folders

Data Classes

Action Maps

Observations

Items

Overlay Templates And Data

Runs

Reports And Overlays

Upload And Download In The Extension

Bridge Sync

Write Policy

Security Rules

Verify Storage Is Working

Read Next

Table of contents

actions.json.storage

When To Use Storage

Workspace Layout

Scope Layout

Root Manifest

Site Folders

Data Classes

Action Maps

Observations

Items

Overlay Templates And Data

Runs

Reports And Overlays

Upload And Download In The Extension

Bridge Sync

Write Policy

Visibility And Sharing

Security Rules

Verify Storage Is Working

Read Next

Table of contents