UI Navigation Guide

Complete guide to using the Kybernesis topology interface.

Topology Canvas Overview
Keyboard Shortcuts
Node Interaction
Search and Filtering
Chat Input
File Upload
Tag Management
Memory List View
Settings Panel
Connectors Panel
MCP API Keys
Tips and Tricks

Topology Canvas Overview

The topology canvas is the main interface for visualizing and interacting with your memory network.

Visual Elements

Memory Nodes

Circular nodes representing individual memories:

Visual indicators:

Color - Represents source type:
- Purple - Uploaded files
- Blue - Chat messages
- Green - Connector synced content
Size - Indicates priority (larger = higher priority)
Glow - Shows selection/hover state
Pulsing - Indicates activity or search match

Node labels:

Title displayed below node
Tags shown as badges
Summary appears on hover

Connections (Edges)

Lines between nodes representing relationships:

Visual properties:

Thickness - Relationship weight (thicker = stronger)
Color - Relationship type
Opacity - Confidence level (more opaque = higher confidence)

Clusters

Groups of related nodes with shared characteristics:

Cluster types:

Tag-based clusters (memories with common tags)
Entity-based clusters (shared entities)
Source-based clusters (same origin)

Canvas Controls

Mouse Controls

Pan (move the view):

terminal

Click + drag on empty space → Pan camera

Zoom:

terminal

Scroll wheel up → Zoom in
Scroll wheel down → Zoom out

Select node:

terminal

Click on node → Show details panel

Drag node:

terminal

Click + drag node → Reposition node
Release → Node returns to physics position

Hover:

terminal

Mouse over node → Show quick preview

Touch Controls (Mobile/Tablet)

Pan:

terminal

One finger drag → Pan camera

Zoom:

terminal

Pinch → Zoom in/out

Select:

terminal

Tap node → Show details

HUD Elements

Top-Left: System Clock

terminal

┌──────────────────┐
│ 14:32:45         │
└──────────────────┘

Shows current system time.

Top-Right: Stats Panel

terminal

┌──────────────────────────┐
│ MEMORIES: 147            │
│ CONNECTIONS: 342         │
│ CLUSTERS: 12             │
│ ACTIVITY: █████░░░ 67%   │
└──────────────────────────┘

Metrics:

Memories - Total memory count
Connections - Total edges in graph
Clusters - Number of detected clusters
Activity - System activity level (updated in real-time)

Toggle stats:

terminal

Cmd/Ctrl + S

Bottom-Right: Keyboard Hints

terminal

┌─────────────────────────────┐
│ [Cmd+H] Toggle Hints        │
│ [Cmd+K] Chat                │
│ [Cmd+L] Memory List         │
│ [Space] Reset View          │
│ [ESC] Clear Selection       │
└─────────────────────────────┘

Toggle hints:

terminal

Cmd/Ctrl + H

Keyboard Shortcuts

Global Shortcuts (with Cmd/Ctrl)

Shortcut	Action	Description
`Cmd/Ctrl + H`	Toggle Hints	Show/hide keyboard shortcuts panel
`Cmd/Ctrl + S`	Toggle Stats	Show/hide statistics panel
`Cmd/Ctrl + K`	Chat	Open chat input modal
`Cmd/Ctrl + C`	Connectors	Open connectors management panel
`Cmd/Ctrl + M`	MCP Keys	Open MCP API keys panel
`Cmd/Ctrl + L`	Memory List	Open memory list view
`Cmd/Ctrl + G`	Tag Manager	Open tag management panel
`Cmd/Ctrl + A`	Settings	Open account settings

Canvas Shortcuts (no modifier)

Key	Action	Description
`Space`	Reset View	Center camera and reset zoom to 1.0
`ESC`	Clear/Close	Clear selection or close active modal
`Enter`	Select Result	Select first search result
`Backspace`	Delete Char	Remove character from search query
`A-Z, 0-9`	Search	Type to search (when no modal is open)

Mouse Shortcuts

Action	Result
Scroll Up	Zoom in
Scroll Down	Zoom out
Click + Drag (canvas)	Pan camera to navigate
Click (node)	Select and show details
Hover (node)	Show quick preview

Node Interaction

Selecting a Node

Click on any node to view its details:

terminal

Node clicked
    ↓
Details panel slides in from right
    ↓
Shows:
  - Full title
  - Summary/description
  - Tags (auto + manual)
  - Source information
  - Chunks (if multi-chunk)
  - Related memories
  - Action buttons

Node Details Panel

Layout:

terminal

┌──────────────────────────────────┐
│ [X] Close                        │
├──────────────────────────────────┤
│ Memory Title                     │
│ ──────────────────────────────── │
│ Source: upload | Priority: 0.85  │
│ Tier: hot | Created: 2024-10-15  │
├──────────────────────────────────┤
│ Summary:                         │
│ This document describes...       │
├──────────────────────────────────┤
│ Tags:                            │
│ [ai] [python] [2025-planning]    │
│ [+] Add Tag                      │
├──────────────────────────────────┤
│ Chunks: [< 1 of 3 >]             │
│ Content preview...               │
├──────────────────────────────────┤
│ Actions:                         │
│ [Edit] [Delete]                  │
└──────────────────────────────────┘

Editing Memory Details

Click "Edit" button in details panel:

Editable fields:

Title - Change display name
Summary - Update description

Steps:

Click [Edit] button
Modify title/summary
Click [Save] or [Cancel]
Changes sync to backend

Deleting a Memory

Click "Delete" button in details panel:

Warning dialog appears:

terminal

┌────────────────────────────────┐
│ Delete Memory?                 │
│ ────────────────────────────── │
│ This will permanently delete:  │
│ - Memory item                  │
│ - All chunks                   │
│ - Vector embeddings            │
│ - Relationships                │
│                                │
│ This cannot be undone.         │
│                                │
│ [Cancel] [Delete Permanently]  │
└────────────────────────────────┘

Steps:

Click [Delete] button
Confirm in dialog
Memory removed from topology
Data deleted from backend

Viewing Chunks

For multi-chunk memories, navigate between chunks:

Chunk navigator:

terminal

Chunks: [< 1 of 3 >]
        ↑   ↑   ↑
     Previous Index Next

Each chunk shows:

Chunk index (position)
Content excerpt
Chunk-specific summary
Vector ID (for debugging)

Search and Filtering

Inline Search

Type directly on the canvas to search:

terminal

Start typing (when no modal is open)
    ↓
Search query appears in search bar
    ↓
Matching nodes highlighted with pulse effect
    ↓
Press Enter to select first result
Press ESC to clear search

Search behavior:

Semantic matching - Finds related concepts
Title matching - Searches memory titles
Tag matching - Includes tag-based filtering
Real-time - Updates as you type

Example:

terminal

Type: "deployment"
      ↓
Matches:
  - "Kubernetes Deployment Guide" (title match)
  - "CI/CD Pipeline Setup" (semantic match)
  - "Production Launch Plan" (semantic match)

Search Results Display

Matching nodes:

Pulsing glow animation
Increased size (1.2x)
Brought to front (z-index)

Search bar:

terminal

┌────────────────────────────────┐
│ Search: deployment             │
│ 3 results                      │
└────────────────────────────────┘

Tag Filtering

Click on a tag badge to filter by tag:

terminal

Click [kubernetes] tag
    ↓
Filter active: only show memories with "kubernetes" tag
    ↓
Other nodes fade out (low opacity)
    ↓
Click tag again to clear filter

Combined with search:

terminal

Search: "optimization"
Filter: [postgresql]
    ↓
Shows only PostgreSQL-related optimization content

Chat Input

Send messages to create new memories from conversations.

Opening Chat

Shortcut:

terminal

Cmd/Ctrl + K

Or click "Chat" button in toolbar.

Chat Modal

terminal

┌──────────────────────────────────────┐
│ Chat Input                      [X]  │
├──────────────────────────────────────┤
│ ┌──────────────────────────────────┐ │
│ │ Type your message here...        │ │
│ │                                  │ │
│ │                                  │ │
│ │                                  │ │
│ └──────────────────────────────────┘ │
│                                      │
│          [Cancel] [Send Message]     │
└──────────────────────────────────────┘

Sending a Message

Steps:

Open chat modal (Cmd/Ctrl + K)
Type your message
Click [Send Message] or press Cmd/Ctrl + Enter
Message sent to ingestion pipeline
New memory node appears in topology

Processing flow:

terminal

Message sent
    ↓
Queued for ingestion
    ↓
Content chunked
    ↓
Embeddings generated
    ↓
Stored in Convex + Chroma
    ↓
Appears in topology (refresh)

Message Formatting

Supports:

Plain text
Line breaks
Long-form content

Best practices:

Be descriptive (helps with search)
Include relevant keywords
Add context for future reference

File Upload

Upload documents to create new memories.

Drag and Drop

Drag files from your computer onto the canvas:

terminal

File dragged over canvas
    ↓
Drop zone appears with highlight
    ↓
Release mouse to drop
    ↓
Upload begins
    ↓
Progress indicator shows status
    ↓
File ingested and appears as node

Visual feedback:

terminal

┌────────────────────────────────┐
│                                │
│    Drop files here to upload   │
│                                │
│    Supported formats:          │
│    PDF, TXT, MD, DOC, DOCX     │
│                                │
└────────────────────────────────┘

Upload Progress

Progress indicator:

terminal

┌────────────────────────────────┐
│ UPLOADING                      │
│ ████████████░░░░░░░░░ 60%      │
│ budget-analysis.pdf            │
└────────────────────────────────┘

Status updates:

UPLOADING - File being transferred
PROCESSING - Backend ingestion
COMPLETE - Ready in topology
ERROR - Upload failed (retry)

Supported File Types

Format	Extension	Notes
Text	.txt	Plain text
Markdown	.md	Formatted text
PDF	.pdf	Extracted text
Word	.doc, .docx	Microsoft Word
Code	.js, .py, .ts, etc.	Source code

Upload Limits

File size: Recommended < 10MB
Inline processing: < 512KB (faster)
Batch uploads: Multiple files supported

Tag Management

Organize memories with tags.

Adding Manual Tags

From node details panel:

terminal

1. Select a node
2. Scroll to Tags section
3. Click [+ Add Tag] button
4. Type tag name
5. Press Enter or click Add

Tag input:

terminal

┌────────────────────────────────┐
│ Add Tag:                       │
│ ┌────────────────────────────┐ │
│ │ 2025-planning              │ │
│ └────────────────────────────┘ │
│              [Add] [Cancel]    │
└────────────────────────────────┘

Tag Badge Colors

Manual tags:

Emerald green (#10b981)
Label: "Manual"

Auto tags:

Slate blue (#64748b)
Label: "Auto"

Custom colors:

Set via Tag Manager
Persists across sessions

Tag Manager Panel

Open with:

terminal

Cmd/Ctrl + G

Features:

terminal

┌──────────────────────────────────────┐
│ Tag Manager                     [X]  │
├──────────────────────────────────────┤
│ Search: ┌──────────────────────────┐ │
│         │ kubernetes               │ │
│         └──────────────────────────┘ │
├──────────────────────────────────────┤
│ All Tags (42):                       │
│                                      │
│ [ai] (12 memories)            [...] │
│ [python] (8 memories)         [...] │
│ [kubernetes] (15 memories)    [...] │
│ [2025-planning] (6 memories)  [...] │
│                                      │
├──────────────────────────────────────┤
│ Selected: kubernetes                 │
│ Actions:                             │
│ [Rename] [Merge] [Set Color] [Delete] │
└──────────────────────────────────────┘

Tag Operations

Rename Tag

terminal

1. Select tag in Tag Manager
2. Click [Rename]
3. Enter new name
4. Confirm
5. All memories updated

Merge Tags

terminal

1. Select source tag
2. Click [Merge]
3. Select target tag
4. Confirm merge
5. All instances replaced

Set Tag Color

terminal

1. Select tag
2. Click [Set Color]
3. Pick color from palette
4. Color applied to all instances

Delete Tag

terminal

1. Select tag
2. Click [Delete]
3. Confirm deletion
4. Tag removed from all memories

Memory List View

View all memories in a sortable, searchable table.

Opening Memory List

Shortcut:

terminal

Cmd/Ctrl + L

Memory List Modal

terminal

┌──────────────────────────────────────────────────────┐
│ Memory List                                    [X]   │
├──────────────────────────────────────────────────────┤
│ Search: ┌────────────────────────────────────────┐   │
│         │ filter memories...                     │   │
│         └────────────────────────────────────────┘   │
├──────────────────────────────────────────────────────┤
│ Title ▼         Source    Date         Priority     │
│ ──────────────────────────────────────────────────── │
│ Q4 Planning     upload    2024-10-15   ████░ 0.85   │
│ API Guide       connector 2024-10-12   ███░░ 0.70   │
│ Chat: Ideas     chat      2024-10-10   ██░░░ 0.45   │
│ ...                                                  │
├──────────────────────────────────────────────────────┤
│ Showing 50 of 147 memories                           │
│                                            [Load More]│
└──────────────────────────────────────────────────────┘

Sorting

Click column headers to sort:

terminal

Click "Title" → Sort alphabetically
Click again  → Reverse order (Z-A)

Click "Date"     → Sort by creation date
Click "Priority" → Sort by priority score
Click "Source"   → Group by source type

Sort indicator:

▼ (down arrow) - Descending
▲ (up arrow) - Ascending

Filtering in List

Search box filters:

Title matching
Tag matching
Source matching

Example:

terminal

Search: "kubernetes"
    ↓
Shows only memories with "kubernetes" in title or tags

Row Actions

Click on a row to select memory:

terminal

Row clicked
    ↓
Row highlighted
    ↓
Quick actions appear:
  [View] [Edit] [Delete] [+ Tag]

Adding Tags from List

terminal

1. Select memory row
2. Click [+ Tag] button
3. Enter tag name
4. Press Enter
5. Tag added to memory

Settings Panel

Manage account preferences and API keys.

Opening Settings

Shortcut:

terminal

Cmd/Ctrl + A

Settings Modal

terminal

┌──────────────────────────────────────┐
│ Account Settings               [X]   │
├──────────────────────────────────────┤
│ Profile:                             │
│ ┌──────────────────────────────────┐ │
│ │ Display Name: John Doe           │ │
│ │ Email: john@example.com          │ │
│ └──────────────────────────────────┘ │
│ [Edit Profile]                       │
├──────────────────────────────────────┤
│ API Access:                          │
│ ┌──────────────────────────────────┐ │
│ │ claude-code-key                  │ │
│ │ kb_abc123... | Last used: 2h ago │ │
│ │ [Regenerate] [Revoke]            │ │
│ └──────────────────────────────────┘ │
│ [+ Generate New API Key]             │
├──────────────────────────────────────┤
│ Notifications:                       │
│ ☑ Enable notifications              │
│ Email Digest: [Weekly ▼]            │
├──────────────────────────────────────┤
│ Data Retention:                      │
│ Retain for: [365 days ▼]            │
├──────────────────────────────────────┤
│ Actions:                             │
│ [Export Data] [Sign Out]             │
└──────────────────────────────────────┘

Profile Settings

Editable fields:

Display name
Email (read-only, from Clerk)

To edit:

terminal

1. Click [Edit Profile]
2. Update display name
3. Click [Save]

API Access

Generate API keys for programmatic access (MCP, Claude Desktop, etc.):

To generate a new key:

terminal

1. Click [+ Generate New API Key]
2. Enter key name (e.g., "claude-code")
3. Select permissions: [read] [write]
4. Click [Generate]
5. Key displayed ONCE - copy immediately!
6. Store securely (cannot retrieve later)

Generated key format:

terminal

kb_1234567890abcdef1234567890abcdef1234567890abcdef

Key management:

Regenerate - Generate new value for existing key name
Revoke - Permanently disable key
Last used - Timestamp of most recent API call

See MCP Setup Guide for usage examples.

Notification Settings

Options:

Enable notifications - Toggle email notifications
Email digest frequency:
- Daily
- Weekly
- Monthly
- Never

Data Retention

Retention period:

30 days
90 days
180 days
365 days
Forever

Note: Archived memories are retained regardless of setting.

Export Data

Click [Export Data] to download:

terminal

Export includes:
  - All memory items
  - Chunks
  - Tags
  - Relationships
  - Summaries

Format: JSON
Size: ~2-50MB depending on collection size

Connectors Panel

Manage OAuth connectors to sync external content.

Opening Connectors

Shortcut:

terminal

Cmd/Ctrl + C

Note: Only available if CONNECTORS_ENABLED=true.

Connectors Modal

terminal

┌──────────────────────────────────────┐
│ Connectors                      [X]  │
├──────────────────────────────────────┤
│ Google Drive                         │
│ Status: Connected                    │
│ Last Sync: 2024-10-24 14:30          │
│ Items: 47 documents                  │
│ [Sync Now] [Disconnect]              │
├──────────────────────────────────────┤
│ Notion                               │
│ Status: Not Connected                │
│ [Connect to Notion]                  │
├──────────────────────────────────────┤
│ [+ Add New Connector]                │
└──────────────────────────────────────┘

Connector States

Connected:

Green indicator
Shows last sync time
Sync Now button enabled

Not Connected:

Gray indicator
Connect button visible

Syncing:

Animated spinner
"Syncing..." status
Sync button disabled

Error:

Red indicator
Error message displayed
Retry button available

Syncing a Connector

terminal

1. Click [Sync Now]
2. Sync job queued
3. Status updates to "Syncing..."
4. Progress indicator shows items
5. Complete → "Last Sync: [time]"

Disconnecting a Connector

terminal

1. Click [Disconnect]
2. Confirmation dialog appears
3. Confirm disconnection
4. OAuth credentials revoked
5. Synced memories remain (not deleted)

See Connectors Guide for detailed setup.

MCP Setup

Access your memories programmatically via MCP (Memory Control Plane) for use with Claude Code, Cursor, and other AI tools.

Opening MCP Modal

Shortcut:

terminal

Cmd/Ctrl + M

MCP Setup Instructions

The MCP modal provides setup instructions for integrating Kybernesis with your AI tools:

terminal

┌──────────────────────────────────────┐
│ MCP Setup                       [X]  │
├──────────────────────────────────────┤
│ Connect Kybernesis to Claude Code,  │
│ Cursor, and other MCP clients.      │
├──────────────────────────────────────┤
│                                      │
│ Setup Instructions                   │
│                                      │
│ 1. Generate API key in Settings      │
│    (Cmd+A → API Access)              │
│                                      │
│ 2. Install MCP client:               │
│    npx -y @kybernesis/mcp            │
│                                      │
│ 3. Configure your AI tool            │
│    (see examples below)              │
│                                      │
└──────────────────────────────────────┘

To get your API key: Press Cmd+A → API Access → Generate New API Key

See the complete setup guide: MCP Integration Guide

Tips and Tricks

Efficiency Tips

1. Use Keyboard Shortcuts

terminal

Master these for fastest navigation:
  Cmd+K - Quick chat
  Cmd+L - Memory list
  Space - Reset view
  ESC   - Close/clear

2. Search While Browsing

terminal

Type directly on canvas to search
No need to open a search modal
Results appear instantly

3. Tag-Based Filtering

terminal

Click any tag badge to filter
Quickly isolate related memories
Click again to clear filter

4. Batch Tag Operations

terminal

Use Tag Manager (Cmd+G) to:
  - Rename tags across all memories
  - Merge duplicate tags
  - Set consistent colors

Performance Tips

1. Limit Display Count

terminal

Memory list shows 50 by default
Load more only when needed
Improves rendering performance

2. Use Specific Searches

terminal

❌ "deployment"
✓ "kubernetes deployment production"
Specific = fewer results = faster

3. Close Unused Modals

terminal

ESC to close any modal
Reduces UI overhead
Improves canvas FPS

Organization Tips

1. Consistent Tag Naming

terminal

Use lowercase, hyphen-separated:
  ✓ "2025-planning"
  ✓ "high-priority"
  ❌ "2025 Planning"
  ❌ "HighPriority"

2. Manual Tags for Projects

terminal

Add project tags manually:
  - "project-apollo"
  - "client-acme"
  - "q4-2024"
Prevents archival
Improves organization

3. Regular Exports

terminal

Export data monthly
Backup before major changes
Format: JSON (easy to restore)

Workflow Tips

1. Chat for Quick Notes

terminal

Cmd+K → Type idea → Send
Faster than uploading files
Good for fleeting thoughts

2. Upload for Documents

terminal

Drag PDFs/docs directly
Preserves formatting
Better for reference materials

3. Connectors for Ongoing Sync

terminal

Connect Google Drive/Notion
Auto-sync keeps memories fresh
No manual re-uploads needed

Next Steps

Retrieval Guide - Master search techniques
Connectors Setup - Connect external platforms
Core Concepts - Understand the system
Memory System - Deep dive into memory management

UI Navigation Guide

Table of Contents

Topology Canvas Overview

Visual Elements

Memory Nodes

Connections (Edges)

Clusters

Canvas Controls

Mouse Controls

Touch Controls (Mobile/Tablet)

HUD Elements

Top-Left: System Clock

Top-Right: Stats Panel

Bottom-Right: Keyboard Hints

Keyboard Shortcuts

Global Shortcuts (with Cmd/Ctrl)

Canvas Shortcuts (no modifier)

Mouse Shortcuts

Node Interaction

Selecting a Node

Node Details Panel

Editing Memory Details

Deleting a Memory

Viewing Chunks

Search and Filtering

Inline Search

Search Results Display

Tag Filtering

Chat Input

Opening Chat

Chat Modal

Sending a Message

Message Formatting

File Upload

Drag and Drop

Upload Progress

Supported File Types

Upload Limits

Tag Management

Adding Manual Tags

Tag Badge Colors

Tag Manager Panel

Tag Operations

Rename Tag

Merge Tags

Set Tag Color

Delete Tag

Memory List View

Opening Memory List

Memory List Modal

Sorting

Filtering in List

Row Actions

Adding Tags from List

Settings Panel

Opening Settings

Settings Modal

Profile Settings

API Access

Notification Settings

Data Retention

Export Data

Connectors Panel

Opening Connectors

Connectors Modal

Connector States

Syncing a Connector

Disconnecting a Connector

MCP Setup

Opening MCP Modal

MCP Setup Instructions

Tips and Tricks

Efficiency Tips

1. Use Keyboard Shortcuts

2. Search While Browsing

3. Tag-Based Filtering

4. Batch Tag Operations

Performance Tips

1. Limit Display Count

2. Use Specific Searches