lb_search

Searches all nodes in your knowledge graph. Supports three search modes and optional filters for PARA scope and tags.

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	—	The search query
mode	string	No	—	Search mode: keyword, semantic, or hybrid. Defaults to hybrid at the service layer if omitted.
para_item_id	string	No	—	Restrict results to nodes tagged with this PARA item
tags	string[]	No	—	Restrict results to nodes with all specified tags
top_k	number	No	50	Candidate pool size for semantic/hybrid modes (max 100)
keyword_query	string	No	—	Override the FTS5 query (useful for forcing keyword matches)
semantic_query	string	No	—	Override the vector search query
limit	number	No	20	Number of results to return (1–100)

Response

{
  "data": [
    {
      "id": "abc123",
      "title": "Node title",
      "summary": "Brief summary",
      "tags": ["tag1"],
      "match_provenance": { "keyword": true, "semantic": true, "score": 0.0325 }
    }
  ],
  "total": 50,
  "total_matches": 636,
  "coverage_capped": true,
  "page": 1,
  "per_page": 20
}

• data — array of matching nodes
• total — number of results in the served set (for pagination)
• total_matches — honest lexical match count (≥N match by keyword). Present for hybrid/keyword searches.
• coverage_capped — true when matches exceed the candidate pool (total_matches > poolK), indicating recall is limited
• match_provenance — per-result provenance showing which index(es) matched: { keyword: boolean, semantic: boolean, score: number }. Present on hybrid search results.

Search modes

Mode	Description
keyword	Full-text search using SQLite FTS5. Exact and prefix matches. Fast.
semantic	Vector similarity search using embeddings. Finds conceptually related content even without keyword overlap.
hybrid	Combines keyword and semantic results using Reciprocal Rank Fusion (RRF). Best overall recall. Default.

Filter behavior

Filter enforcement varies by mode:

• keyword mode — para_item_id and tags filters are applied strictly at the database level. Only nodes matching all filters are returned.
• semantic and hybrid modes — filters are best-effort. The vector index does not support hard filtering, so results are filtered post-retrieval. Fewer results than limit may be returned even when more matching nodes exist.

When precise filter enforcement is required, use keyword mode.