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.

1. ```

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.