Skip to main content

​
Component Props

​
MemoryGraph

The main graph component.

​
Core Props

​
documents
DocumentWithMemories[]
required
Array of documents to display in the graph. Each document must include its memory entries.
​
isLoading
boolean
default:"false"
Shows a loading indicator when true.
​
error
Error | null
default:"null"
Error object to display. Shows an error message overlay when set.
​
variant
"console" | "consumer"
default:"\"console\""
Visual variant:
  • console: Full-featured dashboard view (0.8x zoom, space selector visible)
  • consumer: Embedded widget view (0.5x zoom, space selector hidden)
​
children
ReactNode
Content to render when no documents exist. Useful for empty states.

​
Pagination Props

​
isLoadingMore
boolean
default:"false"
Shows a subtle indicator when loading additional documents.
​
hasMore
boolean
default:"false"
Whether more documents are available to load.
​
totalLoaded
number
Total number of documents currently loaded. Shown in loading indicator.
​
loadMoreDocuments
() => Promise<void>
Callback to load more documents. Called automatically when viewport shows most documents.
​
autoLoadOnViewport
boolean
default:"true"
Automatically load more documents when 80% are visible in viewport.

​
Display Props

​
showSpacesSelector
boolean
Show or hide the space filter dropdown. Defaults to true for console variant, false for consumer.
​
highlightDocumentIds
string[]
default:"[]"
Array of document IDs to highlight with a pulsing outline. Accepts both customId and internal id.
​
highlightsVisible
boolean
default:"true"
Controls whether highlights are shown. Useful for toggling highlights without changing the array.
​
occludedRightPx
number
default:"0"
Pixels occluded on the right side (e.g., by a sidebar). Graph auto-fits accounting for this space.
​
legendId
string
Custom ID for the legend component. Useful for testing or styling.

​
Controlled State Props

​
selectedSpace
string
Currently selected space. When provided, makes space selection controlled. Use "all" for all spaces.
​
onSpaceChange
(spaceId: string) => void
Callback when space selection changes. Required when using selectedSpace.
​
memoryLimit
number
Maximum memories to show per document when a specific space is selected. Only applies when selectedSpace !== "all".
​
isExperimental
boolean
default:"false"
Enable experimental features. Currently unused but reserved for future features.

​
Data Types

​
DocumentWithMemories

interface DocumentWithMemories {
  id: string;
  customId?: string | null;
  contentHash: string | null;
  orgId: string;
  userId: string;
  connectionId?: string | null;
  title?: string | null;
  content?: string | null;
  summary?: string | null;
  url?: string | null;
  source?: string | null;
  type?: string | null;
  status: 'pending' | 'processing' | 'done' | 'failed';
  metadata?: Record<string, string | number | boolean> | null;
  processingMetadata?: Record<string, unknown> | null;
  raw?: string | null;
  tokenCount?: number | null;
  wordCount?: number | null;
  chunkCount?: number | null;
  averageChunkSize?: number | null;
  summaryEmbedding?: number[] | null;
  summaryEmbeddingModel?: string | null;
  createdAt: string | Date;
  updatedAt: string | Date;
  memoryEntries: MemoryEntry[];
}

​
MemoryEntry

interface MemoryEntry {
  id: string;
  customId?: string | null;
  documentId: string;
  content: string | null;
  summary?: string | null;
  title?: string | null;
  url?: string | null;
  type?: string | null;
  metadata?: Record<string, string | number | boolean> | null;
  embedding?: number[] | null;
  embeddingModel?: string | null;
  tokenCount?: number | null;
  createdAt: string | Date;
  updatedAt: string | Date;

  // Fields from join relationship
  sourceAddedAt?: Date | null;
  sourceRelevanceScore?: number | null;
  sourceMetadata?: Record<string, unknown> | null;
  spaceContainerTag?: string | null;

  // Version chain fields
  updatesMemoryId?: string | null;
  nextVersionId?: string | null;
  relation?: 'updates' | 'extends' | 'derives' | null;

  // Memory status fields
  isForgotten?: boolean;
  forgetAfter?: Date | string | null;
  isLatest?: boolean;

  // Space/container fields
  spaceId?: string | null;

  // Legacy fields (for backwards compatibility)
  memory?: string | null;
  memoryRelations?: Array<{
    relationType: 'updates' | 'extends' | 'derives';
    targetMemoryId: string;
  }> | null;
  parentMemoryId?: string | null;
}

​
GraphNode

Internal type for rendered nodes: 
interface GraphNode {
  id: string;
  type: 'document' | 'memory';
  x: number;
  y: number;
  data: DocumentWithMemories | MemoryEntry;
  size: number;
  color: string;
  isHovered: boolean;
  isDragging: boolean;
}

​
GraphEdge

Internal type for connections: 
interface GraphEdge {
  id: string;
  source: string;
  target: string;
  similarity: number;
  edgeType: 'doc-memory' | 'doc-doc' | 'version';
  relationType?: 'updates' | 'extends' | 'derives';
  color: string;
  visualProps: {
    opacity: number;
    thickness: number;
    glow: number;
    pulseDuration: number;
  };
}

​
Exported Components

Besides MemoryGraph, the package exports individual components for advanced use cases:

​
GraphCanvas

Low-level canvas renderer. Not recommended for direct use. 
import { GraphCanvas } from '@supermemory/memory-graph';

​
Legend

Graph legend showing node types and counts. 
import { Legend } from '@supermemory/memory-graph';

​
LoadingIndicator

Loading state indicator with progress counter. 
import { LoadingIndicator } from '@supermemory/memory-graph';

​
NodeDetailPanel

Side panel showing node details when clicked. 
import { NodeDetailPanel } from '@supermemory/memory-graph';

​
SpacesDropdown

Space filter dropdown. 
import { SpacesDropdown } from '@supermemory/memory-graph';

​
Exported Hooks

​
useGraphData

Processes documents into graph nodes and edges. 
import { useGraphData } from '@supermemory/memory-graph';

const { nodes, edges } = useGraphData(
  data,
  selectedSpace,
  nodePositions,
  draggingNodeId,
  memoryLimit
);

​
useGraphInteractions

Handles pan, zoom, and node interactions. 
import { useGraphInteractions } from '@supermemory/memory-graph';

const {
  panX,
  panY,
  zoom,
  selectedNode,
  handlePanStart,
  handleWheel,
  // ... more interaction handlers
} = useGraphInteractions('console');

​
Constants

​
colors

Color palette used throughout the graph: 
import { colors } from '@supermemory/memory-graph';

colors.document.primary;   // Document fill color
colors.memory.primary;     // Memory fill color
colors.connection.strong;  // Strong edge color

​
GRAPH_SETTINGS

Initial zoom and pan settings for variants: 
import { GRAPH_SETTINGS } from '@supermemory/memory-graph';

GRAPH_SETTINGS.console.initialZoom;   // 0.8
GRAPH_SETTINGS.consumer.initialZoom;  // 0.5

​
LAYOUT_CONSTANTS

Spatial layout configuration: 
import { LAYOUT_CONSTANTS } from '@supermemory/memory-graph';

LAYOUT_CONSTANTS.clusterRadius;       // Memory orbit radius
LAYOUT_CONSTANTS.documentSpacing;     // Distance between documents