knowledgebased

A reusable Model Context Protocol server that provides semantic search and a tag-based knowledge graph for any project. Auto-discovers a knowledge directory from cwd; silently disables when absent.

Written in TypeScript. Uses local sentence-transformer embeddings (Xenova/multilingual-e5-small) — no API keys, no network calls after the first model download.

Features

• 🔍 Semantic search — embedding-based natural language queries (multilingual)
• 🤖 RAG search — tiered results with automatic LLM summarization via MCP sampling
• 🏷️ Tag search with graph traversal — follow related: links across fragments
• 📝 Markdown fragments with YAML frontmatter — human-readable, git-friendly
• 🚀 Zero overhead when unused — exits silently if no knowledge is present
• 🔧 Flexible auto-discovery — co-located, hidden, sibling, or user-global

Quick Start

Install

npm install -g knowledgebased
# or run on demand:
npx -y knowledgebased setup

setup registers the server in ~/.copilot/mcp-config.json (or you can configure any MCP client manually). It will:

• Auto-activate in any project where knowledge is discovered
• Stay disabled (zero overhead) elsewhere

Per-repo install (any MCP client)

Add to your .mcp.json / client config:

{
  "mcpServers": {
    "knowledge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "knowledgebased"]
    }
  }
}

Knowledge Discovery

The server discovers knowledge from two independent phases, then unions all results.

Given cwd = ~/workspace/my-project/, here is every location the server checks:

~/
├── .knowledgebased.json                  ← Phase 2: user-global config (always read)
├── notes/                                ← Phase 2: external KB (declared in bases)
│   └── *.md
│
└── workspace/
    ├── my-project.knowledge/             ← Phase 1 ④: sibling folder
    │   └── *.md
    │
    └── my-project/                       ← cwd
        ├── .knowledge.json               ← Phase 1 ①: config pointer (highest pri)
        ├── knowledge/                    ← Phase 1 ②: co-located, visible
        │   └── *.md
        ├── .knowledge/                   ← Phase 1 ③: co-located, hidden
        │   └── *.md
        └── src/

Phase 1 — project source

Walks up from cwd. At each ancestor directory, tries four patterns in order — first match stops the entire walk:

Priority	Pattern	Within git root	Beyond git root
①	.knowledge.json	✅	✅ (explicit intent)
②	knowledge/	✅	❌ (too generic)
③	.knowledge/	✅	❌ (too generic)
④	../<project>.knowledge/	✅	✅ (explicit naming)

Beyond the git root, only explicitly-intentioned patterns (① config pointer and ④ sibling) are checked. If no git root is found at all, generic patterns are never used — only ① and ④ apply. This prevents accidental matches with unrelated knowledge/ directories outside a project context.

Result: 0 or 1 project source (alias: repo, refs validated against cwd).

Phase 2 — external knowledge bases

Always runs (even if Phase 1 found a project source). Reads ~/.knowledgebased.json and matches cwd against repos entries.

Result: 0–N external sources (alias: base ID, refs unscoped). Both phases are unioned and deduped by canonical directory hash.

User-global config (~/.knowledgebased.json)

Defines named knowledge bases and binds them to repos:

{
  "bases": {
    "personal": "~/notes",
    "team": { "knowledge": "~/team/conventions", "cacheDir": "~/.cache/team" }
  },
  "repos": {
    "*": ["personal"],
    "~/workspace/my-project": ["team"]
  }
}

Field	Description
bases.<id>	A string path (shorthand) or { "knowledge": "...", "cacheDir": "..." }. Paths support ~ expansion.
repos."*"	Wildcard — these bases are active in every project.
repos.<path>	Array of base IDs to activate when cwd is inside this path. Longest-prefix match wins (segment-boundary, case-insensitive on Windows).

In the example above:

• personal is available everywhere (wildcard "*")
• team is only available when working inside ~/workspace/my-project
• Fragments from external sources are prefixed with their alias: personal@notes/foo.md

Per-project config (.knowledge.json)

Points to a knowledge directory that lives elsewhere:

{ "knowledge": "../shared-kb", "cacheDir": "./.cache/embeddings" }

Field	Required	Description
knowledge	optional	Path to the knowledge directory. Resolved relative to the config file. Defaults to ./knowledge.
cacheDir	optional	Override for the embedding cache. Defaults to ~/.cache/knowledgebased/<hash>.

Validation rules

These conditions cause a loud startup error:

• repos references a non-existent base ID
• Base ID is "*", or contains @, /, or spaces
• Two bases resolve to the same canonical directory

Knowledge Fragments

Markdown files with YAML frontmatter:

---
tags: [workflow, git]
related: [workflow/branch-naming]
source: session/2026-04-21
verified: false
refs: [src/utils.ts::parseArgs]
---
# Fragment Title

Content goes here...

MCP Tools

Tool	Description
search_knowledge	Tag-based search with graph traversal
search_semantic	Embedding-based semantic search with similarity scores
search_rag	Semantic search with automatic LLM summarization via MCP sampling
list_tags	List all tags with counts
list_sources	List loaded knowledge sources
add_knowledge	Create a new fragment
update_knowledge	Update an existing fragment
delete_knowledge	Delete a fragment permanently
audit_knowledge	Validate refs and related links
reload_sources	Re-discover sources from config

Which search tool to use?

User question
│
├─ "What topics does the KB cover?" → search_semantic (explore)
│     Low threshold, scan fragment titles and scores.
│
├─ "How does X work?" → search_rag (answer)
│     Returns concise summary + references.
│     If key details are missing, follow up with search_knowledge.
│
└─ "Give me everything about Y" → search_knowledge (enumerate)
      tags=["Y"], returns full unabridged content.

search_rag — RAG-style search

search_rag combines semantic search with MCP client sampling to deliver concise, query-aware results. Results are split into tiers:

Tier	Score	Behavior
direct	≥ directThreshold (0.85)	Full content returned verbatim
related	One-hop graph neighbors of direct hits	Summarized via LLM sampling
summarized	≥ threshold (0.80), < directThreshold	Summarized via LLM sampling

Every response includes a references table listing all used fragments with their similarity score, tier, and reason for inclusion.

When the MCP client doesn't support sampling, summarized/related fragments fall back to metadata-only output (title, tags, and a content preview).

Parameters:

Parameter	Default	Description
query	—	Natural language search query
threshold	0.80	Minimum similarity score for inclusion
directThreshold	0.85	Score above which fragments are returned verbatim
maxTokens	500	Max tokens for the LLM summary

CLI Commands

knowledgebased setup                         # Register globally in ~/.copilot/mcp-config.json
knowledgebased init                          # Create knowledge/ in cwd
knowledgebased init --knowledge ../other/kb  # Create .knowledge.json pointing elsewhere

Development

npm install
npm run build      # compile TS → dist/
npm test           # run unit tests via node:test + tsx
npm start          # run from compiled output
npm run watch      # incremental rebuild

License

MIT