OpenClaw + RAG (Without SKYNET vibes ;)

═══════════════════════════════════════════════════════════════════════════════
                    OPENCLAW OFFLINE-FIRST WITH GATED FALLBACK
                         (Production Flow - Feb 2026)
v2 (refined)
═══════════════════════════════════════════════════════════════════════════════

                              ┌──────────────────┐
                              │   User Query     │
                              │  (e.g., Veeam HA)│
                              └────────┬─────────┘
                                       │
                                       v
                          ┌────────────────────────┐
                          │  OpenClaw Controller   │
                          │  (Clawbot Framework)   │
                          │ Enforce YAML/JSON Rules│
                          └────────────┬───────────┘
                                       │
                          ┌────────────v────────────┐
                          │ Strong Prompt:          │
                          │ ALWAYS RAG FIRST        │
                          │ (Score ≥0.75)           │
                          └────────────┬────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    │                                     │
          ┌─────────v──────────┐           ┌─────────────v────────┐
          │  MCP TOOL (Priority)│           │  FALLBACK PATH       │
          │  Offline RAG        │           │  (Gated)             │
          │  rag_query.py       │           │                      │
          └─────────┬──────────┘           │                      │
                    │                      │                      │
        ┌───────────┴─────────┐            │                      │
        │                     │            │                      │
    ┌───v────┐          ┌────v───┐    ┌───v─────┐               │
    │ Ollama │          │ ChromaDB│    │ Low Hit │               │
    │Embeddings          Vault    │    │ Rate    │               │
    │nomic-embed          .md Files    (<0.75)   │               │
    └───┬────┘          └────┬───┘    └──┬──────┘               │
        │                    │            │                      │
        └────────┬───────────┘            │ Miss or Low Conf     │
                 │                        │                      │
                 v                        └──────────────────────┘
            ┌─────────────────┐                  │
            │ Hit Rate ≥0.75? │                  │
            └────────┬────────┘                  │
                     │ YES                       │
                     v                           v
            ┌──────────────────┐         ┌───────────────────────┐
            │  LM Studio Synth  │         │ Vault Miss + General  │
            │  Response Gen     │         │ Reasoning (Offline)   │
            │  llama.cpp GGUF   │         │                       │
            └────────┬─────────┘         └───────────┬───────────┘
                     │                               │
                     │                    ┌──────────v──────────┐
                     │                    │ Ask "Online? (y/n)" │
                     │                    └──────────┬──────────┘
                     │                               │
                     │                  ┌────────────┴─────────┐
                     │                  │                      │
                     │            ┌─────v──┐          ┌───────v───┐
                     │            │ YES    │          │ NO/Retry  │
                     │            │ (User) │          │ (User)    │
                     │            └─────┬──┘          └───┬───────┘
                     │                  │                │
                     │        ┌─────────v────────┐     │
                     │        │ Online Fallback  │     │
                     │        │ Grok/Claude      │     │
                     │        │ OpenRouter/xAI   │     │
                     │        │ **RISK-GATED**   │     │
                     │        └─────────┬────────┘     │
                     │                  │              │
                     └──────────┬───────┴──────────────┘
                                │
                    ┌───────────v────────────┐
                    │  Response to User      │
                    └───────────┬────────────┘
                                │
                ┌───────────────┴────────────────┐
                │                                │
           ┌────v──┐                    ┌───────v────┐
           │Logging │                   │ Pite Store │
           │System  │                   │ Hit Rate   │
           │(SQLite)│                   │ Query Log  │
           └────┬───┘                   │ Patterns   │
                │                       └────────────┘
                v
        ┌──────────────────┐
        │ Query Patterns   │
        │ Hit Rate Stats   │
        │ Performance      │
        │ Analysis         │
        └──────────────────┘

═══════════════════════════════════════════════════════════════════════════════
PRIORITY ENFORCEMENT (Strong Prompt Forces this Flow)
═══════════════════════════════════════════════════════════════════════════════

1️⃣  OFFLINE RAG FIRST (99% of queries)
   - Score ≥0.75: Return Chroma hit + LM Studio synthesis
   - Score <0.75: Trigger fallback gate (user confirmation required)
   - NEVER call online without explicit user approval

2️⃣  USER CONFIRMATION GATE (Security Boundary)
   - "Vault miss. Query online for fallback? (y/n)"
   - Prevents silent data exfiltration
   - Logs all online-flagged queries to Pite

3️⃣  ONLINE FALLBACK (Gated + Logged)
   - Only if user confirms "y"
   - Grok/Claude via OpenRouter
   - LM Studio can proxy (OPENAIAPIBASE=https://openrouter.ai/api/v1)
   - Logged to Pite for audit trail

4️⃣  LOGGING & ANALYTICS (Pite Integration)
   - Hit Rate: % queries satisfied offline
   - Query Patterns: Common misses for vault expansion
   - Performance: Latency per phase (embed → search → synth)

═══════════════════════════════════════════════════════════════════════════════
IMPLEMENTATION SKELETON
═══════════════════════════════════════════════════════════════════════════════

config.yaml (OpenClaw):
  tools:
    - name: rag_query
      script: /path/to/rag_query.py
      description: "Offline RAG (ALWAYS called first per strong prompt)"

  system_prompt: |
    CRITICAL: For EVERY user query:
    1. Always call rag_query first (MCP tool)
    2. If hit (score ≥0.75) → use vault context in response
    3. If miss → state "not in vault" + general knowledge
    4. NEVER initiate online fallback yourself
    5. Wait for user confirmation on fallback prompt

rag_query.py (MCP Tool):
  def rag_query(query):
      embeddings = OllamaEmbeddings(model="nomic-embed-text")
      vectorstore = Chroma(persist_dir="./chromadb")
      docs = vectorstore.as_retriever(
          search_type="similarity_score_threshold",
          search_kwargs={"score_threshold": 0.75, "k": 5}
      ).invoke(query)

      hit = len(docs) > 0
      log_to_pite(query, hit, len(docs))  # Analytics

      return {
          "status": "hit" if hit else "miss",
          "chunks": [d.page_content for d in docs] if hit else [],
          "hit_count": len(docs)
      }

fallback_controller.py (OpenClaw Hook):
  def handle_fallback(query, rag_result):
      if rag_result["status"] == "miss":
          user_choice = input("⚠️  Vault miss. Query online? (y/n): ").strip()
          log_to_pite(query, "fallback_asked", user_choice)

          if user_choice.lower() == "y":
              response = call_grok_or_claude(query)  # OpenRouter
              log_to_pite(query, "fallback_used", response)
              return response
          else:
              return "Staying offline. Not in vault & user declined online."

pite_logging.py (SQLite + Analytics):
  def log_to_pite(query, hit_status, details):
      conn = sqlite3.connect("./pite_analytics.db")
      conn.execute("""
          INSERT INTO query_log (timestamp, query, hit_status, details)
          VALUES (datetime('now'), ?, ?, ?)
      """, (query, hit_status, json.dumps(details)))
      conn.commit()

  # Dashboard query:
  SELECT COUNT(*) as total,
         SUM(CASE WHEN hit_status='hit' THEN 1 ELSE 0 END) as vault_hits,
         100.0 * SUM(CASE WHEN hit_status='hit' THEN 1 ELSE 0 END) / COUNT(*) as hit_rate
  FROM query_log;

═══════════════════════════════════════════════════════════════════════════════
KEY METRICS TO TRACK (Pite Dashboard)
═══════════════════════════════════════════════════════════════════════════════

Hit Rate:        % queries answered offline (goal: >85%)
Miss Patterns:   Gaps in vault (e.g., "no docs on X")
Latency:         Embed (50ms) → Search (10ms) → Synth (500ms) = ~560ms offline
Online Calls:    Count & reasons (audit trail for security)
Score Dist:      Histogram of similarity scores (refine threshold)

═══════════════════════════════════════════════════════════════════════════════











╔═══════════════════════════════════════════════════════════════════╗
║                      CHRIS'S OPENCLAW SETUP                       ║
║                    (Tier 1: Strong Prompt)                        ║
╚═══════════════════════════════════════════════════════════════════╝

┌─────────────────────────┐
│   User Query (HTTP)     │ ◄────── Browser/CLI/IDE Extension
│  "Veeam HA best tips?"  │
└────────────┬────────────┘
             │
             v
┌───────────────────────────────────────────────────────────────────┐
│                     OPENCLAW AGENT                                │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │ System Prompt (config.yaml)                             │     │
│  │ ┌─────────────────────────────────────────────────────┐ │     │
│  │ │ CRITICAL: For ANY query, call rag_query first.     │ │     │
│  │ │ Vault info → answer from vault only.                │ │     │
│  │ │ No vault → state "not in vault" + general answer.  │ │     │
│  │ └─────────────────────────────────────────────────────┘ │     │
│  └─────────────────────────────────────────────────────────┘     │
│                                                                    │
│  Controller Logic: Decides tools needed based on query            │
└───────────────────────┬────────────────────────────────────────────┘
                        │
                        v (1. Query Analysis)
        ┌───────────────────────────────┐
        │ Should I use RAG? ──> YES     │ (Strong prompt forces this)
        └───────────────┬───────────────┘
                        │
                        v (2. MCP Tool Call)
┌───────────────────────────────────────────────────────────────────┐
│                    MCP TOOL INTERFACE                             │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  rag_script.py (Python Bridge)                          │     │
│  │  • Receives user query as arg                           │     │
│  │  • Calls embedding model                                │     │
│  │  • Returns JSON with retrieved docs                     │     │
│  └──────────────────────┬──────────────────────────────────┘     │
└─────────────────────────┼─────────────────────────────────────────┘
                          │
                          v (3. Generate Query Embedding)
┌───────────────────────────────────────────────────────────────────┐
│               OLLAMA SERVICE (Localhost:11434)                    │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  Embedding Model: nomic-embed-text (768-dim vectors)    │     │
│  │  • Converts query → [0.234, -0.891, 0.445, ...]         │     │
│  │  • Cached in RAM for fast repeat queries                │     │
│  └──────────────────────┬──────────────────────────────────┘     │
└─────────────────────────┼─────────────────────────────────────────┘
                          │
                          v (4. Similarity Search)
┌───────────────────────────────────────────────────────────────────┐
│                     VECTOR DATABASE                               │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  ChromaDB (Persistent Disk Storage)                     │     │
│  │  • Pre-indexed .md files from /vault/                   │     │
│  │  • Cosine similarity search against query embedding     │     │
│  │  • Returns top-k chunks (default k=5)                   │     │
│  │  Collection: "veeam_docs" (or your collection name)     │     │
│  └──────────────────────┬──────────────────────────────────┘     │
└─────────────────────────┼─────────────────────────────────────────┘
                          │
                          v (5. Return Context to Agent)
┌───────────────────────────────────────────────────────────────────┐
│                     OPENCLAW AGENT                                │
│  • Receives: "Top 3 matches from vault + relevance scores"        │
│  • Constructs prompt: [CONTEXT] {vault_chunks} [QUERY] {question} │
│  • Sends to LLM for final answer synthesis                        │
└───────────────────────┬────────────────────────────────────────────┘
                        │
                        v (6. LLM Reasoning)
┌───────────────────────────────────────────────────────────────────┐
│                   LM STUDIO (Inference Engine)                    │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  Primary Model: Llama 3.1 8B (or Qwen 2.5 14B)          │     │
│  │  • Context: 8k-128k tokens (model dependent)            │     │
│  │  • Reads vault context + user query                     │     │
│  │  • Generates final answer                               │     │
│  │  Endpoint: http://localhost:1234/v1/chat/completions    │     │
│  └─────────────────────────────────────────────────────────┘     │
│                                                                    │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  OPTIONAL: API Proxy (for external models)              │     │
│  │  • Grok API (xAI) ────> /v1/chat/completions            │     │
│  │  • Claude API (Anthropic) ────> /v1/chat/completions    │     │
│  │  LM Studio routes to external endpoints when configured │     │
│  └─────────────────────────────────────────────────────────┘     │
└───────────────────────┬────────────────────────────────────────────┘
                        │
                        v (7. Response Assembly)
┌───────────────────────────────────────────────────────────────────┐
│                     OPENCLAW AGENT                                │
│  • Final answer from LLM                                          │
│  • Formats response with sources/citations                        │
│  • Returns to user interface                                      │
└───────────────────────┬────────────────────────────────────────────┘
                        │
                        v (8. Display)
┌─────────────────────────┐
│  User Interface Output  │
│  ┌───────────────────┐  │
│  │ Answer: Based on  │  │
│  │ vault doc X...    │  │
│  │                   │  │
│  │ Sources:          │  │
│  │ - veeam_ha.md     │  │
│  └───────────────────┘  │
└─────────────────────────┘


╔═══════════════════════════════════════════════════════════════════╗
║                      DATA FLOW SUMMARY                            ║
╠═══════════════════════════════════════════════════════════════════╣
║ 1. Query → OpenClaw Agent (strong prompt enforces RAG call)       ║
║ 2. Agent → MCP Tool (rag_script.py)                               ║
║ 3. Script → Ollama (embedding generation, cached in RAM)          ║
║ 4. Embedding → ChromaDB (similarity search on .md index)          ║
║ 5. Results → Agent (context chunks returned)                      ║
║ 6. Agent → LM Studio (prompt + context for reasoning)             ║
║ 7. LM Studio → Agent (synthesized answer)                         ║
║ 8. Agent → User (formatted response with sources)                 ║
╚═══════════════════════════════════════════════════════════════════╝


╔═══════════════════════════════════════════════════════════════════╗
║                     KEY COMPONENTS                                ║
╠═══════════════════════════════════════════════════════════════════╣
║ OpenClaw Agent    │ Orchestration layer (Node/TS + MCP protocol)  ║
║ LM Studio         │ LLM inference (local + optional API proxy)    ║
║ Ollama            │ Embedding model service (nomic-embed-text)    ║
║ ChromaDB          │ Vector store (persistent, indexed .md files)  ║
║ rag_script.py     │ Bridge: query → embedding → search → results  ║
║ config.yaml       │ System prompt (CRITICAL RAG instruction)      ║
║ /vault/*.md       │ Your knowledge base (pre-indexed)             ║
╚═══════════════════════════════════════════════════════════════════╝

NOTES:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• All processing 100% local except optional Grok/Claude API calls
• Ollama embedding model stays resident in RAM (fast repeated queries)
• ChromaDB index built once, queried many times (no re-indexing needed)
• Strong prompt = 85-95% RAG reliability without pre-processor complexity
• LM Studio can hot-swap models (Llama/Qwen/etc.) without code changes
• MCP protocol = language-agnostic tool interface (Python/JS/Rust/etc.)

https://www.perplexity.ai/search/whats-the-deal-with-clawbot-mo-6nnbZds4SZmkO8j78nTkMg#16
https://cgfixit.com/livecode