Search Modes

Goal

Know which search command to use and when — keyword, hybrid, or direct — so every lookup is fast and returns the right result.

What the User Gets

Without this: the agent fumbles between search commands, returns chunks when full pages are needed, runs expensive semantic searches when a direct get would do, or misses results entirely. With this: every lookup uses the optimal mode, token budgets are respected, and the user gets the right information in the fewest calls.

Implementation

on user_asks_about(topic):
    # Decision tree: pick the right search mode

    if know_exact_slug(topic):
        # MODE 3: Direct get -- instant, no search overhead
        result = modusbrain get <slug>
        # e.g., "Tell me about Pedro" -> modusbrain get pedro-franceschi
        # Returns the FULL page -- compiled truth + timeline

    elif topic.is_exact_name or topic.is_keyword:
        # MODE 1: Keyword search -- fast, no embeddings needed, day-one ready
        results = modusbrain search "{name_or_keyword}"
        # e.g., "Find anything about Series A" -> modusbrain search "Series A"
        # Returns CHUNKS, not full pages

        # IMPORTANT: keyword search returns chunks
        # If the chunk confirms relevance, THEN load the full page:
        if chunk.confirms_relevance:
            full_page = modusbrain get <slug_from_chunk>

    elif topic.is_semantic_question:
        # MODE 2: Hybrid search -- semantic + keyword, needs embeddings
        results = modusbrain query "{natural language question}"
        # e.g., "Who do I know at fintech companies?" -> modusbrain query "fintech contacts"
        # Returns ranked chunks via vector + keyword + RRF

        # Same rule: chunks first, then get full page if needed
        if chunk.confirms_relevance:
            full_page = modusbrain get <slug_from_chunk>

# Quick reference:
# | Mode    | Command              | Needs Embeddings | Speed   | Best For                        |
# |---------|----------------------|------------------|---------|---------------------------------|
# | Keyword | modusbrain search "term" | No               | Fastest | Known names, exact matches      |
# | Hybrid  | modusbrain query "..."   | Yes              | Fast    | Semantic questions, fuzzy match  |
# | Direct  | modusbrain get <slug>    | No               | Instant | When you know the slug          |

# Progression over time:
#   Day 1:  keyword search (works without embeddings)
#   After first embed: hybrid search unlocked
#   Once you know slugs: direct get for speed

# Precedence for conflicting information within a page:
#   1. User's direct statements (always wins)
#   2. Compiled truth sections (synthesized from evidence)
#   3. Timeline entries (raw signal, reverse chronological)
#   4. External sources (web search, APIs)

Tricky Spots

Search returns chunks, not full pages. After modusbrain search or modusbrain query, you get excerpts. Always run modusbrain get <slug> to load the full page when the chunk confirms relevance. Don’t answer questions from chunks alone when the full context matters.
Keyword search works without embeddings. On day one before any embedding run, modusbrain search still works. Don’t tell the user “search isn’t available yet” — keyword search is always available.
Don’t use hybrid search for known names. modusbrain query "Pedro Franceschi" wastes embedding compute. Use modusbrain search "Pedro Franceschi" or better yet modusbrain get pedro-franceschi if you know the slug.
Token budget awareness. A full page via modusbrain get can be large. Read the search chunks first to confirm relevance before pulling the full page. “Did anyone mention the Series A?” — search results (chunks) are probably enough. “Tell me everything about Pedro” — get the full page.
Hybrid search needs embeddings to have been run. If modusbrain query returns nothing but modusbrain search finds results, the embeddings haven’t been generated yet. Run the embedding pipeline first.

How to Verify

Run modusbrain search "Pedro" — confirm it returns chunks with matching text and slug references.
Run modusbrain query "who works at fintech companies" — confirm it returns semantically relevant results (not just keyword matches on “fintech”).
Run modusbrain get pedro-franceschi — confirm it returns the full page with compiled truth and timeline.
Compare: search for the same entity using all three modes. Keyword should be fastest, hybrid should surface conceptual matches, direct should return the complete page.
After a search returns a chunk, run modusbrain get on the slug from that chunk. Confirm the full page contains more context than the chunk alone.

Part of the ModusBrain Skillpack.

Core Concepts

Knowledge Ingestion

Agent Operations

Search Modes

Search Modes

Goal

What the User Gets

Implementation

Tricky Spots

How to Verify

​Search Modes

​Goal

​What the User Gets

​Implementation

​Tricky Spots

​How to Verify

Search Modes

Goal

What the User Gets

Implementation

Tricky Spots

How to Verify