Documentation

krabnet is a real-time graph context engine. It maintains materialized views over your graph data so that reads are always instant, regardless of how frequently your graph changes.

You interact with krabnet through two interfaces: a gRPC server for backend services, or an MCP server for AI agent integration.

Installation

krabnet requires Rust. Install via Cargo:

cargo install krabnet

This installs two binaries:

• krabnet-server — gRPC server for backend integration
• krabnet-mcp — MCP server for AI agent integration

Core Concepts

Graph Events

krabnet ingests your graph as a stream of mutation events. Five event types are supported:

• NodeAdded — a node is created with a type
• NodeRemoved — a node is deleted
• EdgeAdded — a directed edge is created between two nodes
• EdgeRemoved — an edge is deleted
• PropertyChanged — a property on a node is updated

Frames

A frame is a declared query over your graph — anchored at a specific node, with a pattern of hops to follow. Once registered, krabnet continuously maintains the frame's results as your graph changes. Querying a frame returns the current answer immediately, without traversal.

Hop Patterns

Frames are defined by a sequence of hops. Each hop specifies:

• Direction — outgoing, incoming, or any
• Edge type (optional) — filter by edge type
• Target type (optional) — filter by target node type

Multi-hop patterns let you express neighborhood queries, path queries, and structural patterns over your graph.

gRPC Server

Start the gRPC server:

krabnet-server

The server listens on [::1]:50051 by default. It provides bidirectional streaming, crash recovery via write-ahead logging, and automatic state replay on restart.

Quick Start

Connect with any gRPC client. Here's an example using grpcurl:

1. Ingest some data

# Add nodes
grpcurl -plaintext -d '{
  "node_added": {"node_id": 1, "type_id": 100}
}' [::1]:50051 krabnet.KrabnetService/IngestEvent

grpcurl -plaintext -d '{
  "node_added": {"node_id": 2, "type_id": 200}
}' [::1]:50051 krabnet.KrabnetService/IngestEvent

# Add an edge between them
grpcurl -plaintext -d '{
  "edge_added": {"edge_id": 1, "source": 1, "target": 2, "type_id": 10}
}' [::1]:50051 krabnet.KrabnetService/IngestEvent

2. Register a frame

# Register a 1-hop outgoing frame anchored at node 1
grpcurl -plaintext -d '{
  "anchor_node_id": 1,
  "pattern": [{"direction": "DIRECTION_OUTGOING"}],
  "epoch": 0
}' [::1]:50051 krabnet.KrabnetService/RegisterFrame

3. Query the frame

grpcurl -plaintext -d '{"frame_id": 0}' \
  [::1]:50051 krabnet.KrabnetService/QueryFrame

4. Subscribe to updates

# Stream real-time updates as the graph changes
grpcurl -plaintext -d '{"frame_id": 0}' \
  [::1]:50051 krabnet.KrabnetService/SubscribeFrame

MCP Server

The MCP server lets AI agents interact with krabnet directly as a tool. It communicates over stdio using the Model Context Protocol.

Configuration

Add krabnet to your MCP client configuration. For Claude Desktop:

{
  "mcpServers": {
    "krabnet": {
      "command": "krabnet-mcp"
    }
  }
}

For Claude Code, add to your settings:

{
  "mcpServers": {
    "krabnet": {
      "command": "krabnet-mcp",
      "type": "stdio"
    }
  }
}

Available Tools

Once connected, the agent has access to five tools:

• krabnet_ingest — ingest graph mutation events
• krabnet_register_frame — register a maintained frame
• krabnet_query_frame — query a frame's current results
• krabnet_register_template — register an automatic pattern template
• krabnet_stats — get engine statistics

Example: Building a Graph

An AI agent can build and query a graph through natural tool calls:

# Agent calls krabnet_ingest to add entities
krabnet_ingest({
  "event_type": "NodeAdded",
  "node_id": 1,
  "type_id": 100
})

krabnet_ingest({
  "event_type": "EdgeAdded",
  "edge_id": 1,
  "source": 1,
  "target": 2,
  "type_id": 10
})

# Agent registers a frame for ongoing context
krabnet_register_frame({
  "anchor_node_id": 1,
  "pattern": [{"direction": "Outgoing"}],
  "epoch": 0
})

# Agent queries the frame — instant results
krabnet_query_frame({"frame_id": 0})

gRPC API Reference

The KrabnetService exposes the following RPCs:

MCP Tools Reference

Configuration

gRPC Server

MCP Server

Both servers persist state via write-ahead logging and automatically replay on restart for crash recovery.