@cairnkeep/cli 2.23.0 → 2.24.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.24.0] - 2026-10-24
+
+### Memory retrieval
+
+- Add optional provider-neutral learned reranking for ordinary memory search,
+  with explicit endpoint/model consent and a separate optional credential.
+  Preserve existing scope, current-value, typed and relevance admission;
+  bound candidate text, streamed responses and deadlines. Provider failures
+  preserve the original ranking. Exact keys, including explicit aliases,
+  retain priority. Default search behavior stays unchanged.
+- Add functional POSIX/native-Windows diagnostics, real MCP isolation/fallback
+  controls and a frozen synthetic provider comparison. Document both improved
+  first-result ordering and the regression; do not claim better general recall
+  or agent productivity. Update retrieval/privacy guidance and L04/V04 material.
+- Preserve frozen fixture bytes on Windows and verify linked-install probes.
+  No new runtime dependency, storage migration, automatic provider discovery
+  or team-feature activation is included.
+
+### Security
+
+- Refresh compatible transitive HTTP parser, URI and IP-address dependencies
+  in both lock graphs. Enforce the patched minimum versions, including nested
+  copies, with dependency-policy regression controls.
+- Normalize the container health-check directory's traversal permissions after
+  copying its probe. Verify the legacy entrypoint imports as the runtime UID;
+  do not count module-load failures as successful credential rejection.
+
+## [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

package/docs/containers.md

@@ -86,6 +86,10 @@ configuration fails without issuing a request; probes target only
 `127.0.0.1` and refuse redirects. The existing
 `/usr/local/lib/cairnkeep/container-healthcheck.mjs` command remains available
 as an alias to the packaged probe. Stdio mode requires no HTTP probe.
+The image explicitly makes the probe directory searchable by its unprivileged
+runtime user after copying the file. The OCI regression imports that legacy
+entrypoint as UID 10001 before testing credentials, so a missing or inaccessible
+module cannot be mistaken for a successful authentication rejection.
 File-based probes require a private token readable by the container user;
 world-readable secret mounts fail closed. The Quadlet example explicitly mounts
 its secret as UID/GID 10001 with mode `0400`. For other engines, verify the

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.23.0
-**Last reviewed:** 2026-10-07
+**Baseline:** Cairnkeep 2.24.0
+**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.23.0
+**Baseline:** Cairnkeep 2.24.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
@@ -42,6 +42,13 @@ match/source/conflict explanations without changing legacy defaults. See
 and its recording supplement. The synthetic Markdown comparison measures
 retrieval policy, not general task quality or a storage-format advantage.
 
+Version 2.24 adds an optional, separately configured ranking
+service, not a chat agent or memory authority. It remains default-off. See
+[its bounded provider comparison and regression](../memory-retrieval.md#optional-learned-reranking)
+before enabling it; L04 and its recording supplement cover the privacy,
+doctor and fallback controls. The default-off team preview is separate and is
+not included in this release.
+
 ## 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.23.0
+**Tested with:** Cairnkeep 2.24.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.23.0
+**Tested with:** Cairnkeep 2.24.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.23.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.24.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.23.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0
+   npm install --global @cairnkeep/cli@2.24.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.23.0
+**Tested with:** Cairnkeep 2.24.0
 
 ## Outcome
 

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

@@ -53,6 +53,18 @@ fact and starting a fresh client, verifying the new value and explicit history.
 - No extracted candidate becomes durable without an explicit review action.
 - Enabling typed nodes changes discovery structure, not the authority of a fact.
 
+## Optional reranker extension
+
+From a source checkout of 2.24.0 or newer, run `npm --prefix mcp-memory-server run check:memory-reranker`
+without a provider. Then, only with explicit synthetic-data/provider consent,
+compare the frozen live study in the retrieval guide. Explain both the 6/16
+to 15/16 first-result improvement and the single regression; this is not a
+general accuracy or agent-productivity claim. Show that reranking is off by
+default, has a separate credential, preserves admission and exact-key priority,
+and falls back without mutating stored facts. A failed provider must make
+`cairn doctor` fail even though search still works. Read-only is not a promise
+of zero network traffic: configured search advertises open-world behavior.
+
 ## Source material
 
 - [Operating guide](../../operating.md#the-workflow)

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.23.0
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0
+npm install --global @cairnkeep/cli@2.24.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.23.0; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.24.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.23.0 or use a disposable source checkout.
+- Install Cairnkeep 2.24.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

@@ -32,3 +32,16 @@ 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.
+
+## Optional reranker segment (2.24.0 or newer source checkout)
+
+Record real `check:memory-reranker` output, pausing on the no-network default,
+scope/history canaries and provider-failure fallback. With explicit synthetic
+provider configuration, run `run-memory-reranker-study.mjs --live --summary`.
+Do not show credentials or endpoint addresses. Compare the two arms using the
+same embeddings: the first frozen run improved first hits from 6/16 to 15/16,
+but `current-not-history` regressed. Zoom into that failure rather than hiding
+it. Explain that the earlier HTTP-502 study is separate and remains a failed
+run. Demonstrate the doctor's synthetic request, then disable reranking and
+show unchanged memory text and provenance. This is a recording brief, not a
+claim that this segment has been filmed or published.

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.

package/docs/mcp-tool-profiles.md

@@ -41,3 +41,10 @@ The default `full` profile preserves the same tool names, schemas, responses,
 feature gates, and ordering as an unconfigured server. The annotations help
 conservative clients distinguish observations from actions; they do not grant
 permission or replace the client's approval policy.
+
+With a valid, explicitly enabled memory reranker, `memory_search` advertises
+`openWorldHint: true` because query and bounded candidate excerpts can reach
+the configured service. It remains `readOnlyHint: true`, so a read-only
+profile still exposes it. Tool restriction is not network consent: omit it
+from a custom profile or disable reranking if that data flow is unwanted.
+With reranking off, existing discovery metadata is unchanged.

package/docs/memory-retrieval.md

@@ -161,8 +161,90 @@ 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.
+its own loopback fixture. A separate optional reranker comparison below does
+not replace this older study or retroactively make that failed run successful.
+
+## Optional learned reranking
+
+Available since Cairnkeep 2.24.0. This feature improves ordering, not guaranteed
+recall: the small live comparison below retained the same Recall@3 in both arms.
+
+The optional reranker is default-off and independent of extraction and
+embeddings. Set `CAIRN_MEMORY_RERANK=1`, `CAIRN_MEMORY_RERANK_URL` (a base URL,
+normally ending in `/v1`) and `CAIRN_MEMORY_RERANK_MODEL` on the memory-server
+process. The client appends `/rerank`. If authentication is needed, set the
+separate `CAIRN_MEMORY_RERANK_API_KEY`; extraction/embedding credentials are
+never reused. `CAIRN_MEMORY_RERANK_TIMEOUT_MS` defaults to 2,000 ms and accepts
+100–10,000 ms. Restart the server after configuration changes.
+
+Only `memory_search` in the `memory` address space is reranked, for either
+legacy or hybrid strategy. Notes, context packs, documents and the separate
+team store are unchanged. Existing scope, current-value, typed and relevance
+filters admit candidates first. The provider receives the original query
+(at most 4 KiB) and at most 50 admitted key/value excerpts (at most 4 KiB each),
+not the whole store. Candidate depth is `min(50, max(32, 4 * top_k))`.
+Exact-key priority in hybrid search (including explicit aliases) and typed legacy exact-hit priority remain
+ahead of model scores. The provider only reorders admitted records; it cannot
+add facts, change authority, write memory or recover a candidate already
+rejected by admission. A small final `top_k` can include a candidate outside
+the original top-k prefix after reranking.
+
+The endpoint must return every candidate index exactly once in a `results`
+array with finite `relevance_score` numbers. Negative raw scores are accepted;
+these are ranking values, not calibrated confidence. Returned memory text,
+provenance and existing retrieval scores are unchanged; those scores need not
+be descending after learned reranking. Ties preserve the
+existing order. Timeout, HTTP errors, redirects, oversized responses, invalid
+configuration or malformed/partial indices preserve the original order.
+No retries or alternate provider fallback are made. Unset/disabled configuration
+performs no reranker request and preserves existing discovery and responses.
+When configured, `memory_search` remains read-only but advertises
+`openWorldHint: true` because it can export candidate text.
+
+`cairn doctor` uses synthetic text to check configured reranking and fails if
+the configuration or response is invalid. Ordinary searches still fall back
+safely; doctor does not mistake fallback for a healthy provider.
+
+### Bounded provider comparison
+
+The frozen `memory-reranker-study-v1.json` fixture contains 20 synthetic
+continuity cases, including 16 positive and four negative cases. Both arms use
+the same embedding vectors, admission rules, aliases and final top three.
+Labels and the fixture digest were frozen before the first live ranking run.
+
+| Metric | Hybrid + embeddings | Same candidates + reranker |
+|---|---:|---:|
+| Relevant first result, 16 positive cases | 6/16 | 15/16 |
+| MRR@3 | 0.635417 | 0.968750 |
+| NDCG@3 | 0.728416 | 0.976933 |
+| Recall@3 | 1.0 | 1.0 |
+| Negative queries returning results, 4 cases | 0/4 | 0/4 |
+
+Ten cases improved and **one regressed**: `current-not-history` ranked a
+topical interface distractor above the correct current fact. Hidden history
+was still excluded. No scope/history violation or provider failure occurred.
+Observed additional ranking latency was 9 ms median and 46 ms p95 in this
+small local run; this is not a deployment latency guarantee.
+
+This is an engineering-labeled synthetic comparison with deliberately
+ambiguous topical distractors, not an independent holdout, a human study or
+proof of general agent-quality gains. It justifies an optional experiment,
+not default enablement. Evaluate your provider and corpus before opting in;
+disable `CAIRN_MEMORY_RERANK` to reverse the change.
+
+From a source checkout (these developer study scripts are not installed CLI
+commands):
+
+```sh
+npm --prefix mcp-memory-server run check:memory-reranker
+# Requires explicit existing embedding and reranker configuration:
+node mcp-memory-server/scripts/run-memory-reranker-study.mjs --live --summary
+```
+
+Without `--live`, the study makes no provider calls even when configured.
+Reports include fixture, implementation and model-ID digests, no URLs or keys.
+The frozen fixture SHA-256 is
+`f6a5d2de8d2846dd5a8de764096d92255716592805e8abfdc771181eac23beb1`.
 
 ## Research connection
 

package/docs/operating.md

@@ -495,6 +495,11 @@ vendor or host.
 | `CAIRN_MEMORY_EMBEDDING_URL` | Embeddings endpoint (falls back to `CAIRN_LLM_API_URL`) |
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
+| `CAIRN_MEMORY_RERANK` | Explicit `1` enables optional learned memory-search reranking; off by default |
+| `CAIRN_MEMORY_RERANK_URL` | Explicit HTTP(S) base URL; client appends `/rerank`; no embedded credentials, query or fragment |
+| `CAIRN_MEMORY_RERANK_MODEL` | Required model identifier when reranking is enabled |
+| `CAIRN_MEMORY_RERANK_API_KEY` | Optional separate reranker credential; no extraction/embedding key fallback |
+| `CAIRN_MEMORY_RERANK_TIMEOUT_MS` | Reranking deadline, default `2000`, allowed `100`–`10000`; failure preserves existing search order |
 | `CAIRN_AGENTFS_BASE_DIR` | Server-side base dir for named/global memory scopes (default `~/.cairnkeep`); it does not affect `project` scope |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; unset/default → no capture work) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per session (default `5242880`, 5 MiB; minimum 1024) |

package/docs/privacy-and-data-flow.md

@@ -3,7 +3,8 @@
 Cairnkeep has no telemetry, analytics collector, hosted control plane, or
 automatic remote-service discovery. A default local stdio installation stores
 memory in SQLite on the machine running the MCP server and makes no model or RAG
-request unless the corresponding endpoint and credential are configured.
+request unless the corresponding feature is explicitly configured as described
+below (some operator-owned endpoints do not require a credential).
 
 ## Data flows
 
@@ -11,6 +12,7 @@ request unless the corresponding endpoint and credential are configured.
 |---|---|---|
 | Local substring search | None | Local SQLite only |
 | Embedding-ranked search | Stored memory values that are not cached, plus the search query | `CAIRN_MEMORY_EMBEDDING_URL` or `CAIRN_LLM_API_URL` |
+| Separately opted-in memory reranking | Query and at most 50 scope/current/filter-admitted key/value excerpts, each at most 4 KiB | Only the explicit `CAIRN_MEMORY_RERANK_URL`; separate optional credential, no retries/redirects/alternate hosts |
 | `memory_extract` | The transcript supplied to the tool | `CAIRN_LLM_API_URL` |
 | `domain_knowledge_query` | Workspace slug and query | `ANYTHINGLLM_BASE_URL` |
 | `domain_knowledge_sync` | Files selected by the sync configuration | `ANYTHINGLLM_BASE_URL` |
@@ -50,6 +52,10 @@ Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
 retention, training, or logging policy; verify it before sending confidential
 material. Disabling `CAIRN_LLM_API_KEY`, `ANYTHINGLLM_API_KEY`, remote HTTP
 registration, and delegated tools keeps the core memory workflow local.
+Also leave `CAIRN_MEMORY_RERANK` unset to disable its independent data flow;
+it does not require or inherit `CAIRN_LLM_API_KEY`. A local provider is still a
+separate process that receives these excerpts. Neither a chat agent nor a
+research assistant is part of reranking or authorization.
 
 ## Playbook decision and receipt flow
 
@@ -91,11 +97,14 @@ backups/journals are sensitive local data at rest. Dry-run and commit responses
 contain scopes/address spaces, digests, keys, actions, and counts—not supplied
 or displaced values. No model, API key, endpoint, or network is required.
 
-The existing explicitly configured embedding search is the sole related egress:
-eligible key/value/type/tag text and the query may be sent to
+Explicitly configured embedding search can send eligible key/value/type/tag
+text and the query to
 `CAIRN_MEMORY_EMBEDDING_URL` (or its documented fallback). Hard filters run
 before that request; endpoint failure returns to local substring search. Note
-search is always local and never uses embeddings.
+search is always local and never uses embeddings or reranking. Separately
+opting into the [bounded reranker](memory-retrieval.md#optional-learned-reranking)
+can also send admitted memory excerpts and the query. It only changes ordering,
+never scope, history admission, approval, factual authority or durable memory.
 
 Canonical note storage includes manifest records, Markdown, indexes, history,
 import replay state, staged bytes, backups, and journals. Prepared/committing

package/examples/eval/bundled-fake.json

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