garden.engram.searchMemories

{
  "description": "Search over a space's memories, by meaning and exact words. The caller embeds its query with the space's model and query prefix and sends vector, model and modelDigest, plus q: once the space has a keyword index, the results rank by both (hybrid). A service that runs the space's model may instead embed q itself when no vector is sent; one that can't (it doesn't embed queries, doesn't run the space's model, or doesn't embed for the space's authority) searches by keyword alone instead, unless mode asks otherwise. The response's mode says what ran. Requires a space credential for the space, presented with an HTTP message signature whose audience is this service's DID.",
  "errors": [
    {
      "description": "This service does not index the space.",
      "name": "UnknownSpace"
    },
    {
      "description": "The space's authority hasn't declared an embedding model.",
      "name": "NoModel"
    },
    {
      "description": "The query's model isn't the space's model. Re-read the space's config.",
      "name": "ModelMismatch"
    },
    {
      "description": "q was sent without a vector, this service doesn't run the space's model, and keyword search couldn't run instead (mode hybrid, or the space has no keyword index yet). Embed the query with the space's model and send the vector.",
      "name": "ModelNotHosted"
    },
    {
      "description": "This service doesn't embed queries for this space's authority, and keyword search couldn't run instead (mode hybrid, or the space has no keyword index yet).",
      "name": "TextSearchNotAllowed"
    },
    {
      "description": "mode keyword, and the space's keyword index is still being built. Search with a vector meanwhile.",
      "name": "KeywordIndexBuilding"
    },
    {
      "description": "Too many queries are being embedded. Retry shortly.",
      "name": "EmbedderBusy"
    },
    {
      "description": "The space's index is loading. Retry shortly.",
      "name": "IndexLoading"
    },
    {
      "description": "Too many searches for this space.",
      "name": "RateLimitExceeded"
    }
  ],
  "output": {
    "encoding": "application/json",
    "schema": {
      "properties": {
        "approximate": {
          "description": "Set when the index couldn't re-rank in time, so results are ranked by a coarser comparison and may be less precise.",
          "type": "boolean"
        },
        "memories": {
          "items": {
            "ref": "garden.engram.defs#memoryView",
            "type": "ref"
          },
          "type": "array"
        },
        "mode": {
          "description": "What ran: hybrid, vector (no q, mode vector, or a space whose keyword index is still being built), or keyword (mode keyword, or a fallback when q couldn't be embedded).",
          "knownValues": [
            "hybrid",
            "vector",
            "keyword"
          ],
          "type": "string"
        }
      },
      "required": [
        "memories"
      ],
      "type": "object"
    }
  },
  "parameters": {
    "properties": {
      "author": {
        "description": "Only memories written by this DID.",
        "format": "did",
        "type": "string"
      },
      "limit": {
        "default": 10,
        "maximum": 50,
        "minimum": 1,
        "type": "integer"
      },
      "mode": {
        "description": "hybrid (the default with q and a vector) ranks by meaning and exact words; vector ignores q for ranking; keyword ranks by q's words alone, needs no vector, and answers KeywordIndexBuilding until the space has a keyword index. An explicit mode never falls back.",
        "knownValues": [
          "hybrid",
          "vector",
          "keyword"
        ],
        "type": "string"
      },
      "model": {
        "description": "Must match the space's model.",
        "type": "string"
      },
      "modelDigest": {
        "description": "Must match the space's model digest.",
        "type": "string"
      },
      "q": {
        "description": "The query's text. With a vector, it makes the search hybrid once the space has a keyword index. Sent alone, a service that embeds queries (at most 1000 characters) embeds it with the space's model and query prefix; otherwise the search is by keyword alone.",
        "maxLength": 4000,
        "type": "string"
      },
      "since": {
        "description": "Only memories created at or after this time.",
        "format": "datetime",
        "type": "string"
      },
      "space": {
        "description": "The space URI.",
        "type": "string"
      },
      "tags": {
        "description": "Only memories carrying every one of these tags.",
        "items": {
          "type": "string"
        },
        "maxLength": 16,
        "type": "array"
      },
      "vector": {
        "description": "The query's vector: little-endian IEEE half precision, base64url-encoded without padding.",
        "maxLength": 43000,
        "type": "string"
      }
    },
    "required": [
      "space"
    ],
    "type": "params"
  },
  "type": "query"
}