The query_relations tool (OwnSona Manual)

Next: The text_search tool, Previous: The find_conflicts tool, Up: MCP Tools [Contents][Index]

5.16 The `query_relations` tool ¶

Traverses the relationship graph extracted from your memories to answer connected, multi-hop questions — e.g. “who is my manager’s spouse?” — that a flat similarity search cannot. Read-only; pure breadth-first search over the memory_relations graph, with no LLM call at query time.

The graph is populated by the relation-extraction background job (see Background intelligence); if this tool returns nothing, extraction may not be enabled yet — fall back to recall.

Inputs
Output
Errors

5.16.1 Inputs ¶

entity: Required string. The entity to start from (a person, place, organization, thing, or “the user”). Matched case-insensitively against relation subjects and objects.
max_hops: Integer. Optional, default 2, hard cap 5. Use 1 for direct relations only; higher values follow longer chains.

5.16.2 Output ¶

{
  "ok": true,
  "entity": "my manager",
  "relations": [
    { "subject": "Dana", "predicate": "manages", "object": "the user",
      "source_memory_id": 12, "source_text": "Dana is my manager." }
  ],
  "summary": { "count": 1 }
}

Edges are treated as undirected for reachability. Soft-deleted source memories are excluded, and each edge carries its source memory’s current text. Results are capped at GRAPH_MAX_RELATIONS.

5.16.3 Errors ¶

INVALID_INPUT (missing entity, max_hops < 1), DATABASE_ERROR.

Next: The text_search tool, Previous: The find_conflicts tool, Up: MCP Tools [Contents][Index]