dotstell

---

What is Dotstell?

Dotstell is an open source personal knowledge graph — a single place to write notes, track people, manage tasks, save bookmarks, and connect all of them together through a visual graph. With a built-in AI layer that understands your entire knowledge base.

Most productivity tools are built around capture. Dotstell is built around connection — and now, conversation.

Capture your ideas, meeting notes, and research. Connect them to people, tasks, and bookmarks — building a knowledge graph that grows with you. Ask an AI that answers from your own notes, not the internet — chat, get person intelligence, generate writing, and discover what you already know.

Everything you write, everyone you know, everything you do — all linked in one living knowledge graph. Now with AI that understands all of it.

The question it answers that other tools don't:

"What do I know about this person, this project, this decision — right now, in full context?"

---

Support the project

Dotstell is free, self-hostable, and built in the open. If it saves you time or you believe in what we're building:

• Star the repo — the single most useful thing you can do. It helps others find Dotstell and tells us the work is worthwhile.
• Open an issue — bug reports and feature requests shape what gets built next.
• Contribute code — all skill levels welcome; see the contributing guide.
• Share it — tell someone who needs a better way to organise their work.

Every star, issue, and PR genuinely matters for an early-stage OSS project.

---

Features

Capture

	Feature	Description
📑	Rich Text Notes	Slash commands, tables, code blocks, checklists, images, a table of contents and PDF export; sub-notes, note tabs, colour labels, pinning and drag-to-reorder
📓	Notebooks	Organise notes into named, colour-coded collections; deleted notes stay in the Trash for 30 days
🎙️	Meetings	Paste or upload a Zoom, Teams or Meet transcript (.vtt, .srt, .txt) or your rough notes and get a summary, decisions, action items and open questions; action items become linked tasks. Record a meeting too — see docs/MEETINGS.md
🗣️	Voice dictation	Speak into any note in 12 languages. Fast uses your browser, with spoken punctuation ("comma", "question mark", "new line") and automatic capitals; High accuracy uses Whisper-class models with your own OpenAI, Groq or Gemini key. Words appear as you speak, on a draggable bar that works on a phone
🔖	Smart Bookmarks	Save any URL — title, description and favicon fetched automatically; bulk import from Chrome, Firefox or Safari
✅	Tasks & Priorities	Kanban board and list view with priorities, due dates and times, reminders and overdue alerts
👥	People & 1-on-1s	Track contacts, attach notes, tasks and context directly to people; @mention them in notes

Connect

	Feature	Description
⬡	Wikilinks & Backlinks	Type [[ in any note to link it to another; backlinks and unlinked mentions update automatically
🔗	Manual Linking	Connect any entity to any other — note → person, bookmark → task, and so on
🌐	Knowledge Graph	A visual map of everything; wikilinks and manual connections appear as live edges, with AI-found missing links and clusters
🔍	Universal Search	Ctrl+K command palette across notes, people, tasks and bookmarks, and semantic search by meaning
🏠	Dashboard	Overdue alerts, task progress, recent notes and bookmarks, knowledge health and an AI digest

Ask

	Feature	Description
✨	AI Chat, Write & Assist	Chat grounded in your notes, bookmarks and tasks; draft from templates or improve existing text; inline rewrite, expand and fix; smart titles, auto-tags, summaries, related notes and Person Intelligence. Works with Ollama (local and private), OpenAI, Anthropic, Gemini or Groq
🔌	Connect AI tools (MCP server)	Let Codex, Claude Code, Cursor and Claude Desktop search and read your notes, bookmarks, tasks, people and meetings with a revocable, read-only token — see docs/MCP.md

Yours to keep

	Feature	Description
📤	Export & No Lock-in	One click exports everything as a zip: Markdown notes with wikilinks and front matter (opens in Obsidian), people, tasks (Markdown and CSV), browser-importable bookmarks, and a lossless JSON backup — see docs/EXPORT.md
📥	Import	Bring in Markdown (Obsidian, Notion, Bear, Joplin, Logseq), Evernote (.enex), Google Keep (Takeout) and contacts (.vcf, .csv); notebooks, tags, dates and [[wikilinks]] are kept. Preview first, one-click undo — see docs/IMPORT.md
🖥️	Web, desktop and phone	Use it in the browser, as a ~10 MB desktop app for Windows, macOS and Linux, or on a phone or tablet; 12 themes
🏠	Self-hostable	Your own Supabase project and any Node.js host — see docs/DEPLOYMENT.md

---

Screenshots

Live previews of the app are available on dotstell.com — the landing page includes an interactive knowledge graph, dashboard mockup, and feature walkthroughs.

Try the live app at dotstell.app or download the desktop build for Windows, macOS and Linux.

---

Getting Started

Prerequisites

• Node.js 20.9+
• pnpm — npm install -g pnpm

  We use pnpm instead of npm/yarn because it is significantly faster (hard-linked global store, no re-downloading the same package twice), produces a deterministic pnpm-lock.yaml, and is required by the Tauri CLI toolchain used for the desktop build. The lockfile is committed — always use pnpm install, not npm install, to keep the lockfile consistent.

• A free Supabase account

1. Clone

git clone https://github.com/dotstell/dotstell.git
cd dotstell

2. Install dependencies

pnpm install

3. Set up Supabase

1. Create a new project at supabase.com

2. Go to SQL Editor and run supabase/schema.sql to create all tables, policies, and triggers.

   That one file is all a new project needs. For an existing database, apply any migrations you have not run yet, in order:

supabase/migrations/
├── add_notebooks_table.sql
├── add_notes_soft_delete.sql
├── 002_bookmarks_enhancements.sql
├── 003_bookmark_visits.sql
├── 004_notes_parent.sql
├── 005_notes_sort_pin.sql
├── 006_notes_color.sql
├── 007_notebooks_constraints.sql
├── 008_ai_embeddings.sql          ← vector(768) columns on notes + bookmarks (AI semantic search)
├── 009_ai_match_functions.sql     ← pgvector cosine similarity RPC functions
├── 010_tasks_embedding.sql        ← vector(768) column on tasks + match_tasks() (tasks in AI Chat RAG)
├── 011_fix_function_search_paths.sql
└── 012_mcp.sql                    ← MCP tokens and the read-only functions behind the MCP server

3. Copy your project URL and anon key from Settings → API

4. Configure environment

cp .env.local.example .env.local

Edit .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Behind a corporate SSL proxy? Add NODE_TLS_REJECT_UNAUTHORIZED=0 to your .env.local. Do not set this in production.

5. Run

pnpm dev

Open http://localhost:3000, create an account and start connecting your knowledge.

---

AI Features

Dotstell ships a complete AI layer. All features work with five provider options:

Provider	Chat	Embeddings	Notes
Ollama (local)	✅	✅	Free, private, runs on your machine
OpenAI	✅	✅	GPT-4o, text-embedding-3-small
Anthropic	✅	—	Claude models; use a separate embedding provider
Google Gemini	✅	✅	Generous free tier
Groq	✅	—	Extremely fast inference; use a separate embedding provider

AI features:

• Meeting assistant — paste or upload a Zoom, Teams or Meet transcript (or record the meeting) and get a summary, decisions and action items; turn action items into linked tasks
• Voice dictation — Fast (your browser, with spoken punctuation and automatic capitals, English) or High accuracy (your own OpenAI, Groq or Gemini speech key, with punctuation and capitals from the model); both work on phones
• Connect AI tools (MCP server) — let Codex, Claude Code, Cursor and Claude Desktop read your notes, bookmarks, tasks, people and meetings with a revocable, read-only token (see docs/MCP.md)
• AI Writing Assistant — draft notes from scratch using 8 starter templates (Outline, Meeting notes, Daily log, Research note, OoO email, Proposal, Status update, Email draft) or a custom prompt; improve existing notes with one-click actions (Improve English, Make formal, Make concise, Expand, Full rewrite)
• AI Chat — slide-out panel with RAG (semantic search grounds answers in your notes, bookmarks, and tasks), "This note" and "All knowledge" modes, People tab for person intelligence
• Inline Assist — select text → rewrite / expand / shorten / fix grammar / outline / checklist / explain
• Smart title & auto-tags — suggest a title and up to 5 relevant tags as you write
• Note & bookmark summaries — one-click summary in bullet or paragraph form
• AI Knowledge Digest — dashboard panel summarising your latest notes activity
• Semantic Related Notes — sidebar panel showing notes similar to the one you're reading
• Person Intelligence — searches all your notes and bookmarks for mentions of a person and generates a structured brief
• Graph intelligence — finds missing links, note clusters, and bridgeable gaps in your knowledge graph

API keys are stored only in your browser's localStorage. dotstell's servers never store or log them: a request that goes through a dotstell API route carries the key for that one request and passes it to your chosen AI provider over TLS. Speech-to-text (recording and High accuracy dictation) goes straight from your browser to the provider.

Using Ollama with the live app — Local AI Agent

The hosted app at dotstell.app runs over https://. Modern browsers block https:// pages from fetching http://localhost directly (Private Network Access spec). To use Ollama with the live app, run the Dotstell Local AI Agent — a tiny zero-dependency Node.js proxy that adds the required browser security headers.

Follow these steps in order:

Step 1 — Install and start Ollama

Download Ollama from ollama.com if you haven't already, then make sure it is running:

• Windows: Ollama usually auto-starts as a background service. Open http://127.0.0.1:11434 in your browser — if it shows "Ollama is running" you're ready. If not, find Ollama in the Start Menu and launch it, or run ollama serve in a terminal.
• macOS / Linux: Run ollama serve if it isn't already running in the background.

Windows tip: If ollama serve returns bind: Only one usage of each socket address, Ollama is already running — skip this step entirely.

Step 2 — Pull a model (first time only)

Dotstell needs two model types — one for chat/writing and one for semantic search (RAG). Pull one from each column:

Purpose	Model	Size	Notes
Chat	gemma4:e4b	~4B	Fastest and most accurate in dotstell's meeting tests; fits an 8 GB graphics card — recommended
Chat	qwen3.5:4b	4B	Equally accurate, a little slower
Chat	phi4-mini	3.8B	Small and fast on CPU
Chat	qwen2.5:3b	3B	Strong and multilingual
Chat	llama3.2	3B	Reliable all-rounder
Chat	deepseek-r1:7b	7B	Best reasoning quality — needs a GPU
Chat	qwen2.5:7b	7B	Excellent quality + multilingual — needs a GPU
Embeddings	nomic-embed-text	—	Required for semantic search, Related Notes, and task-aware AI Chat

ollama pull gemma4:e4b
ollama pull nomic-embed-text

Models that think (Qwen 3.5, Gemma 4 and similar) work: dotstell turns the thinking off so replies are quick. You can allow it with Let the model think before answering under the model picker in AI Settings; expect much slower replies.

No GPU? Stick to 3–4B models (phi4-mini, qwen2.5:3b, llama3.2). 7B models are slow on CPU alone.

Step 3 — Start the Dotstell Local AI Agent

You do not need to clone this repo. Run directly via npx (Node.js 18+ required):

npx @dotstell/agent

Keep this terminal window open while you use Ollama in dotstell. The agent runs on http://127.0.0.1:12345 and is loopback-only — not reachable from outside your machine.

Step 4 — Open dotstell.app → AI Settings → choose Ollama (Local)

The settings modal shows a green "Local Agent is running" badge when the agent is detected. All AI features — Chat, Writing Assistant, Inline Assist, Summaries, Person Intelligence, AI Digest — route through the agent automatically.

---

Alternative ways to run the agent:

# Download the single file directly (no npm):
curl -o dotstell-agent.mjs https://raw.githubusercontent.com/dotstell/dotstell/main/packages/agent/index.mjs
node dotstell-agent.mjs

# If you already have the repo cloned:
node packages/agent/index.mjs

See packages/agent/README.md for environment variables, troubleshooting, and security details.

You do not need the agent when running dotstell locally (localhost:3000). PNA restrictions only apply when accessing the live https://dotstell.app.

---

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, React 19)
Language	TypeScript 5 · Rust (desktop shell)
Styling	Tailwind CSS v4
Database	Supabase (PostgreSQL 17.6 + Row Level Security)
Auth	Supabase Auth (JWT)
Rich Text Editor	Tiptap v3
Graph Visualisation	React Flow v11
Desktop	Tauri v2 (native WebView wrapper, ~10 MB installer)
Icons	Lucide React

See docs/ARCHITECTURE.md for a full breakdown of the system design, data model, security model, and key design decisions.

---

Project Structure

The full annotated directory tree is in docs/ARCHITECTURE.md.

Directory	Purpose
src/app/	Next.js App Router pages and API routes (auth, notes, AI, bookmarks, tasks…)
src/components/	React UI components grouped by domain (ai/, editor/, graph/, layout/…)
src/hooks/	Data-fetching and behaviour hooks
src/lib/	AI client, Supabase clients, rate limiter, TipTap extensions; meetings/ (transcripts and digests), voice/ (dictation and speech-to-text), mcp/ (MCP server), import and export
src-tauri/	Rust / Tauri v2 desktop shell
supabase/	Schema SQL and incremental migrations
packages/agent/	Dotstell Local AI Agent — zero-dep Node.js Ollama proxy

---

Roadmap

Feature	Status
Notes, People, Tasks, Bookmarks	✅ Live
Wikilinks + Backlinks	✅ Live
Knowledge Graph	✅ Live
Desktop app (Windows, macOS + Linux)	✅ Live
AI layer — Chat, Assist, Semantic Search, Person Intelligence, Summaries, Digest	✅ Live (v0.4.0)
Local AI via Ollama — works from both live app and local dev	✅ Live (v0.4.0)
AI Writing Assistant — draft from scratch (8 templates) + improve existing content	✅ Live (v0.5.0)
Import (Markdown, Evernote, Google Keep, contacts) and full Export	✅ Live (v0.7.0)
Meetings — transcript summary, decisions and action items, dictation, recording	✅ Live (v0.8.0)
MCP server — AI tools read your knowledge, read-only, with revocable tokens	✅ Live (v0.9.0)
Dictation: phone-friendly bar, High accuracy engine, spoken punctuation and capitals	✅ Live (v0.9.1)
MCP Registry listing (com.dotstell/dotstell)	✅ Listed (v0.9.1)
Browser extension — save pages and clip to dotstell	🔜 Next (v0.10.0)
Docs (per-project documentation)	🔜 Soon
Integrations (Slack, Teams, etc.)	🔜 Planned
Mobile app	🔜 Planned

---

Contributing

Contributions are welcome and genuinely appreciated.

• Bug reports & feature requests — open an issue
• Code contributions — please open an issue first for anything significant so we can align on approach
• Docs, design, tests — always welcome without prior discussion

See CONTRIBUTING.md for full guidelines.

---

Self-Hosting

Dotstell is designed to be self-hostable. You need:

• A Node.js server (or Vercel / any Next.js host)
• A Supabase project (or self-hosted Supabase)

The full guide — database, environment, Supabase auth settings, running it, and what each feature needs — is in docs/DEPLOYMENT.md.

---

License

GNU Affero General Public License v3.0 — AGPL-3.0

This means you can use, modify and distribute Dotstell freely, including self-hosting it. If you run a modified version as a network service, you must make the modified source available to users of that service.

© 2026 Dotstell