Search

NeuralRepo offers two search modes that work together to help you find ideas quickly, whether you remember the exact wording or just the general concept.

Search Modes

Semantic Search

Uses vector similarity powered by Cloudflare Vectorize and the @cf/baai/bge-m3 embedding model. Your query is converted into an embedding and compared against stored idea embeddings. Results are ranked by relevance score and reranked for quality.

Searching for “mobile habit tracker” will surface an idea titled “daily routine app for iOS” even though the words do not overlap.

Keyword Search

Uses SQLite FTS5 full-text search for exact word matching. Fast and precise when you know the specific terms you are looking for.

Searching for “React” returns only ideas that literally contain the word “React.”

Note

Free-tier users get 10 semantic searches per calendar month, counted in UTC and reset on the 1st. When the limit is reached, searches fall back to keyword mode with a notice in the response. Pro users have unlimited semantic search. The counter increments when the search starts, so a semantic search that matches nothing still spends one.

Default Behavior — and Where the Fallback Actually Is

Searching without a mode runs semantic search. What happens when semantic search finds nothing above the threshold depends on which surface you asked from, and the difference matters:

Surface	No semantic matches
GET /api/v1/ideas/search	Returns an empty result set with search_type: "semantic"
nrepo search	Same — reports 0 results
Web app	Same, until you switch the mode toggle to keyword
Agent tool search_ideas	Falls back to keyword automatically (search_type: "fts_fallback")
MCP search_ideas and code_mode	Falls back to keyword automatically

So the REST API and the CLI do not silently retry — ask for mode=keyword when you know the exact wording. The one automatic fallback everywhere is the free-plan quota: once the ten monthly semantic searches are used, every surface returns keyword results — the REST API and the CLI flag it with semantic_limit_reached: true, and the MCP tool with a notice string.

Searching

Web

Use the search box in the sidebar and pick a mode. Keyword search offers three matching styles — any word, all words, or exact phrase — and the result header names the mode that answered, so you always know which one you are reading.

CLI

# Semantic search
nrepo search "distributed task queue"

# Search: "distributed task queue" (semantic) — 3 results
#
# #42 exploring  ⬡ Background job processing system [backend] (87%)
# #18 captured   ◎ Message queue architecture (74%)
# #7  shipped    ◈ Async worker pattern (62%)

nrepo search has no keyword mode of its own — use the web app or the API for that.

API

# Default — semantic, no keyword fallback
GET /api/v1/ideas/search?q=distributed+task+queue

# Force semantic only (identical to the default)
GET /api/v1/ideas/search?q=distributed+task+queue&mode=semantic

# Force keyword only
GET /api/v1/ideas/search?q=distributed+task+queue&mode=keyword

# Keyword matching style: or (default), and, exact
GET /api/v1/ideas/search?q=task+queue&mode=keyword&fts_mode=and

# Override the score threshold for one request
GET /api/v1/ideas/search?q=task+queue&min_score=0.45

Response:

{
  "results": [
    {
      "id": 42,
      "title": "Background job processing system",
      "body": "...",
      "score": 0.87,
      "status": "exploring",
      "tags": ["backend", "infrastructure"]
    }
  ],
  "search_type": "semantic",
  "query": "distributed task queue"
}

MCP

When connected to Claude AI via MCP, use the search_ideas tool:

"Search my NeuralRepo for ideas about authentication"

Claude will call the search_ideas tool and return matching results within the conversation.

Combining Search with Filters

Search results can be narrowed by combining the query with status and tag filters via the API.

API

GET /api/v1/ideas/search?q=auth&status=building&tag=backend

Search Threshold

The search threshold controls the minimum relevance score for semantic results. Ideas scoring below this threshold are excluded from results.

Setting	Range	Default	Scope
search_threshold	0.1 - 0.9	0.2	Your account, every surface
min_score query parameter	0 - 1	(uses search_threshold)	One API request

• Lower values (e.g., 0.2, the default) cast a wide net, surfacing more potential matches. Raise it if results feel noisy.
• Higher values (e.g., 0.7 or 0.8) return fewer results, only very close matches.

Configure the threshold in your user settings:

# Via API
curl -X PATCH https://neuralrepo.com/api/v1/user/me \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings_json": "{\"search_threshold\": 0.5}"}'

Tip

The default threshold of 0.2 is intentionally permissive so you do not miss relevant results. If searches feel noisy, raise the threshold to 0.5 or higher.

How Semantic Search Works

1. Your query text is sent to the @cf/baai/bge-m3 model running on Cloudflare Workers AI.
2. The model generates a vector embedding representing the meaning of your query.
3. The embedding is compared against your stored idea embeddings in Cloudflare Vectorize. NeuralRepo asks for roughly three times the number of results you want (at least 20, at most 50) so there is room to filter and rerank.
4. Matches scoring at or below the search threshold are dropped, as are archived ideas.
5. A reranking step reorders what survives, and the top limit results are returned.

Idea embeddings are generated asynchronously when an idea is created or updated. There may be a brief delay before a brand-new idea appears in semantic search results. Archiving an idea removes its vector immediately, so a deleted idea stops influencing search and duplicate detection right away.

Next Steps

Duplicate Detection The same embeddings, compared against your five nearest ideas.

Tags Narrow a search by tag, and see how tags get assigned in the first place.

Search API Every query parameter and response field for the search endpoint.

Plans & Pricing How the free plan's 10 semantic searches a month are counted.