find_by_title

Category: tasks
Access: read
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Finds tasks, notes, and entities from a remembered phrase when the exact title is unknown. Scores title, description, notes, project, entity names, observations, and entity types, ranking live work above finished work under the memory_lookup_v2 contract.

Arguments

Required: title_fragment.

Optional: limit.

title_fragment.
limit. Note: Clamped to 1..100 (default 20); candidate pools scale from it internally.

Result

JSON object with matches (task/note entries or entity entries, each carrying score, matched_in, surface_scores, primary_surface, confidence, and ranking_contract_version), count, query, hidden_low_confidence_count, ranking_contract_version, lookup_strategy (fts_prefilter or full_scan_fallback), markdown, and message. A blank fragment returns matches [] with the message Empty title fragment.

Boundaries

Only content inside the caller's project grants is loaded and scored; foreign projects never appear, even as low-confidence hints. Finished entries stay reachable but always rank below live work.

Lifecycle / side effects

Pure read; scoring and ranking leave no trace on the matched content.

Errors

title_fragment is enforced-required at call time (missing input is rejected by validation) even though the display schema carries no required list. Unknown arguments and bad types are rejected (strict validator).

Example

{
  "limit": 5,
  "title_fragment": "Paul pack README"
}

Result shape:

{
  "count": 1,
  "hidden_low_confidence_count": 0,
  "lookup_strategy": "fts_prefilter",
  "matches": [
    {
      "confidence": "high",
      "id": "<uuid>",
      "kind": "task",
      "primary_surface": "title",
      "ranking_contract_version": "memory_lookup_v2",
      "score": 0.9,
      "title": "Draft Paul pack README"
    }
  ],
  "query": "Paul pack README",
  "ranking_contract_version": "memory_lookup_v2"
}