nowen-note: a self-hosted knowledge base for NAS and Docker

One tree for folders, rich text and Markdown

The project presents itself as more than an editor: an open source, self-hosted knowledge base, daily record and task collaboration workbench, with a unified knowledge tree, a dual rich text and Markdown editor, an offline workspace, AI RAG question answering, daily records, a task centre and multi-device collaboration.

The unifying idea is the tree. Folders, rich text documents and Markdown documents are mixed together in one hierarchy, with documents allowed at the root, unlimited depth, drag and drop sorting, level adjustment, a unified create menu, expand and collapse for everything, filtering and search, count statistics, a recycle bin and shared directories. The layout is a three column view that shows subfolders and the current level scope.

The project description also makes the ownership argument explicitly. The database, the attachments, the index and the backups are all managed by the operator, attachments can go to S3, Cloudflare R2 or MinIO, and backups can be synced to email or WebDAV. Support is claimed for deployment on UGREEN NAS under UGOS and UGOS Pro, and on the Feiniu NAS under fnOS, with the application reachable over the LAN, over IPv6, or over a public domain with HTTPS configured. There is an online demo at note.nowen.cn with a demo account, which the README warns is reset periodically and not a place for anything important.

The licence is GPL-3.0, the primary language is TypeScript, and the repository topics point at the intended deployment: nas, fnos-app, self-hosted and personal-knowledge-management.

Two editors, and the features that make them more than text boxes

The editor layer is built on Tiptap 3 for rich text and CodeMirror 6 for Markdown, with conversion between the two formats, plain text notes, live preview and a split view.

The list of what the editors support is long and specific: an outline, tables, code blocks, KaTeX for mathematics, Mermaid diagrams, footnotes, callouts, media embedding, Chinese typography, reading position restore, annotations and version history. Reading position restore is the small one that people notice, because it means reopening a long document on a phone drops you where you were.

Chinese typography is worth a second look. The project is built by a Chinese-speaking team for that audience, and the editor has a dedicated set of typography controls for it, which is a level of polish that comes from using the software rather than translating it.

The wider design point is that the tree, the editor, the search, the AI and the task system are one product rather than five that share a login. The README is explicit about that intent, and it is the difference between a notes application and a workspace.

Offline edits are queued, acknowledged and retried

The reliability section is the most detailed part of the feature documentation, and it describes a deliberate approach to the problem of editing on a phone with a bad connection.

The primitives are Yjs for the underlying data, and a set of mechanisms on top: persistence confirmation for Yjs, per-note scoped sync receipts, retransmission of changes that were never confirmed, IndexedDB draft recovery, and serialised version saving for rich text. There is support for personal spaces, shared directories and an offline workspace, with personal directory structure sync, recycle bin recovery and protection against conflicting edits, and offline attachments get corrupt Blob verification and recovery.

The receipts are the interesting part. A note scoped sync receipt is a per-note acknowledgement, so a client knows which notes the server has actually stored rather than which notes it believes it sent. Combined with retransmission of unconfirmed changes, that is what stops a note from silently disappearing because the connection dropped between the client writing it and the server receiving it.

Performance work follows the same logic. The workspace, the editor, tasks, the journal, file management and the AI features load on demand, and static assets support cache validation with Gzip and Brotli pre-compression to reduce the first screen dependencies and repeated transfers.

RAG that retrieves first and sends only the matches

The AI section makes a specific and reassuring claim: the knowledge base question answering uses retrieval augmented generation, and it does not send all of your notes to a large model with every question.

The retrieval modes are the mechanism. In knowledge base mode, the relevant notes and attachments are searched in the local index first, and only the matching fragments are sent. In current note mode, only the note you have open is used. In selected text mode, only the text you have selected or pasted is used. With a local model such as the one Ollama runs, the question and the answer can stay on your own device or server.

The supported providers are an OpenAI compatible API, Tongyi Qianwen, Gemini, DeepSeek, Doubao and Ollama. The AI features include continuing and rewriting text, translation, title and tag generation, summarisation, an embedding index for retrieval, and RAG question answering over the knowledge base, and the task side can query today's tasks, show completion progress and create or complete a personal task after confirmation.

The privacy section is honest about the limit of that design. When you use online embedding or an online large model, the text needed to build the index or to answer a question is sent to the provider you configured. And it says plainly that highly sensitive information such as identity numbers, passwords, API keys and recovery phrases should not be stored in plain text.

The file organisation feature is more conservative still. AI file organisation produces metadata suggestions, requires human confirmation and permission checks, and the semantic search is based on file names, tags and descriptions without reading file bytes.

Docker Compose, a NAS in mind, and an updater that is off by default

The deployment story starts with Docker Compose, and the compose file shows a service built around a single named volume and a single port.

services:
  nowen-note:
    image: cropflre/nowen-note:${NOWEN_IMAGE_TAG:-latest}
    container_name: nowen-note
    restart: unless-stopped
    ports:
      - "${NOWEN_PORT:-3001}:3001"
    volumes:
      - nowen-note-data:/app/data

The environment block sets the database path, the port, the time zone, the public origins and the deployment type, and a health check queries the health endpoint on a ten second interval with a thirty second start period.

A second service carries the updater image, and it is disabled by default, starting only when a profile is passed explicitly. The comment in the compose file is the important part: that container is the only one that mounts the Docker socket, and the main application never mounts it. Separating the process that can replace images from the process that handles your notes is a sensible way to keep a container with socket access away from the data.

The upgrade warning deserves repeating. Before upgrading you should create a full backup and confirm that the database and attachments are persisted, and the README says in bold terms that rolling back the program or the container image does not roll back the database and the attachments. For a self-hosted note archive, that is the single most important operational sentence in the documentation, and it is the reason the backup features exist in the first place, with local automatic backups, background full archive tasks, streaming archives with verification, browser native downloads, email backups and credential encrypted WebDAV backups.

MCP access, a personal API token, and a plugin system

The open capabilities section lists OpenAPI 3.0, a TypeScript SDK, a CLI, webhooks, a plugin system, a restricted Personal API Token, an MCP server and a browser clipping extension, and the MCP server is what connects Claude Code, Cursor, VS Code and similar clients to the workspace.

The scope of MCP access is limited on purpose. It works within the scope of the Personal API Token, covering authorised notes, the knowledge tree, personal tasks and projects, file management and personal automation. Some of the newer write tools require a preview and an explicit confirmation and pass a concurrency version check, and high risk functions are not enabled by default and cannot bypass the notebook scope or the user permissions.

The package nowen-mcp can be built from source, with bin/nowen-mcp.mjs as the client entry point on Node.js 20 or later, and the standard integration is over stdio. Version 1.5.2 adds an optional Streamable HTTP transport that has to be enabled explicitly, is restricted to a loopback address and requires authentication. The advice in the README is to create a separate, minimally scoped token for each client and never to put an administrator password in a client configuration.

The plugin system has a registry in the examples directory, with plugin-registry/ and plugins/ folders, and there is a project documentation tree in docs/ that includes a tutorial centre, an MCP installation guide and a file organisation guide. The repository also carries AGENTS.md, a .claude/ directory, a .agents/ directory with a development skill and a .playwright-mcp/ directory, which is a fairly complete picture of a project that expects both human and automated contributors.

Editorial conclusion

nowen-note suits a person or a small team who wants their notes on hardware they control, on a NAS, and who wants one product instead of a separate editor, a task tool and a knowledge base. It does not suit a user who wants a hosted service, since there is no sign-up path, and it does not suit a deployment where the Docker socket cannot be mounted, because the in-app updater depends on it. Check three things before you install it: that your platform is one of the listed NAS systems or plain Docker, that you have a backup story for the database and the attachments separately from the container, because the README is explicit that rolling back an image does not roll back the data, and that the AI providers you intend to use are ones you have configured yourself, since the retrieval modes are what determine how much of your material leaves the machine. The newest release is v1.5.2 from 2026-10-16 and the last push to the repository was on 2026-10-22.

Frequently asked questions

Official sources

1. cropflre/nowen-note on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases