Overview & architecture

knomit = knowledge + commit. It is a git-backed, temporal knowledge base for AI agents: every fact is a Markdown file committed to git, so the full history of belief is a git history, and provenance is cryptographically signed per commit.

Knowledge is reached over two surfaces:

• an MCP server — cognitive tools (learn, query, explain, update, retract, review, hypothesize) plus knomit_repos, which reports the mounts behind the current binding, and
• a REST API (/api/v1, HAL+JSON, commit-anchored URIs) that the web UI and any HTTP client use.

The four shipped artifacts

Artifact	Binary	What it is
Server	knomit	The core HTTP server. Serves the REST API, the MCP endpoint, the embedded web UI, and (optionally) a git smart-HTTP endpoint. CGO build (ONNX Runtime + graphqlite).
Desktop app	knomit-desktop	A Wails v3 tray/desktop app that boots the server in-process on a loopback port and shows the web UI in a native webview. Ships as Knomit.app on macOS; a binary on Linux, where make desktop-install adds the .desktop launcher and icon. See Desktop app.
Bridge	knomit-bridge	A small pure-Go adapter. Its primary job is a stdio ↔ HTTP MCP proxy that an MCP client (Claude Code, Claude Desktop, Claude Cowork) spawns to talk to the server. It also scaffolds Claude Code integration and runs the editor hooks.
OKF exporter	knomit-okf	A standalone CLI that publishes a knowledge base as a portable Open Knowledge Format repository. It talks to the git endpoint and nothing else — no server, database, or cache is involved in an export. Pure Go, like the bridge.

A fifth layer, the web UI (React/TypeScript), is built to static assets and embedded into both knomit and knomit-desktop. There is no separately deployed frontend.

Note

Build-only tools (not shipped to users): fetchlibs downloads the native libs, calibrate derives per-model retrieval thresholds, and drone runs implementation plans unattended.

How a request flows

Git is the only source of truth; the SQLite store is a rebuildable cache the server indexes for search, the graph, and the commit log.

• The bridge discovers the running server through a lockfile (server.json, written by the desktop app/tray) or a base URL. In repo mode it resolves the agent branch and forwards JSON-RPC to …/repos/{repo}/branches/{branch}/mcp; in lens mode it skips branch discovery and posts to …/lenses/{lens}/mcp, leaving each mount’s branch for the server to resolve.
• The server translates tool/HTTP calls into fact reads and writes. Git is the only source of truth; the SQLite index (per repo, under KNOMIT_HOME/repos/<name>.db) is a rebuildable cache for search, the graph, and the commit log.

The core model, in one paragraph

A repo is one knowledge base; a fresh install has none, and no repo is privileged. Each machine writes only its own agent branch (agent/<host>-<fp8>); main is consensus and is never written directly by the MCP server — agreement is reached by merging agent branches into main. A fact is a Markdown file with YAML frontmatter (kind, type, domain, entities, confidence, sources, refs, evidence_weight, origin). It can be revised and retracted, but only by commit, so its history is immutable and every past version stays readable. Topic and category are not frontmatter keys — they are path segments in kb/<topic>/<category>/<uuid8>.md, where the uuid8 is allocated at creation and never derived from the content, so a fact keeps its identity across every edit. Both are passed as knomit_learn arguments. Reads are commit-anchored: a fact resolves at a commit, not at HEAD, so the graph can be walked as of any point in history.

See Concepts for the full conceptual model; the rest of this section is the operational and reference surface.