Knowledge Graph

Chat context resets every session. The Knowledge Graph does not. Every decision, constraint, bug learning, and spec outcome consolidates into a per-board embedded graph database. When your agent starts work on a new ideation, it queries this graph before deciding anything. It finds prior decisions, detects contradictions, and traces supersedence chains — not from memory, from a durable graph.

The problem it solves

When you build with AI agents across multiple sessions, three failure modes appear quickly:

Lost decisions. The agent re-decides something you already locked down two sprints ago, because the earlier decision only lives in a closed chat thread.
Contradictions without notice. A new spec requirement silently violates a constraint established in a different spec. Nobody catches it until something breaks.
Supersedence drift. You change an architectural decision. The agent keeps applying the old rule because it was never marked as superseded.

The Knowledge Graph is the structural fix for all three.

How it works

Each Pulse board has an embedded graph database stored at:

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

A global discovery index spans all boards:

~/.okto-pulse/global/discovery.lbug

The graph is written by the KG consolidation pipeline — a background worker that takes artifacts from the SQLite queue and materializes them as typed nodes and edges. Agents interact with the KG via 26 dedicated MCP tools, not by writing to the graph directly.

Node types

The graph has 11 typed 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, etc.)
`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

Relationship types

10 typed edge types connect nodes:

Edge	Meaning
`supersedes`	This node replaces an earlier one. The old node is not deleted — the chain is preserved.
`contradicts`	These two nodes are in tension. Contradiction detection surfaces this before the agent proceeds.
`derives_from`	This node was derived from another (spec from ideation, decision from constraint, etc.)
`relates_to`	General association
`mentions`	A node references another in its content
`depends_on`	This node cannot be implemented without the other
`violates`	An implementation or decision crosses a stated constraint
`implements`	A task or code path implements this requirement or contract
`tests`	A test scenario validates this requirement or contract
`validates`	A validation record confirms this node passed its evidence gate

What the agent does with it

At every ideation and refinement, the agent is expected to query the KG before making decisions. The MCP tools it uses:

okto_pulse_kg_query_natural        Ask a natural-language question against the graph
okto_pulse_kg_find_similar_decisions   Surface decisions that are semantically close
okto_pulse_kg_find_contradictions  Detect edges between the current context and existing nodes
okto_pulse_kg_get_supersedence_chain   Trace what replaced what, in order
okto_pulse_kg_get_related_context  Pull the subgraph around a named entity
okto_pulse_kg_explain_constraint   Get the rationale behind a constraint node

When the agent finds a prior decision that applies, it cites it. When it finds a contradiction, it surfaces it to the user before proceeding. When it detects that a decision was superseded, it uses the current node, not the stale one.

Consolidation — how nodes get in

Agents do not write directly to the graph. They create artifacts in the standard Pulse pipeline (decisions, specs, validation records, bug conclusions). The consolidation pipeline picks those up from a SQLite queue and writes them to the graph as typed nodes. The typical consolidation flow:

Agent completes a spec evaluation or task validation.
The core service writes a consolidation record to the queue.
The background worker calls kg_begin_consolidation → adds node and edge candidates → kg_commit_consolidation.
The node is now queryable.

Agents with direct KG access can also run explicit consolidation via:

okto_pulse_kg_begin_consolidation
okto_pulse_kg_add_node_candidate
okto_pulse_kg_add_edge_candidate
okto_pulse_kg_commit_consolidation

Health and diagnostics

The KG exposes a health view in the Pulse board UI (polls every 30 seconds) and via MCP:

okto_pulse_kg_health

This returns queue depth, oldest pending age, dead-letter count, decay tick freshness, and relevance score health. If consolidation is stuck:

okto_pulse_kg_dead_letter_list      See what failed to consolidate
okto_pulse_kg_dead_letter_reprocess Retry failed items
okto_pulse_kg_tick_run_now          Trigger the decay tick immediately

For deeper repair, the CLI provides:

okto-pulse kg backfill <board_id>          dry run
okto-pulse kg backfill <board_id> --apply  enqueue and drain
okto-pulse kg dedup-entities <board_id> --dry-run

Do not delete graph.lbug files to fix KG issues. Use the health and backfill tools above. Deleting the graph loses all decision history for that board.

Summary

The Knowledge Graph is the layer that makes multi-session, multi-agent work coherent. Chat resets. The graph does not. Decisions, constraints, and learnings written today are queryable by any agent working on the same board tomorrow — or in three months, after a team change, after a model upgrade. It is the reason Pulse calls itself a control plane rather than a kanban board.

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Knowledge Graph

Knowledge Graph

The problem it solves

How it works

Node types

Relationship types

What the agent does with it

Consolidation — how nodes get in

Health and diagnostics

Summary

Next steps

ADLC pipeline

MCP setup

​Knowledge Graph

​The problem it solves

​How it works

​Node types

​Relationship types

​What the agent does with it

​Consolidation — how nodes get in

​Health and diagnostics

​Summary

​Next steps

ADLC pipeline

MCP setup

Knowledge Graph

The problem it solves

How it works

Node types

Relationship types

What the agent does with it

Consolidation — how nodes get in

Health and diagnostics

Summary

Next steps