{"slug": "show-hn-local-search-agent-offline-rag-no-embeddings-free-tier", "title": "Show HN: Local Search Agent – offline RAG, no embeddings, free tier", "summary": "Local Search Agent, a new Python framework, enables AI agents to search, fetch, and reason over local documents using BM25 keyword search via Meilisearch, avoiding cloud uploads, embeddings, and vector databases. The open-source tool offers a free tier with Google AI Studio or fully local setup via Ollama, addressing issues like stale indexes and black-box retrieval in traditional RAG systems.", "body_md": "**Give your AI agent a search engine for your local files.**\n\nLocal Search Agent is a Python framework that gives your AI agent a search engine for your local files and lets it search, fetch, and reason over your local documents — the same way a researcher searches the web, but entirely on your machine.\n\nPoint it at a folder. Ask a question. The agent searches your documents, reads the relevant ones, and gives you an answer with citations — no cloud upload, no API calls to external search services, no embeddings, no vector stores.\n\n```\n\"What was the AWS spend in Q3?\"  →  agent searches index  →  fetches relevant docs  →  answers with sources\n```\n\nTraditional RAG (Retrieval-Augmented-Generation) has a fundamental problem: it converts your documents into embeddings and stores them in a vector database. That means:\n\n**Stale indexes**— embeddings go out of date silently. You never know if the agent is reading your latest documents or a six-month-old snapshot**Black-box retrieval**— you can't see why a document was retrieved or not. Debugging poor answers is guesswork** Chunking anxiety**— split too small and you lose context. Split too large and retrieval quality degrades. There's no right answer** Infrastructure overhead**— a vector database is another service to run, maintain, and pay for** Semantic drift**— embeddings are sensitive to how questions are phrased. A question about \"cloud expenditure\" may never match a document that says \"AWS spend\"\n\nLocal Search Agent takes a different approach: **BM25 keyword search via Meilisearch, structured metadata, and a LangGraph agent loop with tools**. The agent searches your document index the same way a developer searches Stack Overflow — with real queries, real results, and full transparency into what was retrieved and why.\n\nThe result is deterministic, auditable, and fast. You can see exactly what the agent fetched for every answer.\n\n```\n1. INGEST     Your documents → parsed, cleaned, chunked, indexed into Meilisearch\n2. SERVE      FastAPI file server makes documents available to the agent via HTTP\n3. SEARCH     LangGraph agent loop: search_local_index → fetch_local_url → reason\n4. ANSWER     Agent returns an answer with inline source citations\n```\n\nEverything runs locally. Meilisearch downloads automatically on first use, no manual setup.\n\n**0.3.0 Release**— Watch the[Role-based Access Control](https://youtu.be/Wjx1Bc0D9uM)** 0.2.1 Release**— Watch the[Zooming + Exporting conversation](https://youtu.be/TpYN-ytgmXk)** 0.2.0 Release**— Watch the[Reranker + Watch mode](https://youtu.be/6zqhHxmEkBY)** Native UI**— Watch the[UI design and configuration video demo](https://youtu.be/J-POiSDbArs)** CLI AGENT**— Watch the[Terminal document querying video demo](https://youtu.be/ZIiN4NG5g3U)** Python API**— Watch the[Local Search Agent API Integration video demo](https://youtu.be/JfoLKScLi1Y)\n\n```\npip install local-search-agent\n# Google AI Studio (free tier — recommended) or paid from openai or anthropic\nlocal-search config set-key --provider google --key YOUR_KEY\n\n# Or use Ollama for a fully local, zero-cost setup (no key needed)\n# Install from https://ollama.com \n# Download any model that support function calling and system instructions: \n`ollama pull gemma4:e2b` (7.2GB) \n`ollama pull gemma4:e4b` (9.6GB) \n`ollama pull nemotron-3-nano:4b` (2.8GB Highly recommended)\nlocal-search ui\n```\n\nThe desktop UI open:\n\n- Create a workspace, name it, point it at a directory of files. The \"Database path\" field is optional — leave it blank to use the default location shown in the hint, or paste a custom path and click \"Set & Restart\".\n- Ingest (parse, clean, chunk).\n- Get a free google api key from ai-studio.\n- Set your api key at the top bar's right corner, or add a paid key for anthropic\\openai . Note: For paid models or ollama, you will need to set model name via the config button at the top bar's right corner.\n- click Ingest from the left sidebar.\n- watch the progress bar at the bottom bar, wait until all files marked as completed.\n- Start asking questions.\n\n```\n# Create a workspace and ingest documents\nlocal-search workspace create finance \"C:\\my_docs\"\nlocal-search ingest --workspace finance --dirs \"C:\\my_docs\"\n\n# Start the file server (keep this running)\nlocal-search serve --workspace finance\n\n# Ask a question\nlocal-search query \"What was the AWS spend in Q3?\" --workspace finance --provider google\n\n# Use interactive mode\nlocal-search query --workspace finance --provider google\npython\nfrom local_search_agent import SearchAgentFramework, SearchAgentConfig\n\nconfig = SearchAgentConfig(\n    document_dirs=[\"C:/my_docs\"],\n    workspace_name=\"finance\",\n    provider=\"google\",\n    # db_path defaults to your OS user config dir — same location as keys.json\n    # override only if you need a custom location:\n    # db_path=\"D:/mydata/search.db\",\n)\n\nframework = SearchAgentFramework(config)\nframework.ingest_and_index()\nframework.start_file_server()\n\nresponse = framework.query(\"What was the AWS spend in Q3?\")\nprint(response[\"answer\"])\n```\n\nWrap an indexed workspace as a tool and plug it into any external AI agent — LangChain, LangGraph, Google Gemini SDK, or any framework that calls a function.\n\n``` python\nfrom local_search_agent import SearchAgentFramework, SearchAgentConfig, LocalSearchTool\n\nconfig = SearchAgentConfig(\n    document_dirs=[\"C:/skills\"],\n    workspace_name=\"skills\",\n    provider=\"google\",\n    model_name=\"gemini-3.1-flash-lite\",  # cheap model for retrieval\n)\n\n# Index once\nframework = SearchAgentFramework(config)\nframework.ingest_and_index()\nframework.start_file_server()\n\n# Create the tool\nskill_tool = LocalSearchTool(config)\n\n# Use inside a LangChain / LangGraph agent\nfrom langchain_core.tools import tool\n\n@tool\ndef search_skills(query: str) -> str:\n    \"\"\"Search the skills knowledge base for coding patterns and techniques.\"\"\"\n    return skill_tool.run(query).answer\n```\n\nPass `return_raw=True`\n\nto bypass the internal LLM summarisation and return the full document text verbatim — useful when the calling agent should reason over the raw content itself:\n\n```\nskill_tool = LocalSearchTool(config, return_raw=True)\n```\n\nSee the [Python API Reference](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/api-reference.md#localsearchtool) for the full `LocalSearchTool`\n\ndocumentation.\n\nRunning this for more than just yourself? Turn one shared deployment into\na proper multi-user server with role-based access control — three roles\n(`superadmin`\n\n/ `admin`\n\n/ `member`\n\n), `admin`\n\n/`member`\n\ngranted per subject\nper workspace, `superadmin`\n\nunconditional across the whole deployment,\nenforced on every protected route. Also includes optional per-role\nmodel/provider cost controls and concurrency/rate-limit management for\ncloud LLM accounts or shared Ollama hardware.\n\nThree pluggable identity providers cover the common setups out of the\nbox: a **header provider** for when you already have an authenticating\nreverse proxy in front, an **API-key provider** (with browser sessions)\nfor when you don't have existing auth infrastructure, and a **JWT\nprovider** that validates against your company's own IdP (Auth0, Okta,\nAzure AD, Google Workspace) when employees already sign in via SSO.\n\n```\n# Bootstrap: create a workspace, a superadmin key, an admin's key, and grant admin access\nlocal-search workspace create finance \"/srv/docs/finance\"\nlocal-search auth create-key --subject root@acme.com --display-name \"IT/Ops\" --superadmin\nlocal-search auth create-key --subject alice@acme.com --display-name \"Alice\" --created-by root@acme.com\nlocal-search grant-access --subject alice@acme.com --workspace finance --role admin\n\n# Run the dashboard with RBAC turned on\nlocal-search ui --multi-tenant --db /var/lib/local-search-agent/prod.db\n```\n\nThis is entirely opt-in — set `identity_provider`\n\non `SearchAgentConfig`\n\n(or pass `--multi-tenant`\n\nto `local-search ui`\n\n) to turn it on; every\nexisting single-user workflow above works exactly as written if you never\ndo. See [Role-Based Access Control](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/role_based_access_control.md)\nfor the full guide, and [Production Deployment](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/production-deployment.md)\nfor running this as a shared server (Docker, systemd, reverse proxy) —\nnote that Dockerfile/systemd/Caddy files live at the repo root, not in\nthe PyPI package itself, so self-hosters should either clone this repo or\ncopy the file contents straight out of that doc.\n\nBy default, scanned or image-based PDFs are processed using RapidOCR. Installing Tesseract enables a faster OCR path (~5 second per page vs. minutes without it).\n\nDigitally-created PDFs (with a text layer) are never affected — they use direct text extraction and skip OCR entirely.\n\n**Windows**\n\nDownload and run the installer from [https://github.com/UB-Mannheim/tesseract/wiki](https://github.com/UB-Mannheim/tesseract/wiki)\n\nMake sure **\"Add Tesseract to the system PATH\"** is checked during installation.\n\n**Linux**\n\n```\nsudo apt install tesseract-ocr        # Ubuntu / Debian\nsudo dnf install tesseract             # Fedora / RHEL\nsudo pacman -S tesseract               # Arch\n```\n\n**macOS**\n\n```\nbrew install tesseract\n```\n\nAfter installation, restart the application — Tesseract is detected automatically. If it's not found, ingestion continues normally using RapidOCR with no errors.\n\n| Format | Extension |\n|---|---|\n`.pdf` |\n|\n| Word | `.docx` |\n| Excel | `.xlsx` |\n| PowerPoint | `.pptx` |\n| HTML | `.html` , `.htm` |\n| Plain text | `.txt` , `.md` |\n| CSV | `.csv` |\n| JSON | `.json` |\n| XML | `.xml` |\n`.eml` |\n\n**One command install**—`pip install local-search-agent`\n\n. Meilisearch downloads automatically**No embeddings, no vector stores**— BM25 search with structured metadata. Fast, deterministic, auditable** Native desktop UI**— pywebview window with live streaming agent responses, workspace management, and chat history** Multi-provider LLM**— Google, Ollama (local), OpenAI, Anthropic** Multi-workspace**— isolate document collections by department, project, channel, or topic. Each workspace is its own search index** Incremental sync**— background scheduler re-indexes only changed files. A 10,000-document corpus with 50 changes re-indexes only the 50** Multi-tenant RBAC**— opt-in three-role access control (`superadmin`\n\n/`admin`\n\n/`member`\n\n) per workspace, with pluggable identity (header, API key, or JWT/SSO), plus optional per-role model/provider cost controls and concurrency/rate-limit management, for running one shared deployment across a team**Full CLI parity**— everything you can do in the UI you can do from the terminal** Python API**— embed the framework directly in your own application** Cross-platform**— Windows, macOS, Linux\n\n| Guide | Description |\n|---|---|\n|\n\n[Installation](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/installation.md)[Architecture](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/architecture.md)[CLI Reference](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/cli-reference.md)[Python API Reference](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/api-reference.md)[Configuration](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/configuration.md)[Ingestion](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/ingestion.md)[Multi-Workspace](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/multi-workspace.md)[Role-Based Access Control](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/role_based_access_control.md)[Production Deployment](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/production-deployment.md)[Semantic Search](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/semantic-search.md)[Troubleshooting](https://github.com/wiss84/local-search-agent/blob/main/local_search_agent/docs/troubleshooting.md)Contributions are welcome. Clone the repo and install in editable mode with dev dependencies:\n\n```\ngit clone https://github.com/wiss84/local-search-agent.git\ncd local-search-agent\npip install -e \".[dev]\"\n```\n\nRun tests before submitting a PR:\n\n```\npytest tests/ -v --cov=local_search_agent --cov-report=term-missing\nruff check .\nruff format .\n```\n\nMIT — see [LICENSE](https://github.com/wiss84/local-search-agent/blob/main/LICENSE) for details.\n\nBuilt by [Wissam Metawee](https://github.com/wiss84)", "url": "https://wpnews.pro/news/show-hn-local-search-agent-offline-rag-no-embeddings-free-tier", "canonical_source": "https://github.com/wiss84/local-search-agent", "published_at": "2026-07-13 18:49:07+00:00", "updated_at": "2026-07-13 19:05:21.899447+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "developer-tools", "artificial-intelligence"], "entities": ["Local Search Agent", "Meilisearch", "LangGraph", "Google AI Studio", "Ollama", "Anthropic", "OpenAI"], "alternates": {"html": "https://wpnews.pro/news/show-hn-local-search-agent-offline-rag-no-embeddings-free-tier", "markdown": "https://wpnews.pro/news/show-hn-local-search-agent-offline-rag-no-embeddings-free-tier.md", "text": "https://wpnews.pro/news/show-hn-local-search-agent-offline-rag-no-embeddings-free-tier.txt", "jsonld": "https://wpnews.pro/news/show-hn-local-search-agent-offline-rag-no-embeddings-free-tier.jsonld"}}