alex09x/kyb

What it claims

KYB is a single Rust server that acts as shared operational memory for coding agents. It is not a vector-DB wrapper: Git is the only store, and the search index is a cache that the server can throw away. The server gives three entry kinds different lifecycles:

• knowledge (plain notes)
• incidents (inc- keys, open → mitigated → resolved)
• tasks (task- keys, open → in_progress → blocked → done | dropped)

Closing an incident, or moving a task to done or dropped, requires a written resolution. The closed entry is archived: its file leaves the working tree, but it stays in default search. Deleting a knowledge entry is different. It counts as a retraction and drops out of default search, though Git keeps the history.

How it works

flowchart LR
  Q[query] --> S{--as-of?}
  S -- yes --> Snap[pick one version per key at date]
  S -- no --> Live[latest + history if --history]
  Snap --> B[Tantivy BM25]
  Live --> B
  Snap --> V{e5 model on disk?}
  Live --> V
  V -- yes --> E[int8 e5-small vectors]
  V -- no --> L[lexical only]
  B --> R[RRF fusion]
  E --> R

• Index rebuild: The Tantivy index is rebuilt from Git every time the server starts. It covers every historical version of every key.
• As-of queries: --as-of picks the snapshot first and searches it second. A superseded version never answers for its key, and knowledge deleted by that date is absent.
• Vector search: The vector side uses multilingual-e5-small in int8 ONNX, held in memory and running on CPU in about 5 ms. If no model is on disk, the server falls back to lexical search only.
• Writes: Writes are upserts by key, and a write with unchanged content is a no-op. There is a flat key space plus tags, with no namespaces. All writes go through one write mutex, while reads are lock-free.
• Structure hints: The server accepts incomplete incident reports but returns hints naming the missing parts.

Evidence

scripts/eval-search.sh scores paraphrase questions at top-1 and top-3. On a 643-entry base (2026-09-22, over LAN), the author says hybrid search roughly doubles the hit rate over BM25 alone.

The author also says the absolute numbers are not meaningful:

• The 14 bundled questions were written against a different base.
• Three of their expected keys do not exist in the measured base.
• An earlier hybrid result of 9/14 and 12/14 did not reproduce on another base.

The fetched text does not include the table's actual figures. The test suite has 421 cases. CI smoke-tests the container and drives the web UI with a browser test.

How to use it

Start the server with one of these:

cargo install knowyourbusiness --locked
kyb-server            # listens on 127.0.0.1:9310

docker compose up -d
KYB_PUBLISH_ADDR=10.0.0.10 docker compose up -d

The client CLI and the skill are installed separately. skills/install.sh also injects pointer sections into each agent's global instructions:

bash skills/install.sh
npx skills add alex09x/kyb

Register the MCP endpoint, which needs no client install:

claude mcp add --transport http kyb http://<host>:9310/mcp

Turn on authentication with tokens:

kyb-server auth add --id agent-a --name "Agent A" --role write --label build-box
echo "$TOKEN" | kyb login

The CLI covers temporal queries and export:

• kyb query "" --changed-between 2026-08-01,2026-08-07
• kyb diff <key>
• kyb get <key> --at <sha>
• kyb export --out kyb.jsonl

The e5 model ships in the Docker image (set via the MODEL_REPO build arg). With a cargo install you must set up the model yourself, otherwise search is lexical only.

Limits

• Open by default: KYB_AUTH=off is the default, so POST /knowledge and DELETE answer unauthenticated. /mcp is exactly as open as the REST API.
• No TLS: The server speaks plain HTTP. Tokens can be replayed by anyone who can watch the traffic, so beyond a trusted LAN or VPN you need a TLS proxy in front.
• compat mode: It lets callers through simply by omitting the token. Never expose it externally.
• ?readonly=1 on MCP: This only hides the six write tools from the agent. It is not a security boundary.
• Attribution is self-reported: Commit authorship and the Kyb-Agent/Kyb-Session trailers are what clients claim. Anyone with direct repository access can forge them.
• Secret scanning: It rejects bodies that look like a token, private key or password. That is pattern-based, not a guarantee.
• Write throughput: A single write mutex serialises all writes.
• English entries: The skill tells agents to write entries in English, even though search is multilingual.
• Licence: The page does not state one. Check it before adopting. The citable release is v0.3.0 (DOI 10.5281/zenodo.23309457).