Skip to content

configuration.md

Latest commit

 

History

History
241 lines (181 loc) · 6.65 KB

configuration.md

File metadata and controls

241 lines (181 loc) · 6.65 KB
Raw

Configuration

Knowns stores project configuration in .knowns/config.json.

This file describes what the project wants Knowns to manage locally, including platform integrations, semantic search settings, and generated artifact behavior.

Example

{
  "name": "my-project",
  "settings": {
    "defaultTaskIdPrefix": "KN",
    "gitTrackingMode": "git-tracked",
    "gitTracking": {
      "tasks": true,
      "docs": true,
      "templates": true,
      "memories": false
    },
    "semanticSearch": {
      "enabled": true,
      "model": "qwen3-embedding:0.6b",
      "provider": "ollama",
      "dimensions": 1024
    },
    "platforms": [
      "claude-code",
      "opencode",
      "codex",
      "kiro",
      "antigravity",
      "cursor",
      "gemini",
      "copilot",
      "agents"
    ],
    "lsp": {
      "enabled": true
    }
  }
}

Important settings

name

The project name shown in Knowns surfaces.

settings.gitTrackingMode

Controls how Knowns manages Git-related generated content.

Supported values:

  • git-tracked
  • git-ignored
  • none

Behavior:

  • git-tracked: keep .knowns/ content tracked in Git
  • git-ignored: keep config/docs/templates tracked while leaving some local data out of Git depending on generated ignore rules
  • none: do not let Knowns manage .gitignore

settings.defaultTaskIdPrefix

Optional default for newly generated task IDs. KN produces IDs such as KN-4F7Q2M.

  • 2-8 alphanumeric characters
  • must start with a letter
  • normalized to uppercase
  • independent of task type; callers may use any valid one-off prefix
  • changing or clearing it affects future tasks only
  • when unset, new IDs take a prefix derived from the project name (Knowns gives KN); existing IDs are never rewritten

Configure it with the init wizard, knowns init --task-prefix KN, knowns settings, the Web settings page, or:

knowns config set settings.defaultTaskIdPrefix KN

knowns settings --global can set the default copied into future projects.

settings.gitTracking

Per-section git tracking toggles. Controls which .knowns/ subdirectories are included or excluded in .gitignore.

Field Default Description
tasks true Track task markdown files
docs true Track documentation files
templates true Track code generation templates
memories false Track AI memory entries

settings.semanticSearch

Controls local semantic search.

Relevant fields:

  • enabled
  • model
  • provider ("ollama", or a provider ID registered with knowns provider add)
  • dimensions
  • vectorStore (backend, mode, externalURL, managedRoot, install, retention) - selects and provisions the vector backend. Defaults to a Knowns-managed local Qdrant, so most projects never set it. See External Qdrant to connect to a Qdrant you run yourself.

A project written before the Ollama-only change may still carry "provider": "local". It is read as "ollama" with the default model, and knowns migrate rewrites it on disk when you choose to.

Common behavior:

  • knowns init can set these values
  • knowns settings lists the embedding models Ollama is already serving
  • knowns provider add registers an OpenAI-compatible provider; select one of its models with knowns config set settings.semanticSearch.model <name>
  • knowns sync can re-apply the semantic setup
  • knowns search --reindex rebuilds the local index
  • See Ollama Embedding Models for recommended models, install/pull commands, and the shape of a third-party OpenAI-compatible provider entry

settings.lsp

Controls LSP-based code intelligence.

  • enabled: whether LSP servers are started for code navigation

settings.platforms

Declares which platform integrations Knowns should manage.

Supported values:

  • claude-code
  • opencode
  • codex
  • kiro
  • antigravity
  • cursor
  • gemini
  • copilot
  • agents

This setting affects what knowns setup, knowns sync, and knowns update create or refresh.

Examples of managed artifacts:

  • instruction files
  • skills
  • MCP config
  • runtime hooks
  • platform-specific config files

settings.autoSyncOnUpdate

Controls whether generated artifacts should be refreshed after upgrading the CLI.

Practical rules

When to edit config manually

You can edit .knowns/config.json directly if you know what you are doing, but the normal path is:

  • knowns init for first-time setup (project structure + git tracking)
  • knowns init also creates selected lightweight project instruction shims such as CLAUDE.md and AGENTS.md
  • knowns setup <target> --global for normal personal AI platform integrations such as MCP/config files, skills, and runtime hooks
  • knowns setup <target> only when you intentionally want repo-local integration files
  • knowns setup agents when you only need repo-local agent shims
  • knowns settings for the interactive project settings center
  • knowns settings --global for defaults reused by future knowns init runs
  • knowns config get/set/list/reset for scriptable config access
  • knowns sync to re-apply config to the current machine

Settings and config shorthands

# Interactive project settings UI
knowns settings
# Shows:
#   Project
#   Git Tracking
#   AI Platforms
#   Search
#   Code Intelligence
#   Maintenance
#   Done

# Defaults for future projects
knowns settings --global

# Or set directly via the scriptable config API
knowns config set embedding true       # Enable semantic search
knowns config set lsp true             # Enable LSP globally
knowns config set lsp.go true          # Enable LSP for Go

# Git Tracking (per-section)
knowns config set gitTracking.tasks true
knowns config set gitTracking.memories false

Changing gitTracking.* toggles automatically regenerates .gitignore.

Interactive knowns init needs a terminal at least 90 columns wide. If the terminal is too small, Knowns prints resize and --no-wizard guidance and stops without initializing by defaults.

When to use knowns sync

Use knowns sync after:

  • cloning a repo with existing .knowns/
  • updating the CLI
  • wanting to restore generated artifacts to match config

Platform-related compatibility

Current skills mapping:

  • .claude/skills -> Claude Code
  • .agents/skills -> OpenCode, Codex, Hermes Agent, Antigravity, Generic Agents
  • .kiro/skills -> Kiro

Related commands

knowns init
knowns setup
knowns settings
knowns sync
knowns config set <key> <value>
knowns config get <key>
knowns migrate
ollama pull qwen3-embedding:0.6b
knowns search --status-check
knowns search --reindex