> ## 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 operations — overview

> Reference for the 26 MCP tools that operate the Pulse Knowledge Graph: schema v0.3.3, the ladybug embedded graph store, and the four tool tiers (consolidation, query, power, admin).

# Knowledge Graph operations — overview

The Knowledge Graph (KG) is the durable layer behind every Pulse board. While chat sessions reset, the KG persists decisions, constraints, alternatives, learnings, and the relationships between them — and exposes that history through **26 dedicated MCP tools**.

This page indexes those tools and the guarantees they sit on. The four sibling pages drill into each tier with full input/output samples:

<CardGroup cols={2}>
  <Card title="Queries" href="/reference/mcp/kg/queries">
    14 read tools — primary query API plus the Cypher / natural-language / introspection escape hatches.
  </Card>

  <Card title="Consolidation" href="/reference/mcp/kg/consolidation">
    7 transactional write primitives that materialize artifacts as nodes and edges.
  </Card>

  <Card title="Health & migration" href="/reference/mcp/kg/health">
    5 admin tools for queue depth, dead-letter recovery, decay tick, and schema migration.
  </Card>

  <Card title="Archive & retention" href="/reference/mcp/kg/archive">
    Cascading entity archive and the KG's retention model — supersedence, decay, dead-letter TTL.
  </Card>
</CardGroup>

For the conceptual "why does the KG exist" framing, see [Knowledge Graph](/concepts/knowledge-graph). This reference page assumes you already know what the graph is and want to call it.

***

## Storage model

Each board has its own embedded graph database file:

```text theme={null}
~/.okto-pulse/boards/{board_id}/graph.lbug
```

A cross-board discovery index covers global semantic search:

```text theme={null}
~/.okto-pulse/global/discovery.lbug
```

The store is **ladybug** (`.lbug` extension) — an embedded property-graph database with HNSW vector indexes built in. Pulse migrated from Kuzu to ladybug on 2026-05-03; some inline source comments still say "Kùzu" because legacy env-var names were preserved. Both files are pure local SQLite-style artifacts — no separate database server runs.

<Warning>
  Never delete `graph.lbug` to fix an issue. Use the [health tools](/reference/mcp/kg/health) and the `okto-pulse kg backfill` CLI command. Deleting the file loses all decision history for that board.
</Warning>

***

## Schema (v0.3.3)

Source: `okto-pulse-feature-inventory.md:1124–1132` and `okto-pulse-core/src/okto_pulse/core/kg/schema.py`.

### 11 node types

| Node type      | What it holds                                                    |
| -------------- | ---------------------------------------------------------------- |
| `Decision`     | A locked design or architectural choice, with rationale          |
| `Criterion`    | An evaluation axis used to make a decision                       |
| `Constraint`   | A hard boundary the implementation must not cross                |
| `Assumption`   | A condition assumed true at decision time                        |
| `Requirement`  | A functional or non-functional requirement                       |
| `Entity`       | A named domain concept (service, model, user type)               |
| `APIContract`  | A contract between components: endpoints, payloads, error shapes |
| `TestScenario` | A scenario with evidence of pass/fail, linked to source code     |
| `Bug`          | A defect with root cause and resolution                          |
| `Learning`     | A lesson from a bug, failed experiment, or retrospective         |
| `Alternative`  | A rejected option, with the reason it was not chosen             |

### 10 relationship types + `belongs_to` multi-pair

| Edge           | Meaning                                                                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `supersedes`   | Replaces an earlier node. The old node stays — the chain is preserved.                                                                               |
| `contradicts`  | Two nodes are in tension. Surfaced before the agent advances.                                                                                        |
| `derives_from` | Node was derived from another (spec from ideation, decision from constraint).                                                                        |
| `relates_to`   | General association, weakest link.                                                                                                                   |
| `mentions`     | Node references another in its content.                                                                                                              |
| `depends_on`   | Cannot be implemented without the other.                                                                                                             |
| `violates`     | Implementation crosses a stated constraint.                                                                                                          |
| `implements`   | Task or code path implements this requirement or contract.                                                                                           |
| `tests`        | Test scenario validates this requirement or contract.                                                                                                |
| `validates`    | Validation record confirms this node passed its evidence gate.                                                                                       |
| `belongs_to`   | Multi-pair containment edge — links a node to its source artifact (spec, sprint, board). One physical edge type, multiple typed source/target pairs. |

### 5 HNSW vector indexes

Each `Decision`, `Constraint`, `Requirement`, `Entity`, and `Learning` node carries a 384-dimensional embedding (default model `sentence-transformers/all-MiniLM-L6-v2`). One HNSW index per type powers semantic search in `kg_query_natural`, `kg_find_similar_decisions`, and `kg_get_decision_history`.

Inspect the live schema with the introspection tool:

```text theme={null}
okto_pulse_kg_schema_info
```

Returns node types, edge types, vector index list, schema version. See [queries](/reference/mcp/kg/queries#kg_schema_info) for the full payload.

***

## The 26 tools at a glance

Source: `okto-pulse-feature-inventory.md:493–546`. Total = 5 admin (in `server.py`) + 7 consolidation (`kg_tools.py`) + 9 query primary (`kg_query_tools.py`) + 5 power (`kg_power_tools.py`).

### Consolidation — 7 transactional primitives

`okto-pulse-core/src/okto_pulse/core/mcp/kg_tools.py:register_kg_tools`

| Tool                                   | Purpose                                                                                                                     |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `okto_pulse_kg_begin_consolidation`    | Open a consolidation session. Returns `session_id`, `content_hash`, `nothing_changed`. TTL 1 h.                             |
| `okto_pulse_kg_add_node_candidate`     | Add a node candidate to the open session (in-memory until commit).                                                          |
| `okto_pulse_kg_add_edge_candidate`     | Add an edge candidate. Cognitive agents may only add: `supersedes`, `contradicts`, `depends_on`, `relates_to`, `validates`. |
| `okto_pulse_kg_get_similar_nodes`      | Find existing nodes similar to a candidate (HNSW + title-prefix fallback).                                                  |
| `okto_pulse_kg_propose_reconciliation` | Compute `ADD` / `UPDATE` / `SUPERSEDE` / `NOOP` hints for every candidate.                                                  |
| `okto_pulse_kg_commit_consolidation`   | Atomically write all candidates + audit row + outbox event. Supports per-candidate overrides.                               |
| `okto_pulse_kg_abort_consolidation`    | Drop an in-flight session — no compensating delete needed.                                                                  |

Full reference and a worked example: [consolidation](/reference/mcp/kg/consolidation).

### Queries — 9 primary tools

`okto-pulse-core/src/okto_pulse/core/mcp/kg_query_tools.py:register_kg_query_tools`

| Tool                                   | Purpose                                                                                                |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `okto_pulse_kg_get_decision_history`   | Trace decisions about a topic over time. Hybrid HNSW + title-CONTAINS.                                 |
| `okto_pulse_kg_get_related_context`    | 2-hop neighborhood traversal. Filterable by edge type, direction, depth.                               |
| `okto_pulse_kg_get_supersedence_chain` | Trace what superseded what (depth ≤ 10).                                                               |
| `okto_pulse_kg_find_contradictions`    | Find `contradicts` pairs — board-wide or anchored to a node.                                           |
| `okto_pulse_kg_find_similar_decisions` | Hybrid ranked similarity: 0.5 × semantic + 0.2 × graph\_centrality + 0.2 × recency + 0.1 × confidence. |
| `okto_pulse_kg_explain_constraint`     | Origin spec/decision + related constraints + violations (`Bug` nodes).                                 |
| `okto_pulse_kg_list_alternatives`      | Alternatives considered and discarded for a decision (with `reason_discarded`).                        |
| `okto_pulse_kg_get_learning_from_bugs` | `Learning → Bug` via `validates` edges.                                                                |
| `okto_pulse_kg_query_global`           | Cross-board semantic search via the global discovery layer (ACL-filtered).                             |

### Power tools — 5 escape hatches

`okto-pulse-core/src/okto_pulse/core/mcp/kg_power_tools.py:register_kg_power_tools`

| Tool                             | Purpose                                                                                                                 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `okto_pulse_kg_query_cypher`     | Read-only Cypher. Write-keyword whitelist, auto-`LIMIT`, `*..20` path bound, 30 s timeout, 30 req/min rate limit.       |
| `okto_pulse_kg_query_natural`    | Natural-language search (hybrid embedding + HNSW + traversal). `since` / `until` filters. Fully deterministic — no LLM. |
| `okto_pulse_kg_schema_info`      | Schema introspection: node types, rel types, vector indexes, schema version.                                            |
| `okto_pulse_kg_verify_grounding` | Verify an agent's answer is grounded in retrieved KG nodes. V1: deterministic entity check + Jaccard 0.7 fallback.      |
| `okto_pulse_kg_query_reflective` | V1 stub of the reflective retrieve-critic loop. Full loop requires LLM callable — use the Python API.                   |

The 14 read tools (9 primary + 5 power) are documented in full on [queries](/reference/mcp/kg/queries).

### Admin — 5 operational tools

`okto-pulse-core/src/okto_pulse/core/mcp/server.py:12484–12857`

| Tool                                  | Line  | Purpose                                                             |
| ------------------------------------- | ----- | ------------------------------------------------------------------- |
| `okto_pulse_kg_health`                | 12484 | KG pipeline health: queue depth, dead-letter count, tick freshness. |
| `okto_pulse_kg_dead_letter_list`      | 12527 | List failed consolidation entries.                                  |
| `okto_pulse_kg_dead_letter_reprocess` | 12570 | Retry dead-letter entries (move back to queue).                     |
| `okto_pulse_kg_migrate_schema`        | 12643 | Trigger schema migration for a board's graph.                       |
| `okto_pulse_kg_tick_run_now`          | 12716 | Trigger the decay tick worker immediately (normally daily).         |

Walkthrough with output samples: [health & migration](/reference/mcp/kg/health).

***

## Permissions and authentication

Every KG tool runs under the standard Pulse [API key / Bearer / `PULSE_API_TOKEN`](/reference/mcp#authentication) auth model. Permissions live in the granular registry at `okto-pulse-core/src/okto_pulse/core/infra/permissions.py:PERMISSION_REGISTRY` as dotted-string flags under the `kg.*` namespace:

* `kg.query.*` — every primary read tool (`decision_history`, `related_context`, `supersedence_chain`, `contradictions`, `similar_decisions`, `constraint_explain`, `alternatives`, `learning_from_bugs`, `global`). Granted as a wildcard or per-tool.
* `kg.power.natural`, `kg.power.schema_info`, `kg.power.cypher` — the read-side power tools split across three flags. `kg.power.cypher` is the most restricted; `kg.power.natural` and `kg.power.schema_info` ship in most presets.
* `kg.session.begin`, `kg.session.add_node`, `kg.session.add_edge`, `kg.session.get_similar`, `kg.session.propose`, `kg.session.commit`, `kg.session.abort` — one flag per consolidation primitive. `kg.session.commit` is the meaningful gate; some presets grant everything except `commit` for dry-run-only roles.
* `kg.admin.settings_read`, `kg.admin.settings_write`, `kg.admin.historical_consolidation`, `kg.admin.wipe_board` — the operational surface. `kg.admin.historical_consolidation` gates dead-letter reprocess + CLI backfill drain.

Permission presets are defined alongside the registry. Cognitive agents typically receive the full `kg.query.*` set plus the `kg.session.*` flags up to and including `commit`. User-facing dashboard agents typically receive `kg.query.*` plus `kg.power.natural` / `kg.power.schema_info`. Operator presets layer in `kg.admin.*` flags. The two power tools `kg.power.cypher` and `kg.session.commit` plus the `kg.admin.*` namespace are the high-trust flags — only grant them deliberately.

***

## When to use which tool

| You want to…                                                 | Reach for                                                                   |
| ------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Ask the graph a question in plain English                    | `kg_query_natural`                                                          |
| Pull every decision Pulse has made about a topic, in order   | `kg_get_decision_history`                                                   |
| Walk the neighborhood around a single node                   | `kg_get_related_context`                                                    |
| Write a new decision / constraint / learning to the graph    | `kg_begin_consolidation` → `kg_add_*_candidate` → `kg_commit_consolidation` |
| Detect that two specs are in tension before advancing        | `kg_find_contradictions`                                                    |
| Confirm an agent's answer is actually backed by graph nodes  | `kg_verify_grounding`                                                       |
| Run an arbitrary read query that the typed tools don't cover | `kg_query_cypher`                                                           |
| Inspect the live schema                                      | `kg_schema_info`                                                            |
| Check whether the consolidation pipeline is healthy          | `kg_health`                                                                 |
| Recover from a stuck consolidation run                       | `kg_dead_letter_list` → `kg_dead_letter_reprocess`                          |

***

## Determinism guarantees

Two properties make the KG safe to depend on across sessions:

1. **No LLM in the read path.** `kg_query_natural`, `kg_find_similar_decisions`, and the rest of the primary query tier use the same embedding model (default `sentence-transformers/all-MiniLM-L6-v2`, 384-dim) plus deterministic graph traversal. Same input + same graph state always returns the same result. `kg_query_reflective` is the lone exception — it is a V1 stub that wraps an LLM critic and is not used by the standard pipeline.
2. **Atomic consolidation.** The 7 primitives compose into a single transaction: `begin → add → propose → commit`. Either every candidate lands or none do, and a content-hash check on `begin` short-circuits a no-op replay (returns `nothing_changed: true`). The audit row + outbox event written by `commit` are the system-of-record for what changed.

These two together are why the graph is treated as durable infrastructure rather than agent scratch space.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Queries" href="/reference/mcp/kg/queries">
    Sample inputs and outputs for the 14 read tools.
  </Card>

  <Card title="Consolidation" href="/reference/mcp/kg/consolidation">
    Walk through writing a decision into the graph end-to-end.
  </Card>
</CardGroup>