GraphRAG

GraphRAG is entity-aware retrieval that goes beyond flat text search. Instead of treating memory as a bag of chunks, GraphRAG extracts entities (people, projects, systems, concepts) and relationships between them, building a traversable knowledge graph that agents use to answer questions about structure, dependency, and connection.

Why GraphRAG?

Vector search finds things that sound similar. Keyword search finds things that contain the same words. Neither is good at answering questions about how things relate to each other.

Query type	Vector	Keyword	GraphRAG
"What is the auth system?"	✅ Good	✅ Good	✅ Good
"Who worked on auth?"	⚠️ Partial	⚠️ Partial	✅ Walks person→project edges
"What depends on the payments service?"	❌ Weak	❌ Weak	✅ Traverses dependency graph
"Show everything related to the migration"	⚠️ Top-K only	⚠️ Keyword match only	✅ Multi-hop traversal

How It Works

1. Entity Extraction

When memory files are indexed, an extraction pass identifies entities and their types (person, project, system, concept, location) plus relationships between them. Extraction can use LLM-based parsing or rule-based patterns depending on configuration.

2. Graph Construction

Extracted entities and relationships are stored as nodes and edges in a local graph store. Each node carries attributes (type, description, first-seen date, source files). Each edge carries a relationship type (works-on, depends-on, related-to, authored-by) and source attribution.

3. Graph-Augmented Retrieval

When the agent queries the knowledge system, GraphRAG enriches the retrieval pipeline:

Entity resolution — map query terms to known graph entities
Neighborhood expansion — retrieve connected entities (1-2 hops)
Subgraph extraction — pull the relevant subgraph as structured context
Context injection — graph context is merged with vector/keyword results before delivery to the agent

Integration with Hybrid Search

GraphRAG does not replace vector or keyword search — it augments them. The retrieval pipeline runs all three in parallel:

Query
  ├── Vector Search → semantic matches
  ├── BM25 Search → keyword matches
  └── Graph Traversal → structural matches
        │
        ▼
  Merge + Rank (weighted score + diversity)
        │
        ▼
  Agent Context Window

The graph traversal results are scored and merged into the same ranking pipeline as vector and keyword results. This ensures that structurally relevant information surfaces alongside textually relevant information.

Graph Store

The knowledge graph is stored locally — no external graph database required. The default implementation uses SQLite with adjacency list tables, keeping the same single-file, offline-first philosophy as the rest of the knowledge system.

Like vector indexes, the graph store is derived from Markdown source files. It can be rebuilt at any time. Deleting the graph store and re-indexing produces the same graph (deterministic extraction assumed).

Entity Types

Type	Examples	Common relationships
Person	Team members, external contacts	works-on, authored, reviewed
Project	Repositories, services, features	depends-on, part-of, deployed-to
System	Infrastructure, databases, APIs	hosts, connects-to, authenticates-via
Concept	Patterns, decisions, principles	applies-to, supersedes, related-to
Location	Environments, regions, clusters	runs-in, replicated-to

When to Use GraphRAG

Your agent fleet works across multiple interconnected projects
You need "show me everything related to X" queries
Dependency and ownership questions are common
The memory corpus is large enough that flat retrieval misses structural connections

For small workspaces with a single project, hybrid search (vector + BM25) is usually sufficient. GraphRAG adds value as the knowledge base grows and inter-entity relationships become important.