@nowledge/openclaw-nowledge-mem 0.6.6 → 0.6.9

package/CHANGELOG.md

@@ -2,15 +2,48 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [0.6.9] - 2026-03-05
+
+### Fixed
+
+- **Auto-recall searched with full prompt instead of user message**: `event.prompt` contains the entire conversation history (system prompt + all prior turns), making recalled memories irrelevant as conversation grows. Now uses a tiered query strategy: substantial messages (>=40 chars) search alone; short messages (3-39 chars, likely follow-ups like "explain that more") include the last 3 messages as context for topic grounding; tiny messages (<3 chars) skip recall. Falls back to truncated `event.prompt` (500 chars) only when `event.messages` is unavailable.
+
+### Added
+
+- **`recallMinScore` config option** (0-100, default 0): Minimum relevance score threshold for auto-recalled memories. Set to e.g. 30 to filter out low-confidence results. Configurable via OpenClaw Config UI, config file, or `NMEM_RECALL_MIN_SCORE` env var.
+
+## [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 +67,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 |
 |-----|------|---------|---------|-------------|
@@ -88,10 +91,13 @@ Config file at `~/.nowledge-mem/openclaw.json` (auto-created on first run). Also
 | `sessionDigest` | boolean | `true` | `NMEM_SESSION_DIGEST` | Thread capture + LLM distillation at session end |
 | `digestMinInterval` | integer 0-86400 | `300` | `NMEM_DIGEST_MIN_INTERVAL` | Minimum seconds between session digests |
 | `maxContextResults` | integer 1-20 | `5` | `NMEM_MAX_CONTEXT_RESULTS` | How many memories to inject at prompt time |
+| `recallMinScore` | integer 0-100 | `0` | `NMEM_RECALL_MIN_SCORE` | Min relevance score (%) to include in auto-recall |
 | `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 +105,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
 {
@@ -49,6 +51,11 @@ Enable the plugin the same way as local mode, then set your remote server in `~/
 
 The `apiKey` is injected as `NMEM_API_KEY` into the nmem CLI process. Never passed as a CLI argument, never logged.
 
+### Configure via WebUI of OpenClaw
+
+<img width="1192" height="2007" alt="openclaw-config" src="https://github.com/user-attachments/assets/a4abd855-db56-4a1f-b0ac-0114909d0c20" />
+
+
 ## How It Works
 
 ### Per-Turn Flow
@@ -62,7 +69,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 +98,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 +161,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 +262,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 +327,23 @@ 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) |
+| `recallMinScore` | integer | `0` | Min relevance score (0-100%) to include in auto-recall. 0 = include all |
+| `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
 {
@@ -327,21 +351,13 @@ On first startup, the plugin creates a config file at `~/.nowledge-mem/openclaw.
   "sessionDigest": true,
   "digestMinInterval": 300,
   "maxContextResults": 5,
+  "recallMinScore": 0,
   "apiUrl": "",
   "apiKey": ""
 }
 ```
 
-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
 
@@ -352,11 +368,18 @@ NMEM_SESSION_CONTEXT=true
 NMEM_SESSION_DIGEST=true
 NMEM_DIGEST_MIN_INTERVAL=300
 NMEM_MAX_CONTEXT_RESULTS=5
+NMEM_RECALL_MIN_SCORE=0
 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,15 +1,15 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.6.6",
+	"version": "0.6.9",
 	"kind": "memory",
 	"uiHints": {
 		"sessionContext": {
 			"label": "Session context injection",
-			"help": "Inject Working Memory and relevant memories at prompt time. Off by default \u2014 the agent can call memory_search on demand instead."
+			"help": "Inject Working Memory and relevant memories at prompt time. Off by default; the agent can call memory_search on demand instead."
 		},
 		"sessionDigest": {
 			"label": "Session digest at end",
-			"help": "Capture conversation threads and distill key memories via LLM at session end. On by default \u2014 negligible cost, one triage call per session."
+			"help": "Capture conversation threads and distill key memories via LLM at session end. On by default. Negligible cost, one triage call per session."
 		},
 		"digestMinInterval": {
 			"label": "Minimum digest interval (seconds)",
@@ -17,7 +17,11 @@
 		},
 		"maxContextResults": {
 			"label": "Max context results",
-			"help": "How many memories to inject for each context cycle (1\u201320)"
+			"help": "How many memories to inject for each context cycle (1-20)"
+		},
+		"recallMinScore": {
+			"label": "Min recall score (%)",
+			"help": "Only inject memories with relevance score above this threshold (0-100). Set to 0 to include all results."
 		},
 		"apiUrl": {
 			"label": "Server URL (remote mode)",
@@ -25,7 +29,7 @@
 		},
 		"apiKey": {
 			"label": "API key (remote mode)",
-			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument \u2014 injected as NMEM_API_KEY env var only.",
+			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument. Injected as NMEM_API_KEY env var only.",
 			"secret": true
 		}
 	},
@@ -35,7 +39,7 @@
 			"sessionContext": {
 				"type": "boolean",
 				"default": false,
-				"description": "Inject Working Memory and recalled memories at prompt time. Off by default \u2014 the agent queries memory on demand via tools."
+				"description": "Inject Working Memory and recalled memories at prompt time. Off by default; the agent queries memory on demand via tools."
 			},
 			"sessionDigest": {
 				"type": "boolean",
@@ -56,6 +60,13 @@
 				"maximum": 20,
 				"description": "Maximum memories to inject at prompt time (only used when sessionContext is enabled)"
 			},
+			"recallMinScore": {
+				"type": "integer",
+				"default": 0,
+				"minimum": 0,
+				"maximum": 100,
+				"description": "Minimum relevance score (0-100%) to include a memory in auto-recall. Set to 0 to include all results."
+			},
 			"apiUrl": {
 				"type": "string",
 				"default": "",
@@ -66,7 +77,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.9",
 	"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";
 
@@ -19,6 +19,7 @@ const ALLOWED_KEYS = new Set([
 	"sessionDigest",
 	"digestMinInterval",
 	"maxContextResults",
+	"recallMinScore",
 	"apiUrl",
 	"apiKey",
 	// Legacy aliases — accepted but not advertised
@@ -42,69 +43,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 +94,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,14 +113,30 @@ 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
+ *                 maxContextResults, recallMinScore, apiUrl, apiKey
  *
  * Legacy aliases (accepted from all sources; never shown in docs):
  *   autoRecall → sessionContext
@@ -184,21 +147,21 @@ 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_RECALL_MIN_SCORE      — integer (0-100)
  *   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,62 +172,120 @@ export function parseConfig(raw, logger) {
 		);
 	}
 
-	// --- sessionContext ---
-	const sessionContext =
-		pickBool(resolvedPlugin, "sessionContext") ??
-		pickBool(resolvedFile, "sessionContext") ??
-		envBool("NMEM_SESSION_CONTEXT", "NMEM_AUTO_RECALL") ??
-		false;
+	const _sources = {};
+
+	// --- 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;
+
+	// --- 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;
 
-	// --- sessionDigest ---
-	const sessionDigest =
-		pickBool(resolvedPlugin, "sessionDigest") ??
-		pickBool(resolvedFile, "sessionDigest") ??
-		envBool("NMEM_SESSION_DIGEST", "NMEM_AUTO_CAPTURE") ??
-		true;
+	// --- 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;
 
-	// --- 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;
+	// --- 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;
 
-	// --- 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;
+	// --- recallMinScore: file > pluginConfig > env > default ---
+	const rmsEnv = envInt("NMEM_RECALL_MIN_SCORE");
+	const rms = firstDefined(
+		{ value: pickNum(resolvedFile, "recallMinScore"), source: "file" },
+		{
+			value: pickNum(resolvedPlugin, "recallMinScore"),
+			source: "pluginConfig",
+		},
+		{ value: rmsEnv, source: "env" },
+		{ value: 0, source: "default" },
+	);
+	const recallMinScore = Math.min(100, Math.max(0, Math.trunc(rms.value)));
+	_sources.recallMinScore = rms.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") ||
-		"";
+	// --- 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,
 		sessionDigest,
 		digestMinInterval,
 		maxContextResults,
+		recallMinScore,
 		apiUrl,
 		apiKey,
+		_sources,
 	};
 }

package/src/hooks/capture.js

@@ -250,7 +250,10 @@ function buildConversationText(normalized) {
 	const parts = [];
 	let total = 0;
 	for (const m of normalized) {
-		const text = truncate(m.fullContent || m.content, MAX_DISTILL_MESSAGE_CHARS);
+		const text = truncate(
+			m.fullContent || m.content,
+			MAX_DISTILL_MESSAGE_CHARS,
+		);
 		const line = `${m.role}: ${text}`;
 		if (total + line.length > MAX_CONVERSATION_CHARS) break;
 		parts.push(line);
@@ -297,7 +300,9 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 
 		//    Skip when no new messages were added (e.g. heartbeat re-sync).
 		if (!result || result.messagesAdded === 0) {
-			logger.debug?.("capture: no new messages since last sync, skipping triage");
+			logger.debug?.(
+				"capture: no new messages since last sync, skipping triage",
+			);
 			return;
 		}
 

package/src/hooks/recall.js

@@ -13,20 +13,148 @@ function escapeForPrompt(text) {
 	);
 }
 
+/** Max query length sent to search — longer messages get truncated. */
+const MAX_QUERY_LENGTH = 500;
+
+/**
+ * Messages shorter than this get augmented with recent conversational
+ * context. Below this threshold, a message is likely referential
+ * ("explain that more", "what about the second point?") and needs
+ * surrounding context to produce useful search results.
+ *
+ * Messages at or above this threshold are substantial enough to
+ * search on their own ("openviking 不好用", "how do I deploy to k8s?").
+ */
+const SHORT_QUERY_THRESHOLD = 40;
+
+/** How many recent messages to include for short-query context. */
+const CONTEXT_MESSAGES = 3;
+
+/** Per-message cap when building context window. */
+const CONTEXT_MSG_MAX_CHARS = 150;
+
+/**
+ * Extract text from message content (string or structured blocks).
+ * Mirrors the pattern from capture.js.
+ */
+function extractText(content) {
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	const parts = [];
+	for (const block of content) {
+		if (!block || typeof block !== "object") continue;
+		if (block.type === "text" && typeof block.text === "string") {
+			const text = block.text.trim();
+			if (text) parts.push(text);
+		}
+	}
+	return parts.join("\n").trim();
+}
+
+/**
+ * Normalize a raw message entry to { role, text }.
+ * Handles both flat { role, content } and nested { message: { role, content } }.
+ * Returns null for non-user/assistant messages, empty content, or slash commands.
+ */
+function normalizeMessage(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const msg =
+		raw.message && typeof raw.message === "object" ? raw.message : raw;
+	const role = typeof msg.role === "string" ? msg.role : "";
+	if (role !== "user" && role !== "assistant") return null;
+	const text = extractText(msg.content);
+	if (!text) return null;
+	// Skip slash commands — they're plugin directives, not conversational
+	if (role === "user" && text.startsWith("/")) return null;
+	return { role, text };
+}
+
+/**
+ * Build the search query from the hook event.
+ *
+ * Three tiers:
+ *   >= 40 chars : latest user message alone (self-contained)
+ *   3-39 chars  : latest user message + recent context (likely referential)
+ *   < 3 chars   : skip recall (too short — "ok", emoji, etc.)
+ *
+ * The event object provides:
+ * - event.messages: structured array of {role, content} messages (preferred)
+ * - event.prompt: the full formatted prompt (fallback, truncated)
+ */
+function buildSearchQuery(event) {
+	const messages = event?.messages;
+
+	if (Array.isArray(messages) && messages.length > 0) {
+		// Find the latest user message (walk backwards)
+		let latestUserIdx = -1;
+		let latestUserText = "";
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const norm = normalizeMessage(messages[i]);
+			if (norm && norm.role === "user") {
+				latestUserIdx = i;
+				latestUserText = norm.text;
+				break;
+			}
+		}
+
+		if (!latestUserText || latestUserText.length < 3) return "";
+
+		// Substantial message — use it alone
+		if (latestUserText.length >= SHORT_QUERY_THRESHOLD) {
+			return latestUserText.slice(0, MAX_QUERY_LENGTH);
+		}
+
+		// Short message — likely a follow-up. Add recent context so
+		// the search engine sees what topic the conversation is about.
+		// Collect up to CONTEXT_MESSAGES messages preceding the latest user
+		// message (both user and assistant, for topic grounding).
+		const contextParts = [];
+		const scanFrom = Math.max(0, latestUserIdx - CONTEXT_MESSAGES);
+		for (let i = scanFrom; i < latestUserIdx; i++) {
+			const norm = normalizeMessage(messages[i]);
+			if (!norm) continue;
+			const truncated =
+				norm.text.length > CONTEXT_MSG_MAX_CHARS
+					? `${norm.text.slice(0, CONTEXT_MSG_MAX_CHARS)}…`
+					: norm.text;
+			contextParts.push(truncated);
+		}
+
+		if (contextParts.length > 0) {
+			// Latest message first (primary intent), then context
+			const combined = `${latestUserText}\n\n${contextParts.join("\n")}`;
+			return combined.slice(0, MAX_QUERY_LENGTH);
+		}
+
+		// No prior context available (first message) — use as-is
+		return latestUserText;
+	}
+
+	// Fallback: use event.prompt but truncate aggressively.
+	// This path only fires when OpenClaw doesn't provide event.messages.
+	if (typeof event?.prompt === "string" && event.prompt.length >= 5) {
+		return event.prompt.slice(0, MAX_QUERY_LENGTH);
+	}
+
+	return "";
+}
+
 /**
- * Builds the before_agent_start hook handler.
+ * Builds the before_prompt_build hook handler.
  *
- * Injects two layers of context at session start:
+ * Injects two layers of context at prompt time:
  * 1. Working Memory — today's focus, priorities, unresolved flags
- * 2. Relevant memories — with types, labels, and source provenance
+ * 2. Relevant memories — searched using the user's latest message
  *
  * Tool guidance is minimal — the agent already sees full tool descriptions
  * in its tool list. We only add a brief behavioral note.
  */
 export function buildRecallHandler(client, cfg, logger) {
+	const minScore = (cfg.recallMinScore ?? 0) / 100; // config is 0-100, API is 0-1
+
 	return async (event) => {
-		const prompt = event.prompt;
-		if (!prompt || prompt.length < 5) return;
+		const searchQuery = buildSearchQuery(event);
+		if (!searchQuery) return;
 
 		const sections = [];
 
@@ -44,9 +172,17 @@ export function buildRecallHandler(client, cfg, logger) {
 
 		// 2. Relevant memories — enriched with scoring signals and labels
 		try {
-			const results = await client.searchRich(prompt, cfg.maxContextResults);
-			if (results.length > 0) {
-				const lines = results.map((r) => {
+			const results = await client.searchRich(
+				searchQuery,
+				cfg.maxContextResults,
+			);
+			// Filter by minimum score if configured
+			const filtered =
+				minScore > 0
+					? results.filter((r) => (r.score ?? 0) >= minScore)
+					: results;
+			if (filtered.length > 0) {
+				const lines = filtered.map((r) => {
 					const title = r.title || "(untitled)";
 					const score = `${(r.score * 100).toFixed(0)}%`;
 					const labels =
@@ -82,7 +218,9 @@ export function buildRecallHandler(client, cfg, logger) {
 			"</nowledge-mem>",
 		].join("\n");
 
-		logger.debug?.(`recall: injecting ${context.length} chars`);
+		logger.debug?.(
+			`recall: injecting ${context.length} chars (query: ${searchQuery.slice(0, 80)}…)`,
+		);
 		return { prependContext: context };
 	};
 }

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/connections.js

@@ -293,9 +293,7 @@ export function createConnectionsTool(client, logger) {
 						const otherTitle = isOlderNode
 							? edge.newer_title || "(untitled)"
 							: edge.older_title || "(untitled)";
-						const otherId = isOlderNode
-							? edge.newer_id
-							: edge.older_id;
+						const otherId = isOlderNode ? edge.newer_id : edge.older_id;
 						const direction = isOlderNode ? "→" : "←";
 						const idLine = otherId ? `\n    → id: ${otherId}` : "";
 						return `  ${direction} ${otherTitle}${relLabel ? ` — ${relLabel}` : ""}${idLine}`;

package/src/tools/status.js

@@ -0,0 +1,152 @@
+/**
+ * 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 || "?"})`,
+			);
+			lines.push(
+				`  recallMinScore: ${cfg.recallMinScore}% (${sources.recallMinScore || "?"})`,
+			);
+
+			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,
+				},
+				recallMinScore: {
+					value: cfg.recallMinScore,
+					source: sources.recallMinScore,
+				},
+				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,
+			};
+		},
+	};
+}