Knowledge Graph

The knowledge graph connects pieces of knowledge in Contox through typed, directional links between schema keys. These links express relationships like "depends on", "see also", and "related to", enabling the system to surface connected knowledge and help users navigate the brain.

Link Model

Each link in the knowledge graph has the following structure:

Link Types

The knowledge graph supports four types of directional links:

see-also

Indicates that two areas of knowledge are related and understanding one benefits from awareness of the other. This is the most common and loosest relationship.

Example: root/api --see-also--> root/backend/auth "The API layer is closely related to the backend auth system."

depends-on

Indicates a hard dependency -- one area of the project relies on another to function correctly. Changes in the target may require changes in the source.

Example: root/api --depends-on--> root/stack/database "The API endpoints depend on the database layer for data access."

child-of

Expresses a hierarchical parent-child relationship. Used when one schema key is a logical subset of another.

Example: root/contracts/auth --child-of--> root/contracts "Auth contracts are a subset of the contracts domain."

related

A general-purpose relationship for knowledge that is connected but does not fit the other categories. Useful for cross-cutting concerns.

Example: root/patterns --related--> root/conventions "Design patterns inform coding conventions."

Confidence Scoring

Links can optionally include a confidence score (0.0--1.0) that indicates how strong or certain the relationship is:

Links without a confidence score (null) are treated as fully confident.

Static vs. Runtime Links

The knowledge graph combines two sources of links:

Static Links (Brain Schema)

Static links are declared in the brain schema definition -- a hierarchical tree of schema keys with pre-defined relationships. These links represent the known, stable structure of a typical project:

// Example from brain-schema-static.ts
{
  schemaKey: 'root/api',
  links: [
    { toSchemaKey: 'root/backend/auth', linkType: 'see-also' },
    { toSchemaKey: 'root/stack/database', linkType: 'depends-on' },
  ],
  children: [
    { schemaKey: 'root/api/auth' },
    { schemaKey: 'root/api/core' },
    { schemaKey: 'root/api/integrations' },
  ],
}

Static links are materialized when the brain schema is loaded. They do not change unless the schema itself is updated.

The current brain schema includes these static link declarations:

Runtime Links (API-Created)

Runtime links are created dynamically through the API or MCP tools. They capture project-specific relationships discovered during development:

// Creating a runtime link via the MCP tool
contox_add_link({
  from: 'root/frontend/hooks',
  to: 'root/backend/api',
  linkType: 'depends-on',
  reason: 'Custom hooks call backend API endpoints',
  confidence: 0.85,
});

Runtime links are stored in the database and persist across sessions. They can be created by:

• Users through the dashboard's link management UI
• MCP tools via contox_add_link
• The Hygiene Agent during automated memory cleanup

Querying the Graph

Links can be queried in two directions:

• Outgoing -- All links originating from a given schema key
• Incoming -- All links pointing to a given schema key
• Both -- Combined view of all connections

The MCP tool contox_get_links and the contox_explain_schemakey tool both expose link data:

// Get all links for a schema key
contox_get_links({
  schemaKey: 'root/api',
  direction: 'both',
});

Use Cases

The knowledge graph powers several features:

Related Content Suggestions

When viewing a context or schema key in the dashboard, the knowledge graph surfaces related areas of knowledge. This helps users discover connections they might not have been aware of.

Context Pack Assembly

The contox_context_pack tool uses the knowledge graph to assemble focused context packs for specific tasks. When building a context pack for work on root/frontend/hooks, the graph reveals that this area depends on root/backend/api, so relevant API documentation is included.

Brain Schema Navigation

The dashboard's brain tree view uses the knowledge graph to show how different areas of the project are connected, making it easier to understand the overall architecture at a glance.

Hygiene Agent

The memory hygiene agent uses link data when analyzing items for cleanup -- for example, it can detect when two items in linked schema keys contain contradictory information and flag them for review.