@dikolab/kbdb 0.2.2 → 0.3.0

package/README.md

@@ -26,11 +26,36 @@ It runs anywhere Node.js or Deno runs. Import your
 Markdown files, and kbdb indexes them automatically.
 Search returns ranked results instantly.
 
+kbdb uses **lexical search** (keyword matching with
+stemming and synonym expansion), not semantic
+embeddings. This is a deliberate tradeoff: fast,
+offline, deterministic, and zero embedding cost.
+When AI agents are the primary consumers, lexical
+search works well -- agents can issue multiple
+keyword queries, use boolean/phrase syntax, and
+expand vocabulary themselves. When an exact-match
+query returns nothing, kbdb automatically retries
+with relaxed OR matching so you always get the
+best available results. Write clear headings
+(they carry 2x ranking weight) and use specific
+terms for best recall.
+
+kbdb tracks **knowledge freshness** automatically.
+Re-learn a file and supersession replaces the old
+version instead of duplicating it. Near-duplicate
+detection warns you before content drifts.
+Integrity checks catch contradictions between
+versions of the same source. Confidence scores
+let agents tell strong matches from weak tail
+results.
+
 As a bonus, kbdb also works as an MCP server --
 giving AI agents like Claude a searchable second
 brain. Store skills, agent profiles, and
 documentation that your AI can query across
-sessions.
+sessions. Default skills (`query-guidance` and
+`memory-protocol`) teach agents how to search
+effectively and what to store.
 
 ---
 
@@ -80,7 +105,9 @@ kbdb learn ./docs --db ./my-kb
 
 Point it at a folder of Markdown files. kbdb reads
 them, breaks them into sections, and builds a
-search index.
+search index. Add `--tags design,v2` to tag
+sections for scoping, or `--replace` to supersede
+existing sections from the same source.
 
 **3. Search**
 
@@ -88,9 +115,11 @@ search index.
 kbdb search "how does auth work" --db ./my-kb
 ```
 
-Results are ranked by relevance with snippets
-showing matched terms in context. Use `--offset`
-to page through large result sets.
+Results are ranked by relevance with confidence
+scores and snippets showing matched terms in
+context. Each result includes `matched_fields`
+(heading, body, code) and `created_at` timestamps.
+Use `--offset` to page through large result sets.
 
 **4. Recall context**
 
@@ -109,18 +138,24 @@ referenced sections.
 
 ## What Can It Do?
 
-- **Import** Markdown files and other documents
-- **Search** with ranked results, snippets, and
-  paginated output
+- **Import** Markdown files and other documents,
+  with tags and source tracking
+- **Supersede** outdated sections automatically
+  when re-learning from the same source
+- **Search** with ranked results, confidence
+  scores, snippets, and paginated output
+- **Relaxed fallback** -- automatic OR retry when
+  exact AND queries return nothing
 - **Recall** sections with progressive context --
   from a quick summary to full related content
+- **Export** the database as a portable snapshot
 - **Skills** -- store reusable prompt templates
   with placeholder arguments
 - **Agents** -- create AI agent profiles that
   combine a persona with skills
 - **Manage** documents, sections, and metadata
-- **Verify** database integrity and clean up
-  unused data
+- **Verify** database integrity, detect
+  contradictions, and clean up superseded data
 - **Rebuild** indexes if anything goes wrong
 
 See the [CLI Reference](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/cli.md)
@@ -132,10 +167,10 @@ for the full command list and examples.
 
 kbdb runs as an
 [MCP](https://modelcontextprotocol.io/) server
-with 18 tools, so AI agents can search your docs,
-recall context progressively, store reusable
-skills, and build agent profiles -- a second brain
-that persists between sessions.
+with 19 tools, so AI agents can search your docs,
+recall context progressively, export snapshots,
+store reusable skills, and build agent profiles --
+a second brain that persists between sessions.
 
 ### Claude Code (CLI)
 
@@ -230,7 +265,7 @@ const results = await client.search({
    offset: 0,
 });
 
-// results = { items, total, offset, limit, has_more }
+// results = { items, total, offset, limit, has_more, relaxed }
 console.log(results.items);
 client.disconnect();
 ```