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.