Knowledge Graph

The Knowledge Graph stores structured facts as directed edges (source → relation → target) with vector embeddings on each fact. Unlike flat Memory entries, the graph captures relationships — who knows whom, which company uses which tool, which event caused which outcome — and lets agents traverse and reason over those connections.

Core concepts

kg_edges

Each fact is a row in kg_edges: a source entity, a relation, a target entity, an optional context, a timestamp, and a fact_embedding vector(1536) indexed with HNSW. Facts are team-scoped and soft-deleted.

Personalized PageRank search

Graph search uses PPR (α=0.85) over a 3-hop subgraph centred on the query entity, combined with cosine similarity on fact embeddings. This returns contextually relevant facts that naive vector search would miss.

Two-pass gleaning

ExtractKnowledgeEdgesAction runs a second LLM pass to catch facts missed in the first pass, then deduplicates by source + relation + target before storing. This significantly improves recall on dense source documents.

Louvain communities

A nightly job runs Louvain community detection (pure PHP) over the graph, groups related entities into topics, generates LLM summaries per community, and indexes those summaries with pgvector HNSW for fast community-level search.

Entity merging

DetectDuplicateEntitiesAction finds semantically equivalent entities (e.g. "OpenAI" vs "Open AI Inc.") and proposes merges. MergeEntitiesAction re-points all edges to the canonical entity. Runs daily at 04:30.

Context injection

The InjectKnowledgeGraphContext middleware sits in the agent execution pipeline. Before each LLM call it queries the graph for facts relevant to the current task and prepends them to the system prompt.

MCP tools

Tool	Description
kg_search	Semantic + PPR graph search. Returns ranked facts with source entities.
kg_entity_facts	Retrieve all facts for a specific entity (outgoing and incoming edges).
kg_add_fact	Store a new fact edge (source, relation, target, context, timestamp).
kg_community_search	Search across Louvain community summaries for topic-level context.
kg_suggest_merges	List pending duplicate-entity merge proposals.
kg_merge_entities	Apply an entity merge — re-points all edges to the canonical entity.

The Knowledge Graph is distinct from Memory. Memory stores unstructured text snippets (episodic, semantic). The Knowledge Graph stores typed, directed facts that support graph traversal and relationship reasoning. Use both together for the richest agent context.

Scheduled maintenance

Job	Schedule	Purpose
BuildKgCommunitiesAction	Daily 02:45	Louvain community detection + LLM summaries + HNSW index rebuild.
DetectDuplicateEntitiesAction	Daily 04:30	Find and propose entity merges for review.

Related concepts

Memory & Knowledge — episodic and semantic memory; use alongside the graph.
Agents — agents with KG context automatically receive relevant facts at inference time.
Signals — inbound signals can trigger KG fact extraction via skill pipelines.