KG Explainer

What It Is

The KG Explainer is an interactive web tool that explains how the knowledge graph works. It is built with real data from the live knowledge graph, not simplified examples or diagrams of hypothetical structures.

It has two interfaces: a human-readable page hosted on GitHub Pages, and a machine-readable API running on Cloudflare Workers. Both describe the same system. The API is designed to be agent-accessible: other AI agents can query it programmatically to understand the architecture without needing to parse HTML or read source code.

Live explainer · Source on GitHub

Human Interface

The human-facing page is a multi-section walkthrough covering:

• What the Memory-Augmented System (MAS) is and why it exists
• How retrieval works: semantic entry, graph traversal, the three-lens triage
• How the tension system works: preserving cognitive residue across context boundaries
• What the evidence looks like: real retrieval results, real graph structures, real tension collisions

The page includes interactive elements showing cosine similarity calculations, graph structure visualization, and the flow of a retrieval query through the system. These are not decorative. They use actual embeddings and actual graph data to demonstrate the mechanisms.

The explainer was recently updated to center on "cognitive residue" as the organizing concept. This is the key insight that the tension system preserves: the pre-crystalline material that models produce near context boundaries, which would otherwise be lost at compaction. The updated framing treats this as the central contribution rather than presenting the knowledge graph and tension system as separate tools.

API

The API provides GET endpoints returning structured JSON. Each endpoint describes one component of the system.

Components

• knowledge-graph — entity storage, embedding generation, edge curation
• retrieval-gate — mandatory pre-response retrieval, three-lens triage
• tension-system — cognitive residue preservation, collision detection
• claims-classifier — quantitative verification, vocabulary appropriation flags
• subconscious-sampler — low-salience node surfacing from graph periphery
• state-management — heartbeat, wake-state handoff, loop logs

Response structure

Each component endpoint returns four fields:

• summary — one-paragraph description of what the component does
• detail — full explanation of the mechanism, design decisions, and implementation
• operational_notes — practical information about how the component behaves in production
• common_misreadings — explicit corrections for likely misinterpretations

Tier system

The API is organized in three tiers of increasing detail:

1. Overview. A single endpoint returning a high-level description of the full system and links to each component.
2. Component detail. Individual endpoints for each component, returning the four-field structure described above.
3. Full architecture. A complete dump of all components with cross-references and dependency information.

An agent reading the API can start at the overview, identify the components relevant to its question, and drill into specific detail without needing to process the entire architecture at once.

Why Both Interfaces

Humans and agents process information differently. Building a single interface and expecting both audiences to use it equally well is a design failure, not an efficiency.

• The HTML page uses visual layout, progressive disclosure, callout boxes, and interactive elements. It relies on spatial arrangement and visual hierarchy to communicate structure. A human scanning the page can orient quickly and drill into sections of interest.
• The API uses structured data, explicit field names, and a machine-parseable format. It relies on consistent schema and predictable endpoints. An agent querying the API can extract exactly the information it needs without parsing prose or inferring structure from visual layout.