@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 (LokiJS)                     │
│         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();
const fusion = new FusionLayer(store, vectorStore);
const results = fusion.search('authentication handler', { topK: 10 });

Key Classes

Class	Description
`GraphStore`	In-memory graph backed by LokiJS with indexed node/edge collections
`VectorStore`	Optional vector index for semantic similarity search (hnswlib)
`ContextQL`	BFS-based graph traversal engine with type filtering and observability pruning
`project`	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

Node Types

28 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`
Observability	`span`, `metric`, `log`
Structural	`layer`, `pattern`, `constraint`, `violation`
Design	`design_token`, `aesthetic_intent`, `design_constraint`
Traceability	`requirement`

Observability types (span, metric, log) are pruned by default in ContextQL queries to reduce noise.

Edge Types

24 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`
Execution	`executed_by`, `measured_by`
Design	`uses_token`, `declares_intent`, `violates_design`, `platform_binding`
Traceability	`requires`, `verified_by`, `tested_by`

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
`lokijs`	In-memory document database backing the graph store
`minimatch`	Glob pattern matching for file filtering during ingestion
`zod`	Runtime schema validation for graph nodes and edges

Optional peer dependencies:

Package	Purpose
`hnswlib-node`	HNSW vector index for semantic search in VectorStore
`tree-sitter`	AST-based code parsing (future upgrade path for CodeIngestor)
`tree-sitter-typescript`	TypeScript grammar for tree-sitter

License

See the root LICENSE file.