## Goal

Build a local, self-hosted documentation knowledge base that can ingest software docs, generate embeddings, store them in SQLite, and expose high-quality retrieval through MCP tools and resources.

---

## Core Architectural Decisions

### Storage

Use:

* SQLite for metadata and document storage
* FTS5 for keyword search
* sqlite-vec for vector similarity search

Avoid a separate vector database unless scale requirements emerge.

---

### Embeddings

Use local embedding models via:

* sentence-transformers

Recommended model:

```text
BAAI/bge-base-en-v1.5
```

Store embeddings alongside document chunks.

---

### Ingestion

Primary sources:

1. Git repositories containing Markdown docs
2. Documentation websites via Crawl4AI
3. Sitemap-driven crawls when available

Pipeline:

```text
Source
  ↓
Extract
  ↓
Normalize
  ↓
Chunk by headings
  ↓
Embed
  ↓
Store
```

Track content hashes so unchanged documents are skipped during reindexing.

---

### Retrieval

Implement hybrid retrieval:

```text
FTS5 keyword search
        +
sqlite-vec similarity search
        ↓
Candidate set
        ↓
Reranker
        ↓
Final results
```

Reranker:

```text
BAAI/bge-reranker-v2
```

The retriever owns all ranking logic.

---

### Public Interface

Do not expose vector search directly.

Expose a retrieval service through MCP:

```python
search_docs(query)

get_context(query)

get_doc(path)
```

The MCP layer becomes the stable API.

Clients never interact with embeddings or vectors.

---

## Repository Layout

```text
src/
├── knowledge/
│   ├── models.py
│   ├── chunking.py
│   ├── embeddings.py
│   ├── ingestion.py
│   ├── sqlite_store.py
│   ├── hybrid_search.py
│   ├── reranker.py
│   └── retrieval.py
│
├── sources/
│   ├── git_docs.py
│   ├── crawl4ai_docs.py
│   └── sitemap_docs.py
│
├── mcp_server/
│   ├── tools.py
│   └── resources.py
│
└── cli/
    ├── ingest.py
    └── reindex.py
```

---

## Retrieval Flow

```text
User Query
     ↓
Embed Query
     ↓
FTS5 Search
     +
Vector Search
     ↓
Merge Results
     ↓
Rerank
     ↓
Return Context Bundle
```

Where a context bundle contains:

```python
ContextBundle(
    passages=[...],
    citations=[...],
    related_docs=[...],
)
```

---

## Future Extensions

Without changing the architecture:

* Multiple documentation corpora
* Version-aware retrieval
* Code snippet indexing
* MCP resources for specific topics
* LangGraph integration
* Docker deployment
* Scheduled reindexing

The key design principle is: **treat the vector store as an internal implementation detail and expose a retrieval-oriented MCP interface instead.**