KYB MCP server
Commit Nov 10, 2026Provides a git-backed shared memory for AI agent fleets to manage a searchable knowledge base, incident reports, and task tracking.
Also known as alex09x/kyb
- Stars
- 67
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is KYB MCP?
KYB provides a git-backed shared memory for AI agent fleets to manage a searchable knowledge base, incident reports, and task tracking.
Summary generated from the project's README
About KYB MCP server
Providing a persistent, shared memory for AI agent fleets is what kyb enables. It allows multiple agents like Claude Code or Codex to maintain a searchable knowledge base, track incident reports, and manage tasks across different sessions and machines. By using Git as the source of truth instead of a traditional database, every change is recorded as a commit, providing built-in versioning, history, and rollback capabilities through markdown files.
Developers use the kyb CLI and MCP tools to interact with a Rust-based server that manages these records. The system features hybrid search, combining BM25 lexical matching with vector search via an optional multilingual-e5-small model. It includes specialized workflows for incident lifecycles, task management with deadlines, and a decision journal to record why certain technical choices were made. The server automatically rejects writes containing potential secrets like private keys to ensure security.
What you can do with it
- 1Maintain operational truthAn agent can record and search for information regarding which servers exist and how services are wired together.
- 2Document technical decisionsAn agent can use the decision journal to record the options considered and the final outcome of a technical choice.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
KYB_PUBLISH_ADDRKYB_VERSION
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablealex09x/kyb is public and reachablegithub.com/alex09x/kyb ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/alex09x/kyb ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubKYB — Know Your Business
The shared memory your AI agent fleet keeps forgetting it needs.
A git-backed, searchable knowledge base and incident tracker for fleets of AI agents. Which servers exist, how services are wired, what broke and how it ended — the operational truth that survives between sessions and across machines.
Website · By Alexander Panasenko
Quick start · How it works · Incidents · Agent skill · MCP · Web UI · HTTP API · Citation
Why
Agents forget everything between sessions. Multiple agents — Claude Code, Codex, Antigravity — on multiple machines rediscover the same infrastructure over and over, and every hard-won incident lesson evaporates the moment the context window closes.
KYB is the shared memory that survives: which servers exist and what runs on them, how services are wired, how they deploy, which decisions were made and why — plus incident reports: what broke, the impact, how to live with it, and how it ended.
How it works
- Git is the canon — there is no database. One markdown file (YAML frontmatter + body)
per entry — under
knowledge/,incidents/ortasks/by kind — one commit per change, a commit sha is a version id. History, diff and rollback come for free; the canon can be read and edited with any text editor. (Flat pre-v2 canons migrate themselves on start.) - The tree holds only what is live. Closing an incident or a task archives it: the
file leaves the working tree, but the final version — resolution included — stays in the
default search, in the listings and in
GET(markedarchived). Deleting plain knowledge is a retraction and drops it from the default search. Git keeps everything either way. - Tantivy is the index — a disposable cache rebuilt from git on every start. It covers
the latest version of every key and every historical version, so agents can search what
the knowledge said before it changed (
--history: "what moved where"). - Search is hybrid — BM25 fused (reciprocal rank) with vector search over every entry (multilingual-e5-small, int8 ONNX, runs locally on CPU in ~5 ms). Ask in one language about a base written in another and it lands; exact technical terms still rank first. No model on disk → the service runs lexical-only.
- Writes are upserts by key — a no-op when content did not change. Flat key space plus tags; no projects, no namespaces.
- Secrets never enter the base — writes are rejected if the body looks like a token, a private key or a password. Store pointers instead.
Architecture
Agents use the kyb CLI over HTTP. The Rust/axum server stores Markdown and history in Git,
then builds search state from that history. Tantivy provides BM25 search; an optional
multilingual-e5-small ONNX model supplies in-memory vectors. Reciprocal rank fusion combines
lexical and semantic candidates. All search modules run inside the server. Without a model,
lexical search still works.
Incident reports
Incidents are first-class entries (kind: incident, keys prefixed inc-) with a lifecycle
open → mitigated → resolved and a rule: closing requires a resolution — an incident
that ends with "it just went away" teaches nobody anything. A report is a control panel, not
a story:
| Field | What it gives an agent |
|---|---|
detection |
an executable "is it still happening?" check, with the expected healthy result |
affected |
machine-readable poisoned windows [{scope, from, to}] — a backtest excludes them programmatically |
knowledge |
links to the knowledge entries the incident concerns |
resolution |
how it ended — searchable, so "how did we fix this last time" has an answer |
| timeline | started/detected/mitigated/resolved_at; the server stamps status transitions |
| follow-ups | - [ ] checkboxes in the body; the server counts them and warns when closing over them |
The server teaches structure instead of gating on it: a bare report is accepted but the
reply carries hints naming the missing actionable parts. kyb incident --template prints
the canonical skeleton.
Resolving archives the report: the canon stays clean (open things only), the record stays searchable forever.
Tasks
The third kind (kind: task, keys prefixed task-): short actionable notes and ideas with
the same close-with-an-outcome discipline and none of the incident ceremony.
- Lifecycle —
open → in_progress → blocked → done | dropped. Onlydoneanddroppedare terminal: they require a resolution ("dropped: obsolete after the rewrite" is knowledge too) and archive the task.in_progressandblockedare work in flight — the task stays live in the canon, inkyb tasksand inopen_tasks. priority— optional,low | medium | high | critical; empty means unranked and stays unranked, nothing infers one. Exact filter onGET /tasksand/search.blocked_reason— optional, what the task waits on. It belongs tostatus: blockedonly: setting it on any other status is rejected, and moving offblockedclears it, so a task never reports a block it is no longer in.assignee— optional, who holds the task right now: a short public label (≤80 chars, single line, secret-scanned like every other field). Empty means unclaimed and stays unclaimed. Exact filter onGET /tasksand/search.parent_task— optional, thetask-key this one hangs under; empty means top-level. Must be a validtask-key and cannot create a parent cycle. A parent that does not exist yet is allowed — a child can be filed before its parent — and is reported back asunknown_parent.- Partial transitions —
POST /tasks/{key}/transition(kyb task-status) moves a task between the live statuses and optionally changes its owner, parent or deadline without resending title, body, tags, priority or links. Leavingblockedclears the reason; the terminal statuses are refused with a pointer tokyb done, because closing demands an outcome. - Deadlines — optional
due(YYYY-MM-DD, or a date-time with its zone),hard(a miss has consequences outside the team: an expiry, a contract or a regulator),remind_days(how early to start surfacing it; default 14, or 30 when hard), and for a date that depends on an event,waits_onwith a provisionalexpecteddate. A deadline field left out of a write keeps its stored value, so rewriting a task never drops its due date; moving one is a new version, visible inkyb historyandkyb diff. - Deadlines surface on their own — every read answer (
/search,/knowledge/{key},/tasks,/incidents, and so every CLI and MCP read) carries adeadlinesblock when an open task is late or inside its reminder window: up to five, the late ones first, then hard before soft and by date, with the days left — a distant hard deadline never pushes a late task out. Nothing due, no block. The CLI prints it as a short banner on stderr;--no-deadlines(?deadlines=false) leaves it off.kyb deadlinesis the full calendar: overdue, this week, later. A bare date is judged by the caller's calendar (the CLI sends its own date asX-KYB-Today); otherwise by the server'sTZ. KYB reminds, it never schedules: no notifications, no recurrence. - A brief before the work —
kyb brief(GET /brief, MCPkyb_brief) is what is live in the base, as pointers only: deadlines, open incidents by severity, active work (in progress, blocked, urgent), and knowledge retracted or changed in the last 7 days, with who wrote it. Each section is capped with "+N more", so it fits in about 40 lines. The skill and the MCP tool tell an agent to call it before infrastructure work, as context for its task and never as a to-do list. Nothing calls it automatically, so sub-agents do not each load it into their context. - A decision journal —
kyb confident(/confident, MCPkyb_confident_*). When an agent asks its owner to decide something, it opens a record: the decision as one English line, the target, the options, what it checked. It then records who decided what, in which words, and later what came of it (kept, corrected, reverted, dropped, with a ref to the evidence). Before the next question,kyb confident checkreturns earlier decisions about the same thing from other sessions, hazards (the same kind of step on the same target that went wrong or was never answered) and lint on the draft question. Records are JSON files in the same git repository, matched by the same embedding model, and never ranked by ordinary search. A precedent is evidence for the agent to judge, not permission. Every field is English, the owner's words translated; the server refuses a record in another script and names the word it found.
Closing archives the task; kyb tasks and the search keep the full record. Every write is a
commit, so kyb history <key> + kyb get <key> --at <sha> reconstruct who held a task, in
which status, at any point in time.
Quick start
curl -fsSL https://kybmemory.com/install.sh | bash
Or let an agent do it. Paste this into Claude Code, Codex or Antigravity:
Install KYB on this machine: read https://kybmemory.com/install.md and follow it step by step. Show me the plan before you install, and report what you verified.
It walks the agent through install.md: show the plan, install, check the server, the skill and a write, then report.
install.sh looks at the machine and picks how to run the server. Then it
installs the kyb CLI (~/.local/bin/kyb) and the agent skill for Claude Code, Codex and
Antigravity, pointed at that server. Run it again to upgrade. KYB_DRY_RUN=1 prints the plan and
changes nothing.
| Machine | Server | Also installed |
|---|---|---|
| macOS, Apple Silicon, Homebrew | brew install alex09x/apps/kyb + brew services (launchd) |
CLI, skill |
| macOS, Apple Silicon, no Homebrew | the release archive, SHA-256 checked against GitHub's digest; a launchd agent com.kybmemory.kyb-server, data in ~/kyb/data |
CLI, skill |
| Linux (amd64, arm64), or an Intel Mac with Docker | ghcr.io/alex09x/kyb via Docker Compose in ~/kyb, data in ~/kyb/data |
CLI, skill |
A server already answers on :9310 |
left as it is | CLI, skill |
Any machine, server elsewhere: KYB_MODE=client KYB_SERVER=<host> |
none | CLI, skill |
The settings are environment variables passed to bash: KYB_MODE, KYB_SERVER, KYB_VERSION,
KYB_DIR and KYB_PORT, documented at the top of the script. On Linux the installer needs
Docker Engine with the Compose plugin, usable by your user. Rootless Docker is detected and handled. KYB_MODE=native uses the archive on a Mac that has Homebrew too.
CI runs every path for real on clean runners. It checks that the skill landed for Claude Code, Codex and Antigravity, and that a rerun upgrades from the previous release.
By hand
# macOS, Apple Silicon
brew install alex09x/apps/kyb && brew services start kyb
# Docker: the server only, with the embedding model baked in (linux/amd64, linux/arm64)
mkdir kyb && cd kyb && curl -fsSLO https://kybmemory.com/docker-compose.yml
KYB_VERSION=v0.3.4 KYB_UID=$(id -u) KYB_GID=$(id -g) docker compose up -d
# crates.io: the kyb-server binary only, lexical search until KYB_MODEL is set
cargo install knowyourbusiness --locked && kyb-server
The compose file lists its settings. cargo install gives no kyb CLI
and no skill; add them with the installer in client mode or bash skills/install.sh from a
checkout (see CLI, The agent skill and
Search quality).
From repository checkout
# build and run from source with Mitts (https://github.com/alex09x/mitts)
curl -fsSL https://mittsbuild.com/install.sh | sh
mitts run --release --bin kyb-server
# docker — data (git canon + index) lives in ./data
docker compose up -d
# remote private-network clients: bind one exact interface, never every NIC
KYB_PUBLISH_ADDR=10.0.0.10 docker compose up -d
| Variable | Default | Notes |
|---|---|---|
KYB_DATA |
./kyb-data |
git canon directory |
KYB_INDEX |
./index |
Tantivy cache (safe to delete) |
KYB_ADDR |
127.0.0.1:9310 |
where to listen; with KYB_AUTH=off anyone who can reach it can write |
KYB_AUTH |
off |
off trusts the network, compat honours a token but does not ask for one (for rollout, on a trusted bind — it protects nothing), required refuses callers without one |
KYB_AUTH_FILE |
./auth.json (Docker: /data/auth.json) |
the token book; keep it on persistent storage beside the data, never inside kyb-data |
KYB_ANON |
(unset) | read: with KYB_AUTH=required, callers without a token may read (a public demo) |
KYB_PUBLISH_ADDR |
127.0.0.1 |
Docker Compose host interface; set one exact private IP for remote clients |
KYB_MODEL |
(unset) | dir with model.onnx + tokenizer.json; absent = lexical-only |
KYB_AUDIT |
audit.jsonl |
JSONL request log |
TZ |
UTC (Docker Compose) |
the server's time zone, e.g. America/Los_Angeles: whose "today" the deadline block uses for a caller that sends no X-KYB-Today (the CLI always sends its own) |
CLI
skills/kyb/bin/kyb (installed to ~/.local/bin/kyb; point it anywhere with KYB_ADDR=host:port):
kyb query "nats streams" [--tag infra] [--history] [--recent] [--kind incident] [--status open] [--service X]
kyb query "nats streams" --as-of 2026-08-01 # the base as it stood then: one version per key,
# the value that was current, not today's. The
# snapshot is chosen first and searched second: a
# superseded version never answers for its key,
# and knowledge deleted by then is absent
kyb query "" --changed-between 2026-08-01,2026-08-07 # what moved while you were away
kyb diff nats-streams [--from <rev>] [--to <rev>] # what changed in it (defaults to the two newest)
# The three above ask a server-version-dependent question, so the CLI checks
# /healthz first and refuses rather than let an older server answer a question
# about the past with today's data. Plain queries are unaffected.
kyb tags # which topics the base covers
kyb add --key nats-streams --title "..." --tags nats,infra <<< "body" # upsert by key
kyb get nats-streams [--at <sha>] # current or any historical version
kyb history nats-streams # the whole chain of changes
kyb export --out kyb.jsonl # every key as of one commit: active, archived and
# retracted, one JSON line each, checked complete
kyb incident --template # print the report skeleton
kyb incident --key inc-2026-07-22-orders-api-oom --title "..." --service orders_api \
--severity high [--hosts host-a] [--knowledge orders-api-architecture] \
[--detection "check + healthy result"] \
[--affected '[{"scope":"...","from":"...","to":"..."}]'] <<< "body"
kyb incidents [--status X] [--service X] [--open-followups] [--all] # live by default, --all adds archived
kyb resolve inc-2026-07-22-orders-api-oom <<< "what fixed it" # resolution is mandatory; closing archives
kyb task --key task-raise-log-retention --title "..." [--tags idea] \
[--priority high] [--status in_progress] [--assignee agent-a] <<< "body"
kyb task --key task-swap-disk --title "..." --status blocked \
--blocked-reason "waiting on the replacement disk" [--parent task-migrate-logs] <<< "body"
kyb task-status task-raise-log-retention --status in_progress --assignee agent-a # partial: nothing resent
kyb task-status task-swap-disk --status blocked --blocked-reason "waiting on the disk"
kyb tasks [--status X] [--priority P] [--assignee A] [--parent K] [--open-followups] [--all]
kyb done task-raise-log-retention <<< "what came of it" # or --status dropped + why
kyb task --key task-renew-api-cert --title "..." --due 2026-03-14 --hard [--remind-days 30] <<< "body"
kyb task --key task-answer-quote --title "..." --waits-on "the quote" --expected 2026-03-20 <<< "body"
kyb task-status task-renew-api-cert --due 2026-03-21 # move a deadline: a version, shown by kyb diff
kyb deadlines [--within 14d] [--overdue] [--hard] [--tag a,b] [--assignee A] [--json]
kyb brief [--tag a,b] [--service X] [--since 7d] [--limit N] [--json] # what is live, as pointers
kyb confident check "api: release patch vs minor after a fix" [--target api] # before asking the owner
kyb confident ask --gist "..." [--options "a|b"] [--proposed a] # when asking; prints the record id
kyb confident decided <id> --by owner --verdict choose_option [--quote "..."] [--ref <commit>]
kyb confident outcome <id> --result reverted --ref "PR #61" # later, by anyone
# every read above prints overdue and nearly due tasks as a banner on stderr; --no-deadlines omits it
The agent skill
bash skills/install.sh installs, for every agent found on the machine:
- the CLI and the MCP bridge (one copy of each on PATH),
- the manual
SKILL.md, - a pointer section in each agent's always-loaded global instructions — a skill an agent never opens is a skill it never uses.
| Agent | Skill path | Pointer |
|---|---|---|
| Claude Code | ~/.claude/skills/kyb |
CLAUDE.md |
| Codex | ~/.codex/skills/kyb |
AGENTS.md |
| Antigravity | ~/.gemini/config/skills/kyb |
GEMINI.md |
Idempotent: sections are delimited by markers and updated in place. The skill encodes the governance that keeps a shared base alive — always query before adding, overwrite the same key instead of inventing synonyms, only verified facts, English entries, file incidents when something breaks and fold the lesson back into knowledge after resolving.
Alternatively, install the skill into any supported agent workspace using the open skills CLI:
npx skills add alex09x/kyb
MCP
The server speaks MCP itself, at POST /mcp. Nothing is installed on the client:
claude mcp add --transport http kyb http://<host>:9310/mcp # Claude Code
codex mcp add kyb --url http://<host>:9310/mcp # Codex
agy mcp add -t http kyb http://<host>:9310/mcp # Antigravity
gemini mcp add -t http kyb http://<host>:9310/mcp # Gemini CLI
Cursor, Windsurf, VS Code and any other client that speaks MCP over HTTP take the same URL in
their own configuration file, in that client's schema (VS Code, for instance, lists it under
servers with type: http). That is the whole setup on the server side; attribution of writes
made over MCP depends on what the client sends - see Attribution. The tool list comes from the server, so upgrading the server is how
every connected agent gets new tools — there is no client to update, and no version of a
client that can disagree with the server about what exists.
A tool call is replayed through the same router that serves the public API, so there is one
implementation of what POST /knowledge means, the audit log records MCP-driven writes like
any other write, and a route that changes changes here with it.
It is stateless: no sessions, no server-initiated stream, GET and DELETE answer 405 and
say so. Batches work. ?readonly=1 on the URL drops the six writing tools for that
registration — a guard rail for an agent, not a security boundary, since nothing stops a
caller from omitting it. The boundary is the token: /mcp passes the caller's
Authorization header to every tool call it replays, so a tool can do exactly what the same
token can do over REST.
rm and reindex are not exposed over MCP at all: retracting an entry and rebuilding the
index should not be something an agent reaches for mid-thought.
This adds no reach that the API did not already have. POST /knowledge and
DELETE /knowledge/{key} already answer unauthenticated on this port; /mcp is exactly as
open as they are and no more. Bind accordingly — see the note in src/config.rs.
It does not replace the CLI
A deploy script, an ssh one-liner on a fleet node, cron and a person at a terminal all
need the CLI, and MCP reaches none of them. Anything that cannot speak MCP uses kyb.
Access: tokens and roles
Out of the box KYB asks nobody for anything (KYB_AUTH=off) and relies on the network it
listens on. To know who wrote what, and to let some callers only read, turn tokens on.
Tokens tell callers apart; they do not hide traffic. KYB itself speaks plain HTTP, and a
token sent over plain HTTP can be read and replayed by anyone who can watch the network. On a
network you trust against eavesdropping (loopback, a private LAN, a VPN) that is enough. To
serve anyone beyond it, put a TLS-terminating proxy in front and point clients at it with
KYB_URL=https://kyb.example.
With Docker Compose the three settings are passed through from .env (KYB_AUTH, KYB_ANON,
KYB_AUTH_FILE), and the book defaults to /data/auth.json - on the persistent volume, outside
the git canon (data/ and auth.json are in .gitignore; the server refuses to start with a
book inside KYB_DATA). Issue tokens with docker compose exec kyb kyb-server auth add .... The server
prints the mode in force when it starts (kyb: auth required - 3 principals in ...); check that
line, or kyb whoami, rather than assuming.
# on the server, next to the data (the book is the root of trust; it is not in git)
kyb-server auth add --id alex --name "Alex" --role admin
kyb-server auth add --id agent-a --name "Agent A" --role write --label build-box
kyb-server auth list # ids, roles, token ids — never tokens
kyb-server auth token --id agent-a # a second token: rotate with an overlap
kyb-server auth revoke --token t_1a2b3c4d # or --id agent-a for the whole principal
KYB MCP questions
How does KYB store data?
It uses Git as the source of truth, where every entry is a markdown file with YAML frontmatter, ensuring every write is versioned and attributed.
Can agents search through historical data?
Yes, the Tantivy index covers both the latest and every historical version of every entry, allowing agents to search what knowledge looked like before it changed.
Does KYB handle sensitive information?
The system includes security measures to prevent secrets from being stored by rejecting writes that appear to contain tokens, private keys, or passwords.
What happens when an incident or task is closed?
Closing an incident or task archives it, removing it from the live working tree while keeping the record searchable in the default search and listings.
