Changelog
All notable changes to knowledge-index are recorded here. Format follows Keep a Changelog; versioning is SemVer with 0.x semantics: breaking changes bump the minor until the MCP tool contract stabilises at 1.0.0.
The single source of truth for the current version is the VERSION file. It is reported by bin/kb --version and by the MCP server in initialize → serverInfo.version.
Not the same axis: a consumer may carry its own component-level compatibility field (e.g. a plugin/cartridge manifest version). Those numbers and this repo's version are independent and will diverge — don't sync them.
[Unreleased]
[0.15.1] — 2026-11-20
- Added: the documentation site knowledge-index.sereda.lv, built with VitePress from
docs/(npm run docs:build; Node is needed only for the site), with a new configuration reference of every setting and the project file. - The name is Knowledge Index again. The rename to GGRAG in 0.15.0 is undone: the repository is github.com/xamresor/knowledge-index again (the old links never stopped working). The add-ons and the audit of 0.15.0 stay.
[0.15.0] — 2026-11-20
Renamed: Knowledge Index is now GGRAG (graph-grounded RAG for code). The package name, the Python module, the data folders and the
kbcommands stay as they are, so nothing breaks for an installed copy.Added: the
auditadd-on (kb addon install audit, free core; off by default): the Audit tab of the admin pages (/admin/audit) with sign-ins and admin actions (browser sign-in, refused sign-in with the reason, admin sign-in and sign-out, rebuild, revoked client) and every tool call with its user, projects, argument, time and result, filtered by user, tool or errors. Kept in the usage database for 90 days.Added: external add-ons (plugins) — a folder with a
plugin.py(NAME, DESCRIPTION, TOOLS, call, and optionally build) installed withkb addon install <folder>and switched on like any add-on. Its tools join the list and go through the core's validation, paging, cursors, usage counting and per-project access; its build hook runs at the end ofkb update. A broken plugin is reported and skipped. A plugin keeps its own licence, so paid add-ons can live in a private repository (bin/plugins.py).
[0.14.1] — 2026-11-20
- Fixed: a frontend call is linked from its enclosing function, not from the whole file. With the file as the source, every function of an API module shared all its routes:
graph_routesfrom one function could leave through another function's route, andreview_contextlisted every importer of the module instead of the screens that call the changed route. - Fixed:
review_contextcounts a controller whose class depends on the change (constructor injection, a property) for all its routes, not only the actions that call it directly. - Fixed: frontend calls whose URL is on the next line (
apiFetch<T>(then the URL, as Prettier writes a long call) were not seen. On the author's Next.js app: 69 -> 111 linked calls. - Added: PHP calls through typed variables and properties (
bin/link_php_calls.py):Rental $rentalthen$rental->total(), or a promotedprivate Payouts $payoutsthen$this->payouts->book(), become INFERREDcallsedges. 179 new edges on the author's Laravel app. graph_explain/graph_affectedon a name defined several times answer for each match (up to 3) instead of asking the agent to pick one.- Benchmark questions can be chains (one grep per step). After these fixes, on the author's 10 questions: KB 100% of the expected files, grep 95%, with ~33x less text from the KB. The questions were written by the same person who fixed the misses they showed: a fresh set is needed before trusting 100%.
[0.14.0] — 2026-11-20
Changed: README intro — what the KB is in one paragraph: one search over related projects and their docs.
Added:
bench/graph_vs_grep.py— retrieval benchmark of KB answers against plain grep (expected files found, text read, extra searches); the questions live outside git. First run and its three kinds of misses:docs/design.md, "Graph vs grep, measured".Added:
repo_map— a first look at a project within a token budget (default 1500): its domains, then the classes and frontend modules most of the code depends on, with their busiest methods and the routes they serve (bin/repomap.py, idea from Aider's repo map). The budget is split between the projects asked for. Withunused: trueit lists dead-code candidates instead: nothing in the graph depends on them and their names appear in no other indexed file; code that Laravel or a frontend framework wires by convention (jobs, listeners, policies, providers, file-system routes …) is never listed.Added:
code_grep— exact text search with a regular expression over the indexed code (config keys, SQL, error messages, strings), only in the caller's projects; ripgrep when installed, else grep.Faster first call after a rebuild. The graph worker remembers the last 8 caller views and cuts them again in the background as soon as a build has finished (graph.json stopped changing and the build's end mark is newer). Before, the first call of each project set after every
kb updatepaid 2-9 s; on a server that rebuilds after each commit that was most of the slow calls. Measured on the author's machine: 5 s → 0.03 s for the firstgraph_routesafter a rebuild.Changed: usage counters live in SQLite, one row per call (
usage-local.sqlite,usage.sqlite; stdlibsqlite3). kb-api and every session's kb-mcp write the same counters; with the JSON file each saved its own copy over it and the last writer won. Rows give real p95 per tool, a "slowest calls" panel on the admin usage page and p95 in theusagetool. An old JSON file is imported once as totals and renamed*.json.imported. A diff passed toreview_contextis not stored as an argument.Added:
review_context. The tool takes a git diff and answers what it touches: changed symbols (grouped by file), what depends on them in every project, the HTTP routes through them with their frontend callers, the docs that name the changed code and the NOTE/WHY comments next to it (bin/review.py, run in the graph worker on the caller's view).Licence: AGPL-3.0-or-later instead of GPL-3.0-or-later, from this version on. The same terms, plus one: whoever runs a changed KB as a network service must offer its users the source. The
versiontool and the admin pages show the licence and a source link (KB_SOURCE_URLfor a changed copy). Releases up to 0.13.0 stay under GPL-3.0-or-later.Faster
kb update: only what changed is rebuilt. A project whose staged files did not change (path, size, mtime, graphify version) keeps its graph; a changed one goes through graphify's incremental update, and a full--forcepass runs only when graphify refuses a smaller graph (deleted code). Merging and post-processing are skipped when no input changed (project manifests, route tables, docs, config, the KB's own code). The qmd collection round runs only when the collection set changed. On the author's machine: 138 s → 10 s with nothing changed.kb buildandKB_FORCE=1rebuild everything.
[0.13.0] — 2026-11-20
Breaking: access protocol v1 is the only sign-in and access path (docs/access-protocol.md). Two webhooks:
KB_LOGIN_URL(POST user name and password, then the code →{token}or{two_factor: {challenge}}) andKB_PERMISSION_URL(POST with the token and the KB's project names →{user, projects: [...] | "*"}), extra headers inKB_HOOK_HEADERS. Every request carries"protocol": 1. Removed:KB_AUTH_URL(GET identity endpoint),KB_LOGIN_API,KB_LOGIN_PATH,KB_LOGIN_2FA_PATH,KB_LOGIN_2FA_SETUP_PATH,KB_LOGIN_HEADERS, the{data: …}answer wrapper, the separate recovery-code field and the authenticator set-up step inkb-login(set it up in your own app).kb-login --apiis now--login-url. Upgrade: add the two webhooks to your API and setKB_PERMISSION_URLandKB_LOGIN_URL;kb-httprefuses to start withoutKB_PERMISSION_URL.Changed: the README is a short start page (94 lines instead of 646): what it is, the demo, five install steps, what the agent gets, the optional parts. The details moved to
docs/install.md,docs/server.mdanddocs/design.md.Added: add-ons, named by what they do (
bin/addons.py,kb addon list|install|remove <name>):tool-multicall(batch),code-mode(run_code and its sandbox, installed into the data folder),fast-routes(rustworkx),metrics,admin. Off by default; an add-on that is off publishes no tool, page or route, and onlykb addon installfetches its pieces. State in<data>/addons.jsonorKB_ADDONS. Upgrade note:batchandrun_codeneedkb addon install tool-multicall/code-modenow.Added: the
metricsadd-on servesGET /metrics(KB_METRICS=onworks too) in the Prometheus text format (graph, docs, storage, builds, tool calls, errors, time, p95, memory) for Prometheus or PMM; loopback without a token, otherwiseKB_METRICS_TOKENas bearer or basic-auth password. No dependency, off by default.Changed: the admin pages, redesigned (Codex mockups, PMM style): tiles with sparklines from the KB's own history, build time and calls per day, graph, docs, storage and answer-time panels; the usage page is a Query-Analytics-style table per tool (calls sparkline, rate, mean, errors, p95) with filters by project, tool and user. Light and dark.
Added: usage is counted by every server (
bin/usage.py): kb-mcp and kb-api too (as userlocal), with hourly history, per-project counts and recent durations for p95.Added: every build logs its time (
logs/builds.log, written bybin/kbwhatever started it).Fixed: build output was staged as code.
.nextof a Next.js app (2.1 GB) and other build or cache folders (.nuxt,.output,coverage,.turbo,.cache) are no longer copied.Added: the
doc-organizationskill (skills/doc-organization/SKILL.md): the guide below as a checklist agents follow when they write, move or tidy docs.Docs:
docs/documentation-guide.md— how to write and keep project docs so the graph links them to the code (domains, heads, plans apart, contract docs, links and names in backticks, checks with the KB).Added: local MCP over HTTP and local admin pages in
kb-api(make serve):POST /mcpspeaks MCP JSON-RPC,/adminshows the status, index charts and the rebuild button without sign-in, only without a token on loopback; forms carry a per-process token and a cross-siteOriginis refused.
[0.12.0] — 2026-11-19
- Added:
batch— up to 10 tool calls in one request, each with the caller's own rights; one failing call is reported in its place. - Added:
run_code— an agent's JavaScript program that calls the tools throughkb(tool, args)and returns only what it needs. Two walls: QuickJS compiled to WebAssembly (norequire,process, network, files or timers; 64 MB, a 20 s deadline, 30 calls), inside a Node process with the permission model on (read access tosandbox/only, no network, no child processes, no writes), plus CPU and open-file limits.run_codeandbatchcannot be called from inside. Needsnpm ciinsandbox/(quickjs-emscripten0.32.0, pinned by the lock file). The program may be TypeScript: Node strips the types before QuickJS runs it, and the tool description declareskb()andprint()with types. - Added: admin pages at
/adminfor the users inKB_ADMINSor<data>/admins.txt: status with a rebuild button, an index page with charts (graph make-up, storage, documents and chunks per project, build times, answer time per tool, calls per day), usage, and sign-in clients with revoke. API login with its second factor, an HttpOnly SameSite=Strict session cookie, CSRF tokens; no scripts.
[0.11.0] — 2026-11-19
The first outside users on a shared server (a developer team): browser sign-in, speed, paging and several-way path search. Breaking: tool contract 2 — docs_search and graph_query are gone, use search with domain: docs or domain: code.
Fixed: code search walked the domain anchors. 2-7 of ~50 shown nodes were empty domain nodes, and a search could start from one;
searchwithdomain: codenow runs on the graph without them, like path search and impact.Added: cursors for long answers. An answer longer than one page ends with a
cursor; the next pages come from that same answer (cursor+page, no other arguments) for 10 minutes (KB_CURSOR_TTL, at mostKB_CURSOR_MAX= 500 kept). Pages stay consistent even if the index is rebuilt meanwhile, and the query does not run again. A cursor works only for the tool, the caller and the project set that made it.searchkeeps a widened first answer (4x the hits and the code budget) behind its cursor;searchwithpageand no cursor still pages by running again.Added:
graph_routes— several ways between two places, with the routes they cross. Hops are priced by kind (calls and requests cheap, imports dearer, inheritance dearest), busy hubs and framework classes cost extra, a symbol merged across files costs a jump; Dijkstra finds the cheapest way, then again with the used edges made dearer for the next ways. Every HTTP hop prints its method, URI and controller. Pin a project in a name:api:Customer. Withrustworkxin graphify's environment (uv tool install graphifyy --with rustworkx) the search runs on its Rust core, 2-3x faster with the same paths; networkx is the fallback.Added: backend-to-backend HTTP calls. A PHP backend listed with
calls/serves(an API client of another service:Http::get('v2/…'),->send($req, 'post', 'v1/…' . $id)) is linked from its enclosing method to the controller of the other service. Test folders are skipped.Added: paging on every tool but
version:pageandpage_length(characters, 1000-50000, default 6000). Lists are cut at blank lines or line ends and say how to get the next page;searchpages docs by hits and code by graph nodes. The old cuts (8000 characters, 25 contracts, graphify's 20 connections ingraph_explain) are gone:graph_explainlists every connection.Changed: optional arguments carry their
defaultin the tool schemas.Faster: a caller's project set is cut from the graph in memory. The graphify worker keeps the main graph parsed and makes each caller's view (
filter_graph, andstrip_domainsfor path and impact) from it, instead of a filtered file written by a subprocess and parsed again. The first call for a new project set on a 23k-node graph: 3-5 s -> 0.3-1.6 s, then milliseconds. The same access rules (the same function). Memory stays bounded:KB_GRAPH_VIEWS(8, two per project set) views andKB_GRAPH_CACHE_FILES(2) files; the worker measured 575 MB with four project sets. Each networkx graph gets its owngraphattribute dict, so graphify's per-graph index never leaks from one view into another. Label suggestions follow the caller's projects.Faster: long-lived graphify and qmd in the servers (
bin/warm.py,bin/graph_worker.py). Every call used to start graphify (parse a 34 MB graph, build networkx) or qmd (load the embedding model). On a 23k-node graph: graph_explain 4-7 s -> 0.01 s, code search 1-4 s -> 0.1 s, docs search 6-8 s -> 0.2 s, same answers. A failing helper falls back to the old path;KB_WARM=0turns them off.Changed:
KB_DOCS_MODEdefaults tolight(no LLM reranker). With the reranker a docs search took 1-2 minutes on a CPU;fullis still there for a machine with a GPU.Added: browser sign-in for MCP clients (OAuth 2.1,
bin/oauth.py). Protected-resource and authorization-server metadata, dynamic client registration, a login page that runs the API's own login with its second factor, PKCE S256, loopback redirects only; the access token is the API's dev token, so the access check is unchanged. On by default when the login settings are present (KB_OAUTH=offto disable).Removed (breaking, tool contract 2):
docs_searchandgraph_query. They were aliases ofsearchand confused new users and their skills. Usesearchwithdomain: docsordomain: code.versionreportsapi_contract: 2.Changed:
kb-loginkeeps the token in a private file, not in a project's.mcp.json. That file is often in git, and the server then worked in one project only. The token goes to~/.claude/kb/token(owner-only);--add-to-clauderegisters the server once in Claude Code's user scope with aheadersHelper(kb-login --headers) that reads the file, so a new login changes no config.--env-filereads the settings without a shell (Windows).--mcp-jsonstill exists and refuses a file that git tracks.Fixed:
graph_affectedstopped at "ambiguous label" for a model named like its domain anchor (Order). It now runs on the graph without anchors, likegraph_path.Fixed: a call site that lost its path prefix was linked to the wrong controller.
${baseUrl.value}/sendmatched the shortest route ending in/send. A suffix match now needs a base-only prefix (api,v1) or a single candidate.Added: versioned API paths handed to list and export helpers count as calls (
usePaginatedList(() => \v2/…`),exportTable('v2/…')). Themethod:` of a call is no longer taken from the next call a few lines down.Changed:
searchruns its docs and code halves in parallel, takesbudgetfor the code half, and its truncation note names options that exist over MCP (graphify's note pointed at CLI flags).Added: server
instructionssay which tool answers which question and how far to trust an edge; a 401 answer carries ahinton how to get a token (the server has no OAuth).Fixed: a failed build left a half-built graph in place.
graph.jsonis rewritten step by step, so a build that died half-way (seen on a server: 104 failed builds in a row) served a graph with nohttp_requestedges and no domains. The previous graph is now kept aside and put back when the build fails.Fixed: one failing
route:listbroke the whole build. The route table was deleted and the HTTP linker then crashed on the missing file. A failed run now keeps the previous table (or an empty one on the first build) and says so.Fixed:
graph_pathreported symbols as connected when they only shared a domain. Path search walked thein_domainedges, so any two members of a domain were two hops apart through the anchor. On the author's graph (5386 nodes) 21 of 105 found paths had no real route at all. Path search now runs on a copy of the caller's graph without the domain anchors (access.path_graph), cut after the access filter.explain, the code search and the dashboard still see the anchors.Fixed:
graph_affectedstopped at the repo boundary. graphify's default relation list does not include the relations this project adds, so a controller method showed no frontend callers and a table no models. The tool now also walkshttp_request,eloquent,fk,sql,defines_tableanddocuments.Fixed:
bin/installtook a graphify that does not start for an old one. After a system Python upgrade the tool's environment can point at a missing interpreter; this is now reported as such.Tests:
tests/test_graph_routes.py— access guards for the graph tools and a run against the real graphify (skipped when it is absent), which the stubbed tests could not catch.Fixed: deleted code stayed in the graph. With graphify's cache kept between builds,
graphify updaterefused to overwrite a project graph that would shrink. The staged copy is the truth, so the build now passes--force.Fixed:
KB_HOMEwas half-honoured by the build. Staged repos, route tables andcluster-onlyused the package directory instead of the data directory, so an installed or relocated KB clustered the wrong graph.kb.hubs.txtis read from the config directory when present.Faster: linking docs into the graph took ~75% of a build. Every doc was searched with one regex per symbol label (docs × symbols). Each doc is now split into its standalone tokens once and the labels are set lookups. Same edges, checked on a 20k-node graph with 370 docs: 141 s -> 1.1 s.
Added: one frontend may call several APIs.
serves = ["api", "own-api"]links each call site to whichever listed API has the route, andproblemsreports a call as unknown only when none has it.Added:
projecton the graph tools (graph_path,graph_explain,graph_affected, and the code half ofsearch). It only narrows: a project outside the caller'sallowedset is refused with the same message as an unknown one. Default = the session's project(s); an empty answer there widens to everything the caller may see. Every graph answer starts with[projects: …].Added: a shared MCP server over HTTP, off by default (
bin/kb-http). One index on a server for a team; each caller sees only their projects. Bearer tokens are checked against an identity endpoint you run (KB_AUTH_URL), cached per token hash. It refuses to start unlessKB_SERVER=onandKB_AUTH_URLare set. Usage counters (kb-http usage, MCP toolusage), job limits per tool kind,KB_DOCS_MODE=light|bm25for a small server. Around it:bin/kb-refresh(rebuild on a new HEAD, for cron),bin/kb-login(get a token from your API, write.mcp.json; no default addresses), templates inexamples/server/.Added: per-caller project access in the core.
kb_core.call_tool(name, args, allowed): graph tools run on a filtered graph copy (bin/access.py), doc hits anddocs_getare checked by their resolved path, contract docs stay open to all.allowed=None(local use) changes nothing.Added:
contracts_search,connections,problems(bin/contracts.py). Routes joined with their frontend call sites and contract docs; the service map from<docs>/contracts/*.md; the gaps between docs and code. Built bykb updateafter the graph.Changed: argument values that start with
-are refused for every tool whose argument reaches a subprocess, so a value cannot read as a CLI option. MCP answers carryisErrorfor a refused call.Changed: docs are staged with
rsync --deletein place — search keeps working during a rebuild — and the staged docs of a project removed from the config are dropped.Fixed:
$api<Type>('...')calls were missed — a TypeScript type argument between the name and the call.php artisan route:listruns withLOG_CHANNEL=null, so the indexed app gets no log files from the build;.ktfiles are counted in the staged sources.Changed: one qmd collection per project. Docs of project
<name>are indexed askb-<name>(the single aggregatedkbcollection is removed on the nextkb kb).searchtakes a newprojectargument: a name, several comma-separated, orall. Without it the search is scoped to the project(s) owning the session's directory (KB_SESSION_DIRor the MCP server's cwd); if that scope finds nothing, it widens to all projects by itself. Every docs answer starts with[projects: …]so the scope is visible.scopestill takes a raw collection and wins.Fixed: Cyrillic and every other non-ASCII text was cut out of the doc index. The staged copy was forced to ASCII — a workaround for a qmd 0.3.2 chunker crash. qmd ≥ 2.5.3 is required now and has no such crash, so the workaround only destroyed text: Russian docs were unsearchable.
Fixed:
kb updatedid not re-stage docs. It re-indexed the old staged copy, so new or edited docs never reached search until a fullkb build.updatenow runs the docs stage too.Changed: graphify's cache survives a rebuild.
repos/<name>/graphify-out/(with its extraction cache) is no longer deleted before each build; only the staged sources are re-copied. Measured: it does not makekb updatenoticeably faster (~2.5 min) — the time goes to clustering and enrichment.Added: ask the index from the dashboard. Two inputs run
graphify queryand the qmd docs search through/search. They work when the page is opened frommake serve(http://127.0.0.1:8899/), which now serves the dashboard on the same origin — no CORS, so no other website can read the index. Opened fromfile://the page works as before and says how to enable them.Added: show or hide domains. Each domain in the sidebar has a checkbox, plus Show all / Hide all. Hiding filters what is drawn; expanding and edge rerouting are unaffected.
Security: tokenless kb-api answers loopback names only. A request whose
Hostis not 127.0.0.1 / localhost / [::1] gets 403, which closes DNS rebinding. With--tokenthe token decides. This also changes the framing of 2026-07-26: the web page is still usable with nothing running, but with the server up it becomes a client of/search.Fixed: the dashboard was empty. Since 0.5.0
web/index.htmlloaded the generated data beforeapp.js, sokbManifest(…)threw aReferenceErrorand the page showed "no generated data" even after a good build.app.jsnow loads first and starts onload; a test pins the order.Fixed: builds with a Laravel project crashed. Since 0.3.1
link_http.pyread theroute:listtable through the graph loader, which rejects anything that is not a graph. It reads plain JSON again; a test covers it.Added: a demo.
examples/demo/holds a fictional shop (Laravel-style API + Vue) and its built dashboard data, so the dashboard can be seen right after cloning:make demo.make demo-buildrebuilds it in a throwaway copy of the checkout, becausebin/kbwritesrepos/and clusters relative to the checkout root and would overwrite your own graph.Tables are a retrieval problem, not a format one, and are still open: markdown tables chunk badly (a row separated from its header is close to meaningless), which is a chunking fix — repeat the header per row-group, or project rows into records. Measured, unfixed. Not the parsers' job.
Three surfaces, split by consumer (framing fixed 2026-07-26 — the reason each exists, which decides what each may require):
Surface Consumer Job Requires MCP (stdio) agents search + traverse inside a session the core; no port, no auth HTTP API scripts, CI, cron the same search, callable from bash/python the core + a port + a token web a human look at status: the graph, index health, counts generated data only — no running process The consequence that corrects an earlier plan: the web page is not a third client of the search API. Its job is status, so it must open from
file://with nothing running. Making it depend on the API would break the one property that makes it useful — that it works when nothing works. If the API happens to be up, the page may light up extra panels (progressive enhancement), never as a requirement.remote canon: the index lives on a server, local agents reach it over MCP/SSH.Deferred, and removed from the roadmap as a feature (2026-07-27). Since 0.4.0 and 0.7.0 there is nothing left to build: install the tool on the box (uv tool install), pointKB_HOMEat a data directory, and a client reaches it either asssh box /abs/path/to/kb-mcpor through an SSH tunnel to a loopback-boundkb-api. What remains is a recipe plus one prerequisite that lives in the corpus repo, not here: the ingest pipeline still assumes a localqmd update && qmd embed, and that step would lie the moment the index moved. Findings worth keeping regardless: SQLite over a network mount is unsafe (unreliable locks, page-at-a-time latency) while plain files over sshfs are fine (the dashboard is just files); embedding is incremental by content hash, so the cost to fear is the one-off initial embed, not the reindex interval; and a non-interactive SSH shell does not have~/.local/binonPATH, so an MCP command must be an absolute path.1.0.0 — when the MCP tool contract stops changing and a second independent consumer exists.
[0.10.0] — 2026-07-27
Language plugins, finished (steps 2–3, gated on a measurement)
The migration that stopped at v0.9.0 because the three enrichers had no tests. Done in the order that made it safe, one commit each:
- Tests first.
tests/test_enrichers.pypinsenrich.py,link_data.pyandlink_rationale.pyat two levels: the pure functions that were about to move, and the whole scripts run as subprocesses against a fixture repo tree (an Eloquent relation, a$tabledeclaration, a foreign key in a migration, a query-builder reference, a rationale comment). Every assertion checks the edge's confidence too — the one field that must never drift, because a regex-derived edge posing as an AST fact is a lie the rest of the graph rests on. - The move.
bin/lang/php_laravel.py(class/layer vocabulary,$table, Eloquent relations, schema + FK patterns, query-builder refs, migration-name parsing, model scan) andbin/lang/js_ts.py(API client shapes, template/script suffixes, build-output dirs). The enrichers now compile no patterns at all, and a test assertsre.compilecannot come back. - The leftovers. With the patterns centralised, three private suffix lists became visible, each missing a file type the project has:
dedupe.py(.tsx/.pylabels treated as class-like, so files were merged by name — twopage.tsxin one Next.js repo would collapse into one node),link_rationale.py(.tsxnever scanned for markers — 132 files),link_data.py(same omission in the label index).
Proven neutral, not assumed. Same input graph, same three enrichers, before and after: 4731 nodes, 18881 edges, edge_hash 07f5d50aa1f29ea0, identical counts by relation and by type. The step-3 fixes are latent on the current corpus and the changelog says so rather than claiming a fix: there are zero rationale markers in .tsx today, and the duplicate .tsx/.py basenames in the staged repos do not collide inside a single repo yet. What changed is that the next React repo will not silently corrupt the graph.
Two boundaries drawn against the tidier-looking option: no sql.py (nothing parses .sql; DB::table and Schema::create match PHP source, so a SQL "language plugin" would be a fake boundary) and route matching stays in link_http.py (a Laravel route table meeting a JS call site is a join between two languages and belongs to neither plugin).
The registry now has two tiers: lang.plugins() for modules that enrich a graph themselves, lang.patterns() for modules that only carry language knowledge.
Removed
A sweep for what the refactor made dead: import json in 7 files (left over from before graph.py owned all JSON I/O), import re in two, import pathlib in one, a duplicate BARE_CLASS in declutter.py, an unapplied MAX_LABEL in lang/markdown.py, and paths.example_file() (no caller — bin/install resolves the .example twins in bash). One replacement rather than a deletion: link_http.py re-split a node id by hand to get the repo tag, which is what graph.repo_of exists for — that inline split was the bypass graph.py was written to end.
Tests: 176 → 200.
[0.9.0] — 2026-07-27
Language knowledge becomes plugins, and documents enter the graph. The four enrichers each carried their own copy of the file-type list — (".js", ".ts", ".tsx", ".vue") appeared verbatim in four files — while framework knowledge (Eloquent, Next/Nuxt HTTP clients) sat in "concern" files rather than language ones. Adding a language meant editing four places, and forgetting one produced a silently partial graph: the worst failure mode here, because nothing looks broken and edges are simply absent.
Added
bin/lang/— the language layer, with one shared source of truth for file-type facts and a plugin registry. The sets are named by role and not merged:FRONTEND(files that call a backend) stays narrower thanALL_CODE, becauselink_httpdeliberately scans only the former and a merged list would quietly change what it looks at. Comment openers per language live here too, so a new language no longer requires touching rationale extraction.bin/lang/markdown.py— the first plugin for a format that is not code, and the proof the contract holds beyond PHP/JS. Documents used to exist only in the search index: findable, but the graph could not answer which document describes this service. Now:- a
docnode per markdown file under a project's docs root (rendered as an ellipse, legend updated); links_todoc → doc from[[wikilink]]and relative markdown links —EXTRACTED, the link is literally in the file;documentsdoc → symbol from a bare mention —INFERREDwith a score, neverEXTRACTED. The mention rule is deliberately stingy, because this is where noise would come from: only distinctive labels (≥5 chars, CamelCase /method()/ namespaced), whole-word case-sensitive, ambiguous labels skipped (same rule asdedupe.py: when in doubt, do not invent a fact), and capped at 12 per document — a doc mentioning forty symbols is an index, not a description.
- a
bin/link_docs.pyas the pipeline step (a module inside a package cannot be executed directly, and every other step is abin/*.pyscript, so the plugin stays importable and testable).- New relations in the graph contract:
links_to,documents. - Tests 159 → 176: the registry (incl. a test that the removed duplication cannot come back), the distinctiveness rules, ambiguity skipping, the per-doc cap, partial-word rejection, vendor exclusion, and idempotence — the pipeline reruns, so nodes must not double.
Fixed
- Wikilink resolution was broken on the first write: the index was keyed by a composite
"repo::path.md"string andPath("api::b.md").stemisapi::b, so[[b]]matched nothing. Two separate indexes now — by path for markdown links, by stem for wikilinks. Caught by a test that expected two edges and got one.
Verified on the real graph
+8 doc nodes, +24 edges across three doc roots, with links_to marked EXTRACTED and documentsINFERRED.
[0.8.0] — 2026-07-27
Non-markdown documents can be indexed, one plugin per format. Reversing the non-goal written a few hours earlier the same day: tables, scans and PDFs, one file or plugin per parser so they do not mix. The scope is deliberately narrower than "multimodality": text extraction through external CLIs, not layout reconstruction.
The trigger was concrete: two ConnectPay PDFs sit in a corpus and were invisible to search, because the doc index only matches **/*.md. pdftotext -layout pulls 17k and 31k characters out of them.
Added
bin/parsers/— one plugin per format, each declaring exactly four things (EXTENSIONS,REQUIRES,CONFIDENCE,extract) so parsers cannot grow into one pile:pdf_text— PDFs with a text layer (pdftotext -layout;-layoutmatters, pricing decks put figures in columns and without it a number loses its row);pdf_ocr— scans and images (pdftoppm+tesseract, languages fromKB_OCR_LANGS);office—.docx .odt .rtf .epub→ markdown including tables, via pandoc.
kb-extract(bin/extract):--listshows what this machine can extract and what to install for the rest,--into <dir>writes<name>.md, otherwise stdout.- Extraction wired into the doc staging of
kb build: non-markdown files under a project'sdocsroot are extracted into the same staged tree, so the index sees them.KB_EXTRACT=0opts out. kb-installnow lists the formats and the missing tools for the rest.- Tests 143 → 159, including an end-to-end extraction of a hand-written PDF (the figure that matters must survive), the priority order, and the reported-not-crashed rule.
Rules the registry enforces
- A missing tool means the format is unsupported, not a crash — reported once, build continues. A silent hole in the index is worse than a loud gap.
- Text layer before OCR, always. A PDF that yields almost nothing is refused with an explanation rather than indexed as an empty document.
- Every extracted file carries provenance: source, tool and its version, timestamp, and
confidence: EXTRACTED | OCR. OCR output is noisy by nature and must never pass for authored text — a hit from anOCRdocument is a lead, not a quote. - The corpus is never modified: extraction writes into the staged copy only.
- Zero Python dependencies survive — every parser is a wrapper over an external CLI, like
graphifyandqmd.
Fixed
- Tool versions in the provenance header are validated. Poppler's
pdftotexttreats--versionas a filename and prints an I/O error, which duly ended up inside a header on the first run; a candidate now has to look like a version and not like a complaint.
[0.7.1] — 2026-07-27
Changed
- Scope boundaries are now explicit (README §Non-goals): multimodality (PDF/scan/image/audio) is out, SaaS connectors and permission mirroring are out, a server-side canonical index is a deployment recipe rather than a feature, and there is no write path. Nothing was removed from the code — this states decisions that were already implicit, so that the comparison table reads as a boundary and not as a to-do list.
- The remote-canon roadmap item is struck through with the reasoning and with the findings that stay valid either way (SQLite over network mounts, incremental embedding, the SSH
PATHtrap).
[0.7.0] — 2026-07-26
Installable as a tool. uv tool install knowledge-index / pipx install knowledge-index puts kb, kb-mcp, kb-api and kb-install on PATH. Answering the question that prompted this («не лучше использовать composer?»): Composer is PHP, and this is Python + bash whose two real dependencies come from different ecosystems — graphify via uv/pip, qmd via npm. No single package manager can deliver that stack, which is why kb-install (a preflight, not a resolver) stays.
Added
pyproject.toml(hatchling), version read from theVERSIONfile so there is still one source of truth. No runtime Python dependencies — standard library only, on purpose.knowledge_index/— a thin launcher, not a rewrite: each entry pointos.execvs the shipped script, so signals, exit codes and the stdio pipe stay exactly as they are (kb-mcp's whole protocol is that pipe).bin/remains the implementation and a plain checkout keeps working.bin/paths.py— the split between code and data, which packaging forces:PACKAGE_ROOT(read-only:bin/,web/,VERSION, examples),DATA_HOME(graphify-out/,repos/,.docs/),CONFIG_HOME(kb.projects.toml,aliases.toml). Installed it follows XDG;KB_HOMEoverrides both; a checkout keeps everything in place, so an existing clone needs no migration.bashand Python read the same resolution (paths.py --sh), so they cannot disagree.kb vendorandkb openas subcommands — they work in both modes, unlike the previous Makefile-only versions. The shell is staged next to the data when installed, because the page loads its data through relative<script src>and afile://page cannot fetch a sibling. A vendored renderer survives an upgrade: staging never touchesvendor/.- Tests 132 → 143: checkout-vs-wheel detection, XDG and
KB_HOMEresolution, examples always read from the shipped copy, staging behaviour, and that the shell exports bash evals are complete and quoted (an empty one would make a build write to/).
Fixed
- An installed copy identified itself as a checkout and pointed its data directory at site-packages. The first marker was
VERSION+bin/kb— both of which the wheel ships. The marker is nowpyproject.toml, which a wheel never installs. Caught by actually installing the tool and readingkb --version, not by reasoning about it. kb-installnow prints the console-script path for.mcp.jsonwhen installed (~/.local/bin/kb-mcp) instead of a site-packages path that the next reinstall would break.
[0.6.1] — 2026-07-26
Added
- README §"Where this sits (and where it does not)" — an honest comparison against the code-side tools (Sourcegraph, Zoekt/OpenGrok, Meta's Glean, CodeQL) and the retrieval-side ones (Onyx, R2R, RAGFlow, txtai, the managed cloud primitives, Glean the company), with a "what the others do better" section: compiler-grade code semantics, connectors and permission mirroring, document understanding, scale and support. Facts stamped July 2026, because licences and pricing move.
Fixed
- Requirements said python
>= 3.10; the floor is 3.11 —tomllibreads the config and the alias table.bin/installalready checked 3.11, so the README was the wrong half.
[0.6.0] — 2026-07-26
The lexical layer stops excluding the answer — without patching qmd. qmd joins a phrase's terms with AND, so a natural-language question turns every word into a hard filter: the page that holds the answer is dropped when it lacks one of them, usually a function word. Measured on the 27-question golden set, asking as a phrase gave recall 0.14.
The fix uses qmd's own documented multi-line form instead of forking or patching it: hand it a query document — intent: plus one lex: line per content word plus a vec: line — which qmd fuses (RRF) rather than intersects.
| Same corpus, same unpatched qmd | recall | MRR |
|---|---|---|
one phrase (AND semantics) | 0.142 | 0.167 |
query document, one lex: per term | 0.670 | 0.586 |
For comparison, patching qmd's parseLexQuery to OR reached recall 0.735 / MRR 0.526 — so this keeps ~90% of the recall gain with better ranking and nothing forked: no maintenance of someone else's fast-moving tool, and nothing that a qmd upgrade silently reverts.
Added
bin/query_build.py— the query document builder: content-word extraction, stop words for Russian and English, compound tokens kept whole (doc-search,shop-api,graph.json,/srv/oldnameare the corpus's most discriminative words and splitting them destroys them), a cap of 12 terms, and a hand-written query document passed through untouched.bin/install+make install/make check— first-run setup: verifies python ≥ 3.11 (tomllib),graphify ≥ 0.9.25,qmd,rsync; createskb.projects.tomlandaliases.tomlfrom their examples; optionally vendors the renderer; prints the ready.mcp.jsonsnippet with absolute paths and the three surface entry points. Never overwrites an existing file, never installs another project's tool behind your back (it prints the command), idempotent, and--checkwrites nothing at all.- Tests 119 → 132: stop words in both languages, compound tokens, ordering and deduplication, the term cap, the stop-words-only fallback, and that explicit
mode=lex|vecis left alone.
Changed
searchwithmodeauto/hybridnow sends a query document;mode=lexandmode=vecremain verbatim passthroughs, because an explicit mode is the caller's decision.- Side effect, deliberate: qmd's own LLM query expansion no longer runs for these searches. It was actively harmful on unknown proper nouns — for one name it invented a domain ("… in philosophy") and dragged the vector search off the corpus, giving that question a recall of exactly zero.
Superseded
- The planned "routing between the lexical and vector legs by question shape" is dropped: the document carries both legs and lets RRF weigh them, which needs no classifier and no heuristics about what a question "looks like".
[0.5.0] — 2026-07-26
The web surface is a source file now. The whole interface used to be a TEMPLATE string inside bin/render_viz.py, rendered into git-ignored graphify-out/kb-graph.html — an interface that could not be diffed, linted or tested, and that nobody could fix without running the pipeline.
Added
web/— the versioned shell:index.html,app.js,style.css. No build step, no framework, no placeholders. Opens fromfile://; entry point ismake open.- A Status panel next to the graph, fed by build-time snapshots: index health (nodes, edges, domains, projects, when the graph was built), the docs collection (files, freshness), the alias table (renames are knowledge, not just configuration), search-quality numbers if a benchmark result is present, and the versions of the repo plus both CLIs. Every block is stamped — a stale number that admits its age is useful, one that pretends to be live is not.
make vendordownloads the renderer intoweb/vendor/(git-ignored) so the page works offline. The page prefers the local copy and falls back to a CDN with a visible banner: a tool whose promise is "the corpus never leaves the machine" must not quietly fetch code from a third party. This was an inconsistency in the previous shell, which loaded vis-network from unpkg unconditionally.- Tests 104 → 119: the data contract the shell depends on (manifest keys, super-node
domkey, per-domain member/intra split, cross-domain rerouting, search index shape, stamped status) and the shell's own rules — no.innerHTML, the local renderer first, no leftover placeholders, and the UI strings staying English.
Changed
bin/render_viz.pyemits data only and takes an output directory:kb-manifest.js(kbManifest({domains, superNodes, fileMap, dataPath, nodeCount, generatedAt})),kb-status.js, and the per-domainkb-graph-data/*.jsthat already existed. The four__PLACEHOLDER__substitutions are gone.- Search results are built with
textContent. The old shell assigned node labels intoinnerHTML; a repository containing a symbol named<img onerror=…>would have executed it. The generator additionally escapes</scriptin every emitted file, so a label cannot end the script tag early. - The stale
graphify-out/kb-graph.htmlis removed by the build; graphify's owngraph.htmlstays as the raw upstream view. README.mdandCLAUDE.mdpoint at the new entry point; the design rules gained three entries (the interface is a source file, snapshots are stamped, the renderer is local).
Unchanged on purpose
- The lazy data split (one
.jsper domain,_cross.js,_index.js, loaded on demand) predates this release and stays:.jscalls rather than JSON + fetch is what makesfile://work.
[0.4.0] — 2026-07-26
One core, two machine transports. The MCP server and a new HTTP API are the same contract: both dispatch through kb_core.call_tool() and publish kb_core.TOOLS, so drift between them would require deleting code rather than forgetting to copy it. The web surface is deliberately not part of this contract — see 0.5.0 in Unreleased.
Added
bin/kb_core.py— every operation, once, transport-free. Schemas, shallow validation, process plumbing, label suggestions and dispatch moved out of the MCP server.- A generic
searchreplacing two narrow tools:{q, domain: docs|code|both, scope, mode: auto|lex|vec|hybrid, limit, min_score, expand_aliases, explain}.domainroutes to qmd, to graphify, or to both with labelled sections;modemaps onto qmd's three entry points;scopepicks a collection other than the default. bin/kb-api+bin/kb_api.py— the HTTP adapter for scripts.GET /health,GET /version,GET /tools,POST /call {name, arguments}(the MCP shape verbatim), plus ergonomicPOST /search,POST /graph/{path,explain,affected},GET /doc?path=. Routing is a pure function (dispatch), so the surface is tested without opening a socket.make serveruns it.- Security policy, enforced at startup: default bind
127.0.0.1; a token (--token/KB_API_TOKEN) is required for any non-loopback bind and the server refuses to start without one — verified live and pinned by tests. Requests off loopback are rejected even if that check were bypassed. Remote use means loopback + an SSH tunnel, not a wider bind. versionoperation /GET /versionreturning{repo, api_contract, collection, aliases}: the repo release and the surface's contract number are separate axes and are never merged.- Validation without a dependency: required keys, primitive types (a
boolis not anintegeron the wire), enum membership — read from the same schema dicts the surfaces publish. An unknown argument is an error, because a silently ignoredmod=lexlooks like the mode did nothing. - Tests 62 → 104: schema/validation,
searchrouting by domain, deprecated shims delegating rather than duplicating, alias expansion on/off per call, the timeout fallback firing only inautomode, and the whole bind/token policy.
Changed
bin/kb-mcpis now transport only (~60 lines): JSON-RPC framing,initialize(now also reportingapiContract),tools/list,tools/call. A bad call comes back as tool text an agent can read and retry, instead of a protocol error it cannot see.docs_searchandgraph_queryare deprecated but working — they translate tosearch, so there is one implementation. Callers written against 0.3.x keep working unchanged.- README gained "Three surfaces, three consumers" with the API reference and the token rule.
[0.3.1] — 2026-07-26
Refactor and tests, no behaviour change. Cleanup before the 0.4.0 core extraction, because the weaknesses below would have been copied into the new layer.
Added
bin/graph.py— the artefact contract in one module: atomic load/save, the node-id format (repo::path::symbol) with parse/build, andRelation/Confidencevocabularies as constants. Previously eight scripts re-derived all of this by hand, so a graphify format change broke eight files silently and a relation typo produced a silently wrong edge instead of an error.- Atomic writes.
graph.save()writes a temp file in the same directory,fsyncs andos.replace()s it; a failed serialization leaves the previous complete graph and no debris. The pipeline rewrites one shared artefact in place and has no recovery step, so a truncatedgraph.jsonwas a real failure mode, not a theoretical one.load/savealso refuse a value that is not a graph. - Tests where the risk is — 26 → 62. New:
dedupe(merge into the single definition, collapse when there is none, leave ambiguous labels untouched, drop self-loops and duplicate edges, keep repos isolated),declutter(curated hubs only; a real service with the same degree survives; exact label match, soModelnever eatsModelFactory),graph(atomicity, shape guards, id round-trip incl. namespaced symbols),alias_expand(directional, whole-token, path segments, partial table degrades instead of breaking). Previously only the pure parser was covered. tests/_kbtest.py— one bootstrap for importingbin/scripts, replacing per-file importlib boilerplate.- README §"Design rules that hold this together" — the properties the code already has, written down so a future change does not trade them away silently.
Changed
- The eight enrichers now use
graph.load/graph.save/graph.read_json/graph.write_jsoninstead ofjson.dump(g, open(path, "w")); local variables no longer shadow the module. - Silent failure removed from the build: a failing
php artisan route:listnow warns loudly and removes the stale route file, instead of|| truequietly dropping the cross-repo half of the graph. - The clustering ↔ labeling double pass is documented as what it is — a fixpoint through files (
cluster-onlycan renumber community ids, the labels file is keyed by them) — rather than looking like a redundant call. bin/kb-mcpimports its sibling module directly; thesys.pathinsert was unnecessary (a directly executed script already has its own directory onsys.path[0]).
[0.3.0] — 2026-07-25
Added
- Alias library — directional query expansion (
bin/alias_expand.py, wired into the MCPdocs_search). When a query contains an old name, the canonical term is appended before the query reaches the index; the original wording is preserved, and the expansion is echoed in the result so it is never silent.- Deployment data, not code: the table lives in a gitignored
aliases.toml(aliases.toml.exampleis committed), exactly likekb.projects.toml— it names private projects, products and people. A missing file means the feature is simply off. - Directional on purpose (old → canonical). A symmetric expansion that dumps every spelling into the query pulls the meta layer to rank 1 — changelogs, planning notes and logs are the documents that contain all spellings at once. Measured and rejected.
- Matching happens on raw query text, before stemming. FTS5's
porter unicode61can collapse a brand into an ordinary word (a product namedBookingerstems tobooking), which turns an alias query into a stopword query; matching the raw string keeps the alias an alias. Whole-token match, tolerant of path separators, so an old path segment (/srv/oldname) triggers too. - Measured on a 27-question golden set (lexical leg): alias-type recall 0.50 → 0.70, overall recall 0.735 → 0.772, MRR 0.526 → 0.536 — i.e. no rank regression, which was the risk. Honest limit: the two questions it rescues land at rank 6–10 (presence restored, rank not), and three of five alias questions already worked without it.
- Deployment data, not code: the table lives in a gitignored
Changed
- Roadmap reordered: the alias library became
0.3.0; the write path moves to0.4.0.
[0.2.0] — 2026-07-25
First tagged release. State of the tool as it is actually used in two private deployments (a personal markdown wiki and a codebase indexing itself), not a rewrite.
Added
- MCP server
bin/kb-mcp(stdio, zero Python dependencies) exposing six tools:graph_query,graph_path,graph_explain,graph_affected,docs_search,docs_get. - Cross-repo graph edges: frontend call sites matched to backend controllers (
calls→serves), incl. Next/React and Nuxt/ofetch$api()matchers, tolerant of a Laravelapi/prefix. confidenceon edges —EXTRACTED | INFERRED | AMBIGUOUS | DERIVED, so regex-derived edges no longer masquerade as AST facts; rendered dotted in the visualisation.- rationale nodes —
NOTE/WHY/HACK/SECURITY/RATIONALEcomments becomerationalenodes withexplainsedges (bin/link_rationale.py, capped at 8 per file). - Doc half: aggregated docs staged into one qmd collection (
kbby default,KB_COLLECTIONto override) with a selectable qmd backend (bin/kb qmd-backend). - Namespace labelling and clustered graph rendering (
bin/label_namespaces.py,bin/render_viz.py). bin/kb --version— prints the repo version plus the resolvedgraphifyandqmdversions.- Unit tests for the HTTP matcher, including
{id?}query-splitting innorm_path.
Changed
- Repository renamed
knowledge-base→knowledge-index(2026-07-05). Old name still appears in historical notes; there is no compatibility shim. - MCP
serverInfo.versionnow reports the real version fromVERSION(it previously reported a hardcoded1.0, which overstated stability).
Requirements
graphify >= 0.9.25(Graphify-Labs/graphify) — the code-graph half.qmd(verified with 2.5.3) — the doc-search half; embeddings run on-device.python3,bash. All generated artefacts (graphify-out/,repos/,.docs/,kb.projects.toml) are gitignored — a checkout builds them, it does not carry them.
Known limits
qmdfilters by collection only; an arbitrary doc-id pre-filter is not supported, so fine-grained scoping needs one collection per scope (or an upstream patch).- The graph covers the languages
graphifyparses; Elixir projects are out of scope.
[0.1.0] — untagged (pre-2026-07-05)
Retroactive label for the pre-MCP era: a single-repo graphify wrapper under the old name knowledge-base. No tag exists for it; recorded here so the numbering means something.