docsmint

# DocsMint

**A self-hosted AI-native knowledge workspace and installable PWA for people,
applications, and AI agents.**

DocsMint stores documents in a structured JSON editor model first. Markdown is
the convenient second format for editing, importing, and exporting content.
Automatic chunking, 1024-dimensional embeddings, multilingual hybrid search,
and GraphRAG make the same knowledge base useful to people, applications, and
agents through the web application, REST API, TypeScript SDK, CLI, and MCP
server.

[![Apache-2.0 License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/hiai-gg/docsmint?sort=semver)](https://github.com/hiai-gg/docsmint/releases)
[![npm](https://img.shields.io/npm/v/@hiai-gg/docsmint?logo=npm)](https://www.npmjs.com/package/@hiai-gg/docsmint)
[![Docker Pulls](https://img.shields.io/docker/pulls/vgalibov/docsmint?logo=docker)](https://hub.docker.com/r/vgalibov/docsmint)
[![Stars](https://img.shields.io/github/stars/hiai-gg/docsmint)](https://github.com/hiai-gg/docsmint/stargazers)
[![CI](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml/badge.svg)](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)
[![Bun](https://img.shields.io/badge/Runtime-Bun_1.3-black?logo=bun&logoColor=white)](https://bun.sh)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
[![Svelte](https://img.shields.io/badge/Svelte-5.x-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev)
[![Elysia](https://img.shields.io/badge/Elysia-1.4-lightgrey?logo=elysia&logoColor=white)](https://elysiajs.com)
[![Tailwind_CSS](https://img.shields.io/badge/Tailwind_CSS-v4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
[![Drizzle_ORM](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle&logoColor=black)](https://orm.drizzle.team)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![MCP Badge](https://lobehub.com/badge/mcp/hiai-gg-docsmint?style=plastic)](https://lobehub.com/mcp/hiai-gg-docsmint)

<img width="1920" height="974" alt="DocsMint installable document workspace" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />

## Why DocsMint?

- **Write naturally** in a rich visual editor or raw Markdown.
- **Find meaning, not only keywords** with exact, lexical, fuzzy, vector,
  multilingual expansion, and graph retrieval fused through RRF.
- **Keep retrieval current** with automatic, incremental chunking and
  re-embedding after document or metadata changes.
- **Connect agents directly** through REST, a typed SDK, CLI, or MCP.
- **Control access** with global keys or category-scoped `read`, `edit`, and
  `write` permissions.
- **Own the full stack**: application data, vectors, graph, queue, and files run
  on infrastructure you control.

## What's new in DocsMint 0.6.7?

- **Reliable HTTPS sessions.** Every protected SvelteKit route accepts Better
  Auth's secure production cookie as well as the local-development cookie.
- **Cleaner retrieval.** Deleted documents are excluded before exact, lexical,
  fuzzy, vector, chunk, and graph ranking.
- **Explicit GraphRAG providers.** Entity extraction requires its own
  chat-completion URL and never sends chat requests to an embedding endpoint.
- **Safer self-host defaults.** Auth origins are validated configuration, the
  SeaweedFS Filer UI binds to loopback, folder moves refresh knowledge
  metadata, and backups exclude `.env`.

DocsMint 0.6.7 includes the safe index recovery introduced in 0.6.6:

- **Safe explicit index recovery.** Admin document reindexing keeps the active
  generation searchable until a new generation has passed embedding, graph,
  summary, and finalize stages.
- **Truthful queue admission.** Maintenance requests force a replacement
  generation and report an error when durable enqueue fails instead of
  returning a false-positive success.
- **Verified MCP distribution.** The official MCP Registry manifest, npm stdio
  package, hosted Streamable HTTP endpoint, bundled Skill, prompts, resources,
  and 17-tool catalog remain one versioned contract.

DocsMint 0.6.6 includes the registry metadata fixes released in 0.6.3-0.6.5
and the complete MCP foundation introduced in 0.6.2:

- **Official MCP identity.** DocsMint now publishes the verified
  `io.github.HiAi-gg/docsmint` registry identity for both the npm stdio server
  and the hosted Streamable HTTP endpoint.
- **One capability implementation.** The public `@hiai-gg/docsmint/mcp`
  contract lets hosts provide a scoped API client while reusing the same 17
  tools, two prompts, three resources, and bundled document-manager Skill.
- **Current protocol runtime.** The MCP server uses the stable v2 server
  package and retains compatible stdio negotiation for existing clients.

DocsMint 0.6.2 includes the reliable knowledge refresh and scoped automation
foundation introduced in 0.6.1:

- **Reliable knowledge refreshes.** Explicit full reindexing now supersedes
  failed or stuck generations, retries release stale extraction claims, and
  publishes embeddings, summaries, and graph projections only for the current
  document generation.
- **Safer scoped automation.** Global keys can manage the complete document
  domain, while category keys stay confined to their category, folders,
  documents, tags, graph traversal, and index operations according to explicit
  `read`, `edit`, and `write` permissions.
- **Portable agent integration.** The MCP package exposes 17 document-manager
  tools, two reusable prompts, three context resources, and a bundled Skill,
  with Bunx, NPX, and local-checkout installation paths.
- **Compatible frontend packaging.** Published frontend entrypoints resolve the
  canonical hiai-ui exports used by the source build and packed consumers.

DocsMint 0.6.1 includes the mobile and PWA foundation introduced in 0.6.0:

- **Installable, update-safe PWA.** A versioned service worker, responsive app
  shell, install prompt, and deterministic offline fallback make DocsMint feel
  at home on desktop and mobile browsers.
- **Private offline reading and explicit drafts.** Identity-partitioned local
  snapshots keep selected documents readable offline. Drafts autosave locally,
  then return through a deliberate review-and-apply flow after reconnecting;
  DocsMint never silently replays offline mutations.
- **Touch-safe mobile navigation.** Sidebar document actions, Copy controls, and
  overflow menus remain reachable on touch devices without depending on hover,
  with accessible targets and narrow-screen layouts.
- **A flexible editor contract.** Reactive visual/Markdown mode preferences,
  Minimal toolbar support, and a reusable compact TipTap editor let hosts match
  the writing surface to the task without forking editor internals.
- **Stable document discovery.** The public API and TypeScript SDK provide
  deterministic cursor pagination and global sorting by title, category,
  folder, or update time, with canonical category and folder metadata.
- **Clear public and restricted sharing.** Share creation exposes the resulting
  URL for both public links and restricted invitation workflows, with an
  explicit Copy action that works on narrow screens.
- **Knowledge built for agents.** REST, the typed SDK, CLI, and MCP server expose
  scoped document operations, while multilingual hybrid search and GraphRAG
  help people and AI agents retrieve connected knowledge instead of isolated
  keyword matches.

DocsMint combines an installable self-hosted PWA knowledge base, mobile document
workspace, offline reading, local drafts, multilingual semantic search,
GraphRAG, MCP, a TypeScript SDK, CLI, and composable frontend hosts in one
open-source system.

For self-hosted customization, see [PWA hosting](docs/PWA_HOSTING.md) and
[extension points](docs/EXTENDING.md).

## Fastest installation: give this prompt to your agent

If you are installing DocsMint through an AI coding agent, use this path first.
It keeps the setup to Docker plus one provider choice and avoids unnecessary
source-code changes.

```text
Install DocsMint from https://github.com/HiAi-gg/docsmint.
Verify Docker and Docker Compose v2, clone the repository, and run
`bash scripts/quickstart.sh`. Do not print or commit .env. Ask me to enter only
an OpenRouter key or select Ollama, then run quickstart again. Verify
http://localhost:50701, http://localhost:50700/api/health, and
`docker compose ps`. Do not replace Bun, rewrite migrations, disable GraphRAG,
or delete volumes.
```

After startup, open **http://localhost:50701** and create the first account.
For manual installation, use the Docker quickstart below.

## Quickstart

### Requirements

- Docker Engine or Docker Desktop
- Docker Compose v2
- One of:
  - an [OpenRouter](https://openrouter.ai/) API key; or
  - a local [Ollama](https://ollama.com/) instance

### Start with Docker

```bash
git clone https://github.com/HiAi-gg/docsmint.git
cd docsmint
bash scripts/quickstart.sh
```

On its first run, the script creates an ignored root `.env`, generates the
database, authentication, and storage secrets, builds the PostgreSQL image,
applies migrations, and starts the complete application.

For OpenRouter, add one value to `.env` and run the script again:

```dotenv
OPENROUTER_API_KEY=sk-or-your-key
```

For Ollama, select the local provider instead:

```dotenv
AI_PROVIDER=ollama
OLLAMA_PORT=11434
```

Then make sure the configured local models are available:

```bash
ollama pull bge-m3
ollama pull qwen3:8b
bash scripts/quickstart.sh
```

Open **http://localhost:50701**. The API health endpoint is
**http://localhost:50700/api/health**.

### First use

1. Create your account in the web application.
2. Create a category or folder and add or import a document.
3. Wait for the document pipeline to finish chunking and embedding.
4. Search u