Knowledge Graph Store

The knowledge graph store (PgGraphStore) is a PostgreSQL + pgvector substrate that persists architectural entities as a labeled property graph. Nodes represent code concepts; edges carry typed relationships. The store drives context injection, hybrid search, and the feedback learning loop.

Architecture

Tables

graph_nodes

Nodes represent discrete architectural entities. Key columns:

graph_edges

Edges are typed relationships between nodes. Primary key is (source_id, target_id, relationship_name).

graph_triplet_embeddings

Dedicated pgvector table for triplet-level semantic search. Stores the embedding of "sourceName → relationshipName → targetName". Migration 0057_triplet_embeddings_pgvector.sql backfills any older inline JSONB vectors.

IGraphStore API

Both PgGraphStore (production) and InMemoryGraphStore (test double) implement IGraphStore:

interface IGraphStore {
  upsertNode(node: GraphNodeInput): Promise<GraphNodeRow>
  upsertEdge(edge: GraphEdgeInput): Promise<GraphEdgeRow>
  upsertNodes(nodes: GraphNodeInput[]): Promise<GraphNodeRow[]>
  upsertEdges(edges: GraphEdgeInput[]): Promise<GraphEdgeRow[]>
  getNode(id: string): Promise<GraphNodeRow | null>
  getEdges(filter: GetEdgesFilter): Promise<GraphEdgeRow[]>

  // pgvector cosine similarity (threshold default 0.92)
  findFuzzyDuplicates(
    name: string,
    embedding: number[],
    threshold?: number,
    scope?: { orgId: string; projectId: string },
  ): Promise<FuzzyDuplicateResult[]>

  // Top-K vector search (lower distance = more relevant)
  searchByEmbedding(
    queryEmbedding: number[],
    topK: number,
    scope: { orgId: string; projectId?: string },
  ): Promise<EmbeddingSearchResult[]>

  deleteNode(id: string): Promise<void>

  // Triplet-level embeddings
  upsertTripletEmbedding(input: TripletEmbeddingInput): Promise<void>
  findFuzzyTripletDuplicates(
    embedding: number[],
    threshold: number,
    scope: { orgId: string; projectId: string },
    topK?: number,
  ): Promise<TripletSearchResult[]>

  // Extraction-cron skip-already-extracted helper
  observationIdsWithNodes(observationIds: string[]): Promise<Set<string>>
}

Tenant isolation

PgGraphStore is instantiated unscoped and then bound to a tenant via .withScope({ orgId, projectId }). Every method runs inside a scoped transaction that sets app.current_org_id (and app.current_project_id) via set_config(..., true) (transaction-local GUC). The production Neon role is BYPASSRLS, so the RLS policies on graph_* tables are inert at runtime - the explicit WHERE org_id = $1 filter in each read method is the authoritative tenant boundary. The GUC + RLS serve as belt-and-suspenders for future role changes and test fixtures that run under NOBYPASSRLS roles.

const store = new PgGraphStore(db)
const scoped = store.withScope({ orgId: 'org_...', projectId: 'proj_...' })
await scoped.upsertNode({ ... })

Per-project enablement

The graph engine is gated per project through the agent-memory control plane (project_memory_config), not by an org-wide flag. A project gets graph context, recall, and MCP graph tools only when its memory is enabled and graph is on for that project. The helper is isGraphEnabledForProject(orgId, projectId).

"Graph on" uses OR semantics: it is true when the project has an explicit project_memory_config.graph_enabled = true, or the org's plan grants the kg_enabled feature flag (plan-assignable via planDefinitions).

Every live consumer gates the same way through isGraphEnabledForProject: the MCP graph tools, context injection at session start, recall, and the extraction cron (which enumerates KG-enabled (org, project) pairs).

The per-project toggle lives in the tenant Memory config (the project's performance/settings page) and is written through PUT /api/projects/[projectId]/memory-config.

Per-work-type recall - which agent work types receive graph-augmented context - is no longer static code. It is an operator-configured recall matrix (with per-org overrides) managed in the memory admin console (/admin/memory, operator-only).

Migrations

Related pages

• Extraction Pipeline - how observations become nodes
• Entity Resolution - UUID5 dedup + fuzzy merge
• Hybrid Search - vector + k-hop traversal
• Context Injection - triplets into agent prompts
• Graph Feedback - EMA weight updates
• MCP Tools - agent-callable graph tools