@harness-engineering/graph
Unified Knowledge Graph for AI-powered context assembly. Ingests code, git history, knowledge artifacts, and external services into an in-memory graph, then queries and searches it to build precisely-scoped context for AI agents.
Architecture
┌──────────────────────────────────────────────────┐
│ Ingest Layer │
│ CodeIngestor · GitIngestor · KnowledgeIngestor │
│ TopologicalLinker · Connectors (Jira/Slack/...) │
└──────────────────┬───────────────────────────────┘
▼
┌──────────────────────────────────────────────────┐
│ Store (in-memory) │
│ GraphStore · VectorStore │
│ Serializer (save/load) │
└──────────┬──────────────────┬────────────────────┘
▼ ▼
┌────────────────┐ ┌─────────────────┐
│ Query Layer │ │ Search Layer │
│ ContextQL │ │ FusionLayer │
│ Projection │ │ (keyword + │
│ │ │ semantic) │
└───────┬────────┘ └────────┬────────┘
└────────┬───────────┘
▼
┌──────────────────────────────────────────────────┐
│ Context Assembly │
│ Assembler · Budget · Phase-aware filtering │
└──────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────┐
│ Adapters │
│ GraphEntropyAdapter · GraphConstraintAdapter │
│ GraphFeedbackAdapter │
└──────────────────────────────────────────────────┘
Quick Start
import {
GraphStore,
CodeIngestor,
ContextQL,
FusionLayer,
VectorStore,
} from '@harness-engineering/graph';
// 1. Create the store
const store = new GraphStore();
// 2. Ingest code
const ingestor = new CodeIngestor(store);
const result = await ingestor.ingest('/path/to/project');
console.log(`Added ${result.nodesAdded} nodes, ${result.edgesAdded} edges`);
// 3. Query the graph with ContextQL
const cql = new ContextQL(store);
const context = cql.execute({
rootNodeIds: ['file:src/index.ts'],
maxDepth: 3,
includeTypes: ['file', 'function', 'class'],
});
// 4. Search with FusionLayer (keyword + optional semantic)
const vectorStore = new VectorStore(1536);
const fusion = new FusionLayer(store, vectorStore);
const results = fusion.search('authentication handler', 10);
Key Classes
| Class | Description |
|---|---|
GraphStore | In-memory graph over plain Maps with indexed from/to/type edge lookups |
VectorStore | In-memory brute-force cosine similarity vector store |
ContextQL | BFS-based graph traversal engine with type filtering and observability pruning |
project (function) | Projection utility to select specific fields from query results |
CodeIngestor | Parses TypeScript/JavaScript files into file, class, function, and method nodes |
GitIngestor | Extracts commit history and co-change relationships from git |
KnowledgeIngestor | Ingests ADRs, learnings, and markdown knowledge artifacts |
TopologicalLinker | Creates structural edges (imports, calls, references) between code nodes |
FusionLayer | Hybrid search combining keyword matching and semantic similarity scores |
Assembler | Phase-aware context assembly with token budgets and coverage reports |
SyncManager | Orchestrates connector syncs with incremental update tracking |
GraphEntropyAdapter | Detects graph drift and dead code for entropy monitoring |
GraphConstraintAdapter | Validates dependency rules and layer boundary violations |
GraphFeedbackAdapter | Computes impact analysis and harness check data from graph state |
CascadeSimulator | Probability-weighted BFS for cascading failure simulation (compute_blast_radius) |
CompositeProbabilityStrategy | Default edge probability strategy blending edge type, change frequency, and coupling |
saveGraph / loadGraph | Serializes and deserializes the graph store to/from disk |
BusinessKnowledgeIngestor | Ingests business rules, processes, concepts, terms, and metrics as graph nodes |
RequirementIngestor | Ingests requirement specifications as traceability nodes |
DesignIngestor | Ingests design tokens and aesthetic intents |
DesignConstraintAdapter | Validates design constraints against graph state |
GraphComplexityAdapter | Computes complexity metrics from graph structure |
GraphCouplingAdapter | Measures coupling between modules via graph edges |
GraphAnomalyAdapter | Detects structural anomalies in the graph |
TaskIndependenceAnalyzer | Determines if tasks can be executed in parallel |
ConflictPredictor | Predicts merge conflicts from co-change patterns |
askGraph | Natural language query interface for the knowledge graph |
IntentClassifier | Classifies natural language query intent for NLQ |
EntityExtractor | Extracts entity references from natural language queries |
EntityResolver | Resolves extracted entities to graph nodes |
ResponseFormatter | Formats NLQ results for display |
queryTraceability | Queries requirement-to-test traceability chains |
PackedSummaryCache | Caches packed context summaries as graph nodes |
groupNodesByImpact | Groups nodes by cascading impact for blast radius analysis |
Node Types
37 node types organized by category:
| Category | Types |
|---|---|
| Code | repository, module, file, class, interface, function, method, variable |
| Knowledge | adr, decision, learning, failure, issue, document, skill, conversation |
| VCS | commit, build, test_result, execution_outcome |
| Observability | span, metric, log |
| Structural | layer, pattern, constraint, violation |
| Design | design_token, aesthetic_intent, design_constraint |
| Traceability | requirement |
| Business Knowledge | business_rule, business_process, business_concept, business_term, business_metric |
| Cache | packed_summary |
Observability types (span, metric, log) are pruned by default in ContextQL queries to reduce noise.
Edge Types
29 edge types organized by category:
| Category | Types |
|---|---|
| Code | contains, imports, calls, implements, inherits, references |
| Knowledge | applies_to, caused_by, resolved_by, documents, violates, specifies, decided |
| VCS | co_changes_with, triggered_by, failed_in, outcome_of |
| Execution | executed_by, measured_by |
| Design | uses_token, declares_intent, violates_design, platform_binding |
| Traceability | requires, verified_by, tested_by |
| Business Knowledge | governs, measures |
| Cache | caches |
Edges carry an optional confidence score (0-1) used by the FusionLayer for ranking.
Connectors
External service connectors implement the GraphConnector interface and sync data into the graph as knowledge nodes.
| Connector | Source | Description |
|---|---|---|
JiraConnector | Jira Cloud | Ingests issues as issue nodes with status, priority, and assignee metadata |
SlackConnector | Slack | Ingests channel messages as conversation nodes linked to referenced code |
ConfluenceConnector | Confluence | Ingests pages as document nodes with body content |
CIConnector | GitHub Actions | Ingests workflow runs as build nodes with status and conclusion |
All connectors accept an optional HttpClient for custom fetch implementations and testability.
Use SyncManager to orchestrate multiple connectors with incremental sync tracking:
import { SyncManager, JiraConnector } from '@harness-engineering/graph';
const sync = new SyncManager(store);
sync.register(new JiraConnector());
await sync.syncAll({
baseUrl: 'https://your-org.atlassian.net',
auth: 'Bearer <token>',
project: 'PROJ',
});
Serialization
import { saveGraph, loadGraph, GraphStore } from '@harness-engineering/graph';
// Persist to disk
await saveGraph(store, '/path/to/graph.json');
// Restore from disk
const restored = new GraphStore();
await loadGraph(restored, '/path/to/graph.json');
Dependencies
| Package | Purpose |
|---|---|
minimatch | Glob pattern matching for file filtering during ingestion |
zod | Runtime schema validation for graph nodes and edges |
tree-sitter (optional) | Enhanced TypeScript AST parsing for code ingestion |
tree-sitter-typescript (optional) | TypeScript grammar for tree-sitter |
License
See the root LICENSE file.