Semantic Search and File Search

This page covers two search endpoints that are easy to confuse with memory search:

• POST /v1/search/files
• POST /v1/search/semantic

They do not search stored RetainDB memory. They search the documents you send right now or the local path you point them at.

When to use these endpoints

Use POST /v1/search/files when:

• you want keyword or filename matches
• you know the symbol, string, or pattern you are looking for
• you are searching a local codebase or directory

Use POST /v1/search/semantic when:

• you want meaning-based search
• you have a list of document snippets, file summaries, or code chunks
• you want relevant candidates without pre-indexing

If you want persistent search across stored project memory, use memory search instead.

POST /v1/search/files

Request

{
  "query": "auth middleware",
  "path": "/workspace/app",
  "mode": "both",
  "file_types": ["ts", "tsx"],
  "max_results": 20,
  "context_lines": 2,
  "case_sensitive": false
}

Important fields:

• query: the text or pattern to search for
• path: optional root directory; defaults to CODEBASE_PATH or the current working directory
• mode: content, filename, or both
• file_types: optional extension filter

Response

{
  "results": [],
  "total_files": 0,
  "total_matches": 0,
  "search_path": "/workspace/app",
  "mode": "both",
  "latency_ms": 18,
  "engine": "ripgrep"
}

RetainDB uses ripgrep when it is available and falls back to a Node-based search when it is not.

POST /v1/search/semantic

Request

{
  "query": "authentication and session management",
  "documents": [
    {
      "id": "src/auth.ts",
      "content": "Creates session cookies and validates JWT access tokens..."
    },
    {
      "id": "src/payments.ts",
      "content": "Handles subscription billing events and invoice retries..."
    }
  ],
  "top_k": 5,
  "threshold": 0.2
}

Important fields:

• documents: between 1 and 500 documents
• each document needs an id and a trimmed content string
• top_k defaults to 10
• threshold defaults to 0.2

Response

{
  "results": [
    {
      "id": "src/auth.ts",
      "score": 0.912,
      "content": "Creates session cookies and validates JWT access tokens...",
      "snippet": "Creates session cookies and validates JWT access tokens..."
    }
  ],
  "total_searched": 2,
  "total_returned": 1,
  "query": "authentication and session management",
  "latency_ms": 63,
  "cache": "miss"
}

Good defaults

• For search/files, start with mode: "both" and a short query
• For search/semantic, send summaries or chunks, not full giant files
• Keep top_k small at first so the results are easy to inspect
• Treat threshold as recall control: lower finds more, higher is stricter

Common mistakes

Treating these like memory APIs

These endpoints do not know anything about project, user_id, or stored memory unless you send the relevant content in the request itself.

Sending too much text

/v1/search/semantic is better when you pre-trim documents into relevant chunks or summaries. Sending full files makes ranking noisier and costs more work.

Searching the wrong path

For /v1/search/files, a bad path returns a 400. If results look suspiciously empty, confirm the search root first.

What to expect

• /v1/search/files is usually the fastest way to find exact strings
• /v1/search/semantic is slower than text search but better for intent-based discovery
• semantic search responses may return cache: "hit" on repeated identical requests

Next step

If you want persistence and user or session scoping, switch to memory search. If you want the MCP equivalents for live code exploration, continue to semantic search tools.