@nowledge/openclaw-nowledge-mem 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -2,15 +2,38 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [0.6.8] - 2026-02-27
+
+### Changed
+
+- **Config priority flipped**: `~/.nowledge-mem/openclaw.json` now takes priority over OpenClaw plugin settings. Most users configure via OpenClaw UI (no file needed). Users who create the file get predictable overrides.
+- **No auto-created config file**: The plugin no longer creates `~/.nowledge-mem/openclaw.json` on first startup. OpenClaw's settings UI works out of the box. Create the file manually when you need persistent or scripted config.
+- **Status tool shows config sources**: `nowledge_mem_status` now shows where each setting comes from (`file`, `pluginConfig`, `env`, or `default`).
+
+### Fixed
+
+- **configSchema broke OpenClaw form UI**: `additionalProperties: true` (added in 0.6.7) caused OpenClaw's config form to show "Unsupported schema mode. Use Raw mode." Removed the field entirely - JSON Schema defaults to allowing additional properties when omitted, so typos still don't crash the plugin, and the form renders normally.
+
+## [0.6.7] - 2026-02-27
+
+### Added
+
+- `nowledge_mem_status` tool: verify effective config, backend connectivity, and version. Shows mode (local/remote), whether API key is set, backend health, and all config values. 10 tools total.
+
+### Fixed
+
+- **configSchema too strict**: `additionalProperties` changed from `false` to `true`. Previously, a typo in openclaw.json config (e.g. `sesionContext`) caused the plugin to silently fail to load. Now OpenClaw passes validation and the plugin's own parser gives a descriptive error listing valid keys.
+- **apiUrl port typo**: configSchema description had port 14142 instead of 14242.
+
 ## [0.6.6] - 2026-02-27
 
 ### Changed - Config file + env var cascade
 
 **Config file at `~/.nowledge-mem/openclaw.json`**
 
-The plugin now reads configuration from a dedicated config file, independent of OpenClaw's `openclaw.json`. The file is auto-created on first startup with sensible defaults. If you had settings in OpenClaw's plugin config, those values are automatically migrated into the file on first run. No manual steps needed.
+The plugin now reads configuration from a dedicated config file, independent of OpenClaw's `openclaw.json`. The file is auto-created on first startup with sensible defaults. If you had settings in OpenClaw's plugin config, those values are automatically seeded into the file on first run. No manual steps needed.
 
-This ensures your settings survive OpenClaw version upgrades that may strip custom plugin config fields (observed in OpenClaw >= 2026.2.25).
+This gives you a single, easy-to-find place for all Nowledge Mem settings. The file persists across plugin reinstalls and OpenClaw upgrades.
 
 **Config cascade** (4 layers, highest to lowest priority):
 1. `api.pluginConfig` - from OpenClaw's plugin config (when supported)
@@ -34,7 +57,7 @@ This ensures your settings survive OpenClaw version upgrades that may strip cust
 
 ### Added - Thread tools + sourceThreadId linkage
 
-**Two new tools for conversation retrieval.** The plugin now provides 9 tools total.
+**Two new tools for conversation retrieval.**
 
 - `nowledge_mem_thread_search` - search past conversations by keyword. Returns matched threads with message snippets and relevance scores. Use when the user asks about a past discussion or wants to find a specific conversation.
 - `nowledge_mem_thread_fetch` - fetch full messages from a specific thread with pagination support. Use to progressively retrieve long conversations. Accepts `offset` and `limit` for paginated retrieval.

package/CLAUDE.md

@@ -28,7 +28,7 @@ Reflects Nowledge Mem's genuine v0.6 strengths:
 src/
   index.js          - plugin registration (tools, hooks, commands, CLI)
   client.js         - CLI wrapper with API fallback; credential handling
-  config.js         - config cascade: pluginConfig > ~/.nowledge-mem/openclaw.json > env vars > defaults
+  config.js         - config cascade: ~/.nowledge-mem/openclaw.json > pluginConfig > env vars > defaults
   hooks/
     behavioral.js   - always-on behavioral guidance (~50 tokens/turn)
     recall.js       - before_prompt_build: inject Working Memory + recalled memories
@@ -44,10 +44,10 @@ src/
     thread-search.js    - search past conversations by keyword
     thread-fetch.js     - fetch full messages from a thread with pagination
 openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
-~/.nowledge-mem/openclaw.json - user config file (auto-created on first run)
+~/.nowledge-mem/openclaw.json - optional user config file (overrides OpenClaw settings when present)
 ```
 
-## Tool Surface (9 tools)
+## Tool Surface (10 tools)
 
 ### OpenClaw Memory Slot (required for system prompt activation)
 - `memory_search` - multi-signal: BM25 + embedding + label + graph + decay. Returns `matchedVia` ("Text Match 100% + Semantic 69%"), `importance`, bi-temporal filters (`event_date_from/to`, `recorded_date_from/to`). Also returns `relatedThreads` (past conversation snippets matching the query) and `sourceThreadId` (link to source conversation). Mode: `"multi-signal"`.
@@ -64,6 +64,9 @@ openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
 - `nowledge_mem_thread_search` - search past conversations by keyword. Returns threads with matched message snippets, relevance scores, and message counts. Supports `source` filter.
 - `nowledge_mem_thread_fetch` - fetch full messages from a specific thread. Supports pagination via `offset` + `limit` for progressive retrieval of long conversations.
 
+### Diagnostics
+- `nowledge_mem_status` - show effective config (mode, apiUrl, apiKey set, sessionContext, sessionDigest, etc.), backend connectivity, and version. No parameters.
+
 ## Hook Surface
 
 - `before_prompt_build` (always-on) - behavioral guidance: brief note telling agent to save/search proactively. Adjusts when sessionContext is on to avoid redundant searches.
@@ -80,7 +83,7 @@ openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
 
 ## Config Keys
 
-Config file at `~/.nowledge-mem/openclaw.json` (auto-created on first run). Also supports env vars and pluginConfig.
+Optional config file at `~/.nowledge-mem/openclaw.json`. Falls through to OpenClaw plugin settings when the file is absent.
 
 | Key | Type | Default | Env Var | Description |
 |-----|------|---------|---------|-------------|
@@ -91,7 +94,9 @@ Config file at `~/.nowledge-mem/openclaw.json` (auto-created on first run). Also
 | `apiUrl` | string | `""` | `NMEM_API_URL` | Remote server URL. Empty = local (127.0.0.1:14242) |
 | `apiKey` | string | `""` | `NMEM_API_KEY` | API key. Never logged. |
 
-**Priority**: pluginConfig > config file > env var > default.
+**Priority**: config file > pluginConfig > env var > default.
+
+`parseConfig()` returns `_sources` object tracking where each value came from (`"file"`, `"pluginConfig"`, `"env"`, `"default"`). Used by `nowledge_mem_status` tool.
 
 Legacy aliases accepted silently in all sources for backward compat:
 `autoRecall`→`sessionContext`, `autoCapture`→`sessionDigest`, `captureMinInterval`→`digestMinInterval`, `maxRecallResults`→`maxContextResults`.
@@ -99,7 +104,6 @@ Legacy aliases accepted silently in all sources for backward compat:
 ### Credential Handling Rules
 - `apiKey` → ONLY via child process env (`NMEM_API_KEY`). Never CLI arg, never logged.
 - `apiUrl` → passed as `--api-url` flag to CLI (not a secret).
-- Config values win over environment variables.
 - `_spawnEnv()` builds per-spawn env; `_apiUrlArgs()` adds `--api-url` when non-default.
 
 ## CLI Surface (nmem commands used by plugin)

package/README.md

@@ -32,13 +32,15 @@ Start Nowledge Mem desktop app or run `nmem serve`, then enable the plugin:
 }
 ```
 
-That's it. The agent gets 9 tools and calls them on demand. No extra tokens wasted.
+That's it. The agent gets 10 tools and calls them on demand. No extra tokens wasted.
 
 ### Remote mode
 
 Connect to a Nowledge Mem server running elsewhere (a VPS, a home server, or a shared team instance). See [remote access guide](https://mem.nowledge.co/docs/remote-access) for server setup.
 
-Enable the plugin the same way as local mode, then set your remote server in `~/.nowledge-mem/openclaw.json`:
+Enable the plugin the same way as local mode, then set `apiUrl` and `apiKey` in the OpenClaw plugin settings.
+
+Or use a config file at `~/.nowledge-mem/openclaw.json`:
 
 ```json
 {
@@ -62,7 +64,7 @@ flowchart TD
     B --> C["Behavioral guidance(always, ~110 tokens)"]
     B -.->|"sessionContext: true"| D["Working Memory +relevant memories (~1-2 KB)"]
 
-    C --> E["Agent processes message(9 tools available)"]
+    C --> E["Agent processes message(10 tools available)"]
     D --> E
 
     E --> F{"Needs past context?"}
@@ -91,6 +93,7 @@ The behavioral hook nudges the agent to **search before answering** and **save a
 | Memory has `sourceThreadId` | `nowledge_mem_thread_fetch` | Fetch full source conversation. Pagination via `offset` + `limit`. |
 | "Find our discussion about X" | `nowledge_mem_thread_search` | Search past conversations by keyword. Returns matched snippets. |
 | "Forget X" | `nowledge_mem_forget` | Delete by ID or search query. |
+| "Is my setup working?" | `nowledge_mem_status` | Show effective config, backend connectivity, and version. |
 
 ### Session Lifecycle (Automatic Capture)
 
@@ -153,21 +156,21 @@ flowchart LR
     subgraph "default" ["Default (recommended)"]
         direction TB
         D1["Every turn: behavioral guidance (~50 tokens)"]
-        D2["Agent calls 9 tools on demand"]
+        D2["Agent calls 10 tools on demand"]
         D3["Session end: thread capture + LLM distillation"]
     end
 
     subgraph context ["Session Context"]
         direction TB
         C1["Every turn: guidance + Working Memory+ recalled memories (~1-2 KB)"]
-        C2["Agent calls 9 tools on demand"]
+        C2["Agent calls 10 tools on demand"]
         C3["Session end: thread capture + LLM distillation"]
     end
 
     subgraph minimal ["Minimal"]
         direction TB
         M1["Every turn: behavioral guidance (~50 tokens)"]
-        M2["Agent calls 9 tools on demand"]
+        M2["Agent calls 10 tools on demand"]
         M3["No automatic capture"]
     end
 ```
@@ -254,8 +257,8 @@ The plugin supports three modes. Choose based on how much you want to guarantee
 
 | Mode | Config | Behavior | Tradeoff |
 |------|--------|----------|----------|
-| **Default** (recommended) | `sessionContext: false, sessionDigest: true` | Agent calls 9 tools on demand. Behavioral guidance every turn (~50 tokens). Conversations captured + distilled at session end. | Lowest cost. Agent decides when to search, usually smart, occasionally forgets. |
-| **Session context** | `sessionContext: true` | Working Memory + relevant memories injected at prompt time, plus all 9 tools still available. | ~1-2 KB/turn. Guarantees context is always present. Best for short sessions or critical workflows. |
+| **Default** (recommended) | `sessionContext: false, sessionDigest: true` | Agent calls 10 tools on demand. Behavioral guidance every turn (~50 tokens). Conversations captured + distilled at session end. | Lowest cost. Agent decides when to search, usually smart, occasionally forgets. |
+| **Session context** | `sessionContext: true` | Working Memory + relevant memories injected at prompt time, plus all 10 tools still available. | ~1-2 KB/turn. Guarantees context is always present. Best for short sessions or critical workflows. |
 | **Minimal** | `sessionDigest: false` | Tool-only, no automatic capture. | Zero overhead beyond guidance. Use when you handle memory manually. |
 
 **Which mode should you use?**
@@ -319,7 +322,22 @@ openclaw nowledge-mem status
 
 ## Configuration
 
-On first startup, the plugin creates a config file at `~/.nowledge-mem/openclaw.json` with defaults. Edit it to customize:
+No config needed to get started. The defaults work for local mode.
+
+To change settings, use the OpenClaw plugin settings UI. Changes take effect on restart.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `sessionContext` | boolean | `false` | Inject Working Memory + relevant memories at prompt time |
+| `sessionDigest` | boolean | `true` | Thread capture + LLM distillation at session end |
+| `digestMinInterval` | integer | `300` | Minimum seconds between session digests for the same thread (0-86400) |
+| `maxContextResults` | integer | `5` | Max memories to inject at prompt time (1-20, only used when sessionContext is enabled) |
+| `apiUrl` | string | `""` | Remote server URL. Empty = local (`http://127.0.0.1:14242`) |
+| `apiKey` | string | `""` | API key for remote access. Injected as `NMEM_API_KEY` env var, never logged |
+
+### Advanced: config file
+
+For persistent or scripted config, create `~/.nowledge-mem/openclaw.json`:
 
 ```json
 {
@@ -332,16 +350,7 @@ On first startup, the plugin creates a config file at `~/.nowledge-mem/openclaw.
 }
 ```
 
-Edit the file and restart OpenClaw. The plugin reads it on every startup.
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `sessionContext` | boolean | `false` | Inject Working Memory + relevant memories at prompt time |
-| `sessionDigest` | boolean | `true` | Thread capture + LLM distillation at session end |
-| `digestMinInterval` | integer | `300` | Minimum seconds between session digests for the same thread (0-86400) |
-| `maxContextResults` | integer | `5` | Max memories to inject at prompt time (1-20, only used when sessionContext is enabled) |
-| `apiUrl` | string | `""` | Remote server URL. Empty = local (`http://127.0.0.1:14242`) |
-| `apiKey` | string | `""` | API key for remote access. Injected as `NMEM_API_KEY` env var, never logged |
+The config file takes priority over OpenClaw settings. Only the keys you include are overridden; missing keys fall through to OpenClaw settings, then env vars, then defaults.
 
 ### Advanced: environment variables
 
@@ -356,7 +365,13 @@ NMEM_API_URL=https://...
 NMEM_API_KEY=your-key
 ```
 
-**Priority**: OpenClaw plugin config > config file > env vars > defaults.
+### Priority
+
+```
+config file > OpenClaw settings > env vars > defaults
+```
+
+Use `nowledge_mem_status` (or `openclaw nowledge-mem status`) to see where each value comes from.
 
 ## What Makes This Different
 

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.6.6",
+	"version": "0.6.8",
 	"kind": "memory",
 	"uiHints": {
 		"sessionContext": {
@@ -66,7 +66,6 @@
 				"default": "",
 				"description": "API key for remote access. Stored in plugin config, injected as NMEM_API_KEY env var. Never logged."
 			}
-		},
-		"additionalProperties": false
+		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
-	"version": "0.6.6",
+	"version": "0.6.8",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {

package/src/config.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -42,69 +42,14 @@ const ALIAS_KEYS = {
 const CONFIG_DIR = join(homedir(), ".nowledge-mem");
 const CONFIG_PATH = join(CONFIG_DIR, "openclaw.json");
 
-const DEFAULT_CONFIG = {
-	sessionContext: false,
-	sessionDigest: true,
-	digestMinInterval: 300,
-	maxContextResults: 5,
-	apiUrl: "",
-	apiKey: "",
-};
-
 /**
- * Read ~/.nowledge-mem/openclaw.json.
- * On first run, creates the file seeded with values from pluginConfig
- * (if any) — this migrates settings before OpenClaw strips them.
- * Returns {} on any error — never crashes.
+ * Read ~/.nowledge-mem/openclaw.json if it exists.
+ * Returns {} when the file is missing or unreadable.
  */
-function readConfigFile(logger, pluginCfg) {
+function readConfigFile(logger) {
 	try {
 		if (!existsSync(CONFIG_PATH)) {
-			// Seed from pluginConfig + env vars for migration.
-			// Users on older OpenClaw get their values written to the file
-			// BEFORE a future OpenClaw update can strip them.
-			const initial = { ...DEFAULT_CONFIG };
-			if (pluginCfg && typeof pluginCfg === "object") {
-				// Resolve aliases in pluginConfig for seeding
-				const resolved = { ...pluginCfg };
-				for (const [oldKey, newKey] of Object.entries(ALIAS_KEYS)) {
-					if (oldKey in resolved) {
-						if (!(newKey in resolved)) {
-							resolved[newKey] = resolved[oldKey];
-						}
-						delete resolved[oldKey];
-					}
-				}
-
-				if (typeof resolved.sessionContext === "boolean")
-					initial.sessionContext = resolved.sessionContext;
-				if (typeof resolved.sessionDigest === "boolean")
-					initial.sessionDigest = resolved.sessionDigest;
-				if (
-					typeof resolved.digestMinInterval === "number" &&
-					Number.isFinite(resolved.digestMinInterval)
-				)
-					initial.digestMinInterval = resolved.digestMinInterval;
-				if (
-					typeof resolved.maxContextResults === "number" &&
-					Number.isFinite(resolved.maxContextResults)
-				)
-					initial.maxContextResults = resolved.maxContextResults;
-				if (typeof resolved.apiUrl === "string" && resolved.apiUrl.trim())
-					initial.apiUrl = resolved.apiUrl.trim();
-				// apiKey intentionally NOT written to disk — keep in env/pluginConfig only
-			}
-
-			mkdirSync(CONFIG_DIR, { recursive: true });
-			writeFileSync(
-				CONFIG_PATH,
-				JSON.stringify(initial, null, 2) + "\n",
-				"utf-8",
-			);
-			logger?.info?.(
-				`nowledge-mem: created config at ${CONFIG_PATH} — edit to customize`,
-			);
-			return { ...initial };
+			return {};
 		}
 		const content = readFileSync(CONFIG_PATH, "utf-8").trim();
 		if (!content) return {};
@@ -148,7 +93,8 @@ function pickBool(obj, key) {
 }
 
 function pickNum(obj, key) {
-	if (typeof obj[key] === "number" && Number.isFinite(obj[key])) return obj[key];
+	if (typeof obj[key] === "number" && Number.isFinite(obj[key]))
+		return obj[key];
 	return undefined;
 }
 
@@ -166,11 +112,27 @@ function resolveAliases(obj) {
 	return resolved;
 }
 
+/**
+ * Return the first option whose value is not undefined.
+ * Each option is { value, source } where source is a label like
+ * "file", "pluginConfig", "env", or "default".
+ */
+function firstDefined(...options) {
+	for (const opt of options) {
+		if (opt.value !== undefined) return opt;
+	}
+	return options[options.length - 1];
+}
+
 // -------------------------------------------------------------------------
 
 /**
  * Parse plugin config with cascade:
- *   pluginConfig > ~/.nowledge-mem/openclaw.json > env vars > defaults
+ *   ~/.nowledge-mem/openclaw.json > pluginConfig > env vars > defaults
+ *
+ * The config file (if it exists) takes highest priority so users who
+ * create it get predictable behavior. Most users won't have one and
+ * will configure via OpenClaw's plugin settings UI (pluginConfig).
  *
  * Canonical keys: sessionContext, sessionDigest, digestMinInterval,
  *                 maxContextResults, apiUrl, apiKey
@@ -184,21 +146,20 @@ function resolveAliases(obj) {
  * Environment variables (all optional):
  *   NMEM_SESSION_CONTEXT       — true/1/yes to enable (alias: NMEM_AUTO_RECALL)
  *   NMEM_SESSION_DIGEST        — true/1/yes to enable (alias: NMEM_AUTO_CAPTURE)
- *   NMEM_DIGEST_MIN_INTERVAL   — seconds (0–86400)
- *   NMEM_MAX_CONTEXT_RESULTS   — integer (1–20)
+ *   NMEM_DIGEST_MIN_INTERVAL   — seconds (0-86400)
+ *   NMEM_MAX_CONTEXT_RESULTS   — integer (1-20)
  *   NMEM_API_URL               — remote server URL
  *   NMEM_API_KEY               — API key (never logged)
  */
 export function parseConfig(raw, logger) {
 	const pluginCfg = raw && typeof raw === "object" ? raw : {};
-	const fileCfg = readConfigFile(logger, pluginCfg);
+	const fileCfg = readConfigFile(logger);
 
 	// Resolve aliases in both sources
 	const resolvedPlugin = resolveAliases(pluginCfg);
 	const resolvedFile = resolveAliases(fileCfg);
 
 	// Strict: reject unknown keys in pluginConfig (typo catcher).
-	// File config is our own — validated by shape, no strict check needed.
 	const unknownKeys = Object.keys(resolvedPlugin).filter(
 		(k) => !ALLOWED_KEYS.has(k),
 	);
@@ -209,55 +170,97 @@ export function parseConfig(raw, logger) {
 		);
 	}
 
-	// --- sessionContext ---
-	const sessionContext =
-		pickBool(resolvedPlugin, "sessionContext") ??
-		pickBool(resolvedFile, "sessionContext") ??
-		envBool("NMEM_SESSION_CONTEXT", "NMEM_AUTO_RECALL") ??
-		false;
+	const _sources = {};
 
-	// --- sessionDigest ---
-	const sessionDigest =
-		pickBool(resolvedPlugin, "sessionDigest") ??
-		pickBool(resolvedFile, "sessionDigest") ??
-		envBool("NMEM_SESSION_DIGEST", "NMEM_AUTO_CAPTURE") ??
-		true;
+	// --- sessionContext: file > pluginConfig > env > default ---
+	const sc = firstDefined(
+		{ value: pickBool(resolvedFile, "sessionContext"), source: "file" },
+		{
+			value: pickBool(resolvedPlugin, "sessionContext"),
+			source: "pluginConfig",
+		},
+		{
+			value: envBool("NMEM_SESSION_CONTEXT", "NMEM_AUTO_RECALL"),
+			source: "env",
+		},
+		{ value: false, source: "default" },
+	);
+	const sessionContext = sc.value;
+	_sources.sessionContext = sc.source;
 
-	// --- digestMinInterval ---
-	const rawInterval =
-		pickNum(resolvedPlugin, "digestMinInterval") ??
-		pickNum(resolvedFile, "digestMinInterval") ??
-		envInt("NMEM_DIGEST_MIN_INTERVAL") ??
-		envInt("NMEM_CAPTURE_MIN_INTERVAL");
-	const digestMinInterval =
-		rawInterval !== undefined
-			? Math.min(86400, Math.max(0, Math.trunc(rawInterval)))
-			: 300;
+	// --- sessionDigest: file > pluginConfig > env > default ---
+	const sd = firstDefined(
+		{ value: pickBool(resolvedFile, "sessionDigest"), source: "file" },
+		{
+			value: pickBool(resolvedPlugin, "sessionDigest"),
+			source: "pluginConfig",
+		},
+		{
+			value: envBool("NMEM_SESSION_DIGEST", "NMEM_AUTO_CAPTURE"),
+			source: "env",
+		},
+		{ value: true, source: "default" },
+	);
+	const sessionDigest = sd.value;
+	_sources.sessionDigest = sd.source;
 
-	// --- maxContextResults ---
-	const rawMax =
-		pickNum(resolvedPlugin, "maxContextResults") ??
-		pickNum(resolvedFile, "maxContextResults") ??
-		envInt("NMEM_MAX_CONTEXT_RESULTS") ??
-		envInt("NMEM_MAX_RECALL_RESULTS");
-	const maxContextResults =
-		rawMax !== undefined
-			? Math.min(20, Math.max(1, Math.trunc(rawMax)))
-			: 5;
+	// --- digestMinInterval: file > pluginConfig > env > default ---
+	const dmiEnv =
+		envInt("NMEM_DIGEST_MIN_INTERVAL") ?? envInt("NMEM_CAPTURE_MIN_INTERVAL");
+	const dmi = firstDefined(
+		{ value: pickNum(resolvedFile, "digestMinInterval"), source: "file" },
+		{
+			value: pickNum(resolvedPlugin, "digestMinInterval"),
+			source: "pluginConfig",
+		},
+		{ value: dmiEnv, source: "env" },
+		{ value: 300, source: "default" },
+	);
+	const digestMinInterval = Math.min(86400, Math.max(0, Math.trunc(dmi.value)));
+	_sources.digestMinInterval = dmi.source;
 
-	// --- apiUrl: pluginConfig > file > env > "" ---
-	const apiUrl =
-		(typeof resolvedPlugin.apiUrl === "string" && resolvedPlugin.apiUrl.trim()) ||
-		(typeof resolvedFile.apiUrl === "string" && resolvedFile.apiUrl.trim()) ||
-		envStr("NMEM_API_URL") ||
-		"";
+	// --- maxContextResults: file > pluginConfig > env > default ---
+	const mcrEnv =
+		envInt("NMEM_MAX_CONTEXT_RESULTS") ?? envInt("NMEM_MAX_RECALL_RESULTS");
+	const mcr = firstDefined(
+		{ value: pickNum(resolvedFile, "maxContextResults"), source: "file" },
+		{
+			value: pickNum(resolvedPlugin, "maxContextResults"),
+			source: "pluginConfig",
+		},
+		{ value: mcrEnv, source: "env" },
+		{ value: 5, source: "default" },
+	);
+	const maxContextResults = Math.min(20, Math.max(1, Math.trunc(mcr.value)));
+	_sources.maxContextResults = mcr.source;
+
+	// --- apiUrl: file > pluginConfig > env > "" ---
+	const fileUrl =
+		typeof resolvedFile.apiUrl === "string" && resolvedFile.apiUrl.trim();
+	const pluginUrl =
+		typeof resolvedPlugin.apiUrl === "string" && resolvedPlugin.apiUrl.trim();
+	const au = firstDefined(
+		{ value: fileUrl || undefined, source: "file" },
+		{ value: pluginUrl || undefined, source: "pluginConfig" },
+		{ value: envStr("NMEM_API_URL"), source: "env" },
+		{ value: "", source: "default" },
+	);
+	const apiUrl = au.value;
+	_sources.apiUrl = au.source;
 
-	// --- apiKey: pluginConfig > file > env > "" ---
-	const apiKey =
-		(typeof resolvedPlugin.apiKey === "string" && resolvedPlugin.apiKey.trim()) ||
-		(typeof resolvedFile.apiKey === "string" && resolvedFile.apiKey.trim()) ||
-		envStr("NMEM_API_KEY") ||
-		"";
+	// --- apiKey: file > pluginConfig > env > "" ---
+	const fileKey =
+		typeof resolvedFile.apiKey === "string" && resolvedFile.apiKey.trim();
+	const pluginKey =
+		typeof resolvedPlugin.apiKey === "string" && resolvedPlugin.apiKey.trim();
+	const ak = firstDefined(
+		{ value: fileKey || undefined, source: "file" },
+		{ value: pluginKey || undefined, source: "pluginConfig" },
+		{ value: envStr("NMEM_API_KEY"), source: "env" },
+		{ value: "", source: "default" },
+	);
+	const apiKey = ak.value;
+	_sources.apiKey = ak.source;
 
 	return {
 		sessionContext,
@@ -266,5 +269,6 @@ export function parseConfig(raw, logger) {
 		maxContextResults,
 		apiUrl,
 		apiKey,
+		_sources,
 	};
 }

package/src/index.js

@@ -18,6 +18,7 @@ import { createForgetTool } from "./tools/forget.js";
 import { createMemoryGetTool } from "./tools/memory-get.js";
 import { createMemorySearchTool } from "./tools/memory-search.js";
 import { createSaveTool } from "./tools/save.js";
+import { createStatusTool } from "./tools/status.js";
 import { createThreadFetchTool } from "./tools/thread-fetch.js";
 import { createThreadSearchTool } from "./tools/thread-search.js";
 import { createTimelineTool } from "./tools/timeline.js";
@@ -52,6 +53,9 @@ export default {
 		api.registerTool(createThreadSearchTool(client, logger));
 		api.registerTool(createThreadFetchTool(client, logger));
 
+		// Diagnostics
+		api.registerTool(createStatusTool(client, logger, cfg));
+
 		// Always-on: behavioral guidance so the agent proactively saves and searches.
 		// Fires every turn via before_prompt_build — ~50 tokens, negligible cost.
 		// When sessionContext is on, guidance adjusts to avoid redundant searches.

package/src/tools/status.js

@@ -0,0 +1,145 @@
+/**
+ * nowledge_mem_status - verify config, connectivity, and backend health.
+ *
+ * Lets the user (or agent) confirm that apiUrl, apiKey, and other
+ * settings are taking effect, and that the backend is reachable.
+ * Shows where each config value comes from (file, pluginConfig, env, default).
+ */
+import { isDefaultApiUrl } from "../config.js";
+
+export function createStatusTool(client, _logger, cfg) {
+	return {
+		name: "nowledge_mem_status",
+		description:
+			"Check Nowledge Mem status: effective configuration, backend connectivity, and version. " +
+			"Call this when the user wants to verify their setup is working, " +
+			"especially after changing apiUrl or apiKey for remote mode.",
+		parameters: {
+			type: "object",
+			properties: {},
+		},
+		async execute() {
+			const lines = [];
+			const details = {};
+			const sources = cfg._sources || {};
+
+			// 1. Mode + connection target
+			const remote = !isDefaultApiUrl(cfg.apiUrl);
+			const mode = remote ? "remote" : "local";
+			details.mode = mode;
+			details.apiUrl = cfg.apiUrl || "http://127.0.0.1:14242";
+			details.apiKeySet = Boolean(cfg.apiKey);
+
+			lines.push(
+				`Mode: ${remote ? `Remote (${cfg.apiUrl})` : "Local (127.0.0.1:14242)"}`,
+			);
+			lines.push(`API key: ${cfg.apiKey ? "set" : "not set"}`);
+
+			// 2. CLI resolution
+			try {
+				const cmd = client.resolveCommand();
+				details.cli = cmd.join(" ");
+				lines.push(`CLI: ${cmd.join(" ")}`);
+			} catch {
+				details.cli = null;
+				lines.push("CLI: not found (install with: pip install nmem-cli)");
+			}
+
+			// 3. Backend health
+			let healthy = false;
+			try {
+				healthy = await client.checkHealth();
+			} catch {
+				// checkHealth already returns false on error
+			}
+			details.healthy = healthy;
+
+			if (healthy) {
+				lines.push("Backend: reachable");
+				// Fetch detailed health info
+				try {
+					const health = await client.apiJson(
+						"GET",
+						"/health",
+						undefined,
+						5000,
+					);
+					if (health.version) {
+						details.version = health.version;
+						lines.push(`Version: ${health.version}`);
+					}
+					if (health.database_connected !== undefined) {
+						details.databaseConnected = health.database_connected;
+						lines.push(
+							`Database: ${health.database_connected ? "connected" : "disconnected"}`,
+						);
+					}
+				} catch {
+					// Health endpoint not available on older backends
+				}
+			} else {
+				lines.push("Backend: not reachable");
+				if (remote) {
+					lines.push(
+						"  Check that apiUrl is correct and the server is running.",
+					);
+					if (!cfg.apiKey) {
+						lines.push("  Remote mode usually requires an API key.");
+					}
+				} else {
+					lines.push("  Ensure the Nowledge Mem desktop app is running.");
+				}
+			}
+
+			// 4. Effective config with sources
+			lines.push("");
+			lines.push("Config (source):");
+			lines.push(
+				`  sessionContext: ${cfg.sessionContext} (${sources.sessionContext || "?"})`,
+			);
+			lines.push(
+				`  sessionDigest: ${cfg.sessionDigest} (${sources.sessionDigest || "?"})`,
+			);
+			lines.push(
+				`  digestMinInterval: ${cfg.digestMinInterval}s (${sources.digestMinInterval || "?"})`,
+			);
+			lines.push(
+				`  maxContextResults: ${cfg.maxContextResults} (${sources.maxContextResults || "?"})`,
+			);
+
+			details.config = {
+				sessionContext: {
+					value: cfg.sessionContext,
+					source: sources.sessionContext,
+				},
+				sessionDigest: {
+					value: cfg.sessionDigest,
+					source: sources.sessionDigest,
+				},
+				digestMinInterval: {
+					value: cfg.digestMinInterval,
+					source: sources.digestMinInterval,
+				},
+				maxContextResults: {
+					value: cfg.maxContextResults,
+					source: sources.maxContextResults,
+				},
+				apiUrl: { value: cfg.apiUrl || "(local)", source: sources.apiUrl },
+				apiKey: {
+					value: cfg.apiKey ? "(set)" : "(not set)",
+					source: sources.apiKey,
+				},
+			};
+
+			lines.push("");
+			lines.push(
+				"Priority: config file > OpenClaw settings > env vars > defaults",
+			);
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details,
+			};
+		},
+	};
+}