docdex 0.2.61 → 0.2.63

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.63
+- Add the packaged six-layer memory map over HTTP, CLI, and MCP so agents can inspect repo, profile, conversation, diary, temporal-KG, and personal-preferences lanes before selecting a memory surface.
+- Extend packaged wake-up context assembly with optional recent-diary startup episodes, expose diary trace counters, and cover the new memory-layers and wake-up flows with HTTP, CLI, chat, and MCP regression tests.
+- Update the packaged agent guidance to call `docdex_memory_layers` first when memory scope is unclear and to document the six-lane memory model in the shipped prompt assets.
+
+## 0.2.62
+- Expand the packaged personal-preferences surface with claim, snapshot, feedback, and mind-clone flows across HTTP, CLI, and MCP, including review/override/forget controls and clone regression coverage.
+- Harden the packaged installer's local-binary path selection by validating `docdexd --version` output before using explicit or fallback local binaries and by avoiding stale repo-local binaries during registry installs.
+
 ## 0.2.61
 - Add the optional personal-preferences memory subsystem with local capture, background digestion, and packaged HTTP/CLI/MCP controls for status, search, processing, export, redaction, deletion, and purge flows.
 - Align the packaged personal-preferences surface with the top-level `[personal_preferences]` config, richer lineage/materialization, review and retention controls, bounded chat-context injection, and supported-client transcript scanning.

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.61 ----
+---- START OF DOCDEX INFO V0.2.63 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).
@@ -92,6 +92,11 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 | docdex_memory_recall | Retrieve technical facts about the current repo. |
 | docdex_save_preference | Store a global user preference (Style, Tooling, Constraint). |
 | docdex_get_profile | Retrieve global preferences. |
+| docdex_memory_layers | Inspect the six memory layers, their scope/storage, and when each one should be used. |
+
+When unsure which memory lane fits the task, call `docdex_memory_layers` first.
+- Repo memory and profile memory are the core/default lanes.
+- Conversation memory, diary memory, temporal knowledge graph, and personal-preferences memory are selective lanes for continuity, handoff notes, structured recall, and richer user-specific context.
 
 ### D. Conversation Memory + Temporal Knowledge Graph
 
@@ -354,6 +359,7 @@ Do not guess fields; use these canonical shapes.
 - `docdex_dag_export`: `{ project_root, session_id|dag_session_id, format?, max_nodes? }`
 - `docdex_memory_save`: `{ project_root, text }`
 - `docdex_memory_recall`: `{ project_root, query, top_k? }`
+- `docdex_memory_layers`: `{ project_root?, repo_path?, conversation_namespace? }`
 - `docdex_get_profile`: `{ agent_id }`
 - `docdex_save_preference`: `{ agent_id, category, content }`
 - `docdex_local_completion`: `{ task_type, instruction, context, max_tokens?, timeout_ms?, mode?, max_context_chars?, agent?, caller_agent_id?, caller_model?, primary_cost_per_million?, project_root?, repo_path? }`

package/lib/install.js

@@ -219,6 +219,12 @@ function getVersion() {
   return version;
 }
 
+function normalizeVersion(value) {
+  return String(value || "")
+    .trim()
+    .replace(/^v/i, "");
+}
+
 function requestOptions() {
   const headers = { "User-Agent": USER_AGENT };
   const token = process.env.DOCDEX_GITHUB_TOKEN || process.env.GITHUB_TOKEN;
@@ -665,11 +671,7 @@ function shouldPreferLocalInstall({ env, localBinaryPath, pathModule, localRepoR
   if (parseEnvBool(env?.[LOCAL_FALLBACK_ENV]) === false) return false;
   if (env?.[LOCAL_BINARY_ENV]) return true;
   if (env?.npm_lifecycle_event !== "postinstall") return false;
-  if (isLocalInstallRequest({ env, pathModule })) return true;
-  if (!env?.INIT_CWD || !localRepoRoot) return false;
-  const initCwd = pathModule.resolve(env.INIT_CWD);
-  const repoRoot = pathModule.resolve(localRepoRoot);
-  return initCwd === repoRoot || initCwd.startsWith(`${repoRoot}${pathModule.sep}`);
+  return isLocalInstallRequest({ env, pathModule });
 }
 
 function resolveLocalBinaryCandidate({
@@ -746,6 +748,100 @@ async function installFromLocalBinary({
   return { binaryPath: destPath, outcome: "local", outcomeCode: "local" };
 }
 
+function parseBinaryVersionOutput(output) {
+  const text = String(output || "").trim();
+  if (!text) return null;
+  const taggedMatch = text.match(/\bdocdexd\s+v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z._-]+)?)\b/i);
+  if (taggedMatch?.[1]) return normalizeVersion(taggedMatch[1]);
+  const genericMatch = text.match(/\bv?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z._-]+)?)\b/);
+  if (genericMatch?.[1]) return normalizeVersion(genericMatch[1]);
+  return null;
+}
+
+function probeBinaryVersion({
+  binaryPath,
+  spawnSyncFn = spawnSync
+}) {
+  if (!binaryPath) {
+    return { version: null, raw: "", error: "missing_binary" };
+  }
+  const result = spawnSyncFn(binaryPath, ["--version"], {
+    encoding: "utf8"
+  });
+  const raw = [result?.stdout, result?.stderr].filter(Boolean).join("\n").trim();
+  if (result?.error) {
+    return {
+      version: null,
+      raw,
+      error: result.error?.message || String(result.error)
+    };
+  }
+  if (typeof result?.status === "number" && result.status !== 0) {
+    return {
+      version: null,
+      raw,
+      error: raw || `exit_${result.status}`
+    };
+  }
+  const version = parseBinaryVersionOutput(raw);
+  if (!version) {
+    return { version: null, raw, error: "version_unparseable" };
+  }
+  return { version, raw, error: null };
+}
+
+function validateLocalBinaryVersion({
+  binaryPath,
+  expectedVersion,
+  spawnSyncFn = spawnSync
+}) {
+  const probed = probeBinaryVersion({ binaryPath, spawnSyncFn });
+  if (!probed.version) {
+    return {
+      ok: false,
+      reason: probed.error || "version_probe_failed",
+      expectedVersion,
+      detectedVersion: null,
+      raw: probed.raw || ""
+    };
+  }
+  if (normalizeVersion(probed.version) !== normalizeVersion(expectedVersion)) {
+    return {
+      ok: false,
+      reason: "version_mismatch",
+      expectedVersion,
+      detectedVersion: probed.version,
+      raw: probed.raw || ""
+    };
+  }
+  return {
+    ok: true,
+    reason: "matched",
+    expectedVersion,
+    detectedVersion: probed.version,
+    raw: probed.raw || ""
+  };
+}
+
+function buildLocalBinaryVersionError({ binaryPath, validation, explicitEnvOverride = false } = {}) {
+  const expected = validation?.expectedVersion || "unknown";
+  const detected = validation?.detectedVersion || "unknown";
+  const sourceName = explicitEnvOverride ? "DOCDEX_LOCAL_BINARY" : "local Docdex binary";
+  const probeHint = validation?.reason === "version_mismatch"
+    ? `expected ${expected} but found ${detected}`
+    : `version probe failed (${validation?.reason || "unknown"})`;
+  return new InstallerConfigError(
+    `${sourceName} is stale or invalid: ${probeHint}`,
+    {
+      expectedVersion: expected,
+      detectedVersion: validation?.detectedVersion || null,
+      binaryPath: binaryPath || null,
+      explicitEnvOverride,
+      probeOutput: validation?.raw || null
+    }
+  );
+}
+
 async function maybeInstallLocalFallback({
   err,
   env,
@@ -761,7 +857,8 @@ async function maybeInstallLocalFallback({
   writeJsonFileAtomicFn,
   logger,
   localRepoRoot,
-  localBinaryPath
+  localBinaryPath,
+  spawnSyncFn = spawnSync
 }) {
   if (!err || err.code !== "DOCDEX_CHECKSUM_UNUSABLE") return null;
   const allowFallback = parseEnvBool(env[LOCAL_FALLBACK_ENV]);
@@ -778,6 +875,18 @@ async function maybeInstallLocalFallback({
     });
   if (!candidate) return null;
 
+  const validation = validateLocalBinaryVersion({
+    binaryPath: candidate,
+    expectedVersion: version,
+    spawnSyncFn
+  });
+  if (!validation.ok) {
+    logger?.warn?.(
+      `[docdex] local fallback skipped for ${candidate}: expected ${version}, detected ${validation.detectedVersion || "unknown"} (${validation.reason}).`
+    );
+    return null;
+  }
+
   return installFromLocalBinary({
     fsModule,
     pathModule,
@@ -1780,6 +1889,7 @@ async function runInstaller(options) {
   const artifactNameFn = opts.artifactNameFn || artifactName;
   const assetPatternForPlatformKeyFn = opts.assetPatternForPlatformKeyFn || assetPatternForPlatformKey;
   const sha256FileFn = opts.sha256FileFn || sha256File;
+  const spawnSyncFn = opts.spawnSyncFn || spawnSync;
   const writeJsonFileAtomicFn = opts.writeJsonFileAtomicFn || writeJsonFileAtomic;
   const restartFn = opts.restartFn;
   const localRepoRoot =
@@ -1853,6 +1963,18 @@ async function runInstaller(options) {
 
   const forceLocalBinary = Boolean(env?.[LOCAL_BINARY_ENV]);
   if (forceLocalBinary && localBinaryPath) {
+    const validation = validateLocalBinaryVersion({
+      binaryPath: localBinaryPath,
+      expectedVersion: version,
+      spawnSyncFn
+    });
+    if (!validation.ok) {
+      throw buildLocalBinaryVersionError({
+        binaryPath: localBinaryPath,
+        validation,
+        explicitEnvOverride: true
+      });
+    }
     const localInstall = await installFromLocalBinary({
       fsModule,
       pathModule,
@@ -1871,6 +1993,18 @@ async function runInstaller(options) {
   }
 
   if (preferLocal) {
+    const validation = validateLocalBinaryVersion({
+      binaryPath: localBinaryPath,
+      expectedVersion: version,
+      spawnSyncFn
+    });
+    if (!validation.ok) {
+      throw buildLocalBinaryVersionError({
+        binaryPath: localBinaryPath,
+        validation,
+        explicitEnvOverride: false
+      });
+    }
     const localInstall = await installFromLocalBinary({
       fsModule,
       pathModule,
@@ -1951,7 +2085,8 @@ async function runInstaller(options) {
       writeJsonFileAtomicFn,
       logger,
       localRepoRoot,
-      localBinaryPath
+      localBinaryPath,
+      spawnSyncFn
     });
     if (fallback) {
       return fallback;
@@ -2666,5 +2801,8 @@ module.exports = {
   ChecksumResolutionError,
   runInstaller,
   describeFatalError,
-  handleFatal
+  handleFatal,
+  parseBinaryVersionOutput,
+  probeBinaryVersion,
+  validateLocalBinaryVersion
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docdex",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {