Documentation

Verify your setup (self-check) & re-indexing

A copy-paste self-check that proves the prom.codes MCP servers are connected and actually working in your project — including that semantic (vector) code search is live — plus how to re-index on demand.

After you install (or update) the prom.codes MCP servers, run this self-check inside a project to confirm everything works end to end. It is the fastest way to know that code search, memory, and the saver are all live — and, crucially, that semantic (vector) search is active, not just keyword/graph fallback.

The self-check prompt

Paste this into the agent in your project. It drives the MCP tools and reports PASS/FAIL per step:

Run a Prometheus self-check and report PASS/FAIL per step:
1. index_status — tell me the resolved workspace root, how many files/symbols
   are indexed, and whether embeddings are reachable.
2. search_code for a CONCEPT in this repo (a full sentence, not a keyword) and
   show one hit WITH its provenance.vector > 0 — proof the dense/semantic path
   is live (not just lexical + graph).
3. memory_status, then memory_write a test fact (type semantic, key
   prom-selfcheck) and memory_list it back to confirm the round-trip.
4. Confirm this repo's CLAUDE.md or AGENTS.md now contains the
   prometheus-memory and prom-saver rule blocks.

How to read the result

#	Step	PASS means
1	`index_status`	the resolved root is your repo; `index.indexed` is true with a sensible file/symbol count (source only — no `node_modules` bloat); `autoIndex.allowedForThisRoot` is true.
2	`search_code`	a concept query returns a hit whose `provenance.vector > 0` — embeddings and dense retrieval are working.
3	`memory_status` + round-trip	`installed: true`, the rule is installed, and your `memory_write` is read back by `memory_list`.
4	config blocks	the repo's `CLAUDE.md` (or `AGENTS.md`) carries the marked `prometheus-memory` and `prom-saver` blocks (auto-installed on server boot).

Example of a healthy run

1 index_status — PASS
  root c:\…\your-project · indexed: 248 files / 8,379 symbols / 58,475 refs
  db ~/.prometheus/<hash>.db · autoIndex.managed=true, allowedForThisRoot=true
  embeddings: provider=prometheus, reachable=true
2 search_code — PASS
  "how does the app avoid US cloud providers for data sovereignty"
  → embed/actions.ts updateAllowedOrigins · provenance vector 0.0127 (lexical/graph 0)
  → the hit came from the dense path alone — semantic search is live
3 memory_status + round-trip — PASS
  installed=true, rule claude-code installed; memory_write → memory_list round-trips
4 config blocks — PASS
  CLAUDE.md contains the prometheus-memory and prom-saver blocks
Result: 4/4 PASS

The decisive signal is step 2 with vector > 0: it proves the embedding proxy produced vectors and that retrieval is using them. A query with no word overlap that still finds the right symbol can only have matched semantically.

Re-indexing on demand

If step 1 shows files indexed but step 2 only ever returns lexical/graph hits (vector always 0), the index has no usable vectors. The usual causes:

the index was first built with an invalid/placeholder key (the embedder returned 401, so search degraded silently to lexical + graph), or
you switched the embedding provider, so the stored vectors are from a different embedding space.

Fix the key/provider, then ask the agent to re-index — no window reload and no deleting any database by hand:

Reindex this project.            ← incremental: embeds only the new/changed
                                    symbols that are missing a vector (fast)

For a provider switch (or to repair a partial index), force a full re-embed, which clears the snapshot and re-embeds every symbol:

Reindex this project with force.

This calls the reindex tool (@prom.codes/context-mcp 0.5.0+) — see MCP tools → reindex. It re-scans every file (entries for files deleted on disk are removed) and runs the embedding pass; the pass is checkpoint-bounded, so a large index can never leave a runaway write-ahead-log file.