add docs for graph package (#603)graph-docs

1 files changed, 44 insertions, 328 deletions

diff --git a/packages/memory-graph/README.md b/packages/memory-graph/README.md
index eae06940..83710f5a 100644
--- a/packages/memory-graph/README.md
+++ b/packages/memory-graph/README.md
@@ -1,378 +1,94 @@
 # @supermemory/memory-graph
 
-> Interactive graph visualization component for Supermemory - visualize and explore your memory connections
+Interactive graph visualization for documents and their memory connections.
 
 [![npm version](https://img.shields.io/npm/v/@supermemory/memory-graph.svg)](https://www.npmjs.com/package/@supermemory/memory-graph)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
-
-- **WebGL-powered rendering** - Smooth performance with hundreds of nodes
-- **Interactive exploration** - Pan, zoom, drag nodes, and explore connections
-- **Semantic connections** - Visualizes relationships based on content similarity
-- **Space filtering with search** - Dynamically search and filter by spaces/tags
-- **Memory limit control** - Limit memories per document (50-3000) for performance
-- **Controlled/uncontrolled modes** - Flexible state management for integration
-- **Responsive design** - Works seamlessly on mobile and desktop
-- **Zero configuration** - Works out of the box with automatic CSS injection
-- **Lightweight** - Tree-shakeable and optimized bundle
-- **TypeScript** - Full TypeScript support with exported types
-
 ## Installation
 
 ```bash
 npm install @supermemory/memory-graph
 # or
-yarn add @supermemory/memory-graph
+bun add @supermemory/memory-graph
 # or
 pnpm add @supermemory/memory-graph
-# or
-bun add @supermemory/memory-graph
 ```
 
 ## Quick Start
 
-The component accepts document data directly - you fetch the data from your backend, which proxies requests to the Supermemory API with proper authentication.
-
 ```tsx
-import { MemoryGraph } from '@supermemory/memory-graph'
-import type { DocumentWithMemories } from '@supermemory/memory-graph'
+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)
-  const [error, setError] = useState<Error | null>(null)
+  const [documents, setDocuments] = useState<DocumentWithMemories[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
 
   useEffect(() => {
-    // Fetch from YOUR backend (which proxies to Supermemory API)
-    fetch('/api/supermemory-graph')
+    fetch('/api/graph')
       .then(res => res.json())
       .then(data => {
-        setDocuments(data.documents)
-        setIsLoading(false)
-      })
-      .catch(err => {
-        setError(err)
-        setIsLoading(false)
-      })
-  }, [])
+        setDocuments(data.documents);
+        setIsLoading(false);
+      });
+  }, []);
 
   return (
-    <MemoryGraph
-      documents={documents}
-      isLoading={isLoading}
-      error={error}
-    />
-  )
-}
-```
-
-## Backend Proxy Example
-
-Create an API route in your backend that authenticates and proxies requests to Supermemory:
-
-### Next.js API Route
-
-```typescript
-// app/api/supermemory-graph/route.ts
-import { NextResponse } from 'next/server'
-
-export async function GET(request: Request) {
-  // Add your own auth check here
-  const user = await getAuthenticatedUser(request)
-  if (!user) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
-
-  const response = await fetch('https://api.supermemory.ai/v3/documents/documents', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
-    },
-    body: JSON.stringify({
-      page: 1,
-      limit: 500,
-      sort: 'createdAt',
-      order: 'desc',
-    }),
-  })
-
-  const data = await response.json()
-  return NextResponse.json(data)
-}
-```
-
-## API Reference
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `documents` | `DocumentWithMemories[]` | **required** | Array of documents to display |
-| `isLoading` | `boolean` | `false` | Whether data is currently loading |
-| `error` | `Error \| null` | `null` | Error that occurred during fetching |
-| `variant` | `"console" \| "consumer"` | `"console"` | Visual variant |
-| `showSpacesSelector` | `boolean` | Based on variant | Show/hide the spaces filter |
-| `children` | `ReactNode` | - | Content to show when no documents |
-| `highlightDocumentIds` | `string[]` | `[]` | Document IDs to highlight |
-| `highlightsVisible` | `boolean` | `true` | Whether highlights are visible |
-
-### Space & Memory Control Props (Optional)
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `selectedSpace` | `string` | `"all"` | Currently selected space (controlled) |
-| `onSpaceChange` | `(spaceId: string) => void` | - | Callback when space changes |
-| `onSearchSpaces` | `(query: string) => Promise<string[]>` | - | Async space search function |
-| `memoryLimit` | `number` | `500` | Max memories per document when space selected |
-| `onMemoryLimitChange` | `(limit: number) => void` | - | Callback when limit changes |
-| `isExperimental` | `boolean` | `false` | Enable experimental features |
-
-### Pagination Props (Optional)
-
-For large datasets, you can implement pagination:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `isLoadingMore` | `boolean` | `false` | Whether loading more data |
-| `hasMore` | `boolean` | `false` | Whether more data is available |
-| `totalLoaded` | `number` | `documents.length` | Total documents loaded |
-| `loadMoreDocuments` | `() => Promise<void>` | - | Callback to load more |
-
-### Types
-
-```typescript
-import type {
-  DocumentWithMemories,
-  MemoryEntry,
-  DocumentsResponse,
-  MemoryGraphProps,
-  MemoryLimit,
-  MemoryCountSelectorProps,
-  GraphNode,
-  GraphEdge,
-  MemoryRelation
-} from '@supermemory/memory-graph'
-
-// Memory limit can be one of these values
-type MemoryLimit = 50 | 100 | 250 | 500 | 1000 | 2000 | 3000
-```
-
-## Advanced Usage
-
-### With Pagination
-
-```tsx
-import { MemoryGraph } from '@supermemory/memory-graph'
-
-function GraphWithPagination() {
-  const [documents, setDocuments] = useState([])
-  const [page, setPage] = useState(1)
-  const [hasMore, setHasMore] = useState(true)
-  const [isLoadingMore, setIsLoadingMore] = useState(false)
-
-  const loadMore = async () => {
-    setIsLoadingMore(true)
-    const res = await fetch(`/api/supermemory-graph?page=${page + 1}`)
-    const data = await res.json()
-    setDocuments(prev => [...prev, ...data.documents])
-    setHasMore(data.pagination.currentPage < data.pagination.totalPages)
-    setPage(p => p + 1)
-    setIsLoadingMore(false)
-  }
-
-  return (
-    <MemoryGraph
-      documents={documents}
-      isLoading={isLoading}
-      isLoadingMore={isLoadingMore}
-      hasMore={hasMore}
-      loadMoreDocuments={loadMore}
-      totalLoaded={documents.length}
-    />
-  )
-}
-```
-
-### Custom Empty State
-
-```tsx
-<MemoryGraph documents={[]} isLoading={false}>
-  <div className="empty-state">
-    <h2>No memories yet</h2>
-    <p>Start adding content to see your knowledge graph</p>
-  </div>
-</MemoryGraph>
-```
-
-### Controlled Space Selection & Memory Limiting
-
-Control the selected space and memory limit externally for integration with your app's state management:
-
-```tsx
-import { MemoryGraph } from '@supermemory/memory-graph'
-
-function ControlledGraph() {
-  const [selectedSpace, setSelectedSpace] = useState("all")
-  const [memoryLimit, setMemoryLimit] = useState(500)
-  const [searchResults, setSearchResults] = useState([])
-
-  // Handle space search via your API
-  const handleSpaceSearch = async (query: string) => {
-    const response = await fetch(`/api/spaces/search?q=${query}`)
-    const spaces = await response.json()
-    setSearchResults(spaces)
-    return spaces
-  }
-
-  return (
-    <div>
-      {/* Display current state */}
-      <div className="controls">
-        <p>Selected Space: {selectedSpace}</p>
-        <p>Memory Limit: {memoryLimit}</p>
-        <button onClick={() => {
-          setSelectedSpace("all")
-          setMemoryLimit(500)
-        }}>
-          Reset Filters
-        </button>
-      </div>
-
-      {/* Controlled graph */}
+    <div style={{ height: '100vh' }}>
       <MemoryGraph
         documents={documents}
-        selectedSpace={selectedSpace}
-        onSpaceChange={setSelectedSpace}
-        onSearchSpaces={handleSpaceSearch}
-        memoryLimit={memoryLimit}
-        onMemoryLimitChange={setMemoryLimit}
+        isLoading={isLoading}
         variant="console"
-        showSpacesSelector={true}
       />
     </div>
-  )
-}
-```
-
-### Uncontrolled Mode (Automatic)
-
-If you don't provide `selectedSpace` or `memoryLimit` props, the component manages its own state:
-
-```tsx
-<MemoryGraph
-  documents={documents}
-  // Component manages space selection and memory limit internally
-  onSearchSpaces={handleSpaceSearch} // Still can provide search function
-  showSpacesSelector={true}
-/>
-```
-
-### Space Search Integration
-
-Implement server-side space search for dynamic filtering:
-
-```tsx
-// Frontend
-const handleSpaceSearch = async (query: string): Promise<string[]> => {
-  const response = await fetch('/api/spaces/search', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ query })
-  })
-  return response.json()
-}
-
-<MemoryGraph
-  documents={documents}
-  onSearchSpaces={handleSpaceSearch}
-  showSpacesSelector={true}
-/>
-
-// Backend (Next.js example)
-// app/api/spaces/search/route.ts
-export async function POST(request: Request) {
-  const { query } = await request.json()
-
-  const response = await fetch('https://api.supermemory.ai/v3/search/spaces', {
-    method: 'GET',
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
-    },
-    params: { q: query }
-  })
-
-  return response.json()
+  );
 }
 ```
 
-### Variants
-
-The `variant` prop controls the visual layout and initial viewport settings:
-
-| Variant | Initial Zoom | Spaces Selector | Legend Position | Use Case |
-|---------|-------------|-----------------|-----------------|----------|
-| `console` | 0.8 | Shown | Bottom-right | Full-page dashboard views |
-| `consumer` | 0.5 | Hidden | Top-right | Embedded/widget views |
+## Features
 
-```tsx
-// Full dashboard view
-<MemoryGraph
-  documents={documents}
-  variant="console"
-/>
+- **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** - Load more documents on demand
+- **TypeScript support** - Full type definitions included
 
-// Embedded widget
-<MemoryGraph
-  documents={documents}
-  variant="consumer"
-/>
-```
+## Essential Props
 
-## Interactive Controls
+| 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 |
 
-- **Pan**: Click and drag the background
-- **Zoom**: Mouse wheel or pinch on mobile
-- **Select Node**: Click on any document or memory
-- **Drag Nodes**: Click and drag individual nodes
-- **Fit to View**: Auto-fit button to center all content
-- **Space Filter**: Click the space selector to filter by space
-- **Space Search**: Type in the search box and press Enter to find spaces
-- **Memory Limit**: Select a limit (50-3K) when filtering by space
+## Documentation
 
-## Browser Support
+Full documentation available at [docs.supermemory.ai](https://docs.supermemory.ai):
 
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
-- Mobile browsers with WebGL support
+- [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 with WebGL support
-
-## Development
-
-```bash
-# Install dependencies
-bun install
-
-# Build the package
-bun run build
-
-# Watch mode for development
-bun run dev
-
-# Type checking
-bun run check-types
-```
+- Modern browser
 
 ## License
 
 MIT
 
-## Support
+## Links
 
-- Issues: [GitHub Issues](https://github.com/supermemoryai/supermemory/issues)
+- [GitHub](https://github.com/supermemoryai/supermemory/tree/main/packages/memory-graph)
+- [Issues](https://github.com/supermemoryai/supermemory/issues)
+- [Supermemory](https://supermemory.ai)