# kb — the fetch-once knowledge base for AI agents

[![Tests](https://github.com/zonion088-design/kb/actions/workflows/test.yml/badge.svg)](https://github.com/zonion088-design/kb/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[中文文档](README.zh-CN.md)

> **Check before fetching. Save after fetching. Never re-fetch. Never fabricate.**

AI agents repeatedly download the same documents, forget what they learned, and
invent dates or authors when asked to save notes. `kb` adds a local discipline
layer that makes the desired loop explicit:

```text
question → search the library → hit: read and answer
                         └── miss: fetch externally → save → answer
```

![kb fetch-once loop](docs/demo.svg)

## Why kb?

| Problem | Typical knowledge base | kb |
|---|---|---|
| Check before an external fetch | Prompt convention | `kb_search` / `kb_exists` make it explicit |
| Duplicate documents | Often stored twice | Three-layer dedup with merge-on-conflict |
| Missing source metadata | Agent may guess | Blank stays blank; metadata is verbatim |
| Scanned PDFs | Easy to treat as readable | Marked `ocr_required`, never silently faked |
| Chinese search | Often needs embeddings | SQLite FTS5 trigram + short-query fallback |
| Infrastructure | API keys and vector DBs | One local SQLite file |

No embeddings. No API keys. No vector database. Just Python, SQLite, six MCP
tools, a CLI, and a localhost web console.

## 30-second quick start

```bash
git clone https://github.com/zonion088-design/kb.git
cd kb
python -m venv .venv
# macOS/Linux: source .venv/bin/activate
# Windows:    .venv\\Scripts\\Activate.ps1
pip install -r requirements.txt

python kb.py init
python examples/seed_demo.py
python kb.py search "储能系统"
```

The demo data is clearly fictional and safe to delete. Re-running the seed
script demonstrates duplicate detection instead of creating second copies.

## Connect it to an agent

Claude Code:

```bash
claude mcp add kb -- python /absolute/path/to/kb/mcp_kb_server.py
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kb": {
      "command": "python",
      "args": ["/absolute/path/to/kb/mcp_kb_server.py"]
    }
  }
}
```

Then load the operating rules into your agent instructions:

```markdown
@/absolute/path/to/kb/KB_RULES.md
```

## The six MCP tools

| Tool | Result |
|---|---|
| `kb_search` | Search documents with compact snippets and metadata filters |
| `kb_exists` | Check whether a source document is already present |
| `kb_get_doc` | Read the full document with truncation and OCR warnings |
| `kb_save_report` | Save fetched research text and source metadata |
| `kb_save_file` | Archive a local file and extract supported PDFs |
| `kb_stats` | Inspect totals, document types, and OCR backlog |

The write path deduplicates by source `external_id`, file SHA-256, and a
title/date suspected-duplicate check. Existing records are merged by filling
empty fields; existing values are not overwritten.

## Try the web console and CLI

```bash
python server.py          # http://127.0.0.1:8643
python kb.py --help       # init / add-text / add-file / search / get / stats / ...
```

The localhost console gives humans editing and deletion controls while the MCP
tools keep agents on the append-and-search path.

## Honest limitations

- Keyword search, not semantic search: this is intentional and keeps the
  default local and dependency-light.
- OCR is detected and flagged; OCR processing is not included.
- Single user, one machine; no auth, sync, or multi-tenant server.
- PDF extraction quality depends on `pypdf` and the source file.

## Development

```bash
python -m unittest discover -s tests -v
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for focused contributions and
[KB_RULES.md](KB_RULES.md) for the design contract. The roadmap lives in
[docs/ROADMAP.md](docs/ROADMAP.md).

## License

[MIT](LICENSE)