Knowledge Graph Model

Graph Storage

Knowledge Tree uses Apache AGE on top of PostgreSQL to provide a property graph database. Resources are stored as labeled nodes and relationships as typed directed edges. You query the graph usingCypher syntax.

The graph is named knowledge_tree by default (configurable). All nodes have a type label (e.g., aws.ec2.instance) and a set of properties.

Nodes

Each node represents a single infrastructure resource with properties:

(:aws.ec2.instance {
  id: "i-abc123",
  name: "prod-api-server",
  provider: "aws",
  region: "us-east-1",
  prop_state: "running",
  prop_instance_type: "m5.large",
  prop_private_ip: "10.0.1.42"
})

Edges

Edges are typed and directed. They represent real infrastructure relationships:

(:k8s.service)-[:EXPOSES]->(:k8s.pod)
(:aws.rds.instance)-[:DEPENDS_ON]->(:aws.vpc)
(:aws.elb.load_balancer)-[:ROUTES_TO]->(:k8s.service)
(:aws.vpc)-[:OWNS]->(:aws.subnet)

Cypher Queries

Query the graph via the API:

# Find all EC2 instances in us-east-1
curl -X POST http://localhost:8080/api/v1/graph/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n {type: \"aws.ec2.instance\"}) WHERE n.region = \"us-east-1\" RETURN n.name, n.prop_state"}'

# Find all dependencies of a specific resource
curl -X POST http://localhost:8080/api/v1/graph/query \
  -d '{"query": "MATCH (n {id: \"db-primary\"})-[r:DEPENDS_ON]->(m) RETURN m.name, type(r)"}'

Vector Embeddings

The pgvector extension stores vector embeddings for each resource and its generated documentation. This enables semantic search: find resources by meaning, not just exact match.

Embeddings are generated by the enricher service and stored with metadata (content type, title, excerpt). The MCP server and chat interface use vector search to find relevant context for AI queries.

Graph Operations