OmniClip RAG

📖 Table of Contents (Click to expand)

• [TL;DR: MCP Quickstart](#-mcp-usage)
• [Core Philosophy & Priceless Boundaries](#-core-philosophy--priceless-boundaries)
• [Core Features](#-core-features)
• [Quick Start & Workflow](#-quick-start--workflow)
• [MCP Usage](#-mcp-usage)
• [High-Leverage Mental Models & Workflows](#-high-leverage-mental-models--workflows)
• [Minimalist & Restrained Architecture](#-minimalist--restrained-architecture)
• [Geek & Developer Entry Points](#-geek--developer-entry-points)
• [Recent Version Trace](#-recent-key-updates)
• [Documentation Hub](#-documentation-hub)
• [Open Source Thanks & License](#-open-source-thanks)

> [!TIP] > TL;DR: MCP Quickstart > > OmniClip RAG now ships a read-only local-first MCP server for searching private Markdown, PDF, and Tika-backed knowledge bases on Windows. > Download OmniClipRAG-MCP-v0.4.8-win64.zip for manual stdio setup or omniclip-rag-mcp-win-x64-v0.4.8.mcpb for the official MCP Registry / MCPB path. > Point your MCP client at OmniClipRAG-MCP.exe, then ask the AI to call omniclip.status first and omniclip.search for the actual retrieval flow. Full details: [MCPSETUP.md](MCPSETUP.md).

What is it? It is a local Markdown semantic search software, a local RAG knowledge base, and now a read-only MCP retrieval server.

How to use it? Just open the application, input your Markdown notes path, and click "Build Knowledge Base" to set up your local RAG vault. Once built, you can use it to semantically search your notes. The retrieved content can be copied and sent to any AI for in-depth discussion, or used for your own deep reading.

What are the benefits? No need to upload any of your data, and no vendor lock-in. It requires no complex configuration or setup. Moreover, it features hot-reloading—newly written notes automatically enter the RAG vault! New notes can also be an organized collection of your historical conversations with AIs, which in turn implicitly provides a permanent memory for them.

> [!NOTE] > Introduction: Handing Over Our "Cyber-Underwear" in the AI Era! > > OmniClip RAG uniquely achieves the impossible: You can have it all! > > - We Demand: Our Markdown notes remain completely ours. > - We Also Demand: Any AI to deeply participate within our permitted and supervised scope. The note vault and the AI must be deeply decoupled yet highly interactive. > - And We Demand: An out-of-the-box experience without any tedious setup, featuring a robust hot-reload capability so new notes automatically enter the RAG semantic pool! It can even compile your historical AI conversations, granting your LLMs a permanent, rolling memory. > > In the AI era, the more we rely on large models, the more personal privacy we surrender. Most knowledge base RAG tools on the market are either agonizingly complex to configure (involving server-like Docker or Python environments), demand a steep learning curve that costs too much time, forcibly tether you to a bloated chat interface, or require you to upload your notes completely. They all attempt to lock your data into their products, making it impossible for you to ever leave them. > > To ensure my notes and thoughts genuinely remain mine, I spent considerable time thinking through and comparing numerous possibilities before finalizing and hand-crafting this pure local semantic retrieval tool—OmniClip RAG. I pushed its core functionalities to the absolute limit, ensuring that it both runs smoothly on most computers and maintains professional-grade capabilities. It functions as a local knowledge firewall, allowing you to selectively let AI deeply read your "second brain" without worrying about your data being hijacked by any cloud or local software.

🎯 Core Philosophy & Priceless Boundaries

OmniClip RAG is a radically decoupled "privacy firewall" and "manual-transfer local RAG search engine" meticulously crafted for the Markdown note ecosystem (natively compatible with Logseq, Obsidian, Typora, MarkText, Zettlr, and any plain text application).

It exclusively performs one highly refined task: it semantic-searches tens of thousands of pages locally via embedded vector algorithms (e.g., BAAI/bge-m3) and structural indexing, meticulously packs the most high-value contextual snippets, and lets you manually clip and paste them into any external top-tier AI (such as ChatGPT, Claude, Kimi, etc.) for profound interactions. In short: As long as your materials are in Markdown formats, this engine acts as the ultimate "second brain permanent memory extractor."

👉 Click to expand: Why Was It Built This Way? (Core Philosophy)

• Absolute Privacy Isolation: External AIs can only leverage the contextual fragments you explicitly bundle and offer via the semantic engine under your supervision. They have zero access to the rest of your vault. Your absolute data sovereignty is inviolable here.
• A Highly Decoupled "Brain-Machine Interface": It binds to no single AI chat UI. If Claude handles complex code better today, you clip content to Claude. If GPT-5 transforms logic modeling tomorrow, you feed the same snippet there. This ensures physical independence between the tool and note content, freeing you from setup locking and platform binding.
• Pursuing the "Strong Lindy Effect": I hope this serves as a memory lighthouse that won't become obsolete in the distant future. As long as the concept of plain text and Markdown persists, you will be able to summon faded historical insights you’ve personally forgotten, powered tightly by this clean and lightweight engine.

✨ Core Features

OmniClip is intentionally not trying to win with flashy UI tricks. The real work went into making local knowledge retrieval dependable, explainable, and maintainable without forcing users into cloud upload or environment chaos.

Local-first by default: indexes, logs, caches, and runtime payloads are managed under %APPDATA%\OmniClip RAG instead of polluting your source notes or requiring a cloud round-trip. Deep Markdown / Logseq understanding: beyond plain Markdown, the parser understands Logseq-style page properties, block properties, block refs, and embeds, so retrieval stays closer to how you actually write. Real hybrid retrieval: combines SQLite + FTS5 + structure-aware scoring + LanceDB vector search so it can catch both exact terms and semantically related ideas. Physically isolated extension formats: Markdown, PDF, and Tika-backed formats keep separate indexes and states, returning unified results with explicit source labels. Traceable query results: results carry source labels, page/format identity, score hints, and state messaging so users can understand why something was returned instead of trusting a black box.

Large Tika format exposure: exposes 1290 extension formats with clear risk tiers for recommended, unknown, untested, and poor-compatibility items. Lean packaged app, external Runtime: the EXE stays lightweight while Runtime components are managed separately, with shared AppData installation and legacy-runtime reuse. Build flows that explain themselves: preflight, rebuild, incremental watch, and Tika auto-install surface stage, progress, and failure reasons instead of leaving users staring at a frozen screen. Degrade before crashing: damaged files, empty files, offline paths, missing runtime pieces, and GPU pressure are all handled with skip/retry/fallback strategies wherever possible. A standard MCP interface: OmniClipRAG-MCP.exe exposes the same local search kernel through a read-only MCP server, so MCP-capable AI clients can query your private knowledge base.

⚙️ Configuration and Indexing UI

🌙 Dark Mode Aesthetics

🚀 Quick Start & Workflow

OmniClip perfectly integrates smoothly into your workflow:

1. Continue writing quietly in your local Markdown vault for extended periods.
2. Double click the OmniClip app—it will transparently and silently maintain a mixed-search index of your vault.
3. When searching for insights, punch in keywords or short sentences. OmniClip will extract and assemble unparalleled fragments in a single click.
4. Paste that rich context bundle directly into the smartest AI model available at the moment.

First-Time Use Guide

The foundation is built as a single portable green EXE. No complicated scripting or dev environments are needed. Just pure "Download, double-click, and run":

1. Launch the desktop app interface.
2. Select the root folder of your note vault.
3. Confirm the data directory (OmniClip refuses to soil or modify your raw notes).
4. (First run) Initiate the space-and-time precheck to estimate load constraints.
5. (First run) Start a one-click model bootstrap (downloads and caches the local model).
6. Finally, trigger a Full Build (index once, run forever via hot reload tracking).
7. Once built, start searching! Find brilliant slices, click to copy snippets, and send them to your favorite LLMs.

🔌 MCP Usage

OmniClip RAG MCP Server lets MCP-capable AI clients search your local knowledge base through the same read-only retrieval core that powers the desktop app.

From v0.4.8, the MCP line is packaged in two parallel distribution forms:

• OmniClipRAG-MCP-v0.4.8-win64.zip for manual file-based setup
• omniclip-rag-mcp-win-x64-v0.4.8.mcpb for the official MCP Registry and MCPB-aware clients

> [!CAUTION] > What You Need First > Use OmniClipRAG-MCP.exe only as the headless read-only bridge for AI clients. It does not build knowledge bases. You MUST build or install your knowledge base from the desktop app first. > If your index has not been built yet, the MCP side will return an explicit index_not_ready style error instead of silently pretending everything is fine.

🛠️ Click to expand: Official Route & Traditional Setup Guide

Official Route (Registry / MCPB)

Since v0.4.1, OmniClip RAG keeps a first-class MCP Registry / MCPB line, so clients that support Registry discovery or MCPB installation can use that path first.

• If your client supports Registry discovery, look for: io.github.msjsc001/omniclip-rag-mcp
• If your client supports MCPB installation, prefer the Release asset: omniclip-rag-mcp-win-x64-v0.4.8.mcpb

For the full Registry/MCPB explanation and client-specific setup notes, see [MCPSETUP.md](MCPSETUP.md).

Traditional Manual Route (Jan.ai / OpenClaw)

If you downloaded the ZIP package manually, or your client does not support the official MCPB format yet, use the traditional absolute-path stdio setup.

Jan.ai Reference Setup

In Jan.ai, create a new MCP server with the following values:

• Server Name: OmniClip RAG
• Transport Type: STDIO
• Command: the full path to OmniClipRAG-MCP.exe (e.g. D:\Apps\OmniClip RAG\dist\OmniClipRAG-MCP-v0.4.8\OmniClipRAG-MCP.exe)
• Arguments: leave empty
• Environment Variables: leave empty by default

OpenClaw Example

Register the MCP server in OpenClaw's config file (%USERPROFILE%\.openclaw\openclaw.json):

{
  "mcpServers": {
    "omniclip-rag": {
      "transport": "stdio",
      "command": "D:\\Apps\\OmniClip RAG\\dist\\OmniClipRAG-MCP-v0.4.8\\OmniClipRAG-MCP.exe",
      "args": []
    }
  }
}

Then restart OpenClaw or its gateway process so it reloads the config.

What The AI Can Do Through MCP

V1 intentionally keeps the MCP surface very small and stable:

• omniclip.status: checks whether your local search environment is ready, tells the AI whether it is running in hybrid mode or a degraded lexical_only mode.
• omniclip.search: searches your local knowledge base, returns explicit source labels such as Markdown · xxx.md or PDF · xxx.pdf · Page N.

How To Ask The AI

Once the MCP server is connected, you can simply speak to the AI in natural language. These prompts work well:

• "Use OmniClip to search my local knowledge base for 'project roadmap' and summarize the most useful points."
• "First call omniclip.status, then tell me whether my local knowledge base is ready."
• "Search only PDF results in OmniClip for 'attention mechanism'."
• "Find notes related to 'my thinking model' in OmniClip and show me the most relevant 5 snippets with sources."

Recommended Ongoing Collaboration Prompts

If you want an AI to behave more like it has a built-in RAG habit instead of waiting for you to remind it every time, the following two prompt templates work well.

For AI Clients With MCP Connected

Use this when the AI can call omniclip.search by itself:

From now on, whenever we discuss a topic, please first search my local knowledge base for information relevant to the current question, and then talk to me based on both the search results and my knowledge base as the boundary of what I know, even if I do not always remember that knowledge clearly myself.

Because my knowledge base may contain hundreds of thousands of chunks, please do not over-expand the search beyond what is needed for the current topic.

If you need more of my background later in the conversation, keep using the same pattern: search my local knowledge base first, then continue the discussion based on the relevant results.

For Web AI Without MCP

Use this when you are talking to a normal web AI that cannot call MCP directly and must ask you for search terms:

From now on, whenever we discuss a topic, please first decide what information you need from my local knowledge base, then ask me for the exact keywords or phrases you want me to search. I will manually search with my local RAG tool and send the retrieved snippets back to you.

Because this web chat does not have MCP access, please behave as if you do: ask me for the search terms you need, wait for the retrieved snippets, and then continue the discussion based on both those snippets and my knowledge base as the boundary of what I know, even if I do not always remember that knowledge clearly myself.

Because my knowledge base may contain hundreds of thousands of chunks, please do not over-expand the search beyond what is needed for the current topic.

If you need more of my background later in the conversation, keep using the same pattern.

💡 High-Leverage Mental Models & Workflows

🔥 Click to expand: The Ultimate Mental Models & Prompt Injection

> [!IMPORTANT] > Core Philosophy: Stop thinking of OmniClip RAG as "just another AI software". Instead, treat it as the ultimate "Local Knowledge Router & Context Dispenser" sitting between you and any state-of-the-art AI. The AI is no longer just chatting with you out of thin air; it is reasoning based on your lifetime of accumulated insights.

From an architecture and knowledge-management perspective, we highly recommend the following high-leverage workflows to unlock emergent abilities:

1. Cross-Model Cognitive Arbitrage

Use OmniClip as your "Single Source of Truth (SSOT)". Since the frontend is physically decoupled from any specific AI, you can take a sin

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: msjsc001
• Source: msjsc001/OmniClip-RAG
• License: MIT
• Homepage: https://msjsc001.github.io/OmniClip-RAG/

Install and usage instructions live in the source repository linked above.