ktx wiki

List, search, and read wiki pages in your ktx project. Wiki pages are Markdown documents that capture business definitions, rules, and gotchas. Agents search them for context when answering questions about your data.

Command signature

ktx wiki [options] [query...]  # list (bare) or search (with query)
ktx wiki read <key>

• Bare ktx wiki lists local wiki pages.
• ktx wiki <query...> searches local wiki pages. Multi-word queries are joined with a space.
• ktx wiki read <key> prints the whole Markdown file for one wiki page, including YAML frontmatter.

Edit the Markdown files under wiki/ directly, or ingest source content with ktx ingest, when you need to add or update wiki knowledge.

Options

-c, --connection <id> takes a connection id from the connections map in ktx.yaml (an unknown id is rejected). It narrows both list and search to pages that are not tied to any connection plus pages tagged with that connection, so an agent working against one database sees only the wiki knowledge relevant to it.

ktx wiki <query> uses hybrid search when storage.search is sqlite-fts5. ktx combines lexical SQLite FTS5 matches, token matches, and semantic matches from wiki page embeddings stored in .ktx/db.sqlite. If embeddings are not configured or the embedding backend is unavailable, ktx skips the semantic lane and keeps lexical and token results.

Examples

# List all wiki pages
ktx wiki

# List all wiki pages as JSON
ktx wiki --json

# Search wiki pages
ktx wiki "monthly recurring revenue"

# List pages scoped to one connection (unscoped + connection-tagged)
ktx wiki --connection warehouse

# Search within one connection's scope
ktx wiki "monthly recurring revenue" -c warehouse

# Search wiki pages as JSON
ktx wiki "monthly recurring revenue" --json --limit 10

# Print the exact Markdown file for a known page key
ktx wiki read revenue-definitions

# Print search results as TSV
ktx wiki "monthly recurring revenue" --output plain

# Inspect which search lanes were used
ktx --debug wiki "monthly recurring revenue" --json

Output

Wiki commands print clack-style pretty output in a TTY and TSV-style plain output when requested. JSON output wraps the items with a command metadata envelope. Search results include matchReasons and lanes metadata so you can see whether lexical, token, or semantic search contributed to the ranking. Use ktx wiki read <key> when you need the full page contents. Read output is the exact Markdown file stored on disk, including YAML frontmatter, and is not wrapped in pretty, plain, or JSON formatting. Pretty search output shows #1, #2, and later rank badges for the displayed results. Plain and JSON output keep the raw score value, which is a ranking score rather than a percentage.

{
  "kind": "list",
  "data": {
    "items": [
      {
        "key": "revenue-definitions",
        "summary": "Canonical revenue metric definitions",
        "score": 0.92,
        "matchReasons": ["lexical", "semantic"],
        "lanes": [
          {
            "lane": "lexical",
            "status": "available",
            "requestedCandidatePoolLimit": 25,
            "effectiveCandidatePoolLimit": 25,
            "returnedCandidateCount": 3,
            "weight": 1.5
          },
          {
            "lane": "semantic",
            "status": "available",
            "requestedCandidatePoolLimit": 25,
            "effectiveCandidatePoolLimit": 25,
            "returnedCandidateCount": 8,
            "weight": 3
          }
        ]
      }
    ]
  },
  "meta": {
    "command": "wiki search"
  }
}

When you pass the global --debug flag, ktx writes search diagnostics to stderr and leaves stdout unchanged. This is useful with --json because stdout stays machine-readable:

[debug] wiki search mode=sqlite-fts5 embedding=configured results=2
[debug] wiki search lane=lexical status=available returned=1 weight=1.5
[debug] wiki search lane=token status=available returned=1 weight=0.75
[debug] wiki search lane=semantic status=available returned=2 weight=3

Common errors