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 consolidation

Consolidation is the only path that writes to a Pulse Knowledge Graph. Seven MCP tools compose into a single transactional flow: 
begin → add_node_candidate* → add_edge_candidate* → propose_reconciliation → commit
                                                                          \
                                                                           → abort
The session is in-memory until commit, which atomically writes all candidates plus an audit row plus an outbox event. A content-hash check on begin short-circuits no-op replays. Sessions expire after 1 hour (kg_session_ttl_seconds). Each primitive is gated by its own dotted-string flag in the granular permission registry: kg.session.begin, kg.session.add_node, kg.session.add_edge, kg.session.get_similar, kg.session.propose, kg.session.commit, kg.session.abort. The meaningful gate is kg.session.commit — presets sometimes grant everything except commit for dry-run-only roles. Cognitive agents typically receive the full set. User-facing dashboards typically receive none. See overview for the full preset model. Source: okto-pulse-core/src/okto_pulse/core/mcp/kg_tools.py:register_kg_tools. Citations below reference 80-pulse-feature-inventory.md:503–515.

​
The transactional flow

​
1. okto_pulse_kg_begin_consolidation

Open a session for a board. Pulse computes a content_hash over the artifact you are consolidating (a spec, a card validation record, a decision artifact); if a previous commit produced the same hash, the call returns nothing_changed: true and you can skip the rest. 
Input:
  board_id:       "brd_abc123"
  source_type:    "spec"
  source_id:      "spec_007"
  source_version: 4
  payload_hash:   "sha256:8c1f..."   (optional — Pulse computes if omitted)

Output:
{
  "session_id":      "kgs_01HV...",
  "content_hash":    "sha256:8c1f...",
  "nothing_changed": false,
  "expires_at":      "2026-05-07T16:30:00Z"
}
When nothing_changed: true, abort and exit: 
{
  "session_id":      null,
  "content_hash":    "sha256:8c1f...",
  "nothing_changed": true
}

​
2. okto_pulse_kg_add_node_candidate

Add a node candidate to the open session. Stays in-memory until commit. Call once per node you want to materialize. 
Input:
  session_id:  "kgs_01HV..."
  node_type:   "Decision"
  title:       "Exponential backoff with jitter for webhook retries"
  body:        "Fixed retries cause thundering-herd at peer recovery..."
  attributes:  {"confidence": 0.9, "rationale": "..."}
  source_ref:  {"spec_id": "spec_007", "section": "retry-strategy"}

Output:
{
  "candidate_id": "cand_001",
  "node_type":    "Decision",
  "embedding_status": "queued"
}
Embeddings are computed on commit, not on add. The attributes map is type-specific — Decision accepts rationale/confidence, Constraint accepts severity/scope, etc. Unknown keys are dropped on commit with a warning in the audit row.

​
3. okto_pulse_kg_add_edge_candidate

Add an edge candidate connecting two candidates (or one candidate and one existing node by node_id).
Cognitive agents may only add 5 edge types: supersedes, contradicts, depends_on, relates_to, validates.The remaining 6 (derives_from, mentions, violates, implements, tests, belongs_to) are reserved for the Layer 1 deterministic worker. Attempts to add them via MCP return a 403 reserved_edge_type error.
Input:
  session_id: "kgs_01HV..."
  src:        {"candidate_id": "cand_001"}
  dst:        {"node_id":      "dec_4c20"}     # existing node
  rel_type:   "supersedes"
  attributes: {"reason": "thundering-herd at recovery"}

Output:
{
  "edge_candidate_id": "edge_cand_001",
  "rel_type":          "supersedes",
  "valid":             true
}

​
4. okto_pulse_kg_get_similar_nodes

Before reconciling, ask the graph what existing nodes look like a given candidate. Used to decide whether to UPDATE an existing node, SUPERSEDE it, or add a fresh one. HNSW vector search if the candidate type has an index, else title-prefix fallback. 
Input:
  session_id:   "kgs_01HV..."
  candidate_id: "cand_001"
  k:            5

Output:
{
  "candidate_id": "cand_001",
  "match_mode":   "hnsw",
  "matches": [
    {"node_id": "dec_4c20", "title": "Fixed 3s retry interval, 5 attempts", "score": 0.78},
    {"node_id": "dec_001",  "title": "No retry — drop on failure",          "score": 0.61}
  ]
}

​
5. okto_pulse_kg_propose_reconciliation

Compute reconciliation hints for every candidate in the session. The hints are advisory — commit will use them by default but you can override per candidate. 
Input:
  session_id: "kgs_01HV..."

Output:
{
  "session_id": "kgs_01HV...",
  "proposals": [
    {
      "candidate_id": "cand_001",
      "hint":         "SUPERSEDE",
      "target_node":  "dec_4c20",
      "rationale":    "Same topic, newer rationale, contradicts older fixed-interval rule"
    },
    {
      "candidate_id": "cand_002",
      "hint":         "ADD",
      "rationale":    "No similar node above 0.7 threshold"
    }
  ]
}
Hint semantics:
HintMeaning
ADDInsert as a new node.
UPDATEUpdate an existing node (target_node) in place. Used for refining attributes.
SUPERSEDEInsert as new + add supersedes edge to target_node. The old node is preserved.
NOOPAlready present and unchanged — drop on commit.

​
6. okto_pulse_kg_commit_consolidation

Atomically write all candidates. Pulse runs four side-effects in one transaction:
  1. Embed each new node (sentence-transformers, 384-dim).
  2. Apply node and edge candidates per their hint (or per agent_overrides).
  3. Append a row to the audit table with the full session payload + hash.
  4. Emit an outbox event for downstream consumers.
Input:
  session_id: "kgs_01HV..."
  agent_overrides:                                     (optional)
    - candidate_id: "cand_001"
      hint:         "ADD"                              # override SUPERSEDE → ADD
      rationale:    "Keeping both — different scopes"

Output:
{
  "session_id":  "kgs_01HV...",
  "committed":   true,
  "applied": {
    "added":      [{"candidate_id": "cand_001", "node_id": "dec_8f1a"}],
    "updated":    [],
    "superseded": [],
    "noop":       []
  },
  "edges_added": [
    {"edge_id": "edge_551", "src": "dec_8f1a", "rel": "supersedes", "dst": "dec_4c20"}
  ],
  "audit_row_id": 17284,
  "outbox_event": "kg.consolidated.v1"
}
If commit fails (lock conflict, schema violation, embedder timeout), nothing lands and the session enters a committable: false state. Either retry commit or call abort.

​
7. okto_pulse_kg_abort_consolidation

Drop an in-flight session without writing anything. No compensating delete is needed because nothing was persisted yet. 
Input:
  session_id: "kgs_01HV..."

Output:
{
  "session_id": "kgs_01HV...",
  "aborted":    true
}
Use abort when:
  • nothing_changed is detected after add_* is already in flight.
  • Reconciliation surfaces a contradiction the agent isn’t allowed to introduce.
  • Session TTL is about to expire and you can’t finish the work.

​
End-to-end example

A cognitive agent finishes a spec evaluation and wants to record the resulting Decision and a supersedes edge to the previous decision on the same topic. 
1. begin_consolidation(spec_007 v4)
   → session_id, content_hash, nothing_changed=false

2. add_node_candidate(type=Decision, title="Exponential backoff...")
   → cand_001

3. get_similar_nodes(cand_001, k=5)
   → matches[0] = {dec_4c20, score=0.78}

4. add_edge_candidate(src=cand_001, dst=dec_4c20, rel=supersedes)
   → edge_cand_001

5. propose_reconciliation()
   → cand_001: SUPERSEDE → dec_4c20

6. commit_consolidation()
   → added: [dec_8f1a], edges: [supersedes dec_8f1a → dec_4c20]
That’s the full happy path. Six tool calls. The seventh (abort) is only reached on the unhappy path.

​
Idempotency and replay safety

Two layers protect the graph from duplicate writes:
  1. Content hash on begin. Re-consolidating the same (source_type, source_id, source_version) with no actual change returns nothing_changed: true and never enters a session. Replays are safe.
  2. NOOP reconciliation hint. Even when a session is opened, candidates whose existing nodes already match are tagged NOOP and skipped on commit.
The combination means an agent can safely call the consolidation flow on every spec evaluation without worrying about bloating the graph with duplicates.

​
Permissions and audit trail

Every consolidation produces an audit row containing the session id, content hash, all candidates, all reconciliation hints, all overrides, and the agent identity from the API key. The audit row is the system-of-record — query the graph to see what the state is, query the audit table to see how it got there. The 6 deterministic edge types (derives_from, mentions, violates, implements, tests, belongs_to) are written exclusively by the Layer 1 worker, not via MCP. This keeps cognitive agents out of structural-graph mutations and makes the deterministic skeleton machine-checkable.

​
Common errors

ErrorCauseFix
403 reserved_edge_typeAgent tried to add derives_from / mentions / violates / implements / tests / belongs_to via MCP.Use one of the 5 cognitive edge types, or let the Layer 1 worker write the relationship.
409 session_expiredSession exceeded kg_session_ttl_seconds (default 3600).Re-open with begin_consolidation.
409 commit_conflictAnother session committed first and the candidate now collides.Re-run propose_reconciliation and re-commit.
422 unknown_attributeAttribute key not in the type’s schema.Drop the unknown key, or extend the type’s schema.
429 rate_limitToo many consolidations per minute for this agent.Back off and retry.

​
Next steps

Queries

Read tools that surface what’s in the graph after consolidation.

Health & migration

Operate the consolidation queue, dead-letter recovery, and decay tick.
Last modified on May 8, 2026