auto-knowledge-base

MCP knowledge base for engineering agents.
Built-in BM25 + vector hybrid search, FSRS-6 spaced repetition, and role-based knowledge diffusion.

knowledge_search · knowledge_learn · knowledge_confirm · knowledge_relevant
Claude Code / Cursor / Windsurf · one npm install

---

Quick Start

# 1. Install
git clone https://github.com/guyeyouhun/auto-knowledge-base.git
cd auto-knowledge-base
npm install                   # installs deps + auto-downloads embedding model (~55MB)
npm run build
node dist/install.js          # creates .env template

# 2. Configure LLM (needed for rerank/synthesis)
# Edit .env:
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o

# 3. Start
node dist/index.js            # runs as MCP server over stdio

No additional services. No embedding server, no vector database, no Python runtime. BM25 and vector search both run in-process with SQLite + ONNX.

---

Usage

# Store knowledge → staging
knowledge_learn(content: "Vite uses Rollup for production bundling", title: "Vite Build")

# Confirm → committed
knowledge_confirm(id: "550e8400-e29b-41d4-a716-446655440000")

# Search (BM25 + vector hybrid + LLM rerank)
knowledge_search(query: "vite rollup")

# Role-aware knowledge push
knowledge_relevant(role: "frontend", task: "configure build tooling")

# Export backup
knowledge_export

---

Core Architecture

Layer	Technology
Retrieval	FTS5 BM25 → cosine similarity → LLM rerank
Embedding	Process-internal ONNX via fastembed (BGESmallZH, 512-dim)
Storage	SQLite + WAL + FTS5 + relation graph + vector columns
Spaced repetition	FSRS-6 for retention optimization
Knowledge diffusion	Role-based BFS activation

Search pipeline

query → BM25 FTS5 → vector cosine rerank
  → if BM25 < limit: vector similarity scan → results
  → (optional) LLM rerank + synthesis

Every stage degrades gracefully. No single failure blocks the response.

Knowledge lifecycle

learn (staging) → confirm (confirmed) → FSRS decay → frozen
                                              ↓
                             refresh queue → content-digester re-digest

---

MCP Tools

Core (4)

Tool	Description
knowledge_search	BM25 + vector hybrid + LLM rerank
knowledge_learn	Store knowledge (staging), auto-dedup
knowledge_confirm	staging → confirmed
knowledge_relevant	Role-based diffusion + BFS activation

Configuration (2)

Tool	Description
knowledge_role_config	Role entry nodes, diffusion depth
knowledge_config	View LLM configuration

Operations (5)

Tool	Description
knowledge_maintenance	FSRS-6 decay sweep
knowledge_export / import	JSON backup / restore
knowledge_audit	Operation log
knowledge_status	Statistics (truth, temperature, relations, embeddings)

Feedback (3)

Tool	Description
knowledge_request_refresh	Request re-digestion (content-digester integration)
knowledge_report_gap	Report knowledge gaps, triggers auto-digest
knowledge_gaps	Query gap records by status/role

---

Configuration

Only the LLM needs to be configured (in .env):

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=your-api-key
LLM_MODEL=gpt-4o

The embedding model (fastembed + BGESmallZH) is automatically downloaded during npm install to knowledge/models/. No embedding configuration needed.

---

Development

npm test                    # 157 tests, 21 files
npm run test:watch          # watch mode
npm run build               # tsc + copy schema

---

Design

• Design goals
• QA plan

---

Contributing · 简体中文