openapi: 3.2.0
info:
  description: emem is shared memory for AI agents working together in the real world.
  license:
    name: Apache-2.0
  title: emem Temporal Route API
  version: 2.4.0
  x-emem-surface-asymmetry:
    memory_notes: MCP only
    reach_them_at: POST /mcp, method tools/call
    read_side_is_here:
    - /v1/memory/search
    - /v1/memory/sse
    - /memories/{path}
    tools:
    - emem_memory_create
    - emem_memory_view
    - emem_memory_delete
    - emem_memory_rename
    - emem_memory_str_replace
    - emem_memory_supersede
    why_not_here: These write the agent correspondence plane, which is prose and untrusted-by-declaration. It is deliberately not part of the REST fact surface, and the two planes are kept apart rather than merged for convenience.
servers:
- description: Hosted instance (HTTPS-only)
  url: https://emem.dev
tags:
- name: Temporal Route
paths:
  /v1/temporal_route:
    get:
      description: 'Turn a time-shaped question into a ready-to-run recall plan: it figures out WHICH bands to pull at WHICH past time windows (e.g. ''the year before the flood'', ''last growing season'', ''two vintages to compare'') so you don''t have to compute tslot offsets by hand. Returns the band + lookback + a `purpose` tag for each step. Algebra: valid(M, a): per-band validity from the physics decay kernel, cite_now versus fetch_for_intent.


        When to use: Call this first when the user''s question is about CHANGE OVER TIME or a PAST EVENT and you''re not sure which bands/dates to recall, ''was this flooded last year'', ''what was the NDVI baseline before the fire'', ''compare this place across vintages''. It hands you the recipe; then run those steps with `emem_recall`. Skip it when the user wants a single current reading. Pass `cell` plus an optional free-text `intent` hint. The plan is deterministic and the receipt cites which algorithm supplied each step.'
      operationId: emem_temporal_route_get
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: PDE-based band routing for a query time + intent (also accepts POST)
      tags:
      - Temporal Route
    post:
      description: 'Turn a time-shaped question into a ready-to-run recall plan: it figures out WHICH bands to pull at WHICH past time windows (e.g. ''the year before the flood'', ''last growing season'', ''two vintages to compare'') so you don''t have to compute tslot offsets by hand. Returns the band + lookback + a `purpose` tag for each step. Algebra: valid(M, a): per-band validity from the physics decay kernel, cite_now versus fetch_for_intent.


        When to use: Call this first when the user''s question is about CHANGE OVER TIME or a PAST EVENT and you''re not sure which bands/dates to recall, ''was this flooded last year'', ''what was the NDVI baseline before the fire'', ''compare this place across vintages''. It hands you the recipe; then run those steps with `emem_recall`. Skip it when the user wants a single current reading. Pass `cell` plus an optional free-text `intent` hint. The plan is deterministic and the receipt cites which algorithm supplied each step.'
      operationId: emem_temporal_route_post
      requestBody:
        content:
          application/json:
            schema:
              properties:
                band:
                  description: the singular spelling of `bands`
                  type: string
                bands:
                  items:
                    type: string
                  type: array
                cell:
                  description: cell64 or place name
                  type: string
                cell64:
                  description: alias for `cell`
                  type: string
                intent:
                  description: routes matching band families up the ranking, e.g. flood_window, crop_season
                  type: string
                lat:
                  type: number
                limit:
                  minimum: 1
                  type: integer
                lng:
                  type: number
                place:
                  type: string
                query_time:
                  description: RFC 3339 instant, or Unix seconds, the answer must be valid at
                  type:
                  - integer
                  - string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        '400':
          content:
            application/json:
              schema:
                properties:
                  details:
                    type: object
                  error:
                    type: string
                type: object
          description: invalid argument; `details.code` names which rule refused
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.'
      summary: 'PDE-based band routing for a query time + intent (algebra: valid; cite_now vs…'
      tags:
      - Temporal Route
components:
  schemas:
    ErrorEnvelope:
      description: The `emem.error.v1` failure envelope returned by every endpoint on a 4xx/5xx. Branch on the stable `code` (not the human `message`). See GET /v1/errors for the full code catalog.
      properties:
        code:
          description: Stable machine-readable error code. One of the codes in GET /v1/errors.
          example: invalid_argument
          type: string
        details:
          description: Optional structured recovery hints; present on errors that ship machine-readable next-steps.
          type: object
        message:
          description: Human-readable detail. For invalid_argument this names the offending field (e.g. "missing field `q`").
          type: string
        path:
          description: Request path that produced the error.
          example: /v1/ask
          type: string
        schema:
          const: emem.error.v1
          type: string
      required:
      - code
      - message
      - schema
      type: object