<p align="center">
  <img src="https://img.shields.io/badge/tests-157%20passed-green?style=flat-square&logo=vitest" alt="tests" />
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license" />
  <img src="https://img.shields.io/badge/MCP-ready-purple?style=flat-square&logo=claude" alt="MCP" />
  <img src="https://img.shields.io/badge/SQLite-FTS5%2BVector-blue?style=flat-square&logo=sqlite" alt="SQLite" />
</p>

<h1 align="center">auto-knowledge-base</h1>

<p align="center">
  <strong>MCP knowledge base for engineering agents.</strong>
  <br />
  Built-in BM25 + vector hybrid search, FSRS-6 spaced repetition, and role-based knowledge diffusion.
</p>

<p align="center">
  <code>knowledge_search</code> · <code>knowledge_learn</code> · <code>knowledge_confirm</code> · <code>knowledge_relevant</code>
  <br />
  <i>Claude Code / Cursor / Windsurf · one <code>npm install</code></i>
</p>

---

## Quick Start

```bash
# 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

```bash
# 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`):

```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

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

---

## Design

- [Design goals](docs/design-goals.md)
- [QA plan](QA.md)

---

<p align="center">
  <a href="CONTRIBUTING.md">Contributing</a> ·
  <a href="README.zh-CN.md">简体中文</a>
</p>