Hulunote

An open-source outliner note application for networked thinking, deeply integrated with AI and MCP protocol, featuring bidirectional links and knowledge graph visualization.

Positioning#

Hulunote is an open-source outliner note tool built on the concept of "AI + Note Hippocampus," inspired by Roam Research, positioned as an open-source alternative supporting infinite-level outliner nesting, bidirectional links, and interactive knowledge graphs.

Core Features#

Outliner & Editing#

Infinite-level bullet lists with drag-and-drop and node zoom
Daily notes with auto-generated date-based journal pages
Multiple isolated database workspaces, each with an independent knowledge universe

Knowledge Network#

[[wiki-style links]] bidirectional link syntax with automatic backlinks
Interactive force-directed knowledge graph with zoom, pan, and click navigation

AI Capabilities#

Built-in MCP client for direct in-app connection to AI models and MCP servers
AI note generation: automatically create complete notes with hierarchical outlines and bidirectional links from a topic description
Cross-database AI search: find and correlate related ideas across all databases
AI-generated Mermaid charts (flowcharts, sequence diagrams, mind maps, Gantt charts, etc.)

External Integration#

MCP Server: exposes tool sets for database browsing, note CRUD, outline node management for Claude Desktop and other MCP clients
OpenClaw plugin: AI Agents can autonomously browse, create, and organize knowledge bases

Architecture Overview#

Frontend#

Languages: ClojureScript (74.1%), JavaScript (13.1%), CSS (11.4%)
State Management: DataScript (in-memory Datalog database for ClojureScript), enabling real-time queries and reactive updates
UI Rendering: Rum (ClojureScript React alternative)
Build: Shadow-cljs

Backend#

Framework: Axum 0.7 (Rust) + SQLx ORM
Authentication: JWT (jsonwebtoken), bcrypt password hashing, default token expiry 720 hours
API Style: RESTful, JSON fields use kebab-case
Performance Claims: Migration from original Clojure to Rust — 5-10x lower memory usage, 10-20x faster startup, 2-5x lower request latency
Compatibility: Rust backend fully compatible with original Clojure backend
Database: PostgreSQL (12+)

Data Model#

Outline Nodes (Navigation Nodes): Note content consists of hierarchical navigation nodes supporting infinite nesting
Multiple Databases: Top-level isolation units, each containing independent note sets and knowledge graphs

MCP Integration Architecture#

Standalone Python process as MCP Server, operating notes via Hulunote REST API
Authentication: JWT Token passed via HULUNOTE_API_TOKEN environment variable

Backend API Endpoints#

Category	Endpoint Examples	Auth Required
Login	`POST /login/web-login`	No
Registration	`POST /login/web-signup`	No
Database Management	`POST /hulunote/new-database`, `get-database-list`, `update-database`	Yes
Note Management	`POST /hulunote/new-note`, `get-note-list`, `get-all-note-list`, `update-hulunote-note`	Yes
Outline Navigation	`POST /hulunote/create-or-update-nav`, `get-note-navs`, `get-all-nav-by-page`, `get-all-navs`	Yes

Deployment & Configuration#

Prerequisites#

PostgreSQL (12+), Rust (1.70+), Node.js / Yarn, Java (for ClojureScript / Shadow-cljs compilation)

Deployment Steps#

# 1. Initialize database
createdb hulunote_open
psql -d hulunote_open -f hulunote-rust/init.sql

# 2. Start backend
cd hulunote-rust && cargo run

# 3. Start frontend dev server
cd hulunote && yarn && npx shadow-cljs watch hulunote

# 4. Open http://localhost:6689 in browser

Backend Environment Variables (.env)#

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	Required
`JWT_SECRET`	JWT signing key	`hulunote-secret-key`
`JWT_EXPIRY_HOURS`	Token expiry (hours)	720
`PORT`	Service port	6689
`RUST_LOG`	Log level	`hulunote_server=debug`

MCP Server Configuration (Claude Desktop)#

{
  "mcpServers": {
    "hulunote": {
      "command": "python",
      "args": ["/path/to/hulunote-mcp-server/hulunote_mcp.py"],
      "env": {
        "HULUNOTE_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Multi-Platform Support#

Web, Electron desktop, Android, iOS, Terminal TUI (mobile and TUI repo links not provided in README, feature completeness unconfirmed).

Use Cases#

Research knowledge management: AI automatically reads materials and creates structured notes with bidirectional links
Knowledge summarization: compress long documents into concise outline nodes
Intelligent Q&A: ask questions about notes, AI returns answers with citations
Cross-database knowledge discovery: AI discovers hidden knowledge associations across databases
AI Agent note management: via OpenClaw plugin, AI Agents can autonomously browse, create, and organize knowledge bases
Claude Desktop integration: read and write notes with natural language via MCP Server

Unconfirmed Information#

Android / iOS repo links not publicly available, may still be in development
OpenClaw platform's independent website and documentation not yet verified
v1.1.0 specific changes not detailed in README
Project is in early stage (208 commits), actual production use cases unconfirmed
Original Clojure backend repo link not found
Only source-code build method available, no Docker one-click deployment solution found