@cairnkeep/cli 2.22.5 → 2.23.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.23.1] - 2026-10-22
+
+### Domain knowledge
+
+- Resolve local AnythingLLM defaults from the existing absolute project-path
+  mapping, with deepest-project matching and the sync script's discovery order.
+  Preserve explicit workspace overrides, legacy fallback, remote HTTP session
+  routing, OpenViking selection and synchronization approval requirements.
+- Bound mapping reads and reject unsafe files, invalid slugs and ambiguous
+  canonical project declarations. Add pure, real stdio, HTTP and synchronization
+  regression controls; update operating guidance and the recording supplement.
+
+### Maintenance
+
+- Allocate the remote-routing test provider's loopback port dynamically; retain
+  the formerly failing PID as a regression instead of hitting fetch's blocked
+  port 10080. Production routing and transport policy are unchanged.
+- Refresh pinned setup, artifact-upload and code-scanning actions; align the
+  packaged CLI and server on Zod 4.6.7 with dependency-parity mutation controls.
+- Update the isolated historical Python MCP integration experiment to 2.2.0;
+  this does not add Python or that experiment to the shipped Node runtime.
+
+## [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/domain-knowledge.md

@@ -29,7 +29,7 @@ work exactly the same without them.
 | `ANYTHINGLLM_API_KEY` | **Required** for the domain-knowledge tools. Unset → the tools error at call time (everything else works). |
 | `ANYTHINGLLM_BASE_URL` | AnythingLLM base URL. Default `http://localhost:3001`. |
 | `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` | Optional path to a custom document-sync script. Unset -> `domain_knowledge_sync` uses the bundled deployment-neutral example. |
-| `CAIRN_ANYTHINGLLM_PROJECTS_FILE` | Optional config path for the bundled sync script. Default `${XDG_CONFIG_HOME:-~/.config}/cairnkeep/anythingllm-projects.json`. |
+| `CAIRN_ANYTHINGLLM_PROJECTS_FILE` | Optional config path for the bundled sync script, also used to pick the default workspace per repository. Default `${XDG_CONFIG_HOME:-~/.config}/cairnkeep/anythingllm-projects.json`. |
 | `CAIRN_ANYTHINGLLM_STATE_FILE` | Optional state path for the bundled sync script. Default `${XDG_STATE_HOME:-~/.local/state}/cairnkeep/anythingllm-sync.json`. |
 
 The query security follow-up validates HTTP(S) URLs and rejects embedded
@@ -54,9 +54,43 @@ first of `.agent/memory.json`, `.opencode/memory.json`, `.claude/memory.json`, o
 }
 ```
 
-`domain_knowledge_query` takes an explicit `workspace`, or falls back to the first
-configured workspace that is not `engineering-patterns` (the conventional shared
-workspace). With no workspace given and none configured, it errors.
+### Which workspace a call targets
+
+A local stdio tool call without an explicit `workspace` resolves one in this order:
+
+1. The project in `anythingllm-projects.json` whose absolute `path` contains the current
+   working directory. The deepest match wins, so a checkout nested inside
+   another project resolves to its own workspace.
+2. Otherwise the first entry in `anythingllm_workspaces` that is not
+   `engineering-patterns`, which is reserved for cross-project patterns and is
+   never chosen as a project default.
+
+Step 1 matters when one machine holds several checkouts that share a single
+global memory config. Without it every repository resolves to the same
+workspace, and a query made from a different repository reports "there is no
+relevant information" instead of revealing that it searched somewhere
+unrelated. Because the mapping is the same file the sync script uses, the
+workspace a repository reads from is the one it embeds into.
+
+If the mapping is absent, unreadable, or malformed, resolution falls back to
+step 2, so existing single-project setups are unaffected.
+
+Mapping discovery follows the bundled sync script exactly:
+`CAIRN_ANYTHINGLLM_PROJECTS_FILE`, then a legacy file beside the selected sync
+script, then `${XDG_CONFIG_HOME:-~/.config}/cairnkeep/anythingllm-projects.json`.
+A missing explicit override does not select another mapping implicitly. Custom
+sync implementations must honor the same mapping or configure an explicit
+workspace; Cairnkeep cannot infer their private lookup rules.
+
+Mapping reads are descriptor-bound UTF-8 JSON, limited to 1 MiB and 4,096
+entries. Symlinked, special, changing and oversized mapping files are not read
+as trusted content. Project paths must be absolute, without tilde expansion,
+matching the sync script. They are canonicalized; relative declarations,
+invalid workspace identifiers and the shared `engineering-patterns` slug are
+skipped. Conflicting slugs for the same deepest canonical project raise a
+controlled ambiguity error: specify `workspace` or correct the declarations.
+Explicit tool arguments always win. With no resolved default, the tool errors.
+This lookup selects a destination; it does not grant approval to synchronize.
 
 In local stdio mode, that config is read from the client project's working
 directory. In remote HTTP mode, the server cannot read files from the client
@@ -64,6 +98,10 @@ PC. Configure `ANYTHINGLLM_BASE_URL`, `ANYTHINGLLM_API_KEY`, and any sync script
 on the HTTP server host, then send the project workspaces in the
 `X-Cairn-AnythingLLM-Workspaces` session header. See
 [Memory storage and deployment](storage.md#per-project-remote-sessions).
+HTTP calls never consult the server checkout's project mapping to choose a
+client's default, including on the synchronization write path. The optional
+OpenViking provider also retains its configured workspace selection rather
+than consulting an AnythingLLM-specific mapping.
 
 The HTTP server performs queries and runs the sync script on its own host. A
 remote sync script must therefore obtain project documents from a server-side

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.22.5
-**Last reviewed:** 2026-10-07
+**Baseline:** Cairnkeep 2.23.1
+**Last reviewed:** 2026-10-22
 
 This map prevents the course from drifting behind the product. It assigns each
 user-facing surface to a lesson and records whether the lesson is complete or
@@ -20,7 +20,7 @@ been rehearsed.
 | Wiki, alignment, and repository quality workflows | L05-L06 | L05-L06 | Brief |
 | Optional local code graph, graph inspection, and harness delegates | L18 | L18 | Brief; default off |
 | Storage placement, export/import, and authenticated remote memory | L07 | L07-L08 | Brief |
-| Document RAG | L00 | L09 | Brief; optional |
+| Document RAG | L00 | L09 | Brief; optional; [V09 routing supplement](video-scripts/V09-workspace-routing-supplement.md) covers local mappings and HTTP isolation |
 | token-miser exploration and routing | L00 | L10 | Brief; optional |
 | Rootless containers and persistent service operation | L01 | L11 | L01 Ready; L11 Brief |
 | Private managed distributions | L12 | L12 | Brief; optional |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.22.5
+**Baseline:** Cairnkeep 2.23.1
 
 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.1
 
 ## 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.1
 
 ## 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.1
    ```
 
 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.1 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.1 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.1
    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.1
 
 ## 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/L09-domain-knowledge.md

@@ -13,6 +13,8 @@ without affecting core Cairnkeep memory.
 
 - Memory versus document RAG responsibilities.
 - Workspace selection and project configuration.
+- Explicit directory-to-workspace mapping for local stdio; HTTP session headers
+  remain authoritative for remote routing, not the server's current directory.
 - Query-only setup before document synchronization.
 - Incremental, full, and replacement synchronization boundaries.
 - Endpoint, credential, and document-selection safety.
@@ -24,12 +26,21 @@ Index a synthetic three-document corpus into a disposable workspace, ask a
 question requiring citations to two documents, update one document, resync, and
 verify the new answer. Then unset the integration and prove memory still works.
 
+Use two disposable checkouts sharing a global memory configuration. Declare
+their absolute paths and distinct slugs in `anythingllm-projects.json`; verify
+root and subdirectory queries report the expected workspace. Check an explicit
+workspace override and an undeclared-directory fallback. Keep synchronization
+synthetic and separately approved; a destination mapping is not write consent.
+See the [recording supplement](../video-scripts/V09-workspace-routing-supplement.md).
+
 ## Acceptance criteria
 
 - Only allowlisted synthetic documents are uploaded.
 - The learner can identify the selected workspace and endpoint without printing
   its credential.
 - Updated content replaces stale retrieval results.
+- The learner verifies the returned workspace before trusting an empty answer;
+  conflicting deepest declarations require an explicit destination or repair.
 - Disabling RAG leaves `/remember` and `/recall` healthy.
 
 ## Source material

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.1
 
 ## 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.1 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.1 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.1, 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.1
 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.1; 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.1 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.1 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.1 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.1 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.1 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.1 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/learning/video-scripts/V09-workspace-routing-supplement.md

@@ -0,0 +1,36 @@
+# V09 supplement — The right documents for the right repository
+
+Technical recording brief; no completed video or full Ready L09 lab is claimed.
+Use invented repository names and a loopback mock, never private mappings,
+provider keys, real documents or production synchronization.
+
+## Real terminal demonstration
+
+Leave a readable pause after each command:
+
+```sh
+npm --prefix mcp-memory-server run build
+npm --prefix mcp-memory-server run check:anythingllm-workspace
+npm --prefix mcp-memory-server run check:remote-context
+```
+
+Show two synthetic checkouts sharing one global configuration, then highlight
+the distinct workspace reported by each real stdio MCP query. Zoom into a
+subdirectory call and an explicit override. Explain that an empty answer from
+the wrong corpus is not evidence that the requested information does not exist.
+
+The mock synchronization prints arguments only; it uploads nothing. Contrast
+destination selection with write consent and show replacement being refused
+without confirmation. For HTTP, show the conflicting server-directory mapping
+fixture and the client header still winning. Do not run a live provider or
+silently activate RAG merely to record this supplement.
+
+## Boundaries and recovery
+
+Explain the lookup order: explicit mapping file, legacy mapping beside the
+selected sync script, then XDG. Missing or invalid mappings keep the legacy
+configured default; inspect the returned workspace. Ambiguous deepest entries
+require an explicit workspace or a corrected mapping. Mapping files are bounded
+and unsafe file types are rejected. Directory matching is routing, not an ACL
+or publisher-authenticity guarantee. Keep the full L09 lesson marked Brief until
+its separate live synthetic-corpus lab has been verified.