docs
/

●  meerkat · knows

meerkat

A knowledge base compiled into a single static Go binary and served three ways — CLI, MCP, and HTTP — so your developers and agents start from what is actually true at your org.

meerkat embeds a Markdown wiki into the binary at build time and exposes it as a CLI (mk search/show/list), an MCP server over stdio for agent harnesses, and an HTTP/OpenAPI server with bearer auth for tools like OpenWebUI. Because content is embedded, search works fully offline with zero runtime dependencies. It is the knows leg of the platform.

No credentials in the binary

The binary ships with no LLM credentials and is read-only over the knowledge base. The only "live" action — ingestion — shells out to your agent CLI, running under your own account.

Installation

The binary is meerkat, with a short alias mk. The repo is private, so authenticate gh once and mk update reuses the token.

install — macOS arm64bash
gh auth login
TAG=v0.4.0
PLATFORM=darwin_arm64
mkdir -p ~/.local/bin
gh release download "$TAG" --repo zegit-zoo/meerkat \
  -p "meerkat_${TAG#v}_${PLATFORM}.tar.gz" --output - \
  | tar -xz -C ~/.local/bin meerkat
ln -sf meerkat ~/.local/bin/mk
meerkat version

Keep current with mk update --check then mk update. Releases are cosign-signed; mk update verifies the checksum and signature before an atomic swap.

Core concepts

Content sources

The wiki body, the ingestion source registry, prompts, and templates are configuration, pulled from a content source at build time. The mechanism is content-source.yaml (copy from the example). If absent, the build uses empty placeholders — which is the open-source default.

content-source.yamlyaml
content:
  type: git              # none | local | git | submodule
  repo: your-org/meerkat-kb
  host: github           # github | gitlab — selects the gh/glab token
  ref: v1.2.0            # tag or commit SHA (pin for reproducibility)
  layout:
    wiki:      wiki                    # markdown pages
    sources:   ingestion/sources.yaml  # the source registry
    prompts:   ingestion/prompts       # per-source prompts
    templates: templates               # page templates

Ingestion

meerkat is the planner; an agent CLI (OpenCode by default) is the executor. Pages begin as placeholders pointing at an upstream source; mk ingest renders one task per page, and mk ingest --execute spawns an agent session per page (under a wall-clock cap) to write the page, commit, and push.

terminalbash
mk ingest sources                       # list the source registry
mk ingest --source policies             # plan only (writes a JSONL batch)
mk ingest --source policies --execute --max-parallel 4

An in-process Bleve BM25 index over the embedded markdown — no external service, no network, no embedding model. Built in-memory at startup; three indexed fields with boosts (title ×5, id ×3, body ×1). The body field accepts Bleve query strings.

Frontmatter filtering is post-search

Field filters like --owner compose after the BM25 query — frontmatter is not yet indexed, so don't present owner:team-x as a working query term.

Next

CLI & integrations

Every mk command, plus the OpenCode (MCP) and OpenWebUI (HTTP) integrations.

Read

mongoose

The harness that wires meerkat in by default.

Read
PreviousError codes

Authoritative reference, generated from the component repos. Spot something stale? Tell us.