# FlowTether — Complete Documentation

> FlowTether is a sovereign Personal Knowledge Management (PKM) system designed for unfinished thinking. It captures fragments — ideas, notes, decisions, conversations — and connects them over time using semantic search, AI chat, and spatial visualization.

## Table of Contents
- [What is FlowTether?](#what-is-flowtether)
- [Core Concepts](#core-concepts)
- [Features](#features)
- [Import Sources](#import-sources)
- [AI Capabilities](#ai-capabilities)
- [Developer Integration](#developer-integration)
- [MCP Server](#mcp-server)
- [API Reference](#api-reference)
- [Privacy & Security](#privacy--security)
- [Pricing](#pricing)

---

## What is FlowTether?

Your ideas don't arrive in order. Your tools shouldn't demand they do.

FlowTether is a knowledge management system built for how people actually think — in fragments, across sources, over time. Most tools demand structure upfront: folders, databases, hierarchies. FlowTether lets you capture first and organize later, using AI to find the connections you missed.

### The Problem FlowTether Solves
- Ideas are scattered across chat logs, note apps, documents, and your memory
- Conversations with AI assistants generate insights that vanish when the session ends
- Traditional note-taking apps demand organization before you're ready to organize
- Knowledge connections form weeks after the original thought — current tools can't handle that

### Who FlowTether is For
- **Researchers**: Synthesize findings across papers, interviews, and field notes
- **Founders**: Track evolving product thinking, investor conversations, and strategic pivots
- **Strategists**: Connect market signals, competitive intelligence, and emerging patterns
- **Writers**: Capture fragments and watch themes emerge across notebooks
- **Developers**: Document architectural decisions, debug logs, and technical knowledge

---

## Core Concepts

FlowTether uses a nautical metaphor to organize knowledge:

### Pearl
An atomic knowledge unit. A Pearl can be a full document, a quick note, a decision record, a conversation extract, or any piece of knowledge worth keeping. Pearls support rich text editing (ProseMirror-based), metadata fields, tags, and file attachments.

### Buoy
A topic cluster that groups related Pearls. Buoys provide lightweight organization without rigid folder hierarchies. A Pearl can belong to multiple Buoys.

### Net
A visual canvas workspace. Nets let you arrange Pearls and Buoys spatially for brainstorming, project planning, or visual thinking.

### Harbor
A sovereignty boundary — a fully isolated workspace with its own permissions, AI settings, and data scope. Think of it as a separate knowledge universe. You might have a "Work" Harbor and a "Personal" Harbor that never mix.

### Strand
A typed relationship between any two knowledge items. Strand types include: related_to, builds_on, contradicts, supersedes, contains, references, and custom types. Strands create a knowledge graph that grows over time.

### SlipStream
An AI chat conversation that has full context of your knowledge. SlipStream uses Retrieval-Augmented Generation (RAG) to search your Pearls when answering questions, cite sources, and create new Pearls from conversation insights.

### Lumi
The AI librarian. Lumi performs intelligent search across your knowledge, suggests connections between Pearls, and helps surface forgotten context. Lumi runs on a local LLM for privacy — your queries never leave the server.

### The Map
A spatial visualization of your entire knowledge graph. Pearls appear as nodes, Strands as edges. You can zoom, filter by source or date, and discover clusters of related knowledge you didn't know existed.

---

## Features

### Capture
- **QuickCapture**: Fast entry with automatic routing — Lumi classifies your input and suggests where it belongs
- **Voice Capture**: Record audio notes, automatically transcribed via Whisper and stored as Pearls
- **Rich Editor**: Full ProseMirror-based editor with markdown support, tables, code blocks, images, and embeds
- **Forms**: Structured data capture with custom templates
- **Chat-to-Pearl**: Extract key insights from SlipStream conversations and save them as standalone Pearls

### Organize
- **Pearls, Buoys, Nets**: Three levels of organization from atomic to spatial
- **Harbor Isolation**: Separate workspaces with independent permissions and AI settings
- **Auto-Linking**: AI suggests connections between new and existing Pearls based on semantic similarity
- **Tags**: Flexible tagging system with tag-based filtering across all views
- **Table View**: Spreadsheet-like view for bulk Pearl management
- **Landmarks**: Pin important Pearls for quick access

### Think
- **SlipStream AI Chat**: RAG-powered conversations that cite your own knowledge
- **The Map**: Spatial knowledge graph visualization
- **Lumi Librarian**: AI-powered semantic search and connection discovery
- **Manifest**: Long-form document assembly from multiple Pearls (3-pane editor)
- **Morning Gifts**: Daily AI-curated selections of relevant forgotten knowledge
- **Tides (Calendar)**: Time-based views with Kanban and Gantt support
- **Focus Timer**: Pomodoro-style timer integrated into the workspace

### Search
- **Semantic Search**: Vector-based meaning search powered by Qwen3-Embedding (1024-dim)
- **Full-Text Search**: PostgreSQL FTS for exact term matching
- **Hybrid Search**: Combined semantic + full-text with intelligent ranking
- **Cross-Source Search**: Search across all import sources simultaneously
- **Search Suggestions**: Real-time suggestions as you type

### Share & Export
- **Share Links**: Public or unlisted sharing of individual Pearls with optional expiry
- **Full Export**: Download all your data in standard formats
- **Manifest Export**: Export assembled documents as PDF or markdown

### Experience
- **7 Themes**: Visual customization including dark mode
- **10 Languages**: English, German, Dutch, French, Spanish, Italian, Portuguese, Japanese, Korean, Chinese
- **Accessibility**: WCAG-compliant interface design
- **Self-Hostable**: Docker-based deployment for full sovereignty

---

## Import Sources

FlowTether imports from 12+ sources, preserving metadata, timestamps, and structure:

| Source | What's Imported | Structure |
|--------|----------------|-----------|
| ChatGPT | Full conversation history (JSON export) | Sessions become SlipStreams, messages become turns |
| Claude | Conversation exports | Sessions and turns preserved |
| Evernote | Notebooks (.enex files) | Each notebook becomes a Buoy, notes become Pearls, attachments stored |
| Confluence | Spaces (HTML export) | Pages become Pearls, spaces become Buoys, cross-links preserved |
| Notion | Workspace exports | Pages become Pearls with metadata |
| Obsidian | Vault exports | Notes become Pearls, wiki-links become Strands |
| Roam Research | JSON exports | Pages and blocks imported with relationships |
| PDF Documents | Full text extraction with OCR | Each document becomes a Pearl |
| DOCX/Word | Rich text preserved | Documents become Pearls |
| Excel/CSV | Structured data import | Rows become Pearls with metadata fields |
| Voice/Audio | Whisper transcription | Audio stored, transcription becomes Pearl content |
| FT Ingest (API) | Programmatic bulk import | For developers and automation pipelines |

---

## AI Capabilities

### Local AI (Privacy-Preserving)
- **Embedding Model**: Qwen3-Embedding-0.6B via Ollama (1024-dimension vectors)
- **Librarian (Lumi)**: Qwen3:4b local LLM for search, suggestions, and classification
- All local AI runs on the FlowTether server — queries never leave the infrastructure

### Managed AI (Optional)
- **SlipStream Chat**: Anthropic Claude API for extended conversations with RAG context
- User explicitly opts into managed AI per Harbor via AI settings
- Conversations use retrieval-augmented generation to cite user's own Pearls

### The Membrane
FlowTether's AI security layer that controls what data flows to AI models:
- Harbor-level AI access toggles (on/off per Harbor)
- Sealed content excluded from all AI operations
- Secret scanning quarantines credentials found in imported content
- No user content is used for AI model training — ever

---

## Developer Integration

### API Keys
- Format: `ft_live_` prefix followed by a secure random string
- Scoped to specific Harbors
- Rate limited per endpoint (5-300 requests/minute)
- Manage keys at: Settings > API Keys in the FlowTether app

### API Overview
- **Base URL**: `https://app.flowtether.ai/api/`
- **Auth Header**: `Authorization: Bearer ft_live_your_key_here`
- **Harbor Header**: `X-Harbor-ID: your-harbor-uuid` (required on most endpoints)
- **Response Format**: `{ "success": true, "data": { ... } }` or `{ "success": false, "error": "ERR_CODE", "message": "Human readable" }`

### Key Endpoints
| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/containers/` | List Pearls, Buoys, or Nets |
| POST | `/api/containers/` | Create a new container |
| GET | `/api/containers/{id}` | Get container with content |
| PUT | `/api/containers/{id}` | Update container |
| GET | `/api/search/` | Hybrid semantic + full-text search |
| POST | `/api/slipstream/sessions` | Create AI chat session |
| GET | `/api/media/serve/{id}` | Serve media files |
| GET | `/api/mcp/harbors` | List harbors (MCP) |
| POST | `/api/mcp/create_pearl` | Create Pearl via MCP |
| POST | `/api/mcp/bulk_ingest` | Batch import (max 100 pearls) |

---

## MCP Server

FlowTether provides a Model Context Protocol (MCP) server that allows AI agents to read from and write to your knowledge base.

### Installation
```bash
pip install mcp httpx python-dotenv
```

Download the server script from: `https://app.flowtether.ai/api/mcp/server/download`

### Configuration
Set environment variables:
```
FLOWTETHER_API_KEY=ft_live_your_key_here
FLOWTETHER_BASE_URL=https://app.flowtether.ai
```

### Available MCP Tools

| Tool | Purpose |
|------|---------|
| `get_instructions` | Returns organization guide, best practices, and accessible harbors. Call this first. |
| `search` | Semantic search across your Pearls. Returns titles, summaries, and relevance scores. |
| `save_pearl` | Create a single Pearl with title, content, summary, tags, and pearl_type. |
| `get_pearl` | Retrieve the full content of a Pearl by its ID. |
| `list_harbors` | List all Harbors accessible to the API key. |
| `list_buoys` | List Buoys (topic clusters) in a Harbor with pearl counts. |
| `bulk_save` | Save multiple Pearls at once (batch create). |

### Pearl Types
When saving Pearls via MCP, use `pearl_type` to classify:
- `insight` — Realizations and discoveries
- `decision` — Choices made (include WHY in content)
- `question` — Unresolved items to investigate
- `idea` — Concepts to explore
- `reference` — External documentation or links
- `note` — General knowledge capture

### Security
- API keys are scoped to specific Harbors
- Sealed content is excluded from all MCP reads
- Secret scanning quarantines credentials found in ingested content
- Duplicate detection (exact + semantic at 0.90 threshold) prevents redundant saves

---

## API Reference

### Authentication
Two methods:
1. **JWT** (browser sessions): Access + refresh tokens via `/api/auth/login`
2. **API Keys** (external tools): `ft_live_` prefixed keys in Authorization header

### Rate Limits
- Auth endpoints: 5-10/minute
- Search: 60/minute
- Data operations: 120-300/minute
- MCP bulk ingest: 10/minute

### Pagination
List endpoints support `page` and `page_size` query parameters. Default page size is 20.

### Error Codes
Standard HTTP status codes with custom error codes:
- `INSUFFICIENT_PEARLS` — Not enough content for the requested operation
- `HARBOR_NOT_FOUND` — Invalid harbor ID or no access
- `RATE_LIMITED` — Too many requests
- `SEALED_CONTENT` — Attempted access to sealed content via AI

---

## Privacy & Security

### Data Hosting
- **Location**: Hetzner data center, Germany (EU)
- **Jurisdiction**: European Union data protection laws (GDPR)
- **No US cloud providers** for primary data storage

### What FlowTether Collects
- Account information (email, display name)
- Content you create or import (Pearls, Buoys, conversations)
- Usage logs for error tracking and service improvement

### What FlowTether Does NOT Do
- No selling of user data to third parties
- No third-party analytics or tracking scripts
- No advertising or ad-based monetization
- No AI model training on user content
- No cross-Harbor data leakage

### Harbor Isolation
Each Harbor is a fully isolated workspace:
- Queries always filter by user_id AND harbor_id
- Row-Level Security (RLS) enforced at the database layer
- API keys scoped to specific Harbors
- AI access configurable per Harbor

### Content Ownership
Users own all content they create or import. Full data export is available at any time. Account deletion removes all data permanently.

---

## Pricing

FlowTether offers a free tier and a Pro subscription:
- **Free**: Core features with storage and usage limits
- **Pro**: Full feature access, higher limits, priority support
- Beta users have full Pro access during the beta period

For current pricing, visit: https://flowtether.ai

---

## Contact

- **Website**: https://flowtether.ai
- **Contact Form**: https://flowtether.ai/contact
- **Response Time**: 1-2 business days

---

*Last updated: February 2026*
*Content-Signal: ai-train=no, search=yes, ai-input=yes*