qdrant-recall-sidecar

Qdrant Recall Sidecar

Overview

A Qdrant sidecar gives Hermes Agent a local semantic search layer over selected skills and recent session text. It is useful when exact keyword search is too brittle but cloud memory is not desired.

The safe default is local-first: bind Qdrant to 127.0.0.1, preview indexing with --dry-run, and index only what you are comfortable searching later.

When to Use

• Hermes needs semantic recall over installed skills.
• Recent user/assistant session text should be searchable locally.
• You want an MCP tool that can search Qdrant from inside Hermes.

Do not use it to index secrets, raw tool outputs, private datasets, or system prompts unless you have reviewed and approved that data class.

Basic Workflow

1. Start local Qdrant.
2. Dry-run the skill or session indexer.
3. Recreate or upsert the collection only after previewing content.
4. Add the Qdrant MCP sidecar to Hermes config.
5. Verify collections, vector size, point-count trend, and a real search result.
6. Schedule the quiet watchdog.
7. If Qdrant runs in Docker, use bounded start/restart for service bring-up and restart calibration for post-restart recall verification.
8. If repair is needed, fix the smallest failing collection first, then verify quiet mode.

Common Pitfalls

1. Mixing embedding models across collections with similar names.
2. Indexing private data because dry-run was skipped.
3. Forgetting that local recall is still a searchable copy of text.
4. Treating Qdrant as a replacement for curated memory. It is retrieval, not judgment.
5. Trusting on-disk collection folders without checking the live Qdrant API after a container restart.
6. Letting Docker CLI stalls or broad rebuild scripts turn a healthy Qdrant HTTP endpoint into a scheduled-task timeout.
7. Rebuilding every corpus when the watchdog only reports one MISSING collection.
8. Mixing service bring-up with data repair. Start or restart the local Qdrant container first; only rebuild collections after the watchdog still reports a data or vector-configuration problem.
9. Treating a tiny point-count drop in a rolling recent-session collection as a rebuild trigger. First confirm API health, intended window bounds, and a known topic search result.
10. Letting archived or lifecycle-marked inactive skills re-enter active recall during a collection rebuild. Keep hidden catalog directories and retired, archived, or deprecated frontmatter out of the active skills collection.