zvec-local-rag-service

What This Skill Does

The zvec-local-rag-service is a specialized tool for deploying an always-on Retrieval Augmented Generation (RAG) backend directly on your local machine. By leveraging the zvec framework and Ollama, this skill transforms your local text files (.txt, .md) into a searchable vector database. It provides an HTTP-based interface for health monitoring, bulk ingestion of documentation, and high-performance semantic search, ensuring your privacy remains intact since no data leaves your local network. It includes management scripts and launchd templates to ensure the service persists as a background process on macOS, making it a robust utility for personal knowledge management.

Installation

To begin, ensure you have Node.js 18+ and an active Ollama instance installed. First, pull the required embedding model using ollama pull mxbai-embed-large. Clone or install the skill via the OpenClaw repository. Navigate to the skill directory and run scripts/manage.sh bootstrap to set up dependencies. For macOS users, execute scripts/manage.sh install-launchd to register the service as a background process. Use scripts/manage.sh start to initialize the service and verify it via scripts/manage.sh health to ensure connectivity to both the RAG service and your local Ollama daemon.

Use Cases

• Technical Documentation Search: Ingest your local library of code docs or API manuals to query them semantically rather than relying on keywords.
• Personal Knowledge Base: Quickly find insights hidden within your markdown notes without needing external cloud tools.
• Local Context for Agents: Provide your AI agents with a high-speed, local source of truth that is always indexed and ready for retrieval.
• Security-Conscious RAG: Perfect for users dealing with proprietary or private data who cannot use public SaaS RAG providers.

Example Prompts

1. "Ingest all my project markdown files located in the ./docs directory into the zvec-local-rag-service."
2. "Search my local documentation for information regarding the authentication flow using the query 'how do I handle OAuth tokens?'"
3. "Check the current status and health of the RAG service and restart it if it is currently offline."

Tips & Limitations

• Security: The service defaults to loopback-only connections (127.0.0.1). If you need to access it from other containers or devices, you must explicitly set the ALLOW_NON_LOOPBACK_HOST environment variable.
• Performance: While mxbai-embed-large provides excellent accuracy, it requires sufficient memory; ensure your machine is not heavily CPU-bound during large ingestion tasks.
• Persistence: While launchd is ideal for macOS, manual management via scripts/manage.sh is recommended for Linux environments. Always audit the launchd.plist file before running the install command to ensure it matches your expected file paths.