Quick start

knomit is a distributed, decentralized knowledge base built from facts — knowledge + commit. This page gets you from zero to a running server with a peer connected.

Install

The quickest way in is a signed release build — no toolchain, no compile step.

Download a release

Grab the desktop app or the server binary for macOS or Linux. The macOS app is notarized and keeps itself up to date; both platforms ship a knomit serve tarball. Start here unless you need to modify knomit.

Build from source

Everything below. Needed if you’re changing knomit itself, or running on a platform the releases don’t cover.

Build from source

Requirements

• Go 1.25+ — the entire backend.
• Node.js + npm — builds the embedded React frontend.
• Git CLI — knomit shells out to git.
• A C compiler — Xcode Command Line Tools on macOS (xcode-select --install), or gcc / build-essential on Linux. The build is CGO-based (SQLite and the ONNX bindings are compiled in).

Note

Two native shared libraries — ONNX Runtime (embeddings) and graphqlite (graph queries) — are downloaded automatically into dist/<goos>-<goarch>/lib/ by make setup / make build. You don’t install them by hand. The build also drops top-level dist/knomit and dist/knomit-bridge symlinks pointing into that platform directory.

Build and run

1. Clone the repository and enter it.

   git clone https://github.com/knomit/knomit.git
   cd knomit

2. Download the native libraries (one-time).

   make setup

3. Build the web frontend and the Go binaries.

   make build

4. Start the server.

   make run

Open http://localhost:19278/ for the web UI. A fresh install starts with no repositories — the UI’s “no repos” screen is the ordinary first-run state, not an error. Create your first one from Manage repos.

Creating a repo runs a short wizard: local or a remote, then — if you gave it a remote — credentials and a branch. It probes as it goes and derives the rest, so you are never asked to classify the remote yourself.

Where it asks is the ontology — the topics your repo accepts, and the rules every fact is validated against. The code preset is the right answer for a codebase and the default preset for everything else. There is no setting to change it afterwards — doing so is a migration through git — so it is worth a minute of thought now. If you point knomit at a branch that is already a knowledge base, the question doesn’t come up at all: that repo’s own ontology governs.

Prefer a native app?

The desktop app is a system-tray app that runs the server in-process and lets MCP clients auto-discover it — no terminal needed to keep knomit running. Most people should just download it. To build it here instead of make run, use make desktop: on macOS that produces dist/darwin-arm64/Knomit.app; on Linux it produces the knomit-desktop binary only — run make desktop-install afterwards for the .desktop launcher and icon.

No CLI to create repos

Repos are created, archived, restored, and purged at runtime through the web UI (“Manage repos”) or the REST API — there is no CLI command to create one, and MCP cannot create repos at all. No repo is privileged: knomit starts with none, and archiving your last one is allowed (it stays restorable). Because nothing falls back to a default name, commands that act on a repo make you name one: knomit verify needs --repo unless you pass --all, and knomit-bridge needs exactly one of --repo or --lens.

Connect an agent over MCP

The simplest setup uses knomit-bridge over stdio — it auto-discovers your agent branch from the running server, so you never look it up by hand.

Claude Code (.mcp.json)

{
  "mcpServers": {
    "knomit": {
      "command": "dist/knomit-bridge",
      "args": ["--repo", "core"]
    }
  }
}

To read across several repos at once, use a lens instead: "args": ["--lens", "<lens-name>"]. --lens and --repo are mutually exclusive — passing both is a fatal error.

Streamable HTTP

Connect directly, substituting the branch logged on startup (/ → : in the URL path):

{
  "mcpServers": {
    "knomit": {
      "type": "streamable-http",
      "url": "http://localhost:19278/api/v1/repos/core/branches/agent:hostname-abc123/mcp"
    }
  }
}

A lens has no branch segment — its URL is http://localhost:19278/api/v1/lenses/<lens-name>/mcp.

Let the bridge write this for you

knomit-bridge claude init scaffolds the Claude Code integration into the current directory: the .mcp.json above, .claude/settings.json, ten /knomit-… skills, and a block appended to CLAUDE.md. Where one of those already exists it drops a companion file beside it rather than overwriting your version. See Claude Code.

The tools are usable without any of it — their descriptions carry the guidance a model needs to call them correctly. What the skills and the CLAUDE.md block add is when to reach for them: recall before touching an unfamiliar area, record a decision once it is made, re-verify a fact before relying on it.

Write your first fact

With an agent connected, ask it to remember something. Under the hood it calls knomit_learn, which writes a markdown fact and commits it:

---
type: observation
confidence: 0.8
domain: [music]
entities: [alice]
refs:
  - src://myrepo/src/preferences.ts@abc1234
---
Alice prefers rock music over jazz.

That write is one atomic, signed git commit on your agent’s branch. Browse it in the web UI, or query it back with knomit_query.

Where to next

Give your agent a knowledge base

Wire knomit into Claude Code or Claude Cowork — slash commands, hooks, and the bridge.

Understand the model

Read Concepts for facts, branches, provenance, and the temporal graph — then Ontologies to shape what your KB will accept.

See how it fits together

The Overview & architecture — the four artifacts and how a request flows.

Wire it into tools

The MCP tools reference and the REST API.

Publish what you learn

OKF export — turn the knowledge base into a portable Open Knowledge Format repository anyone can read.