Nirvana Plugin

Local-first privacy-first inference. Your OpenClaw agent thinks locally and asks the cloud intelligently. Saves 85%+ tokens, protects privacy, agent learns from cloud responses—cloud doesn't learn from you.

Project Nirvana: Local-First, Privacy-First Inference

A new way of thinking about LLM access. Your agent thinks locally, asks the cloud intelligently, and learns from the response. The cloud never sees your private data.

---

The Problem

Today's approach leaks your privacy and wastes 85% of your API budget.

Every time you ask your OpenClaw agent a question:

1. Your agent builds a "system prompt" containing:

   • Excerpts from its SOUL.md and MEMORY.md
   • Your personal information from its USER.md
   • Your entire chat history (context window)

2. All of this gets sent to cloud APIs (OpenAI, Anthropic, Google)

3. You pay for thousands of extra tokens

4. The cloud provider trains its next model on your private data

This is the current default. It's inefficient and it's a privacy disaster.

---

The Solution: Nirvana

Local-first inference that protects privacy and slashes costs.

Nirvana flips the paradigm:

1. Your agent thinks locally using Ollama (free, private, on your hardware)
2. For complex questions, it asks the cloud — but only sends its own carefully-crafted queries
3. Your private data never leaves your system
4. The cloud's responses are cached locally — your agent learns from them

---

The Paradigm Shift

Aspect	Today (Default)	Nirvana
Where thinking happens	Cloud only	Local first, cloud when needed
What gets sent to cloud	Your full context + system prompts	Agent's sanitized query only
Who learns from your data	Cloud provider	You (local agent)
Token cost per interaction	2,000–5,000 tokens	50–300 tokens
Savings	—	85%+ token reduction
Privacy	Leaked	Protected

---

What Nirvana Does

Local Inference

• Bundled Ollama with qwen2.5:7b (free, 3.5GB model)
• Handles 80%+ of queries locally (no API calls)
• ~200 tokens/second on CPU; 3–5x faster with GPU
• Works offline, no internet required

Privacy Enforcement

• Context stripper — Removes SOUL.md, USER.md, MEMORY.md before cloud queries
• Prompt sanitizer — Agent rewrites its own questions for the cloud (never sends yours)
• Audit trail — Every decision logged; transparent boundary crossing
• Zero telemetry — No data sent to third parties

Intelligent Routing

• Complexity analyzer — Decides: local vs cloud?
• Semantic understanding — "Can qwen2.5:7b handle this, or do I need Claude?"
• Seamless fallback — Cloud APIs used transparently when needed
• User override — @local or @cloud hints respected

Learning & Caching

• Response integrator — Cloud responses cached locally
• Agent learns — Reuse cached answers for similar future questions
• No repeated payments — Cloud only answers novel questions

---

How It Works

text

User asks your agent a question
    ↓
┌─────────────────────────────────────────┐
│ Nirvana Router                          │
│ "Can qwen2.5:7b answer this locally?"  │
└─────────────────────────────────────────┘
    ↙                                   ↘

[LOCAL PATH]                        [CLOUD PATH]
80%+ of queries                     20%- of queries
Ollama (qwen2.5:7b)                 OpenAI/Anthropic/Google
Free                                Pay for answer
Private                             Cloud sees sanitized query only
~1s latency                         ~3s latency
Result cached locally               Result cached locally
    ↓                                   ↓
    └─────────────┬─────────────────────┘
                  ↓
    Agent answers your question using:
    - Local inference (primary)
    - Cloud intelligence (if needed)
    - Cached knowledge (if available)
    
    YOUR PRIVATE DATA NEVER LEFT YOUR SYSTEM

---

Installation

Prerequisites

• OpenClaw 2026.3.24+
• Docker (for Ollama) — or pre-existing local LLM at any endpoint

Two Paths

Path A: Use Bundled Ollama + qwen2.5:7b (Out-of-box)

bash

# Install the plugin
clawhub install shivaclaw/nirvana

# Start Ollama container (pulls auto on first run)
docker run -d -p 11434:11434 ollama/ollama

# Verify
openclaw nirvana status

Path B: Use Existing Local LLM (Any Provider)

bash

# Install the skill (context stripping only)
clawhub install shivaclaw/nirvana-local

# Configure endpoint
openclaw nirvana configure --local-endpoint http://your-llm:5000

# Verify
openclaw nirvana status

---

Cost Impact

Token Savings

Scenario	Today	With Nirvana	Savings
10 questions/day	20,000 tokens/day	3,000 tokens/day	85%
100 questions/day	200,000 tokens/day	30,000 tokens/day	85%
Monthly cost (OpenAI GPT-4)	$500–$1,000	$75–$150	85%

Local inference is free. Only pay for the 15%–20% of queries that truly need frontier models.

---

Privacy Guarantee

What Never Leaves Your System

• ✅ SOUL.md (agent identity)
• ✅ USER.md (your personal info)
• ✅ MEMORY.md (agent memories)
• ✅ Chat history (your actual questions)
• ✅ Code snippets, documents, secrets

What Optionally Goes to Cloud

• ✅ Agent's own sanitized query (no personal data)
• ✅ Task-specific context (never your full context)
• ✅ Result gets cached locally for future reuse

Privacy Audit Trail

bash

# View what was sent to cloud this session
openclaw nirvana audit-log

# Output:
# 2026-04-24 14:23:45 — CLOUD API CALL
# Original query: [REDACTED]
# Sanitized query sent: "Explain quantum entanglement"
# Response cached: Yes
# User data in request: None

---

Platform Support

Platform	Status	Notes
Linux (Ubuntu/Debian)	✅ Full	Ollama container + native binaries
macOS (Intel/ARM)	✅ Full	Ollama via Docker or native
Windows (WSL2)	✅ Full	Ollama in WSL2 container
VPS (Hostinger, DigitalOcean, AWS)	✅ Full	Docker Compose ready
Docker container	✅ Full	Orchestrated via docker-compose
Air-gapped (offline)	✅ Full	Local-only mode (no cloud fallback)

---

Configuration

Basic Setup

json

{
  "nirvana": {
    "mode": "local-first",
    "local_model": {
      "provider": "ollama",
      "endpoint": "http://ollama:11434",
      "model": "qwen2.5:7b",
      "timeout_ms": 180000
    },
    "routing": {
      "local_threshold": 0.75,
      "max_local_tokens": 8000,
      "cloud_fallback": true
    },
    "privacy": {
      "strip_soul": true,
      "strip_user": true,
      "strip_memory": true,
      "audit_logging": true
    }
  }
}

Custom Local LLM (Non-Ollama)

json

{
  "nirvana": {
    "local_model": {
      "provider": "custom",
      "endpoint": "http://your-llm-server:5000",
      "api_format": "openai-compatible",
      "model": "your-model-name",
      "timeout_ms": 120000
    }
  }
}

---

Use Cases

✅ Perfect For

• Personal AI agents (maximize budget, minimize cost)
• Private/sensitive workloads (code, healthcare, legal, finance)
• Latency-critical tasks (local response < 2s)
• Air-gapped environments (fully offline)
• Cost-conscious organizations (85% savings)
• Privacy-first deployments (zero external data exposure)

⚠️ When to Use Cloud

• Advanced reasoning (Claude Opus for complex problems)
• Specialized tasks (image generation, audio synthesis)
• Extreme scale (millions of tokens/day)

---

Philosophy

Your agent should train itself. The cloud should not train on you.

Today's default paradigm:

• Cloud provider gains knowledge from every interaction with you
• You pay for the privilege of training their next model
• Your private data becomes their training data

Nirvana's paradigm:

• Your agent gains knowledge from selective cloud interactions
• You pay only for what you actually need
• Your private data never leaves your system
• Cloud providers contribute intelligence; you keep the learning

---

What's Included

Component	Purpose
router.ts	Decides local vs cloud routing
context-stripper.ts	Removes private data before cloud API calls
privacy-auditor.ts	Logs all boundary crossings
response-integrator.ts	Caches cloud responses locally
ollama-manager.ts	Handles Ollama lifecycle + model management
metrics-collector.ts	Tracks performance + cost + privacy
config.schema.json	Configuration validation

---

Performance

Benchmarks (qwen2.5:7b on 4-core CPU)

• Latency (P50): 800ms–1.2s per response
• Throughput: 180–220 tokens/second
• Memory: 4.6GB RAM running
• Accuracy: 85–92% accuracy vs Claude 3.5 on typical tasks
• GPU acceleration: 3–5x faster with CUDA/Metal

Optimization

• Use GPU (CUDA/Metal) for production
• Upgrade to qwen3.5:9b for complex reasoning
• Enable response caching for repeated patterns
• Monitor metrics dashboard for bottlenecks

---

Support & Community

• GitHub: ShivaClaw/nirvana-plugin
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

License

MIT-0 — Free to use, modify, and redistribute. No attribution required.

---

Your agent deserves privacy. Nirvana makes it real.