• 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.

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.EllisMorrow/omniclip-rag-mcp
• The MCPB keeps its legacy internal package identity so existing installations continue to recognize upgrades after the GitHub account rename.
• If your client supports MCPB installation, prefer the Release asset: omniclip-rag-mcp-win-x64-v0.4.13.mcpb

For the full Registry/MCPB explanation and client-specific setup notes, see MCP_SETUP.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.13\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.13\\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.

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 single highly-dense Context Pack retrieved locally and feed it in parallel to different engines: Have Claude 3.5 Sonnet write core refactoring code based on the snippet, forward the exact same context to O1 for boundary security reviews, and use another model for a localized report. You are leveraging your stable local index to "arbitrage" the strengths of different cloud LLMs, mitigating the blind spots of any single model.

2. Passive Intelligence Hub & Evidence-Layer Isolation

Fully exploit the support for PDF and Tika (1290 formats). Treat your Markdown vault as your "Cognitive Mainchain" (where your judgments and thoughts live), and treat PDFs/DOCXs/EMLs as your "Raw Evidence Silo". Dump unstructured industry reports and reference books into local folders without manually organizing them. When researching, intentionally isolate your queries: search Markdown for "what I thought", and search PDF/Tika for "what the raw evidence says". Over the MCP protocol, you can simply ask an AI: "Search my recent PDF reports on attention mechanisms and cross-reference them with my markdown reflections." Your PC instantly becomes an offline, private intelligence war room.

3. Project Context Compressor & Shadow Brainstorming

For long-running, complex projects containing requirements, deprecated drafts, and meeting notes, never manually dig through folders when you are stuck. Instead, perform fuzzy searches using sentences or conflicting pairs (e.g., Why did we make this architectural decision back then? or Privacy vs Convenience). By abusing the "fuzzy semantic association" of the vector engine, OmniClip might suddenly connect a psychology note you wrote two years ago with your current architecture hurdle, triggering true "Serendipity". It prevents the friction of "re-thinking what you have already thought through".

4. The "Permanent Memory Hippocampus" & Absolute Privacy Firewall

Whenever an AI helps you solve a profound issue or draft an ingenious architecture, immediately summarize it into a clean Markdown file and drop it into your Vault. OmniClip's millisecond hot-reload mechanism instantly pulls it into the LanceDB and FTS5 retrieval pool. Over time, you physically mount a continuously-growing, strictly supervised "past-life memory" onto any AI you use. Your vault stays entirely local. You are only handing the AI the "Minimum Viable Context"—never uploading the gold mine itself. This guarantees absolute data sovereignty and privacy.

🌟 The Golden Rule: Before writing a massive document, making a complex decision, or starting a deep chat with an AI — Search first, chat later. OmniClip's true power isn't doing the thinking for you; it's handing back exactly what you've already thought, read, and accumulated, right when you and your AI need it most.

💬 Appendix: Recommended Prompt for AI (Prompt Injection)

When pasting your retrieved context packs to an AI, you may want the AI to utilize the knowledge effectively without just "summarizing" or "parroting" your notes. We highly recommend including the following guidelines in your System Prompt or initial message to the AI:

- In our conversation, I may sometimes include RAG semantic retrieval snippets (not the full text) related to the topic as background information for our discussion.
	- This information comes from my local RAG retrieval software, which searches all relevant snippets within my local note vault. This allows me to establish a deep, critical connection between you and my knowledge base, without the time and effort of uploading the entire vault, thus maximizing the privacy of my notes while enabling in-depth interaction.
	- The sole purpose of providing these snippets is to synchronize you with my knowledge boundaries and make our conversation deeper and more meaningful.
		- Some of the snippets I provide may be irrelevant; please ignore this noise on your own.
		- Please directly treat these snippets as known premises and converse with me based on them. Absolutely do not summarize, simply agree with, parrot back, or distill this background information.
		- When you find it necessary, or when your reply is inspired by a specific snippet:
			- Please naturally mention the relevant note title and paragraph so I can accurately locate it locally (this also helps me with subsequent additions, deletions, or modifications to my local notes).
	- During your reasoning and our conversation, you can ask me to provide supplemental information at any time if needed.
		- If you need specific support, please explicitly tell me the exact words or phrases to search for. I will use those to retrieve the key snippets and return them to you.
		- If you find that key content is truncated when reviewing a snippet, you can directly ask me to provide the complete note page.

Start the Desktop GUI:

.\scripts\run_gui.ps1

Build the Packaged Windows EXE:

.\scripts\build_exe.ps1

Run the headless MCP self-check from source:

python launcher_mcp.py --mcp-selfcheck

For Automation and Terminal Devs, the native CLI is still on active duty:

.\scripts\run.ps1 status
.\scripts\run.ps1 query "your question"

V0.4.13 Key Updates

v0.4.13 makes Markdown live watch genuinely event-driven and moves each incremental parse, embedding, and CUDA workload into a disposable child process.

• ⚡ Idle watch no longer rescans every vault: after startup reconciliation, watchdog responds only to real filesystem changes.
• ⏱️ Users can set the quiet period after editing: the 10-second default merges repeated saves into one incremental update.
• 🧹 Large resources are released after every batch: parsing, embedding, and vector writes finish in a disposable process so Windows can reclaim Commit, RAM, and VRAM.
• 🧵 Watched vaults do not load duplicate models concurrently: semantic update batches are serialized to reduce GPU and Windows Commit peaks.
• 🚫 Generated Logseq history and recovery trees are ignored: .stversions, backups, recycle trees, and conflict-trash files no longer trigger pointless updates.

V0.4.12 Key Updates

v0.4.12 replaces the universal Reranker memory floor with a model-aware live resource estimate and makes query progress visible directly beside the Search action.

• 🧠 Auto now evaluates the workload instead of a universal 10 GiB floor: the Reranker decision uses the local model weight, batch settings, Windows Commit headroom, available physical memory, and free CUDA memory.
• 🎯 The compact query-state button now names the active stage: preparing, lexical recall, semantic recall, fusion, reranking, result finalization, context packing, and fallback stages are visible with progress.
• 🧭 Query failures remain visible: a failed query no longer falls back to showing the previous completed state.
• 📐 Numeric query controls stay attached to their labels: score threshold and result-limit fields no longer drift away from their explanatory text on wide windows.
• 🧹 Disposable query children are explicitly reaped: normal completion, cancellation, and failure paths wait for process termination instead of leaving query workers behind.
• 🛑 Multi-vault live watch stops reliably: global stop covers every actual watcher, each vault shows a non-repeatable stopping state, and scans plus incremental vector writes honor safe cooperative cancellation.
• 🧵 PDF/Tika directory actions stay responsive: completion-time state reloads and indexed-source summaries run through a coalesced background refresh, and stale results cannot overwrite newer directory settings.

V0.4.11 Key Updates

v0.4.11 keeps CUDA semantic recall available under Windows commit pressure while preventing native PyTorch crashes during Reranker loading and teardown.

• 🧠 CUDA semantic recall remains available in Auto mode: low Windows commit headroom skips only the optional Reranker stage instead of disabling vector retrieval or losing the full query.
• 🛟 Native query failures now retain a semantic recovery path: a fresh CPU semantic process without reranking is attempted before the final lexical-only fallback.
• 🧹 Query-worker shutdown no longer migrates large CUDA models back to CPU: disposable workers let Windows reclaim their resources after the result is safely written.
• 🧭 The Query Console now tells users exactly what to do: close memory-heavy applications, keep Auto selected, enable automatic Windows paging-file management or increase the paging file, and restart if needed; Runtime or model reinstallation is not required for this condition.

V0.4.10 Key Updates

v0.4.10 is a candidate stability release that keeps Runtime detection and semantic-model failures away from the interactive desktop process.

• 🛑 Queries stay disabled while startup Runtime detection is active: both buttons and the execution guard remain blocked until the detection result is available.
• 🔄 Safe startup no longer leaves a stale repair warning: the isolated status-only Runtime probe still runs in safe mode, and its exact result is applied to the Start and Runtime pages.
• 🧱 Semantic queries now run in a disposable child process: native PyTorch, SentenceTransformer, or CrossEncoder access violations can no longer terminate the main Qt interface.
• 🛟 A crashed semantic query gets one clean lexical recovery attempt: the UI stays alive and can still return useful results with a visible degradation warning.
• 🧠 Multi-vault model reuse remains bounded to one query process: selected vaults share the same embedding/reranker resources during a query, and the operating system reclaims them when the child exits.

V0.4.9 Key Updates

v0.4.9 completes the startup-responsiveness work with an isolated Runtime probe, truthful detecting states, staggered background refreshes, and a new high-contrast flat application icon.

• ⚡ Runtime detection starts automatically after first paint: the Start and Runtime pages immediately show a detecting state and update themselves without requiring a manual refresh.
• 🧵 Heavy startup work is isolated from the GUI process: Runtime validation and the initial workspace snapshot run in disposable child processes, while Markdown, extension, and Tika refreshes start in a controlled sequence.
• 🪶 First paint avoids unnecessary parser and ML initialization: the full Tika format catalog is parsed only when the format picker is opened, and lightweight status paths no longer probe vector dependencies.
• 🧭 Status labels are more truthful: an installed but not-yet-verified Runtime is no longer reported as missing, while enabled PDF/Tika sources distinguish unbuilt state from pending verification.
• ✨ The application icon is now a simpler flat mark: the new balanced ring-and-spark design remains recognizable at Windows thumbnail sizes.

V0.4.8 Key Updates

v0.4.8 is the startup responsiveness and extension-source removal release: packaged GUI startup now yields the first window before heavyweight Runtime-management and extension-summary refresh work finishes, while 拓展格式 > PDF / Tika source rows now have a true remove action that clears matching extension index/state data and then removes the source directory from extension settings without ever touching the user's original files.

• 🚀 Packaged startup is much less likely to freeze on first paint: heavyweight Runtime-management refreshes and extension-source summary rebuilds now move behind the initial window draw instead of blocking the GUI thread before the shell becomes visible.
• 🧭 PDF/Tika source rows finally have a real remove flow: the danger action no longer stops at “clear index”; it now removes the source directory from the extension registry/UI after cleaning its matching extension index/state data.
• 🧹 Extension-side cleanup is now complete but still safe: removing a PDF/Tika source clears local extension state and index traces for that source, while still never deleting the original external folder.
• 🛑 Cancelled delete tasks keep their source directories intact: the UI no longer risks dropping a source directory from extension settings when the underlying delete task did not actually complete.
• 🧪 The local release line is internally consistent again: package metadata, setup examples, release notes, and MCP-facing paths now all line up on the v0.4.8 version line.

V0.4.6 Key Updates

v0.4.6 is the UI cognition and navigation polish release: the Start page now speaks in the clearer Primary / Included scope mental model for Markdown source directories, the configuration tabs follow the real product workflow order, and the desktop shell gains a unified theme-aware hover-help layer that can be globally turned on or off.

• 🧱 Extension build control is materially stronger now: PDF/Tika build tasks gained a dedicated control layer for truthful progress payloads, interruption awareness, conservative resume contracts, and explicit READY / query_ready / vector_ready state truth.
• 📄 PDF preflight is lighter and faster without losing exact page counts: single-file PDF preflight now reads metadata/page structure instead of drifting into partial text extraction, so it no longer feels like a hidden mini-build.
• 👀 Slow extension work is much easier to read from the UI: preflight/build tasks now expose real file-level progress, current file labels, busy-bar fallback, and elapsed-time feedback when a single file or slow parser would otherwise look frozen.
• 📦 Frozen EXE PDF preflight is hardened again: packaged builds no longer misdiagnose a healthy PDF parser as unavailable just because pypdf metadata was missing from the frozen environment.
• 🧹 Release-facing docs are cleaner again: local development absolute paths were replaced with neutral example install paths before this public release.

V0.4.3 Key Updates

v0.4.3 is the release that turns the recent hotfix line into a cleaner public release: semantic retrieval now tells the truth, download flows finally follow the active environment end to end, and the MCP/packaging line is again fully reproducible from the repository itself.

• 🧠 Semantic retrieval is now honest instead of silently misleading: if vector_backend is disabled or semantic vectors have not been rebuilt yet, the desktop app and MCP payloads now say so explicitly instead of pretending full hybrid search is active.
• 📁 Model / reranker download targets now strictly follow the active data root: Runtime repair, embedding-model download, reranker download, delete-model actions, logs, and cache all stay inside the currently active environment root.
• 🌏 China-first automatic download is much more resilient: the automatic chain now prefers ModelScope -> HF mirror -> Hugging Face official, exposes live terminal output and heartbeat logs, and keeps download failures visible instead of looking frozen.
• 🧭 Index-state messaging is now much more actionable: the overview chips distinguish “index ready but lexical-only” from “semantic backend enabled but vector table still missing”, so users know when a rebuild is still required.
• 🛠 The formal release chain is restored inside the repo: OmniClipRAG-MCP.spec is now back in-tree, so build.py can rebuild the GUI ZIP, MCP ZIP, and .mcpb bundle from one version source of truth.

V0.4.2 Key Updates

v0.4.2 is the release that turns OmniClip's recent internal convergence work into a publishable product line: data-root truth is now unified, GUI recovery can repair broken environments without silent fallback, and the desktop shell is cleaner to operate day to day.

• 🗂 Data root is now treated as the active environment root: config, logs, cache, models, main Runtime, Tika Runtime, and workspaces now follow the same active data root contract instead of letting GUI, Runtime, and launcher guess separately.
• 🚧 Broken data roots now enter a recovery shell instead of trapping users outside the app: when the active environment is unavailable, the GUI starts in a restricted recovery mode, explains the problem in plain language, and lets the user retry or switch to another saved environment.
• 🔁 Saved data-root switching is now a real environment switcher: the GUI can keep multiple saved roots, forget invalid ones from the list, and switch whole environments through a controlled restart instead of partial hot state drift.
• 🧰 Desktop polish landed on top of the architecture work: the query desk can collapse into a compact one-line form, classic UI themes were added, and the app icon chain was unified so runtime assets and packaged Windows builds stop drifting apart.
• 🌐 The documentation surface now includes a public website: the GitHub Pages site is live at msjsc001.github.io/OmniClip-RAG, and the top-level docs now point to it directly.

V0.4.1 Key Updates

v0.4.1 turned the new MCP line from "a working second shell" into "a Registry-ready delivery line" so OmniClip could be published through the official MCP Registry instead of living only as a raw manual ZIP.

• 🚀 Official Registry route is now the primary discovery strategy: the project now ships a formal server.json metadata file for MCP Registry publishing instead of targeting the deprecated modelcontextprotocol/servers README list.
• 📦 A standard MCPB package is now part of the release story: omniclip-rag-mcp-win-x64-v0.4.1.mcpb becomes the Registry/MCPB-aware distribution asset, while the old ZIP remains for manual users.
• 🧭 README and MCP docs are now split for strangers, not just existing users: the English README now exposes a first-screen MCP quickstart, the Chinese README keeps its original voice with a lighter MCP entry point, and MCP_SETUP.md now explains ZIP vs .mcpb explicitly.
• 🛠 The first Registry publish path is intentionally manual: 0.4.1 is reserved as the first clean MCP Registry version so hash, metadata, and release assets can be verified before later automation.

V0.4.0 Key Updates

v0.4.0 introduced the first dedicated read-only MCP shell on top of the existing retrieval core, turning OmniClip from a desktop-only app into a standard MCP-capable local search engine.

(See Releases page for historical version update notes from V0.1.0 to the present).