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 Algorithms 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: Algorithms
paths:
  /v1/algorithms:
    get:
      description: 'Content-addressed dictionary of composition recipes, formulas that fuse attested band facts (and embeddings) into derived scores, classifications, and similarity metrics.


        When to use: Call when the user''s question is COMPOSITE (flood risk, urban density, water consensus, change-since-2020) rather than a single band readout. Each entry has `kind` (solo | combined | embedding), the input `bands` (assemble one `emem_recall` body from them), the `formula` in plain math, the `output` shape, and a `citation`. The agent applies the formula in-process and quotes the algorithm key + `algorithms_cid` (from `emem_manifests`) alongside the input fact_cids, that gives the receipt enough context for any other operator to replay the same composition deterministically. Embedding entries (cosine, novelty, change, neighborhood-consistency) operate on `geotessera`; for the most common k-NN pattern the protocol-native `emem_find_similar` is faster than fetching vectors and computing locally.'
      operationId: emem_algorithms
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: composition recipe registry (formulas that fuse band facts)
      tags:
      - Algorithms
  /v1/algorithms/{key}:
    get:
      description: 'Per-key drill-down on a single composition recipe, full body (kind, inputs, formula, output, citation, references) for ONE algorithm key. Companion to `emem_algorithms` (which is the catalog).


        When to use: Call when you already know the algorithm key (from `emem_algorithms`''s catalog or the topic registry) and need its full math. Cheaper than fetching the full catalog when you only need one entry. Returns the same structure that `/v1/algorithms/{key}` does. 404s with `cid_not_found` if the key isn''t registered, call `emem_algorithms` for the live key list.'
      operationId: emem_explain_algorithm
      parameters:
      - in: path
        name: key
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: per-key drill-down on a single algorithm (formula, inputs, citation), pair with…
      tags:
      - Algorithms