Search and retrieval — bRRAIn Docs

Find vault content from an extension with Vault().Search, Vault().Grep and the search_vault MCP tool, and handle degraded results.

Search and retrieval

An extension has three ways to find content in the vault:

| You need | Use | | --- | --- | | An exact token or identifier in text files | Vault().Grep | | A keyword in a folder, simple and predictable | Vault().Search with a short term | | Ranked, case-insensitive results, including PDFs and Office files | The search_vault tool through MCP().Tool |

Vault().Search

type VaultSearchRequest struct {
	Query  string
	Path   string              // scope to a folder
	Limit  int
	Cursor string
	Facets map[string][]string // AND across keys, OR within a key
}

type VaultSearchResponse struct {
	Hits       []VaultSearchHit // Path, Name, Snippet, Score, MIME
	NextCursor string
	Degraded   bool // true: the platform answered with its fallback scan
}

The SDK describes Search as Graph-RAG-powered with a grep fallback. On current brain pods the search route always serves the fallback:

  • every response has Degraded: true;
  • matching is a literal, case-sensitive substring test, line by line, over text files (the first 1 MiB of each);
  • one hit per matching line, so a file can appear several times;
  • every hit has the same Score, so the order says nothing about relevance;
  • Facets and Cursor are not applied and NextCursor is empty;
  • Limit defaults to 50 and is capped at 500.

Write your code against the contract (honor Degraded, follow NextCursor when present) and your queries against the behavior: search for a short, distinctive term, scope by folder, and de-duplicate by path. A natural-language question as the query usually finds nothing.

func FindNotes(ctx context.Context, c *platformsdk.Client, project, term string) ([]platformsdk.VaultSearchHit, bool, error) {
	res, err := c.Vault().Search(ctx, platformsdk.VaultSearchRequest{
		Query: term,                  // a short, distinctive term, not a question
		Path:  "projects/" + project, // scope by folder
		Limit: 50,
	})
	if err != nil {
		return nil, false, err
	}
	return res.Hits, res.Degraded, nil
}

Vault().Grep

Grep takes VaultGrepRequest{Pattern, Path, MaxResults} and returns hits with a Path, a Line number and a Snippet, plus Truncated when it stopped at the limit (default 200, cap 1000). The SDK rejects an empty pattern and negative limits before sending.

func FindDecisionIDs(ctx context.Context, c *platformsdk.Client) (*platformsdk.VaultGrepResponse, error) {
	return c.Vault().Grep(ctx, platformsdk.VaultGrepRequest{
		Pattern:    "DEC-2026-",
		Path:       "decisions-learnings",
		MaxResults: 100,
	})
}

Ranked search with search_vault

The pod's built-in search_vault tool (server brrain) is the search people use from Claude Desktop, the VS Code extension and Nexus. When the pod's full-text index is warm it is case-insensitive by default, returns ranked results, and searches PDFs and Office files through their extracted text, with hits pointing at the original file. It returns at most 20 hits per call. Call it through MCP().Tool; the tool's arguments go inside an args object:

func toolText(ctx context.Context, c *platformsdk.Client, server, tool string, args map[string]any) (string, map[string]any, error) {
	out, err := c.MCP().Tool(ctx, platformsdk.MCPCall{
		Server:    server,
		Tool:      tool,
		Arguments: map[string]any{"args": args}, // tool arguments go inside "args"
	})
	if err != nil {
		return "", nil, err
	}
	text, _ := out["text"].(string)
	if isErr, _ := out["is_error"].(bool); isErr {
		return "", nil, fmt.Errorf("%s/%s: %s", server, tool, text)
	}
	structured, _ := out["structured"].(map[string]any)
	return text, structured, nil
}

func RankedSearch(ctx context.Context, c *platformsdk.Client, query, folder string) (string, error) {
	text, _, err := toolText(ctx, c, "brrain", "search_vault", map[string]any{
		"query": query,
		"path":  folder,
		"limit": 10,
	})
	return text, err
}

text is a readable answer for a person; structured carries the hits as data.

Permissions

Search and tool calls from your extension run as the extension. They are not filtered by the requesting user's project permissions. Scope every search to the folders the user may see, and never return content the user could not open in Nexus.

Next

  • Models: ground model answers in what you found.
  • Examples: a complete grounded-answer function.