{
  "components": {
    "schemas": {
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "RecallRequest": {
        "properties": {
          "graph": {
            "default": false,
            "description": "Expand recall through graph neighbors.",
            "title": "Graph",
            "type": "boolean"
          },
          "limit": {
            "default": 5,
            "description": "Maximum recall seeds returned.",
            "maximum": 50,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "modality": {
            "anyOf": [
              { "type": "string" },
              { "type": "null" }
            ],
            "description": "Optional modality filter (text/image/pdf/...).",
            "title": "Modality"
          },
          "neighbor_limit": {
            "default": 3,
            "description": "Neighbors per seed when graph=True.",
            "maximum": 20,
            "minimum": 0,
            "title": "Neighbor Limit",
            "type": "integer"
          },
          "prefer_replacements": {
            "default": false,
            "description": "Boost current replacements over superseded.",
            "title": "Prefer Replacements",
            "type": "boolean"
          },
          "query": {
            "description": "Free-text recall query.",
            "title": "Query",
            "type": "string"
          }
        },
        "required": ["query"],
        "title": "RecallRequest",
        "type": "object"
      },
      "SemanticRecallRequest": {
        "properties": {
          "limit": {
            "default": 5,
            "description": "Top-K results to return (max 50).",
            "maximum": 50,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "query": {
            "description": "Free-text query for semantic (cosine) recall.",
            "title": "Query",
            "type": "string"
          }
        },
        "required": ["query"],
        "title": "SemanticRecallRequest",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                { "type": "string" },
                { "type": "integer" }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": ["loc", "msg", "type"],
        "title": "ValidationError",
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Recall typed memory items with provenance, supersession, and policy gates. Companion to the MCP stdio server — same recall logic, exposed for web-based AI tools (Claude.ai connectors, ChatGPT GPT actions, Gemini extensions, Grok). Public schema mirror published at app.griff.run/openapi.json. The recall endpoints (/stats, /recall, /semantic-recall) live behind Cloudflare Access on memory.griff.run and require both a CF Access service token and an operator-issued bearer token; /health is the only endpoint reachable without auth.",
    "title": "griffai-memory HTTP API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/health": {
      "get": {
        "operationId": "health_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Health Health Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Liveness check, no auth required.",
        "tags": ["meta"]
      }
    },
    "/recall": {
      "post": {
        "description": "Recall typed memory items with provenance, supersession, and policy gates.\n\nUse this BEFORE answering questions about prior decisions, fleet history, operator\npreferences, project state, or anything that might be in the memory layer. Pull the\noperator's actual durable record rather than guessing from priors.",
        "operationId": "recall_recall_post",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "anyOf": [
                { "type": "string" },
                { "type": "null" }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecallRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "title": "Response Recall Recall Post",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Recall typed memory matching a query.",
        "tags": ["recall"]
      }
    },
    "/semantic-recall": {
      "post": {
        "description": "Semantic (vector) recall against the `memory_embeddings` corpus.\n\nEncodes the query with BAAI/bge-small-en-v1.5 and returns the top-K\nitems by cosine similarity, joined with `memory_items` metadata.\n\nCold-load behavior: the first request in a server process pays ~6 s\nfor model + matrix load. Subsequent requests complete in ~16 ms\nend-to-end on the current ~120K-row corpus.\n\nRaw embedding vectors are intentionally NOT returned; only metadata\n+ score per item.",
        "operationId": "semantic_recall_endpoint_semantic_recall_post",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "anyOf": [
                { "type": "string" },
                { "type": "null" }
              ],
              "title": "Authorization"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticRecallRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Semantic Recall Endpoint Semantic Recall Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Top-K cosine recall over BGE-small embeddings (MEM-S7).",
        "tags": ["recall"]
      }
    },
    "/stats": {
      "get": {
        "operationId": "stats_stats_get",
        "parameters": [
          {
            "in": "header",
            "name": "authorization",
            "required": false,
            "schema": {
              "anyOf": [
                { "type": "string" },
                { "type": "null" }
              ],
              "title": "Authorization"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Stats Stats Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Counts of memory items / edges / sources / sensitivity events.",
        "tags": ["meta"]
      }
    }
  },
  "servers": [
    {
      "description": "Production tunnel via Cloudflare Access (operator-side credentials required).",
      "url": "https://memory.griff.run"
    }
  ]
}