query

Run a vector query against an explicit semantic layer. Like recall, but you choose the layer instead of defaulting to L0. The server embeds the query text and returns scored node ids, nearest first. Dispatches to the query internal service method.

recall versus query

recall always searches layer L0 — the raw cells you stored. query lets you target a specific layer:

L0 — raw stored cells.
L1 and L2 — consolidated, promoted knowledge.

Higher layers hold fewer, more durable nodes that the system promotes from L0 over time. Use query with L1 or L2 when you want consolidated knowledge rather than every raw cell. See The HNSW mesh and Layer promotion.

Parameters

Name	Type	Required	Default	Description
`text`	string	Yes	—	The query text, embedded server-side.
`layer`	string	Yes	—	The semantic layer to search. One of `L0`, `L1`, `L2`.
`k`	integer	No	`10`	Number of neighbours to return (minimum `1`).
`filter`	object	No	—	A convenience `NodeFilter`, AND-ed after the caller’s access scope.

Returns

{
  "nodes": [
    { "node_id": "<uuid>", "distance": <number> }
  ]
}

Returned as the structuredContent payload, nearest first.

Over MCP, query returns only {node_id, distance} pairs — not hydrated cell content. To read a cell’s content, use a hydrating surface such as the REST API, which returns full nodes.

Example

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": { "text": "storage architecture decisions", "layer": "L1", "k": 5 }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"nodes\":[{\"node_id\":\"6f9619ff-8b86-d011-b42d-00cf4fc964ff\",\"distance\":0.08}]}" }
    ],
    "structuredContent": {
      "nodes": [
        { "node_id": "6f9619ff-8b86-d011-b42d-00cf4fc964ff", "distance": 0.08 }
      ]
    },
    "isError": false
  }
}

Annotations

The tool’s MCP behaviour hints, as emitted in tools/list (advisory display metadata — see the annotations contract):

`readOnlyHint`	`destructiveHint`	`idempotentHint`	`openWorldHint`
`true`	`false`	`true`	`false`

A pure read against the chosen layer — writes nothing.

recall for the L0 shortcut.
Layer promotion for how L1/L2 are built.

Overview

Tools

recall versus query

Parameters

Returns

Example

Annotations

​recall versus query

​Parameters

​Returns

​Example

​Annotations

​Related

recall versus query

Parameters

Returns

Example

Annotations

Related