Knowladex docs.

Everything you need to drop raw notes into Knowladex and walk away with an interconnected wiki you can query from Claude, Cursor, or any tool that speaks MCP. Start with the 5-minute quickstart, or jump straight to the tool reference.

01 What is Knowladex?

Knowladex is a multi-tenant knowledge-base platform built on a single architectural choice: the model that compiles your knowledge base is the model you're already paying for.

Drop raw documents — meeting transcripts, half-finished specs, customer call notes, scratch files — into a project. Then ask your AI tool to compile. It calls Knowladex's MCP compile tool, gets a payload of raw docs and current wiki state, and writes interconnected articles back over write_article. Knowladex stores, indexes, cross-links, and serves them.

02 Who it's for

• Consultants & agencies running knowledge bases for many clients. Each client is its own org with its own users, tokens, and (optionally) subdomain.
• AI-native product teams who want their own internal docs queryable by their own agents — same wiki, same scope, same permissions as their humans.
• Solo operators drowning in scratch files and transcripts who want a wiki that organizes itself overnight.

03 Quickstart (5 minutes)

Assumes Knowladex has already provisioned your workspace. (If you're self-hosting, see the repo for the deploy guide.)

1. 01
   Sign in to your workspace

   Open https://app.knowladex.com/c/<your-org>/login and sign in with the email and password your account team gave you.

2. 02
   Create your first project

   Click New project. A project is one knowledge base — pick a slug like acme-rebrand or q1-research.

3. 03
   Mint an API token

   Go to My account → Create API token. You'll get a kbm.<org>.<random> string. Save it — it's only shown in full once.

4. 04
   Wire up your MCP client

   The My account page has copy-paste configs for Claude Code, Cursor, and Claude Desktop. See connecting your AI tool for the full guide.

5. 05
   Ingest your first doc

   In your AI tool: "ingest this file into the acme-rebrand project on Knowladex" — drop a markdown file. The AI tool will call ingest_document.

6. 06
   Compile

   Then: "compile the acme-rebrand knowledge base". Your AI tool will call compile, read every raw doc, and write wiki articles via write_article.

7. 07
   Browse

   Open the dashboard at /c/<org>/p/<project>. You'll see a fully-formed wiki with cross-links, an index, and search.

04 Core concepts

Knowladex's data model is small enough to fit in one diagram. Five things, in order from outermost to innermost:

Organization

The top-level tenant. One org = one client (if you're an agency) or one company (if you're a product team). Orgs contain users, projects, and tokens, and are the unit of isolation — users in one org can never see another org's data. Org slugs look like acme-corp or knowladex.

Project

One knowledge base inside an org. An org can have many projects (e.g. marketing-research, infra-rewrite, product-decisions). Each project has its own raw store, wiki, index, schema, and activity log.

Raw documents

The unstructured input. Markdown, transcripts, meeting dumps, scratch files. Knowladex stores them as-is in the project's raw/ directory. Each raw doc gets an id, title, tags, and optional source URL. Raw docs are never modified after ingest — they're the source of truth.

Wiki articles

The compiled output. Markdown files with frontmatter (title, tags, sources), stored in the project's wiki/ directory. Articles link to each other with [[wikilinks]], and link back to the raw documents they were compiled from. Knowladex maintains a backlink graph automatically.

The compile loop

The verb that ties raw docs to wiki articles. When you ask your AI tool to "compile", it calls compile, which returns:

• Every raw doc that's new or changed since the last compile
• The current state of the wiki (existing articles, the index)
• Per-project compile instructions from schema.md

Your AI tool reads everything, decides what articles to create or update, and calls write_article for each one. Knowladex stores the article, regenerates the dashboard, and updates the backlink graph. The next compile only sees what's changed since this run.

MCP — the bridge

Knowladex exposes everything — ingest, compile, write, search, lint — as Model Context Protocol tools. Any AI tool that speaks MCP (Claude Code, Cursor, Claude Desktop, your own agent) can call them with a Bearer token. There is no Knowladex SDK to install. The protocol is the SDK.

05 Authentication & roles

Two ways to authenticate

Knowladex has two entry points: a web dashboard and an MCP endpoint. Each takes a different credential.

• Web dashboard — sign in at /c/<org>/login with your email and password. A SameSite=Lax session cookie keeps you signed in.
• MCP endpoint — POST to /mcp with Authorization: Bearer kbm.<org>.<random>. Tokens are minted from your account page and bound to a single user.

Three roles

Every user (and every API token, since tokens inherit their user's role) has one of three roles:

• viewer — read-only. Can list projects, read articles, search the wiki, view the activity log. Cannot create or modify anything.
• editor — read + write content. Can ingest documents, compile, write articles, update the schema. Cannot manage users or tokens.
• org_admin — full control of the org. Editor permissions plus manage users, mint tokens, change roles, delete users.

Role changes for web sessions take effect on the next request — when an org_admin demotes a user from editor to viewer, every existing browser session for that user is destroyed immediately, so the next page load reflects the new role. No waiting period.

See the permissions matrix for a tool-by-tool breakdown.

06 Connecting your AI tool

Knowladex exposes POST /mcp over HTTP using the MCP Streamable HTTP transport. Any client that supports HTTP MCP can connect directly. Clients that only speak stdio (Claude Desktop, currently) connect through a small bridge.

Claude Code recommended

Claude Code has first-class HTTP MCP support. One terminal command:

claude mcp add knowladex https://app.knowladex.com/mcp \
  --scope user \
  --transport http \
  --header "Authorization: Bearer kbm.acme.YOUR_TOKEN"

--scope user is the important flag — without it Claude Code only registers Knowladex for the folder you're standing in. With it, Knowladex is available in every Claude Code session you ever start. From then on, try: "claude, list all the projects in knowladex".

Cursor

Add to ~/.cursor/mcp.json (create the file if it doesn't exist). Cursor will pick it up on next restart.

{
  "mcpServers": {
    "knowladex": {
      "url": "https://app.knowladex.com/mcp",
      "headers": {
        "Authorization": "Bearer kbm.acme.YOUR_TOKEN"
      }
    }
  }
}

Claude Desktop

Claude Desktop currently only speaks stdio MCP, so we use the mcp-remote bridge to forward stdio over HTTP. Add to claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude.

{
  "mcpServers": {
    "knowladex": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.knowladex.com/mcp",
        "--header",
        "Authorization: Bearer kbm.acme.YOUR_TOKEN"
      ]
    }
  }
}

Custom / curl

The endpoint speaks standard JSON-RPC 2.0 over HTTP. Test it with curl:

curl -X POST https://app.knowladex.com/mcp \
  -H "Authorization: Bearer kbm.acme.YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

You'll get back a list of every tool you have permission to call. From there, send tools/call requests with the tool name and arguments.

07 Recipes

Compile a knowledge base from scratch

You have a folder of meeting notes, customer transcripts, and half-finished specs. You want a wiki.

1. Create a project: "create a project called acme-discovery in Knowladex".
2. Ingest the docs: drop the folder into your AI tool and say "ingest every file in this folder into acme-discovery on knowladex, tagged with the year and the source type".
3. Set the schema (optional): "update the schema for acme-discovery to require articles for every customer mentioned, every product mentioned, and every blocker raised".
4. Compile: "compile the acme-discovery knowledge base". Your AI tool will call compile, get every raw doc plus your schema, and write articles.
5. Lint: "lint acme-discovery and fix any orphans". Your AI tool will call lint_wiki and patch any issues.

Incremental updates

You've added new docs to a wiki that's been running for a while. You want to update only what changed.

1. Ingest the new docs as usual.
2. Ask your AI tool: "compile the acme-discovery knowledge base — incremental, just what's changed".
3. The compile tool defaults to incremental mode. It returns only the new and modified raw docs, plus the current wiki state, so your AI tool can decide whether each new doc gets its own article, gets merged into an existing one, or just adds backlinks.

For a full rebuild from raw, pass fullRecompile: true. You'll rarely need this — incremental is the right default.

Search and retrieve

Search in Knowladex uses MiniSearch (fuzzy + prefix), scoped to a project. The MCP search tool returns ranked results with excerpts.

• "search the knowladex wiki for billing rewrite and read the top 3 articles"
• "find every article in acme-discovery tagged 'blocker' and summarize them" (uses list_articles with a tag filter)
• "read the auth-system article and follow every backlink" (uses read_article; backlinks come back in the response)

Lint and clean up

Wiki rot is real. Articles get orphaned, links break, content goes stale. The lint_wiki tool finds these issues; your AI tool can fix them.

1. "lint acme-discovery on knowladex and show me the report"
2. "fix every broken wikilink in the report" — your AI tool calls read_article, decides what the link should be, and calls write_article with the fix.
3. "any article that hasn't been touched in 90 days, add a 'stale' tag"

Per-project schema

Each project has a schema.md file that's read on every compile. It's free-form markdown — instructions written for an LLM, not a parser. Use it to encode conventions:

# schema.md

## Article conventions
- Every customer mentioned in raw docs gets its own article.
- Every decision mentioned gets an article tagged 'decision'.
- Use [[wikilinks]] for every internal cross-reference.
- Cite source raw docs in the frontmatter sources field.

## Voice
- Past tense for events, present tense for current state.
- Lead with the conclusion, then the evidence.

Read it with get_schema; update it with update_schema. The next compile picks it up automatically.

08 Tool reference — project

Every Knowladex capability is exposed as an MCP tool. This section documents the customer-facing tools you (and your AI tool) can call. The two org-management tools below (create_org, delete_org) are restricted to the Knowladex global admin and won't appear in tools/list for org-scoped tokens.

09 Tool reference — ingest

10 Tool reference — wiki

11 Tool reference — search

12 Tool reference — compile

13 Tool reference — categories

Manual categories are a curated organization layer that sits alongside tags. Where tags are free-form and per-article, categories are named buckets with their own colors and ordering — useful for hand-grouping articles into "Decisions / Customers / Open Questions / Done" or similar editorial slices. The web Organize page and these MCP tools are interchangeable; both go through CategoriesService and respect the same per-project mutex.

14 Tool reference — canvas

Knowladex stores spatial knowledge maps as JSON Canvas files — the open spec Obsidian and a growing set of tools read and write. A canvas is a 2D plane of text/file/link/group nodes plus edges between them. Your AI tool can write canvases for you, and you can take them anywhere that speaks the format.

15 Tool reference — maintenance

16 Tool reference — user & tokens

User and token management is admin-only. End users manage their own profile, password, and tokens through the My account page in the dashboard — no MCP call required.

17 Limits & quotas

Knowladex enforces three independent kinds of limits: per-tier plan quotas (storage), per-tier MCP rate limits (requests/min), and per-org PDF concurrency (in-flight ingests). All three are enforced server-side and surface as structured errors your AI tool can read and react to.

Plan tier quotas

Hard limits (independent of plan)

• Markdown body: ~5 MB per ingest_document / write_article call.
• PDF binary: ~22 MB per ingest_pdf call (30 MB base64). For larger PDFs, split first.
• PDF parse timeout: 60 s wall-clock per file. A wedged parser releases its slot automatically — it can't deadlock the queue.
• Tags: up to 30 per document, 1–64 chars each.
• Bulk category assign / unassign: up to 1,000 article slugs per call.
• Search query: up to 200 chars on the public /search route, 30 results max.
• Public export: capped at 10,000 articles per /share/…/export.zip download.

Subscription drift

When a paid customer's Stripe subscription enters past_due or unpaid status (failed payment), the org is automatically rate-limited at the Solo tier (10 req/min) until the bill clears. The plan field on the org isn't changed — the customer is still formally on Studio or Agency — but the rate limiter treats them as Solo so abuse can't continue indefinitely on a failed payment. Beta-pass orgs are exempt; they have no Stripe subscription to drift on.

Rate-limit responses

When you hit a rate limit, the /mcp endpoint returns HTTP 429 with a structured JSON body:

{
  "error": "Rate limit exceeded — your operator plan allows 30 mcp/minute. You've used 30.",
  "code": "rate_limited",
  "plan": "operator",
  "limit": 30,
  "used": 30,
  "resetInSeconds": 42,
  "resetAt": "2026-04-09T22:35:12Z",
  "upgradeUrl": "https://app.knowladex.com/c/<org>/me#billing"
}

The response also includes a Retry-After header, so MCP clients that respect HTTP semantics will back off automatically.

Per-org PDF queue full

When a PDF arrives but your org has already maxed out its plan's concurrent-ingest slots, ingest_pdf returns a clear error: "PDF queue full (3 max for operator plan). Wait for in-flight PDFs to finish or upgrade your plan." The slot is released as soon as any in-flight PDF finishes (success OR failure), so a wedged parser doesn't permanently consume your queue.

18 Permissions matrix

Quick reference: which role can call which tool. Roles are additive — editor can do everything viewer can, and org_admin can do everything editor can. The two global-admin tools (create_org, delete_org) are not visible to org-scoped tokens at all.

19 FAQ