path: root/apps/docs/memory-graph/api-reference.mdx

---
title: 'API Reference'
description: 'Complete reference for Memory Graph props and types'
---

## Component Props

### MemoryGraph

The main graph component.

#### Core Props

<ParamField path="documents" type="DocumentWithMemories[]" required>
  Array of documents to display in the graph. Each document must include its memory entries.
</ParamField>

<ParamField path="isLoading" type="boolean" default="false">
  Shows a loading indicator when true.
</ParamField>

<ParamField path="error" type="Error | null" default="null">
  Error object to display. Shows an error message overlay when set.
</ParamField>

<ParamField path="variant" type='"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)
</ParamField>

<ParamField path="children" type="ReactNode">
  Content to render when no documents exist. Useful for empty states.
</ParamField>

#### Pagination Props

<ParamField path="isLoadingMore" type="boolean" default="false">
  Shows a subtle indicator when loading additional documents.
</ParamField>

<ParamField path="hasMore" type="boolean" default="false">
  Whether more documents are available to load.
</ParamField>

<ParamField path="totalLoaded" type="number">
  Total number of documents currently loaded. Shown in loading indicator.
</ParamField>

<ParamField path="loadMoreDocuments" type="() => Promise<void>">
  Callback to load more documents. Called automatically when viewport shows most documents.
</ParamField>

<ParamField path="autoLoadOnViewport" type="boolean" default="true">
  Automatically load more documents when 80% are visible in viewport.
</ParamField>

#### Display Props

<ParamField path="showSpacesSelector" type="boolean">
  Show or hide the space filter dropdown. Defaults to `true` for console variant, `false` for consumer.
</ParamField>

<ParamField path="highlightDocumentIds" type="string[]" default="[]">
  Array of document IDs to highlight with a pulsing outline. Accepts both `customId` and internal `id`.
</ParamField>

<ParamField path="highlightsVisible" type="boolean" default="true">
  Controls whether highlights are shown. Useful for toggling highlights without changing the array.
</ParamField>

<ParamField path="occludedRightPx" type="number" default="0">
  Pixels occluded on the right side (e.g., by a sidebar). Graph auto-fits accounting for this space.
</ParamField>

<ParamField path="legendId" type="string">
  Custom ID for the legend component. Useful for testing or styling.
</ParamField>

#### Controlled State Props

<ParamField path="selectedSpace" type="string">
  Currently selected space. When provided, makes space selection controlled. Use `"all"` for all spaces.
</ParamField>

<ParamField path="onSpaceChange" type="(spaceId: string) => void">
  Callback when space selection changes. Required when using `selectedSpace`.
</ParamField>

<ParamField path="memoryLimit" type="number">
  Maximum memories to show per document when a specific space is selected. Only applies when `selectedSpace !== "all"`.
</ParamField>

<ParamField path="isExperimental" type="boolean" default="false">
  Enable experimental features. Currently unused but reserved for future features.
</ParamField>

## Data Types

### DocumentWithMemories

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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.

```typescript
import { GraphCanvas } from '@supermemory/memory-graph';
```

### Legend

Graph legend showing node types and counts.

```typescript
import { Legend } from '@supermemory/memory-graph';
```

### LoadingIndicator

Loading state indicator with progress counter.

```typescript
import { LoadingIndicator } from '@supermemory/memory-graph';
```

### NodeDetailPanel

Side panel showing node details when clicked.

```typescript
import { NodeDetailPanel } from '@supermemory/memory-graph';
```

### SpacesDropdown

Space filter dropdown.

```typescript
import { SpacesDropdown } from '@supermemory/memory-graph';
```

## Exported Hooks

### useGraphData

Processes documents into graph nodes and edges.

```typescript
import { useGraphData } from '@supermemory/memory-graph';

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

### useGraphInteractions

Handles pan, zoom, and node interactions.

```typescript
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:

```typescript
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:

```typescript
import { GRAPH_SETTINGS } from '@supermemory/memory-graph';

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

### LAYOUT_CONSTANTS

Spatial layout configuration:

```typescript
import { LAYOUT_CONSTANTS } from '@supermemory/memory-graph';

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