1  # NeuralOS Unified Graph RAG & Embedding Space Specification
   2  
   3  ## 1. Concept
   4  
   5  Traditional RAG uses isolated vector embeddings to retrieve text snippets, lacking awareness of entity relationships, hierarchies, or system constraints.
   6  NeuralOS solves this by unifying:
   7  1. **EmbeddingGemma-2**: Maps text, concepts, skills, and torrents into a single 768-dimensional vector space.
   8  2. **NetworkX Directed Graph**: Tracks semantic connections (`prerequisite_for`, `complements`, `belongs_to`, `has_genre`, `prioritizes`).
   9  3. **Hybrid Retrieval**: Combines semantic cosine similarity search with 1-hop and 2-hop topological neighbor traversal.
  10  
  11  ---
  12  
  13  ## 2. Database Schema (`/var/neural_memory/data/graph_rag.db`)
  14  
  15  ### `nodes` Table
  16  - `id` (TEXT PRIMARY KEY): Unique identifier (e.g. `skill:grpo-rl-training`, `movie:interstellar`, `pref:video_4k`).
  17  - `type` (TEXT): Node category (`skill`, `torrent`, `fact`, `preference`, `agent`, `concept`).
  18  - `title` (TEXT): Human-readable title.
  19  - `content` (TEXT): Full textual representation.
  20  - `metadata` (JSON): Additional key-value attributes.
  21  - `embedding` (BLOB): 768-float32 binary vector (3,072 bytes per node).
  22  - `created_at` (REAL): Unix timestamp.
  23  
  24  ### `edges` Table
  25  - `source` (TEXT): Source node ID.
  26  - `target` (TEXT): Target node ID.
  27  - `relation` (TEXT): Semantic edge type.
  28  - `weight` (REAL): Association strength (0.0 to 1.0).
  29  - `created_at` (REAL): Unix timestamp.
  30  
  31  ---
  32  
  33  ## 3. Supported Entity Categories
  34  
  35  | Type | Count | Description |
  36  | :--- | :--- | :--- |
  37  | **`skill`** | 98 | AI research skills across 23 subfields (RL, RAG, Serving, etc.) |
  38  | **`concept`** | 25 | Category taxonomy nodes and conceptual groupings |
  39  | **`agent`** | 7 | Operational agents (`nova`, `code-reviewer`, `ui-tester`, etc.) |
  40  | **`preference`** | 3 | Chief Architect rules (4K quality, concise CLI tone, zero hallucination) |
  41  | **`torrent`** | 3+ | Movies, series, and multi-gigabyte collections in Magnet Vault |
  42  | **`fact`** | 2+ | Hardware topology and immutable operational knowledge |
  43  
  44  ---
  45  
  46  ## 4. Usage CLI
  47  
  48  - Statistics: `graph-rag stats`
  49  - Semantic Vector Search: `graph-rag search "<query>"`
  50  - Hybrid Graph RAG: `graph-rag hybrid "<query>"`
  51  - Batch Ingestion: `graph-rag ingest <payload.json>`
  52