hermes-scout 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,27 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-11-22
10
+
11
+ ### Added
12
+
13
+ - `semantic_search` tool: search a folder of local text files by meaning.
14
+ - Line-aligned, overlapping chunking with a configurable chunk size.
15
+ - Embeddings from any OpenAI-compatible `/embeddings` endpoint, local Ollama by default.
16
+ - Incremental SQLite index in the plugin's data folder, keyed by folder and embedding model.
17
+ - Cosine-similarity ranking with file path, line range and score in every result.
18
+ - Settings form (`base_url`, `embedding_model`, `api_key`, `top_k`, `chunk_chars`, `max_files`,
19
+ `max_file_kb`).
20
+ - Skips hidden, dependency, binary and oversized files and every path Hermes's file tools refuse.
21
+ - `hermes-scout` command line tool (`search` and `index`), installable from PyPI.
22
+ - Documentation site built with MkDocs Material.
23
+ - Tests for the engine, the HTTP client, the command line and the Hermes wiring (34 tests, over 90%
24
+ coverage), run in CI on Python 3.11 to 3.14 with ruff lint and CodeQL analysis.
25
+
26
+ [Unreleased]: https://github.com/Shizoqua/hermes-scout/compare/v0.1.0...HEAD
27
+ [0.1.0]: https://github.com/Shizoqua/hermes-scout/releases/tag/v0.1.0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lanre Shittu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,327 @@
1
+ Metadata-Version: 2.4
2
+ Name: hermes-scout
3
+ Version: 0.1.0
4
+ Summary: Search local files by meaning with embeddings from any OpenAI-compatible server. A Hermes Agent plugin and a standalone CLI.
5
+ Keywords: semantic search,embeddings,retrieval,rag,ollama,hermes-agent,cli
6
+ Author: Lanre Shittu
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ License-Expression: MIT
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Classifier: Topic :: Text Processing :: Indexing
21
+ License-File: LICENSE
22
+ Project-URL: Changelog, https://github.com/Shizoqua/hermes-scout/blob/main/CHANGELOG.md
23
+ Project-URL: Documentation, https://shizoqua.github.io/hermes-scout/
24
+ Project-URL: Homepage, https://github.com/Shizoqua/hermes-scout
25
+ Project-URL: Issues, https://github.com/Shizoqua/hermes-scout/issues
26
+
27
+ <div align="center">
28
+
29
+ # hermes-scout
30
+
31
+ **Search your local files by meaning, not just keywords.**<br>
32
+ A [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin and a standalone command line tool.
33
+
34
+ ![hermes-scout: find anything in your files by meaning](docs/banner.png)
35
+
36
+ [![PyPI](https://img.shields.io/pypi/v/hermes-scout?label=pypi&color=7c5cff&logo=pypi&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://pypi.org/project/hermes-scout/)
37
+ [![Downloads](https://img.shields.io/pepy/dt/hermes-scout?label=downloads&color=ec4899&logo=python&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://pepy.tech/project/hermes-scout)
38
+ [![tests](https://img.shields.io/github/actions/workflow/status/Shizoqua/hermes-scout/tests.yml?branch=main&label=tests&logo=githubactions&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://github.com/Shizoqua/hermes-scout/actions/workflows/tests.yml)
39
+ [![docs](https://img.shields.io/github/actions/workflow/status/Shizoqua/hermes-scout/docs.yml?branch=main&label=docs&logo=materialformkdocs&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://shizoqua.github.io/hermes-scout/)
40
+ <br>
41
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3b82f6?logo=python&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://www.python.org/)
42
+ [![Hermes Agent plugin](https://img.shields.io/badge/Hermes%20Agent-plugin-a855f7?labelColor=1e1b2e&style=flat-square)](https://github.com/NousResearch/hermes-agent)
43
+ [![Zero dependencies](https://img.shields.io/badge/dependencies-zero-14b8a6?labelColor=1e1b2e&style=flat-square)](#development)
44
+ [![License: MIT](https://img.shields.io/badge/license-MIT-f59e0b?labelColor=1e1b2e&style=flat-square)](LICENSE)
45
+
46
+ [**Documentation**](https://shizoqua.github.io/hermes-scout/) ·
47
+ [**Getting started**](https://shizoqua.github.io/hermes-scout/getting-started/) ·
48
+ [**Changelog**](CHANGELOG.md) ·
49
+ [**Report a bug**](https://github.com/Shizoqua/hermes-scout/issues/new/choose)
50
+
51
+ </div>
52
+
53
+ ---
54
+
55
+ Ask *"where do we handle rate limits?"* and get back the relevant paragraphs from your notes, docs
56
+ or code, even when they never use the words "rate limit". Results come with file paths, line
57
+ numbers and a similarity score.
58
+
59
+ hermes-scout works two ways:
60
+
61
+ - **As a Hermes Agent plugin**, adding a `semantic_search` tool the agent can call.
62
+ - **As a standalone command**, `hermes-scout search "..." ~/notes`, for anyone with Python.
63
+
64
+ Embeddings come from any OpenAI-compatible `/embeddings` endpoint. By default that is a local
65
+ [Ollama](https://ollama.com) server, so your files never leave your machine and searches cost nothing.
66
+
67
+ ![Demo: asking Hermes where rate limits are handled, and the ranked passages semantic_search returns](docs/demo.gif)
68
+
69
+ ## Contents
70
+
71
+ - [Why](#why)
72
+ - [Features](#features)
73
+ - [Quick start](#quick-start)
74
+ - [Command line](#command-line)
75
+ - [Example](#example)
76
+ - [How it works](#how-it-works)
77
+ - [Supported embedding servers](#supported-embedding-servers)
78
+ - [Settings](#settings)
79
+ - [Troubleshooting](#troubleshooting)
80
+ - [Disclosure](#disclosure)
81
+ - [Roadmap](#roadmap)
82
+ - [Development](#development)
83
+ - [Contributing](#contributing)
84
+ - [License](#license)
85
+
86
+ ## Why
87
+
88
+ Keyword search only finds the words you remember. Notes say "back off and retry", code says
89
+ `except HTTPError as err: if err.code == 429`, and docs say "throttling". You remember none of
90
+ those phrasings. Semantic search compares *meaning*: the query and every passage are turned into
91
+ embedding vectors, and the passages pointing in the most similar direction come back first.
92
+
93
+ ## Features
94
+
95
+ - **Search by meaning** across notes, docs and source code in any folder.
96
+ - **Local-first.** Works out of the box with Ollama, LM Studio, llama.cpp or vLLM on your own machine.
97
+ - **Fast repeat searches.** An incremental index re-embeds only files that changed since the last search.
98
+ - **Safe by default.** Skips hidden files, dependency folders, binaries and every path Hermes's own
99
+ file tools refuse to read, such as `.env` files and credential stores.
100
+ - **Zero dependencies.** Python standard library only: nothing extra to install or audit.
101
+ - **Precise results.** Every hit names the file, the line range and a cosine similarity score.
102
+ - **Two ways to use it:** as a Hermes tool or as a `hermes-scout` command in any terminal.
103
+ - **Configurable** from the Hermes Desktop settings page or `hermes plugins config hermes-scout`.
104
+
105
+ ## Quick start
106
+
107
+ 1. **Start a local embeddings server** (Ollama shown; see [other servers](#supported-embedding-servers)):
108
+
109
+ ```bash
110
+ ollama pull nomic-embed-text
111
+ ollama serve # if it is not already running
112
+ ```
113
+
114
+ 2. **Install hermes-scout** in Hermes:
115
+
116
+ ```bash
117
+ hermes plugins install hermes-scout
118
+ hermes plugins enable hermes-scout
119
+ ```
120
+
121
+ or as a command line tool:
122
+
123
+ ```bash
124
+ pipx install hermes-scout # or: pip install hermes-scout
125
+ ```
126
+
127
+ 3. **Search.** Ask Hermes:
128
+
129
+ > Search my notes in ~/notes for how I set up backups.
130
+
131
+ or run:
132
+
133
+ ```bash
134
+ hermes-scout search "how I set up backups" ~/notes
135
+ ```
136
+
137
+ The first search of a folder builds its index. Later searches only re-read files that changed.
138
+
139
+ ## Command line
140
+
141
+ ```console
142
+ $ hermes-scout search "how does the client handle rate limiting" ~/project
143
+ 0.59 notes/retries.md:1-3
144
+ Retry policy
145
+ 0.18 notes/pasta.md:1-3
146
+ Dinner
147
+ ```
148
+
149
+ | Command | What it does |
150
+ |---|---|
151
+ | `hermes-scout search QUERY [PATH]` | Search a folder (default: the current one). `-k 10` for more results, `--json` for scripts. |
152
+ | `hermes-scout index [PATH]` | Build or refresh the index ahead of time. |
153
+ | `hermes-scout --version` | Print the version. |
154
+
155
+ Point it at another server with `--base-url` and `--model`, or the `SCOUT_BASE_URL` and
156
+ `SCOUT_MODEL` environment variables. Hosted endpoints read their key from `SCOUT_API_KEY`. The
157
+ index lives in your user cache folder (`~/.cache/hermes-scout/index.db` on Linux). Full reference:
158
+ [Command line docs](https://shizoqua.github.io/hermes-scout/cli/).
159
+
160
+ ## Example
161
+
162
+ A search across a small project. The model receives this from the tool:
163
+
164
+ ```json
165
+ {
166
+ "query": "how does the client handle rate limiting and retries",
167
+ "root": "/home/me/project",
168
+ "model": "nomic-embed-text",
169
+ "results": [
170
+ {
171
+ "path": "notes/retries.md",
172
+ "lines": "1-3",
173
+ "score": 0.5948,
174
+ "text": "Retry policy\n\nWhen the API answers 429 the client waits with exponential backoff and jitter, then retries up to five times."
175
+ },
176
+ {
177
+ "path": "notes/pasta.md",
178
+ "lines": "1-3",
179
+ "score": 0.1849,
180
+ "text": "Dinner\n\nBoil pasta in salted water, add garlic and olive oil."
181
+ }
182
+ ],
183
+ "index": {"indexed_files": 0, "reused_files": 2, "removed_files": 0, "chunks": 2}
184
+ }
185
+ ```
186
+
187
+ The relevant note scores far above the unrelated one, and `"indexed_files": 0` shows that the
188
+ second search reused the index instead of embedding the folder again.
189
+
190
+ ## How it works
191
+
192
+ ```mermaid
193
+ flowchart LR
194
+ A[Folder of text files] --> B[Split into overlapping<br/>line-aligned chunks]
195
+ B --> C{New or changed<br/>since last search?}
196
+ C -- yes --> D[Embed via<br/>/embeddings endpoint]
197
+ C -- no --> E[(SQLite index)]
198
+ D --> E
199
+ Q[Your question] --> F[Embed the question]
200
+ E --> G[Rank chunks by<br/>cosine similarity]
201
+ F --> G
202
+ G --> R[Top passages with<br/>path, lines, score]
203
+ ```
204
+
205
+ 1. **Chunking.** Text files are split into chunks of whole lines (1,200 characters by default).
206
+ Neighbouring chunks share two lines, so a passage that straddles a boundary is still found whole.
207
+ 2. **Embedding.** Chunks are sent to the embeddings endpoint in batches of 32 and stored as float32
208
+ vectors with their precomputed norms.
209
+ 3. **Incremental index.** The index lives in SQLite in the plugin's own data folder
210
+ (`<hermes home>/plugin-data/hermes-scout/index.db`), keyed by folder and embedding model. Only
211
+ new or changed files (by modification time and size) are re-embedded, and deleted files are dropped.
212
+ 4. **Ranking.** The question is embedded the same way and chunks are ranked by cosine similarity:
213
+ `score = (q · c) / (‖q‖ ‖c‖)`.
214
+
215
+ Indexes for different embedding models are kept apart, so switching models never mixes vectors.
216
+
217
+ **What gets indexed:** common text, documentation, code and config extensions (`.md`, `.txt`, `.py`,
218
+ `.ts`, `.go`, `.rs`, `.json`, `.yaml`, ...). **Skipped:** hidden files and folders, dependency and
219
+ build folders (`node_modules`, `venv`, `dist`, `build`, ...), symlinks, binary files, files over the
220
+ size limit, and every path Hermes's file tools refuse to read.
221
+
222
+ ## Supported embedding servers
223
+
224
+ Any server that implements the OpenAI `POST /embeddings` API works. Set `base_url` to its `/v1` root.
225
+
226
+ | Server | `base_url` | Example `embedding_model` |
227
+ |---|---|---|
228
+ | [Ollama](https://ollama.com) (default) | `http://localhost:11434/v1` | `nomic-embed-text`, `mxbai-embed-large` |
229
+ | [LM Studio](https://lmstudio.ai) | `http://localhost:1234/v1` | the embedding model you loaded |
230
+ | [llama.cpp server](https://github.com/ggml-org/llama.cpp) (`--embeddings`) | `http://localhost:8080/v1` | the loaded model's name |
231
+ | [vLLM](https://github.com/vllm-project/vllm) | `http://localhost:8000/v1` | e.g. `BAAI/bge-m3` |
232
+ | Hosted OpenAI-compatible APIs | the provider's `/v1` URL | the provider's embedding model (set `api_key`) |
233
+
234
+ ## Settings
235
+
236
+ In Hermes, edit them in the Desktop app (**Settings → Plugins → hermes-scout**) or with
237
+ `hermes plugins config hermes-scout`. The command line takes the same settings as flags
238
+ (`--base-url`, `--model`, `--chunk-chars`, `--max-files`, `--max-file-kb`, `-k`).
239
+
240
+ | Setting | Default | Meaning |
241
+ |---|---|---|
242
+ | `base_url` | `http://localhost:11434/v1` | OpenAI-compatible base URL; the plugin calls `<base_url>/embeddings` |
243
+ | `embedding_model` | `nomic-embed-text` | Model name the endpoint serves |
244
+ | `api_key` | not set | Only for hosted endpoints; stored by Hermes as `SCOUT_API_KEY` |
245
+ | `top_k` | `5` | Passages returned per search (the model may ask for 1 to 20) |
246
+ | `chunk_chars` | `1200` | Chunk size in characters; applies to files indexed afterwards |
247
+ | `max_files` | `2000` | Files indexed per folder |
248
+ | `max_file_kb` | `1000` | Larger files are skipped |
249
+
250
+ ## Troubleshooting
251
+
252
+ | Message | Fix |
253
+ |---|---|
254
+ | `cannot reach the embeddings server at http://localhost:11434/v1` | Start Ollama (`ollama serve`) or point `base_url` at your server. |
255
+ | `answered HTTP 404 ... model not found` | Pull the model (`ollama pull nomic-embed-text`) or set `embedding_model` to one the server has. |
256
+ | `answered HTTP 401` | A hosted endpoint needs `api_key`. |
257
+ | No results for files you expected | Check the file's extension, size (`max_file_kb`) and that it is not hidden or in a skipped folder. |
258
+ | The first search is slow | Expected for a large folder: every file is embedded once. Later searches only embed changes. |
259
+
260
+ ## Disclosure
261
+
262
+ - **Network:** file contents (chunks) and search queries are sent to the embeddings endpoint you
263
+ configure. The default is a server on your own machine. If you point `base_url` at a hosted API,
264
+ that service receives the text of the files you search.
265
+ - **Files read:** text files under the folder the model asks to search, minus the skipped paths
266
+ listed above. The plugin never writes to that folder.
267
+ - **Files written:** the index database in the plugin's own data folder only.
268
+ - **Credentials:** the optional API key is read through Hermes's secret store and sent only to the
269
+ configured endpoint. It is dropped if the endpoint redirects to another origin.
270
+ - No telemetry, no background processes, no shell commands, no self-updating.
271
+
272
+ ## Roadmap
273
+
274
+ - Hybrid ranking: combine keyword (BM25) and vector scores.
275
+ - Result diversity (MMR) so near-duplicate chunks do not crowd the top results.
276
+ - An index statistics command and a way to clear old indexes.
277
+ - Tested on macOS and Windows in CI.
278
+
279
+ Ideas and bug reports are welcome in [Issues](https://github.com/Shizoqua/hermes-scout/issues).
280
+
281
+ ## Development
282
+
283
+ The search engine (`hermes_scout/engine.py`) and the HTTP client (`hermes_scout/embeddings.py`) use
284
+ only the Python standard library and do not import Hermes, so the tests run without a Hermes install
285
+ or network access:
286
+
287
+ ```bash
288
+ python -m pip install "pytest>=8,<9" "pytest-cov>=6,<8" "ruff==0.15.10"
289
+ python -m pytest --cov=hermes_scout # 34 tests, no network
290
+ ruff check . && ruff format --check .
291
+ ```
292
+
293
+ | Path | Contents |
294
+ |---|---|
295
+ | `hermes_scout/__init__.py` | Hermes wiring: tool registration, settings, file-safety checks, storage |
296
+ | `hermes_scout/plugin.yaml` | Plugin manifest read by Hermes |
297
+ | `hermes_scout/engine.py` | Chunking, file walking, the SQLite index and ranking |
298
+ | `hermes_scout/embeddings.py` | OpenAI-compatible embeddings client |
299
+ | `hermes_scout/cli.py` | The `hermes-scout` command |
300
+ | `docs/` | The documentation site (MkDocs Material) |
301
+
302
+ Before a release, check the plugin the way the Hermes catalog does:
303
+
304
+ ```bash
305
+ hermes plugins validate hermes_scout --install-deps
306
+ hermes plugins doctor hermes_scout --ci
307
+ ```
308
+
309
+ Every push runs lint, the tests on Python 3.11 to 3.14 with a 90% coverage floor, CodeQL security
310
+ analysis and a strict docs build. Publishing a GitHub release uploads the package to PyPI.
311
+
312
+ ## Contributing
313
+
314
+ Bug reports, ideas and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md);
315
+ the [Code of Conduct](CODE_OF_CONDUCT.md) applies everywhere in this project. Report security
316
+ problems privately as described in [SECURITY.md](SECURITY.md). Release notes live in
317
+ [CHANGELOG.md](CHANGELOG.md).
318
+
319
+ If hermes-scout is useful to you, a star helps other people find it.
320
+
321
+ [![Star history](https://api.star-history.com/svg?repos=Shizoqua/hermes-scout&type=Date)](https://star-history.com/#Shizoqua/hermes-scout&Date)
322
+
323
+ ## License
324
+
325
+ MIT, see [LICENSE](LICENSE). Made by [Lanre Shittu](https://github.com/Shizoqua). To cite this project, use
326
+ the "Cite this repository" button on GitHub ([CITATION.cff](CITATION.cff)).
327
+
@@ -0,0 +1,300 @@
1
+ <div align="center">
2
+
3
+ # hermes-scout
4
+
5
+ **Search your local files by meaning, not just keywords.**<br>
6
+ A [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin and a standalone command line tool.
7
+
8
+ ![hermes-scout: find anything in your files by meaning](docs/banner.png)
9
+
10
+ [![PyPI](https://img.shields.io/pypi/v/hermes-scout?label=pypi&color=7c5cff&logo=pypi&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://pypi.org/project/hermes-scout/)
11
+ [![Downloads](https://img.shields.io/pepy/dt/hermes-scout?label=downloads&color=ec4899&logo=python&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://pepy.tech/project/hermes-scout)
12
+ [![tests](https://img.shields.io/github/actions/workflow/status/Shizoqua/hermes-scout/tests.yml?branch=main&label=tests&logo=githubactions&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://github.com/Shizoqua/hermes-scout/actions/workflows/tests.yml)
13
+ [![docs](https://img.shields.io/github/actions/workflow/status/Shizoqua/hermes-scout/docs.yml?branch=main&label=docs&logo=materialformkdocs&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://shizoqua.github.io/hermes-scout/)
14
+ <br>
15
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3b82f6?logo=python&logoColor=white&labelColor=1e1b2e&style=flat-square)](https://www.python.org/)
16
+ [![Hermes Agent plugin](https://img.shields.io/badge/Hermes%20Agent-plugin-a855f7?labelColor=1e1b2e&style=flat-square)](https://github.com/NousResearch/hermes-agent)
17
+ [![Zero dependencies](https://img.shields.io/badge/dependencies-zero-14b8a6?labelColor=1e1b2e&style=flat-square)](#development)
18
+ [![License: MIT](https://img.shields.io/badge/license-MIT-f59e0b?labelColor=1e1b2e&style=flat-square)](LICENSE)
19
+
20
+ [**Documentation**](https://shizoqua.github.io/hermes-scout/) ·
21
+ [**Getting started**](https://shizoqua.github.io/hermes-scout/getting-started/) ·
22
+ [**Changelog**](CHANGELOG.md) ·
23
+ [**Report a bug**](https://github.com/Shizoqua/hermes-scout/issues/new/choose)
24
+
25
+ </div>
26
+
27
+ ---
28
+
29
+ Ask *"where do we handle rate limits?"* and get back the relevant paragraphs from your notes, docs
30
+ or code, even when they never use the words "rate limit". Results come with file paths, line
31
+ numbers and a similarity score.
32
+
33
+ hermes-scout works two ways:
34
+
35
+ - **As a Hermes Agent plugin**, adding a `semantic_search` tool the agent can call.
36
+ - **As a standalone command**, `hermes-scout search "..." ~/notes`, for anyone with Python.
37
+
38
+ Embeddings come from any OpenAI-compatible `/embeddings` endpoint. By default that is a local
39
+ [Ollama](https://ollama.com) server, so your files never leave your machine and searches cost nothing.
40
+
41
+ ![Demo: asking Hermes where rate limits are handled, and the ranked passages semantic_search returns](docs/demo.gif)
42
+
43
+ ## Contents
44
+
45
+ - [Why](#why)
46
+ - [Features](#features)
47
+ - [Quick start](#quick-start)
48
+ - [Command line](#command-line)
49
+ - [Example](#example)
50
+ - [How it works](#how-it-works)
51
+ - [Supported embedding servers](#supported-embedding-servers)
52
+ - [Settings](#settings)
53
+ - [Troubleshooting](#troubleshooting)
54
+ - [Disclosure](#disclosure)
55
+ - [Roadmap](#roadmap)
56
+ - [Development](#development)
57
+ - [Contributing](#contributing)
58
+ - [License](#license)
59
+
60
+ ## Why
61
+
62
+ Keyword search only finds the words you remember. Notes say "back off and retry", code says
63
+ `except HTTPError as err: if err.code == 429`, and docs say "throttling". You remember none of
64
+ those phrasings. Semantic search compares *meaning*: the query and every passage are turned into
65
+ embedding vectors, and the passages pointing in the most similar direction come back first.
66
+
67
+ ## Features
68
+
69
+ - **Search by meaning** across notes, docs and source code in any folder.
70
+ - **Local-first.** Works out of the box with Ollama, LM Studio, llama.cpp or vLLM on your own machine.
71
+ - **Fast repeat searches.** An incremental index re-embeds only files that changed since the last search.
72
+ - **Safe by default.** Skips hidden files, dependency folders, binaries and every path Hermes's own
73
+ file tools refuse to read, such as `.env` files and credential stores.
74
+ - **Zero dependencies.** Python standard library only: nothing extra to install or audit.
75
+ - **Precise results.** Every hit names the file, the line range and a cosine similarity score.
76
+ - **Two ways to use it:** as a Hermes tool or as a `hermes-scout` command in any terminal.
77
+ - **Configurable** from the Hermes Desktop settings page or `hermes plugins config hermes-scout`.
78
+
79
+ ## Quick start
80
+
81
+ 1. **Start a local embeddings server** (Ollama shown; see [other servers](#supported-embedding-servers)):
82
+
83
+ ```bash
84
+ ollama pull nomic-embed-text
85
+ ollama serve # if it is not already running
86
+ ```
87
+
88
+ 2. **Install hermes-scout** in Hermes:
89
+
90
+ ```bash
91
+ hermes plugins install hermes-scout
92
+ hermes plugins enable hermes-scout
93
+ ```
94
+
95
+ or as a command line tool:
96
+
97
+ ```bash
98
+ pipx install hermes-scout # or: pip install hermes-scout
99
+ ```
100
+
101
+ 3. **Search.** Ask Hermes:
102
+
103
+ > Search my notes in ~/notes for how I set up backups.
104
+
105
+ or run:
106
+
107
+ ```bash
108
+ hermes-scout search "how I set up backups" ~/notes
109
+ ```
110
+
111
+ The first search of a folder builds its index. Later searches only re-read files that changed.
112
+
113
+ ## Command line
114
+
115
+ ```console
116
+ $ hermes-scout search "how does the client handle rate limiting" ~/project
117
+ 0.59 notes/retries.md:1-3
118
+ Retry policy
119
+ 0.18 notes/pasta.md:1-3
120
+ Dinner
121
+ ```
122
+
123
+ | Command | What it does |
124
+ |---|---|
125
+ | `hermes-scout search QUERY [PATH]` | Search a folder (default: the current one). `-k 10` for more results, `--json` for scripts. |
126
+ | `hermes-scout index [PATH]` | Build or refresh the index ahead of time. |
127
+ | `hermes-scout --version` | Print the version. |
128
+
129
+ Point it at another server with `--base-url` and `--model`, or the `SCOUT_BASE_URL` and
130
+ `SCOUT_MODEL` environment variables. Hosted endpoints read their key from `SCOUT_API_KEY`. The
131
+ index lives in your user cache folder (`~/.cache/hermes-scout/index.db` on Linux). Full reference:
132
+ [Command line docs](https://shizoqua.github.io/hermes-scout/cli/).
133
+
134
+ ## Example
135
+
136
+ A search across a small project. The model receives this from the tool:
137
+
138
+ ```json
139
+ {
140
+ "query": "how does the client handle rate limiting and retries",
141
+ "root": "/home/me/project",
142
+ "model": "nomic-embed-text",
143
+ "results": [
144
+ {
145
+ "path": "notes/retries.md",
146
+ "lines": "1-3",
147
+ "score": 0.5948,
148
+ "text": "Retry policy\n\nWhen the API answers 429 the client waits with exponential backoff and jitter, then retries up to five times."
149
+ },
150
+ {
151
+ "path": "notes/pasta.md",
152
+ "lines": "1-3",
153
+ "score": 0.1849,
154
+ "text": "Dinner\n\nBoil pasta in salted water, add garlic and olive oil."
155
+ }
156
+ ],
157
+ "index": {"indexed_files": 0, "reused_files": 2, "removed_files": 0, "chunks": 2}
158
+ }
159
+ ```
160
+
161
+ The relevant note scores far above the unrelated one, and `"indexed_files": 0` shows that the
162
+ second search reused the index instead of embedding the folder again.
163
+
164
+ ## How it works
165
+
166
+ ```mermaid
167
+ flowchart LR
168
+ A[Folder of text files] --> B[Split into overlapping<br/>line-aligned chunks]
169
+ B --> C{New or changed<br/>since last search?}
170
+ C -- yes --> D[Embed via<br/>/embeddings endpoint]
171
+ C -- no --> E[(SQLite index)]
172
+ D --> E
173
+ Q[Your question] --> F[Embed the question]
174
+ E --> G[Rank chunks by<br/>cosine similarity]
175
+ F --> G
176
+ G --> R[Top passages with<br/>path, lines, score]
177
+ ```
178
+
179
+ 1. **Chunking.** Text files are split into chunks of whole lines (1,200 characters by default).
180
+ Neighbouring chunks share two lines, so a passage that straddles a boundary is still found whole.
181
+ 2. **Embedding.** Chunks are sent to the embeddings endpoint in batches of 32 and stored as float32
182
+ vectors with their precomputed norms.
183
+ 3. **Incremental index.** The index lives in SQLite in the plugin's own data folder
184
+ (`<hermes home>/plugin-data/hermes-scout/index.db`), keyed by folder and embedding model. Only
185
+ new or changed files (by modification time and size) are re-embedded, and deleted files are dropped.
186
+ 4. **Ranking.** The question is embedded the same way and chunks are ranked by cosine similarity:
187
+ `score = (q · c) / (‖q‖ ‖c‖)`.
188
+
189
+ Indexes for different embedding models are kept apart, so switching models never mixes vectors.
190
+
191
+ **What gets indexed:** common text, documentation, code and config extensions (`.md`, `.txt`, `.py`,
192
+ `.ts`, `.go`, `.rs`, `.json`, `.yaml`, ...). **Skipped:** hidden files and folders, dependency and
193
+ build folders (`node_modules`, `venv`, `dist`, `build`, ...), symlinks, binary files, files over the
194
+ size limit, and every path Hermes's file tools refuse to read.
195
+
196
+ ## Supported embedding servers
197
+
198
+ Any server that implements the OpenAI `POST /embeddings` API works. Set `base_url` to its `/v1` root.
199
+
200
+ | Server | `base_url` | Example `embedding_model` |
201
+ |---|---|---|
202
+ | [Ollama](https://ollama.com) (default) | `http://localhost:11434/v1` | `nomic-embed-text`, `mxbai-embed-large` |
203
+ | [LM Studio](https://lmstudio.ai) | `http://localhost:1234/v1` | the embedding model you loaded |
204
+ | [llama.cpp server](https://github.com/ggml-org/llama.cpp) (`--embeddings`) | `http://localhost:8080/v1` | the loaded model's name |
205
+ | [vLLM](https://github.com/vllm-project/vllm) | `http://localhost:8000/v1` | e.g. `BAAI/bge-m3` |
206
+ | Hosted OpenAI-compatible APIs | the provider's `/v1` URL | the provider's embedding model (set `api_key`) |
207
+
208
+ ## Settings
209
+
210
+ In Hermes, edit them in the Desktop app (**Settings → Plugins → hermes-scout**) or with
211
+ `hermes plugins config hermes-scout`. The command line takes the same settings as flags
212
+ (`--base-url`, `--model`, `--chunk-chars`, `--max-files`, `--max-file-kb`, `-k`).
213
+
214
+ | Setting | Default | Meaning |
215
+ |---|---|---|
216
+ | `base_url` | `http://localhost:11434/v1` | OpenAI-compatible base URL; the plugin calls `<base_url>/embeddings` |
217
+ | `embedding_model` | `nomic-embed-text` | Model name the endpoint serves |
218
+ | `api_key` | not set | Only for hosted endpoints; stored by Hermes as `SCOUT_API_KEY` |
219
+ | `top_k` | `5` | Passages returned per search (the model may ask for 1 to 20) |
220
+ | `chunk_chars` | `1200` | Chunk size in characters; applies to files indexed afterwards |
221
+ | `max_files` | `2000` | Files indexed per folder |
222
+ | `max_file_kb` | `1000` | Larger files are skipped |
223
+
224
+ ## Troubleshooting
225
+
226
+ | Message | Fix |
227
+ |---|---|
228
+ | `cannot reach the embeddings server at http://localhost:11434/v1` | Start Ollama (`ollama serve`) or point `base_url` at your server. |
229
+ | `answered HTTP 404 ... model not found` | Pull the model (`ollama pull nomic-embed-text`) or set `embedding_model` to one the server has. |
230
+ | `answered HTTP 401` | A hosted endpoint needs `api_key`. |
231
+ | No results for files you expected | Check the file's extension, size (`max_file_kb`) and that it is not hidden or in a skipped folder. |
232
+ | The first search is slow | Expected for a large folder: every file is embedded once. Later searches only embed changes. |
233
+
234
+ ## Disclosure
235
+
236
+ - **Network:** file contents (chunks) and search queries are sent to the embeddings endpoint you
237
+ configure. The default is a server on your own machine. If you point `base_url` at a hosted API,
238
+ that service receives the text of the files you search.
239
+ - **Files read:** text files under the folder the model asks to search, minus the skipped paths
240
+ listed above. The plugin never writes to that folder.
241
+ - **Files written:** the index database in the plugin's own data folder only.
242
+ - **Credentials:** the optional API key is read through Hermes's secret store and sent only to the
243
+ configured endpoint. It is dropped if the endpoint redirects to another origin.
244
+ - No telemetry, no background processes, no shell commands, no self-updating.
245
+
246
+ ## Roadmap
247
+
248
+ - Hybrid ranking: combine keyword (BM25) and vector scores.
249
+ - Result diversity (MMR) so near-duplicate chunks do not crowd the top results.
250
+ - An index statistics command and a way to clear old indexes.
251
+ - Tested on macOS and Windows in CI.
252
+
253
+ Ideas and bug reports are welcome in [Issues](https://github.com/Shizoqua/hermes-scout/issues).
254
+
255
+ ## Development
256
+
257
+ The search engine (`hermes_scout/engine.py`) and the HTTP client (`hermes_scout/embeddings.py`) use
258
+ only the Python standard library and do not import Hermes, so the tests run without a Hermes install
259
+ or network access:
260
+
261
+ ```bash
262
+ python -m pip install "pytest>=8,<9" "pytest-cov>=6,<8" "ruff==0.15.10"
263
+ python -m pytest --cov=hermes_scout # 34 tests, no network
264
+ ruff check . && ruff format --check .
265
+ ```
266
+
267
+ | Path | Contents |
268
+ |---|---|
269
+ | `hermes_scout/__init__.py` | Hermes wiring: tool registration, settings, file-safety checks, storage |
270
+ | `hermes_scout/plugin.yaml` | Plugin manifest read by Hermes |
271
+ | `hermes_scout/engine.py` | Chunking, file walking, the SQLite index and ranking |
272
+ | `hermes_scout/embeddings.py` | OpenAI-compatible embeddings client |
273
+ | `hermes_scout/cli.py` | The `hermes-scout` command |
274
+ | `docs/` | The documentation site (MkDocs Material) |
275
+
276
+ Before a release, check the plugin the way the Hermes catalog does:
277
+
278
+ ```bash
279
+ hermes plugins validate hermes_scout --install-deps
280
+ hermes plugins doctor hermes_scout --ci
281
+ ```
282
+
283
+ Every push runs lint, the tests on Python 3.11 to 3.14 with a 90% coverage floor, CodeQL security
284
+ analysis and a strict docs build. Publishing a GitHub release uploads the package to PyPI.
285
+
286
+ ## Contributing
287
+
288
+ Bug reports, ideas and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md);
289
+ the [Code of Conduct](CODE_OF_CONDUCT.md) applies everywhere in this project. Report security
290
+ problems privately as described in [SECURITY.md](SECURITY.md). Release notes live in
291
+ [CHANGELOG.md](CHANGELOG.md).
292
+
293
+ If hermes-scout is useful to you, a star helps other people find it.
294
+
295
+ [![Star history](https://api.star-history.com/svg?repos=Shizoqua/hermes-scout&type=Date)](https://star-history.com/#Shizoqua/hermes-scout&Date)
296
+
297
+ ## License
298
+
299
+ MIT, see [LICENSE](LICENSE). Made by [Lanre Shittu](https://github.com/Shizoqua). To cite this project, use
300
+ the "Cite this repository" button on GitHub ([CITATION.cff](CITATION.cff)).