Retrieval API

Input

{
  "prompt": "Fix UI and validate in browser",
  "provider": "codex",
  "cwd": "/path/to/project",
  "limit": 4,
  "budget": {
    "maxChars": 6000
  }
}

Task Envelope

{
  "summary": "Fix UI and validate in browser",
  "language": "en",
  "taskTypes": ["ui"],
  "surfaces": ["ui"],
  "risks": [],
  "operations": ["fix"],
  "constraints": [],
  "files": [],
  "commands": [],
  "intentModes": ["execute"],
  "ruleSignals": [
    {
      "id": "explicit_execute",
      "polarity": "positive",
      "weight": 8,
      "reason": "explicit execution wording"
    },
    {
      "id": "ui_surface",
      "polarity": "positive",
      "weight": 8,
      "reason": "UI, frontend, or browser surface wording"
    }
  ],
  "keywords": ["UI", "browser", "validate"],
  "negativeKeywords": [],
  "segments": ["Fix UI and validate in browser"],
  "length": 30
}

Match Output

{
  "rank": 1,
  "id": "browser-validation",
  "title": "Browser Validation",
  "score": 82,
  "rawScore": 12.4,
  "rankScore": 32.1,
  "postSelectionScore": 82,
  "evidenceFamilies": ["triggers", "signals"],
  "strongAnchor": true,
  "recallPolicy": "must",
  "risk": "high",
  "confidence": "high",
  "summary": "Open the real browser after UI changes.",
  "card": {
    "libraryScope": "project"
  },
  "reasons": [
    { "field": "triggers", "term": "browser validation", "weight": 52, "kind": "phrase-exact" },
    { "field": "ruleSignals", "term": "ui_surface", "weight": 48, "kind": "UI, frontend, or browser surface wording" }
  ],
  "similarCards": []
}

Cards whose active-card scope does not match the detected projectContext are filtered out before scoring.

The CLI explain surface wraps the same data with envelope and query diagnostics:

ome match "Fix UI and validate in browser" --explain --json

{
  "ok": true,
  "threshold": 40,
  "limit": 4,
  "diagnostics": {
    "engineVersion": "sparse-v2",
    "scorerVersion": "bm25f-evidence-v2",
    "threshold": 40,
    "limit": 4,
    "inputCardCount": 1,
    "applicableCardCount": 1,
    "evaluatedCardCount": 1,
    "timedOut": false,
    "complete": true,
    "candidateListTruncated": false,
    "abstained": false,
    "abstainReason": null,
    "selectedCardIds": ["browser-validation"],
    "candidates": [
      {
        "id": "browser-validation",
        "libraryScope": "project",
        "score": 82,
        "rawScore": 12.4,
        "rankScore": 32.1,
        "postSelectionScore": 82,
        "priorityScore": 7,
        "evidenceFamilies": ["triggers", "signals"],
        "strongAnchor": true,
        "eligible": true,
        "selected": true,
        "rejectionReason": null,
        "reasons": []
      }
    ]
  },
  "queryVariants": ["Fix UI and validate in browser", "ui test browser validate"],
  "projectContext": {
    "projectKey": "github.com/example/app",
    "modulePath": "apps/web",
    "source": "git"
  },
  "libraries": [
    { "scope": "global", "exists": true, "readable": true },
    { "scope": "project", "exists": true, "readable": true }
  ],
  "matches": [
    {
      "rank": 1,
      "id": "browser-validation",
      "score": 82,
      "rawScore": 12.4,
      "rankScore": 32.1,
      "postSelectionScore": 82,
      "evidenceFamilies": ["triggers", "signals"],
      "strongAnchor": true,
      "card": {
        "libraryScope": "project"
      },
      "reasons": [
        { "field": "ruleSignals", "term": "ui_surface", "weight": 48, "kind": "UI, frontend, or browser surface wording" }
      ],
      "similarCards": [
        {
          "id": "browser-validation-overlap",
          "title": "Browser smoke checklist",
          "score": 82,
          "reason": "title, triggers, or topics are highly similar"
        }
      ]
    }
  ],
  "additionalContext": "# OME Matched Experience Cards\\n\\nMatched cards are optional reminders, not required reuse.\\n- Choice: You may apply a whole card, use only the useful parts, or ignore any match that does not fit the task.\\n- Before acting: If a card helps, say one short sentence about what OME reminded you to consider, then proceed.\\n- Final: If any card was used, state how many cards were used and include only the applied `Final link if used` values; omit this line if none.\\n..."
}

libraries describes the global/project library stack used for the match. Project cards include libraryScope: project; their rendered full-card command uses ome experience show CARD_ID --scope project --section rule.

similarCards lists near-duplicates that were omitted from the ranked output. The renderer can mention them as omitted related cards, but it should not inject duplicate full lessons.

Score fields have separate contracts:

• score is the corpus-size-stable 0-100 evidence score used for the configured threshold;
• rawScore is the BM25F sparse value used only as a ranking channel;
• rankScore is the deterministic reciprocal-rank-fusion result;
• postSelectionScore is the evidence score after the selection pipeline;
• priorityScore appears in candidate diagnostics as a non-relevance tie-breaker derived from card metadata.

diagnostics makes rejection and abstention inspectable without logging a raw prompt. It reports the retrieval versions, counts, completeness, selected ids, and a bounded candidate list. candidateListTruncated explicitly says whether that list omitted rows while evaluatedCardCount retains the total. Rejected candidates retain rejectionReason and positive/negative reasons. When no candidate clears the evidence contract, abstained is true and matches is empty; the engine does not fill the limit with weak cards.

ruleSignals are registered internal recall hints derived from the prompt. Positive engine hints provide evidence or routing gates; negative hints suppress only their declared targets. They are heuristic signals, not the final usage standard. Hook context renders natural-language criteria and match reasons instead of exposing hint ids.

additionalContext uses a fixed English instruction frame and contains only compact index information. Card rule bodies are not injected. Matched cards are optional reminders, not proof that the agent used them. The frame gives the agent choice: apply a whole card, use useful parts, or ignore matches that do not fit. The agent should fetch the rule only when a card applies, and mention only cards it actually used in the final response. That disclosure line should state the number of OME experience cards used and include only the rendered Final link if used values. Card titles are rendered as Markdown links to the relevant experience card paths.

Budgeted Context

{
  "cards": ["browser-validation"],
  "additionalContext": "...",
  "truncated": false,
  "budgetUsedChars": 1200
}