# Sage Knowledge Vault — Technical Specification & Case Study

> Air-gapped, offline knowledge vault and Hybrid Retrieval-Augmented Generation (RAG) engine. Fuses ChromaDB dense vector embeddings with SQLite FTS5 Okapi BM25 sparse keyword search and AST graph analysis, exposed via a 9-tool Model Context Protocol (MCP) server.

- **Status:** Internal Production // Private Local Vault
- **HTML Case Study:** https://asimansari.com/projects/sage.html
- **Canonical Domain:** https://sage.asimansari.com

---

## 1. Architectural Philosophy: Dual-Engine Hybrid RAG

Relying solely on vector embeddings leads to query-document semantic drift and fails on exact symbol matches (e.g., function names like `sqlite3_step()`, error codes, or specific flags).

Sage implements a **Dual-Engine Reciprocal Rank Fusion (RRF)** pipeline:
1. **Dense Vector Engine (ChromaDB):** Indexes 4,013 curated engineering specification chunks using high-dimensional cosine distance for conceptual queries.
2. **Sparse Lexical Engine (SQLite FTS5):** Employs Okapi BM25 ranking across tokenized codebases and markdown documentation for exact identifier and variable lookups.
3. **AST Graph Traversal (Graphify):** Maps code AST trees and markdown cross-links into structured edges, enabling multi-hop dependency queries.

---

## 2. The 9-Tool Model Context Protocol (MCP) Surface

Sage exposes its knowledge graph to autonomous workstation agents through standard JSON-RPC 2.0 MCP tools:

- `vault_search(query, mode="hybrid")`: Executes reciprocal rank fusion across ChromaDB and SQLite FTS5.
- `vault_read(topic, section)`: Retrieves canonical markdown documentation chunks.
- `vault_symbols(identifier)`: Queries AST symbol definitions and function signatures.
- `vault_graph_neighbors(node_id)`: Explores bidirectional dependency edges in the knowledge graph.
- `vault_verify(claim, source_topic)`: Evaluates factual consistency against verified local text.
- `vault_reindex(path)`: Re-indexes modified documentation and updates FTS5 indexes.
- `vault_stats()`: Reports total chunk counts, token distributions, and index memory footprints.
- `vault_checkpoint()`: Commits atomic SQLite transactions to disk.
- `vault_health()`: Diagnostics check confirming local filesystem accessibility.

---

## 3. Torikago Sandbox Isolation

To guarantee zero telemetry leakage and prevent automated agents from performing unauthorized network egress, Sage operates strictly within the **Torikago** sandboxing environment:
- Network sockets disabled (zero internet access).
- Read-only filesystem mounts over host repository roots.
- All operations execute locally with sub-second terminal response times via `sage ask "..."`.