hermes-digup
This server provides read-only tools to search, read, and browse the user's Mac files via a synced DigUp index, and to check index freshness.
Search files by meaning and exact words across documents, PDFs, screenshots, images, audio, and video; filter by kind, folder, and result limit.
Search code in Mac projects by behavior or name when DigUp code search is enabled.
Read a matched passage by
segment_id, optionally including neighboring pages/passages; supports code segments.Read all extracted text from a Mac file in paginated chunks, with continuation offset and code option.
Browse indexed files newest first, filtered by folder, kind, or name substring.
Check index status, including last sync time, index contents, and embedding-server availability.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hermes-digup find that PDF about the Q3 budget I saved last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hermes-indexing-mcp-server
An MCP server that lets your Hermes Agent search the files on your Mac by what's in them. It reuses the index the DigUp app already keeps, and gets query embeddings from EmbeddingGemma 2, served by oMLX on a second, always-on Mac.
Nothing is indexed twice. DigUp keeps indexing on your laptop the way it does now. This project copies its index to the Pi on a schedule, and searches it there with the same ranking DigUp uses.
Mac no.1 (laptop) Raspberry Pi Mac no.2 (always on)
┌──────────────────────┐ ┌───────────────────────────┐ ┌─────────────────────────┐
│ DigUp app │ rsync │ Hermes Agent (gateway) │ HTTP │ oMLX │
│ └ index.sqlite ─────┼──over ────▶│ └ hermes-digup (MCP) │──query──▶│ EmbeddingGemma 2 │
│ digup-sync (launchd) │ SSH, │ ├ index copy │◀─vector──│ (google's weights, │
│ │ every │ ├ meaning + keywords │ │ pinned in memory) │
│ Hermes desktop app ──┼── 15 min │ └ tools for the agent │ │ its own sub key │
│ (remote gateway) ───┼───────────▶│ │ └─────────────────────────┘
└──────────────────────┘ Tailscale └───────────────────────────┘ TailscaleContents
Related MCP server: Keepygaga RAG
How it works
The index. DigUp keeps one SQLite file, ~/Library/Application Support/DigUp/index.noindex/index.sqlite, plus
code.sqlite beside it if code search is on. The file holds every indexed file, a 768-dimension EmbeddingGemma 2
vector for every photo, PDF page, document passage, video frame and 30 seconds of audio, and a full-text keyword
index. This server reads that format directly (DigUp's schema 5) and never writes to it.
The sync. DigUp writes to its index while it runs, so copying the file as-is could catch it halfway through a
write. A launchd job on the laptop runs digup-sync.sh every 15 minutes. It:
takes a consistent snapshot with SQLite's backup API, including changes still in DigUp's write-ahead log;
runs an integrity check on the snapshot and turns it into one self-contained file;
sends it to the Pi with rsync over SSH. Only changed blocks cross the network, and rsync renames the finished file into place, so the Pi never sees half a file;
writes
manifest.json(when and from where), which lets the Pi tell how fresh its copy is.
If the laptop is asleep, nothing runs. launchd runs a missed sync when the laptop wakes. If the Pi can't be reached, the job logs it and tries again next time. If the files haven't changed, nothing is uploaded and only the "last confirmed" time is updated.
The search. On the Pi, hermes-digup loads the vectors into memory and watches the index file. When a new copy
lands, it loads and checks the new copy first, then switches to it. If the new copy won't open, the old one keeps
answering and index_status reports why the new one was refused. Each query goes to Mac no.2 to be embedded with
DigUp's prompt (task: search result | query: …). The ranking is DigUp's own, ported from its Swift code:
every vector is scored, with scores centred for each modality (text, image, audio);
a file has to stand out by meaning (z ≥ 2) or contain at least half of the query's words;
word matches add a bonus, which is why exact invoice numbers, names and error codes still work;
words that name a kind of file ("…in a video", "screenshot of…") give a small boost.
The embeddings. Query vectors only make sense if they come from the same model DigUp used for the index. DigUp
runs an 8-bit llama.cpp build of EmbeddingGemma 2, and it checked that build against mlx-vlm running Google's own
weights (google/embeddinggemma-2): cosine 0.999 or better on text. oMLX loads EmbeddingGemma 2 through that same
mlx-vlm, so the setup script on Mac no.2 serves Google's weights with your oMLX. oMLX adds no prompt of its own; the
Pi adds DigUp's. hermes-digup doctor proves the match: it re-embeds passages from your index and compares them with
the vectors DigUp stored. A cosine of about 1.0 means the two are identical.
What you need
Machine | Needs |
Mac no.1 (laptop) | DigUp installed, with its first indexing pass done. Stock macOS tools only: bash, sqlite3, rsync, ssh. |
Mac no.2 (server) | Apple Silicon, oMLX (the menu bar app or the Homebrew install) with a main API key set, about 1.5 GB free disk for the model and about 1 GB of memory to keep it loaded. |
Raspberry Pi | Hermes Agent, Raspberry Pi OS Bookworm or newer (Python 3.10+), rsync, and room for about two copies of the index (DigUp shows its size in Settings). A Pi 4 or 5 with 2 GB+ RAM. |
All three | Tailscale, on the same tailnet. |
Clone this repository on the Pi and on both Macs (or copy the deploy/ folder to the Macs):
git clone https://github.com/georgeslane/hermes-indexing-mcp-server.git
cd hermes-indexing-mcp-serverSetup
Do the steps in this order: the Pi needs oMLX's address, key and model name from step 2, and the laptop needs the Pi set up before it can sync.
1. Tailscale names
Find each machine's Tailscale name (MagicDNS) with tailscale status or in the Tailscale admin console. This guide
uses these example names, so swap in yours:
macbook: Mac no.1mac-mini: Mac no.2raspberrypi: the Pi, with the userpi
If MagicDNS is off, use the 100.x.y.z Tailscale IPs instead. Both work everywhere a name is asked for.
2. Mac no.2: the embedding server
oMLX needs a main API key before it can be reached from another machine. If you haven't set one, set it in the menu
bar app (Settings → Security) or in the web admin at http://127.0.0.1:8000/admin. Then, on the always-on Mac:
deploy/mac-server/setup-embedding-server.sh --exposeThe script only uses oMLX's admin API, so your other models and settings stay as they are. It:
finds your oMLX: its port and main key from
~/.omlx/settings.json(or the folder the app uses), and starts it if it isn't running;with
--expose, makes oMLX listen on the network (0.0.0.0) instead of only on this Mac, and restarts it. oMLX then refuses every request that has no key. Leave--exposeout if oMLX already listens on the network;downloads
google/embeddinggemma-2with oMLX's own downloader, unless oMLX already has it;pins the model, so oMLX keeps it loaded (text only, about 0.9 GB) and never unloads it for being idle. The first search after a quiet night is as quick as any other;
creates an oMLX sub key named
hermes-digupfor the Pi. A sub key can run models but can't change oMLX's settings, and you can revoke it on its own. It's saved in~/.config/hermes-digup/embedding-server.env, and a later run reuses it;embeds a test query the way the Pi will, and checks that the vector has 768 dimensions;
prints the
DIGUP_EMBED_URL,DIGUP_EMBED_API_KEYandDIGUP_EMBED_MODELlines for the Pi. Keep them for step 3.
Options:
--admin-key KEY: if the main key isn't in oMLX's settings file (for example, you set it withOMLX_API_KEY).--port 8000: if the script can't tell which port oMLX uses.--hf-token TOKEN: if Hugging Face asks you to accept the model's license first.--model-id NAME: to use an EmbeddingGemma 2 that oMLX already has under another name.--uninstall: deletes the Pi's sub key and unpins the model.
Don't quantize EmbeddingGemma 2 with oQ for this. A re-quantized copy can drift away from DigUp's vectors; doctor
would show it.
Keep this Mac available:
Never sleep: System Settings → Energy → turn on "Prevent automatic sleeping when the display is off". Or run
sudo pmset -a sleep 0.oMLX after a restart: the menu bar app starts its server at launch, so add oMLX to System Settings → General → Login Items, and turn on automatic login (Users & Groups) if the Mac runs without a screen. With Homebrew,
brew services start omlxdoes the same. Both restart oMLX if it crashes.Firewall: if the macOS firewall is on, allow oMLX the first time macOS asks.
From the Pi, check that you can reach it:
curl -s http://mac-mini:8000/health # {"status":"healthy",...}3. The Pi: install the MCP server
On the Pi, with the values step 2 printed:
deploy/pi/install.sh --embed-url http://mac-mini:8000,http://100.x.y.z:8000 \
--api-key <key from step 2> --model <model name from step 2>oMLX names a model after its folder, so the name depends on how the model was downloaded: for example
embeddinggemma-2, or embeddinggemma-2-bf16 for a community bf16 copy. If the name is wrong anyway, the Pi asks
oMLX for its model list and uses the EmbeddingGemma 2 it finds there (unquantized first). doctor then says which
name it used.
DIGUP_EMBED_URL takes several addresses, comma-separated, tried in order. Giving the MagicDNS name and the IP means
a DNS hiccup doesn't stop meaning search.
The script:
checks Python, and that this Python's SQLite can read DigUp's keyword index (FTS5 with DigUp's tokenizer);
installs
python3-venvandrsyncwith apt if they're missing;installs the server into its own virtualenv at
~/.local/share/hermes-digup/venvand links the command to~/.local/bin/hermes-digup;creates
~/.local/share/hermes-digup/index/, where the laptop will put the index;writes
~/.config/hermes-digup/config.env. The MCP server andhermes-digup doctorboth read this file, so the agent and your shell always use the same settings;installs the
digup-searchHermes skill into~/.hermes/skills/productivity/digup-search/(see Making Hermes search here first). If the desktop app uses a profile other than the default one, add--profile NAME.
Make sure SSH is on, so the laptop can log in to copy files: sudo raspi-config → Interface Options → SSH.
4. Mac no.1: sync DigUp's index to the Pi
On the laptop that runs DigUp, first give it a passwordless SSH key for the Pi. launchd can't type passwords:
ssh-keygen -t ed25519 -f ~/.ssh/hermes_digup -N ""
ssh-copy-id -i ~/.ssh/hermes_digup.pub pi@raspberrypiThen install the sync job:
deploy/mac-laptop/install.sh --pi pi@raspberrypi --key ~/.ssh/hermes_digupThe script:
copies
digup-sync.shto~/Library/Application Support/hermes-digup/, so the job keeps working even if you move or delete the repository;writes
~/.config/hermes-digup/sync.env;checks that SSH to the Pi works without a password and that the Pi has rsync;
installs the launchd job
com.hermes-digup.sync, which runs at login, then every 15 minutes, and after a wake when a run was missed. The first sync starts right away.
--interval 600 changes how often it syncs, in seconds. Ten to thirty minutes is a sensible range. DigUp makes a new
file searchable within seconds, so a shorter interval means fresher results on the Pi. Each run is cheap: an
unchanged index sends nothing, and a changed one sends only the changed blocks.
The sync finds the index on its own. It looks at DIGUP_INDEX_DIR in sync.env, then at DigUp's own "index folder"
setting, then at DigUp's default location.
To run a sync by hand and watch it:
~/Library/Application\ Support/hermes-digup/digup-sync.sh --force -v
tail -f ~/Library/Logs/hermes-digup-sync.logTailscale SSH (
tailscale set --sshon the Pi) also works with no keys at all. But the default tailnet policy asks you to sign in again in a browser every 12 hours ("check" mode), which breaks unattended syncs. Plain SSH keys are the reliable choice, unless your policy uses"action": "accept".
5. Add it to Hermes
Hermes runs on the Pi, so the MCP server runs there too, as a subprocess of Hermes. On the Pi, run:
hermes mcp add digup --command ~/.local/bin/hermes-digup --args serveor add this to ~/.hermes/config.yaml:
mcp_servers:
digup:
command: "/home/pi/.local/bin/hermes-digup" # the path install.sh printed
args: ["serve"]
timeout: 60
connect_timeout: 30Then run /reload-mcp in a Hermes chat. A running gateway notices the config change by itself within about a
minute. You can also add the server from the Hermes desktop app on the laptop: Settings → MCP servers, with your
Pi's gateway selected. MCP setup always applies to the gateway the app is connected to, which here is the Pi.
All settings come from ~/.config/hermes-digup/config.env, so this block needs no env:. Any setting can still be
overridden there; for example, env: {DIGUP_STALE_HOURS: "12"}.
Hermes registers the tools as mcp_digup_search_files, mcp_digup_read_passage and so on. Every tool is marked
read-only.
6. Check it
On the Pi:
hermes-digup doctor[ok ] index /home/pi/.local/share/hermes-digup/index/index.sqlite: 18342 files, 61877 vectors, schema 5
[ok ] last synced 0.2 hours ago
vectors made by: google/embeddinggemma-2@bfcd298 llama.cpp-vectors1 text-q8_0+mmproj-q8_0
[ok ] embedding server http://mac-mini:8000 answered in 38 ms
[ok ] query vectors vs DigUp's: mean cosine 0.9996 over 6 stored passages (match)
all goodThen search from the shell:
hermes-digup search "the clause about pets in the lease"
hermes-digup search "screenshot of the payment declined error" --kind screenshot
hermes-digup search "INV-2026-0042"
hermes-digup read 48213 # the text of a result's segment_idThen ask Hermes, from the desktop app on your laptop, something like "find the PDF where my landlord talks about pets", "what did that podcast say about sleep, and when?" or "summarise the latest bank statement in Downloads".
What Hermes can do with it
Tool | What it does |
| Hybrid search (meaning plus exact words). Takes optional |
| The same over DigUp's code index ("retry a failed call with backoff"), if code search is on in DigUp. Uses DigUp's code-retrieval prompt. |
| The full text of a match (a PDF page, a document passage, a screenshot's text, a stretch of code), with up to 3 neighbouring passages on each side. |
| All the text DigUp extracted from one file, in order, in pages ( |
| Lists indexed files, newest first, filtered by folder, kind or part of the name ("my latest screenshots"). |
| How fresh the copy is, what's in it, and whether the embedding server answers. |
Pictures, audio and video are found by meaning. DigUp keeps vectors for them, not words, so read_* has no text for
them, except for screenshots, whose text DigUp reads on a Mac. Paths are paths on the laptop, which you can open from
there.
Making Hermes search here first
Out of the box Hermes can take a while to reach for these tools. It tends to search the Pi's own disk first with its built-in file tools, which can never find your Mac's files. Two things cause this:
Tool Search. Hermes's Tool Search is on by default. It keeps every MCP tool out of the model's tool list, showing only a one-line preview of each, while its own file tools are always loaded.
What the model knows. Nothing tells the model that your files live on another machine.
These settings fix both. They're in order of effect; the first two together are usually enough.
1. Pin the digup-search skill (deploy/pi/install.sh installs it). Its full text then goes into the system
prompt of every new chat. It tells the model that your files are on your Mac, to use the digup tools first and not
search this machine's disk, and how to read a match before quoting it. In the Pi's ~/.hermes/config.yaml (or the
profile's), add:
skills:
auto_load:
- digup-searchIt costs about 1,000 tokens per chat. Without pinning, the skill still appears in Hermes's skill list and the model is told to load matching skills, so it helps either way; pinned, it's certain.
2. Tell Hermes to remember it. Memory is also part of every chat's system prompt. In any chat, say:
Remember: my files are on my Mac, not on this machine. To find, read or summarise any of my files, use the digup tools first, never the local filesystem or terminal.
3. Load the tools directly (optional). If digup is your only MCP server, or you have just a few, turn Tool Search off so their full descriptions are always in front of the model:
tools:
tool_search:
enabled: offThis loads every MCP server's tools into every chat, so skip it if you have large servers attached. Even with Tool Search on, each tool's preview starts by saying what it's for (for example, "Find the user's Mac files by content; use it first.").
Changes apply to new chats: start one in the desktop app after editing.
When something is down
Situation | What happens |
Laptop asleep, off, or away | The Pi keeps searching its last copy. When the copy is older than |
Pi unreachable during a sync | The sync logs it and exits. The next run sends everything that changed. |
Sync killed halfway (laptop sleeps, network drops) | rsync never put a partial file in place. The Pi still has the previous complete copy, and the next run finishes the job. A leftover lock is cleared automatically. |
A broken or unexpected file arrives | The new copy is checked before it's used. If it fails, the old one keeps answering and |
Mac no.2 asleep, rebooting, or unreachable | Each embedding address gets a 3-second connection check, then the next address is tried. If none answers, the search runs on exact words only, and the result says |
The embedding server returns the wrong kind of vector (wrong model, wrong size, token vectors) | A clear error saying what's wrong. |
DigUp turns code search off | The next sync removes |
DigUp is updated and its index schema changes | Known schemas load normally. A newer one is tried anyway, with a warning in results and status asking you to update hermes-digup. |
The same question twice | Its vector is cached (the last 512 queries), so Mac no.2 isn't asked again. |
Settings
Pi: ~/.config/hermes-digup/config.env. Environment variables override this file, and DIGUP_CONFIG points to
a different one.
Setting | Default | Meaning |
|
| Folder holding |
| (none) | Embedding server base URL(s), comma-separated, tried in order. Without one, only keyword search works. |
| (none) | Bearer token for the embedding server. |
|
|
|
|
| The model's name in oMLX, as the setup script printed it. If the server has no model by that name, its EmbeddingGemma 2 is used, whatever it's called. |
|
| Seconds to wait for a vector once connected. |
|
| Age after which results mention that the index is old. |
| auto |
|
|
| Logs go to stderr, which Hermes saves in |
Laptop: ~/.config/hermes-digup/sync.env
Setting | Default | Meaning |
| (required) |
|
|
| Where the copy goes on the Pi, relative to the Pi user's home. Must match |
| (none) | Private key to use (a path without spaces). |
| auto | Only if DigUp's index lives somewhere unusual. |
|
|
|
|
| Also copy |
To change the sync interval, run install.sh --interval <seconds> again.
Troubleshooting
hermes-digup doctor says there's no index. The laptop hasn't synced yet. Run
~/Library/Application\ Support/hermes-digup/digup-sync.sh --force -v on it and read the output. The usual causes:
SSH asks for a password: set up the key from step 4.
rsync is missing on the Pi:
sudo apt install rsync.DigUp hasn't finished its first pass yet.
"the Pi isn't reachable" in the sync log. Check that ssh pi@raspberrypi works from the laptop and that
Tailscale is connected on both machines.
The sync log says it can't open the index ("operation not permitted"). You moved DigUp's index into a folder
macOS protects, such as Documents or Desktop. Give /bin/bash Full Disk Access (System Settings → Privacy &
Security), or keep the index in its default place.
The comparison says "mismatch" (cosine well below 1). oMLX isn't making DigUp's vectors. Check that
DIGUP_EMBED_MODEL names Google's google/embeddinggemma-2 as oMLX downloaded it, not an oQ-quantized or
community-converted copy. Re-running setup-embedding-server.sh sets this up. A "close" result (0.9 to 0.98) still
searches, but ranks a little worse than DigUp.
Searches say "keywords only". Mac no.2 didn't answer. Check that oMLX is running there (its menu bar icon, or
brew services info omlx), and look at ~/.omlx/logs/server.log. From the Pi, run
curl http://mac-mini:8000/health. If it only answers on Mac no.2 itself, oMLX listens on 127.0.0.1: run the setup
script again with --expose.
HTTP 401. DIGUP_EMBED_API_KEY on the Pi doesn't match the sub key in Mac no.2's
~/.config/hermes-digup/embedding-server.env, or the sub key was deleted in oMLX. Re-running the setup script makes
a new one.
"no model 'embeddinggemma-2'" or "It has no EmbeddingGemma 2 model". When DIGUP_EMBED_MODEL isn't the model's
name in oMLX, the Pi uses the server's EmbeddingGemma 2 under its own name, and doctor shows a [warn] line with the
setting to put in config.env. If oMLX has no EmbeddingGemma 2 at all, the error lists the models it has: run the
setup script on Mac no.2 to download it.
Hermes doesn't show the tools. Run hermes mcp test digup, check ~/.hermes/logs/mcp-stderr.log, and make sure
the command: path exists (ls ~/.local/bin/hermes-digup). Run /reload-mcp after changes.
A result is missing. First check that DigUp itself finds it on the laptop. If it does, the Pi's copy is just
older: run index_status, or hermes-digup status, to see when it was last synced.
Running the embeddings on the Pi instead
The Pi only embeds search queries, so it can run EmbeddingGemma 2 itself and free the ~1 GB oMLX keeps loaded on Mac
no.2. Your index doesn't change and nothing is re-indexed. The Pi runs the very file DigUp made the index with:
embeddinggemma-2-Q8_0.gguf at DigUp's pinned revision, checksum-verified. It's run by the same llama.cpp release
DigUp builds (b11461, with DigUp's one-line memory patch) and mean-pooled the same way. That's an even closer match to
your index than oMLX's bf16 copy.
On the Pi (a Pi 5, or a Pi 4 with 4 GB or more):
deploy/pi/setup-embedding-server.shThe script:
installs
git,cmakeand a compiler with apt if they're missing;downloads llama.cpp at b11461, checks it's the exact commit DigUp pins, applies DigUp's patch, and builds only
llama-server, optimized for this CPU. This happens once and takes about 10 to 20 minutes on a Pi 5;downloads the text part of the model (310 MB, resumable) and checks DigUp's SHA-256;
runs it as the systemd user service
hermes-digup-embeddings. It listens on127.0.0.1:8088only, so nothing else on your network can reach it and it needs no key. systemd restarts it if it stops, and lingering is turned on so it starts at boot;embeds a test query and checks for a 768-dimension vector;
puts
http://127.0.0.1:8088first inDIGUP_EMBED_URLand keeps the Mac's addresses after it, so the Mac is used only if the Pi's server is down;runs
hermes-digup doctor. Its comparison line should say "match".
Then:
Restart the MCP server with
/reload-mcpin Hermes, or restart Hermes. The MCP server readsDIGUP_EMBED_URLwhen it starts.Free the Mac's memory. On Mac no.2, run
deploy/mac-server/setup-embedding-server.sh --unpin. This unpins and unloads EmbeddingGemma 2 but keeps the Pi's key, so the Mac still answers as the fallback. oMLX then loads the model only if the Pi's server is down.
What it costs the Pi:
Memory: about 0.5 GB while serving. The service also asks systemd to cap it at 1.5 GB, so it can't crowd out Hermes, where your system enforces memory limits on user services (Raspberry Pi OS normally does).
Speed: a query is short, so expect well under a second on a Pi 5. The test query's time is printed at the end. Repeated queries are cached anyway.
Options: --port, --threads (all cores by default), and --no-fallback to drop the Mac from DIGUP_EMBED_URL.
--uninstall stops the service and puts the Mac first again. After that, run the Mac's script without --unpin to pin
the model there again.
Check on it with systemctl --user status hermes-digup-embeddings and journalctl --user -u hermes-digup-embeddings.
Other setups
Ollama, LM Studio or llama.cpp on Mac no.2 instead of oMLX. Set DIGUP_EMBED_URL to the server and
DIGUP_EMBED_MODEL to its name for EmbeddingGemma 2. With llama.cpp, the closest match is the file DigUp itself
runs: ggml-org/embeddinggemma-2-GGUF's embeddinggemma-2-Q8_0.gguf, served by
llama-server --embedding --pooling mean -c 2048 -ub 2048. For Ollama, either set DIGUP_EMBED_API=ollama (its native
/api/embed) or keep openai with the URL ending in /v1. Then run hermes-digup doctor and look at the
comparison line. Only a "match" means search will rank like DigUp.
Running the server on the laptop itself. Point DIGUP_INDEX_DIR at DigUp's own folder
(~/Library/Application Support/DigUp/index.noindex). The server sees DigUp's write-ahead log, opens the live index
read-only next to DigUp, and picks up DigUp's changes as they happen, with no sync needed. This is handy for trying
things out, or if Hermes ever runs on the Mac.
Hermes reaching the server over HTTP. Run hermes-digup serve --http --host 100.x.y.z --port 8765 (for example
under systemd) and use url: "http://100.x.y.z:8765/mcp" in Hermes's config instead of command:.
Updating and uninstalling
Update:
git pull, then on the Pi rundeploy/pi/install.shagain (it keeps your config). On the Macs, run their scripts again.Pi: remove the
digupentry from Hermes, thenrm -rf ~/.local/share/hermes-digup ~/.config/hermes-digup ~/.local/bin/hermes-digup.Laptop:
deploy/mac-laptop/install.sh --uninstall.Mac no.2:
deploy/mac-server/setup-embedding-server.sh --uninstalldeletes the Pi's sub key and unpins the model. To free its disk space too, delete EmbeddingGemma 2 on oMLX's Models page.
Development
python3 -m venv .venv && .venv/bin/pip install -e '.[test]'
.venv/bin/pytestThe tests build indexes with DigUp's exact schema and run the real embedding client against a fake embedding server. They cover:
meaning, keyword and lookup ranking;
filters;
reading pages and documents (chunk overlaps merged);
hot reload, and refusing a broken copy;
a live WAL-mode index;
failover, timeouts and the keyword fallback;
Ollama and API keys;
the vector comparison;
the sync script, against a local stand-in for the Pi;
the Pi's embedding-server script, with stand-ins for git, cmake, the download and systemd, and a fake
llama-serverthat systemd really starts;the oMLX setup script, against a fake oMLX (its JavaScript JSON helper runs under Node instead of
osascript);the Hermes skill: Hermes's authoring rules, that it names exactly the server's tools, and that every tool's preview fits Tool Search's 60 characters.
Layout:
src/hermes_digup/
index.py reads DigUp's SQLite index, validates and hot-reloads snapshots
search.py DigUp's hybrid ranking (Searcher.swift), ported
textnorm.py DigUp's query normalisation, stopwords and kind words (SearchText.swift)
embed.py EmbeddingGemma 2 client: DigUp's prompts, failover, cache
service.py the tools' logic; server.py exposes it over MCP; cli.py the shell commands
hermes/skills/
digup-search/ the Hermes skill that makes the agent search the Mac's files here first
deploy/
mac-laptop/ digup-sync.sh + launchd installer (Mac no.1)
mac-server/ oMLX setup for EmbeddingGemma 2, through its admin API (Mac no.2)
pi/ virtualenv installer and Hermes config, and the optional on-Pi embedding server (Raspberry Pi)DigUp's index format isn't a public API, so a DigUp update could change it. The reader checks the schema version and tells you when it sees one it doesn't know.
License
MIT. DigUp is MIT licensed, EmbeddingGemma 2 is Apache 2.0, and oMLX is Apache 2.0. This project isn't affiliated with DigUp, oMLX, Google or Nous Research.
Available Tools
6 toolsbrowse_filesARead-onlyIdempotent
List the user's Mac files, newest first.
Filter by folder, kind or part of the name: 'my latest screenshots', 'PDFs in Downloads'.
Inputs: kind, limit, folder, name_contains.
index_statusARead-onlyIdempotent
Check how fresh the user's Mac file index is.
When it was last synced, what's in it, and whether the embedding server answers.
Inputs: no named parameters.
read_fileARead-onlyIdempotent
Read all the text of one of the user's Mac files.
Everything DigUp extracted from the file (PDF pages, document text, slide and sheet text, screenshot text), in order, in pages of max_chars. Use it for paths from a digup search, which don't exist on this machine. Pictures, audio and video have no text.
Inputs: path (required), code, offset, max_chars.
read_passageBRead-onlyIdempotent
Read the text of a digup search match (segment_id).
The full text of the matched page, passage or code stretch, as DigUp read it.
Inputs: segment_id (required), code, context.
search_codeARead-onlyIdempotent
Find code in the user's Mac projects by what it does.
Searches DigUp's code index (if code search is turned on in DigUp). Returns files with line ranges; read them with read_passage(code=true) or read_file(code=true).
Inputs: query (required), limit, folder.
search_filesARead-onlyIdempotent
Find the user's Mac files by content; use it first.
Searches DigUp's index of the user's Mac, by meaning and exact words: documents, PDFs page by page, photos and screenshots by what they show, audio and video by what's said, with timestamps. Use it first for any question about the user's files; they aren't on this machine, so the terminal and the local file tools can't find them. Returns the best matching files with where the match is (page, timestamp, chunk), an excerpt, and a segment_id for read_passage. Results marked weaker_match trail far behind the top ones.
Inputs: query (required), kinds, limit, folder.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct action/resource: index health, semantic file search, semantic code search, passage reading, whole-file reading, and file listing. The overlap between read_passage and read_file is clearly resolved by segment_id vs whole-file path semantics.
All names use consistent snake_case with predictable verb_noun or noun_status patterns. The verbs search_, read_, browse_, and index_ are used coherently and reflect their operations.
Six tools is well-scoped for a file-index search/read server. Each tool has a clear role, and there are no redundant or filler tools.
The surface covers the lifecycle needed for this domain: checking index status, discovering files via search or browsing, searching code separately, and reading either matched passages or complete files. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
Securely search and manage workspace context files for AI agents and teams.
Agentic search over your Dewey document collections from any MCP-compatible client.
Search your knowledge bases from any AI assistant using hybrid RAG.
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search a Mac's documents by content using a local index, returning ranked paths and matching snippets. It supports formats like PDF, DOCX, HWP, and OCR'd scans, with Korean-aware search, while keeping everything offline and without requiring filesystem access.45 npmMIT
- AlicenseAqualityCmaintenanceEnables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.1MIT
- AlicenseAqualityCmaintenanceEnables natural-language search over locally indexed files such as markdown, text, images, videos, and PDFs, and retrieves indexed text or media metadata by path. It lets Cursor query a local embedding index built with Gemini and SQLite.2MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to search a locally indexed second brain built from scattered notes, docs, PDFs, and chat exports, returning hybrid vector-plus-keyword results with section-level citations rather than whole files.-