MarkiNote ✨

✨ 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.

💾 Data, persistence, and import

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

To import local Markdown files from lib on Windows after the stack is running:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\import-library.ps1 -Source .\lib

The importer accepts .md, .markdown, and .txt, checks paths and name conflicts before upload, and never makes the repository directory the live data source. A server failure can still leave a batch partially imported; back up first and reconcile completed items from the command output.

🤖 AI agent

Available tools

Agent runs are capped at eight tool rounds and 24 total tool calls. Agent file tools use a 512 KiB file limit even though regular documents may reach 2 MiB; fetch_url accepts at most 2 MiB and considers at most 20,000 extracted characters for an additional long-page summary call. File mutations are journaled, backed up before the change, and exposed as tool cards. Rollback always targets one explicit operation index; the API does not pretend that a multi-file group can be reversed atomically.

Reviewed provider allowlist

As of 2026-08-09, the repository allowlist is:

These models are called with thinking disabled to keep the current multi-step tool protocol consistent. Key validation intersects the provider's /models response with the local capability-reviewed allowlist; an arbitrary remote model is never enabled automatically. Provider availability, prices, regional policy, and model IDs can change—verify them in the DeepSeek documentation and Kimi documentation.

Keys, privacy, and approvals

• A key entered in the Web UI lives only in the current page's memory. Legacy MarkiNote local-storage key entries are removed, and a refresh or close clears the in-memory value.
• Provider/model preferences may persist, but the key does not. MARKINOTE_AI_API_KEY is one optional global server-side fallback, so it must match the selected provider. In the current Compose baseline it is an environment variable visible to Docker host/container administrators; production operators should inject it through an external secret manager or leave it empty.
• Messages, selected documents, attachments, and fetched-page summaries are sent to the chosen external provider. Do not submit content that the provider is not authorized to process.
• Long-page summarization and optional automatic title generation make additional provider requests and may incur additional cost.
• AI write access starts off for new and restored conversations.
• Unselected resources require approval. After web_search or fetch_url, any mutation requires a new one-time approval for the exact tool name and canonical arguments, treating web content as untrusted instructions.
• fetch_url rejects credentials in URLs, private/link-local destinations, unsafe redirect hops, and DNS/peer mismatches. web_search remains best-effort scraping of public search pages, not a guaranteed official search API.
• Fake-provider tests verify protocol behavior only. They do not prove a real account, balance, region, model, or network path.

🏗️ Architecture

flowchart LR
    User[Browser] -->|HTTP / SSE| Gateway[NGINX :8080]
    Gateway --> Web[React production assets]
    Gateway --> API[FastAPI :8000<br/>one worker]
    API --> Library[(LocalFS documents)]
    API --> State[(JSON or SQL conversations/journals)]
    API --> Providers[DeepSeek / Kimi]
    API -. metrics .-> Prometheus
    API -. traces .-> OTel[OpenTelemetry Collector]

MarkiNote is a modular monolith, not a microservice estate. HTTP adapters call application/domain services, which depend on explicit storage/provider ports. The browser consumes a TypeScript client generated from FastAPI's OpenAPI schema. Agent replies use versioned SSE envelopes, while regular API failures use Problem Details with a stable error code and request ID.

Compose profiles

MARKINOTE_CONVERSATION_BACKEND=database
MARKINOTE_POSTGRES_DB=markinote
MARKINOTE_POSTGRES_USER=markinote
MARKINOTE_POSTGRES_PASSWORD=<strong-random-password>
MARKINOTE_DATABASE_URL=postgresql+psycopg://markinote:<url-encoded-password>@postgres:5432/markinote
MARKINOTE_AUTO_CREATE_DATABASE=false

docker compose --profile postgres up -d --wait postgres
docker compose --profile migration run --rm --no-deps migrate
docker compose --profile postgres up -d --build --wait

MARKINOTE_OTEL_ENABLED=true
MARKINOTE_OTEL_ENDPOINT=http://otel-collector:4318/v1/traces
MARKINOTE_OTEL_SERVICE_NAME=markinote-api

docker compose --profile observability up -d --wait
curl --fail http://127.0.0.1:9090/-/ready

⚙️ Configuration reference

Copy .env.example to .env for Compose. Pydantic also reads .env.local for native API development. The following are the settings most operators need to understand.

Access and runtime

Storage and retention

AI and operational controls

🧑‍💻 Native development

Requirements: Python 3.12, uv, Node.js 20.19+ (Node 22 recommended), and npm.

uv sync --frozen --all-extras
npm ci --prefix packages/api-client
npm ci --prefix apps/web
npm run generate:api
uv run uvicorn markinote_api.application:app --host 127.0.0.1 --port 8000 --reload

Start Vite in another terminal.

PowerShell:

$env:VITE_API_PROXY='http://127.0.0.1:8000'
npm run dev --prefix apps/web

Bash:

VITE_API_PROXY=http://127.0.0.1:8000 npm run dev --prefix apps/web

The Web app defaults to http://127.0.0.1:5173. Swagger UI is at http://127.0.0.1:8000/api/docs, ReDoc at /api/redoc, and the raw contract at /api/openapi.json. The committed snapshot and generated TypeScript client live under packages/api-client/.

✅ Validation and evidence

Run the public quality gates from the repository root:

# Python
uv run ruff check apps/api/src apps/api/scripts tests apps/api/tests infra
uv run mypy apps/api/src/markinote_api
uv run pytest -q
uv run pytest apps/api/tests -q --cov=markinote_api --cov-config=pyproject.toml --cov-report=term-missing

# API contract and Web
npm run generate:api
npm run typecheck --prefix packages/api-client
npm run typecheck --prefix apps/web
npm run lint --prefix apps/web
npm run test:coverage --prefix apps/web
npm run build --prefix apps/web

# Browser behavior
npx --prefix apps/web playwright install chromium
npm run e2e --prefix apps/web -- --project=chromium --project=mobile-chrome

# Compose model
docker compose config --quiet

CI definitions include Linux and Windows quality gates, OpenAPI drift, PostgreSQL/Alembic, gateway CRUD and SSE, container builds, dependency audits, CodeQL, Trivy, SBOM/provenance, restore rehearsals, cross-browser checks, and release-image validation. A workflow file is a test definition—not evidence of a successful remote run.

🔐 Production deployment

The default stack is optimized for local evaluation. For a non-loopback or internet-facing deployment, place the gateway behind TLS and use the production overlay only with immutable image digests produced by a successful release workflow.

Minimum production requirements:

1. Generate different long random values for MARKINOTE_ACCESS_TOKEN and MARKINOTE_SECRET_KEY; never commit them. Production validation requires at least 24 and 32 characters respectively, while 48-byte random values are recommended.
2. Set an HTTPS-only MARKINOTE_PUBLIC_ORIGIN and an explicit MARKINOTE_TRUSTED_HOSTS JSON array containing its hostname plus api and 127.0.0.1. Production rejects *.
3. Keep exactly one API container and one worker while documents use LocalFS.
4. Set MARKINOTE_AUTO_CREATE_DATABASE=false and run Alembic before starting a database-backed API.
5. Keep API, PostgreSQL, Redis, Prometheus, and OTLP ports private. Restrict the API egress network to approved provider destinations at the host/orchestrator layer; a Docker bridge is not a domain firewall.
6. Back up and restore-test all business volumes, plus PostgreSQL if enabled, before each important release.
7. Deploy API and gateway digests from the same release and verify /api/v1 reports the expected version.

Browsers exchange the deployment token through same-origin POST /auth/access-token for an HttpOnly, SameSite=Strict cookie; non-browser clients may use a Bearer token. Never put a token in a URL. Versioned APIs, OpenAPI, and API documentation are protected when authentication is enabled; health endpoints remain unauthenticated and metrics stay on the internal API network. The NGINX baseline rate-limits ordinary API traffic to 10 requests/second, AI starts to 12/minute, authentication to 5/minute, and concurrent AI streams to four per directly observed source address; review the real client-IP boundary behind a load balancer.

MARKINOTE_VERSION=v4.0.0
MARKINOTE_API_IMAGE=ghcr.io/wink-wink-wink555/markinote-api
MARKINOTE_GATEWAY_IMAGE=ghcr.io/wink-wink-wink555/markinote-gateway
MARKINOTE_API_DIGEST=sha256:<release-api-manifest-digest>
MARKINOTE_GATEWAY_DIGEST=sha256:<release-gateway-manifest-digest>
MARKINOTE_VOLUME_PREFIX=markinote_prod
MARKINOTE_ENVIRONMENT=production
MARKINOTE_HTTP_BIND=127.0.0.1
MARKINOTE_HTTP_PORT=8080
MARKINOTE_ACCESS_TOKEN=<48-byte-or-longer-random-value>
MARKINOTE_SECRET_KEY=<different-48-byte-or-longer-random-value>
MARKINOTE_PUBLIC_ORIGIN=https://notes.example.com
MARKINOTE_TRUSTED_HOSTS='["notes.example.com","api","127.0.0.1","localhost"]'
MARKINOTE_AUTO_CREATE_DATABASE=false
MARKINOTE_AGENT_RUN_RECONCILE_ON_STARTUP=true
MARKINOTE_AGENT_RUN_SINGLE_WRITER=true
MARKINOTE_AGENT_RUN_RECONCILE_LIMIT=1000

python3 infra/ci/production-compose-preflight.py --env-file .env.production
docker compose --env-file .env.production -f infra/compose.yaml -f infra/compose.production.yaml pull api gateway migrate

# Run this when the database adapter/schema is in use.
docker compose --env-file .env.production -f infra/compose.yaml -f infra/compose.production.yaml --profile migration run --rm --no-deps migrate

docker compose --env-file .env.production -f infra/compose.yaml -f infra/compose.production.yaml up -d --no-build --wait api gateway

🛟 Backup, restore, and rollback

• /data/backups contains AI rollback and Saga recovery material; it is not a disaster-recovery backup. The repository does not schedule daily or off-site backups for you.
• Back up library, conversations, backups, trash, and state; also run pg_dump --format=custom --no-owner --no-acl when PostgreSQL is active.
• For a consistent checkpoint, stop gateway/API writes before the database dump and volume archives. Hash the archives, encrypt off-host copies, and record the image digests and schema revision.
• Restore into a new, explicitly named volume prefix. Restore database and file volumes before starting API/gateway, then validate hashes, Alembic head, health, and a read/write/restore user journey.
• The initial operational targets are daily full backups, an extra backup before important releases, RPO 24 hours, and restore-rehearsal RTO 2 hours. These are unproven targets, not service guarantees.
• Never restore old AI before-images over current files without checking the recorded after-fingerprint. Legacy or corrupt records fail closed and require isolated inspection.
• Keep the original failed volumes until incident review is complete. Backup archives can contain documents, conversations, prompts, and before-images; encrypt off-site copies and restrict access.

Exercise the repository's isolated rehearsal scripts before relying on a backup process:

python infra/ci/local-volume-restore-rehearsal.py --artifact-dir .artifacts/local-volume-restore
python infra/ci/backup-restore-rehearsal.py --artifact-dir .artifacts/postgres-restore

These scripts are test rehearsals, not a substitute for an operator-approved production backup system.

🩺 Monitoring and incident response

Use the response X-Request-ID to correlate gateway and API logs. Never copy authorization headers, cookies, AI keys, full prompts, attachments, document bodies, or tool arguments into incident evidence.

⚠️ Known limitations

High priority

• Conversation Saga retention is not fully unified. Recovery records and snapshots under the backups volume are not yet completely counted by MARKINOTE_BACKUP_MAX_BYTES, so that value is not an absolute cap for every backup artifact. An unresolved Saga can retain a conversation before-image and currently has no automatic TTL. Monitor the volume and resolve recovery references promptly.
• External acceptance evidence is pending. Local fake-provider and contract tests cannot prove real DeepSeek/Kimi accounts, the first GitHub Actions/CodeQL/Trivy/SBOM run, published image digests, Docker Engine startup, a real PostgreSQL instance, or a target-environment restore.

Product and API gaps

• Trash list/restore endpoints exist, but the React UI does not expose them yet.
• Sidebar search covers filenames and paths; body search is agent-only.
• web_search scrapes public search pages on a best-effort basis.
• Official Web saves use content versions, but a third-party client can omit the precondition.
• Invalid or missing conversationId handling is not yet perfectly uniform across every path.
• Some message, attachment, and context defaults are duplicated across contracts rather than generated from one schema.

Operational boundaries

• Single tenant and single writer only; no accounts, OIDC, RBAC, tenant isolation, or HA.
• PostgreSQL does not make the LocalFS document store multi-writer safe; Redis is not on the request path.
• Rollback is one explicit operation, not an atomic multi-file transaction.
• Corrupt JSON audit records do not yet have an automated quarantine/repair workflow.
• Readiness does not scan every record, provider, backup, or disaster-recovery path.
• The PowerShell importer can leave a partially completed batch after an upstream failure.
• The maximum AI stream/lease and gateway SSE timeout are different boundaries; logs are required to distinguish a slow provider from a gateway interruption.

🧭 Troubleshooting

📁 Repository layout

apps/api/                 FastAPI application, Alembic migrations, scripts, and API tests
apps/web/                 React/TypeScript SPA, unit tests, and Playwright journeys
packages/api-client/      Committed OpenAPI snapshot and generated TypeScript client
infra/                    Compose topology, NGINX, monitoring, and CI smoke programs
scripts/                  User-facing maintenance/import helpers
tests/                    Cross-component, recovery, observability, and supply-chain contracts
.github/                  CI, CodeQL, cross-browser, release workflows, and templates
README.md                 Canonical English documentation
README_CN.md              Simplified Chinese documentation

Public operating documentation is intentionally self-contained in the two root README files. Local design notes and private audit material are excluded from the repository release and must not be required by builds, tests, images, alerts, or public links.

📦 Release and repository governance

• Protect main; require reviewed pull requests and successful required checks before merge.
• Preserve the Flask edition on lite. Full-edition work and releases belong on main.
• Create SemVer tags only from a reviewed main commit. The release workflow must publish API and gateway images from the same source SHA.
• Deploy immutable manifest digests, not mutable tags. Keep the version, source SHA, paired digests, CI/release links, SBOM/provenance, migration revision, backup/restore evidence, and smoke results.
• Workflow definitions do not activate GitHub branch protection, environment approval, immutable registry policy, or secret management; configure those controls in the hosting platform.
• Never attach resolved environment files, credentials, database URLs, private documents, or unredacted screenshots to release evidence.

See CHANGELOG.md for release notes, CONTRIBUTING.md for development rules, and SECURITY.md for private vulnerability reporting.

🤝 Contributing

Issues and pull requests are welcome. Before opening a PR:

1. Explain the user-visible change and the data/security/concurrency impact.
2. Add or update tests and generated contracts.
3. Run the relevant quality gates above.
4. Include only redacted UI evidence.
5. Update both README languages when behavior, configuration, operations, or limitations change.

Please report vulnerabilities privately according to SECURITY.md, not through a public issue.

📄 License

MarkiNote is released under the MIT License.