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 Intent 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: Intent
paths:
  /v1/intent:
    post:
      description: 'Say what you want in one typed object and get the answer, without choosing a primitive. `type` is a tagged union: it selects the intent AND decides which other fields are read, so send only the fields its row needs. The plan is EXECUTED in the same call, so you receive the result (the resolved cell64, the similarity, the delta, the verdict), not a list of calls to make yourself.


        type | needs | optional | answers

        where_is | description | | cell64 for a named place

        what_is_here | cell OR place | description | what is attested at a location

        is_like | a, b | | cosine similarity of two cells

        did_change | cell, band, window | | delta for one band over [start,end] tslots

        find_like | key | k, filter | nearest cells by embedding

        confirm | claim, cell | | verdict plus the signed facts behind it

        ask | description | place/cell/lat+lng | free-text question, packaged answer


        An unknown or missing `type` returns a structured `needs_intent_type` envelope naming the seven values rather than a hard error, so you can correct it on the next turn.


        When to use: Call when the question maps onto one of the seven rows above and you would rather state the goal than pick a primitive. Otherwise go direct: a band at a cell is emem_recall, a region is emem_recall_polygon, a free-text place question is emem_ask (type:"ask" forwards to it). `window` takes tslots, not dates: get them from emem_trajectory. A tool named here but absent from `tools/list` is not a dead end: every one of the {TOOL_TOTAL} dispatches by name at `/mcp` and `/mcp/full`; the core list is {TOOL_CORE} to keep the catalog small, and `emem_tools` enumerates the rest.'
      operationId: emem_intent
      requestBody:
        content:
          application/json:
            schema:
              properties:
                a:
                  type: string
                b:
                  type: string
                band:
                  type: string
                cell:
                  type: string
                claim:
                  $ref: '#/components/schemas/Claim'
                description:
                  type: string
                filter:
                  $ref: '#/components/schemas/Claim'
                k:
                  type: integer
                key:
                  type: string
                place:
                  type: string
                type:
                  enum:
                  - where_is
                  - what_is_here
                  - is_like
                  - did_change
                  - find_like
                  - confirm
                  - ask
                  type: string
                window:
                  items:
                    type: integer
                  maxItems: 2
                  minItems: 2
                  type: array
              required:
              - type
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        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: typed agent intent → execution plan.
      tags:
      - Intent
components:
  schemas:
    Claim:
      properties:
        agg:
          description: Aggregation over `window`
          enum:
          - any
          - all
          - mean
          - min
          - max
          type: string
        band:
          description: Band key (e.g. `indices.ndvi`, `copdem30m.elevation_mean`)
          type: string
        op:
          description: Comparison or membership operator
          enum:
          - eq
          - ne
          - lt
          - le
          - gt
          - ge
          - in
          - ni
          - exists
          - absent
          type: string
        tslot:
          description: Specific tslot; one of `tslot` or `window` MUST be set
          type: integer
        value:
          description: Right-hand value, band-typed (number for scalar bands, array for vector bands, set for in/ni). Required even for exists/absent where it is ignored.
        window:
          description: Inclusive [start, end] u64 Unix-epoch range
          items:
            type: integer
          maxItems: 2
          minItems: 2
          type: array
      required:
      - band
      - op
      - value
      type: object
    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