mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-02 02:11:20 +00:00
cfa6c7cb17
Document-to-memory links and actual `derives` relations were both emitted as `derives`, so they shared the same color and legend entry. This separates structural document links into a `document` edge type, adds a dedicated theme color with `--graph-edge-document` support, and updates force-layout and level-of-detail handling to preserve existing structural behavior. The package and MCP widget legends/themes now distinguish document links from derived-memory relations. Adds regression coverage for edge classification and validates the package plus its MCP consumer. <!-- capy-badge:start --> <a href="https://capy.ai/thread/jam_01M36F4MPFXZCA8J14T53YY029"><picture><source media="(prefers-color-scheme: dark)" srcset="https://capy.ai/badge/accent-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://capy.ai/badge/accent-light.svg"><img alt="Open in Capy" src="https://capy.ai/badge/accent-light.svg"></picture></a> <!-- capy-badge:end -->
102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# @supermemory/memory-graph
|
|
|
|
Interactive graph visualization for documents and their memory connections.
|
|
|
|
[](https://www.npmjs.com/package/@supermemory/memory-graph)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @supermemory/memory-graph
|
|
# or
|
|
bun add @supermemory/memory-graph
|
|
# or
|
|
pnpm add @supermemory/memory-graph
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```tsx
|
|
import { MemoryGraph } from '@supermemory/memory-graph';
|
|
import type { DocumentWithMemories } from '@supermemory/memory-graph';
|
|
|
|
function App() {
|
|
const [documents, setDocuments] = useState<DocumentWithMemories[]>([]);
|
|
const [isLoading, setIsLoading] = useState(true);
|
|
|
|
useEffect(() => {
|
|
fetch('/api/graph')
|
|
.then(res => res.json())
|
|
.then(data => {
|
|
setDocuments(data.documents);
|
|
setIsLoading(false);
|
|
});
|
|
}, []);
|
|
|
|
return (
|
|
<div style={{ height: '100vh' }}>
|
|
<MemoryGraph
|
|
documents={documents}
|
|
isLoading={isLoading}
|
|
variant="console"
|
|
/>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Interactive canvas visualization** - Pan, zoom, and drag nodes using Canvas 2D rendering
|
|
- **Document and memory nodes** - Documents as rectangles, memories as hexagons
|
|
- **Relationship visualization** - Edges show document similarity and memory version chains
|
|
- **Space filtering** - Filter by workspace or view all memories
|
|
- **Two variants** - Full-featured console mode or embedded consumer mode
|
|
- **Pagination support** - Keep the initial graph fitted as pages arrive; manual pan, zoom, or selection takes control of the view
|
|
- **TypeScript support** - Full type definitions included
|
|
|
|
## Essential Props
|
|
|
|
| Prop | Type | Description |
|
|
|------|------|-------------|
|
|
| `documents` | `DocumentWithMemories[]` | Array of documents with their memory entries |
|
|
| `isLoading` | `boolean` | Show loading state |
|
|
| `variant` | `"console" \| "consumer"` | Display mode (default: "console") |
|
|
| `error` | `Error \| null` | Error to display |
|
|
| `loadMoreDocuments` | `() => Promise<void>` | Function to load more data |
|
|
| `highlightDocumentIds` | `string[]` | IDs of documents to highlight |
|
|
|
|
Console mode uses the supplied theme colors for its surface, 16px dot grid, document icons, and node fills and strokes. Consumer mode keeps its transparent surface and cluster colors.
|
|
|
|
Set `colors.dotColor` or the `--graph-dot` CSS variable to style the dot grid independently of text. When neither is set, the grid uses `textMuted`.
|
|
|
|
Document-to-memory links use `colors.edgeDocument` or `--graph-edge-document`, while derived-memory relations use `colors.edgeDerives` or `--graph-edge-derives`.
|
|
|
|
For paginated initial loading, pass `hasMore` and `isLoadingMore` alongside `documents`. In both variants, new batches gradually warm the force layout from the existing node positions. Initial and appended nodes relax until their movement stays low, then cool automatically; a tick limit bounds settling for layouts that keep drifting. The initial view smoothly follows the changing bounds until loading and settling finish. Manual interaction immediately cancels automatic camera movement. Clicking a node selects it without restarting the forces; dragging warms the layout until release, including release outside the canvas. Changing the document selection starts a new fit; the Fit control remains available at any time. The existing static layout safeguard for more than 6,000 nodes remains in place.
|
|
|
|
## Documentation
|
|
|
|
Full documentation available at [docs.supermemory.ai](https://docs.supermemory.ai):
|
|
|
|
- [Overview](https://docs.supermemory.ai/memory-graph/overview) - What it is and when to use it
|
|
- [Installation](https://docs.supermemory.ai/memory-graph/installation) - Setup and requirements
|
|
- [Quick Start](https://docs.supermemory.ai/memory-graph/quickstart) - Get running in 2 minutes
|
|
- [API Reference](https://docs.supermemory.ai/memory-graph/api-reference) - Complete API documentation
|
|
- [Examples](https://docs.supermemory.ai/memory-graph/examples) - Common use cases
|
|
- [Troubleshooting](https://docs.supermemory.ai/memory-graph/troubleshooting) - Common issues
|
|
|
|
## Requirements
|
|
|
|
- React 18+
|
|
- Modern browser
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Links
|
|
|
|
- [GitHub](https://github.com/supermemoryai/supermemory/tree/main/packages/memory-graph)
|
|
- [Issues](https://github.com/supermemoryai/supermemory/issues)
|
|
- [Supermemory](https://supermemory.ai)
|