Knowledge Graph (Brain)

Introduction to the Knowledge Graph

The Knowledge Graph, often referred to as the Brain within the Hopsule ecosystem, is a sophisticated visualization engine designed to map the intricate web of your organization’s judgment. Unlike traditional list-based views, the Knowledge Graph provides a multi-dimensional perspective on how Decisions, Memories, and Context Packs interact. It serves as the visual manifestation of your team’s collective memory, allowing engineering leaders and developers to see not just what was decided, but how those decisions are anchored in history and logic.

In a rapidly scaling engineering organization, decisions are rarely isolated events. They are interconnected responses to technical challenges, market shifts, and previous commitments. The Knowledge Graph surfaces these hidden connections, making the "blast radius" of a new decision immediately apparent. By transforming abstract governance into a tangible map, Hopsule ensures that enforcement is experienced as remembrance rather than control. This visibility is critical for maintaining architectural integrity across distributed teams and long-lived projects.

Important: The Knowledge Graph is not a static diagram; it is a real-time, interactive interface that reflects the current state of your organization's decision landscape. As new memories are appended or decisions are accepted via the Hopsule Dashboard or Hopsule CLI, the graph updates dynamically to preserve the most accurate representation of your context.

Accessing and Navigating the Brain

To access the Knowledge Graph, navigate to the Brain icon in the primary sidebar of the Hopsule Dashboard. Upon loading, the system renders a force-directed layout of your current project’s entities. This layout is designed to group related items naturally based on their shared tags and explicit links, providing an intuitive starting point for exploration. You can toggle between different projects or view a global graph that spans your entire organization, provided you have the necessary permissions.

Navigation within the graph is designed to be fluid and responsive, supporting standard mouse and keyboard interactions. You can pan across the canvas by clicking and dragging, and zoom in to inspect specific clusters using the scroll wheel or the dedicated zoom controls in the interface. For complex graphs with hundreds of nodes, the Recenter button allows you to quickly return to a global view of your decision landscape. The graph also supports a "Focus Mode," where selecting a single node temporarily dims unrelated entities, allowing you to trace the specific lineage of a single Decision or Memory without visual noise.

Tip: Use the Spacebar to toggle between the selection tool and the pan tool for faster navigation during high-level architectural reviews.

Understanding Node Types

The Knowledge Graph utilizes a distinct visual language to categorize different entities. Each node represents a specific piece of organizational context, and its appearance provides immediate information about its type and status. Understanding these visual cues is essential for interpreting the health and structure of your team's memory system.

• Decisions: These are the primary nodes in the graph, represented by circular icons. Their color indicates their current lifecycle state:

  • Draft (Gray): Decisions currently being formulated and not yet enforceable.

  • Pending (Yellow): Decisions awaiting review or consensus from the team.

  • Accepted (Green): Active, enforceable constraints that Hopsule for VS Code will monitor.

  • Deprecated (Red): Historical decisions that are no longer active but remain for traceability.

• Memories: Represented by smaller, square nodes, these are append-only entries that provide the "Why" behind a decision. They are always linked to at least one decision or context pack, acting as the evidentiary support for your organization's judgment.

• Context Packs (Capsules): These are represented by larger, hexagonal nodes. They act as containers or "gravity wells" in the graph, pulling together related decisions and memories into a portable bundle.

• Tags: Represented as floating labels or colored halos around nodes, tags allow you to see thematic overlaps (e.g., #security, #performance, #infrastructure) across different branches of the graph.

Edge Types and Relationship Mapping

The connections between nodes, known as edges, define the structural integrity of your memory system. In Hopsule, edges are not merely decorative; they represent explicit relationships and dependencies that inform how Hopper provides suggestions and how the Hopsule API serves context to external tools. There are three primary types of relationships visible in the Knowledge Graph:

The first is the Decision-to-Decision Link. This indicates a direct dependency or a historical succession. For example, if a new decision regarding database indexing supersedes a previous one, an edge will connect the two, often leading from the Deprecated node to the Accepted node. This creates a clear audit trail of how your engineering standards have evolved over time. Seeing these links helps developers understand the "precedent" for current constraints.

The second type is the Memory-to-Decision Link. This is perhaps the most critical relationship in Hopsule, as it connects an enforceable rule to its underlying reasoning. A decision without a memory is a mandate without a reason; the Knowledge Graph highlights these connections to ensure that every constraint is backed by organizational history. In the graph, these appear as solid lines connecting square memory nodes to circular decision nodes, forming a "provenance cluster."

The third type is the Membership Link, which connects decisions and memories to a Context Pack. When a Capsule is active, all its constituent parts are visually grouped around the capsule node. This allows you to see exactly what context is being exported when you share a pack with another team or an AI agent via Hopsule MCP. It ensures that context remains portable and self-contained.

Filtering and Temporal Analysis

As an organization grows, the Knowledge Graph can become dense. To maintain clarity, Hopsule provides powerful filtering tools located in the Filter Pane. You can filter nodes by their lifecycle state, specific tags, or the individual who authored the entry. This is particularly useful for senior developers who want to review only Pending decisions or for security officers who need to see all decisions tagged with #compliance.

One of the most powerful features of the Knowledge Graph is the Temporal Slider. This tool allows you to "rewind" the state of your organization's memory. By sliding the timeline back, you can see what the decision landscape looked like six months ago, which decisions were active then, and which memories had been recorded. This temporal analysis is invaluable for post-mortems and for understanding how architectural debt may have accumulated over time. It transforms the graph from a static snapshot into a living history of organizational judgment.

Important: Filtering the graph only changes your current view; it does not delete or hide data from the underlying system. All decisions remain enforceable by Hopsule for VS Code regardless of your current graph filter settings.

Strategic Analysis: Clusters and Gaps

The Knowledge Graph is a diagnostic tool for engineering leadership. By observing the density and distribution of nodes, you can identify the "centers of gravity" in your technical architecture. High-density clusters often indicate areas of the system that are undergoing rapid change or require significant governance. Conversely, isolated nodes—decisions that have no links to memories or other decisions—represent a risk to organizational continuity.

Identifying "orphaned memories" is a key part of maintaining a healthy Hopsule instance. An orphaned memory is a piece of context that was recorded but never formally linked to an enforceable decision. These often represent "lost lessons" that the team intended to act upon but never did. The Knowledge Graph makes these visible as floating square nodes, prompting leaders to either link them to existing decisions or use them as the basis for new ones.

Using the Graph for Decision Review Meetings

The Knowledge Graph is designed to be the centerpiece of technical steering committee meetings and architectural reviews. Instead of scrolling through a flat list of documents, teams can project the Brain and walk through the decision landscape visually. This approach encourages a more holistic discussion about how a proposed change affects existing commitments.

1. Identify the Entry Point: Search for the primary decision or tag related to the meeting's agenda.

2. Expand the Context: Click the node to reveal its immediate neighbors, including the memories that explain why it was created.

3. Simulate Impact: Use the graph to trace dependencies. If we deprecate this decision, which other "Accepted" decisions are impacted?

4. Capture Real-time: As the team discusses, use the Hopper integration within the graph view to draft new memories or link existing nodes based on the conversation.

By using the graph in this way, the meeting itself becomes an act of preservation. The reasoning discussed in the room is captured and linked immediately, ensuring that the "why" is never lost to time or personnel turnover. This turns governance into a collaborative, visual process rather than a bureaucratic hurdle.

Graph Export and Public Sharing

While the Knowledge Graph is primarily an internal tool for governance and remembrance, there are times when you may need to share your decision landscape with external stakeholders, auditors, or partner teams. Hopsule allows you to export specific views of the graph as high-resolution images or interactive snapshots accessible via secure tokens.

When sharing a snapshot, you can choose to redact sensitive Memories while keeping the Decisions visible. This is particularly useful for compliance reporting, where you need to prove that an enforcement system is in place without exposing the internal reasoning behind every technical trade-off. These snapshots are "frozen" versions of the graph, providing a point-in-time reference for external review. You can manage all active sharing tokens from the Settings tab within the Hopsule Dashboard.

Tip: Use the "Export as SVG" option for architectural documentation or internal presentations to maintain high visual fidelity at any scale.

Performance and Large Datasets

Hopsule is built to support the complexity of enterprise engineering organizations. As your graph grows to include thousands of decisions and memories, the Knowledge Graph employs several optimization techniques to ensure a smooth experience. The system uses Level of Detail (LoD) rendering, which simplifies the appearance of distant nodes while maintaining full detail for the area you are currently inspecting.

For exceptionally large datasets, Hopsule introduces Clustered Views. In this mode, the graph automatically groups related nodes into "meta-nodes" based on their Context Pack membership or shared tags. This reduces visual clutter and allows you to navigate the organization at a high level before "diving in" to specific sub-graphs. The Hopsule API also supports paginated graph queries, allowing custom integrations to pull specific segments of the brain without overwhelming the client. Regardless of the size of your organization, Hopsule ensures that your collective memory remains accessible, navigable, and performant.

Important: If you experience performance degradation on older hardware, navigate to Graph Settings and disable "Physics Animations" to reduce the computational load on your local machine.