{
  "markdown": "[![kbdb documentation -- a file-based knowledge base with hybrid search, as a CLI and MCP server](https://diko316.gitlab.io/knowledge-base-db/readme-banner.png)](https://diko316.gitlab.io/knowledge-base-db/)\n\n# @dikolab/kbdb\n\n[![npm version](https://img.shields.io/npm/v/@dikolab/kbdb)](https://www.npmjs.com/package/@dikolab/kbdb)\n[![JSR version](https://jsr.io/badges/@dikolab/kbdb)](https://jsr.io/@dikolab/kbdb)\n[![documentation](https://img.shields.io/badge/docs-diko316.gitlab.io-blue)](https://diko316.gitlab.io/knowledge-base-db/)\n[![license: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/LICENSE)\n[![Glama quality score](https://glama.ai/mcp/servers/diko316/knowledge-base-db/badges/score.svg)](https://glama.ai/mcp/servers/diko316/knowledge-base-db)\n[![support via PayPal](https://img.shields.io/badge/support-PayPal-0070ba.svg)](https://paypal.me/dikolab)\n\nA file-based knowledge base with ranked keyword and\nsemantic (hybrid) search -- learn your documents,\nthen recall the relevant knowledge. No external\nserver. Runs as a CLI and MCP server.\n\n📖 **[Documentation](https://diko316.gitlab.io/knowledge-base-db/)** ·\n[MCP Setup](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html) ·\n[CLI Reference](https://diko316.gitlab.io/knowledge-base-db/details/cli.html)\n\n[GitLab](https://gitlab.com/diko316/knowledge-base-db)\n| [NPM](https://www.npmjs.com/package/@dikolab/kbdb)\n| [JSR](https://jsr.io/@dikolab/kbdb)\n| [License: AGPL-3.0](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/LICENSE)\n\n> Runs on **Node.js 20+** or **Deno 2.6+**. No database\n> server, no cloud account -- just files on disk.\n\n---\n\n## What is kbdb?\n\n**kbdb** gives AI agents a persistent, searchable\nsecond brain. Point it at your Markdown docs and it\nindexes them into a file-based knowledge base --\nthen agents (and you) recall the most relevant\nknowledge by ranked keyword and semantic search,\nnot exact-key lookup. It is a *living* store: agents\nlearn new facts, update them, and recall them across\nsessions.\n\nNo external server to install, no cloud account --\njust files on disk. It runs anywhere Node.js or Deno\nruns, and works as an [MCP](https://modelcontextprotocol.io/)\nserver, so agents like Claude can plug it in as a\nmemory tool.\n\n**How search works:** kbdb uses **keyword search** by\ndefault -- synonyms are expanded, terms are ranked\nby relevance, and headings carry 2× weight in\nscoring. When an exact query finds nothing, kbdb\nautomatically loosens the match so you still get the\nbest available results.\n\nWant smarter results? Use `--algo hybrid` to blend\nkeyword matching with similarity search -- finding\nresults even when different words describe the same\nconcept. The default **TF-IDF** embedding provider\nworks offline with zero setup. Swap it for a\nthird-party provider (local ONNX model or remote\nAPI) in `worker.toml` when you need richer\nembeddings.\n\n**Knowledge stays fresh:** Re-learn a file and kbdb\nreplaces the old version automatically.\nNear-duplicate detection warns you when you are\nlearning something you already have -- by embedding\nsimilarity, so it catches the same fact reworded, not\njust the same bytes. `kbdb contradictions` reports\nsections that cover the same ground so you can read\nthem together. Integrity checks verify checksums,\norphans and references. Confidence scores help agents\ntell strong matches from weak ones.\n\n---\n\n## Getting Started\n\n### What You Need\n\nOne of these (pick whichever you already have):\n\n- **Node.js** version 20 or newer --\n  [Download](https://nodejs.org/)\n- **Deno** version 2.6 or newer --\n  [Download](https://deno.com/)\n  (2.6 is the floor: the storage engine loads its\n  WebAssembly through source-phase imports, which\n  is what lets it run offline after one\n  `deno install`. Older Deno fails with a\n  misleading `Module not found` naming a `.wasm`\n  file that is present.)\n\nThat's it. No database server. No extra tools.\n\n### Install\n\n**Using Node.js:**\n\nCLI build hosted on\n[NPM](https://www.npmjs.com/package/@dikolab/kbdb).\n\n```sh\nnpm install -g @dikolab/kbdb\n```\n\n**Using Deno:**\n\nCLI build hosted on\n[JSR](https://jsr.io/@dikolab/kbdb).\n\n```sh\ndeno install -Agf jsr:@dikolab/kbdb/cli\n```\n\nSee the\n[CLI Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-cli.html)\nfor prerequisites and verification steps.\n\n### Try It Out\n\n**1. Create a knowledge base**\n\n```sh\nkbdb db init --db ./my-kb\n```\n\nThis creates a `.kbdb` folder that holds all your\ndata.\n\n**2. Feed it your docs**\n\n```sh\nkbdb learn ./docs\n```\n\nPoint it at a folder of Markdown files. kbdb reads\nthem, breaks them into sections, and builds a\nsearch index. Add `--tags design,v2` to tag\nsections for scoping, `--replace` to update\nexisting sections from the same source, or\n`--level 2` to set the hierarchical depth\n(1 = broadest, 6 = narrowest). When learning a\ndirectory, level is auto-detected from folder\ndepth.\n\n**3. Search**\n\n```sh\nkbdb search \"how does auth work\"\n```\n\nResults are ranked by relevance with snippets\nshowing where your terms matched. Output defaults\nto `--format rec` (recfile: one `field: value` per\nline) for easy grepping. Other formats: `json`\n(machine-readable), `text` (numbered list), and\n`mcp` (JSON-RPC 2.0 envelope). Use `--offset` to\npage through large result sets.\n\nTo try hybrid search (keyword + AI similarity):\n\n```sh\nkbdb search \"how does auth work\" --algo hybrid\n```\n\n> **Tip: `--db` is optional for the CLI.** kbdb\n> walks up from your working directory to the\n> nearest `.kbdb` folder, so commands just work\n> anywhere inside a project. Point at a specific\n> base with `--db <dir>` (the parent of `.kbdb`),\n> or set `KBDB_DB_DIR`. Only the `mcp` server\n> requires an explicit `--db` -- it never searches\n> the working directory.\n\n**Search across bases:** enrich results with\nread-only knowledge from other databases using\n`--other-db <dir>` (repeatable), or add `--cascade`\nto also pull from `.kbdb` folders in parent\ndirectories:\n\n```sh\nkbdb search \"how does auth work\" \\\n   --other-db ~/shared-kb --cascade\n```\n\nEvery result carries a `source_db` field -- the\ndatabase root it came from -- which you can paste\nstraight back into `--db` or `--other-db`.\n\n> **Scripting:** Add `--format json` to get\n> structured JSON output for parsing. Use\n> `--non-interactive` or set\n> `KBDB_NON_INTERACTIVE=1` to suppress prompts in\n> CI pipelines.\n\n**4. Recall context**\n\n```sh\nkbdb recall <kbid> --depth 1\n```\n\nStart with a search result's kbid and expand\ncontext progressively: depth 0 gives the section\ncontent, depth 1 adds parent documents and\nback-references, depth 2 adds siblings and forward\nreferences, depth 3 includes full text of\nreferenced sections.\n\n---\n\n## Knowledge Base\n\nBuild, search, and maintain your knowledge store.\n\n- **Import** Markdown and plain text files with\n  tags and source tracking\n- **Smart updates** -- re-learning a file supersedes\n  the old version instead of duplicating it\n- **History** -- a superseded section is retired, not\n  deleted: `kbdb history` walks the chain from either\n  end, and an old kb-id still resolves\n- **Search** with three algorithms: keyword\n  (default), AI similarity, or hybrid (both)\n- **Auto-fallback** -- if your exact query finds\n  nothing, kbdb loosens the match automatically\n- **Recall** sections with progressive context --\n  from a quick summary to full related content,\n  or as deep as a `--max-tokens` budget allows\n- **Measure** whether retrieval is actually any\n  good -- `kbdb eval` scores Recall@k, MRR and\n  nDCG@k against your own dataset, and exits\n  non-zero when a change makes ranking worse\n- **Neighbourhood** -- `kbdb neighbourhood` says what\n  relates to a section *and how*: eight typed edges,\n  seven of them recorded facts and one inferred\n- **Consolidate** -- `kbdb consolidate` proposes groups\n  of sections that could become one. It proposes only;\n  you write the merge and apply it yourself\n- **Export** -- snapshot your knowledge base for\n  backup\n- **Verify** database integrity and clean up\n  stale data\n- **Rebuild** indexes if anything goes wrong\n\nSee the\n[Knowledge Base Guide](https://diko316.gitlab.io/knowledge-base-db/details/knowledge-base.html)\nfor the full walkthrough, including export and backup.\n\n---\n\n## Agent Tooling\n\nIntegrate kbdb with AI agents and custom tools.\n\n**MCP quick-start (Claude CLI):**\n\n```sh\nclaude mcp add kbdb -- \\\n   npx @dikolab/kbdb mcp --db /path/to/project\n```\n\nSee the\n[MCP Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html)\nfor Claude Code, VS Code, and Claude Desktop\nconfig files, plus troubleshooting.\n\n- **MCP server** with 20 tools -- search, recall,\n  learn, revise, gaps, contradictions, export,\n  skill/agent search, and more\n- **Skills** -- store reusable prompt templates\n  with fill-in-the-blank arguments\n- **Agents** -- create AI agent profiles that\n  combine a persona with skills\n- **Capture policy** -- the server tells the agent\n  what to store during the MCP handshake itself, so\n  it needs no per-host configuration. Two of its six\n  clauses are about what *not* to store: chat\n  summaries, guesses, secrets, and anything the code\n  already says. kbdb delivers the policy; it cannot\n  make an agent follow it\n- **Auto-capture** -- can ask the host's own model to\n  pick out knowledge worth storing. It needs the MCP\n  `sampling` capability, and **Claude Code does not\n  advertise it**, so auto-capture is inert there.\n  Every other feature in this list is unaffected --\n  see [Host Support](https://diko316.gitlab.io/knowledge-base-db/details/host-support.html)\n- **Daemon resilience** -- configurable request\n  timeout and automatic retry with daemon respawn\n- **Worker daemon** lifecycle management --\n  stop and restart the background process\n- **Granular Deno permissions** -- the daemon\n  runs with scoped permissions instead of\n  `--allow-all`\n- **Path confinement** -- the daemon rejects\n  path traversal (`..`) in export/import\n\n**What the server tells an agent.** The `initialize`\nresponse carries an `instructions` string -- the one\nchannel every compliant MCP host receives without any\nsetup. kbdb spends it on capture policy: search before\nanswering, treat an `unanswered` verdict as a gap to\ninvestigate rather than guess at, store decisions and\ncorrections that cost real effort to find, and do not\nstore what the code already says. The same sentences\nare quoted in the `learn`, `revise` and `search` tool\ndescriptions rather than paraphrased, so there is one\nsource for all of them.\n\nSee the\n[Agent Tooling Guide](https://diko316.gitlab.io/knowledge-base-db/details/agent-tooling.html)\nfor MCP setup, skills, agents, and the library API, and\n[Capture Policy](https://diko316.gitlab.io/knowledge-base-db/details/design/capture-policy.html)\nfor the six clauses in full and why they are written\nonce.\n\n---\n\n## For Developers\n\n### Library API\n\nUse kbdb programmatically in your Node.js or Deno\nproject:\n\n```typescript\nimport { createWorkerClient } from '@dikolab/kbdb';\n\n// Spawns a background worker if not already running\nconst client = await createWorkerClient({\n   contextPath: '/path/to/.kbdb',\n   requestTimeoutMs: 30_000,\n});\n\nconst results = await client.search({\n   query: 'authentication',\n   limit: 10,\n   offset: 0,\n});\n\nconsole.log(results.items);\nclient.disconnect();\n```\n\nPass `contextPath` (the `.kbdb` directory itself)\nor `dbPath` (the parent directory -- kbdb discovers\n`.kbdb` inside it).\n\nSee the\n[Library API Reference](https://diko316.gitlab.io/knowledge-base-db/details/library-api.html)\nfor the full API.\n\n### Development Setup\n\n```sh\ngit clone https://gitlab.com/diko316/knowledge-base-db.git\ncd knowledge-base-db\nnpm install\nnpm test\n```\n\n### Docker\n\n**Two Dockerfiles, and they are not interchangeable.**\n\n`Dockerfile` at the repository root builds the **MCP\nserver** -- that is the one MCP directories build, and\nthe one to use if you want kbdb in a container. See\n[Install MCP Server](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html#docker)\nfor the host configuration and why it needs a named\nvolume rather than a bind mount.\n\n`Dockerfile.tooling` builds the **development\ntoolchain** (Node.js and Deno), which every `make`\ntarget uses through `docker-compose.yaml`:\n\n```sh\nHOST_UMASK=$(umask) docker compose run --rm tool sh\n```\n\nRun `make benchmark` to measure search and rebuild\nlatency at scale -- results are written to\n[docs/benchmark/benchmark.md](https://diko316.gitlab.io/knowledge-base-db/benchmark/benchmark.html)\nautomatically.\n\nSee the [Makefile](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/Makefile)\nfor all available build targets.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes and add tests\n4. Run `npm test` and `npm run lint`\n5. Open a merge request\n\n---\n\n## Documentation\n\n- [Second Brain with Claude Code](https://diko316.gitlab.io/knowledge-base-db/details/second-brain-claude-code.html)\n  -- the canonical setup guide: workspace layout,\n  correct commands, MCP wiring\n- [CLI Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-cli.html)\n  -- prerequisites, npm/JSR install, verification\n- [Knowledge Base Guide](https://diko316.gitlab.io/knowledge-base-db/details/knowledge-base.html)\n  -- importing, searching, recall, export\n- [Agent Tooling Guide](https://diko316.gitlab.io/knowledge-base-db/details/agent-tooling.html)\n  -- MCP, skills, agents, library API\n- [CLI Reference](https://diko316.gitlab.io/knowledge-base-db/details/cli.html) -- full command\n  list with examples\n- [MCP Installation Guide](https://diko316.gitlab.io/knowledge-base-db/details/install-mcp.html)\n  -- Claude CLI, Claude Code, VS Code, Claude Desktop\n- [MCP Server Guide](https://diko316.gitlab.io/knowledge-base-db/details/mcp-server.html) --\n  setup, tools, environment config, and what the\n  server tells an agent at `initialize`\n- [Host Support](https://diko316.gitlab.io/knowledge-base-db/details/host-support.html) --\n  which MCP hosts deliver the capture policy and\n  advertise sampling, measured rather than assumed\n- [Capture Policy](https://diko316.gitlab.io/knowledge-base-db/details/design/capture-policy.html)\n  -- what kbdb tells an agent to store, and why it is\n  stated once\n- [Search and Ranking](https://diko316.gitlab.io/knowledge-base-db/details/search-and-ranking.html)\n  -- how search works under the hood\n- [Storage Architecture](https://diko316.gitlab.io/knowledge-base-db/details/storage.html) --\n  file formats, directory layout, and what retained\n  history costs\n- [Deno Permissions](https://diko316.gitlab.io/knowledge-base-db/details/deno-permissions.html)\n  -- the permission flags kbdb needs, and why\n- [Benchmark Results](https://diko316.gitlab.io/knowledge-base-db/benchmark/benchmark.html)\n  -- search and rebuild latency at scale\n- [Learn scaling](https://diko316.gitlab.io/knowledge-base-db/benchmark/learn-scaling.html)\n  -- how learn cost grows with corpus size\n- [Contradiction signals](https://diko316.gitlab.io/knowledge-base-db/benchmark/contradiction-signals.html)\n  -- calibrating the near-duplicate and contradiction\n  thresholds over 1128 labelled pairs\n- [Release Notes](https://diko316.gitlab.io/knowledge-base-db/release-notes/)\n- [Architecture Overview](https://diko316.gitlab.io/knowledge-base-db/overview.html)\n\n### The search engine\n\nStorage, indexing and ranking come from\n[`@dikolab/vdb`](https://www.npmjs.com/package/@dikolab/vdb),\nkbdb's sibling project by the same author. Its\ndocumentation covers the retrieval side in depth:\n\n- [vdb Overview](https://diko316.gitlab.io/private-dikolab-moon-monorepo/vdb/overview.html)\n  -- storage model, partitions, BM25F, vector and hybrid search\n- [vdb Examples](https://diko316.gitlab.io/private-dikolab-moon-monorepo/vdb/examples.html)\n  -- worked queries and ranking behaviour\n\n---\n\n## Support\n\nkbdb is free, AGPL-licensed software. If it earns a\nplace in your workflow, you can support ongoing\ndevelopment via\n[PayPal](https://paypal.me/dikolab).\n\n## License\n\nThis project is dual-licensed:\n\n- **Open source** under the\n  [GNU Affero General Public License v3.0](https://gitlab.com/diko316/knowledge-base-db/-/blob/main/LICENSE)\n  (`AGPL-3.0-only`)\n- **Commercial license** available for closed-source\n  or SaaS use\n\nVersions `<= 0.5.0` remain under the ISC license.\n\nSee [LICENSING.md](./LICENSING.md) for details and\ncontact information.\n\n---\n",
  "bytes": 16474,
  "sha": "826ffdb9255094a9d625e60c59db6e1fb5c70c6b49c4c5377128a9f6e2ecf0b9",
  "repo_slug": "diko316/knowledge-base-db",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_diko316_kbdb_1c5f053b/readme"
}