offline-knowledge

Files (200)

• SKILL.md
• auto-update.sh
• bible-parse.py
• INDEX.md · code-corpus/
• embeddings-vector-search.md · code-corpus/ai-llm/
• mcp-server-basics.md · code-corpus/ai-llm/
• nous-research-api.md · code-corpus/ai-llm/
• ollama-api.md · code-corpus/ai-llm/
• openai-compatible-api.md · code-corpus/ai-llm/
• opencode-zen.md · code-corpus/ai-llm/
• openrouter-api.md · code-corpus/ai-llm/
• dependency-management.md · code-corpus/architecture/
• error-handling-strategies.md · code-corpus/architecture/
• logging-monitoring.md · code-corpus/architecture/
• project-structure.md · code-corpus/architecture/
• jwt-auth.md · code-corpus/auth/
• oauth2-google.md · code-corpus/auth/
• password-hashing.md · code-corpus/auth/
• rbac.md · code-corpus/auth/
• go.md · code-corpus/best-practices/
• python.md · code-corpus/best-practices/
• rust.md · code-corpus/best-practices/
• shell.md · code-corpus/best-practices/
• sql.md · code-corpus/best-practices/
• typescript.md · code-corpus/best-practices/
• chrono-timing.md · code-corpus/c++/
• classes-inheritance.md · code-corpus/c++/
• compile-time-programming.md · code-corpus/c++/
• enums-type-safety.md · code-corpus/c++/
• exception-safety.md · code-corpus/c++/
• file-io-streams.md · code-corpus/c++/
• function-objects.md · code-corpus/c++/
• lambda-expressions.md · code-corpus/c++/
• modern-features.md · code-corpus/c++/
• move-semantics-forwarding.md · code-corpus/c++/
• multithreading.md · code-corpus/c++/
• networking.md · code-corpus/c++/
• raii-destructors.md · code-corpus/c++/
• random.md · code-corpus/c++/
• ranges-views.md · code-corpus/c++/
• serialization.md · code-corpus/c++/
• smart-pointers.md · code-corpus/c++/
• stl-algorithms.md · code-corpus/c++/
• stl-containers.md · code-corpus/c++/
• strings-stringview.md · code-corpus/c++/
• templates.md · code-corpus/c++/
• type-traits-sfinae.md · code-corpus/c++/
• arrays-strings.md · code-corpus/c/
• bit-manipulation.md · code-corpus/c/
• command-line.md · code-corpus/c/
• enums-constants.md · code-corpus/c/
• error-handling.md · code-corpus/c/
• file-io.md · code-corpus/c/
• functions-scope.md · code-corpus/c/
• input-output.md · code-corpus/c/
• linked-libraries.md · code-corpus/c/
• linked-list.md · code-corpus/c/
• multi-file-projects.md · code-corpus/c/
• multifile_project · code-corpus/c/
• pointers-memory.md · code-corpus/c/
• …and 140 more

SKILL.md (first lines)

# Offline Knowledge — Cascade Knowledge Lookup Without Internet

## Overview

The offline knowledge tool provides a transparent **cascade lookup** across four local sources, in order of speed/cost:

1. **web_cache** — semantic search (~50ms, zero cost, always checked first)
2. **kiwix-serve** (Docker) — Wikipedia, WikiMed, Wikivoyage, Wikibooks, Wiktionary via ZIM files
3. **mycortex** — personal knowledge brain via RAG
4. **LLM native knowledge** — always available, no lookup needed

**When online:** saves API calls on every cached query — cache hit → skip web_search entirely.
**When offline:** the cascade IS your internet — kiwix ZIM files are a local Wikipedia.

## Installation

```bash
# Step 1: Run the installer
hermes-cortex/install.sh    # steps 11 + 13 cover all offline tools

# Step 2: Download content (interactive menu)
hermes-cortex/ops/offline/prep-offline.sh

# Step 3: Verify
offline_knowledge stats
```

## Usage Protocol — How to Use This in Every Session

### Before `web_search()` — Check Offline Knowledge First

```python
# Step 1: Check offline cascade (cache → kiwix → everything)
offline_result = terminal("""
    offline_knowledge query "your question here"
""")
import json
data = json.loads(offline_result["output"])

if data.get("cache", {}).get("status") == "hit":
    # Cache hit — use cached results directly (fastest, cheapest)
    hits = data["cache"]["hits"]
    # Each hit has: query, summary, urls, similarity
    
elif data.get("kiwix", {}).get("status") == "hit":
    # Kiwix hit — ZIM content has the answer
    results = data["kiwix"]["results"]
    # Each has: title, url (localhost:8080), relevance
    
elif data.get("summary", {}).get("source") == "none":
    # Nothing local — proceed with web_search as normal
    
    # Then STORE the result for next time:
    web_results = web_search("your question here")
    terminal(f"""
        echo '{json.dumps(web_results)}' | web_cache store "your question here" -
    """)
```

### Quick Status Check (First Message of Session)

```bash
offline_knowledge stats
```

If kiwix-serve isn't running, start it:
```bash
docker compose -f ~/.hermes-cortex/offline/kiwix-docker-compose.yml up -d
```

## Pre-Flight Checklist (Before Going Offline)

```bash
# 1. Download all content
hermes-cortex/ops/offline/prep-offline.sh --mode=travel   # or build/education/all

# 2. Verify everything works
offline_knowledge stats
# Expected: web_cache ✅, kiwix-serve ✅, mycortex ✅
# Expected: ZIM files listing with correct sizes

# 3. Test a cascade query
offline_knowledge query "how to treat a snake bite in the jungle"
# Should return results from ZIM content (no internet needed)

# 4. Done. Unplug and go.
```

## Command Reference

| Command | Description |
|---------|-------------|
| `offline_knowledge query <question>` | Cascade: cache → kiwix → mycortex (recommended) |
| `offline_knowledge cascade-search <question>` | Detailed per-source results |
| `offline_knowledge kiwix-search <term>` | Direct ZIM full-text search |
| `offline_knowledge kiwix-status` | Check if kiwix-serve is running |
| `offline_knowledge kiwix-list` | List all loaded ZIM content |
| `offline_knowledge generate-library` | Regenerate library XML from ZIM files |
| `offline_knowledge bible search "verse" --lang en` | Search Bible translations |
| `offline_knowledge bible list` | List available translations |
| `offline_knowledge hymns search "Amazing Grace"` | Search hymn lyrics across all hymns |
| `offline_knowledge hymns list` | List hymn resources (PDF, ABC, XML) |
| `./ops/offline/prep-bible.sh --langs=all` | Download all Bible translations |
| `./ops/offline/prep-hymns.sh` | Download public domain hymns from Open Hymnal Project |
| `python3 ops/offline/offline-reader.py` | Launch local web UI for browsing Bible, hymns, and reference |
| `./ops/offline/auto-update.sh` | Check for content updates (silent if offline) |
| `offline_knowledge stats` | Full system status |
| `offline_code search <query>` | Semantic + keyword search over 367 code snippets, 27 languages |
| `offline_code search "<query>" --lang go` | Search filtered by language |
| `offline_code gen "<prompt>"` | RAG code generation using Ollama (context from matching snippets) |
| `offline_code gen "<prompt>" --model qwen2.5:3b` | Code gen with an explicit model (env `CODING_MODEL` pins it) |
| `offline_code index --force` | Rebuild the embedding index (after adding snippets) |
| `offline_code stats` | Corpus statistics |

## Available ZIM Content

| ZIM File | Size | What it covers |
|---|---|---|
| `wikivoyage_en_all_nopic` | 232 MB | Travel guides, phrasebooks, safety info for 33,000+ destinations |

From lukemcqueen/hermes-cortex, MIT.

More from lukemcqueen/hermes-cortex