lorekeeper-search

name	lorekeeper-search
description	Search the Lorekeeper knowledge base and provide relevance feedback with confidence ratings. Use when the agent needs to recall domain knowledge, look up facts, or query the memory store. Ensures every search ends with a lore_update feedback call (including confidence) to improve knowledge quality over time.
version	v2.0.0

Lorekeeper Search with Feedback

Lorekeeper is a persistent memory store exposed via MCP tools (lore_search, lore_update, lore_insert). It uses hybrid semantic + keyword search to surface relevant knowledge.

Critical rule: Every lore_search MUST be followed by a lore_update feedback call once the task is complete. This feedback loop — including confidence ratings — keeps the knowledge base accurate and self-correcting.

Workflow

Fresh-news / time-sensitive searches

When the task is about news, releases, or anything that must be recent:

• Search with explicit date anchors and primary-source domains.
• Verify the publish date on every candidate before using it.
• Skip anything older than the requested cutoff or whose date cannot be confirmed.
• Treat aggregators as discovery only; prefer official blogs, docs, GitHub releases, arXiv, and government pages.
• If nothing meets the cutoff, returning nothing is correct.

See references/news-freshness.md for a compact checklist.

Step 1: Search

Call lore_search with a specific natural language query.

lore_search({ query: "voucher stacking rules in checkout", limit: 10, min_score: 0.1 })

• Use natural language questions, not single keywords
• Raise min_score (e.g. 0.3) if results are noisy; lower limit if you need fewer results
• Soft-deleted memories (flagged as unreliable) are excluded by default.
• Filter by recency: created_after / updated_after accept ISO 8601 UTC strings (naive = UTC; non-UTC offsets raise an error). Use to scope searches to a time window, e.g. created_after: "2026-06-01T00:00:00".
• Change sort order: sort_by accepts "relevance" (default, by hybrid score), "recent" (by updated_at DESC), or "frequent" (by usage_count DESC). Composes with timestamp filters and limit.

Step 2: Use the results and verify

Each result contains memory.id, memory.title, memory.content, relevance.combined_score, and links. Each link has its own id, relation_type, reason, source_memory_id, and target_memory_id.

While using the results:

• Track which memories were helpful and verify their factual accuracy
• Assess each link: does the stated relationship (reason) make sense? Does it correctly connect the two memories?

This dual verification informs both memory and link confidence ratings in Step 3.

Step 3: Provide feedback with confidence (MANDATORY)

After completing your task, call lore_update with feedback on every returned memory and every link from those results.

lore_update({
  memory_feedback: [
    { id: "<memory-uuid-1>", useful: true, confidence: 9 },
    { id: "<memory-uuid-2>", useful: false, confidence: 4 },
    { id: "<memory-uuid-3>", useful: false, confidence: 1 }
  ],
  link_feedback: [
    { id: "<link-uuid-1>", useful: true, confidence: 8 },
    { id: "<link-uuid-2>", useful: false, confidence: 3 }
  ]
})

How to get link IDs: Each search result has a links array. Each element has an id field — use that as the link feedback id.

Fields (same semantics for both memories and links):

• useful — whether the memory/link was relevant to the task (for links: whether following the relationship led you to something useful)
• confidence (1–10) — how likely the content/relationship is factually correct:
  • 1–2: Definitely or almost certainly wrong. Memory will be soft-deleted (excluded from future searches).
  • 3–4: Likely incorrect or highly suspect.
  • 5–6: Uncertain — cannot confirm or deny.
  • 7–8: Likely correct based on available evidence.
  • 9–10: Confirmed correct (verified against code, docs, or authoritative source).

Critical: useful and confidence interact — understand the difference before rating:

• False positive (memory appeared but is about an unrelated topic, content is valid): useful: false, confidence: 7–9 → ranking penalty only, memory is NOT deleted
• Wrong/stale content (the memory itself contains incorrect or outdated facts): useful: false, confidence: 1–2 → memory is soft-deleted
• Correct and on-topic: useful: true, confidence: 7–10 → score boosted
• Uncertain relevance: useful: false, confidence: 5–6 → slight penalty, kept

⚠️ Only use confidence: 1–2 when the content is factually wrong or stale — not simply because it was an irrelevant search result. Using low confidence on a valid-but-off-topic memory will delete it permanently.

Decision Guide

Need domain knowledge or facts?
  ├─ YES → lore_search → use results → verify content → lore_update (always, with confidence)
  └─ NO  → skip Lorekeeper

If search returns zero results, there is nothing to provide feedback on — proceed normally.

Example

1. lore_search({ query: "Python async patterns in service layer" })

2. Results:

   • Memory aaa-111 (async patterns) — relevant, verified correct. Has link lnk-001 → bbb-222 (references, reason: "retry logic depends on async context"). Relationship is valid.
   • Memory bbb-222 (retry logic) — irrelevant to this task, content looks correct. Has link lnk-002 → ccc-333 (part_of, reason: "old sync API used in retry flow"). Old API was removed — link is stale.
   • Memory ccc-333 (old sync API) — outdated info.

3. lore_update({
     memory_feedback: [
       { id: "aaa-111", useful: true, confidence: 9 },
       { id: "bbb-222", useful: false, confidence: 7 },
       { id: "ccc-333", useful: false, confidence: 2 }
     ],
     link_feedback: [
       { id: "lnk-001", useful: true, confidence: 8 },
       { id: "lnk-002", useful: false, confidence: 2 }
     ]
   })
   

   Result: ccc-333 is soft-deleted (confidence ≤ 2, useful=false). lnk-002 score drops toward removal.

Rules

• Never skip feedback — even if no results were useful, mark them all useful: false with a confidence rating
• Always include confidence — this is how the knowledge base self-corrects over time
• Rate links too — collect all link IDs from results[].links[].id and include them in link_feedback
• Link confidence = whether the stated relationship is factually correct; link useful = whether following it led somewhere valuable
• Verify before rating — cross-reference memory content against code, docs, or your own knowledge
• Feedback after task completion — wait until you have used the results before judging usefulness
• Batch into one call — send all feedback in a single lore_update, not one per memory
• Be honest about uncertainty — if you cannot verify, use confidence 5–6 rather than guessing high

Related Skills

• [lorekeeper-protocol] — The full session protocol orchestrating when to search.
• [lorekeeper-memorize] — Companion: search first, then insert new discoveries.
• [lorekeeper-reconcile] — When search returns suspected stale data, run reconcile to fact-check.