mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-05-04 06:30:09 +00:00
334 lines
8.1 KiB
Text
334 lines
8.1 KiB
Text
---
|
|
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
|
|
```
|