@remnic/core 9.69.51 → 9.69.53

package/dist/who-knows-cli.d.ts

@@ -1,5 +1,5 @@
-import { W as WhoKnowsResult } from './access-service-BZaC-RZw.js';
-import './types-DCB90q3g.js';
+import { W as WhoKnowsResult } from './access-service-H-qEdnSs.js';
+import './types-Du6VdoAg.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';
@@ -17,13 +17,13 @@ import './active-context-config.js';
 import './local-llm-config.js';
 import './semantic-merge-config.js';
 import './types-continuity.js';
-import './orchestrator-BTqT3F6X.js';
+import './orchestrator-iexgVLow.js';
 import './recall-state.js';
 import './utils/serialize-mutations.js';
 import './search/port.js';
 import './included-memories.js';
 import './briefing.js';
-import './storage-DNQWtOSM.js';
+import './storage-CMm-3aD3.js';
 import './corpus-read-cancellation.js';
 import './artifact-search.js';
 import './active-context-transform.js';
@@ -39,7 +39,7 @@ import './write-envelope.js';
 import './structured-attributes.js';
 import './buffer.js';
 import './extraction-faithfulness.js';
-import './local-llm-BXYC-mbU.js';
+import './local-llm-BkkEK9rn.js';
 import './model-registry.js';
 import './fallback-llm.js';
 import './fallback-llm-codex-subscription.js';
@@ -48,8 +48,8 @@ import './resolve-provider-secret.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
-import './maintenance-zJiLsKBY.js';
-import './catalog-DK2eHhax.js';
+import './maintenance-CLBIvVxg.js';
+import './catalog-BuMyYPUn.js';
 import './namespaces/search.js';
 import './compounding/engine.js';
 import './shared-context/manager.js';
@@ -59,7 +59,7 @@ import './utility-runtime.js';
 import './tier-routing.js';
 import './lifecycle.js';
 import './orchestration/compression-guideline-coordinator.js';
-import './semantic-consolidation-DEzRyeyn.js';
+import './semantic-consolidation-D--qe0eE.js';
 import './connectors/codex-materialize.js';
 import './logger.js';
 import './embedding-fallback.js';
@@ -81,17 +81,17 @@ import './conversation-index/chunker.js';
 import './conversation-index/backend.js';
 import './faiss-adapter-BHecI1fF.js';
 import './runtime/child-process.js';
-import './dependency-propagation-delivery-BMkR4gmY.js';
+import './dependency-propagation-delivery-BrhPjAHQ.js';
 import './namespaces/storage.js';
 import './threading.js';
-import './scope-profiles-Bg1rB-Dp.js';
+import './scope-profiles-BN1Dgfha.js';
 import './graph-DRkl22KE.js';
 import './graph-write-lock.js';
 import './recall-xray.js';
 import './memory-provenance.js';
 import './user-model.js';
 import './recall-context-composition.js';
-import './generic-recall-paths-BCRtXU32.js';
+import './generic-recall-paths-C0J1Oxb7.js';
 import './live-connectors-runner.js';
 import './framework-CNDn2164.js';
 import './relevance.js';
@@ -99,7 +99,7 @@ import './negative.js';
 import './session-observer-state.js';
 import './semantic-BalR6EXU.js';
 import './replay/types.js';
-import './service-DGEIDOeD.js';
+import './service-VealHeqO.js';
 import './extraction-judge.js';
 import './lcm/engine.js';
 import './lcm/archive.js';
@@ -122,7 +122,7 @@ import './types-B1VHaf2w.js';
 import './transfer/capsule-import.js';
 import './transfer/types.js';
 import './recall-navigation.js';
-import './access-namespace-preflight-C1q3XuAc.js';
+import './access-namespace-preflight-U9RAdxqZ.js';
 import './access-token-capabilities.js';
 import 'node:async_hooks';
 import './recall-explain-renderer.js';
@@ -130,7 +130,7 @@ import './access-citation.js';
 import './access-health-types.js';
 import './corpus-watermark.js';
 import './replica-divergence.js';
-import './tagging-CPVwgadt.js';
+import './tagging-BjsNFKWz.js';
 import './explicit-capture.js';
 import './access-wearables-meetings-surface.js';
 import './deep-recall.js';

package/dist/who-knows-cli.js

@@ -4,9 +4,9 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-7TTOX6NW.js";
-import "./chunk-ETNC6TT6.js";
-import "./chunk-RIP2AOZW.js";
+} from "./chunk-SPWNCGSM.js";
+import "./chunk-43IQRLEF.js";
+import "./chunk-QWQB7TOB.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-46WM6JX2.js";
 import "./chunk-D5F7TKMH.js";
@@ -25,14 +25,16 @@ import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
-import "./chunk-PQWICTRO.js";
+import "./chunk-4UVJ6EIT.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
+import "./chunk-S45INSV3.js";
 import "./chunk-J3IWHCMF.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-DUJYRVUD.js";
+import "./chunk-ZIKENA2C.js";
 import "./chunk-PCEYGOSL.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-3ONXXHQO.js";
@@ -52,15 +54,13 @@ import "./chunk-ZLQ37WJX.js";
 import "./chunk-IUM3VSHI.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
+import "./chunk-6Q3ZTEF6.js";
 import "./chunk-ZTHGFTMW.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-EP6BA7VV.js";
 import "./chunk-E2AWJ7KQ.js";
-import "./chunk-S45INSV3.js";
-import "./chunk-ZIKENA2C.js";
-import "./chunk-6Q3ZTEF6.js";
 import "./chunk-YCVB7X56.js";
 import "./chunk-PJKTFXE2.js";
 import "./chunk-W5BIQOAJ.js";
@@ -75,12 +75,12 @@ import "./chunk-BJMBJZ2Y.js";
 import "./chunk-UKJAGEXH.js";
 import "./chunk-FP2373TW.js";
 import "./chunk-L272A5QW.js";
-import "./chunk-SGHGCFVV.js";
+import "./chunk-JE334SIA.js";
 import "./chunk-ZA53AZND.js";
+import "./chunk-7RJUVTVF.js";
 import "./chunk-AL3UYZ5N.js";
 import "./chunk-RL6NEVXT.js";
 import "./chunk-PWPIERBM.js";
-import "./chunk-7RJUVTVF.js";
 import "./chunk-C7HJ3NEI.js";
 import "./chunk-NB3LRY4T.js";
 import "./chunk-5FVVY2EB.js";

package/dist/who-knows.d.ts

@@ -1,6 +1,6 @@
-export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-BZaC-RZw.js';
-import './types-DCB90q3g.js';
-import './orchestrator-BTqT3F6X.js';
+export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-H-qEdnSs.js';
+import './types-Du6VdoAg.js';
+import './orchestrator-iexgVLow.js';
 import './recall-state.js';
 import './utils/serialize-mutations.js';
 import './search/port.js';
@@ -23,7 +23,7 @@ import './semantic-merge-config.js';
 import './types-continuity.js';
 import './included-memories.js';
 import './briefing.js';
-import './storage-DNQWtOSM.js';
+import './storage-CMm-3aD3.js';
 import './corpus-read-cancellation.js';
 import './artifact-search.js';
 import './active-context-transform.js';
@@ -39,7 +39,7 @@ import './write-envelope.js';
 import './structured-attributes.js';
 import './buffer.js';
 import './extraction-faithfulness.js';
-import './local-llm-BXYC-mbU.js';
+import './local-llm-BkkEK9rn.js';
 import './model-registry.js';
 import './fallback-llm.js';
 import './fallback-llm-codex-subscription.js';
@@ -48,8 +48,8 @@ import './resolve-provider-secret.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
-import './maintenance-zJiLsKBY.js';
-import './catalog-DK2eHhax.js';
+import './maintenance-CLBIvVxg.js';
+import './catalog-BuMyYPUn.js';
 import './namespaces/search.js';
 import './compounding/engine.js';
 import './shared-context/manager.js';
@@ -59,7 +59,7 @@ import './utility-runtime.js';
 import './tier-routing.js';
 import './lifecycle.js';
 import './orchestration/compression-guideline-coordinator.js';
-import './semantic-consolidation-DEzRyeyn.js';
+import './semantic-consolidation-D--qe0eE.js';
 import './connectors/codex-materialize.js';
 import './logger.js';
 import './embedding-fallback.js';
@@ -81,17 +81,17 @@ import './conversation-index/chunker.js';
 import './conversation-index/backend.js';
 import './faiss-adapter-BHecI1fF.js';
 import './runtime/child-process.js';
-import './dependency-propagation-delivery-BMkR4gmY.js';
+import './dependency-propagation-delivery-BrhPjAHQ.js';
 import './namespaces/storage.js';
 import './threading.js';
-import './scope-profiles-Bg1rB-Dp.js';
+import './scope-profiles-BN1Dgfha.js';
 import './graph-DRkl22KE.js';
 import './graph-write-lock.js';
 import './recall-xray.js';
 import './memory-provenance.js';
 import './user-model.js';
 import './recall-context-composition.js';
-import './generic-recall-paths-BCRtXU32.js';
+import './generic-recall-paths-C0J1Oxb7.js';
 import './live-connectors-runner.js';
 import './framework-CNDn2164.js';
 import './relevance.js';
@@ -99,7 +99,7 @@ import './negative.js';
 import './session-observer-state.js';
 import './semantic-BalR6EXU.js';
 import './replay/types.js';
-import './service-DGEIDOeD.js';
+import './service-VealHeqO.js';
 import './extraction-judge.js';
 import './lcm/engine.js';
 import './lcm/archive.js';
@@ -122,7 +122,7 @@ import './types-B1VHaf2w.js';
 import './transfer/capsule-import.js';
 import './transfer/types.js';
 import './recall-navigation.js';
-import './access-namespace-preflight-C1q3XuAc.js';
+import './access-namespace-preflight-U9RAdxqZ.js';
 import './access-token-capabilities.js';
 import 'node:async_hooks';
 import './recall-explain-renderer.js';
@@ -130,7 +130,7 @@ import './access-citation.js';
 import './access-health-types.js';
 import './corpus-watermark.js';
 import './replica-divergence.js';
-import './tagging-CPVwgadt.js';
+import './tagging-BjsNFKWz.js';
 import './explicit-capture.js';
 import './access-wearables-meetings-surface.js';
 import './deep-recall.js';

package/dist/who-knows.js

@@ -9,8 +9,8 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-ETNC6TT6.js";
-import "./chunk-RIP2AOZW.js";
+} from "./chunk-43IQRLEF.js";
+import "./chunk-QWQB7TOB.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-46WM6JX2.js";
 import "./chunk-D5F7TKMH.js";
@@ -29,14 +29,16 @@ import "./chunk-F4TWWUMP.js";
 import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
-import "./chunk-PQWICTRO.js";
+import "./chunk-4UVJ6EIT.js";
 import "./chunk-MRPOZBJC.js";
 import "./chunk-S2HLHAZ4.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-LDXUBPMO.js";
+import "./chunk-S45INSV3.js";
 import "./chunk-J3IWHCMF.js";
 import "./chunk-AAD2ZS6P.js";
 import "./chunk-DUJYRVUD.js";
+import "./chunk-ZIKENA2C.js";
 import "./chunk-PCEYGOSL.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-3ONXXHQO.js";
@@ -56,15 +58,13 @@ import "./chunk-ZLQ37WJX.js";
 import "./chunk-IUM3VSHI.js";
 import "./chunk-C64XATK7.js";
 import "./chunk-42JKGUFJ.js";
+import "./chunk-6Q3ZTEF6.js";
 import "./chunk-ZTHGFTMW.js";
 import "./chunk-I55KAVET.js";
 import "./chunk-L2EXJQJP.js";
 import "./chunk-45GF7Y3V.js";
 import "./chunk-EP6BA7VV.js";
 import "./chunk-E2AWJ7KQ.js";
-import "./chunk-S45INSV3.js";
-import "./chunk-ZIKENA2C.js";
-import "./chunk-6Q3ZTEF6.js";
 import "./chunk-YCVB7X56.js";
 import "./chunk-PJKTFXE2.js";
 import "./chunk-W5BIQOAJ.js";
@@ -79,12 +79,12 @@ import "./chunk-BJMBJZ2Y.js";
 import "./chunk-UKJAGEXH.js";
 import "./chunk-FP2373TW.js";
 import "./chunk-L272A5QW.js";
-import "./chunk-SGHGCFVV.js";
+import "./chunk-JE334SIA.js";
 import "./chunk-ZA53AZND.js";
+import "./chunk-7RJUVTVF.js";
 import "./chunk-AL3UYZ5N.js";
 import "./chunk-RL6NEVXT.js";
 import "./chunk-PWPIERBM.js";
-import "./chunk-7RJUVTVF.js";
 import "./chunk-C7HJ3NEI.js";
 import "./chunk-NB3LRY4T.js";
 import "./chunk-5FVVY2EB.js";

package/dist/write-envelope.d.ts

@@ -1,4 +1,4 @@
-import { u as MemoryCategory, N as MemorySubject } from './types-DCB90q3g.js';
+import { u as MemoryCategory, N as MemorySubject } from './types-Du6VdoAg.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.69.51",
+  "version": "9.69.53",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3307,7 +3307,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.69.51"
+    "@remnic/coding-graph": "^9.69.53"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/config.ts

@@ -34,10 +34,6 @@ import { cloneDefaultSessionObserverBands } from "./session-observer-bands.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import { normalizeEntitySchemas } from "./entity-schema.js";
 import { expandTildePath } from "./utils/path.js";
-// Finding 4 (#394): use the shared coerce helper instead of inlining the same
-// boolean-coercion logic that connectors/index.ts already exports. The helper
-// lives in connectors/coerce.ts (a tiny, dependency-free module) so neither
-// config.ts → connectors/index.ts nor the reverse circular import arises.
 import { coerceBool, coerceBooleanLike, coerceInstallExtension, coerceNumber } from "./connectors/coerce.js";
 import { parseSubjectRuntimeConfig } from "./subject-config.js";
 import { parseRecallStateViews } from "./recall-state-view.js";
@@ -58,6 +54,7 @@ import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
 import { parseDeepRecallConfig } from "./deep-recall-config.js";
 import { parseRecallNavigationConfig } from "./recall-navigation-config.js";
 import { parseSessionExperienceConfig } from "./experience/session-experience-config.js";
+import { parseSeedGraduationConfig } from "./lifecycle/seed-graduation.js";
 import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { parseWritePathDedupConfig } from "./dedup/novelty-gate.js";
@@ -639,6 +636,7 @@ const MEMORY_OS_PRESETS: Record<MemoryOsPresetName, Record<string, unknown>> = {
     // explicitly.
     procedural: { enabled: false },
     sessionExperience: { enabled: false },
+    seedGraduation: { enabled: false },
     recallNavigation: { enabled: false },
   },
   balanced: {
@@ -1834,6 +1832,7 @@ export function parseConfig(
     recallNavigation: parseRecallNavigationConfig(cfg.recallNavigation),
     // Session-end experience extraction (issue #2979) — default off.
     sessionExperience: parseSessionExperienceConfig(cfg.sessionExperience),
+    seedGraduation: parseSeedGraduationConfig(cfg.seedGraduation),
     dependencyPropagation: parseDependencyPropagationConfig(cfg),
     // Temporal Supersession (issue #375)
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false, // On by default

package/src/directory-sidecars.test.ts

@@ -8,6 +8,8 @@ import { test } from "node:test";
 import {
   DIRECTORY_SIDECAR_BASENAME,
   DIRECTORY_SIDECAR_MARKER,
+  NEIGHBORHOOD_ABSTRACT_LABEL,
+  applyDirectorySidecarDrillDown,
   findDirectorySidecarsForQuery,
   loadDirectorySidecar,
   parseDirectorySidecarsEnabled,
@@ -385,3 +387,114 @@ test("write-path refresh stays inside the changed namespace and skips unrelated
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+function hit(rel: string, snippet: string, score = 1) {
+  return { path: rel, snippet, score };
+}
+
+test("drill-down is a no-op when disabled even if sidecars exist", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Telescope calibration log for the north dome.");
+    await runDirectorySidecarMaintenance(root, true);
+    const incoming = [hit("facts/2026-01-02/fact-1.md", "Telescope calibration log")];
+    const out = await applyDirectorySidecarDrillDown("/does-not-exist", "telescope", incoming, {
+      enabled: false,
+    });
+    assert.deepEqual(out, incoming);
+    assert.equal(out[0].snippet, "Telescope calibration log");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down attaches the neighborhood abstract to hits under a fresh sidecar", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Telescope calibration log for the north dome.");
+    await writeMemory(root, "facts/2026-01-02/fact-2.md", "Mirror alignment drift measured at 3 arcmin.");
+    await writeMemory(root, "entities/crew-1.md", "Catering roster for the base kitchen.");
+    await runDirectorySidecarMaintenance(root, true);
+
+    const incoming = [
+      hit("facts/2026-01-02/fact-1.md", "Telescope calibration log"),
+      hit("entities/crew-1.md", "Catering roster"),
+    ];
+    const out = await applyDirectorySidecarDrillDown(root, "telescope calibration", incoming, {
+      enabled: true,
+    });
+    assert.match(out[0].snippet, new RegExp(`^${NEIGHBORHOOD_ABSTRACT_LABEL} `));
+    assert.match(out[0].snippet, /Telescope/i);
+    assert.match(out[0].snippet, /Telescope calibration log$/m);
+    assert.equal(out[1].snippet, "Catering roster", "unrelated hit keeps its snippet");
+    assert.equal(out[0].path, incoming[0].path);
+    assert.equal(out[1].path, incoming[1].path);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down skips stale sidecars and does not write", async () => {
+  const root = store();
+  try {
+    const dayDir = path.join(root, "facts", "2026-01-02");
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Boiler pressure nominal.");
+    await runDirectorySidecarMaintenance(root, true);
+    await writeMemory(root, "facts/2026-01-02/fact-2.md", "Coolant pump replaced with spare unit.");
+    const stale = await loadDirectorySidecar(dayDir, { refresh: false });
+    assert.equal(stale?.fresh, false);
+
+    const mtimeBefore = (await stat(path.join(dayDir, DIRECTORY_SIDECAR_BASENAME))).mtimeMs;
+    const out = await applyDirectorySidecarDrillDown(
+      root,
+      "boiler",
+      [hit("facts/2026-01-02/fact-1.md", "Boiler pressure nominal.")],
+      { enabled: true },
+    );
+    assert.equal(out[0].snippet, "Boiler pressure nominal.");
+    const mtimeAfter = (await stat(path.join(dayDir, DIRECTORY_SIDECAR_BASENAME))).mtimeMs;
+    assert.equal(mtimeAfter, mtimeBefore, "retrieval must not refresh a stale sidecar");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down namespace scoping never attaches a foreign abstract", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "namespaces/alpha/facts/2026-05-01/a-1.md", "Alpha wing telescope mirror audit.");
+    await writeMemory(root, "namespaces/beta/facts/2026-05-01/b-1.md", "Beta wing telescope mirror audit.");
+    await runDirectorySidecarMaintenance(root, true);
+
+    const betaHits = [hit("namespaces/beta/facts/2026-05-01/b-1.md", "Beta wing telescope mirror audit.")];
+    const out = await applyDirectorySidecarDrillDown(root, "telescope mirror", betaHits, {
+      enabled: true,
+      namespace: "beta",
+    });
+    assert.match(out[0].snippet, new RegExp(`^${NEIGHBORHOOD_ABSTRACT_LABEL} `));
+    assert.match(out[0].snippet, /Beta wing/i);
+    assert.doesNotMatch(out[0].snippet, /Alpha wing/i);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("drill-down prefers the most specific matching directory", async () => {
+  const root = store();
+  try {
+    await writeMemory(root, "facts/2026-01-02/fact-1.md", "Telescope calibration log for the north dome.");
+    await writeMemory(root, "facts/2026-01-03/fact-2.md", "Guide star acquisition failed twice.");
+    await runDirectorySidecarMaintenance(root, true);
+
+    const out = await applyDirectorySidecarDrillDown(
+      root,
+      "telescope calibration",
+      [hit("facts/2026-01-02/fact-1.md", "Telescope calibration log")],
+      { enabled: true },
+    );
+    assert.match(out[0].snippet, /2026-01-02/);
+    assert.doesNotMatch(out[0].snippet, /Guide star/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/directory-sidecars.ts

@@ -27,12 +27,16 @@
  * sidecar path WITHOUT the marker are user content: never overwritten, never
  * removed.
  *
- * Layer 2 (this slice): {@link refreshDirectorySidecarsAfterWrite} refreshes
- * only the changed directory and its category ancestors, so a memory write
- * populates sidecars without walking the rest of the store. `enabled: false`
- * is a proven no-op (no reads, no writes). Config parsing lives here;
- * `parseConfig` wiring, retrieval drill-down, xray, and LLM summarization
- * remain later layers on #2977 (`config.ts` is at its file-size ratchet).
+ * Layer 2: {@link refreshDirectorySidecarsAfterWrite} refreshes only the
+ * changed directory and its category ancestors. `enabled: false` is a
+ * proven no-op (no reads, no writes).
+ *
+ * Layer 3 (this slice): {@link applyDirectorySidecarDrillDown} scores
+ * fresh sidecars and attaches the winning directory's abstract to hits.
+ * `enabled` stays a function argument — not a parseConfig key (`config.ts`
+ * and `types.ts` are at their file-size ratchets). Retrieval never writes.
+ * xray trajectory, storage write-hook, parseConfig wiring, and LLM
+ * summarization remain later layers on #2977.
  */
 
 import { createHash } from "node:crypto";
@@ -47,6 +51,8 @@ import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
 
 export const DIRECTORY_SIDECAR_BASENAME = "overview.md";
 export const DIRECTORY_SIDECAR_MARKER = "<!-- remnic-directory-sidecar -->";
+/** Prefix prepended to a hit snippet when a fresh directory abstract attaches. */
+export const NEIGHBORHOOD_ABSTRACT_LABEL = "Neighborhood:";
 
 const ABSTRACT_MAX_CHARS = 256;
 const OVERVIEW_MAX_CHARS = 4000;
@@ -87,6 +93,13 @@ export interface DirectorySidecarMatch extends DirectorySidecar {
   readonly score: number;
 }
 
+/** Minimal hit shape drill-down mutates. Extra fields pass through. */
+export interface DirectorySidecarHit {
+  path: string;
+  snippet: string;
+  score: number;
+}
+
 export interface DirectorySidecarReport {
   written: string[];
   removed: string[];
@@ -435,7 +448,7 @@ export async function loadDirectorySidecar(
 export async function findDirectorySidecarsForQuery(
   memoryDir: string,
   query: string,
-  options: { namespace?: string; limit?: number } = {},
+  options: { namespace?: string; limit?: number; refresh?: boolean } = {},
 ): Promise<DirectorySidecarMatch[]> {
   const scope = options.namespace ? path.join(memoryDir, "namespaces", options.namespace) : memoryDir;
   if (!isRealDirectory(scope)) return [];
@@ -447,7 +460,7 @@ export async function findDirectorySidecarsForQuery(
   const matches: DirectorySidecarMatch[] = [];
   for (const root of scopeRoots(scope)) {
     for (const dir of collectSidecarDirs(root)) {
-      const sidecar = await loadDirectorySidecar(dir);
+      const sidecar = await loadDirectorySidecar(dir, { refresh: options.refresh });
       if (!sidecar) continue;
       const abstractLower = sidecar.abstract.toLowerCase();
       const overviewLower = sidecar.overview.toLowerCase();
@@ -466,3 +479,52 @@ export async function findDirectorySidecarsForQuery(
     .filter((candidate) => !matches.some((other) => other.dir.startsWith(`${candidate.dir}${path.sep}`)))
     .slice(0, limit);
 }
+
+function attachNeighborhoodAbstract(snippet: string, abstract: string): string {
+  const line = `${NEIGHBORHOOD_ABSTRACT_LABEL} ${abstract}`;
+  if (snippet === line || snippet.startsWith(`${line}\n`)) return snippet;
+  return snippet.length === 0 ? line : `${line}\n${snippet}`;
+}
+
+function mostSpecificSidecarForHit(
+  memoryDir: string,
+  hitPath: string,
+  matches: readonly DirectorySidecarMatch[],
+): DirectorySidecarMatch | null {
+  if (path.basename(hitPath) === DIRECTORY_SIDECAR_BASENAME) return null;
+  const abs = path.isAbsolute(hitPath) ? path.resolve(hitPath) : path.resolve(memoryDir, hitPath);
+  let best: DirectorySidecarMatch | null = null;
+  for (const match of matches) {
+    const rel = path.relative(match.dir, abs);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) continue;
+    if (best === null || match.dir.length > best.dir.length) best = match;
+  }
+  return best;
+}
+
+/**
+ * Retrieval drill-down (layer 3 of #2977): score fresh directory sidecars
+ * and attach the winning neighborhood abstract to hits under that directory.
+ * `enabled: false` (the default) returns hits unchanged with no I/O.
+ * Never writes. Does not reorder. parseConfig is not consulted.
+ */
+export async function applyDirectorySidecarDrillDown<T extends DirectorySidecarHit>(
+  memoryDir: string,
+  query: string,
+  hits: readonly T[],
+  options: { enabled?: boolean; namespace?: string } = {},
+): Promise<T[]> {
+  if (options.enabled !== true) return [...hits];
+  const matches = await findDirectorySidecarsForQuery(memoryDir, query, {
+    namespace: options.namespace,
+    refresh: false,
+  });
+  const fresh = matches.filter((match) => match.fresh && match.abstract.length > 0);
+  if (fresh.length === 0) return [...hits];
+  return hits.map((hit) => {
+    const match = mostSpecificSidecarForHit(memoryDir, hit.path, fresh);
+    if (!match) return hit;
+    const snippet = attachNeighborhoodAbstract(hit.snippet, match.abstract);
+    return snippet === hit.snippet ? hit : { ...hit, snippet };
+  });
+}