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.
Knowledge Graph queries
Pulse exposes 14 read-only KG tools:
- 9 primary query tools — typed, opinionated answers to the questions agents ask most often.
- 5 power tools — escape hatches for arbitrary Cypher, natural-language search, schema introspection, grounding verification, and a reflective retrieve-critic stub.
Permissions are dotted-string flags in the granular registry (okto-pulse-core/src/okto_pulse/core/infra/permissions.py:PERMISSION_REGISTRY):
- The 9 primary tools sit under
kg.query.* — granted as a wildcard or per-tool (kg.query.decision_history, kg.query.global, …).
- The 5 power tools split across
kg.power.natural, kg.power.schema_info, kg.power.cypher. kg.power.cypher is the most restricted and is typically excluded from default presets.
kg.power.cypher and the natural-language tool also write to the per-node hit counter that feeds relevance_score over time — every read result you take from these tools is logged.
None of these tools write graph data. None of them call an LLM at runtime — every primary tool is a deterministic combination of HNSW vector search and graph traversal. (kg_query_reflective is the sole exception and is a V1 stub.)
For the schema (11 node types, 10 rel types + belongs_to, 5 HNSW indexes) and tool inventory, see overview.
Source: okto-pulse-core/src/okto_pulse/core/mcp/kg_query_tools.py:register_kg_query_tools. Citations below reference 80-pulse-feature-inventory.md:519–531.
okto_pulse_kg_get_decision_history
Trace decisions about a topic over time. Hybrid HNSW + title-CONTAINS search, results ordered chronologically with supersedence chain summaries.
Input:
board_id: "brd_abc123"
topic: "retry strategy for webhook delivery"
limit: 20
since: "2026-01-01T00:00:00Z" (optional)
Output:
{
"topic": "retry strategy for webhook delivery",
"match_mode": "hybrid",
"results": [
{
"node_id": "dec_8f1a",
"title": "Exponential backoff with jitter for webhook retries",
"type": "Decision",
"created_at": "2026-02-14T10:22:11Z",
"rationale": "Fixed retries cause thundering-herd at peer recovery...",
"superseded_by": null,
"score": 0.83
},
{
"node_id": "dec_4c20",
"title": "Fixed 3s retry interval, 5 attempts",
"type": "Decision",
"created_at": "2025-11-08T18:05:00Z",
"superseded_by": "dec_8f1a",
"score": 0.71
}
]
}
okto_pulse_kg_get_related_context
2-hop neighborhood traversal around a single node. Supports edge type filter, direction filter, max depth (default 2, cap 4).
Input:
board_id: "brd_abc123"
node_id: "dec_8f1a"
edge_types: ["supersedes", "depends_on", "violates"] (optional)
direction: "both" ("in" | "out" | "both")
max_depth: 2
Output:
{
"anchor": {"node_id": "dec_8f1a", "title": "Exponential backoff..."},
"nodes": [
{"node_id": "con_2e", "type": "Constraint", "title": "Webhook receivers must respond within 30s"},
{"node_id": "dec_4c20", "type": "Decision", "title": "Fixed 3s retry interval, 5 attempts"}
],
"edges": [
{"src": "dec_8f1a", "rel": "depends_on", "dst": "con_2e"},
{"src": "dec_8f1a", "rel": "supersedes", "dst": "dec_4c20"}
]
}
okto_pulse_kg_get_supersedence_chain
Walk the supersedes chain for a decision (max depth 10). Returns nodes in newest-to-oldest order.
Input:
board_id: "brd_abc123"
node_id: "dec_8f1a"
max_depth: 10
Output:
{
"head": "dec_8f1a",
"chain": [
{"node_id": "dec_8f1a", "title": "Exponential backoff with jitter", "created_at": "2026-02-14T10:22:11Z"},
{"node_id": "dec_4c20", "title": "Fixed 3s retry interval, 5 attempts", "created_at": "2025-11-08T18:05:00Z"},
{"node_id": "dec_001", "title": "No retry — drop on failure", "created_at": "2025-09-02T09:11:30Z"}
],
"depth": 3
}
okto_pulse_kg_find_contradictions
Find contradicts edges. With no node_id, returns all contradiction pairs on the board. With node_id, returns the pairs anchored at that node.
Input:
board_id: "brd_abc123"
node_id: "dec_8f1a" (optional)
Output:
{
"anchor": "dec_8f1a",
"pairs": [
{
"left": {"node_id": "dec_8f1a", "title": "Exponential backoff..."},
"right": {"node_id": "con_99", "title": "Webhook payloads must arrive in order"},
"edge_id": "edge_771",
"created_at": "2026-02-14T10:23:02Z"
}
]
}
okto_pulse_kg_find_similar_decisions
Hybrid ranked similarity. The reranking formula is fixed in kg_service.py:244:
score = 0.5 × semantic + 0.2 × graph_centrality + 0.2 × recency_decay + 0.1 × confidence
relevance_score on each node — do not conflate the two (80-pulse-feature-inventory.md:957).
Input:
board_id: "brd_abc123"
query: "How should we handle out-of-order events from the queue?"
limit: 5
Output:
{
"results": [
{
"node_id": "dec_5b2",
"title": "Sequence-number gating for queue consumers",
"score": 0.78,
"components": {"semantic": 0.81, "graph_centrality": 0.66, "recency": 0.92, "confidence": 0.80}
}
]
}
okto_pulse_kg_explain_constraint
Returns the origin spec/decision for a Constraint node, related constraints, and any Bug nodes that record violations of it.
Input:
board_id: "brd_abc123"
node_id: "con_2e"
Output:
{
"constraint": {"node_id": "con_2e", "title": "Webhook receivers must respond within 30s"},
"origin": {"type": "spec", "id": "spec_007", "title": "Webhook delivery v2"},
"related_constraints": [
{"node_id": "con_2f", "title": "Retries must use exponential backoff"}
],
"violations": [
{"node_id": "bug_4411", "title": "Slow consumer caused 30s+ retries", "resolved_at": "2026-03-01"}
]
}
okto_pulse_kg_list_alternatives
For a Decision, return the Alternative nodes that were considered and discarded, with the recorded reason_discarded.
Input:
board_id: "brd_abc123"
node_id: "dec_8f1a"
Output:
{
"decision": "dec_8f1a",
"alternatives": [
{
"node_id": "alt_22",
"title": "Token-bucket rate limit instead of backoff",
"reason_discarded": "Adds complex per-tenant accounting; backoff is sufficient for current volume."
}
]
}
okto_pulse_kg_get_learning_from_bugs
Trace Learning nodes derived from bugs in an area, via Learning → Bug validates edges.
Input:
board_id: "brd_abc123"
area: "webhook delivery"
limit: 10
Output:
{
"results": [
{
"learning": {"node_id": "lrn_18", "title": "Always log raw delivery latency, not retry-counter"},
"bug": {"node_id": "bug_4411", "title": "Slow consumer caused 30s+ retries"},
"captured_at": "2026-03-02T11:00:00Z"
}
]
}
okto_pulse_kg_query_global
Cross-board semantic search via the global discovery layer (~/.okto-pulse/global/discovery.lbug). ACL-filtered: only returns nodes from boards the calling agent’s API key can read.
Input:
query: "What did we decide about retry strategies?"
limit: 20
Output:
{
"results": [
{"board_id": "brd_abc123", "node_id": "dec_8f1a", "title": "Exponential backoff...", "score": 0.81},
{"board_id": "brd_other", "node_id": "dec_5b2", "title": "Sequence-number gating...", "score": 0.74}
],
"boards_searched": 4
}
Source: okto-pulse-core/src/okto_pulse/core/mcp/kg_power_tools.py:register_kg_power_tools. Citations: 80-pulse-feature-inventory.md:535–543.
These are escape hatches. Reach for them when the typed primary tools don’t cover the question, when you need full schema introspection, or when you need to verify an answer is grounded in actual graph data.
okto_pulse_kg_query_cypher
Read-only Cypher against the board graph. Safety rails:
- Write keywords (
CREATE, DELETE, MERGE, SET, REMOVE) are rejected by whitelist.
LIMIT is auto-injected if the query lacks one.- Variable-length paths bounded to
*..20.
- 30-second timeout.
- 30 requests / minute / agent rate limit.
Input:
board_id: "brd_abc123"
cypher: "MATCH (d:Decision)-[:supersedes]->(o:Decision) RETURN d.title, o.title"
params: {}
Output:
{
"columns": ["d.title", "o.title"],
"rows": [
["Exponential backoff with jitter", "Fixed 3s retry interval, 5 attempts"],
["Fixed 3s retry interval, 5 attempts", "No retry — drop on failure"]
],
"row_count": 2,
"elapsed_ms": 18
}
kg_query_cypher is the broadest read tool — but the typed primary tools above are faster and safer for the common patterns. Reach for Cypher only when the typed tools genuinely don’t fit.
okto_pulse_kg_query_natural
Plain-English question against the graph. Hybrid embedding + HNSW + 1-hop traversal expansion. No LLM — deterministic.
Input:
board_id: "brd_abc123"
query: "Why did we move away from fixed retry intervals?"
since: "2025-01-01T00:00:00Z" (optional)
until: null
limit: 10
Output:
{
"answer_nodes": [
{"node_id": "dec_8f1a", "title": "Exponential backoff with jitter", "snippet": "Fixed retries cause thundering-herd...", "score": 0.84}
],
"supporting_edges": [
{"src": "dec_8f1a", "rel": "supersedes", "dst": "dec_4c20"}
]
}
okto_pulse_kg_schema_info
Schema introspection. Use this to assert the live schema version before issuing version-specific Cypher, or to discover new node/edge types after an upgrade.
Input:
board_id: "brd_abc123"
Output:
{
"schema_version": "0.3.3",
"node_types": ["Decision", "Criterion", "Constraint", "Assumption", "Requirement",
"Entity", "APIContract", "TestScenario", "Bug", "Learning", "Alternative"],
"rel_types": ["supersedes", "contradicts", "derives_from", "relates_to", "mentions",
"depends_on", "violates", "implements", "tests", "validates", "belongs_to"],
"vector_indexes": [
{"node_type": "Decision", "dim": 384, "metric": "cosine", "model": "sentence-transformers/all-MiniLM-L6-v2"},
{"node_type": "Constraint", "dim": 384, "metric": "cosine"},
{"node_type": "Requirement", "dim": 384, "metric": "cosine"},
{"node_type": "Entity", "dim": 384, "metric": "cosine"},
{"node_type": "Learning", "dim": 384, "metric": "cosine"}
]
}
okto_pulse_kg_verify_grounding
Verify that an agent-generated answer is actually backed by retrieved KG nodes. V1: deterministic entity check + Jaccard fallback at 0.7 threshold.
Input:
board_id: "brd_abc123"
answer_text: "We use exponential backoff with jitter to avoid thundering-herd retries."
retrieved_nodes: ["dec_8f1a", "con_99"]
Output:
{
"grounded": true,
"score": 0.82,
"matched_entities": ["exponential backoff", "jitter", "retries"],
"unmatched_phrases": []
}
okto_pulse_kg_query_reflective
V1 stub of the reflective retrieve-critic loop. Returns a single retrieve+critic pass. The full multi-step loop requires an LLM callable wired through the Python API — this MCP variant is intentionally a thin stub.
Input:
board_id: "brd_abc123"
query: "What constraints apply to webhook retries?"
Output:
{
"stub": true,
"candidates": [
{"node_id": "con_2e", "title": "Webhook receivers must respond within 30s", "score": 0.79}
],
"critic_notes": "Single-pass retrieval. For multi-step reflection, use the Python API."
}
| You want… | Use |
|---|
| Decisions about a topic, ordered in time | kg_get_decision_history |
| Everything within 2 hops of a node | kg_get_related_context |
| The full supersedes chain back to the root | kg_get_supersedence_chain |
| Pairs of nodes that contradict each other | kg_find_contradictions |
| Top-N decisions by hybrid similarity score | kg_find_similar_decisions |
| The origin and downstream impact of a constraint | kg_explain_constraint |
| Why an alternative was rejected | kg_list_alternatives |
| Lessons from past bugs in an area | kg_get_learning_from_bugs |
| Cross-board semantic search | kg_query_global |
| An arbitrary read query | kg_query_cypher |
| Plain-English question against this board | kg_query_natural |
| The live schema | kg_schema_info |
| Verify an answer is grounded in graph data | kg_verify_grounding |
| One-shot reflective retrieve | kg_query_reflective |
Determinism note
Every primary query and every power tool except kg_query_reflective is deterministic over a fixed graph state. Same board_id + same input + same graph.lbug snapshot = same output. This is what makes the KG safe to depend on for long-horizon agent decisions.
Next steps
Consolidation
Write nodes and edges into the graph through transactional sessions.
Health & migration
Operate the consolidation pipeline: queue depth, dead-letter, decay tick, schema migration.
