API Reference

Complete reference for props, types, and configuration options

Component Props

Core Props

documents · DocumentWithMemories[] · required

Array of documents with their associated memories to display in the graph. This is the primary data source for the visualization.

<MemoryGraph
  documents={[
    {
      id: "doc-1",
      title: "Meeting Notes",
      memoryEntries: [
        {
          id: "mem-1",
          documentId: "doc-1",
          content: "Discussed project roadmap",
          // ... other memory fields
        }
      ]
    }
  ]}
/>

isLoading · boolean · default: "false"

Indicates whether the initial data is currently loading. Shows a loading indicator overlay.

<MemoryGraph
  documents={documents}
  isLoading={true}
/>

error · Error | null · default: "null"

Error object to display if data fetching fails. Shows an error state with the error message.

<MemoryGraph
  documents={documents}
  error={new Error('Failed to load graph data')}
/>

children · ReactNode

Content to display when no documents are available. Useful for custom empty states.

<MemoryGraph documents={[]}>
  <div>
    <h2>No memories yet</h2>
    <button>Add Memory</button>
  </div>
</MemoryGraph>

Display Props

variant · 'console' | 'consumer' · default: "'console'"

Visual variant that determines the default zoom level and UI layout.

• console: Full dashboard view (zoom: 0.8, spaces selector shown, legend bottom-right)
• consumer: Embedded widget view (zoom: 0.5, spaces selector hidden, legend top-right)

{/* Full dashboard */}
<MemoryGraph documents={documents} variant="console" />

{/* Embedded widget */}
<MemoryGraph documents={documents} variant="consumer" />

showSpacesSelector · boolean · default: "Based on variant"

Controls visibility of the spaces/container filter dropdown. Defaults to true for console variant, false for consumer variant.

{/* Force show on consumer variant */}
<MemoryGraph
  documents={documents}
  variant="consumer"
  showSpacesSelector={true}
/>

legendId · string

Custom ID for the legend element. Useful for DOM targeting or testing.

<MemoryGraph
  documents={documents}
  legendId="my-custom-legend"
/>

Highlighting Props

highlightDocumentIds · string[] · default: "[]"

Array of document IDs to highlight in the graph. Supports both internal IDs and custom IDs. Perfect for showing search results or filtered content.

<MemoryGraph
  documents={documents}
  highlightDocumentIds={['doc-123', 'custom-id-456']}
/>

highlightsVisible · boolean · default: "true"

Controls whether highlights are currently visible. Useful for toggling highlights on/off.

const [showHighlights, setShowHighlights] = useState(true)

<MemoryGraph
  documents={documents}
  highlightDocumentIds={searchResults}
  highlightsVisible={showHighlights}
/>

Pagination Props

For large datasets, implement pagination to load documents incrementally:

isLoadingMore · boolean · default: "false"

Indicates whether additional data is being loaded. Shows a loading indicator without blocking interactions.

<MemoryGraph
  documents={documents}
  isLoadingMore={true}
/>

hasMore · boolean · default: "false"

Indicates whether more documents are available to load.

<MemoryGraph
  documents={documents}
  hasMore={page < totalPages}
/>

totalLoaded · number · default: "documents.length"

Total number of documents currently loaded. Displayed in the loading indicator.

<MemoryGraph
  documents={documents}
  totalLoaded={documents.length}
/>

loadMoreDocuments · () => Promise<void>

Async callback function to load more documents. Called automatically when user scrolls near the viewport edge.

const loadMore = async () => {
  const nextPage = await fetchNextPage()
  setDocuments(prev => [...prev, ...nextPage])
}

<MemoryGraph
  documents={documents}
  hasMore={true}
  loadMoreDocuments={loadMore}
/>

Advanced Props

occludedRightPx · number · default: "0"

Number of pixels occluded on the right side (e.g., by a chat panel). Used to adjust auto-fit calculations.

{/* Account for 400px chat panel on the right */}
<MemoryGraph
  documents={documents}
  occludedRightPx={400}
/>

autoLoadOnViewport · boolean · default: "true"

Enable automatic loading when 80% of documents are visible in viewport. Set to false for manual pagination control.

<MemoryGraph
  documents={documents}
  hasMore={true}
  loadMoreDocuments={loadMore}
  autoLoadOnViewport={false}
/>

themeClassName · string

Custom theme class name for styling overrides. Use with Vanilla Extract theme system.

import { customTheme } from './my-theme.css'

<MemoryGraph
  documents={documents}
  themeClassName={customTheme}
/>

TypeScript Types

Core Data Types

interface DocumentWithMemories {
  id: string
  customId?: string | null
  title?: string
  content?: string
  summary?: string
  url?: string
  summaryEmbedding?: number[]  // For similarity calculations
  memoryEntries: MemoryEntry[]
  createdAt: string
  updatedAt: string
  userId?: string
  spaceId?: string
  spaceContainerTag?: string
}

interface MemoryEntry {
  id: string
  documentId: string
  content: string | null
  embedding?: number[]
  spaceContainerTag?: string
  spaceId?: string
  updatesMemoryId?: string | null
  relation?: 'updates' | 'extends' | 'derives' | null
  isForgotten?: boolean
  isLatest?: boolean
  forgetAfter?: string | null
  createdAt: string
  updatedAt: string
}

Graph Types

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

interface GraphEdge {
  id: string
  source: string
  target: string
  similarity: number  // 0-1 for semantic similarity
  visualProps: {
    opacity: number
    thickness: number
    glow: number
    pulseDuration: number
  }
  color: string
  edgeType: 'doc-memory' | 'doc-doc' | 'version'
  relationType?: 'updates' | 'extends' | 'derives'
}

Component Props Type

interface MemoryGraphProps {
  // Core
  documents: DocumentWithMemories[]
  isLoading?: boolean
  error?: Error | null
  children?: ReactNode

  // Display
  variant?: 'console' | 'consumer'
  showSpacesSelector?: boolean
  legendId?: string

  // Highlighting
  highlightDocumentIds?: string[]
  highlightsVisible?: boolean

  // Pagination
  isLoadingMore?: boolean
  hasMore?: boolean
  totalLoaded?: number
  loadMoreDocuments?: () => Promise<void>

  // Advanced
  occludedRightPx?: number
  autoLoadOnViewport?: boolean
  themeClassName?: string
}

Variants Comparison

Feature	Console	Consumer
Initial Zoom	0.8 (closer view)	0.5 (wider view)
Spaces Selector	Shown by default	Hidden by default
Legend Position	Bottom-right	Top-right
Best For	Full-page dashboards	Embedded widgets
Use Cases	Admin panels, analytics	Sidebars, chat integration

Console Variant

<MemoryGraph
  documents={documents}
  variant="console"
  // Spaces selector shown
  // Legend in bottom-right
  // Closer initial view
/>

Consumer Variant

<MemoryGraph
  documents={documents}
  variant="consumer"
  // Spaces selector hidden
  // Legend in top-right
  // Wider initial view
/>

Type Imports

Import all types you need for TypeScript:

import type {
  // Data types
  DocumentWithMemories,
  MemoryEntry,
  DocumentsResponse,

  // Graph types
  GraphNode,
  GraphEdge,
  MemoryRelation,

  // Component types
  MemoryGraphProps,

  // Theme types (if customizing)
  Sprinkles,
} from '@supermemory/memory-graph'

Next Steps

Examples

See real-world implementation patterns

Troubleshooting

Solve common issues