MarkiNote ✨

A self-hosted Markdown workspace with a guarded AI agent.

简体中文 · Quick start · Features · AI agent · Operations · Contributing

✨ Overview

MarkiNote turns a directory of Markdown files into a browser-based writing, reading, and AI-assisted knowledge workspace. The current full edition combines a React 19 and TypeScript client, a FastAPI modular monolith, a generated OpenAPI client, and an NGINX same-origin gateway. Optional Compose profiles add PostgreSQL, Prometheus, and OpenTelemetry.

The AI assistant is an agent rather than a chat-only sidebar: it can inspect the library, search content, create and edit documents, organize folders, fetch public web pages, and roll back one selected file operation. Mutating tools are deliberately guarded by opt-in write access, resource selection, one-time approvals, bounded input, before-images, and an operation journal.

[!IMPORTANT] MarkiNote 4.0.0 is Beta software. It is suitable for open-source review, single-machine self-hosted evaluation, and feedback. It is not yet a stable production release, a multi-user account system, or a highly available service. Read Known limitations before exposing it beyond a trusted machine.

The original Flask-based lightweight edition is preserved on the lite branch. The main branch contains this full React/FastAPI/Docker edition.

At a glance

🔗 Project Integration: FinNote Intelligent Financial Document System

MarkiNote has been integrated with FinanceMCP to form FinNote, an intelligent financial document system designed for financial research, AI-assisted analysis, and long-term knowledge preservation. The project participated in the Shanghai Collegiate Computer Application Ability Competition and received a Second Prize.

🌐 Live Demo: https://finvestai.top/

Within the FinNote architecture, FinanceMCP serves as the financial data and tool service layer. Built with Node.js, Express, and the Model Context Protocol (MCP) SDK, it exposes 19 standardized MCP tools that provide AI agents with access to stocks, funds, bonds, macroeconomic data, financial news, technical indicators, and multi-market financial data.

MarkiNote serves as the AI Agent-powered document and knowledge management application layer. It receives and organizes users' natural-language tasks, presents financial data and model-generated analysis inside an editable Markdown workspace, and turns the resulting analysis into manageable, traceable, and reusable document assets.

In the FinNote use case, the two systems collaborate through an HTTP / MCP service workflow:

Natural-language request → AI Agent task understanding → FinanceMCP tool invocation → Financial data retrieval → AI-assisted analysis → Markdown document generation and preservation → Continuous editing and knowledge management

As a result, MarkiNote can be used not only as a general-purpose self-hosted Markdown workspace and AI Agent document operating system, but also as the intelligent research workspace of FinNote, connecting real-time financial data, AI analysis, and long-term document asset management within a unified workflow.

🎯 Implemented features

Sidebar search filters names and paths. Full-text document search is available to the agent through search_files.

🚀 Docker quick start

Requirements

• Docker Desktop or Docker Engine
• Docker Compose v2 (v2.24 or newer is recommended)
• About 2 GB of free memory for the default stack; optional profiles need more

1. Prepare configuration

PowerShell:

Copy-Item .env.example .env
docker compose config --quiet

Bash:

cp .env.example .env
docker compose config --quiet

The checked-in defaults bind the gateway to 127.0.0.1:8080. A loopback-only evaluation may leave MARKINOTE_ACCESS_TOKEN empty. Before binding to another interface, configure access security as described in Production deployment.

2. Build and start

docker compose up -d --build --wait

Open http://127.0.0.1:8080. Useful checks:

docker compose ps
docker compose logs -f --tail=200 api gateway
curl --fail http://127.0.0.1:8080/gateway-health
curl --fail http://127.0.0.1:8080/health/live
curl --fail http://127.0.0.1:8080/health/ready

PowerShell users can replace the three curl calls with Invoke-RestMethod.

gateway-health proves only that NGINX is serving. health/live proves that the API process is alive. health/ready additionally checks the four writable data directories and, when the database backend is active, its schema revision; it still does not validate every record, provider, or restore path.

3. Stop or update safely

# Preserve containers, named volumes, and the Docker Desktop start button.
docker compose stop

# Rebuild after pulling a code update.
docker compose up -d --build --wait

# Remove containers and networks, but preserve named volumes.
docker compose down

[!CAUTION] docker compose down -v deletes the named data volumes. Do not use it as a routine stop or upgrade command.

1. Create or upload a .md, .markdown, or .txt document from the library sidebar.
2. Switch between Source, Preview, and Split modes. Mermaid and KaTeX are rendered in Preview.
3. Open the AI panel, select a provider/model, and enter a transient provider key or use a server-managed key.
4. Attach selected library documents or use the currently open document as context.
5. Keep Allow write tools disabled for read-only help. Enable it only when an agent must change files.
6. Review each requested resource or external-content mutation. Approvals are bound to the exact tool arguments and are consumed once.
7. If a completed AI file operation should be reversed, choose its explicit operation index from the tool card.

💾 Data, persistence, and import

The default Compose stack stores application data in named volumes. It does not bind-mount the repository's lib directory.