dsh-tdai-memory 0.4.0 → 0.4.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Scorp1o117
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Scorp1o117
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,22 +15,22 @@ Part of the [DeepSeek Harness Enhancement Suite](https://github.com/Scorp1o117/d
 A port of **TencentDB Agent Memory** (Tencent Cloud's open-source four-layer
 memory system, originally an OpenClaw plugin) into DeepSeek Harness.
 
-## Compatibility (v0.3.6)
-
-Verified with DSH `0.1.7-rc.2` (Web) and `0.2.0-rc.2` (Desktop runtime) in isolated profiles. The Desktop app uses its own `desktop` profile. Other DSH prereleases remain unverified.
-
-## Desktop install
-
-Use the Desktop-installed `dsh` command (Application → Manage dsh Command), or the app’s Plugins page. Then install into the Desktop profile:
-
-```powershell
-dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
-```
-
-Restart the Desktop app to load the client bundle. Desktop keeps its profile under `$DSH_HOME/profiles/desktop`.
-
-
-## Features
+## Compatibility (v0.4.1)
+
+Verified with DSH `0.1.7-rc.2` (Web) and `0.2.0-rc.2` (Desktop runtime) in isolated profiles. The Desktop app uses its own `desktop` profile. Other DSH prereleases remain unverified.
+
+## Desktop install
+
+Use the Desktop-installed `dsh` command (Application → Manage dsh Command), or the app’s Plugins page. Then install into the Desktop profile:
+
+```powershell
+dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
+```
+
+Restart the Desktop app to load the client bundle. Desktop keeps its profile under `$DSH_HOME/profiles/desktop`.
+
+
+## Features
 
 - **L0 conversation capture**: every turn (turn end, request boundary) is
   written to raw conversation storage (JSONL + SQLite + FTS + vectors)
@@ -69,14 +69,14 @@ Hard-won wiring details:
 
 ## Configuration (profile patch + settings)
 
-Configuration is stored in the `tdai-memory` entry of the active Profile patch.
-On first launch, DSH imports the old `$DSH_HOME/settings.yaml` values into that
-entry. The **Web UI Settings → 记忆**
+Configuration is stored in the `tdai-memory` entry of the active Profile patch.
+On first launch, DSH imports the old `$DSH_HOME/settings.yaml` values into that
+entry. The **Web UI Settings → 记忆**
 section edits every field (v0.2.0, write-only keys); TdaiCore is built at
 startup, so changes apply **after a restart**.
 
-```yaml
-# $DSH_HOME/profiles/web/cordis.patch.yml
+```yaml
+# $DSH_HOME/profiles/web/cordis.patch.yml
 - id: tdai-memory
   name: 'dsh-tdai-memory'
   config:
@@ -107,11 +107,11 @@ then mount it in `$DSH_HOME/profiles/web/cordis.patch.yml`:
 - insert:
     - id: tdai-memory
       name: 'dsh-tdai-memory'
-      config: {}          # fill through Settings → 记忆
+      config: {}          # fill through Settings → 记忆
 ```
 
-and restart `dsh web`. LLM/embedding API keys can be set in the Web UI
-settings page (记忆 / Memory) or in the `tdai-memory` Profile patch entry.
+and restart `dsh web`. LLM/embedding API keys can be set in the Web UI
+settings page (记忆 / Memory) or in the `tdai-memory` Profile patch entry.
 
 > **Note for users**
 > - This plugin is a standard **profile bundle** (`dsh.bundle.patch`):
@@ -140,6 +140,14 @@ not need it. Users who select the local backend should install and approve
   stored=0); off by default; enable only with a more reliable model
 - **L1 memory vectors**: written with storage (8088 embedding is fast); L0
   vectors run as a background task, drained by `destroy()` on headless exit
+- **Search tools** (`toolsEnabled`, on by default): the switch lives in the
+  Plugins page and applies in place — the row config is `volatile`, so the
+  plugin re-syncs its registration without a restart. If both tools are
+  missing, look for the plugin's
+  `[tdai-memory] tools registered: tdai_memory_search, tdai_conversation_search`
+  log line (v0.4.1+). Before v0.4.1 it read `config.toolsEnabled` off the
+  Volatile wrapper cordis hands to `apply` — a property that never exists — so
+  the failure was completely silent (issue #3)
 - **Upgrades**: after pulling new upstream code, rerun
   `npx tsc -p dsh-tsconfig.json` in the tdai project dir (output in `dist-dsh/`)
 
@@ -147,5 +155,5 @@ not need it. Users who select the local backend should install and approve
 
 MIT
 
-
-Saves use the configuration form API. Rejected writes retain the draft and show an error. Changing a model preserves credentials, and disabling a default-on option explicitly stores `false`.
+
+Saves use the configuration form API. Rejected writes retain the draft and show an error. Changing a model preserves credentials, and disabling a default-on option explicitly stores `false`.

package/README.zh.md

@@ -12,22 +12,22 @@
 
 把 **TencentDB Agent Memory**（腾讯云开源的四层记忆系统，原为 OpenClaw 插件）移植进 DeepSeek Harness。
 
-## 兼容性（v0.3.6）
-
-已在 DSH `0.1.7-rc.2`（Web）与 `0.2.0-rc.2`（桌面端运行时）的一次性 Profile 验证。桌面端使用独立的 `desktop` Profile；其他预发布版本暂未验证。
-
-## 桌面端安装
-
-在桌面端的“插件”页面安装，或使用桌面端“应用 → 管理 dsh 命令”注册的命令：
-
-```powershell
-dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
-```
-
-重启桌面端以加载客户端插件。配置位于 `$DSH_HOME/profiles/desktop`。
-
-
-## 能力
+## 兼容性（v0.4.1）
+
+已在 DSH `0.1.7-rc.2`（Web）与 `0.2.0-rc.2`（桌面端运行时）的一次性 Profile 验证。桌面端使用独立的 `desktop` Profile；其他预发布版本暂未验证。
+
+## 桌面端安装
+
+在桌面端的“插件”页面安装，或使用桌面端“应用 → 管理 dsh 命令”注册的命令：
+
+```powershell
+dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
+```
+
+重启桌面端以加载客户端插件。配置位于 `$DSH_HOME/profiles/desktop`。
+
+
+## 能力
 
 - **L0 对话捕获**：每轮对话（turn 结束、请求边界）自动写入原始对话（JSONL + SQLite + FTS + 向量）
 - **L1 结构化记忆**：后台管线用 LLM 从对话中提取事实/偏好/事件（persona / episodic / instruction），写入 `records/` + SQLite + FTS + 向量
@@ -96,7 +96,8 @@ tdai-memory:
 - **提取模型**：`mimo-v2.5` 提取正确但单次 20-30s（后台执行，不阻塞对话）；`deepseek-v4-flash` 快但 JSON 输出不合规（提取 0 条）
 - **dedup**：LLM 冲突检测输出解析不稳（曾导致 stored=0），默认关闭；开启需换更稳的模型
 - **L1 记忆向量**：随存储写入（8088 embedding 快）；L0 向量走后台任务，headless 退出时由 `destroy()` drain
+- **搜索工具**（`toolsEnabled`，默认开启）：开关在插件页，切换后**原地生效**（行配置是 `volatile`，无需重启即重新注册）。若两个工具完全缺失，可查插件日志 `[tdai-memory] tools registered: …`（v0.4.1 起）；v0.4.1 之前它读的是 cordis 交给 `apply` 的 Volatile 包装对象上的 `config.toolsEnabled` —— 那个属性永远不存在，因此整个失败过程完全静默（issue #3）
 - **升级**：上游拉新代码后，在 tdai 项目目录重跑 `npx tsc -p dsh-tsconfig.json`（产物在 `dist-dsh/`）
 
-
-保存使用配置表单 API；宿主拒绝写入时保留草稿并提示错误。只修改模型不会覆盖密钥，关闭默认开启的选项会显式保存 `false`。
+
+保存使用配置表单 API；宿主拒绝写入时保留草稿并提示错误。只修改模型不会覆盖密钥，关闭默认开启的选项会显式保存 `false`。

package/THIRD-PARTY-NOTICES.md

@@ -1,20 +1,20 @@
-# Third-party notices
-
-## TencentDB Agent Memory core (vendored in `vendor/tdai`)
-
-`vendor/tdai` is a TypeScript-compiled copy of the host-neutral core of
-[TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
-(`tdai-memory-openclaw-plugin`, npm: `@tencentdb-agent-memory/memory-tencentdb`),
-compiled with `tsc -p dsh-tsconfig.json` (see the upstream repo for source).
-Its runtime dependencies are declared in this package's `dependencies`.
-
-MIT License — Copyright (c) 2026 TencentCloud
-
-## Runtime dependencies
-
-- `ai` / `@ai-sdk/openai` — Vercel AI SDK (Apache-2.0)
-- `@node-rs/jieba` — Rust jieba bindings (MIT)
-- `sqlite-vec` — vector search extension for SQLite (Apache-2.0 / MIT)
-- `json5` — JSON5 parser (MIT)
-- `undici` — HTTP client (MIT)
-- `@tencentdb-agent-memory/tcvdb-text` — TencentDB text utilities (MIT)
+# Third-party notices
+
+## TencentDB Agent Memory core (vendored in `vendor/tdai`)
+
+`vendor/tdai` is a TypeScript-compiled copy of the host-neutral core of
+[TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
+(`tdai-memory-openclaw-plugin`, npm: `@tencentdb-agent-memory/memory-tencentdb`),
+compiled with `tsc -p dsh-tsconfig.json` (see the upstream repo for source).
+Its runtime dependencies are declared in this package's `dependencies`.
+
+MIT License — Copyright (c) 2026 TencentCloud
+
+## Runtime dependencies
+
+- `ai` / `@ai-sdk/openai` — Vercel AI SDK (Apache-2.0)
+- `@node-rs/jieba` — Rust jieba bindings (MIT)
+- `sqlite-vec` — vector search extension for SQLite (Apache-2.0 / MIT)
+- `json5` — JSON5 parser (MIT)
+- `undici` — HTTP client (MIT)
+- `@tencentdb-agent-memory/tcvdb-text` — TencentDB text utilities (MIT)

package/cordis.patch.yml

@@ -1,8 +1,8 @@
-# dsh-tdai-memory — bundle patch layer
-#
-# Declares the plugin as a Cordis loader entry, making the package a standard
-# profile bundle: `dsh plugin --profile <p> add dsh-tdai-memory` installs and
-# mounts it without manual cordis.patch.yml edits.
-- insert:
-    - id: tdai-memory
-      name: 'dsh-tdai-memory'
+# dsh-tdai-memory — bundle patch layer
+#
+# Declares the plugin as a Cordis loader entry, making the package a standard
+# profile bundle: `dsh plugin --profile <p> add dsh-tdai-memory` installs and
+# mounts it without manual cordis.patch.yml edits.
+- insert:
+    - id: tdai-memory
+      name: 'dsh-tdai-memory'

package/index.js

@@ -37,7 +37,7 @@ const Config = z.object({
   /** TDAI data directory; default: ~/.memory-tencentdb/memory-tdai. */
   dataDir: z.string().default(""),
   /** LLM used for L1/L2/L3 extraction (OpenAI-compatible). Falls back to TDAI_LLM_* env. */
-  llm: z.object({
+  llm: z.object({
     baseUrl: z.string().default(""),
     apiKey: z.string().default("").role("secret"),
     model: z.string().default(""),
@@ -52,34 +52,34 @@ const Config = z.object({
     sessionHeaderName: z.string().default("x-opencode-session"),
     /** Fixed session id for LLM requests; empty = persistent auto id. */
     sessionId: z.string().default(""),
-  }).default({}),
+  }).default({}),
   /** Embedding endpoint (OpenAI-compatible /v1/embeddings). */
-  embedding: z.object({
+  embedding: z.object({
     baseUrl: z.string().default("http://127.0.0.1:8088/v1"),
     apiKey: z.string().default("").role("secret"),
     model: z.string().default("Qwen3-Embedding-0.6B"),
     dimensions: z.number().default(1024),
     sendDimensions: z.boolean().default(false),
-  }).default({}),
+  }).default({}),
   /** Capture conversations into L0. */
   captureEnabled: z.boolean().default(true),
   /** L1 extraction pipeline (facts from conversations). */
-  extraction: z.object({
+  extraction: z.object({
     enabled: z.boolean().default(true),
     /** Conflict detection before storing; extra LLM call, disable if flaky.
      *  Off by default: dedup LLM output parsing is flaky (README matches). */
     enableDedup: z.boolean().default(false),
-  }).default({}),
+  }).default({}),
   /** Recall injection settings. */
-  recall: z.object({
+  recall: z.object({
     enabled: z.boolean().default(true),
     maxResults: z.number().default(5),
     scoreThreshold: z.number().default(0.3),
     timeoutMs: z.number().default(3000),
-  }).default({}),
+  }).default({}),
   /** Register the two search tools. */
   toolsEnabled: z.boolean().default(true),
-}).volatile();
+}).volatile();
 
 /**
  * Whether a derived message is real human input.
@@ -106,18 +106,31 @@ function extractText(content) {
     .trim();
 }
 
+/**
+ * Resolve the config value handed to `apply`.
+ *
+ * The row schema ends in `.volatile()` (hot-reloadable config). Config
+ * validation runs through the standard-schema path, which returns the
+ * validated object wrapped in a cosmokit `Volatile`: a frozen `{ get() }`
+ * reference whose OWN properties are always `undefined`. Reading
+ * `config.toolsEnabled` off it can therefore never be true — the tools guard
+ * did exactly that and silently stopped registering the search tools in
+ * v0.3.4 (issue #3). Read config through this helper only.
+ *
+ * The wrapper is a live reference (`updateVolatile` swaps its inner value), so
+ * calling this at use time — not once at startup — sees volatile edits.
+ */
+function runtimeConfigOf(config) {
+  return typeof config?.get === "function" ? config.get() : config;
+}
+
 function apply(ctx, config) {
   // ── build-once state (rebuildable) ───────────────────────────────────────
-  // TdaiCore is built from the RESOLVED settings value (composition entry as
-  // base, `tdai-memory` settings section / settings.yaml as user layer), so
-  // keys stored in settings.yaml (llm.apiKey etc.) are honored. The settings
-  // inject callback that drives `installSettingsSection`'s setSource is
-  // scheduled by cordis as a plugin start — it ALWAYS runs after any 0ms
-  // timer — so the no-settings fallback below cannot be allowed to win the
-  // race. Instead of racing, we let the fallback build from the entry config
-  // first (guaranteeing a working core even without settings), and REBUILD
-  // from the resolved settings when the settings mount arrives. The fallback
-  // is a one-shot; the settings build always wins afterwards.
+  // TdaiCore is built once from the resolved row config: the composition entry
+  // as base with the Plugins-page values merged in by the host (settings.yaml is
+  // no longer a config source since v0.4.0 — see client.js `configForms`). The
+  // build is deferred past the 0ms window so web/headless boots are never
+  // blocked on TdaiCore's stores and embedding client.
   let core = null;
   let tdaiConfig = null;
   let dataDir = "";
@@ -339,69 +352,137 @@ function apply(ctx, config) {
   }
 
   // ── tools ────────────────────────────────────────────────────────────────
-  if (config.toolsEnabled) {
-    ctx.tools.register(defineTool({
-      name: "tdai_memory_search",
-      description:
-        "Search structured long-term memories (facts, preferences, and experiences extracted from past conversations). " +
-        "Use this to recall what the user told you or what happened in earlier sessions.",
-      parameters: {
-        query: { type: "string", required: true, description: "The memory to search for." },
-        limit: { type: "integer", description: "Maximum results (default 5)." },
-      },
-      output: {
-        schema: { type: "string" },
-        render: (_args, value) => [{ type: "text", text: value }],
-      },
-      async execute(args) {
-        const result = await core.searchMemories({ query: args.query, limit: args.limit ?? 5 });
-        return result.text;
-      },
-    }));
-    ctx.tools.register(defineTool({
-      name: "tdai_conversation_search",
-      description:
-        "Search raw past conversation logs (L0) by keyword. Use this to look up exact quotes or details " +
-        "that structured memory search does not cover.",
-      parameters: {
-        query: { type: "string", required: true, description: "Text to find in past conversations." },
-        limit: { type: "integer", description: "Maximum results (default 5)." },
-      },
-      output: {
-        schema: { type: "string" },
-        render: (_args, value) => [{ type: "text", text: value }],
-      },
-      async execute(args) {
-        const result = await core.searchConversations({ query: args.query, limit: args.limit ?? 5 });
-        return result.text;
-      },
-    }));
+  // `toolsEnabled` defaults to true (schema `.default(true)`), so only an
+  // explicit `false` turns the two search tools off. Read through
+  // `runtimeConfigOf` — the volatile row config has no plain properties (#3).
+  let toolsRegistered = false;
+  let toolsDeferred = false;
+  let toolsDisposers = [];
+
+  /** The core, or a clear error while the first build is still in flight. */
+  function requireCore() {
+    if (!core) throw new Error("tdai-memory is still initializing; retry this call in a moment");
+    return core;
+  }
+
+  function registerTools(tools) {
+    if (toolsRegistered) return;
+    if (typeof tools?.register !== "function") {
+      ctx.logger.warn("[tdai-memory] tools service does not expose register(); search tools stay unavailable");
+      return;
+    }
+    toolsRegistered = true;
+    toolsDisposers = [
+      tools.register(defineTool({
+        name: "tdai_memory_search",
+        description:
+          "Search structured long-term memories (facts, preferences, and experiences extracted from past conversations). " +
+          "Use this to recall what the user told you or what happened in earlier sessions.",
+        parameters: {
+          query: { type: "string", required: true, description: "The memory to search for." },
+          limit: { type: "integer", description: "Maximum results (default 5)." },
+        },
+        output: {
+          schema: { type: "string" },
+          render: (_args, value) => [{ type: "text", text: value }],
+        },
+        async execute(args) {
+          const result = await requireCore().searchMemories({ query: args.query, limit: args.limit ?? 5 });
+          return result.text;
+        },
+      })),
+      tools.register(defineTool({
+        name: "tdai_conversation_search",
+        description:
+          "Search raw past conversation logs (L0) by keyword. Use this to look up exact quotes or details " +
+          "that structured memory search does not cover.",
+        parameters: {
+          query: { type: "string", required: true, description: "Text to find in past conversations." },
+          limit: { type: "integer", description: "Maximum results (default 5)." },
+        },
+        output: {
+          schema: { type: "string" },
+          render: (_args, value) => [{ type: "text", text: value }],
+        },
+        async execute(args) {
+          const result = await requireCore().searchConversations({ query: args.query, limit: args.limit ?? 5 });
+          return result.text;
+        },
+      })),
+    ];
+    ctx.logger.info("[tdai-memory] tools registered: tdai_memory_search, tdai_conversation_search");
+  }
+
+  function unregisterTools() {
+    for (const dispose of toolsDisposers.splice(0)) {
+      try {
+        dispose();
+      } catch (error) {
+        ctx.logger.warn(`[tdai-memory] tool dispose failed: ${String(error)}`);
+      }
+    }
+    toolsRegistered = false;
+    ctx.logger.info("[tdai-memory] tools unregistered (toolsEnabled=false)");
   }
 
-  // ── settings-backed configuration ─────────────────────────────────────────
-  // The composition entry stays the base layer; a registered `tdai-memory`
-  // settings section overlays it (settings.yaml). The source is a GETTER
-  // (`() => scope.get()`), not the config object — we must call it to obtain
-  // the resolved settings. The settings mount (cordis inject) always arrives
-  // after our fallback timer, so the fallback builds the core from the entry
-  // config first (one-shot) and the settings build REBUILDS the core with the
-  // resolved values (apiKey included).
-  // Compat shim: dsh-settings 0.1.2-rc.1 removed the module-level
-  // `installSettingsSection` export (the provider now lives at ctx.settings).
-  // Inline the same logic via ctx.inject(["settings"]) — works on both
-  // 0.1.1 (module export wrapper) and 0.1.2 (ctx.settings) hosts.
-  ctx.on("settings/document-updated", (id) => {
-    if (id === NS) ctx.logger.warn("[tdai-memory] settings updated; restart to apply (TdaiCore is built at startup)");
-  });
+  /** Align tool registration with the live `toolsEnabled` value. */
+  function syncTools() {
+    if (runtimeConfigOf(config)?.toolsEnabled === false) {
+      if (toolsRegistered) unregisterTools();
+      return;
+    }
+    if (toolsRegistered || toolsDeferred) return;
+    // `tools` is in this plugin's `inject`, so the service is normally live
+    // here; `ctx.inject` is the fallback for hosts that mount it later. The old
+    // one-shot `ctx.tools` property read registered nothing and said nothing.
+    const tools = ctx.tools ?? ctx.get?.("tools");
+    if (tools === undefined) {
+      toolsDeferred = true;
+      ctx.logger.warn("[tdai-memory] tools service not ready; deferring search-tool registration");
+      ctx.inject(["tools"], (toolCtx) => {
+        toolsDeferred = false;
+        const deferred = toolCtx.tools ?? toolCtx.get?.("tools");
+        if (deferred === undefined) {
+          ctx.logger.warn("[tdai-memory] tools service still unavailable; search tools stay unavailable");
+          return;
+        }
+        registerTools(deferred);
+      });
+      return;
+    }
+    registerTools(tools);
+  }
+
+  // `toolsEnabled` is a volatile config path, so flipping it (Plugins page)
+  // updates the running fiber in place instead of remounting this plugin: the
+  // loader reports that as `loader/volatile-update`, and this keeps the
+  // registration in sync with the new value.
+  ctx.on("loader/volatile-update", () => {
+    try {
+      syncTools();
+    } catch (error) {
+      ctx.logger.warn(`[tdai-memory] tool sync failed: ${String(error)}`);
+    }
+  });
+
+  syncTools();
+
+  // ── configuration changes ─────────────────────────────────────────────────
+  // Configuration lives in the Plugins page (client.js → configForms), i.e. in
+  // this row's own config. Because the row schema is `.volatile()`, an edit is
+  // applied to the running fiber in place — the loader reports it as
+  // `loader/volatile-update` (the tools above re-sync on it) — while TdaiCore
+  // is built at startup, so an edit that must reach the core needs a plugin
+  // reload. Legacy settings documents are only reported here.
+  ctx.on("settings/document-updated", (id) => {
+    if (id === NS) ctx.logger.warn("[tdai-memory] settings updated; restart to apply (TdaiCore is built at startup)");
+  });
 
-  // Fallback when no settings service ever mounts: build from the entry
-  // config. One-shot — if the settings mount arrives later, its build
-  // supersedes this one. Delayed past the 0ms window so headless/web boots
-  // are never blocked on this timer.
+  // Deferred first build (see the note at the top of apply).
   setTimeout(() => {
     if (!builtOnce) {
       builtOnce = true;
-      void build(typeof config.get === "function" ? config.get() : config);
+      void build(runtimeConfigOf(config));
     }
   }, 500);