mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-05-04 06:30:09 +00:00
add docs for graph package (#603)
This commit is contained in:
nexxeln
parent
7a2f2cb99c
commit
1b9b3012e3
8 changed files with 1075 additions and 328 deletions
334
apps/docs/memory-graph/api-reference.mdx
Normal file
334
apps/docs/memory-graph/api-reference.mdx
Normal file
|
|
@ -0,0 +1,334 @@
|
|||
---
|
||||
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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue