> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying the graph

> Practical Knowledge Graph query patterns for decisions, contradictions, natural search, and global context.

# Querying the graph

You can query the KG when an agent needs durable context before writing or validating work. Start with specific read tools; use Cypher only when the dedicated tool does not cover the question.

## Natural language queries

`okto_pulse_kg_query_natural` performs deterministic retrieval over embeddings, HNSW indexes, and traversal. It does not ask an LLM to invent an answer.

```text theme={null}
okto_pulse_kg_query_natural(board_id="...", query="why did we choose the current auth model?")
```

## Cypher queries

`okto_pulse_kg_query_cypher` is read-only and intended for operators. Use explicit limits and narrow patterns.

```text theme={null}
MATCH (d:Decision) RETURN d.title, d.relevance_score LIMIT 20
```

## Semantic search

HNSW indexes cover `Decision`, `Constraint`, `Requirement`, `Entity`, and `Learning` nodes. Semantic search is retrieval; it is separate from the stored `relevance_score` formula.

## Decision history retrieval

Use `okto_pulse_kg_get_decision_history` when the topic is known but the decision ID is not.

## Contradiction detection

Run `okto_pulse_kg_find_contradictions` before introducing a spec that may conflict with old decisions or constraints.

## Global cross-board queries

`okto_pulse_kg_query_global` searches the global discovery graph and respects board access.

## Relevance scoring

The v0.3.3 base score is:

```text theme={null}
clamp(0.4*source_confidence + 0.3*log(1+degree)/log(100) + 0.3*decayed_hits - contradict_penalty + priority_boost, 0.0, 1.5)
```

Bug nodes use the higher of priority boost and severity boost.

## UI boost button

The UI boost endpoint adds `+0.3` to stored score and clamps at `1.5`. It is an operator override, not a change to semantic retrieval.

## Related pages

* [KG query tools](/reference/mcp/kg/queries)
* [KG health](/kg-operations/health)