​

Brain-First Lookup Protocol

​

Goal

​

What the User Gets

​

Implementation

lookup(name_or_topic):
  // STEP 1: Keyword search (fast, works day one, no embeddings needed)
  results = modusbrain search "{name_or_topic}"
  if results.length > 0:
    page = modusbrain get {results[0].slug}
    return page  // done, brain had it

  // STEP 2: Hybrid search (needs embeddings, finds semantic matches)
  results = modusbrain query "what do we know about {name_or_topic}"
  if results.length > 0:
    page = modusbrain get {results[0].slug}
    return page

  // STEP 3: Direct slug (if you know or can guess the slug)
  page = modusbrain get "people/{slugify(name_or_topic)}"
  if page: return page

  // STEP 4: External API (FALLBACK ONLY)
  // Only reach here if brain has nothing
  return external_search(name_or_topic)

​

Why Brain First

• Relationship history (how you know them, what you discussed)
• Your own assessments (what you think of them, not their LinkedIn bio)
• Meeting transcripts (what was said, what was decided)
• Cross-references (who they know, what companies they’re connected to)
• Timeline (what changed recently, what’s trending)

​

Tricky Spots

1. Try keyword first, then hybrid. Keyword search works without embeddings (day one). Hybrid search needs embeddings but finds semantic matches. Try both in sequence.
2. Fuzzy slug matching. modusbrain get supports fuzzy matching. If the exact slug doesn’t exist, it suggests alternatives. Use this for name variants (“Pedro” → “pedro-franceschi”).
3. Don’t skip for “simple” questions. Even “what’s Acme Corp’s address?” should check the brain first. The brain might have it, and the lookup adds no latency (< 100ms for keyword search).
4. Load compiled truth + recent timeline. The compiled truth gives you the state of play in 30 seconds. The timeline gives you what changed recently. Both together = full context.

​

How to Verify

1. Ask about someone in the brain. Verify the agent searched the brain FIRST (check tool call order in the response).
2. Ask about someone NOT in the brain. Verify the agent searched the brain, found nothing, THEN fell back to external search.
3. Ask the same question twice. Second time should be instant (brain has it).