{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/neruva-io/json-schema/neruva-io-agent-recall-request-schema.json",
  "title": "AgentRecallRequest",
  "description": "One-call federated query. Searches records semantically + scans\nKG by entity overlap with the query tokens.\n\nnamespace OR namespaces: pass one for single-session recall, or a\nlist to fan across multiple sessions (e.g., a user's last 10\nsessions for the cross-session graph-RAG narrative). namespaces\nwins if both are provided.\n\nmode:\n  None (default) -- pure semantic ranking by cosine score.\n  'qa_optimized' -- additionally BM25-fuse over the candidate pool\n                    via Reciprocal Rank Fusion (RRF). Worth ~+20pp\n                    on memory-QA benchmarks where the question\n                    contains specific entity tokens (brand names,\n                    amounts, dates) that semantic search alone\n                    under-weights.\n\nrecency_first:\n  False (default) -- semantic relevance ordering.\n  True -- after ranking, re-sort the returned records by ts desc\n          (newest first). Use for knowledge-update questions where\n          the most recent fact wins.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/neruva-io-openapi.json#/components/schemas/AgentRecallRequest",
  "properties": {
    "query": {
      "type": "string",
      "title": "Query"
    },
    "namespace": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Namespace"
    },
    "namespaces": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Namespaces"
    },
    "top_k": {
      "type": "integer",
      "title": "Top K",
      "default": 10
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "User Id"
    },
    "mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mode"
    },
    "recency_first": {
      "type": "boolean",
      "title": "Recency First",
      "default": false
    }
  },
  "type": "object",
  "required": [
    "query"
  ]
}