Knowledge & Graph-RAG

mosaic-knowledge is a pure-Rust, dependency-free engine that is include_str!-vendored into every generated app that declares a vector_dbs. It ingests text, code, and books; builds a knowledge graph; and answers with grounded, graph-augmented retrieval. Provider calls (embeddings) happen only at the app's env seams, never inside the engine.

Ingestion tiers

Tier	What it indexes	Notes
`book` / `pdf`	EPUB / DOCX / PDF	pure-Rust parsing, chapter markers, OCR seam (`MOAIC_OCR_CMD`)
`code`	source files + `Cargo.toml`/`package.json`/…	symbol extraction, call sites, import edges
`docs`	markdown / text	tier chunker (parent–child chunks)
git sources	repositories	ADR 0013; delta re-indexing (ADR 0019); latest-changes analysis (K11)

Sources are the declared floor, runtime ceiling: runtime sources can be added without a redeploy (ADR 0014), and persisted to any backend through the OpenDAL seam (ADR 0015).

Retrieval

Hybrid. BM25 (keyword) + vector (cosine) fused by reciprocal rank fusion.
Graph-augmented re-rank (ADR 0047). Personalized PageRank over the persisted document graph, with Louvain communities + modularity; optional cross-encoder re-rank seam (MOAIC_RERANK_*).
Citation. Every answer carries its sources; the assistant/voice rewrite raw references into real page URLs.

Embeddings

Default: a deterministic local 256-dim embedder (no network).
MOAIC_EMBED_LOCAL=1 forces local; MOAIC_EMBED_ONNX_MODEL loads an ONNX sentence model; MOAIC_EMBED_* points at a hosted embedding API.

Book concepts & typed entities (the thesis layer)

Concepts (ADR 0047 P51). Book text is turned into a concept/"topic" graph.
Typed entities (ADR 0047 P52). A gazetteer maps typed entities (person, location, topic, doctrine, council, book, sermon, …) to graph nodes. The DSL declares a floor; the runtime registry adds/removes entities live (add_entity / remove_entity) — persisted and restored at boot, reflected in the graph without re-indexing.

Reports & profile

make_report renders a markdown report over a graph neighborhood.
repo_profile (K6) + knowledge_stats + recent_changes (K11) describe a git source.
CLI: mosaic knowledge-report.

Surfaces

/knowledge — the knowledge sources page (declared floor + runtime).
POST /api/vectordb/{kb}/search — hybrid search.
/api/vectordb/{kb}/entity?name=…, /entities, /gazetteer — typed-entity lookup + runtime curation.
MCP — 23 knowledge tools (see MCP).

The 23 knowledge MCP tools

search_knowledge, read_chunk, list_sources, list_knowledge, list_symbols, list_books, cite, query_graph, find_symbol, find_callers, get_call_graph, find_similar_implementation, find_concept, find_entity, list_entities, list_gazetteer, add_entity, remove_entity, make_report, repo_profile, knowledge_stats, recent_changes, reindex_knowledge.