vecgrep: Instructions file for Claude Code

vecgrep — Claude Code working notes

What this is

A local-first semantic search tool. CLI-first, web UI on the side. OSS — no PII, no leaked context, no portfolio data, no internal hostnames in source. Generic-only.

Architecture cheat sheet

vecgrep/backend/
├── main.py              FastAPI app, mounts /api and serves frontend/dist
├── config.py            settings + ~/.vecgrep paths
├── ingestion/
│   ├── adapters/        text, markdown, pdf, url -> str
│   └── chunkers/        SentenceWindowChunker (default), FixedTokenChunker
├── embed/               OllamaBackend (default), OpenAIBackend (fallback)
├── store/               QdrantStore wrapper (embedded mode)
└── api/                 routes: search, corpus, config

vecgrep/cli/             Click commands that hit the local API
vecgrep/frontend/        React + Tailwind, single page, built into dist/

Design rules

• Flat over nested. No abstract base classes for things with one impl.
• Adapter and chunker interfaces are the only spots designed for extension — everything else is concrete.
• Config in one place (backend/config.py), env vars override JSON.
• ~/.vecgrep/ is the only persistence location. --ephemeral skips it.
• Qdrant runs in embedded mode (path=...) by default — no server, no Docker. Server mode (qdrant_url) is opt-in for concurrent readers/writers (serve + watch at once). Embedded locks the dir to ONE process; two clients on different backends = silent split-brain (CLI writes embedded while the daemon reads server, or vice-versa). A multi-process deployment MUST pin qdrant_url in ~/.vecgrep/config.json, not just the systemd unit env — env only reaches the units, so a bare CLI invocation falls back to embedded and diverges. vecgrep doctor reconciles registry↔store but only against whichever backend IT resolves, so same rule applies.
• Errors that the user can fix (Ollama not running, model not pulled) get plain English messages with the exact command to fix.
• MCP exposes no DIRECT mutation. The stdio MCP server is read-only (search, list_corpora, get_corpus). The HTTP transport adds the propose_* family (propose_write, propose_edit, propose_delete) — but these write/remove nothing: each creates an inert pending proposal that a human turns into a real write/delete via vecgrep confirm (off-protocol). So even over a leaked/unauthed /mcp endpoint an agent can only suggest a change, never land one — and a propose_delete removes a doc + its embeddings only after that human confirm. Direct/immediate index and delete stay on the REST routes, which operators keep behind tailnet / VPN / localhost. The propose corpus set is default-deny (VECGREP_PROPOSE_ALLOWED_CORPORA), so a proposal can't even target a corpus the operator hasn't opened.
  • propose_edit has two modes: full overwrite (content= the whole new body) or surgical patch (old_str= + new_str= — a str-replace of one unique span, so you don't re-send an 8KB doc to fix one line). The patch is a hard error if old_str is missing or appears more than once (add surrounding context to disambiguate); it touches the body only, frontmatter is preserved, and it flows through the identical proposal/confirm/corpus-gate path. Example — fix a date without a regen: propose_edit(doc_id="notes-007", old_str="July 25", new_str="July 17").