Yuheng

Yuheng 玉衡

The knowledge platform for the age of AI agents. Yuheng brings in what your organization knows — files, web pages, Feishu, Notion and more — turns it into knowledge that is searchable, trustworthy and actually maintained, answers people's questions with citations, and hands the same capabilities to your AI agents over REST and MCP.

Yuheng does not try to be your agent. It is the knowledge layer: Claude, Cursor, your own ReAct loop — any agent — comes here to search, ask, read the Wiki and write knowledge back.

The name: 玉衡 (Yùhéng, Alioth) is the fifth star of the Big Dipper, where the bowl meets the handle; 璇玑玉衡 was also the ancient Chinese instrument for measuring the heavens. The mark draws the Dipper around it: stars joined into one figure, as knowledge is, and the star that weighs and measures, as knowledge needs.

What it does

 Ingest             Organize             Answer                Maintain              Expose
 ───────────────    ─────────────────    ──────────────────    ──────────────────    ────────────────
 files and URLs     knowledge bases      hybrid retrieval      duplicates and        REST /api/v1
 data-source sync   chunking, FAQ, tags  cited streaming Q&A   near-copies           MCP (22 tools)
 collaborative docs Auto-Wiki            web search            periodic review       Go SDK · CLI
                    graph (optional)                           answer feedback
                                                               owners and to-dos

• Knowledge in: upload documents (PDF, Word, Excel, PPT, HTML, EPUB, images, audio, video), import web pages, or connect Feishu/Lark wiki and drive, Notion, Yuque, RSS, GitLab and Tencent ima with scheduled incremental sync — or write in Yuheng's own collaborative documents, whose pages flow into the knowledge base.
• Answers out: vector + BM25 hybrid retrieval, rerank and query rewriting; every answer links back to the chunks it came from; optional knowledge graph and 12 web-search providers (including self-hosted SearXNG).
• Knowledge that does not quietly rot: knowledge health compares the documents of a knowledge base as they change, finding word-for-word copies and near-copies that differ (the old policy says 15 days of leave, the new one 10 — with the difference highlighted); asks owners to review what nobody has confirmed within the review period; and takes answers people marked "not helpful" to the documents they cite. Every finding is routed to the person who should act, collected in a personal to-do, and settled by superseding one document with the other, confirming a document is still right, or dismissing it with a reason.
• Built for agents: everything the web UI does is a REST endpoint (JWT or scoped API keys) and an MCP tool; there is also a Go SDK, the yuheng CLI and a DeepSeek Harness plugin.
• Enterprise-ready: one workspace per company with any number of knowledge bases, four member roles and workspace groups, system administrators who manage workspaces and accounts, audit logs, AES-256-GCM encrypted credentials, login rate limits and lockout, Langfuse tracing.

A look around

The company, people and policies in the screenshots are made-up demo data.

Features

📥 Ingestion and parsing

• docreader gRPC parsing service: layout analysis, OCR of scans, tables, multimodal image captions; optional in-process Rust parser anydoc
• Data-source connectors: Feishu/Lark (wiki and drive), Notion, Yuque, RSS, GitLab, Tencent ima — encrypted credentials, scheduled incremental sync, conflict strategies
• Folder trees, tags, batch operations, chunk-level editing with history, custom metadata

📝 Collaborative documents (docs profile)

• Spaces and page trees, page permissions and restricted pages, locking, trash
• Real-time collaboration (Yjs) or exclusive editing; tables, Mermaid, draw.io, attachments, block references, templates
• Comments, mentions, watching and notifications, revision history and restore, public share links, import and export
• A space bound to a knowledge base mirrors its pages into it; a restricted page never reaches the knowledge base

🔎 Retrieval and Q&A

• One retrieval engine, done properly: PostgreSQL + ParadeDB (BM25) + pgvector, no separate search cluster to run
• Hybrid retrieval, RRF fusion, rerank, query rewriting and expansion; FAQ entries; knowledge graph (Neo4j, optional)
• Streaming answers with a retrieval-progress timeline and clickable citations; answers can be rated helpful / not helpful

📖 Auto-Wiki

• An LLM pipeline organizes a knowledge base into interlinked Wiki pages, with human editing, version history and an issue-feedback loop

🩺 Knowledge health

• Content comparison: word-for-word duplicates, and near-copies compared as text with the differences highlighted
• Periodic review: a knowledge base's review period sends overdue documents to their owners
• Answer feedback: "not helpful" gathers on the cited documents; the question is attached only when the person chooses to
• Owners and routing: every document has an owner, every finding goes to the person best placed to act; a personal knowledge to-do
• Settling: supersede one of two documents (a docs page is excluded and marked superseded, never deleted), confirm still valid, dismiss with a reason

🤖 For your AI agents

• The /api/v1 REST API, Swagger UI at /swagger/index.html (non-release mode)
• Scoped API keys (retrieve, chat, ingest, manage_kbs, …), optionally limited to knowledge bases
• yuheng-mcp: 22 MCP tools over stdio / SSE / HTTP
• Go SDK, yuheng CLI, DeepSeek Harness plugin

🏢 Platform

• Workspaces with owner / admin / contributor / viewer roles and workspace groups; users are global identities placed into workspaces by invitation or by a system administrator, who also creates workspaces
• Audit logs and knowledge-base activity, task-queue dashboard, Langfuse, rate limiting
• File storage: a local directory or any S3-compatible store, RustFS bundled by default

Architecture

┌──────────────────┐  REST / SSE  ┌──────────────────────────────────────────────┐
│ Web UI · CLI     │ ◄──────────► │  Go backend (Gin, /api/v1)                    │
│ Go SDK           │              │  Q&A · retrieval · Wiki · docs · health       │
└──────────────────┘              │  async tasks (asynq / Redis, or in-process)   │
┌──────────────────┐  MCP (23)    └──┬──────────────┬───────────────┬────────────┘
│ AI agents        │ ◄────────────── │              │ gRPC          │ WebSocket
└──────────────────┘                 │              ▼               ▼
          ┌──────────────────────────┴──┐   ┌────────────┐   ┌────────────────┐
          │ PostgreSQL (ParadeDB)       │   │ docreader  │   │ collab (Yjs)   │
          │ data · pgvector · BM25      │   │ (Python)   │   │ docs mode only │
          └─────────────────────────────┘   └────────────┘   └────────────────┘
          Redis · RustFS / S3 · Neo4j (optional) · Langfuse (optional)

See the architecture overview (Chinese).

Project status

Yuheng is in its 0.x preview phase. It began as a fork of Tencent WeKnora and now evolves independently with a substantially reworked architecture: retrieval is unified on PostgreSQL (ParadeDB), and the product centres on knowledge bases, collaborative documents and knowledge health; the upstream built-in agent, IM channels and multi-engine adapters are not carried forward.

• The /api/v1 REST API may change between 0.x releases; MCP tool names are stable.
• The documentation is Chinese-first (website-docs/); the quick start and installation guide also exist in English.
• Docker images are not published yet; build them locally (below).

Quick start

You need Docker with Compose v2, Node.js and npm (the frontend is built on the host), and git; 4 CPU cores and 8 GB of memory are recommended. The first build downloads a lot and takes a while.

git clone https://github.com/magicyuan876/Yuheng.git
cd Yuheng
cp .env.example .env

Edit .env before the first start: JWT_SECRET and SYSTEM_AES_KEY are empty and must be set; the server refuses to start while they are empty, too short, or one of the old published examples:

openssl rand -hex 32     # -> JWT_SECRET
openssl rand -hex 16     # -> SYSTEM_AES_KEY (32 hex characters = the 32 bytes AES-256 needs)

Change DB_PASSWORD and REDIS_PASSWORD too. Keep SYSTEM_AES_KEY safe: stored credentials such as API keys are encrypted with it and cannot be recovered without it.

./scripts/build_frontend_dist.sh      # builds the frontend assets the frontend image needs
docker compose up -d --build
docker compose ps                     # wait until the services are healthy

This starts the frontend, the Go backend (app), docreader, PostgreSQL (ParadeDB), Redis and RustFS. Optional profiles: --profile docs adds the collaborative documents service and draw.io (settings in section K of .env.example); --profile full starts every optional component (Neo4j, Langfuse, SearXNG, the MCP server, …). TZ defaults to UTC.

First use

Open http://localhost (port FRONTEND_PORT, default 80). There is no default account.

• The first account to register becomes the administrator of the deployment; registration then closes, and others join by invitation. DISABLE_REGISTRATION=false keeps it open, true closes it from the start.
• Before asking anything, configure at least one chat model and one embedding model under Settings → Models; Ollama on the host and any OpenAI-compatible API work.
• To have knowledge health ask for reviews, set a review period in the knowledge base's basic settings.

Service	Address
Web UI	http://localhost (FRONTEND_PORT)
API	http://localhost:8080 (APP_PORT)
Readiness	http://localhost:8080/ready
Swagger UI	http://localhost:8080/swagger/index.html (when GIN_MODE is not release)

By default every published port except the frontend binds to localhost only. To serve beyond one machine, put a TLS reverse proxy in front of the frontend. Full steps: installation and quick start.

Clients and integrations

Client	Directory	Notes
Web UI	frontend/	Vue 3.5 + TypeScript + Vite; Tailwind v4 + shadcn-vue (migrating from TDesign screen by screen)
MCP server	mcp-server/	Install from source (pip install ./mcp-server); 22 tools
CLI	cli/	yuheng: scriptable JSON output, multiple profiles
Go SDK	client/	The CLI is built on it
DeepSeek Harness plugin	packages/dsh-yuheng/	Install from source

Documentation

• Product documentation (Chinese): getting started, architecture, features, API reference, clients, development
• Good places to start: introduction · collaborative documents · knowledge health · MCP · API overview · extension points
• Changelog · Roadmap

Development

make test             # go test ./... (needs Docker: tests run on a real PostgreSQL)
make lint             # golangci-lint
cd frontend && npm run lint && npm test && npm run type-check
cd docreader && uv sync && pytest tests/
cd cli && make build && make test

See CONTRIBUTING.md for the workflow and conventions, and follow the code of conduct. Report security issues privately as described in SECURITY.md.

Security notes

• Credentials (API keys, data-source tokens, …) are encrypted at rest with AES-256-GCM; the server refuses to start with a missing or example key.
• Outbound requests of data sources and URL imports go through SSRF protection and an allow-list.
• Login and registration are rate-limited per IP and repeated failures lock the account; CORS does not allow credentials by default.
• Never commit .env. For production, deploy on an internal network; see the installation guide.

Acknowledgements

Yuheng is partly derived from WeKnora by Tencent; the upstream MIT code is used as declared in NOTICE, THIRD_PARTY_NOTICES.md and licenses/upstream-weknora/. The lettering of the logo is Noto Serif CJK (SIL Open Font License 1.1), converted to outlines.

License

MIT. The license covers the code; the names Yuheng and 玉衡 and the project's marks are not licensed as the name of a modified product — see TRADEMARK.md.