Semantic Search Tools

RetainDB MCP exposes several search tools that sound similar but solve different problems.

Start with the primary verbs

If you are choosing quickly:

• exact text or filename lookup: grep
• meaning-based codebase exploration in the live workspace: search_code
• open a hit after search: read
• browse before searching: explore
• stored project retrieval: search

The namespaced equivalents

These are the underlying advanced tools:

• grep -> code.search_text
• search_code -> code.search_semantic
• search is the primary retrieval verb; use context.query when you want the explicit namespaced retrieval surface
• for ranking an in-memory document set, use code.semantic_documents

grep

Use this when you already know the string, symbol, or filename you want.

Best for:

• finding a function name
• matching an error string
• locating files by filename
• quick repo-wide grep behavior

Example:

{
  "query": "TODO",
  "path": "/workspace/app",
  "mode": "content",
  "file_types": ["ts", "tsx"],
  "max_results": 20
}

search_code

Use this when you know the idea you want, not the exact text.

Best for:

• "where is authentication handled?"
• "find retry logic"
• "show me session management"
• exploring an unfamiliar codebase

Canonical mapping: search_code -> code.search_semantic

search_code stays index-free. It searches the local repo directly, broadens the semantic candidate pass before falling back, and returns workspace diagnostics so you can tell whether indexed RetainDB retrieval is healthy, stale, unbound, or using lexical rescue.

Example:

{
  "query": "authentication and session management",
  "path": "/workspace/app",
  "file_types": ["ts", "tsx"],
  "top_k": 8,
  "threshold": 0.2,
  "max_files": 150
}

code.semantic_documents

Use this when you already have the documents and just want RetainDB to rank them semantically.

Best for:

• ranking a custom set of notes or snippets
• re-ranking chunks you produced elsewhere
• toolchains where you do not want RetainDB to scan the filesystem directly

Example:

{
  "query": "database connection pooling",
  "documents": [
    {
      "id": "src/db.ts",
      "content": "Creates pooled Postgres clients and retries idle disconnects..."
    },
    {
      "id": "src/auth.ts",
      "content": "Validates JWT tokens and rotates session cookies..."
    }
  ],
  "top_k": 5,
  "threshold": 0.3
}

Which tool to pick first

Use this order:

1. grep if you know the exact term
2. search_code if you only know the concept
3. code.semantic_documents if the candidate documents are already in hand
4. search if what you really want is indexed RetainDB project context rather than local workspace search

Common mistakes

Using semantic code search for an exact identifier

If you know the symbol name, grep is usually faster and cleaner.

Expecting local search tools to search stored project knowledge

For indexed RetainDB context, use search or the explicit namespaced retrieval tools.

Ignoring workspace diagnostics

If search_code warns that the workspace is stale, drifted, or unbound, trust the local code hits first. If project-backed retrieval also says the repo source is missing or unverified, ingest a real local/GitHub source before treating stored retrieval as authoritative.

Reading too early

Use search_code or grep first, then read the best hit instead of opening files blindly.

Next step

If you have not configured RetainDB MCP yet, start with setup tools. If you want the HTTP routes behind these tools, read semantic search and file search.