Knowledge Graphs

Connect decisions, code, and documentation in a queryable graph. Understand how your project's knowledge is interconnected.

Graph tiers by plan

Pro: Graph-Lite

Module-level import graph only. Supports dependencies and 1-hop impact for files/modules. No call/dataflow/type layers.

Elite/Team: Full Graph

Full multi-layer graph (module + call + dataflow + type) with deeper impact analysis and graph ingestion via graph(action="ingest").

Search + graph workflow

Use search to identify the best target, then graph queries to answer dependency and impact questions. This keeps prompts small and avoids unnecessary local scans.

search(mode="hybrid", query="token refresh flow", limit=3)
graph(action="impact", target={ "type": "module", "path": "src/auth.rs" }, max_depth=2)

What are Knowledge Graphs?

Knowledge graphs represent information as nodes (entities) connected by edges (relationships). In ContextStream, knowledge graphs help you:

Track Dependencies

See how decisions affect other parts of your system

Connect Context

Link related memories, code, and documentation

Trace Impact

Understand what changes when you modify something

Discover Insights

Find non-obvious connections in your knowledge base

Creating Knowledge Nodes

Create a node representing a piece of knowledge:

curl -X POST https://api.contextstream.io/api/v1/memory/nodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your-workspace-id",
    "category": "decision",
    "summary": "Use PostgreSQL for primary database",
    "details": "Chose PostgreSQL over MySQL for better JSON support and advanced features.",
    "tags": ["database", "architecture"],
    "confidence": 0.95
  }'

Connecting Nodes

Create relationships between nodes:

curl -X POST https://api.contextstream.io/api/v1/graph/knowledge/edges \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "workspace_id": "your-workspace-id",
    "source_node_id": "node-postgres-decision",
    "target_node_id": "node-schema-design",
    "relation_type": "influences",
    "weight": 0.9,
    "context": "Database choice affects schema capabilities"
  }'

Common relation types:

influencesdepends_onsupersedesrelated_toimplements

Querying the Graph

Find related knowledge nodes:

curl -X POST https://api.contextstream.io/api/v1/graph/knowledge/related \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "workspace_id": "your-workspace-id",
    "node_id": "node-postgres-decision",
    "max_depth": 2,
    "relation_types": ["influences", "depends_on"]
  }'

Get all decisions in a workspace:

curl https://api.contextstream.io/api/v1/graph/knowledge/decisions?workspace_id=your-workspace-id \
  -H "Authorization: Bearer YOUR_API_KEY"

Code Graph Analysis

Code graph endpoints analyze indexed code entities (files, functions, types, variables). They are separate from knowledge graph endpoints; memory node types like decision or fact are not valid here. Use /api/v1/graph/knowledge/path with UUID node IDs (no type) for knowledge graph queries.

Pro Graph-Lite supports module-level targets only (files/paths) and 1-hop impact. Elite/Team unlocks function/type/variable layers and deeper impact analysis.

Accepted code entity types (v0.4.x consolidated graph tool):

graph(action="dependencies") target.type: module (file/path), function (method), type (struct/enum/trait/class), variable (data/const/constant)

graph(action="call_path") source.type/target.type: function (method) only (type optional; ids are function IDs)

graph(action="impact") target.type: module (file/path), function (method), type (struct/enum/trait/class), variable (data/const/constant)

Type payload examples (code graph only):

module/file/path: {"target":{"type":"module","path":"src/auth.rs"}}function/method: {"target":{"type":"function","id":"fn_login"}}type/struct/enum/trait/class: {"target":{"type":"type","id":"User"}}variable/data/const/constant: {"target":{"type":"variable","id":"API_KEY"}}

Dependencies example:

curl -X POST https://api.contextstream.io/api/v1/graph/dependencies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": { "type": "module", "path": "src/auth.rs" },
    "max_depth": 3
  }'

Call path example:

curl -X POST https://api.contextstream.io/api/v1/graph/call-paths \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "source": { "id": "fn_login", "type": "function" },
    "target": { "id": "fn_verify_token", "type": "function" },
    "max_depth": 5
  }'

Impact analysis example:

curl -X POST https://api.contextstream.io/api/v1/graph/impact-analysis \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "change_type": "modify_signature",
    "target": { "id": "User", "type": "type" }
  }'

Graph ingestion (Elite/Team full graph):

curl -X POST https://api.contextstream.io/api/v1/graph/ingest/PROJECT_UUID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "wait": true }'

Knowledge graph path example (memory node UUIDs):

curl -X POST https://api.contextstream.io/api/v1/graph/knowledge/path \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "source": { "id": "7e3b0b5e-2c76-4f49-8e5a-2f2bfe7eb7f3" },
    "target": { "id": "5c3a6b1a-0f89-4ddc-bb29-0a2a9a3c2c4e" },
    "max_depth": 5
  }'

Next Steps

Semantic Search

Find the best targets first

Context Pack

Distilled context for AI

Memory Events

Store context as memories

API Reference

Full graph endpoint docs