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:

Queries

14 read tools — primary query API plus the Cypher / natural-language / introspection escape hatches.

Consolidation

7 transactional write primitives that materialize artifacts as nodes and edges.

Health & migration

5 admin tools for queue depth, dead-letter recovery, decay tick, and schema migration.

Archive & retention

Cascading entity archive and the KG’s retention model — supersedence, decay, dead-letter TTL.

For the conceptual “why does the KG exist” framing, see 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:

~/.okto-pulse/boards/{board_id}/graph.lbug

A cross-board discovery index covers global semantic search:

~/.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” but the runtime has been ladybug since okto-pulse-core 0.1.14. Both files are pure local SQLite-style artifacts — no separate database server runs.

Never delete graph.lbug to fix an issue. Use the health tools and the okto-pulse kg backfill CLI command. Deleting the file loses all decision history for that board.

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:

okto_pulse_kg_schema_info

Returns node types, edge types, vector index list, schema version. See queries 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.

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.

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.

Permissions and authentication

Every KG tool runs under the standard Pulse API key / Bearer / PULSE_API_TOKEN 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:

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.
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.

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Knowledge Graph operations — overview

Knowledge Graph operations — overview

Queries

Consolidation

Health & migration

Archive & retention

Storage model

Schema (v0.3.3)

11 node types

10 relationship types + `belongs_to` multi-pair

5 HNSW vector indexes

The 26 tools at a glance

Consolidation — 7 transactional primitives

Queries — 9 primary tools

Power tools — 5 escape hatches

Admin — 5 operational tools

Permissions and authentication

When to use which tool

Determinism guarantees

Next steps

Queries

Consolidation

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Documentation Index

​Knowledge Graph operations — overview

Queries

Consolidation

Health & migration

Archive & retention

​Storage model

​Schema (v0.3.3)

​11 node types

​10 relationship types + belongs_to multi-pair

​5 HNSW vector indexes

​The 26 tools at a glance

​Consolidation — 7 transactional primitives

​Queries — 9 primary tools

​Power tools — 5 escape hatches

​Admin — 5 operational tools

​Permissions and authentication

​When to use which tool

​Determinism guarantees

​Next steps

Queries

Consolidation

Knowledge Graph operations — overview

Storage model

Schema (v0.3.3)

11 node types

10 relationship types + `belongs_to` multi-pair

5 HNSW vector indexes

The 26 tools at a glance

Consolidation — 7 transactional primitives

Queries — 9 primary tools

Power tools — 5 escape hatches

Admin — 5 operational tools

Permissions and authentication

When to use which tool

Determinism guarantees

Next steps