mindex 1.0.0

FOR HUMANS

A coding agent should not read your codebase — it should ask. mindex indexes your repositories locally and answers three kinds of question cheaply: semantic search (hybrid BGE-M3 retrieval returns the handful of chunks that matter, not whole files), exact symbols (where is X defined, who calls it — a tree-sitter symbol table instead of a grep loop), and research (you ask a question in English, a local model runs the whole investigation and hands back a cited Markdown report, so the code it read never enters your expensive model's context).

Everything stays on your machine: vectors in a local Qdrant, metadata in a local SQLite file, embeddings from a local BGE-M3 server. 21 programming languages plus Markdown.

This first release contains the HTTPS API server, two CLI tools (mindex-index for bulk indexing, mindex-watch to keep an index live), a terminal search frontend, two MCP servers (mindex for search and symbols, scout for research) and a VS Code extension attached below — download mindex-vscode-1.0.0.vsix and run code --install-extension mindex-vscode-1.0.0.vsix. Start with the README.

FOR MACHINES

Wire contracts — stable, snapshot-tested, safe to build clients on.

• Errors are RFC 7807 application/problem+json with a namespaced machine code (validation.top_k_out_of_range, selector.empty, research.busy, …). The code is the localization key and the thing to branch on; title/detail are English prose and are not. Pinned by codes_are_stable.
• OpenAPI 3.1 at /api-docs/openapi.json, Swagger UI at /swagger-ui, both served by the same process. Every handler is in the spec — a test asserts the count, so an endpoint missing from it is a build failure, not a surprise.
• Data-plane routes carry /v0; management routes (/projects, /gc, /status, /config, /health, /version) are unversioned. /v0 is the contract generation, not the release number — 1.0.0 ships /v0 deliberately.
• POST /v0/{guid}/research is one-way SSE. Event names and their field sets are a contract (progress_wire_fields_are_stable, done_event_carries_the_reason_and_the_run_cost_on_the_wire, done_reason_wire_values_are_stable). Every frame is one data: line — payloads are JSON-escaped, so a line-oriented reader is safe. Cancellation is disconnect; there is no cancel endpoint.
• GET /metrics is OpenMetrics on the same listener. Metric names and types are pinned by metric_names_are_stable; every label value comes from a server-defined set, and project_guid is the only open-ended one.

Reading the research output. The report's citations are provenance-checked server-side before you see them: each path:start-end is bucketed verified / path_only / unverified against what the run's own tools actually returned, and a draft that fails is sent back to the model with the offending locations named. So trust a report with a clean citations event; the one thing worth checking is citations.unverified_paths. Read done.reason too — finalized means the model judged the evidence sufficient, anything else means a budget stopped it and the report says so in its own first paragraph.

Keeping an index correct. Unchanged files are skipped by content hash and by derivation version, so a slicer or tags-query change rebuilds affected files on the next ordinary run with no --force and no bookkeeping. POST /drift compares a posted path → sha256 manifest against the index and classifies every file stale / missing / orphaned / indexing; it is read-only and backs mindex-index --check, the MCP drift tool and the watcher's sweep. Paths are repo-root-relative with forward slashes, exactly as first indexed — a different spelling creates a duplicate rather than updating.

Operational shape. One process per database (the indexing claim is an in-process lock). TLS is the whole of the transport security and there is no API auth — put a reverse proxy in front of it to reach it from anywhere but localhost; every client can carry an optional X-Api-Key for that proxy, which mindex itself ignores. Schema is one migration; there is no upgrade path across a schema change, and the database may be dropped and recreated freely.

Architecture, invariants, and the reasoning (with the measurements it rests on) are in .claude/CLAUDE.md.