openKMS

Open Knowledge Management System — one governed knowledge network for people and agents.

Teams retrieve, contribute, and govern the same corpus—so answers stay sourced and permission-aware, not trapped in private chat or stale files. Documentation · Vision: docs/goals.md.

Repository layout

• backend/ — FastAPI API (default port 8102)
• frontend/ — React + Vite (default port 5173)
• openkms-cli/ — Parse and pipeline CLI (used by the background worker)
• openkms-skill/ — Optional Agent Skill + Python CLI for agents calling the public HTTP API (personal API keys in the app under Settings; see docs/features/openkms-skill.md)
• vlm-server/ — mlx-vlm HTTP server for PaddleOCR-VL document parsing (run this separately)
• docker/ — Dockerfiles and docker-compose.yml (run via docker compose -f docker/docker-compose.yml … from repo root; see docker/README.md)
• docs/ — Architecture, features, developer setup, and research notes (published at yingrui.github.io/openKMS)
• qa-agent/ — Optional LangGraph Q&A service (proxied by the backend for KB chat)

Documentation

Topic	Where
Run locally	docs/quickstart.md · docs/developer/setup.md
Vision	docs/goals.md
Features & APIs	docs/functionalities.md
Security design	docs/security.md · docs/features/data-security.md
Roadmap	docs/development_plan.md
Comparisons & evaluation research	docs/research/ (RAGFlow, Confluence AI, OKF, text quality)

Quick start

Option A — Everything in Docker

1. Recommended: start mlx-vlm separately (see above and vlm-server/README.md).
2. cp backend/.env.example backend/.env and edit (secrets, auth, optional LLM URLs).
3. docker compose -f docker/docker-compose.yml up -d --build — builds images and starts Postgres (pgvector), MinIO, Neo4j, backend, worker, and frontend (nginx).
4. Open http://localhost:8082.

See docker/README.md for ports, env overrides, and how the worker reaches a host VLM.

Option B — Backend and frontend on the host

1. Recommended: start mlx-vlm separately for parsing (vlm-server/README.md).
2. cp backend/.env.example backend/.env and cp frontend/.env.example frontend/.env.
3. Start Postgres, MinIO, and Neo4j (optional for ontology): cd docker && docker compose -f docker-compose.yml up -d postgres minio neo4j
4. cd backend && uv sync && alembic upgrade head
5. Run uvicorn app.main:app --reload --port 8102 in backend/ and npm install && npm run dev in frontend/ (two terminals).
6. Open http://localhost:5173 (Vite proxies /api to the backend).

For a full walkthrough, auth modes, and optional services (QA agent, etc.), see docs/developer/setup.md and the docs site.

PaddleOCR-VL / mlx-vlm (run separately)

Document parsing expects a VLM server compatible with PaddleOCR-VL (default URL http://localhost:8101). Do not rely on the main Docker stack for this — run mlx-vlm on the host (or another machine) so you can use Apple Silicon / GPU and avoid huge images.

1. See vlm-server/README.md for how to start the server (e.g. ./start.sh in vlm-server/).
2. Point OPENKMS_VLM_URL (backend, worker, openkms-cli) at that URL. In the full Docker stack, the worker defaults to http://host.docker.internal:8101 so a host-run mlx-vlm is reachable.

Without a running VLM, uploads and pipeline jobs that parse documents will fail.