trusty-search

trusty-search

Hybrid semantic + lexical + relational code search. Replaces mcp__mcp-vector-search__* tools.

When to Use

• Locate code: "Where is X defined?" / "How is X used?"
• Explore concepts: "How does the migration system work?"
• Find tech debt: "Where are the TODOs / FIXMEs?"
• Q&A over codebase: Use chat for synthesized answers with citations.

Do NOT use for: persistent memory (use trusty-memory), edits (use Edit), or shell-level file listing.

Architecture

• Single daemon at http://127.0.0.1:7878 serves all projects.
• Named indexes — one per project: claude-mpm, cto, duetto, open-mpm, rust-dre, etc.
• Hybrid retrieval:
  • BM25 — lexical/keyword precision
  • HNSW — vector semantic similarity
  • KG — knowledge graph relational signals
  • Fused with Reciprocal Rank Fusion (RRF)

Query Type Routing

search_code accepts a query_type hint that biases the fusion weights. Always specify it.

query_type	Use For	Bias
Definition	"Where is run_pending_migrations defined?"	BM25 precision
Usage	"How is the planner agent invoked?"	Vector similarity
Conceptual	"How does the migration system work?"	Balanced BM25+vector+KG
BugDebt	"Show me the TODOs / hacks"	Keyword match

If unspecified, the daemon auto-routes — but explicit is better.

Tool Reference

Search

search_code — primary tool.

mcp__trusty-search__search_code(
  query="migration registry",
  index="claude-mpm",
  query_type="Definition",
  limit=10
)

chat — LLM-powered Q&A over the index with citations.

mcp__trusty-search__chat(
  index="claude-mpm",
  question="How does the hook dispatcher route PreToolUse events?"
)

Index Management

mcp__trusty-search__list_indexes()
mcp__trusty-search__create_index(name="new-project", root="/abs/path")
mcp__trusty-search__delete_index(name="old-project")
mcp__trusty-search__index_status(index="claude-mpm")
mcp__trusty-search__reindex(index="claude-mpm")
mcp__trusty-search__index_file(index="claude-mpm", path="src/foo.py")
mcp__trusty-search__remove_file(index="claude-mpm", path="src/old.py")

Health

mcp__trusty-search__search_health()
# Returns daemon liveness + uptime.

When to Use search_code vs chat

Need	Tool
List of matching files/symbols	search_code
Quick lookup, then read source	search_code
Synthesized explanation across many files	chat
Citations and a narrative answer	chat
Bulk grep replacement	search_code with query_type="Definition"

search_code is cheap; chat is more expensive. Prefer search_code + targeted Read when feasible.

Index Health Workflow

# 1. Confirm daemon up
search_health()

# 2. Confirm index registered and healthy
index_status(index="claude-mpm")

# 3. If stale or recently changed many files:
reindex(index="claude-mpm")

# 4. For single-file invalidation after edit:
index_file(index="claude-mpm", path="src/claude_mpm/foo.py")

If search_health fails: the daemon is not running. Start it externally (trusty-search serve). The MCP transport assumes the daemon is already serving.

Example Calls

Definition lookup

search_code(
  query="run_pending_migrations",
  index="claude-mpm",
  query_type="Definition",
  limit=5
)

Conceptual exploration

search_code(
  query="how hooks get dispatched after tool use",
  index="claude-mpm",
  query_type="Conceptual",
  limit=15
)

Tech debt audit

search_code(
  query="TODO FIXME XXX HACK",
  index="claude-mpm",
  query_type="BugDebt",
  limit=50
)

Q&A

chat(
  index="claude-mpm",
  question="What invariants does the migration registry enforce on migration IDs?"
)

Integration with trusty-memory

Search → understand → remember. After investigation, persist learnings.

# 1. Find code
search_code(query="model_tier_hook", index="claude-mpm", query_type="Definition")

# 2. Read and understand the code (use Read tool)

# 3. Persist the learning
mcp__trusty-memory__memory_remember(
  content="model_tier_hook enforces planner→claude-opus-4-7 routing; config at ~/.claude-mpm/config/configuration.yaml models.planning",
  room="Backend",
  tags=["hooks", "model-tier", "planner"],
  importance=0.8
)

# 4. Optionally assert relationship in KG
mcp__trusty-memory__kg_assert(
  subject="model_tier_hook",
  predicate="enforces",
  object="planner-model-routing"
)

Migration from mcp-vector-search

Old	New
mcp__mcp-vector-search__search_code	mcp__trusty-search__search_code
mcp__mcp-vector-search__index_project	mcp__trusty-search__create_index + reindex
mcp__mcp-vector-search__get_project_status	mcp__trusty-search__index_status
mcp__mcp-vector-search__search_similar	search_code with query_type="Usage"
mcp__mcp-vector-search__search_context	search_code with query_type="Conceptual" or chat
mcp__mcp-vector-search__search_hybrid	search_code (hybrid is default)

Best Practices

• Always pass index: the daemon hosts many projects; omitting index is ambiguous.
• Specify query_type: it materially improves ranking.
• Start narrow: limit=10 for search_code, then expand if needed.
• Reindex sparingly: full reindex is expensive — prefer index_file for single-file updates.
• Verify before claiming: check search_health if results seem stale or empty.
• Pair with memory: search to find, memory to remember.