Knowledge Graph

Cortexa automatically discovers and links related thoughts by querying the HNSW semantic index after every embedding. The result is a navigable knowledge graph where each thought connects to its nearest semantic neighbors -- revealing patterns and relationships across projects, topics, and time.

Exploring the Knowledge Map

The graph keeps its 2D and 3D renderers, lenses, overlays, pinning, and live updates. New exploration controls help you move from the overview to a specific thought:

• Topics shows named communities discovered in the currently loaded map. Choose a topic to load a neighborhood around up to 64 of its members. The topic's anchor is always included in the seed request.
• Constellation cards preview up to nine thoughts and their stored connections. These are small topology samples, not the full topic or suggested links.
• Camera controls sit in the bottom-right corner: zoom in, zoom out, fit the map (F), and expand the map. Escape exits the expanded view and clears the current selection. Choose Topics to return to the topic cards.
• 2D and 3D share the same map and selection. In 2D, topic labels sit above their clusters. In 3D, a ring marks the selected thought and only a small set of hubs keeps a persistent label; hover any thought for its title. Camera navigation respects reduced-motion preferences.
• Thought details opens when you select a thought. Read its full text, summary, origin, source context, and tags without leaving the map. Connected thoughts are navigable from the inspector.
• Explore neighborhood loads a thought's direct stored connections, including ones missing from the overview sample. Distance expands to two connection steps. Local requests use at most 300 thoughts; they do not load unrelated global hubs. Counts refer to the loaded view, not complete vault connectivity.
• Overview and Back retrace exploration. Saved views remembers up to 12 named topic/thought locations on this device; it stores the scope and selected thought, not a screenshot, camera pose, or filter preset.
• Start a path here selects a starting thought. Select another thought to highlight a shortest undirected path through stored connections in the loaded view. Suggested semantic edges and pending dreams are excluded. A missing path means none was found in this view; a connection does not establish causation or agreement. Very long paths show the first 100 text steps while highlighting the full route.
• Discover lists stored links across projects in the loaded map. Connection details explain the link type and weight. Semantic weights are embedding similarity, not factual confidence. Clicking a suggested semantic edge opens details before the explicit Save this connection action.
• Timeline replays creation history with a date, visible-thought count, and latest thought's project and title. Playback, seeking, and speed controls remain available.
• View → Background (3D) offers Nebula, Starlight, and Midnight. The choice is remembered. Backgrounds use a static texture, while softer bloom and shaded thought nodes keep dense connections readable.
• View → Visual effects offers Auto, Full, and Quiet. Auto reduces 2D ambient glow and moving link particles for large maps, reduced-motion preferences, or sustained slow 2D frame rates. Full overrides this adjustment. Quiet leaves thoughts, labels, connections, and controls accessible. The existing 3D renderer still uses its own batching and quality limits.

The overview loads at most 500 thoughts. Zooming changes the camera only; search and topic navigation load local neighborhoods without scaling the canvas to the entire vault. The semantic preview searches up to 500 loaded seeds rather than scanning every embedded thought. Indexed metadata lookups keep imported vaults from holding the shared store lock for long joins.

Large maps compute their topic communities in a background worker; the force layout itself retains its existing incremental animation-frame simulation. Focused labels reserve space before neighboring labels are placed. Off-screen culling, saved layout positions, and batched 3D drawing remain in use.

The desktop frontend and backend must be rebuilt together: neighborhood exploration uses the graph_neighborhood Tauri command. This query is read-only, clamps expansion to two hops and 500 live thoughts, ignores deleted/trashed endpoints and near-duplicate semantic edges, and preserves seeds within its budget.

How Auto-Linking Works

When a thought is captured and embedded, Cortexa runs an AutoLink background job:

1. Query the HNSW index -- the thought's embedding vector is searched against the index for its link_top_k nearest neighbors above link_threshold similarity
2. Exclude self -- the thought itself is filtered out of results
3. Clear stale links -- any existing semantic links for this thought are removed (handles re-embedding cleanly)
4. Create bidirectional links -- for each qualifying neighbor, a link is created in both directions with the cosine similarity score
5. Notify -- a "Related thoughts found" notification shows the top 3 matches with similarity percentages and previews

Links are stored in the SQLite database with the link type "semantic", the similarity score, and both endpoint IDs. Because links are bidirectional, if Thought A links to Thought B, Thought B also links back to Thought A.

Example notification

Related thoughts found
[87%] Switched from brute-force cosine to HNSW index for O(log N) search
[74%] HNSW parameters: ef_construction=200 gives good recall at the cost of...
[61%] Considered Annoy and ScaNN before settling on instant-distance for the...

Configuration

Knowledge graph settings are in Settings > Search & KG:

Setting	Default	Range	Description
link_top_k	5	1-50	Maximum number of neighbors to link per thought
link_threshold	0.55	0.0-1.0	Minimum cosine similarity to create a link
auto_link	true	--	Whether to run auto-linking after each embedding

Tuning link_top_k

• Lower values (3-5) create a sparse graph with only strong connections. Good for focused vaults where you want only the most relevant links.
• Higher values (10-20) create a denser graph that surfaces more tangential connections. Good for exploration and cross-project discovery.
• The maximum is 50, but values above 15-20 rarely add useful connections.

Tuning link_threshold

• Higher values (0.7+) require strong semantic similarity. Links are fewer but very relevant.
• Lower values (0.4-0.5) cast a wider net. You get more links but some may feel tangential.
• The default of 0.55 is a good balance for English-language vaults with nomic-embed-text embeddings. Multilingual models or models with different similarity distributions may need adjustment.
• Setting threshold to 0.0 links to the nearest neighbors regardless of similarity (not recommended -- you will get noise).

Disabling auto-link

Set auto_link to false if you want to manage links manually or run bulk rebuilds instead of incremental linking. When disabled, the AutoLink job exits immediately without querying the index.

Stale Link Cleanup

When a thought is re-embedded (for example, after switching embedding models and clicking Re-embed all), the auto-link job clears all existing semantic links for that thought before creating new ones. This ensures the graph reflects the current embeddings and does not accumulate stale connections from a previous model.

The cleanup is per-thought: only the re-embedded thought's links are cleared. Other thoughts' links remain intact until they are re-embedded in turn.

Manual Rebuild

To rebuild the entire knowledge graph from scratch:

1. Open Settings > Search & KG
2. Click Rebuild knowledge graph

This:

1. Wipes all existing semantic links across the entire vault
2. Iterates every thought that has an embedding vector
3. For each thought, queries the HNSW index for its top-K neighbors above threshold
4. Creates fresh bidirectional links

Rebuild is useful after:

• Changing link_top_k or link_threshold (existing links were created with the old settings)
• Switching embedding models and completing a re-embed pass
• Any situation where you suspect the graph has drifted from the current index state

Progress events are emitted during rebuild so you can track it in the Activity panel.

Viewing Related Items in the UI

In the main item list, expand any thought to see its related items:

• Related section -- shows linked thoughts sorted by similarity score (highest first)
• Similarity badge -- each link displays its cosine similarity as a percentage (e.g., "87% similar")
• Preview text -- the first ~80 characters of each linked thought's content

Clickable Navigation

Click any related item to navigate to it and expand its detail view. This lets you follow chains of related thoughts -- from a decision, to the architecture note it informed, to the debug finding that challenged it.

The navigation is immediate: clicking a related item scrolls to it, highlights it, and expands it in the list. You can traverse the graph visually by following links from one thought to the next.

Link events

When auto-linking completes, Cortexa emits item-linked events for both the source thought and each linked neighbor. The UI listens for these events to update the related items section in real time -- you see links appear as soon as the background job finishes, without refreshing.

How the Graph Relates to Search

The knowledge graph and search are built on the same HNSW index but serve different purposes:

Feature	Search	Knowledge Graph
When it runs	On demand (user query)	Automatically after embedding
Query	User's search text, embedded as a vector	The thought's own embedding vector
Signal	Hybrid (semantic + keyword)	Semantic only (cosine similarity)
Output	Ranked search results	Persistent bidirectional links
Purpose	Find relevant thoughts now	Discover relationships for later

The knowledge graph pre-computes relationships so they are available instantly when you expand a thought. Search computes relevance on the fly for a specific query. Both use the same HNSW index, so they are always in sync.

Deep Think Integration

The Counterpoint stage of Deep Think uses the HNSW index directly (not the knowledge graph links) to pull the 8 nearest neighbors for contradiction detection. This means the critic has access to your most semantically similar prior thoughts regardless of whether auto-linking created explicit connections.

The knowledge graph links and Deep Think's neighbor lookup are independent but complementary -- the graph is for human navigation, Deep Think's lookup is for LLM-powered critique.

Example: Cross-Project Discovery

Suppose you capture a decision about rate limiting in Project A:

/idea: Use token bucket algorithm for API rate limiting, with per-user buckets
stored in Redis with TTL-based cleanup

Later, in Project B, you capture:

Rate limiting the WebSocket connections: need to throttle message frequency
per connection without blocking other connections

If both thoughts embed similarly (both deal with rate limiting and per-entity throttling), the knowledge graph links them automatically -- even though they are in different projects. Expanding either thought reveals the other in the related items section.

This cross-project linking is one of Cortexa's key differentiators over per-project memory systems. Your insights compound across your entire vault.

What's Next

• Search -- how hybrid search uses the same HNSW index
• Deep Think -- how the Counterpoint stage uses semantic neighbors for contradiction detection
• MCP Tools Reference -- tools for searching and context injection