Sightmap Memory: Durable Notes Agents Read at Runtime

Memory entries are short freeform notes attached at the file root or to a view, component, or request. They record runtime context that source code may not state, such as quirks, invariants, and workarounds.

memory:
  - Past dates render but are aria-disabled
  - Range mode, 1st click = start, 2nd = end, 3rd resets

Each entry is a non-empty string, usually a sentence or short bullet. Consumers treat the content as text rather than structured data.

Where they attach

memory is a string array. Its location determines when the entries apply.

.sightmap/flights.yaml

version: 1

memory:                                  # file-level — applies whenever any definition in this file is active
  - Dates throughout the app are ISO-8601 (YYYY-MM-DD)

views:
  - name: FlightSearch
    route: /search
    memory:                              # view-level — applies when the URL matches /search
      - The search form lives inside a modal on mobile; selectors differ
    components:
      - name: DepartureDatePicker
        selector: '[data-picker="departure"]'
        memory:                          # component-level — applies when this component is matched
          - Accepts typed YYYY-MM-DD — skips the calendar
          - Past dates render but are aria-disabled

requests:
  - name: SearchFlights
    route: /api/flights/search
    memory:                              # request-level — applies in the network-trace detail view
      - Rate-limited to 10 requests/min per user; returns 429 beyond that

The activation rules:

File-level: applies whenever any definition from that file is active.
View-level: applies whenever the current URL matches that view’s route.
Component-level: applies whenever that component is matched on the current view.
Request-level: applies in the network-trace detail view for that request.

What consumers do with them

Memory entries are runtime guidance, not configuration. Conforming implementations SHOULD include applicable entries in a [Guide] section at the top of enriched output. The sightmap CLI prints view-level memory in the snapshot header and includes component memory in annotated JSON written with --json.

memory contains guidance for consumers at runtime. description supports review and maintenance and is not surfaced at runtime. Put page-driving context in memory and YAML-maintenance context in description.

What to write

Use memory for short observations about runtime behavior that the source code does not make obvious. Good entries:

“Past dates render but are aria-disabled”
“Rate-limited to 10 requests/min per user; returns 429 beyond that”
“The third click on the date range resets the selection”

Avoid entries that:

Repeat the definition’s name, such as “This is the search page”
Restate behavior already exposed by the controls, such as “Type a city name and submit”
Contain a long explanation that belongs in smaller entries or in description

Update or delete a memory entry when the behavior it describes changes.

Conformance describes how implementations verify they follow the spec correctly, including the rules above.

The spec

Reference

Sightmap Memory: Durable Notes Agents Read at Runtime

Where they attach

What consumers do with them

What to write

Next

​Where they attach

​What consumers do with them

​What to write

​Next

Where they attach

What consumers do with them

What to write

Next