> ## 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 > How Pulse persists decisions, constraints, and learnings across sessions, sprints, and agent changes — so the agent remembers what you decided, even after the chat ends. # 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: ```text theme={null} ~/.okto-pulse/boards/{board_id}/graph.lbug ``` A global discovery index spans all boards: ```text theme={null} ~/.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: ```text theme={null} 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: ```text theme={null} 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: ```text theme={null} 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: ```text theme={null} 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: ```bash theme={null} okto-pulse kg backfill dry run okto-pulse kg backfill --apply enqueue and drain okto-pulse kg dedup-entities --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 How the six stages from Ideation to Validation feed the KG. Connect your agent to start using KG tools in sessions.