Configuration

Configuration is layered, lowest to highest precedence:

1. Defaults — internal/config/config.go Defaults(), the single source of truth.
2. knomit.toml — searched next to the binary, then at KNOMIT_HOME/knomit.toml.
3. Environment variables — overlay any value that is set (non-empty).

KNOMIT_HOME is resolved first (it is the config search root) and therefore cannot be overridden from inside the TOML file.

Caution

Malformed numeric or duration env values fail at boot rather than being silently ignored — a typo in KNOMIT_PORT or a duration knob stops the server, it doesn’t fall back to the default.

KNOMIT_HOME and the data layout

KNOMIT_HOME (default ~/.knomit) is the single root for all runtime data. KNOMIT_REPO is a backward-compatible alias. Everything else derives from it:

$KNOMIT_HOME/
├── knomit.toml                 # optional config file
├── repos/
│   ├── trunk.db                # the default repo (SQLite cache; git is source of truth)
│   ├── trunk.db-shm / -wal     # SQLite sidecars
│   ├── trunk.sessions.db       # ephemeral: tool cursors + pipeline work-steal sessions
│   ├── <name>.db               # any additional repo (auto-discovered by *.db glob)
│   └── archive/
│       ├── <ksuid>.db          # archived (deleted-but-recoverable) repo
│       └── <ksuid>.json        # archive manifest {id, repo_name, archivedAt, originURL}
├── models/
│   └── embeddinggemma/         # cached ONNX model + tokenizer
├── bin/
│   └── knomit-bridge           # symlink the desktop app creates on launch
├── id_ed25519 / .pub           # agent SSH key (signs commits; derives credential-encryption key)
└── …

Repos are discovered by scanning repos/ for *.db files at startup (and at runtime via POST /api/v1/repos:rescan); the filename minus .db is the repo name, and names must match [a-z0-9_-]+.

Note

The *.sessions.db sidecar is not opened as a repo — repo discovery globs repos/*.db and filters session DBs out.

The default repo

The default repo is named trunk (config.DefaultRepoName), stored at repos/trunk.db. It is opened first on startup and initialized on first run. “trunk” is only the repo name — the MCP server name and the git committer identity are both still knomit.

Server discovery lockfile

server.json is written by the desktop app/tray on startup and read by knomit-bridge to find the running server’s port. Contents are {pid, port, version}, mode 0600, written atomically (write-then-rename). Its location is not under KNOMIT_HOME:

• macOS: ~/Library/Application Support/knomit/server.json
• Linux: $XDG_STATE_HOME/knomit/server.json (default ~/.local/state/knomit/server.json)

knomit.toml

Place a knomit.toml next to the binary or at KNOMIT_HOME/knomit.toml. Top-level keys are bare (not under a table); the rest are [tables]. Defaults shown:

# --- top-level ---
repo            = "~/.knomit"   # KNOMIT_HOME (the TOML key is "repo"); resolved before TOML, so setting it here is a no-op
host            = "localhost"
port            = "19278"
socket          = ""            # Unix socket path (alternative to host:port)
ontology_root   = "kb"          # path within git where facts live
onnx_lib_path   = ""            # override the ONNX Runtime shared library
local_origin_root = ""          # root for permitted local-path git origins ("" = disabled)
read_only       = false         # read-only demo: reject mutations, hide git + write tools, pull-only sync
methodology_min_score = 0.15    # composite-score floor for methodology candidates

[llm]
model    = "gemini-2.5-flash"
provider = "gemini"
api_key  = ""
cache    = false
batch    = false

[embeddings]
model = "embeddinggemma"

[git]
origin          = ""            # remote URL for the default repo
serve           = true          # expose the built-in git smart-HTTP server
port            = ""            # git-serve port
network_timeout = "120s"        # bounds every remote git network op (clone/fetch/push)

[remote]
token       = ""                # GitHub/PAT token
user        = ""
password    = ""
ssh_key     = ""                # path to an SSH private key
auth_method = ""                # "token" | "basic" | "ssh" | "none" (inferred if empty)

[cluster_cache]
resolution         = 4.0        # Louvain γ (higher = more, smaller communities)
min_community_size = 2          # communities smaller than this are relabelled as noise

[session]
tool_idle_ttl     = "15m"       # query/explain cursor TTL
pipeline_idle_ttl = "60m"       # review/hypothesize work-steal session TTL
sweep_interval    = "5m"        # reaper cadence (never disabled)

[discovery]
effort_default         = "normal"  # "normal" | "medium" | "high"
confidence_threshold   = 0.5       # min confidence to write a discovered proposal
blast_radius_threshold = 1         # min reach for a backward keystone proposal (0 = off)
bridge                 = "both"    # "domain" | "entity" | "both"

[log]
format          = "console"     # "console" (human, stderr) | "json" (structured, stdout)
level           = "info"        # zerolog level: trace|debug|info|warn|error|fatal|panic
file            = ""            # non-empty adds a rotating JSON file sink (lumberjack)
max_size_mb     = 10            # rotate the file sink at this size
max_backups     = 3            # rotated files to keep
max_age_days    = 7            # max age for rotated files
slow_request_ms = 1000          # log HTTP/MCP requests slower than this at WARN (0 = off)
crash_file      = ""            # non-empty redirects fd 2 (stderr) to persist fatal/CGO tracebacks

[runtime]
addr = ""                       # diagnostics port (pprof + /metrics + /runtime/*); "" = off. Bind local only.

Environment variables

Config-backed (override knomit.toml)

Variable	Overrides	Default
KNOMIT_HOME (or KNOMIT_REPO)	data root	~/.knomit
KNOMIT_HOST	host	localhost
KNOMIT_PORT	port	19278
KNOMIT_SOCKET	socket	—
KNOMIT_READ_ONLY	read_only	false
KNOMIT_LOCAL_ORIGIN_ROOT	local_origin_root	— (disabled)
ONNXRUNTIME_SHARED_LIBRARY	onnx_lib_path	—
KNOMIT_EMBED_MODEL	embeddings.model	embeddinggemma
KNOMIT_LLM_MODEL	llm.model	gemini-2.5-flash
KNOMIT_LLM_PROVIDER	llm.provider	gemini
KNOMIT_API_KEY	llm.api_key	—
KNOMIT_LLM_CACHE	llm.cache	false
KNOMIT_LLM_BATCH	llm.batch	false
KNOMIT_GIT_ORIGIN	git.origin	—
KNOMIT_GIT_SERVE	git.serve	true
KNOMIT_GIT_PORT	git.port	—
KNOMIT_GIT_NETWORK_TIMEOUT	git.network_timeout	120s
KNOMIT_REMOTE_TOKEN	remote.token	—
KNOMIT_REMOTE_USER	remote.user	—
KNOMIT_REMOTE_PASSWORD	remote.password	—
KNOMIT_REMOTE_SSH_KEY	remote.ssh_key	~/.knomit/id_ed25519
KNOMIT_REMOTE_AUTH	remote.auth_method	auto-detected
KNOMIT_METHODOLOGY_MIN_SCORE	methodology_min_score	0.15
KNOMIT_CLUSTER_CACHE_RESOLUTION	cluster_cache.resolution	4.0
KNOMIT_CLUSTER_CACHE_MIN_COMMUNITY_SIZE	cluster_cache.min_community_size	2
KNOMIT_SESSION_TOOL_IDLE_TTL	session.tool_idle_ttl	15m
KNOMIT_SESSION_PIPELINE_IDLE_TTL	session.pipeline_idle_ttl	60m
KNOMIT_SESSION_SWEEP_INTERVAL	session.sweep_interval	5m
KNOMIT_DISCOVERY_EFFORT_DEFAULT	discovery.effort_default	normal
KNOMIT_DISCOVERY_CONFIDENCE_THRESHOLD	discovery.confidence_threshold	0.5
KNOMIT_DISCOVERY_BLAST_RADIUS_THRESHOLD	discovery.blast_radius_threshold	1
KNOMIT_DISCOVERY_BRIDGE	discovery.bridge	both
KNOMIT_LOG_FORMAT	log.format	console
KNOMIT_LOG_LEVEL	log.level	info
KNOMIT_LOG_FILE	log.file	— (stderr/stdout only)
KNOMIT_LOG_MAX_SIZE	log.max_size_mb	10
KNOMIT_LOG_MAX_BACKUPS	log.max_backups	3
KNOMIT_LOG_MAX_AGE	log.max_age_days	7
KNOMIT_LOG_SLOW_MS	log.slow_request_ms	1000
KNOMIT_CRASH_LOG	log.crash_file	— (off)
KNOMIT_RUNTIME_ADDR	runtime.addr	— (off)

Provider credentials (read directly)

These are read by the LLM adapters, not through knomit.toml:

Variable	Purpose
ANTHROPIC_API_KEY	Anthropic API key
GOOGLE_AI_API_KEY	Gemini API key
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	AWS credentials for Bedrock
AWS_REGION	AWS region for Bedrock (default us-east-1)

Standalone knobs (no TOML key)

Variable	Read by	Purpose	Default
KNOMIT_REFLECT_PROPOSE_CAP	synthesize/reflect	Max new methodologies a reflect step may propose (0 = none)	1
KNOMIT_REFLECT_NOVELTY_THRESHOLD	synthesize/reflect	Cosine floor to reject near-duplicate methodologies	0.85 (model-dependent)
KNOMIT_BASE_URL	knomit-bridge	Override the discovered server URL	http://localhost:19278
KNOMIT_MCP_DEBUG	knomit-bridge	Non-empty → debug logging	— (info)

Note

KNOMIT_PPROF_ADDR was replaced by the gated runtime diagnostics port (KNOMIT_RUNTIME_ADDR), which serves pprof, Prometheus /metrics, expvar, and live process controls together. See Observability.

LLM configuration

Synthesis is the only LLM-backed feature. Configure a provider via the model name and credentials:

Provider	Variables
Gemini (default)	KNOMIT_LLM_MODEL=gemini-2.5-flash · GOOGLE_AI_API_KEY=…
Anthropic	KNOMIT_LLM_MODEL=claude-sonnet-4-6 · ANTHROPIC_API_KEY=…
Bedrock	KNOMIT_LLM_MODEL=us.anthropic.claude-sonnet-4-6-v1 · AWS_ACCESS_KEY_ID=… · AWS_SECRET_ACCESS_KEY=…
Claude CLI	KNOMIT_LLM_PROVIDER=claude-cli — uses the claude CLI (no API key; works with Anthropic Max)
Gemini CLI	KNOMIT_LLM_PROVIDER=gemini-cli — uses the gemini CLI (no API key; works with Google AI Pro)

For API providers the provider is auto-detected from the model name; CLI providers must be set explicitly via KNOMIT_LLM_PROVIDER. Embeddings are a separate, local model and never call an LLM — see Embeddings.

No key, no problem — for reads

If you only browse, search, and query, you never need an LLM key. It’s required only to run synthesis. A read-only instance (like the public demo) needs no provider credentials at all.

Verifying integrity

The knomit verify subcommand runs integrity checks against a live on-disk repo (read-only, but it takes per-branch locks — stop any writing agent for a clean snapshot):

knomit verify                 # verify the default repo
knomit verify --repo work     # verify a specific repo
knomit verify --all --deep    # every repo, including per-fact format checks

See the CLI reference for every flag and exit code.