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.
- hermes_scout-0.1.0/CHANGELOG.md +27 -0
- hermes_scout-0.1.0/LICENSE +21 -0
- hermes_scout-0.1.0/PKG-INFO +327 -0
- hermes_scout-0.1.0/README.md +300 -0
- hermes_scout-0.1.0/hermes_scout/__init__.py +134 -0
- hermes_scout-0.1.0/hermes_scout/cli.py +122 -0
- hermes_scout-0.1.0/hermes_scout/embeddings.py +101 -0
- hermes_scout-0.1.0/hermes_scout/engine.py +256 -0
- hermes_scout-0.1.0/hermes_scout/plugin.yaml +45 -0
- hermes_scout-0.1.0/hermes_scout/schemas.py +34 -0
- hermes_scout-0.1.0/pyproject.toml +48 -0
- hermes_scout-0.1.0/tests/conftest.py +6 -0
- hermes_scout-0.1.0/tests/test_cli.py +112 -0
- hermes_scout-0.1.0/tests/test_embeddings.py +91 -0
- hermes_scout-0.1.0/tests/test_engine.py +154 -0
- hermes_scout-0.1.0/tests/test_plugin.py +132 -0
|
@@ -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
|
+

|
|
35
|
+
|
|
36
|
+
[](https://pypi.org/project/hermes-scout/)
|
|
37
|
+
[](https://pepy.tech/project/hermes-scout)
|
|
38
|
+
[](https://github.com/Shizoqua/hermes-scout/actions/workflows/tests.yml)
|
|
39
|
+
[](https://shizoqua.github.io/hermes-scout/)
|
|
40
|
+
<br>
|
|
41
|
+
[](https://www.python.org/)
|
|
42
|
+
[](https://github.com/NousResearch/hermes-agent)
|
|
43
|
+
[](#development)
|
|
44
|
+
[](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
|
+

|
|
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
|
+
[](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
|
+

|
|
9
|
+
|
|
10
|
+
[](https://pypi.org/project/hermes-scout/)
|
|
11
|
+
[](https://pepy.tech/project/hermes-scout)
|
|
12
|
+
[](https://github.com/Shizoqua/hermes-scout/actions/workflows/tests.yml)
|
|
13
|
+
[](https://shizoqua.github.io/hermes-scout/)
|
|
14
|
+
<br>
|
|
15
|
+
[](https://www.python.org/)
|
|
16
|
+
[](https://github.com/NousResearch/hermes-agent)
|
|
17
|
+
[](#development)
|
|
18
|
+
[](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
|
+

|
|
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
|
+
[](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)).
|