feat(bench): add support for reranking and multi-query retrieval

- Introduce Reranker and MultiQuery options in bench.Config
- Implement LLMReranker for retrieving and scoring candidates
- Enhance Search method to utilize reranking and multi-query features
- Update README.md to document new retrieval boosters: rerank and multi-query
- Add tests for the new reranking feature and multi-query expansions

Author: AccursedGalaxy

README.md

@@ -140,6 +140,36 @@ extra LLM call (only when there are facts in scope to reconcile against) plus a
 cheap per-candidate retrieval, and a malformed/failed consolidation response
 safely falls back to an additive insert. See `PLAN-v2.md` §4.2.
 
+### Retrieval boosters: rerank + multi-query
+
+Brute-force cosine over a single query phrasing leaves recall on the table: the
+fact that answers a question often exists but sits just past the top-k cutoff
+(retrieval dilution). Two opt-in `Search` boosters recover it, both leaving the
+public `Search` signature unchanged:
+
+```go
+m, _ := mneme.New(
+    mneme.WithReranker(&openai.LLMReranker{LLM: llm}), // over-retrieve, reorder, keep top-k
+    mneme.WithMultiQuery(3),                            // expand into 3 phrasings, union the hits
+)
+```
+
+- **Rerank** (`WithReranker`): `Search` retrieves a wider pool (`DefaultRerankPoolN`,
+  ~20) instead of just `k`, hands it to the `Reranker` to reorder by relevance,
+  then keeps the leading `k`. The shipped `openai.LLMReranker` scores each
+  candidate with one LLM call and is parse-defensive — a malformed response
+  leaves the cosine order untouched. The `Reranker` interface is tiny, so a
+  cross-encoder or hosted rerank API can drop in later.
+- **Multi-query** (`WithMultiQuery(n)`): one LLM call rewrites the query into up
+  to `n` diverse phrasings; their hits are unioned (deduped by id, best score
+  wins) before reranking. Targets multi-hop questions where one phrasing won't
+  surface every needed fact. Expansion is best-effort: if the call or its parse
+  fails, `Search` falls back to the original query alone.
+
+Each booster adds an LLM call per `Search` — opt in when retrieval accuracy is
+worth the cost. The `bench` harness exposes both as `-rerank` and `-multiquery n`.
+See `PLAN-v2.md` §4.3.
+
 ## Eval harness
 
 The extraction prompt is versioned (`extractionPromptV1`, …) and scored by the

bench/run.go

@@ -50,6 +50,15 @@ type Config struct {
 	// harness A/B prompt versions (e.g. v1 vs the conservative v2).
 	ConsolidationVersion string
 
+	// Reranker, when set, enables a rerank pass in Search (PLAN-v2.md §4.3): the
+	// harness over-retrieves and reorders candidates before truncating to K. Nil
+	// leaves Search at plain top-k cosine.
+	Reranker mneme.Reranker
+
+	// MultiQuery, when > 1, makes Search expand each question into that many
+	// phrasings and union the hits before reranking (PLAN-v2.md §4.3).
+	MultiQuery int
+
 	// Progress, if set, is called after each sample is fully scored. Lets the
 	// runner print live progress without the library writing to stdout.
 	Progress func(doneSamples, totalSamples int)
@@ -93,12 +102,24 @@ func Run(ctx context.Context, samples []Sample, cfg Config) (Report, error) {
 	if cfg.ConsolidationVersion != "" {
 		opts = append(opts, mneme.WithConsolidationVersion(cfg.ConsolidationVersion))
 	}
+	if cfg.Reranker != nil {
+		opts = append(opts, mneme.WithReranker(cfg.Reranker))
+	}
+	if cfg.MultiQuery > 1 {
+		opts = append(opts, mneme.WithMultiQuery(cfg.MultiQuery))
+	}
 	mem, err := mneme.New(opts...)
 	if err != nil {
 		return Report{}, fmt.Errorf("build memory: %w", err)
 	}
 
-	report := Report{K: cfg.K, Strategy: cfg.Strategy, ConsolidationVersion: cfg.ConsolidationVersion}
+	report := Report{
+		K:                    cfg.K,
+		Strategy:             cfg.Strategy,
+		ConsolidationVersion: cfg.ConsolidationVersion,
+		Rerank:               cfg.Reranker != nil,
+		MultiQuery:           cfg.MultiQuery,
+	}
 	for i, s := range samples {
 		results, err := runSample(ctx, mem, answerLLM, judge, cfg, s)
 		if err != nil {

bench/score.go

@@ -37,6 +37,10 @@ type Report struct {
 	// ConsolidationVersion records which consolidation prompt version was used
 	// (empty for additive runs or the library default), for run provenance.
 	ConsolidationVersion string
+	// Rerank records whether a rerank pass was active in Search; MultiQuery
+	// records the query-expansion fan-out (0/1 = off), both for run provenance.
+	Rerank     bool
+	MultiQuery int
 }
 
 // CategoryStat aggregates one category (or the whole run) into mean metrics.

cmd/bench/main.go

@@ -23,6 +23,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/AccursedGalaxy/mneme"
 	"github.com/AccursedGalaxy/mneme/bench"
 	"github.com/AccursedGalaxy/mneme/provider"
 	"github.com/AccursedGalaxy/mneme/provider/fake"
@@ -49,6 +50,8 @@ func run() error {
 		k         = flag.Int("k", 5, "search top-k facts fed to the answer model")
 		strategy  = flag.String("strategy", bench.StrategyAdditive, "write strategy: additive | consolidate")
 		cprompt   = flag.String("cprompt", "", "consolidation prompt version (e.g. v1 | v2); empty = library default. Only used with -strategy consolidate")
+		rerank    = flag.Bool("rerank", false, "enable the LLM rerank pass in Search (over-retrieve, reorder, truncate to k)")
+		multiQ    = flag.Int("multiquery", 0, "if >1, expand each question into this many search phrasings and union the hits before reranking")
 		limit     = flag.Int("limit", 0, "if >0, run only the first N samples (smoke test)")
 		maxQ      = flag.Int("maxq", 0, "if >0, cap questions per sample (smoke/cost control)")
 		out       = flag.String("out", "bench/RESULTS.md", "results file to write (markdown); empty to skip")
@@ -113,13 +116,20 @@ func run() error {
 	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Hour)
 	defer cancel()
 
+	var reranker mneme.Reranker
+	if *rerank {
+		reranker = &openai.LLMReranker{LLM: llm}
+	}
+
 	report, err := bench.Run(ctx, samples, bench.Config{
 		LLM:                  llm,
 		Embedder:             embedder,
 		Store:                st,
 		K:                    *k,
 		Strategy:             *strategy,
 		ConsolidationVersion: *cprompt,
+		Reranker:             reranker,
+		MultiQuery:           *multiQ,
 		Progress: func(done, total int) {
 			fmt.Fprintf(os.Stderr, "\r  scored %d/%d samples", done, total)
 			if done == total {
@@ -144,6 +154,8 @@ func run() error {
 		maxQ:     *maxQ,
 		samples:  len(samples),
 		cprompt:  *cprompt,
+		rerank:   *rerank,
+		multiQ:   *multiQ,
 	})
 	fmt.Print(md)
 
@@ -211,6 +223,8 @@ type runMeta struct {
 	dataset, path, model, embedder string
 	limit, maxQ, samples           int
 	cprompt                        string // consolidation prompt version, if set
+	rerank                         bool   // rerank pass active in Search
+	multiQ                         int    // multi-query fan-out (0/1 = off)
 }
 
 // render builds the human + markdown report: a per-category table (the lever
@@ -225,6 +239,12 @@ func render(report bench.Report, m runMeta) string {
 	if m.cprompt != "" {
 		fmt.Fprintf(&b, "  ·  cprompt: `%s`", m.cprompt)
 	}
+	if m.rerank {
+		fmt.Fprintf(&b, "  ·  rerank: `on`")
+	}
+	if m.multiQ > 1 {
+		fmt.Fprintf(&b, "  ·  multiquery: `%d`", m.multiQ)
+	}
 	b.WriteString("\n\n")
 	fmt.Fprintf(&b, "Metrics: **EM** = normalized exact match, **F1** = token-overlap F1, **Judge** = LLM semantic match. n = question count.\n\n")
 
@@ -255,6 +275,12 @@ func render(report bench.Report, m runMeta) string {
 	if m.cprompt != "" {
 		fmt.Fprintf(&b, " -cprompt %s", m.cprompt)
 	}
+	if m.rerank {
+		fmt.Fprintf(&b, " -rerank")
+	}
+	if m.multiQ > 1 {
+		fmt.Fprintf(&b, " -multiquery %d", m.multiQ)
+	}
 	if m.limit > 0 {
 		fmt.Fprintf(&b, " -limit %d", m.limit)
 	}

memory.go

@@ -84,6 +84,8 @@ type memory struct {
 	consolidationVersion  string
 	clock                 func() time.Time
 	allowEmbedderMismatch bool
+	reranker              Reranker
+	multiQueryN           int
 }
 
 var _ Memory = (*memory)(nil)

parse.go

@@ -129,6 +129,49 @@ func cleanOps(ops []consolidationOp) []consolidationOp {
 	return out
 }
 
+// queryEnvelope is the documented multi-query expansion response shape:
+// {"queries":["...","..."]}.
+type queryEnvelope struct {
+	Queries []string `json:"queries"`
+}
+
+// parseQueries pulls the expansion list out of a raw multi-query response
+// defensively, mirroring parseExtraction (fences, embedded object, bare array).
+// On any unrecoverable failure it returns nil, so Search falls back to the
+// original query alone rather than erroring.
+func parseQueries(raw string) []string {
+	s := stripFences(raw)
+
+	var env queryEnvelope
+	if err := json.Unmarshal([]byte(s), &env); err == nil && env.Queries != nil {
+		return cleanQueries(env.Queries)
+	}
+	if obj := firstBalanced(s, '{', '}'); obj != "" {
+		if err := json.Unmarshal([]byte(obj), &env); err == nil && env.Queries != nil {
+			return cleanQueries(env.Queries)
+		}
+	}
+	if arr := firstBalanced(s, '[', ']'); arr != "" {
+		var qs []string
+		if err := json.Unmarshal([]byte(arr), &qs); err == nil {
+			return cleanQueries(qs)
+		}
+	}
+	return nil
+}
+
+// cleanQueries trims each query and drops empties, so a sloppy model response
+// does not produce blank search phrasings.
+func cleanQueries(qs []string) []string {
+	out := make([]string, 0, len(qs))
+	for _, q := range qs {
+		if q = strings.TrimSpace(q); q != "" {
+			out = append(out, q)
+		}
+	}
+	return out
+}
+
 // clean drops items with empty text and trims surrounding whitespace, so a
 // model that emits {"text":""} or stray spaces does not create junk facts.
 func clean(facts []extractedFact) []extractedFact {

pipeline.go

@@ -278,21 +278,37 @@ func (m *memory) consolidate(ctx context.Context, scope Scope, existing []labele
 
 // Search embeds the query and returns the top-k facts in scope by cosine
 // similarity, Score populated, highest first.
+//
+// With a reranker (WithReranker) or multi-query (WithMultiQuery) configured it
+// over-retrieves a wider pool (DefaultRerankPoolN per phrasing), unions and
+// reorders it, then keeps the leading k — recovering answer facts that raw
+// cosine dilutes past the cutoff. The public signature is unchanged; with no
+// booster the result is identical to plain top-k cosine.
 func (m *memory) Search(ctx context.Context, query string, scope Scope, k int) ([]Fact, error) {
 	if strings.TrimSpace(query) == "" || k <= 0 {
 		return nil, nil
 	}
-	qvec, err := m.embedOne(ctx, query)
-	if err != nil {
-		return nil, fmt.Errorf("embed query: %w", err)
+
+	queries := m.searchQueries(ctx, query)
+	poolN := k
+	if m.reranker != nil || len(queries) > 1 {
+		poolN = rerankPoolN(k)
 	}
-	hits, err := m.store.Search(ctx, scope, qvec, k)
+
+	facts, err := m.gatherCandidates(ctx, queries, scope, poolN)
 	if err != nil {
-		return nil, fmt.Errorf("search: %w", err)
+		return nil, err
 	}
-	facts := make([]Fact, len(hits))
-	for i, h := range hits {
-		facts[i] = recordToFact(h.Record, h.Score)
+
+	if m.reranker != nil && len(facts) > 1 {
+		facts, err = m.reranker.Rerank(ctx, query, facts)
+		if err != nil {
+			return nil, fmt.Errorf("rerank: %w", err)
+		}
+	}
+
+	if len(facts) > k {
+		facts = facts[:k]
 	}
 	return facts, nil
 }