@cairnkeep/cli 2.22.5 → 2.23.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.23.0] - 2026-10-21
+
+### Memory retrieval
+
+- Add opt-in `memory_search` hybrid lexical/identifier admission, bounded query
+  aliases, explicit semantic-only thresholds, deterministic ranking, duplicate
+  source locators and optional conflict/match explanations. Preserve existing
+  default responses, history, scope filters and storage layouts. Fall back to
+  lexical admission when optional embedding results are invalid or unavailable.
+- Add a frozen continuity study against real curated Markdown files, including
+  the same-policy Markdown parity control and 0/100/1,000 distractors. Document
+  synthetic limitations and unsuccessful live-provider evaluation; update the
+  agent guidance, learning lesson and recording supplement.
+
+### CI
+
+- Allow a retried, fully gated CI job to replace its run-local tree-addressed
+  release candidate instead of failing on the existing artifact name. Keep all
+  platform/runtime dependencies and immutable published versions unchanged; add
+  parsed-workflow positive and mutation controls.
+
 ## [2.22.5] - 2026-10-08
 
 ### Operations

package/claude/commands/recall.md

@@ -19,7 +19,14 @@ Read order (canonical sources still win over derived layers):
 
 <process>
 ## 1. AgentFS
-`memory_search` scope `project` with $ARGUMENTS. If nothing relevant, retry scope `all`.
+`memory_search` scope `project` with $ARGUMENTS. When the discovered schema
+supports it, use `strategy: "hybrid"` for identifier-sensitive or mixed-wording
+queries and `explain: true` to inspect matches. Supply only aliases already known
+from the task. Semantic-only hybrid matches require an explicitly chosen
+positive `min_score`; retain the existing semantic strategy for paraphrases
+when no model-specific threshold is available. Empty results are valid.
+Use broader configured scopes only when the question genuinely spans them;
+do not automatically widen a search merely to force a hit.
 
 ## 2. Wiki
 Read `.planning/wiki/index.md` if present and follow links relevant to $ARGUMENTS.

package/docs/README.md

@@ -31,6 +31,9 @@ linked guides rather than the project landing page.
 
 ## Context intelligence
 
+- [Memory retrieval and the Markdown baseline](memory-retrieval.md) explains
+  optional hybrid admission, aliases, relevance diagnostics and reproducible
+  continuity evidence against searchable Markdown.
 - [Context intelligence](context-intelligence.md) connects progressive context-pack
   retrieval, the frozen benchmark, usage receipts, review-gated proposals, and
   the optional read-only OpenViking provider.

package/docs/agents.md

@@ -27,6 +27,15 @@ constraints, recurring failures, or prior work:
 This protocol improves continuity without allowing stale memory to outrank
 code, tests, current documentation, or the user's request.
 
+When the discovered tool schema supports it, `strategy: "hybrid"` is useful for
+identifier-sensitive and mixed-wording queries. `explain: true` exposes selection
+reasons; explicit `query_aliases` can express names already known from the task.
+Do not invent aliases or broaden scopes to obtain a match. Semantic-only
+paraphrase retrieval needs an explicitly chosen positive `min_score` in hybrid
+mode; without a model-specific threshold, the existing semantic strategy remains
+available. Empty results are valid, and ranking scores are not factual confidence.
+See [memory retrieval and evidence](memory-retrieval.md).
+
 ## What setup installs
 
 `cairn setup` reconciles a delimited Cairnkeep block in the project's

package/docs/benchmarks/memory-retrieval-v1.json

@@ -0,0 +1,115 @@
+{
+  "schema_version": 1,
+  "study": "synthetic-memory-continuity-v1",
+  "fixture_digest": "051a1ee175fc20d9e38c43d838b234c759133805ab335f74ef5603ee0871fce8",
+  "embedding": {
+    "mode": "none"
+  },
+  "limitations": [
+    "Synthetic retrieval scenarios, not autonomous task-quality or human-usability evidence.",
+    "Markdown baseline shares BM25/tokenization and receives identical alias information.",
+    "Markdown with the same admission policy is included to distinguish retrieval-policy gains from storage format.",
+    "Offline cases do not evaluate learned semantic paraphrase retrieval.",
+    "Explicit live threshold is an example, not universal calibration or a confidence probability.",
+    "Current-state fixture excludes archived history; actual supersession is covered by the MCP regression.",
+    "No automatic contradiction reconciliation, human consent or concurrent local-store access is claimed."
+  ],
+  "measurements": [
+    {
+      "adapter": "markdown-bm25",
+      "distractor_count": 0,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0.75,
+      "irrelevant_bytes": 794
+    },
+    {
+      "adapter": "markdown-hybrid",
+      "distractor_count": 0,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "legacy-substring",
+      "distractor_count": 0,
+      "hit_at_1": 0.3333333333333333,
+      "recall_at_5": 0.3333333333333333,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "hybrid-lexical",
+      "distractor_count": 0,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "markdown-bm25",
+      "distractor_count": 100,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0.75,
+      "irrelevant_bytes": 3359
+    },
+    {
+      "adapter": "markdown-hybrid",
+      "distractor_count": 100,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "legacy-substring",
+      "distractor_count": 100,
+      "hit_at_1": 0.3333333333333333,
+      "recall_at_5": 0.3333333333333333,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "hybrid-lexical",
+      "distractor_count": 100,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "markdown-bm25",
+      "distractor_count": 1000,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0.75,
+      "irrelevant_bytes": 3359
+    },
+    {
+      "adapter": "markdown-hybrid",
+      "distractor_count": 1000,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "legacy-substring",
+      "distractor_count": 1000,
+      "hit_at_1": 0.3333333333333333,
+      "recall_at_5": 0.3333333333333333,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    },
+    {
+      "adapter": "hybrid-lexical",
+      "distractor_count": 1000,
+      "hit_at_1": 0.8888888888888888,
+      "recall_at_5": 0.8888888888888888,
+      "negative_false_positive_rate": 0,
+      "irrelevant_bytes": 0
+    }
+  ]
+}

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.22.5
+**Baseline:** Cairnkeep 2.23.0
 **Last reviewed:** 2026-10-07
 
 This map prevents the course from drifting behind the product. It assigns each

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.22.5
+**Baseline:** Cairnkeep 2.23.0
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -36,6 +36,12 @@ explicit native Codex exec exports. See the L16 memory-protocol supplement;
 protocol observations and independently verified task correctness remain
 separate evidence, not a claim of model improvement.
 
+Version 2.23 adds opt-in hybrid memory retrieval, explicit query aliases and
+match/source/conflict explanations without changing legacy defaults. See
+[memory retrieval](../memory-retrieval.md), [L04](lessons/L04-memory-fundamentals.md)
+and its recording supplement. The synthetic Markdown comparison measures
+retrieval policy, not general task quality or a storage-format advantage.
+
 ## The three-layer model
 
 1. **Memory server:** an MCP process that owns scoped durable storage. The

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.22.5
+**Tested with:** Cairnkeep 2.23.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.22.5
+**Tested with:** Cairnkeep 2.23.0
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.22.5
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.23.0
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.22.5 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.23.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -47,7 +47,7 @@ sync. Codex project trust remains an explicit operator decision.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.22.5
+   npm install --global @cairnkeep/cli@2.23.0
    cairn --version
    ```
 

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.22.5
+**Tested with:** Cairnkeep 2.23.0
 
 ## Outcome
 

package/docs/learning/lessons/L04-memory-fundamentals.md

@@ -15,6 +15,10 @@ review extracted candidates before they become durable memory.
 - Key families: `decisions/`, `pitfalls/`, `patterns/`, `bugs/`,
   `constraints/`, and `conventions/`.
 - Exact read versus semantic search and substring fallback.
+- Optional hybrid lexical/identifier admission, explicit aliases, match reasons
+  and valid empty results; similarity scores are not factual confidence.
+- Curated Markdown as a credible baseline; indexing policy and storage format
+  are separate decisions.
 - Superseding a fact without losing history.
 - Session-end candidate extraction and `/memory-review` as the acceptance gate.
 - Typed node metadata, tags, and hard filters as an independent opt-in.
@@ -27,10 +31,24 @@ Store three synthetic facts in different categories, retrieve them by an
 imprecise query, supersede one, inspect its history, and reject one staged
 candidate.
 
+From a source checkout, run:
+
+```sh
+npm --prefix mcp-memory-server run study:memory-retrieval
+```
+
+Compare the 0/100/1,000-distractor results and explain
+why Markdown with the same admission policy matches Cairnkeep. Inspect the
+semantic-only case that lexical modes miss; do not describe the synthetic
+report as general accuracy. Repeat retrieval after superseding a synthetic
+fact and starting a fresh client, verifying the new value and explicit history.
+
 ## Acceptance criteria
 
 - The learner can justify the scope and category for each fact.
 - Search finds a fact without requiring its exact key.
+- A nearby but incorrect identifier and an unrelated query return no hybrid
+  match; aliases never widen scope or grant authority.
 - Superseding preserves the prior value in history.
 - No extracted candidate becomes durable without an explicit review action.
 - Enabling typed nodes changes discovery structure, not the authority of a fact.
@@ -38,5 +56,7 @@ candidate.
 ## Source material
 
 - [Operating guide](../../operating.md#the-workflow)
+- [Memory retrieval and the Markdown baseline](../../memory-retrieval.md)
+- [Recording supplement](../video-scripts/V04-memory-retrieval-supplement.md)
 - [Storage and deployment](../../storage.md)
 - [L14 - Typed memory and controlled import](L14-typed-memory.md)

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.22.5
+**Tested with:** Cairnkeep 2.23.0
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

package/docs/learning/lessons/L22-native-windows.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.22.5, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 
@@ -16,7 +16,7 @@ perform a reversible uninstall without relying on WSL or Git Bash.
 From PowerShell:
 
 ```powershell
-npm install --global @cairnkeep/cli@2.22.5
+npm install --global @cairnkeep/cli@2.23.0
 cairn version
 
 $Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'

package/docs/learning/lessons/L23-guided-setup.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.22.5; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.23.0; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 

package/docs/learning/lessons/L24-okf-exchange.md

@@ -1,7 +1,7 @@
 # L24 - Reviewed knowledge exchange
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/learning/lessons/L25-playbooks.md

@@ -1,7 +1,7 @@
 # L25 - Bounded workflow playbooks
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/learning/lessons/L26-context-intelligence.md

@@ -1,7 +1,7 @@
 # L26 - Context intelligence with explicit authority
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L27-ecosystem-evidence.md

@@ -1,6 +1,6 @@
 # L27 - Evaluate context companions without moving authority
 
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L28-security-assurance.md

@@ -1,7 +1,7 @@
 # L28 - Verify Cairnkeep's security posture
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.5 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.23.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -11,7 +11,7 @@ and choose least authority for a network-facing MCP client.
 
 ## Prerequisites
 
-- Install Cairnkeep 2.22.5 or use a disposable source checkout.
+- Install Cairnkeep 2.23.0 or use a disposable source checkout.
 - Complete [L20 - Least-authority MCP tool profiles](L20-mcp-tool-profiles.md).
 - Use synthetic values only; never paste a real bearer token into a recording,
   terminal transcript, or issue.

package/docs/learning/video-scripts/V04-memory-retrieval-supplement.md

@@ -0,0 +1,34 @@
+# V04 supplement — Finding the current fact without flooding context
+
+Technical recording brief; no video is claimed as recorded. Use the source
+checkout containing hybrid memory search and only invented fixture content.
+
+## Real terminal demonstration
+
+Type at readable human speed, leaving pauses after each command:
+
+```sh
+npm --prefix mcp-memory-server run build
+npm --prefix mcp-memory-server run check:memory-retrieval
+npm --prefix mcp-memory-server run study:memory-retrieval
+```
+
+Zoom into the real MCP test's new-process handoff, superseded-history exclusion,
+wrong-identifier refusal and provider-failure result. Demonstrate an MCP call
+with `strategy: "hybrid"` and `explain: true`; show matched terms and source
+locators, then show an unrelated query returning zero results. Explain that
+agents still verify maintained sources and do not automatically correct memory.
+
+## Evidence and pacing
+
+Show the frozen 1,000-distractor table: 3/9 first hits for substring, 8/9 for
+BM25 and hybrid. Pause on the difference in irrelevant bytes and negative hits.
+Then highlight that Markdown with the same admission policy also achieves 8/9
+and zero negative hits. State that storage format did not cause the gain.
+
+Finish with the semantic-only paraphrase that lexical modes miss. Explain that
+provider-specific thresholds need their own evidence, that a ranking score is
+not confidence, and that the attempted live study failed with HTTP 502. Do not
+invent a successful live result or claim general task-quality improvements.
+Use short terminal zooms and side-by-side result comparisons instead of static
+slides; keep credentials and real memory off screen.

package/docs/memory-retrieval.md

@@ -0,0 +1,174 @@
+# Memory retrieval and the Markdown baseline
+
+Status: available since Cairnkeep 2.23.0 as an opt-in strategy. Existing search
+defaults are unchanged; the developer study commands require a source checkout.
+
+Cairnkeep keeps authoritative memory text readable. Ordinary memory lives in
+AgentFS-backed SQLite; derived note address spaces and wiki pages use files.
+Optional embeddings are a rebuildable search aid, not fine-tuning, encrypted
+storage, or a replacement for the original text. Semantic search computes
+missing vectors lazily and caches them outside the authoritative records.
+Configured providers receive memory text and queries; an endpoint can run
+locally or remotely. See [storage](storage.md).
+
+## Opt-in hybrid search
+
+Existing `memory_search` calls retain legacy behavior and response shapes.
+Clients can explicitly select the new strategy through MCP:
+
+```json
+{
+  "scope": "project",
+  "query": "office tunnel access",
+  "strategy": "hybrid",
+  "top_k": 5,
+  "explain": true
+}
+```
+
+The result has `mode: "hybrid"`, ordinary original-text `results`, and a
+`retrieval` diagnostic. Empty results are valid: `empty_reason` distinguishes
+an empty scope from `no_relevant_memory`. `embedding_status` distinguishes
+unconfigured, available, failed and not-used providers. Ranking scores are
+labelled `ranking-not-confidence`; neither a cosine nor a lexical score is a
+probability that a statement is true.
+
+The new strategy currently supports the `memory` address space. File-backed
+note searches retain their existing exact behavior; requesting hybrid there
+fails explicitly. Existing `memory_read` key/query semantics are unchanged.
+
+### Selection and ranking
+
+1. Resolve explicit scopes and apply enabled typed-node hard filters before
+   ranking or embedding. Neither aliases nor semantic similarity widens scope.
+2. Tokenize Unicode words, ignore a small source-defined set of common
+   English/Italian stop words, and rank with BM25 (key terms appear twice).
+   Query terms are capped at 64; tokenization is capped at 4,096 terms per field.
+3. Admit lexical matches covering at least 60% of significant query terms,
+   with at least two matched terms for multi-term queries or one for a single
+   term. An exact key is admitted directly. Compound identifiers and numeric
+   identifiers must match exactly within at least one explicit query variant.
+   Match complete identifiers, not prefixes: `ember-42` does not match
+   `ember-42-backup`, and `4.2.1` does not match `4.2.1-rc1`. Sentence-ending
+   punctuation is not part of an identifier.
+4. With embeddings available, semantic scores contribute to ranking. A match
+   based only on semantics additionally requires an **explicit positive**
+   `min_score`. Omitted or zero `min_score` never admits semantic-only matches.
+   Choose that threshold using examples from the configured model and corpus;
+   no universal cosine cutoff is supplied or claimed as calibrated confidence.
+5. Put exact keys first, then sort by 80% normalized BM25 contribution plus
+   20% nonnegative cosine contribution. Break ties by scope/key deterministically.
+   Collapse identical key/value pairs; keep different values separate.
+
+`top_k` is a maximum, not a quota to fill. Provider failure, incomplete vectors,
+zero vectors or invalid dimensions fall back to lexical admission. Failure
+diagnostics include no provider response bodies. This does not change the
+legacy strategy's existing fallback semantics.
+
+With `explain: true`, each result includes `match.reasons`, matched terms,
+lexical coverage, the optional semantic score, and source scope/key locators.
+Identical records retain all source locators. `possible_conflicts` identifies
+admitted records sharing a key but having different live values across scopes.
+That is a review aid, not a finding that one value is false or an instruction
+to merge them. Explanations exist only in the response; no new recall log is kept.
+
+### Explicit aliases
+
+Aliases can be curated into ordinary memory text, or supplied as bounded query
+alternatives:
+
+```json
+{
+  "scope": "project",
+  "query": "home connection",
+  "strategy": "hybrid",
+  "query_aliases": ["office tunnel access", "relaybox"],
+  "explain": true
+}
+```
+
+At most eight aliases of 256 UTF-8 bytes each are accepted. The original hybrid
+query is bounded to 4 KiB. Invalid bounds fail before opening scopes or making
+provider requests. Aliases affect lexical selection; the original query is
+embedded once. They are caller-supplied hints and may explicitly substitute an
+identifier, not automatically inferred identities or additional authority.
+`query_aliases` and `explain` require `strategy: "hybrid"`.
+
+## Current values, history and authority
+
+Search reads live records and excludes hidden supersession history. Updating a
+fact through the existing supersession workflow makes the new value current
+and preserves the displaced value for explicit history inspection. A new MCP
+process can retrieve the live value after the previous local process exits.
+Simultaneous clients should use one shared server: independent direct local
+AgentFS processes can contend for native database locks.
+
+Current means current in the store, not independently verified or still true
+in the real world. No automatic expiry, contradiction resolution, history
+deletion, knowledge promotion or durable memory mutation is introduced. Verify
+maintained sources and supersede stale facts only through an authorized workflow.
+Personal scopes in a trusted deployment are not a multi-user ACL mechanism.
+The separate team preview is unchanged.
+
+## A fair Markdown comparison
+
+A curated Markdown folder provides readable durable knowledge, human editing,
+navigation and Git history. Adding the same retrieval policy can reproduce the
+same retrieval results. Cairnkeep provides a maintained shared MCP interface,
+scope routing, lifecycle operations and harness integrations; SQLite itself is
+not evidence of better recall.
+
+The reproducible study builds real temporary Markdown files and equivalent
+memory candidates with identical keys, values, scopes and explicit aliases.
+It compares a searchable-folder BM25 baseline, the legacy substring policy,
+the new admission policy and the same new policy applied to Markdown. Both
+folder variants receive the same tokenizer/BM25 implementation; the baseline
+is deliberately strong, and the Markdown parity control distinguishes search
+policy gains from storage format. The substring comparator unions explicit
+query variants, equivalent to separate legacy requests.
+
+Thirteen declared scenarios include a changed tunnel configuration, aliases,
+Italian queries, continuation conventions, release policy, unrelated queries,
+nearby/obsolete identifiers and wrong-project content, with 0/100/1,000
+distractors. The [frozen report](benchmarks/memory-retrieval-v1.json) shows:
+
+| Adapter, 1,000 distractors | Correct first result, 9 positive cases | Negative queries returning results, 4 cases | Irrelevant value bytes |
+|---|---:|---:|---:|
+| Legacy substring | 3/9 | 0/4 | 0 |
+| Markdown + BM25 | 8/9 | 3/4 | 3,359 |
+| Hybrid lexical admission | 8/9 | 0/4 | 0 |
+| Markdown + same admission | 8/9 | 0/4 | 0 |
+
+These are synthetic regression cases, not general retrieval accuracy, an
+independent holdout, autonomous task quality or proof of human consent. The
+semantic-only paraphrase is deliberately missed by lexical modes; the report
+does not claim perfect recall. A real MCP control separately verifies actual
+supersession, new-process handoff, scope filtering before provider requests and
+provider-failure behavior. No live user memory is read by these checks.
+
+From a source checkout:
+
+```sh
+npm --prefix mcp-memory-server run build
+npm --prefix mcp-memory-server run check:memory-retrieval
+npm --prefix mcp-memory-server run study:memory-retrieval
+# Explicit provider evaluation, using synthetic fixtures only:
+node mcp-memory-server/scripts/run-memory-retrieval-study.mjs --live --summary
+```
+
+The live study reports a model-ID digest, not credentials or endpoint addresses.
+Its sample threshold of 0.75 is an evaluation arm, not a recommended default.
+An attempted live run during development accepted short probes but failed with
+HTTP 502 on some fixture inputs. No successful live-model result is claimed.
+The offline suite never requires a model, API key, paid service or network beyond
+its own loopback fixture. An optional learned reranker remains deferred until
+provider-specific evidence demonstrates a benefit beyond this simpler policy.
+
+## Research connection
+
+[Alex Wang's associative-memory article](https://alexwang.ai/posts/associative-memory/)
+provides a useful perspective on recall interference. Its neural-layer capacity
+experiments do not establish limits for a text database. This implementation
+applies selective retrieval at the application layer without changing model
+weights. Merely applying softmax to an existing score list preserves ordering
+and would not improve fixed-top-k selection.

package/docs/operating.md

@@ -32,6 +32,11 @@ sync command but never runs it automatically. This guide covers all three.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
   embedding-ranked search. Without it, memory search degrades to substring
   matching — everything else still works.
+  Explicit `memory_search` calls with `strategy: "hybrid"` additionally support
+  lexical/identifier admission without a provider, bounded `query_aliases`,
+  optional explanations and empty results. Semantic-only admission requires an
+  explicit positive `min_score`; see [memory retrieval](memory-retrieval.md)
+  for model-specific threshold limits and the Markdown comparison.
 - Optional: rootless Podman for the containerized memory server and isolated
   workspace base described in [Containers](containers.md).
 

package/docs/releasing.md

@@ -66,6 +66,13 @@ or moved. If the tree-addressed candidate has expired, rerun CI for the exact
 release commit before retrying publication; the workflow never substitutes a
 different version or tree.
 
+CI job retries can also regenerate the same tree-addressed candidate. Its
+upload explicitly replaces an existing artifact of that name within the same
+workflow run, only after all platform/runtime dependencies succeed. This avoids
+an artifact-name conflict after a completed job is retried; it does not move
+versioned image tags, republish npm versions or replace GitHub Release assets.
+Candidate checksums and tree/version binding are verified as usual.
+
 ## Repository configuration
 
 ### Repeatable post-publication verification

package/docs/storage.md

@@ -48,6 +48,11 @@ services used to process/search memory. They do not change where the SQLite
 databases are stored. Git-provider and routing configuration do not change
 storage either.
 
+`memory_search` can optionally select [hybrid retrieval](memory-retrieval.md).
+This changes read-time ranking only: aliases are request hints, explanations
+are returned to the caller without a new log, and original memory text remains
+authoritative. No new store, migration or automatic memory capture is introduced.
+
 Trajectory storage is deliberately separate from MCP memory. The harness hook
 writes `.agentfs/trajectory.db` on the client machine where Claude Code,
 OpenCode, or Pi is running; it is never redirected to the remote HTTP memory server.

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.22.5","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.23.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/mcp-memory-server/dist/index.js

@@ -25,6 +25,7 @@ import { profileAllowsTool, resolveMcpToolProfile } from "./mcp-tool-profile.js"
 import { isWorkEvidenceEnabled } from "./work-evidence-schema.js";
 import { extractMemoryCandidates as extractMemoryCandidatesFromProvider } from "./memory-extraction.js";
 import { applyReviewedMemory, invalidateReviewedMemory } from "./reviewed-memory-store.js";
+import { rankHybridMemory } from "./memory-retrieval.js";
 const MINIMUM_NODE_MAJOR = 22;
 const nodeMajor = Number.parseInt(process.versions.node, 10);
 if (!Number.isInteger(nodeMajor) || nodeMajor < MINIMUM_NODE_MAJOR) {
@@ -377,7 +378,14 @@ async function semanticSearch(scope, query, topK, minScore, config = getMemoryCo
         entries: filterEntries(await listEntries(candidate, "", { projectId, typed: options.typed }), options.filters ?? {}),
     })));
     const allEntries = perScopeEntries.flatMap((group) => group.entries);
+    const hybrid = (embeddingStatus, semanticScores) => ({
+        ...rankHybridMemory(allEntries, query, { topK, minScore, aliases: options.aliases, explain: options.explain, embeddingStatus, semanticScores }),
+        mode: "hybrid",
+        ...(embeddingConfig ? { model: embeddingConfig.model } : {}),
+    });
     if (allEntries.length === 0) {
+        if (options.strategy === "hybrid")
+            return hybrid(embeddingConfig ? "not_used" : "unconfigured");
         return { results: [], mode: embeddingConfig ? "semantic" : "substring" };
     }
     const substringFallback = () => {
@@ -390,6 +398,8 @@ async function semanticSearch(scope, query, topK, minScore, config = getMemoryCo
         };
     };
     if (!embeddingConfig) {
+        if (options.strategy === "hybrid")
+            return hybrid("unconfigured");
         return substringFallback();
     }
     try {
@@ -422,9 +432,23 @@ async function semanticSearch(scope, query, topK, minScore, config = getMemoryCo
             }
         }
         const [queryVector] = await embedTexts(embeddingConfig, [query]);
+        if (options.strategy === "hybrid") {
+            const validVector = (vector) => {
+                if (!vector?.length || vector.length > 65536 || vector.some(value => !Number.isFinite(value)))
+                    return false;
+                const squaredNorm = vector.reduce((total, value) => total + value * value, 0);
+                return squaredNorm > 0 && Number.isFinite(squaredNorm);
+            };
+            if (!validVector(queryVector) || allEntries.some(entry => !validVector(vectors.get(entry)) || vectors.get(entry).length !== queryVector.length)) {
+                throw new Error("Embedding vectors are incomplete or invalid.");
+            }
+        }
         for (const cache of caches) {
             cache.save();
         }
+        if (options.strategy === "hybrid") {
+            return hybrid("available", new Map(allEntries.map(entry => [entry, Math.max(-1, Math.min(1, cosineSimilarity(queryVector, vectors.get(entry))))])));
+        }
         const exact = options.typed
             ? allEntries.filter((entry) => isExactTextHit(entry, query)).sort(compareMemoryEntries).map((entry) => ({ ...entry, score: 1 }))
             : [];
@@ -444,6 +468,8 @@ async function semanticSearch(scope, query, topK, minScore, config = getMemoryCo
     }
     catch {
         // Embedding endpoint failure — degrade gracefully to substring matching.
+        if (options.strategy === "hybrid")
+            return hybrid("failed");
         return substringFallback();
     }
 }
@@ -1112,6 +1138,9 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             query: z.string().min(1),
             top_k: z.number().int().min(1).max(50).optional(),
             min_score: z.number().min(0).max(1).optional(),
+            strategy: z.enum(["legacy", "hybrid"]).optional().describe("Default legacy preserves current retrieval. Hybrid admits lexical/identifier matches and semantic-only matches above an explicit positive min_score."),
+            query_aliases: z.array(z.string().trim().min(1).max(256)).max(8).optional().describe("Explicit alternative query phrases for hybrid lexical retrieval; never widens scopes."),
+            explain: z.boolean().optional().describe("Include hybrid match reasons, provenance locators and possible conflicting live values."),
             ...(typedNodesEnabled ? {
                 address_space: NODE_ADDRESS_SPACE_SCHEMA.optional(),
                 node_types: z.array(nodeTypeSchema).min(1).optional(),
@@ -1124,8 +1153,17 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
         },
     }, async (input) => {
         const { scope, query, top_k, min_score } = input;
+        if (input.strategy !== "hybrid" && (input.query_aliases !== undefined || input.explain !== undefined)) {
+            throw new Error("query_aliases and explain require strategy='hybrid'.");
+        }
+        if (input.strategy === "hybrid") {
+            // Validate bounds before opening scopes or contacting an embedding service.
+            rankHybridMemory([], query, { topK: top_k ?? 8, minScore: min_score ?? 0, aliases: input.query_aliases });
+        }
         const addressSpace = "address_space" in input && input.address_space !== undefined ? NODE_ADDRESS_SPACE_SCHEMA.parse(input.address_space) : undefined;
         if (addressSpace && addressSpace !== "memory") {
+            if (input.strategy === "hybrid")
+                throw new Error("Hybrid retrieval currently supports the memory address space only.");
             const noteStore = await import("./note-store.js");
             const entries = noteStore.searchAddressedNotes({ ...noteTargetOptions(scope, addressSpace), query, ...memoryFiltersFromInput(input) }).slice(0, top_k ?? 8);
             const results = entries.map((entry) => ({ ...entry, score: 1 }));
@@ -1135,11 +1173,14 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
                 structuredContent: payload,
             };
         }
-        const { results, mode, model } = await semanticSearch(scope, query, top_k ?? 8, min_score ?? 0, memoryConfig(), context.projectId, {
+        const { results, mode, model, retrieval } = await semanticSearch(scope, query, top_k ?? 8, min_score ?? 0, memoryConfig(), context.projectId, {
             typed: typedNodesEnabled,
             filters: typedNodesEnabled ? memoryFiltersFromInput(input) : {},
+            strategy: input.strategy,
+            aliases: input.query_aliases,
+            explain: input.explain,
         });
-        const payload = { mode, model, count: results.length, results };
+        const payload = { mode, model, count: results.length, results, ...(retrieval ? { retrieval } : {}) };
         return {
             content: [{ type: "text", text: asToolText(payload) }],
             structuredContent: payload,

package/mcp-memory-server/dist/memory-retrieval.js

@@ -0,0 +1,128 @@
+const STOP = new Set('a an and are as at be by can do does for from how i in is it me my of on or our please that the their this to use we what when where which with would you your un una uno il lo la gli le di da del della e che con come per posso mio mia sul nel dei'.split(' '));
+const normalize = (value) => value.normalize('NFKC').toLowerCase();
+const compare = (left, right) => left.scope.localeCompare(right.scope, 'en') || left.key.localeCompare(right.key, 'en');
+const rounded = (value) => Math.round(value * 1e6) / 1e6;
+export function retrievalTerms(text) {
+    const result = [];
+    for (const match of normalize(text).matchAll(/[\p{L}\p{N}]+/gu)) {
+        if (match[0].length > 1 && !STOP.has(match[0]))
+            result.push(match[0]);
+        if (result.length === 4096)
+            break;
+    }
+    return result;
+}
+function identifiers(text) {
+    // Match ordinary words too, then select identifiers. Requiring a separator
+    // in an unanchored greedy expression repeatedly rescans long plain words.
+    const result = new Set();
+    for (const match of text.matchAll(/[\p{L}\p{N}]+(?:[._:/-][\p{L}\p{N}]+)*/gu)) {
+        if (/[._:/\d-]/u.test(match[0]))
+            result.add(match[0]);
+    }
+    return result;
+}
+function variant(text) {
+    const normalized = normalize(text).trim();
+    return { normalized, terms: [...new Set(retrievalTerms(text))].slice(0, 64), identifiers: identifiers(normalized) };
+}
+/** BM25 is also used by the transparent Markdown-folder baseline. */
+export function lexicalMemoryScores(entries, query) {
+    const queryTerms = [...new Set(retrievalTerms(query))].slice(0, 64);
+    const docs = entries.map(entry => [
+        ...retrievalTerms(entry.key), ...retrievalTerms(entry.key),
+        ...retrievalTerms(entry.value), ...retrievalTerms([entry.node_type, ...(entry.tags ?? [])].filter(Boolean).join(' ')),
+    ]);
+    const frequencies = docs.map(terms => {
+        const counts = new Map();
+        for (const term of terms)
+            counts.set(term, (counts.get(term) ?? 0) + 1);
+        return counts;
+    });
+    const averageLength = docs.reduce((total, terms) => total + terms.length, 0) / Math.max(1, docs.length) || 1;
+    const documentFrequencies = new Map(queryTerms.map(term => [term, frequencies.filter(counts => counts.has(term)).length]));
+    return docs.map((terms, index) => queryTerms.reduce((score, term) => {
+        const frequency = frequencies[index].get(term) ?? 0;
+        const df = documentFrequencies.get(term) ?? 0;
+        const idf = Math.log(1 + (entries.length - df + 0.5) / (df + 0.5));
+        return score + idf * frequency * 2.2 / (frequency + 1.2 * (0.25 + 0.75 * terms.length / averageLength));
+    }, 0));
+}
+export function rankHybridMemory(entries, query, options) {
+    const aliases = options.aliases ?? [];
+    if (Buffer.byteLength(query, 'utf8') > 4096 || !query.trim() || aliases.length > 8
+        || aliases.some(alias => !alias.trim() || Buffer.byteLength(alias, 'utf8') > 256)
+        || !Number.isInteger(options.topK) || options.topK < 1 || options.topK > 50
+        || !Number.isFinite(options.minScore) || options.minScore < 0 || options.minScore > 1) {
+        throw new Error('Hybrid memory search requires bounded query, aliases, result count and similarity threshold.');
+    }
+    const variants = [...new Set([query, ...aliases].map(text => normalize(text).trim()))].map(variant);
+    const lexicalScores = variants.map(item => lexicalMemoryScores(entries, item.normalized));
+    const candidates = entries.map((entry, index) => {
+        const text = normalize([entry.key, entry.value, entry.node_type, ...(entry.tags ?? [])].filter(Boolean).join('\n'));
+        const words = new Set(retrievalTerms(text));
+        const entryIdentifiers = identifiers(text);
+        const matches = variants.map((item, v) => {
+            const matched = item.terms.filter(term => words.has(term));
+            const coverage = item.terms.length ? matched.length / item.terms.length : 0;
+            const identifierMatch = [...item.identifiers].every(id => entryIdentifiers.has(id));
+            const exactKey = normalize(entry.key) === item.normalized;
+            return {
+                matched, coverage, identifierMatch, exactKey,
+                eligible: identifierMatch && (exactKey || (coverage >= 0.6 && matched.length >= Math.min(2, item.terms.length) && matched.length > 0)),
+                lexical: lexicalScores[v][index],
+            };
+        });
+        const best = matches.filter(match => match.eligible).sort((a, b) => Number(b.exactKey) - Number(a.exactKey) || b.lexical - a.lexical)[0];
+        const rawSemantic = options.semanticScores?.get(entry);
+        const semantic = typeof rawSemantic === 'number' && Number.isFinite(rawSemantic) && rawSemantic >= -1 && rawSemantic <= 1 ? rawSemantic : null;
+        const semanticAdmission = options.minScore > 0 && semantic !== null && semantic >= options.minScore && matches.some(match => match.identifierMatch);
+        const lexical = best?.lexical ?? 0;
+        const score = 0.8 * lexical / (1 + lexical) + 0.2 * Math.max(0, semantic ?? 0);
+        return { entry, best, semantic, semanticAdmission, score };
+    }).filter(item => item.best || item.semanticAdmission)
+        .sort((a, b) => Number(Boolean(b.best?.exactKey)) - Number(Boolean(a.best?.exactKey)) || b.score - a.score || compare(a.entry, b.entry));
+    const grouped = new Map();
+    for (const candidate of candidates) {
+        const key = JSON.stringify([candidate.entry.key, candidate.entry.value]);
+        const group = grouped.get(key) ?? [];
+        group.push(candidate);
+        grouped.set(key, group);
+    }
+    const results = [...grouped.values()].slice(0, options.topK).map(group => {
+        const item = group[0];
+        const reasons = [
+            ...(item.best?.exactKey ? ['exact-key'] : []),
+            ...(item.best ? ['lexical-coverage'] : []),
+            ...(item.semanticAdmission ? ['semantic-threshold'] : []),
+            ...(group.length > 1 ? ['identical-records-collapsed'] : []),
+        ];
+        return {
+            ...item.entry, score: rounded(item.score),
+            ...(options.explain ? { match: {
+                    reasons, matched_terms: item.best?.matched ?? [], lexical_coverage: rounded(item.best?.coverage ?? 0),
+                    semantic_score: item.semantic === null ? null : rounded(item.semantic),
+                    sources: group.map(({ entry }) => ({ scope: entry.scope, key: entry.key })).sort(compare),
+                } } : {}),
+        };
+    });
+    const conflicts = [...new Set(results.map(item => item.key))].flatMap(key => {
+        const relevant = candidates.filter(item => item.entry.key === key);
+        return new Set(relevant.map(item => item.entry.value)).size > 1
+            ? [{ key, scopes: [...new Set(relevant.map(item => item.entry.scope))].sort() }] : [];
+    });
+    return {
+        results,
+        retrieval: {
+            strategy: 'hybrid',
+            score_kind: 'ranking-not-confidence',
+            embedding_status: options.embeddingStatus ?? (options.semanticScores ? 'available' : 'unconfigured'),
+            semantic_min_score: options.minScore > 0 ? options.minScore : null,
+            alias_count: aliases.length,
+            candidates: entries.length,
+            admitted: grouped.size,
+            ...(results.length === 0 ? { empty_reason: entries.length ? 'no_relevant_memory' : 'empty_scope' } : {}),
+            ...(options.explain ? { possible_conflicts: conflicts } : {}),
+        },
+    };
+}

package/mcp-memory-server/package.json

@@ -15,6 +15,8 @@
         "check:embeddings": "node scripts/smoke-embeddings.mjs",
         "check:extract": "node scripts/smoke-extract-cli.mjs",
         "check:search": "node scripts/smoke-search-e2e.mjs",
+        "check:memory-retrieval": "node scripts/smoke-memory-retrieval.mjs && node scripts/smoke-memory-retrieval-mcp.mjs && node scripts/run-memory-retrieval-study.mjs --check --summary",
+        "study:memory-retrieval": "npm run build && node scripts/run-memory-retrieval-study.mjs --summary",
         "check:scope-guard": "node scripts/smoke-scope-guard.mjs",
         "check:http-guard": "node scripts/smoke-http-guard.mjs",
         "check:remote-context": "node scripts/smoke-remote-context.mjs",

package/opencode/command/recall.md

@@ -25,7 +25,14 @@ Read order (canonical sources still win over derived layers):
 
 <process>
 ## 1. AgentFS
-`cairn-memory_memory_search` scope `project` with $ARGUMENTS. If nothing relevant, retry scope `all`.
+`cairn-memory_memory_search` scope `project` with $ARGUMENTS. When the discovered
+schema supports it, use `strategy: "hybrid"` for identifier-sensitive or
+mixed-wording queries and `explain: true` to inspect matches. Supply only aliases
+already known from the task. Semantic-only hybrid matches require an explicitly
+chosen positive `min_score`; retain the existing semantic strategy for paraphrases
+when no model-specific threshold is available. Empty results are valid.
+Use broader configured scopes only when the question genuinely spans them;
+do not automatically widen a search merely to force a hit.
 
 ## 2. Wiki
 Read `.planning/wiki/index.md` if present and follow links relevant to $ARGUMENTS.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cairnkeep/cli",
-    "version": "2.22.5",
+    "version": "2.23.0",
     "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
     "license": "Apache-2.0",
     "type": "module",

package/scripts/test-memory-retrieval-docs.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$ROOT"
+for path in docs/memory-retrieval.md docs/benchmarks/memory-retrieval-v1.json docs/learning/video-scripts/V04-memory-retrieval-supplement.md; do
+  [[ -f "$path" ]]
+done
+for path in docs/README.md docs/operating.md docs/storage.md docs/agents.md docs/learning/lessons/L04-memory-fundamentals.md; do
+  grep -qF 'memory-retrieval.md' "$path"
+done
+for path in claude/commands/recall.md opencode/command/recall.md; do
+  grep -qF 'do not automatically widen' "$path"
+  grep -qF 'strategy: "hybrid"' "$path"
+done
+grep -qF 'same admission' docs/memory-retrieval.md
+grep -qF 'HTTP 502' docs/memory-retrieval.md
+grep -qF 'ranking-not-confidence' docs/memory-retrieval.md
+grep -qF 'Status: available since Cairnkeep 2.23.0' docs/memory-retrieval.md
+echo 'PASS: hybrid retrieval, Markdown parity, provider limitations and learning/recording references'

package/scripts/test-release-sbom.sh

@@ -14,6 +14,8 @@ fail() {
 
 node - "$ROOT/package.json" "$ROOT/package-lock.json" "$CANDIDATE_WORKFLOW" "$PUBLISH_WORKFLOW" <<'NODE'
 const fs = require("node:fs");
+const assert = require("node:assert/strict");
+const { parse } = require("yaml");
 
 const manifest = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
 const lock = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
@@ -36,6 +38,36 @@ if (!candidateWorkflow.includes("release-candidate:")
   || !candidateWorkflow.includes("name: release-candidate-${{ steps.candidate.outputs.tree }}")) {
   throw new Error("CI must build and upload a tree-addressed release candidate after its required jobs");
 }
+function validateCandidateRetry(workflow) {
+  const job = workflow.jobs["release-candidate"];
+  assert.deepEqual(new Set(job.needs), new Set([
+    "memory-server", "native-windows", "repository", "shell-portability",
+    "server-boot", "container", "fresh-install-macos",
+  ]), "candidate retry must retain every platform/runtime gate");
+  assert.equal(job.if, undefined, "candidate retry must not bypass failed or pending gates");
+  const uploads = job.steps.filter(step => step.uses?.startsWith("actions/upload-artifact@"));
+  assert.equal(uploads.length, 1, "candidate retry must have one artifact publication");
+  assert.equal(uploads[0].with.name, "release-candidate-${{ steps.candidate.outputs.tree }}");
+  assert.equal(uploads[0].with.overwrite, true, "candidate upload must support same-run retries");
+  assert.equal(uploads[0].with["if-no-files-found"], "error");
+}
+const candidate = parse(candidateWorkflow);
+const positive = structuredClone(candidate);
+positive.jobs["release-candidate"].steps.find(step => step.uses?.startsWith("actions/upload-artifact@")).with.overwrite = true;
+validateCandidateRetry(positive);
+for (const overwrite of [undefined, false]) {
+  const invalid = structuredClone(positive);
+  invalid.jobs["release-candidate"].steps.find(step => step.uses?.startsWith("actions/upload-artifact@")).with.overwrite = overwrite;
+  assert.throws(() => validateCandidateRetry(invalid), /same-run retries/);
+}
+const missingGate = structuredClone(positive);
+missingGate.jobs["release-candidate"].needs = missingGate.jobs["release-candidate"].needs.filter(name => name !== "native-windows");
+assert.throws(() => validateCandidateRetry(missingGate), /every platform\/runtime gate/);
+const bypass = structuredClone(positive);
+bypass.jobs["release-candidate"].if = "always()";
+assert.throws(() => validateCandidateRetry(bypass), /must not bypass/);
+validateCandidateRetry(candidate);
+console.log("PASS: retry-safe candidate upload and four gate/replacement mutation controls");
 if (!publishWorkflow.includes("- name: Download the CI-verified release candidate")
   || !publishWorkflow.includes("jq -r '.conclusion'")
   || !publishWorkflow.includes("== success")

package/templates/playbook-agent-instructions.md.template

@@ -10,6 +10,11 @@ inventory, or search commands such as `pwd`, `ls`, `rg --files`, `find`,
 - If `memory_search` is available, derive one short query from the task and
   search `scope: project` once. Derive it from the user's task; do not inspect
   the repository first merely to formulate the query.
+- When the discovered schema supports hybrid search, use it for explicit
+  identifiers or mixed wording; request explanations when needed. Supply only
+  aliases already known from the task. Hybrid semantic-only matches require an
+  explicit model-specific positive similarity threshold; otherwise keep the
+  existing semantic strategy for paraphrases. Empty results are acceptable.
 - Treat returned memory as a locator, not authority. Read and verify the
   maintained repository sources it references before implementing a result.
 - If the tool is unavailable or no relevant result exists, continue with