Site memory

Site memory is the structured context your enterprise hands to agents — page map, workflows, business policies, UI guidance, per-page state. You author it once as JSON; the SDK serves it to agents over the channel each one understands. The point: agents stop screenshotting and guessing their way through your site.

This is not the agent's own memory. Conversation history belongs to the agent. Site memory belongs to you — it's the machine-readable description of how your site works.

Site memory is JSON, delivered as a WebMCP capability. A WebMCP-native agent doesn't scrape your DOM — it calls a synthetic getSiteContext tool and receives this snapshot verbatim. The same JSON also powers the <meta>/JSON-LD tags, the screenshot overlay, and the /.well-known/agent-context.json endpoint, so every agent class reads the same source of truth.

The end-to-end flow

author (SDK or dashboard)
        │  provideSiteMemory({...})  /  PUT /v1/sites/:id/memory
        ▼
   gateway store  ──(ETag)──►  client.syncSiteMemory()  ──►  browser snapshot
        │                                                        │
        │                                                        ├─ WebMCP synthetic tool  → WebMCP agents
        ├─ /.well-known/agent-context.json → anything, no SDK    ├─ <meta> + JSON-LD       → DOM agents, search
        └─ dashboard "Site memory" view + AI score               └─ visual overlay         → screenshot agents

You can author memory two ways — in code (provideSiteMemory) or in the dashboard — and they converge on the same gateway-stored snapshot. The browser SDK pulls it with syncSiteMemory() and fans it out to the four delivery channels.

Provide it once

client.provideSiteMemory({
  siteMap: {
    pages: [
      { path: '/', name: 'Home', purpose: 'Featured products' },
      { path: '/cart', name: 'Cart', availableActions: ['proceedToCheckout'] },
      { path: '/checkout', name: 'Checkout', prerequisites: ['Cart must not be empty'] },
    ],
    navigation: { flow: 'Home → Cart → Checkout', pattern: 'linear' },
  },
  workflows: {
    purchase: {
      steps: [
        { step: 1, action: 'Add items to cart' },
        { step: 2, action: 'Review cart' },
        { step: 3, action: 'Checkout' },
      ],
      notes: 'User confirmation required at step 3.',
    },
  },
  policies: {
    shipping: 'Free over $50',
    returns: '30-day window',
  },
  uiGuidance: {
    addToCart: { selector: '.add-to-cart-btn', behavior: 'Click to add 1 unit' },
    checkout: { selector: '#proceed-checkout', location: 'Right sidebar of /cart' },
  },
})

provideSiteMemory merges keys, so partial updates do not nuke siblings. Use client.siteMemory.update('policies.shipping', '...') to overwrite a single dot-path.

Per-page context

Pages with dynamic state (a checkout that knows the cart total, a search page that knows the active filter) can override their slice without rewriting the whole snapshot.

client.provideForPage({
  path: '/checkout',
  payload: {
    currentStep: 'order-review',
    estimatedTotal: 49.99,
    requiredFields: ['shipping-address', 'payment-method'],
  },
})

Page contexts ride alongside the global snapshot. WebMCP and well-known clients can pull pageContexts['/checkout'] to read the live state.

Four delivery channels

Different agent classes consume site memory differently. The SDK ships all four channels — pick the ones that match the agents you care about.

The well-known endpoint is the universal fallback — like robots.txt for AI agents. Agentronics serves it through the gateway; production hosts proxy from their domain.

Site context as a WebMCP tool

For WebMCP-native agents, the most direct channel is a synthetic tool. The agent sees a getSiteContext tool in its menu and calls it instead of inspecting the page:

import { createWebMcpContextTool } from '@agentronics/sdk'
 
const contextTool = createWebMcpContextTool({
  getSnapshot: () => client.siteMemory.get(),
})
 
// register alongside your other governed tools
client.registerTool(contextTool)

The agent receives the JSON snapshot as the tool result — no DOM reads, no screenshots. Because it's a governed tool, the call is traced (memory.accessed), so you can see exactly which agents pull context and when.

Gateway sync

Site memory authored in the dashboard syncs into the browser SDK on demand:

await client.syncSiteMemory()

The SDK keeps an ETag, so subsequent syncs are 304s with no payload.

Dashboard view & quality score

The Site memory page in the dashboard renders the exact snapshot each site hands to agents (the same JSON delivered over WebMCP and the well-known endpoint), so you can see what an agent sees. Alongside it, the snapshot is scored 0–100 for how useful it is to an agent:

The score weighs completeness, clarity, and actionability. Scoring runs server-side in the dashboard via Vertex AI Gemini when configured, and falls back to a deterministic completeness check so a number always renders. The completeness check asks whether the snapshot has each of these:

• ✓Site map — pages with paths + purpose
• ✓Navigation — flow + pattern between pages
• ✓Workflows — multi-step task definitions
• ✓Policies — shipping, returns, business rules
• ✓UI guidance — selectors + behavior per action
• –Per-page context — live state for dynamic pages

The numbers the score reasons over come from the snapshot itself — nothing is invented. A snapshot missing UI guidance and per-page context lands in the "Adequate" band with concrete suggestions for what to add; fill those in and it climbs toward "Strong."

Reading the bands

Traces

Every provide, update, provideForPage, and gateway/well-known sync emits a memory.updated trace tagged with metadata.kind === 'site'. Reads through siteMemory.get() and the WebMCP tool emit memory.accessed. Use those to see exactly what agents pull from you.