NoteFast

AI-first knowledge base — block-level API + MCP, AI writes and understands, humans read.

NoteFast is a single-user, self-hosted knowledge base where Markdown is the surface and SQLite is the source of truth. Its core is a block tree model with full-text search, semantic retrieval, RAG chat, and AI-assisted writing — all exposed through REST and MCP.

Quick Start

# Local development
bun install
bun --filter @notefast/server dev     # API + MCP on :3140
bun --filter @notefast/web dev        # Web UI on :5173

# Docker
docker compose up -d

Set a password for the Web UI and an API token for MCP access:

export AUTH_PASSWORD=your-password
export API_TOKEN=nf_your-secret-token

Optionally configure an AI provider to unlock search, chat, and writing:

export AI_PROVIDER=openai         # or: deepseek, siliconflow, ollama, etc.
export AI_API_KEY=sk-...
export EMBEDDING_PROVIDER=openai
export EMBEDDING_API_KEY=sk-...

AI settings can also be managed at runtime through the Web UI (/settings).

Architecture

notefast/
├── packages/
│   ├── core/          # Shared types, block model, markdown↔block, AI config
│   ├── server/        # REST API (Hono), MCP Server, AI engine
│   └── web/           # React reading/writing UI

Data Model

Everything is a block — a tree node with type and inline Markdown content:

document
├── heading "Architecture"
├── paragraph "NoteFast uses a block tree model..."
├── code "const x = 1"
└── list
    ├── list_item "Point one"
    └── list_item "Point two"

Blocks are the atomic unit. No raw file manipulation — all operations go through the block API.

Storage

• SQLite single-file database in data/ — schema migrations, FTS5 search, block tree CRUD
• sqlite-vec extension for vector search (production) with JSON fallback
• Content-addressed media in data/media/<sha256> — deduplicated images, stable asset:<sha256> references in Markdown
• AI configuration persists to data/ai.config.json with masked API keys in public views

AI Capabilities

All AI features require an LLM provider (OpenAI-compatible API). 18 presets available: OpenAI, DeepSeek, Gemini, Ollama, SiliconFlow, etc.

Capability	What it does
Hybrid Search	FTS5 + semantic embedding with RRF fusion, optional reranker
RAG Chat	Conversational AI with note citations, agent loop, tool calling
AI Writing	Ctrl+Enter inline continuation, refine, translate, summarise
AutoLink	After each write, the LLM extracts key concepts; high-confidence semantic matches automatically create inter-note links (ref_type=ai_auto) — no manual review
Web Search	Optional Brave Search integration for external knowledge
Title/Suggest	AI-generated document titles and summaries
MCP Server	Full read/write/search/chat tools for external AI agents

MCP Integration

External AI agents (Claude Desktop, Cursor, etc.) connect to NoteFast via MCP:

{
  "mcpServers": {
    "notefast": {
      "url": "http://localhost:3140/mcp",
      "headers": { "Authorization": "Bearer nf_your-secret-token" }
    }
  }
}

Available tools: search, get_doc, get_block, create_doc, create_block, update_block, semantic_search, chat, list_docs, set_doc_tags, autolink_run, and more.

Keyboard Shortcuts

Key	Action
⌘K	Command palette
⌘J	AI chat panel
⌘Enter	AI continue writing
⌘N	New document
⌘S	Save (in editor)
⌘P	Preview / Edit (in editor)
⌘B / I / E	Bold / Italic / Inline code
⌘⇧K	Insert link

Environment Variables

Variable	Description
AUTH_PASSWORD	Web UI login password
API_TOKEN	API / MCP Bearer token
PORT	Server port (default 3140)
DATA_DIR	SQLite + media storage path
AI_PROVIDER	LLM provider preset ID
AI_API_KEY	LLM API key
EMBEDDING_PROVIDER	Embedding provider preset ID
EMBEDDING_API_KEY	Embedding API key

Quality

bun lint        # oxlint, zero tolerance for correctness violations
bun run typecheck   # strict TypeScript across all packages
bun test        # 350+ tests across 33 suites

License

MIT — see LICENSE.