cortivex-knowledge

Cortivex Knowledge Graph

This skill covers how KnowledgeCurator nodes maintain shared CRDT knowledge graphs across pipeline agents, preventing duplicate work and synthesizing findings from multiple agents working in parallel.

Overview

When multiple agents analyze the same codebase, they independently discover facts about files, functions, patterns, and relationships. Without coordination, agents duplicate effort and produce redundant findings. The KnowledgeCurator node solves this by maintaining a shared knowledge graph that all agents can read from and write to.

The knowledge graph uses Conflict-free Replicated Data Types (CRDTs) for eventual consistency. This means:

• Any agent can add knowledge at any time without locks
• Concurrent additions from multiple agents merge automatically without conflicts
• No central coordinator is required for graph updates
• All agents converge to the same view of the graph

When to Use

• Pipelines with 2+ analysis agents working on the same codebase
• When agents should be aware of what other agents have already discovered
• To prevent multiple agents from analyzing the same file or function
• When downstream nodes need a unified summary of all agent findings
• For long-running pipelines where agents accumulate knowledge over time

You do NOT need a KnowledgeCurator for:

• Single-agent pipelines
• Pipelines where agents work on completely separate files with no overlap
• Simple sequential DAGs where each node receives the full output of the previous one

How It Works

Knowledge Node Types

The graph stores five types of knowledge nodes:

| Type | Represents | Examples | |------|-----------|----------| | Entity | A specific code artifact | src/auth/login.ts, validateJWT(), UserModel | | Concept | An abstract pattern or principle | "repository pattern", "middleware chain", "dependency injection" | | Process | A workflow or operational procedure | "CI/CD pipeline", "database migration", "build process" | | Data | A data structure or schema | "User model", "JWT payload", "API response schema" | | Finding | An analysis result from an agent | "SQL injection in queries.ts:47", "O(n^2) loop in filter.ts:34" |

Edge Types

Relationships between nodes are typed:

| Edge | Meaning | Example | |------|---------|---------| | uses | Entity A calls or imports Entity B | login.ts uses validateJWT() | | implements | Entity implements a Concept | UserRepository implements "repository pattern" | | depends_on | A requires B to function | auth.ts depends_on session.ts | | produces | A Process produces a Data or Entity | "build process" produces dist/bundle.js | | related_to | General association | "rate limiting" related_to "middleware chain" | | found_in | A Finding was discovered in an Entity | "SQL injection" found_in queries.ts | | supersedes | A newer Finding replaces an older one | "fixed: SQL injection" supersedes "SQL injection" |

CRDT Merge Semantics

• Add-only nodes: Knowledge nodes are never deleted. The graph is a grow-only set.
• Last-write-wins metadata: If two agents update the same node's metadata, the latest timestamp wins.
• Automatic merge: No manual conflict resolution is needed. The CRDT guarantees convergence.
• Idempotent additions: Adding the same node twice has no effect (deduplication is built in).

Pipeline Configuration

Adding a KnowledgeCurator to a Pipeline

name: knowledge-aware-review
version: "1.0"
description: Multi-agent review with shared knowledge graph
nodes:
  - id: knowledge
    type: KnowledgeCurator
    config:
      graph_id: review-session-1
      persist: true
      dedup_strategy: content-hash
      merge_interval_seconds: 5
      max_nodes: 10000
      max_edges: 50000

  - id: security_scan
    type: SecurityScanner
    depends_on: [knowledge]
    config:
      scan_depth: deep
      knowledge_graph: review-session-1
      skip_known_findings: true

  - id: code_review
    type: CodeReviewer
    depends_on: [knowledge]
    config:
      review_scope: changed_files
      knowledge_graph: review-session-1
      skip_known_findings: true

  - id: bug_hunt
    type: BugHunter
    depends_on: [knowledge]
    config:
      hunt_scope: changed_files
      knowledge_graph: review-session-1
      skip_known_findings: true

  - id: synthesize
    type: KnowledgeCurator
    depends_on: [security_scan, code_review, bug_hunt]
    config:
      graph_id: review-session-1
      action: synthesize
      output_format: structured

How Agents Interact with the Graph

When an agent has knowledge_graph configured, it performs these steps during its work:

Before starting analysis on a file:

cortivex_knowledge({
  action: "query",
  graph_id: "review-session-1",
  query: {
    type: "entity",
    label: "src/auth/login.ts"
  }
})

If the file already has findings from another agent, the current agent can skip it or focus on aspects not yet covered.

After discovering something:

cortivex_knowledge({
  action: "add",
  graph_id: "review-session-1",
  nodes: [
    {
      type: "finding",
      label: "SQL injection vulnerability",
      metadata: {
        file: "src/db/queries.ts",
        line: 47,
        severity: "high",
        agent: "agent-security-scanner-1",
        cwe: "CWE-89"
      }
    }
  ],
  edges: [
    {
      type: "found_in",
      source: "SQL injection vulnerability",
      target: "src/db/queries.ts"
    }
  ]
})

Checking for duplicate work:

cortivex_knowledge({
  action: "check_covered",
  graph_id: "review-session-1",
  files: ["src/auth/login.ts", "src/auth/session.ts"]
})

Response:

{
  "src/auth/login.ts": {
    "covered": true,
    "agents": ["agent-code-reviewer-2"],
    "findings_count": 3
  },
  "src/auth/session.ts": {
    "covered": false,
    "agents": [],
    "findings_count": 0
  }
}

The agent can then skip login.ts and focus on session.ts.

Synthesis

After all analysis agents complete, a KnowledgeCurator in synthesize mode produces a unified report:

cortivex_knowledge({
  action: "synthesize",
  graph_id: "review-session-1",
  output_format: "structured"
})

Response:

{
  "graph_stats": {
    "total_nodes": 47,
    "total_edges": 83,
    "entities": 28,
    "findings": 12,
    "concepts": 4,
    "agents_contributed": 3
  },
  "findings_summary": [
    {
      "severity": "high",
      "count": 2,
      "items": ["SQL injection in queries.ts:47", "XSS in render.ts:112"]
    },
    {
      "severity": "medium",
      "count": 5,
      "items": ["..."]
    }
  ],
  "duplicate_work_prevented": {
    "files_skipped": 8,
    "estimated_savings": "$0.024"
  },
  "architecture_insights": [
    "Repository pattern detected in src/db/",
    "Middleware chain in src/api/middleware/"
  ]
}

Querying the Graph

Search by Label

cortivex_knowledge({
  action: "search",
  graph_id: "review-session-1",
  pattern: "auth|login|jwt",
  case_insensitive: true
})

Get All Connections for a Node

cortivex_knowledge({
  action: "neighbors",
  graph_id: "review-session-1",
  node_label: "src/auth/login.ts",
  depth: 2
})

Graph Statistics

cortivex_knowledge({
  action: "stats",
  graph_id: "review-session-1"
})

KnowledgeCurator Node Reference

- id: knowledge
  type: KnowledgeCurator
  config:
    graph_id: my-graph                  # unique identifier for this graph instance
    persist: true                       # save graph to disk between runs
    storage_path: .cortivex/knowledge/  # directory for persisted graphs
    dedup_strategy: content-hash        # content-hash | label-match | none
    merge_interval_seconds: 5           # how often agents sync with the graph
    max_nodes: 10000                    # cap on graph size
    max_edges: 50000                    # cap on edge count
    action: maintain                    #