Graph Kernel Evo³ — Evolution Cubed

Phase 1: SqliteGraphStore Implementation (1 week)
├── src/store/sqlite.rs — New GraphStore implementation
│   ├── Use sqlx with sqlite feature (compile-time checked)
│   ├── Same schema as knowledge_graph table
│   ├── WAL mode for concurrent reads
│   ├── In-memory option for testing (`:memory:`)
│   └── File-based for production ([home-path])
├── Cargo.toml — New feature flag: `sqlite`
│   ├── sqlx = { features = ["sqlite", "runtime-tokio"] }
│   └── Feature: sqlite = ["sqlx/sqlite", "tokio"]
└── src/bin/graph_kernel_service.rs — Backend selection
    └── Match on DB_BACKEND env var: "sqlite" | "postgres" | "auto"

Phase 2: Sync Engine (3 days)
├── src/sync/mod.rs — Bidirectional sync module
│   ├── Full dump: Supabase → SQLite (initial load)
│   ├── Incremental: Poll Supabase for changes since last_sync_at
│   ├── Write-through: Local writes → SQLite + queue for Supabase push
│   └── Conflict resolution: Last-writer-wins with source tracking
└── Background task: tokio::spawn sync every 5 minutes

Phase 3: Hybrid Mode (2 days)
├── Reads: Always local SQLite (sub-10ms)
├── Writes: Local SQLite + async push to Supabase
├── Sync status in /health response
└── Manual sync trigger: POST /api/admin/sync

// Request
POST /api/knowledge/traverse
{
  "start": "clawdbot",           // Starting entity
  "predicates": ["uses", "depends_on"],  // Edge types to follow (null = any)
  "direction": "outgoing",       // "outgoing" | "incoming" | "both"
  "max_hops": 3,                 // Maximum traversal depth
  "max_results": 100,            // Result set cap
  "min_confidence": 0.5,         // Confidence floor
  "return_paths": true           // Include full path for each result
}

// Response
{
  "paths": [
    {
      "entities": ["clawdbot", "graph-kernel", "postgresql"],
      "edges": [
        {"subject": "clawdbot", "predicate": "uses", "object": "graph-kernel"},
        {"subject": "graph-kernel", "predicate": "uses", "object": "postgresql"}
      ],
      "hops": 2,
      "min_confidence": 0.85
    }
  ],
  "stats": {
    "entities_visited": 42,
    "edges_traversed": 67,
    "elapsed_ms": 12
  }
}

// src/service/traversal.rs
pub async fn traverse_handler(
    State(state): State<Arc<AppState>>,
    Json(request): Json<TraversalRequest>,
) -> Result<Json<TraversalResponse>, (StatusCode, Json<ErrorResponse>)> {
    let pool = state.store.pool();
    let mut visited: HashSet<String> = HashSet::new();
    let mut frontier: VecDeque<(String, Vec<TraversalEdge>, u32)> = VecDeque::new();
    let mut paths: Vec<TraversalPath> = Vec::new();

    frontier.push_back((request.start.clone(), vec![], 0));
    visited.insert(request.start.clone());

    while let Some((entity, path, depth)) = frontier.pop_front() {
        if depth > request.max_hops || paths.len() >= request.max_results {
            break;
        }

        // Query adjacent triples in one SQL call
        let triples = query_adjacent(pool, &entity, &request).await?;

        for triple in triples {
            let next_entity = if request.direction == "incoming" {
                &triple.subject
            } else {
                &triple.object
            };

            let mut new_path = path.clone();
            new_path.push(triple.clone());

            if !visited.contains(next_entity) {
                visited.insert(next_entity.clone());
                paths.push(TraversalPath::from_edges(&new_path));
                frontier.push_back((next_entity.clone(), new_path, depth + 1));
            }
        }
    }

    Ok(Json(TraversalResponse { paths, stats: ... }))
}

// src/service/normalize.rs

use std::collections::HashMap;
use std::sync::LazyLock;

/// Canonical entity normalization rules
static ALIAS_MAP: LazyLock<HashMap<&str, &str>> = LazyLock::new(|| {
    let mut m = HashMap::new();
    // Normalize common aliases
    m.insert("dream weaver", "dream-weaver-engine");
    m.insert("dreamweaver", "dream-weaver-engine");
    m.insert("dream-weaver", "dream-weaver-engine");
    m.insert("clawdbot", "clawdbot");
    m.insert("clawdbot-gateway", "clawdbot");
    m.insert("comp-core", "comp-core");
    m.insert("compcore", "comp-core");
    // ... loaded from config file or embedded resource
    m
});

/// Canonicalize an entity name.
///
/// Steps:
/// 1. Lowercase
/// 2. Trim whitespace
/// 3. Replace spaces/underscores with hyphens
/// 4. Check alias map for known variants
/// 5. Return canonical form
pub fn canonicalize_entity(name: &str) -> String {
    let normalized = name
        .trim()
        .to_lowercase()
        .replace(' ', "-")
        .replace('_', "-");

    ALIAS_MAP
        .get(normalized.as_str())
        .map(|s| s.to_string())
        .unwrap_or(normalized)
}

// In add_knowledge_handler:
let triple = KnowledgeTriple {
    subject: canonicalize_entity(&triple.subject),
    object: canonicalize_entity(&triple.object),
    predicate: triple.predicate.to_lowercase(),
    ..triple
};

// In query_knowledge_handler:
let subject = params.subject.map(|s| canonicalize_entity(&s));
let object = params.object.map(|s| canonicalize_entity(&s));

// src/service/cache.rs

use lru::LruCache;
use parking_lot::RwLock;
use std::hash::{Hash, Hasher};
use std::num::NonZeroUsize;
use std::time::{Duration, Instant};

pub struct QueryCache {
    cache: RwLock<LruCache<u64, CachedResult>>,
    ttl: Duration,
}

struct CachedResult {
    response: KnowledgeQueryResponse,
    cached_at: Instant,
}

impl QueryCache {
    pub fn new(max_entries: usize, ttl_secs: u64) -> Self {
        Self {
            cache: RwLock::new(LruCache::new(
                NonZeroUsize::new(max_entries).unwrap()
            )),
            ttl: Duration::from_secs(ttl_secs),
        }
    }

    pub fn get(&self, key: &KnowledgeQueryParams) -> Option<KnowledgeQueryResponse> {
        let hash = hash_params(key);
        let cache = self.cache.read();
        cache.peek(&hash)
            .filter(|r| r.cached_at.elapsed() < self.ttl)
            .map(|r| r.response.clone())
    }

    pub fn put(&self, key: &KnowledgeQueryParams, response: KnowledgeQueryResponse) {
        let hash = hash_params(key);
        let mut cache = self.cache.write();
        cache.put(hash, CachedResult {
            response,
            cached_at: Instant::now(),
        });
    }

    /// Invalidate all entries (called on write)
    pub fn invalidate(&self) {
        self.cache.write().clear();
    }
}

# Connect
WS /api/knowledge/subscribe

# Subscribe message
{
  "action": "subscribe",
  "filter": {
    "subjects": ["clawdbot", "graph-kernel"],
    "predicates": ["uses", "depends_on"],
    "min_confidence": 0.7
  }
}

# Notification
{
  "event": "triple_created",
  "triple": {
    "subject": "clawdbot",
    "predicate": "uses",
    "object": "gemini-2.5",
    "confidence": 0.95,
    "source": "topology-ingester"
  },
  "timestamp": "2026-02-14T12:00:00Z"
}

// src/service/websocket.rs
use axum::extract::ws::{WebSocket, WebSocketUpgrade};
use tokio::sync::broadcast;

/// Broadcast channel for triple change events
pub struct TripleEventBus {
    sender: broadcast::Sender<TripleEvent>,
}

impl TripleEventBus {
    pub fn new(capacity: usize) -> Self {
        let (sender, _) = broadcast::channel(capacity);
        Self { sender }
    }

    pub fn publish(&self, event: TripleEvent) {
        // Ignore error (no subscribers)
        let _ = self.sender.send(event);
    }

    pub fn subscribe(&self) -> broadcast::Receiver<TripleEvent> {
        self.sender.subscribe()
    }
}

// In route handlers, after successful triple insert:
state.event_bus.publish(TripleEvent::Created(triple));

GET /api/knowledge/graph?subject=clawdbot&hops=2&format=d3
GET /api/knowledge/graph?subject=clawdbot&hops=2&format=mermaid
GET /api/knowledge/graph?subject=clawdbot&hops=2&format=dot

{
  "nodes": [
    {"id": "clawdbot", "group": "service", "weight": 15},
    {"id": "graph-kernel", "group": "service", "weight": 8},
    {"id": "postgresql", "group": "infrastructure", "weight": 3}
  ],
  "links": [
    {"source": "clawdbot", "target": "graph-kernel", "predicate": "uses", "confidence": 0.95},
    {"source": "graph-kernel", "target": "postgresql", "predicate": "uses", "confidence": 0.90}
  ]
}

graph LR
    clawdbot -->|uses| graph-kernel
    graph-kernel -->|uses| postgresql
    clawdbot -->|uses| rag-plusplus

digraph G {
    "clawdbot" -> "graph-kernel" [label="uses"];
    "graph-kernel" -> "postgresql" [label="uses"];
}

// src/service/visualization.rs

pub fn render_d3(paths: &[TraversalPath]) -> D3Graph {
    let mut nodes = IndexSet::new();
    let mut links = Vec::new();

    for path in paths {
        for edge in &path.edges {
            nodes.insert(edge.subject.clone());
            nodes.insert(edge.object.clone());
            links.push(D3Link {
                source: edge.subject.clone(),
                target: edge.object.clone(),
                predicate: edge.predicate.clone(),
                confidence: edge.confidence,
            });
        }
    }

    D3Graph {
        nodes: nodes.into_iter().map(|id| D3Node {
            id: id.clone(),
            group: infer_group(&id),
            weight: links.iter().filter(|l| l.source == id || l.target == id).count(),
        }).collect(),
        links,
    }
}

pub fn render_mermaid(paths: &[TraversalPath]) -> String {
    let mut lines = vec!["graph LR".to_string()];
    let mut seen = HashSet::new();

    for path in paths {
        for edge in &path.edges {
            let key = format!("{}--{}-->{}", edge.subject, edge.predicate, edge.object);
            if seen.insert(key) {
                lines.push(format!(
                    "    {} -->|{}| {}",
                    sanitize_mermaid(&edge.subject),
                    edge.predicate,
                    sanitize_mermaid(&edge.object)
                ));
            }
        }
    }

    lines.join("\n")
}

// Replace sequential inserts with a multi-row VALUES clause
pub async fn bulk_insert_triples(
    pool: &PgPool,
    triples: &[KnowledgeTriple],
) -> Result<BulkInsertResult, sqlx::Error> {
    // Chunk into batches of 500 (PostgreSQL parameter limit ~32K)
    let chunk_size = 500;
    let mut added = 0;
    let mut updated = 0;

    for chunk in triples.chunks(chunk_size) {
        // Build multi-row INSERT
        let mut query = String::from(
            "INSERT INTO knowledge_graph (subject, predicate, object, confidence, source) VALUES "
        );
        let mut params: Vec<String> = Vec::new();
        let mut bind_values: Vec<&str> = Vec::new();

        for (i, triple) in chunk.iter().enumerate() {
            let offset = i * 5;
            params.push(format!(
                "(${}, ${}, ${}, ${}, ${})",
                offset + 1, offset + 2, offset + 3, offset + 4, offset + 5
            ));
        }

        query.push_str(&params.join(", "));
        query.push_str(
            " ON CONFLICT (subject, predicate, object) DO UPDATE SET \
              confidence = GREATEST(knowledge_graph.confidence, EXCLUDED.confidence), \
              source = EXCLUDED.source"
        );

        // Execute with binds
        let mut q = sqlx::query(&query);
        for triple in chunk {
            q = q.bind(&triple.subject)
                 .bind(&triple.predicate)
                 .bind(&triple.object)
                 .bind(triple.confidence)
                 .bind(&triple.source);
        }

        let result = q.execute(pool).await?;
        added += result.rows_affected() as usize;
    }

    Ok(BulkInsertResult { added, updated, total: triples.len() })
}

// SQLite-optimized batch
let mut tx = pool.begin().await?;
sqlx::query("PRAGMA synchronous = OFF").execute(&mut *tx).await?;

for triple in &triples {
    sqlx::query("INSERT OR REPLACE INTO knowledge_graph ...")
        .bind(...)
        .execute(&mut *tx)
        .await?;
}

tx.commit().await?;

ALTER TABLE knowledge_graph
ADD COLUMN valid_from TIMESTAMPTZ DEFAULT NOW(),
ADD COLUMN valid_until TIMESTAMPTZ DEFAULT NULL,
ADD COLUMN superseded_by BIGINT REFERENCES knowledge_graph(id) DEFAULT NULL;

-- Index for temporal queries
CREATE INDEX idx_knowledge_temporal
ON knowledge_graph (subject, predicate, valid_from, valid_until)
WHERE valid_until IS NULL;

// Query with temporal filter
GET /api/knowledge?subject=clawdbot&at=2026-01-15T00:00:00Z

// Insert with validity
POST /api/knowledge
{
  "subject": "clawdbot",
  "predicate": "uses",
  "object": "gemini-2.5",
  "confidence": 0.95,
  "valid_from": "2026-02-01T00:00:00Z",
  "supersedes": {"subject": "clawdbot", "predicate": "uses", "object": "gemini-1.5"}
}

// src/analysis/community.rs

/// Louvain community detection over the knowledge graph
pub struct CommunityDetector {
    adjacency: HashMap<String, Vec<(String, f64)>>,  // entity → [(neighbor, weight)]
}

impl CommunityDetector {
    /// Build adjacency from triples
    pub fn from_triples(triples: &[StoredKnowledgeTriple]) -> Self {
        let mut adj: HashMap<String, Vec<(String, f64)>> = HashMap::new();
        for triple in triples {
            adj.entry(triple.subject.clone())
                .or_default()
                .push((triple.object.clone(), triple.confidence));
            adj.entry(triple.object.clone())
                .or_default()
                .push((triple.subject.clone(), triple.confidence));
        }
        Self { adjacency: adj }
    }

    /// Run Louvain algorithm
    pub fn detect(&self) -> Vec<Community> {
        // Phase 1: Local modularity optimization
        // Phase 2: Community aggregation
        // Iterate until convergence
        // Return communities with member lists
        todo!("Implement Louvain — or use petgraph + community crate")
    }
}

GET /api/knowledge/communities
→ {
    "communities": [
      {
        "id": 0,
        "name": "Audio Production",  // Auto-generated from dominant predicate
        "members": ["dream-weaver-engine", "cc-echelon", "cc-cinematographer", ...],
        "internal_edges": 45,
        "modularity": 0.72
      },
      ...
    ],
    "modularity_score": 0.65,
    "algorithm": "louvain"
  }

GET /api/knowledge/metrics
→ {
    "graph": {
      "node_count": 221,
      "edge_count": 3502,
      "density": 0.072,
      "avg_degree": 31.7,
      "clustering_coefficient": 0.43,
      "diameter": 7,
      "connected_components": 3
    },
    "top_pagerank": [
      {"entity": "clawdbot", "score": 0.142},
      {"entity": "mohamed-diomande", "score": 0.098},
      {"entity": "comp-core", "score": 0.076}
    ],
    "top_betweenness": [
      {"entity": "clawdbot", "score": 0.312},
      {"entity": "graph-kernel", "score": 0.187}
    ],
    "bridges": [
      {"entity": "orbit", "connects": ["infrastructure", "agent-services"]}
    ]
  }

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  GK Instance A   │     │  GK Instance B   │     │  GK Instance C   │
│  (Mohamed)       │     │  (Team Alpha)    │     │  (CI/CD Agent)   │
│                  │     │                  │     │                  │
│  Local triples   │◄───►│  Local triples   │◄───►│  Local triples   │
│  + HMAC signer   │     │  + HMAC signer   │     │  + HMAC signer   │
└────────┬─────────┘     └────────┬─────────┘     └────────┬─────────┘
         │                        │                        │
         └────────────┬───────────┘────────────────────────┘
                      │
              ┌───────▼────────┐
              │  Federation    │
              │  Relay         │
              │                │
              │  - Merge rules │
              │  - Provenance  │
              │  - Conflict    │
              │    resolution  │
              └────────────────┘

   POST /api/federation/offer
   {"triples": [...], "instance_id": "alpha", "since": "2026-02-14T00:00:00Z"}

   POST /api/federation/accept
   {"triple_ids": [1, 2, 3], "instance_id": "alpha"}

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Clawdbot   │  │  LangChain  │  │  CrewAI     │  │  Custom     │
│  Agent      │  │  Agent      │  │  Agent      │  │  Agent      │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │                │
       └────────────────┼────────────────┼────────────────┘
                        │
                ┌───────▼────────┐
                │  Graph Kernel  │
                │  Context API   │
                │                │
                │  /api/context  │  ← Universal context request
                │  /api/verify   │  ← Universal token verification
                │  /api/register │  ← Agent registration
                └────────────────┘

POST /api/context/request
{
  "agent_id": "langchain-agent-42",
  "agent_framework": "langchain",
  "conversation_id": "conv-abc-123",
  "anchor": {
    "type": "turn_id",     // or "entity", "timestamp", "content_hash"
    "value": "550e8400-e29b-41d4-a716-446655440000"
  },
  "policy": "default",     // or custom policy hash
  "max_tokens": 4096,      // Token budget for context window
  "format": "messages"     // "messages" | "text" | "triples" | "graph"
}

// Response
{
  "context": {
    "messages": [
      {"role": "user", "content": "...", "turn_id": "..."},
      {"role": "assistant", "content": "...", "turn_id": "..."}
    ],
    "total_tokens": 3847
  },
  "provenance": {
    "slice_id": "a1b2c3...",
    "admissibility_token": "d4e5f6...",
    "graph_snapshot_hash": "789abc...",
    "policy_ref": {"policy_id": "slice_policy_v1", "params_hash": "..."},
    "schema_version": "1.0.0"
  }
}

# Published as `graph-kernel` on crates.io
[package]
name = "graph-kernel"
version = "0.2.0"
# ... remove internal paths, make self-contained

# pip install graph-kernel
from graph_kernel import GraphKernelClient, Triple

gk = GraphKernelClient("http://localhost:8001")

# Add knowledge
gk.add_triple(Triple("clawdbot", "uses", "gemini-2.5", confidence=0.95))

# Query
triples = gk.query(subject="clawdbot", predicate="uses")

# Traverse
paths = gk.traverse("clawdbot", predicates=["uses"], max_hops=3)

# Verify token
is_valid = gk.verify_token(admissibility_token, slice_id, ...)

# Subscribe to changes
async for event in gk.subscribe(subjects=["clawdbot"]):
    print(f"New triple: {event.triple}")

// npm install @openclaw/graph-kernel
import { GraphKernel } from '@openclaw/graph-kernel';

const gk = new GraphKernel('http://localhost:8001');

// Add knowledge
await gk.addTriple({
  subject: 'clawdbot',
  predicate: 'uses',
  object: 'gemini-2.5',
  confidence: 0.95
});

// Query
const triples = await gk.query({ subject: 'clawdbot' });

// Traverse with visualization
const graph = await gk.traverse('clawdbot', {
  predicates: ['uses'],
  maxHops: 3,
  format: 'd3'
});

// Render in browser
gk.visualize(graph, document.getElementById('graph-container'));

Graph Kernel Protocol v1 (GKP/1)

1. CONTEXT REQUEST
   - Client sends anchor, policy reference, budget constraints
   - Server returns evidence bundle with admissibility token

2. TOKEN VERIFICATION
   - Client presents token + provenance metadata to any verifier
   - Verifier confirms token authenticity without accessing signing secret

3. POLICY REGISTRATION
   - Client registers expansion policy with hash-stable fingerprint
   - Server returns policy reference (policy_id + params_hash)

4. KNOWLEDGE ASSERTION
   - Client asserts (subject, predicate, object, confidence, source)
   - Server stores and indexes, returns assertion ID

5. FEDERATION
   - Instances exchange knowledge with provenance preservation
   - Cross-instance tokens use federated verification

{
  "prefix": {
    "gk": "https://openclaw.org/prov/graph-kernel/",
    "prov": "http://www.w3.org/ns/prov#"
  },
  "entity": {
    "gk:slice/a1b2c3": {
      "prov:type": "gk:SliceExport",
      "gk:sliceId": "a1b2c3",
      "gk:admissibilityToken": "d4e5f6",
      "gk:graphSnapshotHash": "789abc"
    }
  },
  "activity": {
    "gk:slicing/001": {
      "prov:type": "gk:ContextSlicing",
      "gk:policyId": "slice_policy_v1",
      "gk:policyParamsHash": "..."
    }
  },
  "wasGeneratedBy": {
    "gk:gen1": {
      "prov:entity": "gk:slice/a1b2c3",
      "prov:activity": "gk:slicing/001"
    }
  }
}

┌─────────────────────────────────────────────────────────┐
│                   Graph Kernel Cloud                     │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │  API Gateway  │  │  Auth (JWT)  │  │  Rate Limiter │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬────────┘ │
│         │                  │                  │          │
│  ┌──────▼──────────────────▼──────────────────▼────────┐│
│  │              GK Instance Pool                        ││
│  │                                                      ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          ││
│  │  │ Tenant A │  │ Tenant B │  │ Tenant C │  ...     ││
│  │  │ (SQLite) │  │ (SQLite) │  │ (SQLite) │          ││
│  │  └──────────┘  └──────────┘  └──────────┘          ││
│  └─────────────────────────────────────────────────────┘│
│                                                          │
│  ┌──────────────────────────────────────────────────────┐│
│  │  Shared Infrastructure: Metrics, Logging, Billing    ││
│  └──────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘

2026 Q1 (Now)
├── Evo 1.1: SQLite Backend ████████████████ (2 weeks)
├── Evo 1.2: Multi-hop Traversal ██████ (3 days)
├── Evo 1.3: Entity Normalization ████ (2 days)
├── Evo 1.4: Query Caching ██ (1 day)
└── Evo 1.5: Pool Optimization █ (1 hour)

2026 Q2
├── Evo 2.2: Graph Visualization ████ (2 days)
├── Evo 2.3: Batch Ingest ████ (2 days)
├── Evo 2.1: WebSocket Subscriptions ██████ (3 days)
├── Evo 2.6: Structural Metrics ██████ (3 days)
├── Evo 2.4: Temporal Versioning ████████████ (1 week)
└── Evo 2.5: Community Detection ████████████ (1 week)

2026 Q3
├── Evo 3.3: Graph Kernel SDK ████████████████████████████ (4 weeks)
├── Evo 3.5: W3C PROV-DM ████████████ (1 week)
└── Evo 3.2: Universal Context API ████████████████████████████████████████ (6-8 weeks)

2026 Q4
├── Evo 3.1: Federation ████████████████████████████ (3-4 weeks)
├── Evo 3.4: Protocol Spec ████████████████████████████████ (4-6 weeks)
└── Evo 3.6: Cloud (begins) ████████████████████████████████████████████████ (ongoing)