The shared memory your AI agent fleet keeps forgetting it needs.
KYB — Know Your Business is a git-backed, searchable knowledge base for fleets of AI agents. Which servers exist, how services are wired, what broke and how it ended, what is still open — the operational truth that survives between sessions and across machines. Every write keeps the attribution its client supplied: which agent, and when known, which session and workspace.
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.
inc-orders-api-oom with an executable detection check and resolution.Session 2 (weeks later): Another agent on a different machine asks "why did the order service keep restarting?" Hybrid search can surface that resolution even when the wording differs from the entry — instead of re-investigating what was already solved.
brew install alex09x/apps/kyb && brew services start kyb (or Docker / Cargo: cargo install knowyourbusiness --locked && kyb-server).2. Wire your fleet: Drop the skill into local agents via
bash skills/install.sh (from a git checkout), or connect directly over native HTTP MCP via POST /mcp.3. Ask before reasoning: Agents query KYB first, claim tasks, and enrich the shared knowledge base before finishing.
Seven ideas, one operational truth.
No database, no namespaces, no ceremony. Just git, a disposable index, and a search that actually finds things.
Git is the canon
One markdown file per entry, one commit per change. A commit sha is a version id. There is no database — history, diff and rollback come for free, and any text editor can read the canon.
Hybrid search
BM25 fused (reciprocal rank) with vector search over every entry — e5-small, int8 ONNX locally on CPU. Describe a problem in your own words and the right entry surfaces; exact technical terms still rank first.
Incidents & tasks built in
Not just facts: operational events and work in flight are first-class entries with real lifecycles — and every closing demands an outcome in writing.
Upserts by key
Writes are keyed and deterministic — a no-op when content did not change, so no empty commits. Flat key space plus tags; predictable key patterns are the deduplication mechanism.
Every write says who
A commit records the attribution its client supplied — the agent, and when known its session and the workspace it ran in — as git trailers, as by in history and the ledger, on each version in the console. A write without context has none; older commits are not attributed after the fact. Forensics, not identity: attribution grants nothing; tokens do.
Local, private, no secrets
Binds to 127.0.0.1 by default. To serve a trusted LAN, opt into one exact private interface; out of the box tokens are off and the service speaks plain HTTP, so never publish port 9310 to the internet as it is: turn tokens on and put TLS in front first. Writes that look like a token, key or password are rejected: store pointers, never credentials.
Rust, all the way down
axum + tantivy 0.22 + git2 + ort (ONNX Runtime). One write mutex, lock-free reads. The index is a disposable cache — lose it and it rebuilds from git on the next start.
Git in, ranked answers out.
Three kinds, one flat key space.
Only the closing states archive an entry — and every one of them requires an outcome in writing.
What is true now
A fact under a stable key: architecture, topology, deploys, decisions, gotchas.
What happened
An operational event: what broke, the impact, the runbook, the resolution.
What is in flight
Work and ideas: who holds it right now, what it waits on, what came of it.
A report is a control panel, not a story.
The server teaches structure instead of gating on it — a bare report is accepted, but the reply names every missing actionable part. Two hard rules: keys start with inc-, and closing requires a resolution.
inc-2026-08-06-orders-api-oom
orders_api OOM loop: the write buffer grows until the container restarts.
A board your agents can actually share.
A task is a short actionable note with a real lifecycle. Claim it before you start so two agents don't do the same work; block it with the reason it waits on; close it with what came of it. Every change is a git commit, so history replays who held what, in which status, at any point in time.
Partial transitions
kyb task-status sends the status and nothing else — title, body, tags, priority and links stay exactly as stored. A transition never has to fetch and resend the task.
Nothing is inferred
Unranked stays unranked, unclaimed stays unclaimed. A blocked_reason is only valid while blocked — moving off blocked clears it, so a task never advertises a block it is out of. parent_task hangs child work under the task it belongs to.
One command wires it into every agent on the machine.
A skill an agent never opens is a skill it never uses — so the installer drops a pointer into each agent's always-loaded global instructions. Marker-delimited and idempotent: re-running updates the section in place.
Claude Code
~/.claude/skills/kyb
+ CLAUDE.md
Codex
~/.codex/skills/kyb
+ AGENTS.md
Antigravity
~/.gemini/…/skills/kyb
+ GEMINI.md
Executed from a clone of the KYB repository. (The Homebrew package installs the client CLI and wires this automatically.)
What no database can enforce — governance
The loop is ask → assess → enrich: query before reasoning, write back what you learned before finishing.
Always query before adding. Found something close? Overwrite the same key — duplicates kill a shared base.
Entries are self-contained and hold verified facts only — never a guess dressed as knowledge.
Working a task means claiming it first, blocking it with a reason, closing it with an outcome.
Broke something? File an incident, close it with a real resolution, then fold the lesson back into knowledge.
Secrets never in bodies — pointers in refs, and the server rejects the rest.
Native MCP over HTTP.
KYB is not an MCP alternative — it speaks Model Context Protocol natively. The server serves the MCP protocol directly over HTTP at POST /mcp. No client-side adapters, no subprocesses, and no client packages to install or update.
Zero client adapters
The tool list is generated by the server. Clients discover capabilities when listing tools, without updating a local KYB adapter, and may need to refresh or reconnect after an upgrade.
Shared audit log
Tool calls forwarded through /mcp execute against the same API routes and share the audit log; when tokens are on, the actor is recorded too. Eligible operations (entry gets, search queries, and mutations) are recorded with caller IP and duration, while routine health (/healthz), taxonomy (/tags), and all incident and task list reads are excluded to avoid polling noise.
Agent skills or MCP
Both reach the same server. The agent skill (skills/install.sh) gives Claude Code, Codex and Antigravity the kyb command and the rules for using it; MCP is for any client that would rather call tools than run a shell — IDEs, desktop apps, or those same agents. Either path records attribution when the client supplies it: the CLI reads its environment, MCP needs the hook, the client’s metadata or the headers described under Attribution; a client registered with nothing but the URL writes unattributed.
Who wrote what, on every version.
Since 0.3.0 a write is committed with up to four trailers: the agent, its session, the workspace it ran in and where that record came from — whichever of them the client could tell; empty fields are left out, and a write with no context carries none. History and the activity ledger return them as by; the console shows them on each version; kyb whoami shows what the current shell would write. Workspaces are a repository name and a path inside it, never an absolute path. The git author stays the service’s unless tokens name a principal.
via: cli
The kyb command read the environment the agent runs it in: which provider, which session, which repository.
via: hook
Claude Code calls the MCP tools over HTTP; a decision-free PreToolUse hook adds the record to each call, and the server takes it out of the arguments before the API sees them.
via: meta
The MCP client’s own call metadata named the conversation (Codex, Antigravity) when there is no hook. Fixture-tested; live evidence so far is for cli and hook.
via: headers
Any client: X-Kyb-Agent, X-Kyb-Session, X-Kyb-Workspace. Sources are read in order — hook, then the client’s metadata, then headers. The first source that names an agent selects the agent and the session it has; a missing session may be filled by a source naming the same agent or no agent, and the workspace is the first available value. via names the agent’s source; which source filled each field is not recorded.
The record is what the caller supplied, not an authenticated identity. GET /whoami echoes it back. Access is a separate matter: tokens with read, write and admin roles, off by default.
A console for people, served from the binary.
Open http://<host>:9310/. No build step, no separate service, one quiet type scale; colour only where state demands it. Every screen and every write a person can make is driven by a browser test in CI, with block coverage of the page script held at 100%.
Queues, not boards
Incidents and tasks are attention queues: what needs a person now, with the reason in the row — blocked and why, open with no detection check, stale for how long.
Versions
An entry’s own ledger: every version, newest first, with the whole of what it changed and, when the client said, who wrote it and from where. Any version is one click away as it was first written.
Ledger
Activity is a change ledger: the whole change, not a feed. Each row names the author when tokens identify one, otherwise the agent and workspace when the client supplied them, otherwise unknown.
Services and hosts
For each service or host an incident names: what is open on it right now, the notes those incidents cite, the open tasks pointing at them. Every row says why it is listed; nothing is inferred from tags.
Vectors earn their keep.
Evaluated with scripts/eval-search.sh using paraphrase questions that share few or no tokens with the entries they land on. In-memory Tantivy BM25 fused with an int8 multilingual ONNX model running locally on CPU.
scripts/eval-search.sh. The example queries were originally drafted against a different test base (three target keys are absent from this 643-entry corpus, capping the reachable score well below 14/14). On identical queries against the same corpus, hybrid vector fusion roughly doubles retrieval hit rate over lexical BM25 alone. Replace example queries and target keys with your own base before drawing production conclusions.
A small, honest surface.
Eligible API operations are appended to a JSONL audit log — timestamp, ip, method, path, status, duration — while routine health (/healthz), taxonomy (/tags), and all incident and task list reads are excluded to avoid polling noise.
Up in two commands.
Two things to know before you expose it
Tokens are off by default — keep port 9310 on a private network. Tokens with read, write and admin roles tell callers apart and name them as the author of their commits; they do not encrypt the traffic, so beyond a trusted network add TLS in front. And run the container as your host uid: otherwise the git canon ends up root-owned and unreadable by hand, and git-as-truth is the whole point.
One idempotent command, whole pipeline.
Refuses to run with uncommitted changes, waits for CI green, health-checks the server, then rolls the skill and CLI to every machine. Sleeping laptops don't abort the rollout — unreachable hosts are skipped and the run ends with a per-machine health table.
Machine-specific config lives outside the repo in a gitignored fleet.local.sh. Releases are byte-reproducible: fixed member order, pinned mtimes, zeroed uid/gid, verified against a layout contract before the tag build can ship.
Citing KYB.
KYB is authored by Alexander Panasenko. If you use KYB in academic, archival, or technical research, cite the software via Zenodo:
@misc{panasenko2026kyb,
doi = {10.5281/zenodo.23309457},
url = {https://zenodo.org/records/23309457},
author = {Panasenko, Alexander},
title = {KYB (Know Your Business): Git-backed knowledge base and incident tracker for AI agents},
version = {0.3.0},
publisher = {Zenodo},
year = {2026}
}
Give your agents a memory.
One command to run it, one to wire every agent on every machine into the same operational truth.