@dikolab/kbdb 0.2.1 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ required.
 [GitLab](https://gitlab.com/tech-slaves/knowledge-base-db)
 | [NPM](https://www.npmjs.com/package/@dikolab/kbdb)
 | [JSR](https://jsr.io/@dikolab/kbdb)
-| [License: ISC](LICENSE)
+| [License: ISC](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/LICENSE)
 
 ---
 
@@ -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,21 +138,27 @@ 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](docs/details/cli.md)
+See the [CLI Reference](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/cli.md)
 for the full command list and examples.
 
 ---
@@ -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)
 
@@ -203,7 +238,7 @@ Add to your `claude_desktop_config.json`:
 ### Other AI Agents
 
 Any MCP-compatible agent can connect. See the
-[MCP Server Guide](docs/details/mcp-server.md) for
+[MCP Server Guide](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/mcp-server.md) for
 setup instructions, Deno variants, environment
 variable configuration, and the full list of
 available tools.
@@ -230,13 +265,13 @@ 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();
 ```
 
 See the
-[Library API Reference](docs/details/library-api.md)
+[Library API Reference](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/details/library-api.md)
 for the full API.
 
 ### Development Setup
@@ -257,7 +292,7 @@ A Docker setup is included with all build tools
 HOST_UMASK=$(umask) docker compose run --rm dev bash
 ```
 
-See the [Makefile](Makefile) for all available
+See the [Makefile](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/Makefile) for all available
 build targets.
 
 ### Contributing
@@ -272,17 +307,17 @@ build targets.
 
 ## Documentation
 
-- [Detailed Guides](docs/details/) -- CLI
+- [Detailed Guides](https://gitlab.com/tech-slaves/knowledge-base-db/-/tree/main/docs/details) -- CLI
   reference, MCP setup, search internals, storage
   format, library API
-- [Release Notes](docs/release-notes/)
-- [Architecture Overview](docs/overview.md)
+- [Release Notes](https://gitlab.com/tech-slaves/knowledge-base-db/-/tree/main/docs/release-notes)
+- [Architecture Overview](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/docs/overview.md)
 
 ---
 
 ## License
 
-ISC License -- see [LICENSE](LICENSE) for details.
+ISC License -- see [LICENSE](https://gitlab.com/tech-slaves/knowledge-base-db/-/blob/main/LICENSE) for details.
 
 ---