Skip to main content

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

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:
  1. 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.
  2. Contradictions without notice. A new spec requirement silently violates a constraint established in a different spec. Nobody catches it until something breaks.
  3. 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 22 dedicated MCP tools, not by writing to the graph directly.

​
Node types

The graph has 11 typed node types:
Node typeWhat it holds
DecisionA locked design or architectural choice, with rationale
CriterionAn evaluation axis used to make a decision
ConstraintA hard boundary the implementation must not cross
AssumptionA condition assumed true at decision time
RequirementA functional or non-functional requirement
EntityA named domain concept (service, model, user type, etc.)
APIContractA contract between components: endpoints, payloads, error shapes
TestScenarioA scenario with evidence of pass/fail, linked to source code
BugA defect with root cause and resolution
LearningA lesson from a bug, failed experiment, or retrospective
AlternativeA rejected option, with the reason it was not chosen

​
Relationship types

10 typed edge types connect nodes:
EdgeMeaning
supersedesThis node replaces an earlier one. The old node is not deleted — the chain is preserved.
contradictsThese two nodes are in tension. Contradiction detection surfaces this before the agent proceeds.
derives_fromThis node was derived from another (spec from ideation, decision from constraint, etc.)
relates_toGeneral association
mentionsA node references another in its content
depends_onThis node cannot be implemented without the other
violatesAn implementation or decision crosses a stated constraint
implementsA task or code path implements this requirement or contract
testsA test scenario validates this requirement or contract
validatesA 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:
  1. Agent completes a spec evaluation or task validation.
  2. The core service writes a consolidation record to the queue.
  3. The background worker calls kg_begin_consolidation → adds node and edge candidates → kg_commit_consolidation.
  4. 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, dead-letter count, last tick timestamp, and schema-drift warnings. 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 consolidation worker 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.

​
Next steps

ADLC pipeline

How the six stages from Ideation to Validation feed the KG.

MCP setup

Connect your agent to start using KG tools in sessions.
Last modified on May 7, 2026