mindflow

mindflow is a mix between traditional mind mapping, rich text editing, and personal knowledge base. Organize ideas spatially, write detailed content within each node, and connect thoughts across different contexts.

Features

Rich Content Organization

• Rich Text Editing - Full-featured editor with Markdown, task lists, code blocks, and formatting
• Multiple Canvases - Separate maps for different projects, topics, or contexts
• Fullscreen Editor - Distraction-free writing mode for deep work

Spatial Thinking

• Auto-Arrange - Automatic hierarchical layout when needed
• Drag & Connect - Build relationships by connecting nodes
• Hierarchies & Networks - Support both tree structures and cross-links

Productivity

• Keyboard-First - Quick shortcuts for creating, navigating, and organizing
• Smart Search - Find content across all maps
• AI Expansion - Optional AI to expand ideas and suggest connections
  • Default - General expansion of ideas
  • Breakdown - Break into subtasks and action items
  • Brainstorm - Generate related ideas and possibilities
  • Socratic - Ask probing questions to deepen thinking

Quick Start

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose
• Anthropic API key (for AI features)

Installation

git clone https://github.com/jamesseeman/mindflow.git
cd mindflow
npm install

Set up Docker services (PostgreSQL + Ollama):

# Start database and Ollama
docker compose up -d

# Enable pgvector extension
docker compose exec db psql -U root -d local -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Pull embedding model
docker compose exec ollama ollama pull nomic-embed-text

Configure environment:

cp .env.example .env.local

Edit .env.local:

DATABASE_URL="postgresql://root:password@localhost:5432/local"
ANTHROPIC_API_KEY="sk-ant-..."

Run migrations and start:

npm run db:migrate
npm run dev

Visit http://localhost:5173 🎉

Switching Embedding Providers

Local (Ollama) - Default:

EMBEDDING_PROVIDER="ollama"
EMBEDDING_API_URL="http://localhost:11434/api/embeddings"
EMBEDDING_MODEL="nomic-embed-text"

Hosted (OpenAI) - For Vercel/production:

EMBEDDING_PROVIDER="openai"
EMBEDDING_API_URL="https://api.openai.com/v1/embeddings"
EMBEDDING_API_KEY="sk-..."
EMBEDDING_MODEL="text-embedding-3-small"

Usage Guide

Keyboard Shortcuts

Shortcut	Action
Ctrl+K or /	Open omnibar (search, create, navigate)
Tab	Create child node (while editing)
Ctrl+Enter	Create sibling node (while editing)
Escape	Exit fullscreen / Close dialogs
/ in editor	Open slash commands menu
/connect	Link to another node

Getting Started

1. Create your first canvas

   • Press Ctrl+K to open the omnibar
   • Type a name and click "Create map"

2. Add your first thought

   • Click "Add node" to create a new card
   • Write your content using the rich text editor
   • Each node can hold as much or as little as you need

3. Build connections

   • Press Tab while writing to create a child node
   • Press Ctrl+Enter to create a sibling node
   • Drag between nodes to create links
   • Use /connect to link to nodes in other maps

4. Organize spatially

   • Drag nodes to position them meaningfully
   • Click "Auto-arrange" for automatic hierarchical layout
   • Use multiple maps to separate different contexts

5. Find anything

   • Press Ctrl+K to search across all your content
   • Results show context and which map they're in
   • Jump between related ideas instantly

Project Structure

src/
├── lib/
│   ├── components/       # Reusable UI components
│   ├── editor/          # TipTap extensions and slash commands
│   ├── server/          # Server-only code (DB, auth, AI)
│   ├── stores/          # Global state
│   ├── utils/           # Helper functions
│   └── types/           # Shared TypeScript types
├── routes/
│   ├── api/            # API endpoints
│   └── +page.svelte    # Main application page
└── hooks.server.ts     # Server hooks (auth integration point)

Roadmap

• Multiple mind maps
• Rich text editing with Markdown
• AI-powered node expansion
• Semantic search
• Auto-arrange layout
• Keyboard shortcuts
• Node context menu
• Deploy to Docker hub
• Text selection actions (extract to nodes, ask AI)
• Recent nodes in omnibar
• AI-powered node placement suggestions
• Connection discovery (related nodes)
• Export (Markdown, JSON, PDF)

Tech Stack

• Framework: SvelteKit (TypeScript)
• Graph Visualization: XYFlow (Svelte Flow)
• Rich Text Editor: TipTap / ProseMirror
• Styling: Tailwind CSS
• Database: PostgreSQL + pgvector
• ORM: Drizzle ORM
• AI: Anthropic Claude API (configurable model)
• Embeddings: Ollama (local) or OpenAI (hosted) - switch via env vars