kbdb
This server is a knowledge-base memory layer for AI agents: it stores, searches, recalls, revises, and maintains persistent knowledge as an MCP tool set.
Search the knowledge base by keyword, vector, or hybrid relevance, with pagination, document/section modes, relaxed fallback, and partition scoping.
Learn new content from Markdown, HTML, TOML, plain text, or images; split into sections with tags, titles, replacements, and descriptions.
Recall and retrieve stored sections or documents with progressive context depth, token budgets, compact/full formats, and batch lookups.
Revise and track history — fix wrong facts (new kb-id, old revision retired but readable) and list revision chains.
Unlearn and garbage-collect — remove sections or whole documents, and delete unreferenced sections.
Explore relationships — view neighbourhood relations (supersedes, parent/child, sibling, references, similar), consolidate merge candidates, and detect overlapping/contradictory sections.
Maintain integrity — run integrity checks, rebuild indexes, export snapshots, get DB status, and review knowledge gaps.
Manage skills and agents — learn, search, recall, unlearn, and compose content in skill/agent partitions (legacy shorthands).
Improve retrieval quality — save eval cases, mark results as useful/not useful, and propose auto-capture content for user confirmation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kbdb search my notes for how authentication works"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

@dikolab/kbdb
A file-based knowledge base with ranked keyword and semantic (hybrid) search -- learn your documents, then recall the relevant knowledge. No external server. Runs as a CLI and MCP server.
📖 Documentation · MCP Setup · CLI Reference
GitLab | NPM | JSR | License: AGPL-3.0
Runs on Node.js 20+ or Deno 2.6+. No database server, no cloud account -- just files on disk.
What is kbdb?
kbdb gives AI agents a persistent, searchable second brain. Point it at your Markdown docs and it indexes them into a file-based knowledge base -- then agents (and you) recall the most relevant knowledge by ranked keyword and semantic search, not exact-key lookup. It is a living store: agents learn new facts, update them, and recall them across sessions.
No external server to install, no cloud account -- just files on disk. It runs anywhere Node.js or Deno runs, and works as an MCP server, so agents like Claude can plug it in as a memory tool.
How search works: kbdb uses keyword search by default -- synonyms are expanded, terms are ranked by relevance, and headings carry 2× weight in scoring. When an exact query finds nothing, kbdb automatically loosens the match so you still get the best available results.
Want smarter results? Use --algo hybrid to blend
keyword matching with similarity search -- finding
results even when different words describe the same
concept. The default TF-IDF embedding provider
works offline with zero setup. Swap it for a
third-party provider (local ONNX model or remote
API) in worker.toml when you need richer
embeddings.
Knowledge stays fresh: Re-learn a file and kbdb
replaces the old version automatically.
Near-duplicate detection warns you when you are
learning something you already have -- by embedding
similarity, so it catches the same fact reworded, not
just the same bytes. kbdb contradictions reports
sections that cover the same ground so you can read
them together. Integrity checks verify checksums,
orphans and references. Confidence scores help agents
tell strong matches from weak ones.
Related MCP server: Librarian
Getting Started
What You Need
One of these (pick whichever you already have):
Node.js version 20 or newer -- Download
Deno version 2.6 or newer -- Download (2.6 is the floor: the storage engine loads its WebAssembly through source-phase imports, which is what lets it run offline after one
deno install. Older Deno fails with a misleadingModule not foundnaming a.wasmfile that is present.)
That's it. No database server. No extra tools.
Install
Using Node.js:
CLI build hosted on NPM.
npm install -g @dikolab/kbdbUsing Deno:
CLI build hosted on JSR.
deno install -Agf jsr:@dikolab/kbdb/cliSee the CLI Installation Guide for prerequisites and verification steps.
Try It Out
1. Create a knowledge base
kbdb db init --db ./my-kbThis creates a .kbdb folder that holds all your
data.
2. Feed it your docs
kbdb learn ./docsPoint it at a folder of Markdown files. kbdb reads
them, breaks them into sections, and builds a
search index. Add --tags design,v2 to tag
sections for scoping, --replace to update
existing sections from the same source, or
--level 2 to set the hierarchical depth
(1 = broadest, 6 = narrowest). When learning a
directory, level is auto-detected from folder
depth.
3. Search
kbdb search "how does auth work"Results are ranked by relevance with snippets
showing where your terms matched. Output defaults
to --format rec (recfile: one field: value per
line) for easy grepping. Other formats: json
(machine-readable), text (numbered list), and
mcp (JSON-RPC 2.0 envelope). Use --offset to
page through large result sets.
To try hybrid search (keyword + AI similarity):
kbdb search "how does auth work" --algo hybridTip:
--dbis optional for the CLI. kbdb walks up from your working directory to the nearest.kbdbfolder, so commands just work anywhere inside a project. Point at a specific base with--db <dir>(the parent of.kbdb), or setKBDB_DB_DIR. Only themcpserver requires an explicit--db-- it never searches the working directory.
Search across bases: enrich results with
read-only knowledge from other databases using
--other-db <dir> (repeatable), or add --cascade
to also pull from .kbdb folders in parent
directories:
kbdb search "how does auth work" \
--other-db ~/shared-kb --cascadeEvery result carries a source_db field -- the
database root it came from -- which you can paste
straight back into --db or --other-db.
Scripting: Add
--format jsonto get structured JSON output for parsing. Use--non-interactiveor setKBDB_NON_INTERACTIVE=1to suppress prompts in CI pipelines.
4. Recall context
kbdb recall <kbid> --depth 1Start with a search result's kbid and expand context progressively: depth 0 gives the section content, depth 1 adds parent documents and back-references, depth 2 adds siblings and forward references, depth 3 includes full text of referenced sections.
Knowledge Base
Build, search, and maintain your knowledge store.
Import Markdown and plain text files with tags and source tracking
Smart updates -- re-learning a file supersedes the old version instead of duplicating it
History -- a superseded section is retired, not deleted:
kbdb historywalks the chain from either end, and an old kb-id still resolvesSearch with three algorithms: keyword (default), AI similarity, or hybrid (both)
Auto-fallback -- if your exact query finds nothing, kbdb loosens the match automatically
Recall sections with progressive context -- from a quick summary to full related content, or as deep as a
--max-tokensbudget allowsMeasure whether retrieval is actually any good --
kbdb evalscores Recall@k, MRR and nDCG@k against your own dataset, and exits non-zero when a change makes ranking worseNeighbourhood --
kbdb neighbourhoodsays what relates to a section and how: eight typed edges, seven of them recorded facts and one inferredConsolidate --
kbdb consolidateproposes groups of sections that could become one. It proposes only; you write the merge and apply it yourselfExport -- snapshot your knowledge base for backup
Verify database integrity and clean up stale data
Rebuild indexes if anything goes wrong
See the Knowledge Base Guide for the full walkthrough, including export and backup.
Agent Tooling
Integrate kbdb with AI agents and custom tools.
MCP quick-start (Claude CLI):
claude mcp add kbdb -- \
npx @dikolab/kbdb mcp --db /path/to/projectSee the MCP Installation Guide for Claude Code, VS Code, and Claude Desktop config files, plus troubleshooting.
MCP server with 20 tools -- search, recall, learn, revise, gaps, contradictions, export, skill/agent search, and more
Skills -- store reusable prompt templates with fill-in-the-blank arguments
Agents -- create AI agent profiles that combine a persona with skills
Capture policy -- the server tells the agent what to store during the MCP handshake itself, so it needs no per-host configuration. Two of its six clauses are about what not to store: chat summaries, guesses, secrets, and anything the code already says. kbdb delivers the policy; it cannot make an agent follow it
Auto-capture -- can ask the host's own model to pick out knowledge worth storing. It needs the MCP
samplingcapability, and Claude Code does not advertise it, so auto-capture is inert there. Every other feature in this list is unaffected -- see Host SupportDaemon resilience -- configurable request timeout and automatic retry with daemon respawn
Worker daemon lifecycle management -- stop and restart the background process
Granular Deno permissions -- the daemon runs with scoped permissions instead of
--allow-allPath confinement -- the daemon rejects path traversal (
..) in export/import
What the server tells an agent. The initialize
response carries an instructions string -- the one
channel every compliant MCP host receives without any
setup. kbdb spends it on capture policy: search before
answering, treat an unanswered verdict as a gap to
investigate rather than guess at, store decisions and
corrections that cost real effort to find, and do not
store what the code already says. The same sentences
are quoted in the learn, revise and search tool
descriptions rather than paraphrased, so there is one
source for all of them.
See the Agent Tooling Guide for MCP setup, skills, agents, and the library API, and Capture Policy for the six clauses in full and why they are written once.
For Developers
Library API
Use kbdb programmatically in your Node.js or Deno project:
import { createWorkerClient } from '@dikolab/kbdb';
// Spawns a background worker if not already running
const client = await createWorkerClient({
contextPath: '/path/to/.kbdb',
requestTimeoutMs: 30_000,
});
const results = await client.search({
query: 'authentication',
limit: 10,
offset: 0,
});
console.log(results.items);
client.disconnect();Pass contextPath (the .kbdb directory itself)
or dbPath (the parent directory -- kbdb discovers
.kbdb inside it).
See the Library API Reference for the full API.
Development Setup
git clone https://gitlab.com/diko316/knowledge-base-db.git
cd knowledge-base-db
npm install
npm testDocker
Two Dockerfiles, and they are not interchangeable.
Dockerfile at the repository root builds the MCP
server -- that is the one MCP directories build, and
the one to use if you want kbdb in a container. See
Install MCP Server
for the host configuration and why it needs a named
volume rather than a bind mount.
Dockerfile.tooling builds the development
toolchain (Node.js and Deno), which every make
target uses through docker-compose.yaml:
HOST_UMASK=$(umask) docker compose run --rm tool shRun make benchmark to measure search and rebuild
latency at scale -- results are written to
docs/benchmark/benchmark.md
automatically.
See the Makefile for all available build targets.
Contributing
Fork the repository
Create a feature branch
Make your changes and add tests
Run
npm testandnpm run lintOpen a merge request
Documentation
Second Brain with Claude Code -- the canonical setup guide: workspace layout, correct commands, MCP wiring
CLI Installation Guide -- prerequisites, npm/JSR install, verification
Knowledge Base Guide -- importing, searching, recall, export
Agent Tooling Guide -- MCP, skills, agents, library API
CLI Reference -- full command list with examples
MCP Installation Guide -- Claude CLI, Claude Code, VS Code, Claude Desktop
MCP Server Guide -- setup, tools, environment config, and what the server tells an agent at
initializeHost Support -- which MCP hosts deliver the capture policy and advertise sampling, measured rather than assumed
Capture Policy -- what kbdb tells an agent to store, and why it is stated once
Search and Ranking -- how search works under the hood
Storage Architecture -- file formats, directory layout, and what retained history costs
Deno Permissions -- the permission flags kbdb needs, and why
Benchmark Results -- search and rebuild latency at scale
Learn scaling -- how learn cost grows with corpus size
Contradiction signals -- calibrating the near-duplicate and contradiction thresholds over 1128 labelled pairs
The search engine
Storage, indexing and ranking come from
@dikolab/vdb,
kbdb's sibling project by the same author. Its
documentation covers the retrieval side in depth:
vdb Overview -- storage model, partitions, BM25F, vector and hybrid search
vdb Examples -- worked queries and ranking behaviour
Support
kbdb is free, AGPL-licensed software. If it earns a place in your workflow, you can support ongoing development via PayPal.
License
This project is dual-licensed:
Open source under the GNU Affero General Public License v3.0 (
AGPL-3.0-only)Commercial license available for closed-source or SaaS use
Versions <= 0.5.0 remain under the ISC license.
See LICENSING.md for details and contact information.
Available Tools
30 toolsagent-contentBRead-onlyIdempotent
Shorthand for content with sectionType: agent. Deprecated; removal in 2.0.0.
Inputs: ids (required).
agent-learnBIdempotent
Shorthand for learn with sectionType: agent. The content is the persona text. Deprecated; removal in 2.0.0.
Inputs: content (required), tags, type, docid, +3 more.
agent-recallARead-onlyIdempotent
Shorthand for recall with sectionType: agent. Deprecated; removal in 2.0.0.
Inputs: kbid, depth, kbids, format, +1 more.
agent-searchARead-onlyIdempotent
Shorthand for search with sectionType: agent. Deprecated; removal in 2.0.0.
Inputs: query (required), algo, mode, docid, +3 more.
agent-unlearnBDestructiveIdempotent
Shorthand for unlearn with sectionType: agent. Deprecated; removal in 2.0.0.
Inputs: kbid (required), docid.
auto-capture-reviewA
Propose knowledge for storage and let the user confirm it, when the host supports elicitation.
Inputs: title, action, content.
checkARead-onlyIdempotent
Verify the integrity of the knowledge base. Reports checksum mismatches, orphan sections, broken references, and circular reference chains.
Inputs: no named parameters.
consolidateARead-onlyIdempotent
Propose groups of stored sections that could become one, so a knowledge base of twenty overlapping notes can become a few good ones. Proposes ONLY -- nothing is merged. Each group reports its weakest link. Without an entailment judge kbdb CANNOT tell whether a group disagrees with itself; read every section before merging it.
Inputs: about, limit.
contentBRead-onlyIdempotent
Compose a rendered Markdown document from one or more kbid or docid identifiers.
Inputs: ids (required), sectionType.
contradictionsARead-onlyIdempotent
Report pairs of stored sections covering the same ground, to read together before trusting either. Similarity finds pairs; it cannot judge agreement. Without an entailment model every pair reads "related", and no "contradicts" means nothing was asked, not that nothing conflicts.
Inputs: limit.
exportAIdempotent
Export the knowledge base as a self-contained directory snapshot (sections, documents, catalog -- no indexes).
Inputs: path.
gapsARead-onlyIdempotent
Report what this knowledge base is repeatedly asked and answers badly, worst first. Call it to decide what to learn next. Ranking is triage, not measurement: the log records how each search went, never whether the answer helped.
Inputs: limit, since.
gcADestructive
Remove unreferenced sections from the knowledge base. A section is eligible when no document manifest references it.
Inputs: no named parameters.
historyARead-onlyIdempotent
List every revision of a section, oldest first, and name the current one. Call it when a kb-id you hold no longer appears in search: revisions are retired, not deleted, so a stale kb-id still leads to the text that replaced it. A section revised once has two revisions; one never revised has one.
Inputs: kbid (required).
learnAIdempotent
Store durable knowledge in the agent's second brain. Store decisions, corrections, and facts that cost real effort to find. Do not store what the code or docs already say, chat summaries, guesses, or secrets. When a stored fact is wrong, fix it with revise, not a second copy. Structured content (Markdown, HTML, TOML) splits into sections sharing a docid, each carrying a level and a parent. Attach tags for scoping. replace matches on title within its document and heading path; a title with neither matches on title alone, so name things distinctly.
Inputs: content (required), tags, type, docid, +4 more.
mark_resultAIdempotent
Record whether a recalled section answered a query. Accumulates real usage into an eval dataset. Call it once you know whether a result helped, including when it did not -- a wrong answer is the more useful judgement.
Inputs: kbid (required), query (required), useful (required).
neighbourhoodARead-onlyIdempotent
List what relates to a section and HOW, so you can decide what to read next. Eight relations: supersedes, superseded-by, parent, child, sibling, references, referenced-by, similar. Seven are recorded facts; only "similar" is inferred from a cosine. Related is not relevant -- judge these against your task.
Inputs: kbid (required), limit.
rebuildA
Reconstruct all index files from section files and document manifests on disk. Use this to recover from index corruption.
Inputs: no named parameters.
recallARead-onlyIdempotent
Expand remembered context after search. Retrieves full content and context for sections by identifier, returning section text, level, parent, metadata, references, and back-references. Call it on the kbids search returned. Use maxTokens to bound the payload, and format: compact when you only need the content.
Inputs: kbid, depth, kbids, format, +2 more.
retrieveARead-onlyIdempotent
Low-level fetch of a section or document by identifier. For AI agent workflows, prefer recall which includes metadata, context, and back-references.
Inputs: kbid, docid.
reviseADestructive
When a stored fact is wrong, fix it with revise, not a second copy. Content addressing means the correction gets a NEW kb-id. The old one is retired, not deleted: it stops appearing in search, still reads by kb-id, and "history" walks between them. Fields you omit keep their existing values.
Inputs: kbid (required), content (required), tags, docid, +3 more.
save_evalsAIdempotent
Validate and persist retrieval eval cases drafted via the eval-generate prompt. Rejects cases whose kbids do not resolve, and drops duplicates. Call it only with kbids a search actually returned; invented ids fail the whole batch.
Inputs: cases (required).
searchARead-onlyIdempotent
Recall relevant knowledge by ranked keyword and semantic (hybrid) relevance. Returns ranked results with heading, snippet, matched terms, level, parent, and sectionType. Sections from the same document receive a sibling score boost when multiple sections match. Use multiple short keyword queries for best coverage. Use recall for full content. A retrieval_verdict of "unanswered" means kbdb does not have it: investigate, do not guess.
Inputs: query (required), algo, mode, docid, +4 more.
skill-contentCRead-onlyIdempotent
Shorthand for content with sectionType: skill. Deprecated; removal in 2.0.0.
Inputs: ids (required).
skill-learnAIdempotent
Shorthand for learn with sectionType: skill. Skills are prompt templates; use {{argName}} placeholders for arguments. Deprecated; removal in 2.0.0.
Inputs: content (required), tags, type, docid, +3 more.
skill-recallARead-onlyIdempotent
Shorthand for recall with sectionType: skill. Deprecated; removal in 2.0.0.
Inputs: kbid, depth, kbids, format, +1 more.
skill-searchARead-onlyIdempotent
Shorthand for search with sectionType: skill. Deprecated; removal in 2.0.0.
Inputs: query (required), algo, mode, docid, +3 more.
skill-unlearnADestructiveIdempotent
Shorthand for unlearn with sectionType: skill. Deprecated; removal in 2.0.0.
Inputs: kbid (required), docid.
statusARead-onlyIdempotent
Get knowledge base status including document count, section count, index size, and cache statistics.
Inputs: no named parameters.
unlearnADestructiveIdempotent
Remove a section from the knowledge base by its kb-id, or an entire document (and its member sections) by docid.
Inputs: kbid (required), docid, sectionType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Several tools occupy very similar ground: retrieve, recall, and content all fetch material by identifier with different levels of context, and the 10 deprecated skill-*/agent-* tools duplicate the core learn/search/unlearn/recall/content operations. The descriptions help somewhat, but an agent faces many near-overlapping choices for simple read and write actions.
Naming is a mix of single-word verbs and nouns (learn, search, status, neighbourhood, gaps), bare abbreviations (gc, rebuild), verb_noun names with underscores (save_evals, mark_result), and a hyphenated compound (auto-capture-review). The deprecated skill-* and agent-* names introduce a third resource-prefix convention, so no coherent naming pattern holds across the set.
Thirty tools is too many for this server, especially because ten are deprecated shorthands that should not be used. The 20 core operations are already extensive, so the deprecated duplicates add real selection burden and make the surface feel bloated.
The knowledge-base lifecycle is well covered: create/learn, read/search/recall/retrieve/content, update/revise, delete/unlearn, plus maintenance (check, gc, rebuild, status) and evaluation (mark_result, save_evals, contradictions, gaps). A notable gap is the lack of an import/restore tool to complement the export snapshot, but agents can work around it.
Maintenance
Related MCP Connectors
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables intelligent ingestion and querying of PDF, Markdown, and text files using hybrid search that combines keyword matching and semantic embeddings with citations.2-
- AlicenseNot gradedqualityCmaintenanceProvides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.34Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to parse and search documents including PDF, Word, Excel, PowerPoint, and images via OCR, with support for semantic search and batch processing.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents with long-term memory and retrieval-augmented generation (RAG) capabilities, allowing them to recall past conversations, search local files, and learn user preferences.MIT