Optional AI

Structured CLI/MCP storage, retrieval, governance, lifecycle, file-backed skills, and synthesis operate without a generative AI provider. AI is required for knowl ask, explicitly supplied raw text through CLI or MCP ingest, and the configured filter → extract → verify → merge pipeline. When configured, AI can also assist CLI decision comparison and best-effort MCP state derivation. Deterministic writes remain available without it.

Use provider-specific model identifiers appropriate to the service rather than relying on a hard-coded recommendation:

# OpenAI
knowl config set ai.provider openai
knowl config set ai.model provider-model-id
knowl config set ai.apiKey '${OPENAI_API_KEY}'

# Anthropic
knowl config set ai.provider anthropic
knowl config set ai.model provider-model-id
knowl config set ai.apiKey '${ANTHROPIC_API_KEY}'

# Ollama's OpenAI-compatible local endpoint
knowl config set ai.provider ollama
knowl config set ai.model local-model-name
knowl config set ai.baseUrl http://localhost:11434/v1

# A custom OpenAI-compatible endpoint
knowl config set ai.provider custom
knowl config set ai.model provider-model-id
knowl config set ai.baseUrl https://provider.example/v1
knowl config set ai.apiKey '${CUSTOM_API_KEY}'

Environment-variable placeholders are resolved at runtime. Ollama can run without an API key. Deterministic knowl synthesize does not use this configuration.

ai.apiKey may be set literally, and .knowl/config.json is written owner-readable (0600) on POSIX systems and replaced atomically, so an interrupted write cannot leave a half file that loadConfig refuses to parse. Prefer an environment reference — the '${VAR}' form above — or the provider variables OPENAI_API_KEY and ANTHROPIC_API_KEY, so the credential never lands in a file inside the repository directory at all.