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), and
• a REST API (/api/v1, HAL+JSON, commit-anchored URIs) that the web UI and any HTTP client use.

The three 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 looknomitck port and shows the web UI in a native webview. Ships as Knomit.app on macOS; a binary + .desktop launcher on Linux. 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.

A fourth UI 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, resolves the agent branch, and forwards JSON-RPC to …/branches/{branch}/mcp?profile=code.
• 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 (default: trunk). 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. Facts are immutable, content-addressed Markdown with YAML frontmatter (topic, category, kind, type, domain, entities, confidence, sources, refs). 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.