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 isthe 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, andagents through the web application, REST API, TypeScript SDK, CLI, and MCPserver.

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 andre-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, andwrite permissions.
• Own the full stack: application data, vectors, graph, queue, and files runon infrastructure you control.

What's new in DocsMint 0.7.0?

• Signed workspace assertions. Trusted server-to-server hosts can restrictan assertion to one category with independent read, edit, and writepermissions; an omitted scope remains workspace-wide and role-derived.
• Consistent effective-category authorization. Direct and folder-inheritedcategories are enforced before counts, pagination, indexing, search, andGraphRAG retrieval. Index status is read-only; refresh requires write.
• Release-safe indexing. Context-aware embedding generations and recoveryprevent stale metadata work from becoming active.

This OSS release adds no host RBAC, billing, invitations, or product UI.

DocsMint 0.7.0 includes the 0.6.8 reliability fixes:

• Workspace-safe recovery. Explicit operator reindexing carries thedocument's workspace into every durable pipeline stage, including RLS reads.
• Consistent operator authentication. Both documented admin key headersbypass interactive rate limits during maintenance operations.

DocsMint 0.6.8 includes the self-host reliability fixes introduced in 0.6.7:

• Reliable HTTPS sessions. Every protected SvelteKit route accepts BetterAuth'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 ownchat-completion URL and never sends chat requests to an embedding endpoint.
• Safer self-host defaults. Auth origins are validated configuration, theSeaweedFS Filer UI binds to loopback, folder moves refresh knowledgemetadata, 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 activegeneration searchable until a new generation has passed embedding, graph,summary, and finalize stages.
• Truthful queue admission. Maintenance requests force a replacementgeneration and report an error when durable enqueue fails instead ofreturning a false-positive success.
• Verified MCP distribution. The official MCP Registry manifest, npm stdiopackage, 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.5and the complete MCP foundation introduced in 0.6.2:

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

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

• Reliable knowledge refreshes. Explicit full reindexing now supersedesfailed or stuck generations, retries release stale extraction claims, andpublishes embeddings, summaries, and graph projections only for the currentdocument generation.
• Safer scoped automation. Global keys can manage the complete documentdomain, while category keys stay confined to their category, folders,documents, tags, graph traversal, and index operations according to explicitread, edit, and write permissions.
• Portable agent integration. The MCP package exposes 17 document-managertools, 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 thecanonical 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 appshell, install prompt, and deterministic offline fallback make DocsMint feelat home on desktop and mobile browsers.
• Private offline reading and explicit drafts. Identity-partitioned localsnapshots 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, andoverflow 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 matchthe writing surface to the task without forking editor internals.
• Stable document discovery. The public API and TypeScript SDK providedeterministic cursor pagination and global sorting by title, category,folder, or update time, with canonical category and folder metadata.
• Safe standalone sharing. Standalone DocsMint exposes public links withexpiry, optional passwords, Copy, and revoke controls. Host-managed consumersretain their existing restricted invitation workflow.
• Knowledge built for agents. REST, the typed SDK, CLI, and MCP server exposescoped document operations, while multilingual hybrid search and GraphRAGhelp people and AI agents retrieve connected knowledge instead of isolatedkeyword matches.

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

For self-hosted customization, see PWA hosting andextension points.

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 unnecessarysource-code changes.

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 API key; or
  • a local Ollama instance

Start with Docker

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 thedatabase, 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:

OPENROUTER_API_KEY=sk-or-your-key

For Ollama, select the local provider instead:

AI_PROVIDER=ollama
OLLAMA_PORT=11434

Then make sure the configured local models are available:

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

Open http://localhost:50701. The API health endpoint ishttp://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 using an exact phrase, a related concept, an alternate language, ora misspelling.
5. Open Settings → API when you want to connect a CLI, MCP client, orexternal application.

The canonical local ports are:

See Deployment for domains, TLS, provider tuning,backups, and production operation.

Embedding provider URLs, models, and credentials are deployment configuration.They are never stored in browser settings or local storage.

Use DocsMint from the terminal

The published package includes the CLI. It connects to an already runningDocsMint server; installing it does not deploy the server.

npm install @hiai-gg/docsmint

bunx --package @hiai-gg/docsmint docsmint init \
  --url http://localhost:50700 \
  --key 'your-global-or-category-key'

bunx --package @hiai-gg/docsmint docsmint search "project architecture"
bunx --package @hiai-gg/docsmint docsmint list
bunx --package @hiai-gg/docsmint docsmint read <document-id>
bunx --package @hiai-gg/docsmint docsmint create \
  --title "Release notes" --content "# Version 0.2.9"

Credentials can also be supplied through HIAI_DOCS_URL andHIAI_DOCS_API_KEY. See the CLI guide for everycommand and configuration precedence.

Connect an MCP client

DocsMint exposes document search, reading, creation, updates, categories,folders, tags, GraphRAG traversal, index status and refresh, snapshots,history, and export as MCP tools. It also publishes reusable prompts,context resources, and a document-manager skill for agent clients.

{
  "mcpServers": {
    "docsmint": {
      "command": "bunx",
      "args": ["--package", "@hiai-gg/docsmint", "docsmint-mcp"],
      "env": {
        "HIAI_DOCS_URL": "http://localhost:50700",
        "HIAI_DOCS_API_KEY": "your-global-or-category-key"
      }
    }
  }
}

Run the server directly to verify the installation:

bunx --package @hiai-gg/docsmint docsmint-mcp

The server uses stdio and works with MCP-capable clients such as ClaudeDesktop, Cursor, and coding agents that accept standard MCP configuration. Seethe MCP guide for its 17 tools, prompts,resources, skill, and API routes.

Agent skills after installation

The MCP tools are the recommended portable agent skills. A category-bound agentcan receive only the knowledge and operations it needs; a trusted personalagent can use a global key. Agents do not need database or filesystem access.After startup, create an API key in Settings → API and add the MCP blockabove to the agent client. For custom agent workflows, use the same key throughthe CLI, SDK, or REST API.

TypeScript SDK

bun add @hiai-gg/docsmint

import { DocsClient } from '@hiai-gg/docsmint';

const docs = new DocsClient({
  baseUrl: 'http://localhost:50700',
  apiKey: process.env.HIAI_DOCS_API_KEY,
});

const created = await docs.createDoc({
  title: 'Meeting notes',
  content: '# Agenda',
});

const results = await docs.search('what did we decide?');
console.log(created.id, results.items);

The SDK is a typed fetch client with retries for transient failures. See theSDK reference and REST API.

API keys and integrations

Create and revoke integration keys from Settings → API.

Category permissions are explicit and non-hierarchical:

• read permits list, read, search, and export;
• edit permits updates to existing content, attachments, and versions;
• write permits create, move, delete, share, and publish operations.

Combine permissions when an integration needs more than one capability.API-key lifecycle operations require the owning browser session; an API keycannot create or elevate another key. Server-to-server integrations are notaffected by browser CORS. Browser integrations must add their exact origin toCORS_ORIGINS.

What is included?

frontend/          SvelteKit workspace and TipTap editor
backend/           Elysia REST API, search, workers, and authentication
packages/db/       Drizzle schema and migrations
packages/sdk/      Typed API client
packages/cli/      Terminal client
packages/mcp-server/  MCP stdio server
postgres/          PostgreSQL image with vector and graph extensions

The Docker deployment runs:

• Web — document editor, folders, categories, sharing, settings, and search;
• API — documents, attachments, versions, keys, search, and administration;
• PostgreSQL 18 — relational data, pgvector/pgvectorscale vectors, and theApache AGE graph in one database;
• Redis 8 — BullMQ queues, caching, retries, and job recovery;
• SeaweedFS — S3-compatible attachment storage.

How search works

Every document save schedules background work. Content is chunked, changedchunks are embedded, and the completed generation is activated atomically. Theprevious valid generation remains searchable if a provider call fails.

Search combines exact title matches, multilingual lexical search, typo-tolerantfuzzy matching, semantic vectors, adaptive query expansion, and Apache AGEgraph neighbors. Reciprocal rank fusion combines the channels without allowingone weak provider result to dominate. Authorization is applied before retrievaland again before results are returned.

GraphRAG is part of the normal search path in the reference configuration. Itextracts entities after embeddings are ready and finds related documents beyonddirect keyword or vector similarity. It degrades gracefully when an externalmodel is unavailable.

For pipeline internals and tuning, see Architecture andDeployment.

Stack

• Bun, TypeScript, Elysia, Zod, and Pino
• Svelte 5, SvelteKit, Tailwind CSS, and TipTap
• Better Auth and Drizzle ORM
• PostgreSQL 18, pgvector, pgvectorscale, and Apache AGE
• Redis 8 and BullMQ
• SeaweedFS with its S3-compatible API
• OpenAI-compatible providers through OpenRouter or local Ollama

Comparison

DocsMint overlaps with several excellent open-source knowledge tools, but itsfocus is a compact knowledge runtime shared equally by humans and agents.

This is a product-positioning summary, not a claim that every listed projectlacks a feature. Check each project's current documentation when choosing adeployment.

Documentation

• Documentation index
• Product usage
• REST API and OpenAPI JSON
• Architecture
• Deployment and operations
• Extension points
• Maintainer release flow
• Security policy
• Changelog

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run build

Read CONTRIBUTING.md before opening a pull request. Pleasereport vulnerabilities through SECURITY.md, not a public issue.

License

DocsMint is released under the Apache License 2.0.

Built as an independent open-source project in theHiAi ecosystem.