@nowledge/openclaw-nowledge-mem 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
-## [Unreleased]
+## [0.7.3] - 2026-03-30
+
+### Added
+
+- **Status tool now checks plugin trust and memory slot.** `nowledge_mem_status` reads `plugins.allow` from the OpenClaw config: warns when the allowlist exists but the plugin is missing (loading will be blocked); shows a tip when no allowlist is set (plugin loads via `entries.enabled`, but trust is implicit). Also warns when the memory slot points to `memory-core` instead of `openclaw-nowledge-mem` — a common misconfiguration after upgrading to OpenClaw 3.22+. Both checks include the exact fix command.
+- **Clarified that no `tools.*` config is needed.** All plugin tools register automatically when the plugin loads. Listing `nowledge_mem_*` names in `tools.allow` is a misconfiguration — OpenClaw silently strips allowlists that contain only plugin entries. The only config users need is `plugins.allow: ["openclaw-nowledge-mem"]`. Updated troubleshooting in README, SKILL.md, and website docs (EN + ZH).
+
+## [0.7.2] - 2026-03-30
+
+### Added
+
+- **Status tool now reports memory slot configuration.** `nowledge_mem_status` checks whether the OpenClaw memory slot points to `openclaw-nowledge-mem`. If another plugin (e.g. the built-in `memory-core`) holds the slot, the tool shows a warning with the fix command. This catches a common misconfiguration after upgrading to OpenClaw 3.22+, where the implicit slot default changed to `memory-core`.
 
 ### Fixed
 

package/CLAUDE.md

@@ -118,7 +118,7 @@ When `contextEngine` points elsewhere (or is absent), hooks handle everything. N
 - `nowledge_mem_thread_fetch` - fetch messages from a specific thread. Start with a small page, then use `offset` + `limit` for progressive retrieval only when more context is needed.
 
 ### Diagnostics
-- `nowledge_mem_status` - show effective config (mode, apiUrl, apiKey set, sessionContext, sessionDigest, etc.), backend connectivity, and version. No parameters.
+- `nowledge_mem_status` - show plugin trust status, memory slot status, effective config (mode, apiUrl, apiKey set, sessionContext, sessionDigest, etc.), backend connectivity, and version. Checks `plugins.allow`: warns if set but plugin not included (loading blocked); shows tip if not set (plugin loads via `entries.enabled` but trust is implicit). Warns if the memory slot points to `memory-core` instead of `openclaw-nowledge-mem` (common after OpenClaw 3.22+ upgrade). No parameters.
 
 ## Skill Surface
 
@@ -151,6 +151,8 @@ Credentials (apiUrl/apiKey): also reads `~/.nowledge-mem/config.json` (shared wi
 | `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 |
 | `maxThreadMessageChars` | integer 200-20000 | `800` | `NMEM_MAX_THREAD_MESSAGE_CHARS` | Max chars per captured thread message before truncation |
+| `captureExclude` | string[] | `[]` | — | Session key glob patterns to skip during auto-capture. `*` matches within a colon-segment. Example: `["agent:*:cron:*"]` |
+| `captureSkipMarker` | string | `"#nmem-skip"` | — | In-band marker: any message containing this text skips capture for the session. Not sticky across compaction |
 | `apiUrl` | string | `""` | `NMEM_API_URL` | Remote server URL. Empty = local (127.0.0.1:14242) |
 | `apiKey` | string | `""` | `NMEM_API_KEY` | API key. Never logged. |
 

package/README.md

@@ -433,6 +433,56 @@ If OpenClaw logs a warning like `plugins.allow is empty; discovered non-bundled
 
 If you also use linked or workspace copies, review `plugins.load.paths` before relying on an allowlist. OpenClaw allowlists plugin ids, not install provenance.
 
+## Troubleshooting
+
+**Only `memory_search` and `memory_get` show up — saves go to local markdown files**
+
+The memory slot is probably still set to the built-in `memory-core`. OpenClaw 3.22+ defaults to `memory-core` when no explicit slot is configured. Reinstall to reset the slot automatically:
+
+```bash
+openclaw plugins install @nowledge/openclaw-nowledge-mem
+```
+
+Or set the slot manually in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": { "memory": "openclaw-nowledge-mem" }
+  }
+}
+```
+
+Restart OpenClaw after either change.
+
+**Plugin tools not available**
+
+All 10 plugin tools register automatically when the plugin loads. No tool-level config is needed — just make sure the plugin itself is trusted:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-nowledge-mem"]
+  }
+}
+```
+
+If `openclaw status` shows a CRITICAL warning about `plugins.allow`, this is the fix. Run `nowledge_mem_status` inside a conversation to check both plugin trust and memory slot status.
+
+Do not list `nowledge_mem_*` tool names in `tools.allow` — OpenClaw silently strips allowlists that contain only plugin entries, so the config looks active but does nothing.
+
+**Search timeouts with many concurrent agents**
+
+When running many agents in parallel, all searches share a single database connection. Upgrade to Nowledge Mem v0.6.12+ (backend) so scoring writes no longer block search responses.
+
+**`nmem --json status` fails in local mode**
+
+The Nowledge Mem backend is not running. Start it from the desktop app, or run the backend manually.
+
+**Remote mode not connecting**
+
+Check `~/.nowledge-mem/config.json` credentials. Run `nmem --json --api-url "$URL" status` to verify the server is reachable.
+
 ## What Makes This Different
 
 - **Local-first**: no API key, no cloud account. Your knowledge stays on your machine.

package/SKILL.md

@@ -186,6 +186,18 @@ First check the plugin status:
 openclaw nowledge-mem status
 ```
 
+If only `memory_search` and `memory_get` tools are available (other Nowledge Mem tools missing), the memory slot may still point to the built-in `memory-core`. Verify the slot in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": { "memory": "openclaw-nowledge-mem" }
+  }
+}
+```
+
+If missing, reinstall (`openclaw plugins install @nowledge/openclaw-nowledge-mem`) which sets the slot automatically. This is common after upgrading OpenClaw to 3.22+ where the default memory slot changed.
+
 Then verify in chat.
 
 For a clean synthetic check:
@@ -237,6 +249,7 @@ What to expect:
 | `plugins.allow is empty` warning | Add `openclaw-nowledge-mem` to `plugins.allow` if the user wants explicit trust |
 | Remote config seems ignored | Check whether `~/.nowledge-mem/openclaw.json` is overriding plugin settings |
 | Local mode unexpectedly talks to a remote server | Check for stale `NMEM_API_URL` / `NMEM_API_KEY` in the environment or an overriding `~/.nowledge-mem/openclaw.json` |
+| Plugin tools missing | Ensure the plugin is in `plugins.allow: ["openclaw-nowledge-mem"]`. Do **not** put `nowledge_mem_*` tool names in `tools.allow` — OpenClaw silently strips plugin-only allowlists. No `tools.*` config is needed; plugin tools load automatically when the plugin is allowed. |
 
 ## Notes for Agents
 

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.7.1",
+	"version": "0.7.3",
 	"kind": "memory",
 	"skills": ["skills/memory-guide"],
 	"uiHints": {
@@ -28,6 +28,14 @@
 			"label": "Max thread message chars",
 			"help": "Maximum characters preserved per captured OpenClaw thread message (200-20000). Higher values keep more of long messages in Nowledge thread history."
 		},
+		"captureExclude": {
+			"label": "Exclude session patterns",
+			"help": "Session key glob patterns to skip during auto-capture. Use * to match within a colon-segment. Example: agent:*:cron:*"
+		},
+		"captureSkipMarker": {
+			"label": "Skip marker",
+			"help": "Text marker in messages that prevents capture for the session. Default: #nmem-skip. Note: if compaction drops the marked message, capture resumes — use captureExclude patterns for persistent filtering."
+		},
 		"apiUrl": {
 			"label": "Server URL (remote mode)",
 			"help": "Leave empty for local mode (default: http://127.0.0.1:14242). Set to your remote server URL for cross-device or team access. See: https://docs.nowledge.co/docs/remote-access"
@@ -79,6 +87,17 @@
 				"maximum": 20000,
 				"description": "Maximum characters preserved per captured OpenClaw thread message before truncation."
 			},
+			"captureExclude": {
+				"type": "array",
+				"items": { "type": "string" },
+				"default": [],
+				"description": "Session key glob patterns to exclude from auto-capture. Glob * matches within a colon-delimited segment. Example: agent:*:cron:* excludes all cron job sessions."
+			},
+			"captureSkipMarker": {
+				"type": "string",
+				"default": "#nmem-skip",
+				"description": "Text marker in messages that prevents capture for the entire session. When any message contains this marker, the session is skipped. Note: compaction may drop the marked message — use captureExclude for persistent filtering."
+			},
 			"apiUrl": {
 				"type": "string",
 				"default": "",

package/package.json

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

package/src/config.js

@@ -21,6 +21,8 @@ const ALLOWED_KEYS = new Set([
 	"maxContextResults",
 	"recallMinScore",
 	"maxThreadMessageChars",
+	"captureExclude",
+	"captureSkipMarker",
 	"apiUrl",
 	"apiKey",
 	// Legacy aliases — accepted but not advertised
@@ -343,6 +345,43 @@ export function parseConfig(raw, logger) {
 	const apiKey = ak.value;
 	_sources.apiKey = ak.source;
 
+	// --- captureExclude: file > pluginConfig > default ---
+	const captureExclude = (() => {
+		const fromFile = Array.isArray(resolvedFile.captureExclude)
+			? resolvedFile.captureExclude
+			: null;
+		const fromPlugin = Array.isArray(resolvedPlugin.captureExclude)
+			? resolvedPlugin.captureExclude
+			: null;
+		_sources.captureExclude = fromFile
+			? "file"
+			: fromPlugin
+				? "pluginConfig"
+				: "default";
+		const entries = fromFile ?? fromPlugin ?? [];
+		return entries
+			.filter((v) => typeof v === "string" && v.trim())
+			.map((v) => v.trim());
+	})();
+
+	// --- captureSkipMarker: file > pluginConfig > default ---
+	const captureSkipMarker = (() => {
+		const fromFile =
+			typeof resolvedFile.captureSkipMarker === "string"
+				? resolvedFile.captureSkipMarker.trim()
+				: undefined;
+		const fromPlugin =
+			typeof resolvedPlugin.captureSkipMarker === "string"
+				? resolvedPlugin.captureSkipMarker.trim()
+				: undefined;
+		_sources.captureSkipMarker = fromFile
+			? "file"
+			: fromPlugin
+				? "pluginConfig"
+				: "default";
+		return fromFile || fromPlugin || "#nmem-skip";
+	})();
+
 	return {
 		sessionContext,
 		sessionDigest,
@@ -350,6 +389,8 @@ export function parseConfig(raw, logger) {
 		maxContextResults,
 		recallMinScore,
 		maxThreadMessageChars,
+		captureExclude,
+		captureSkipMarker,
 		apiUrl,
 		apiKey,
 		_sources,

package/src/context-engine.js

@@ -22,7 +22,12 @@
 
 import { ceState } from "./ce-state.js";
 import { BASE_GUIDANCE, SESSION_CONTEXT_GUIDANCE } from "./hooks/behavioral.js";
-import { appendOrCreateThread, triageAndDistill } from "./hooks/capture.js";
+import {
+	appendOrCreateThread,
+	hasSkipMarker,
+	matchesExcludePattern,
+	triageAndDistill,
+} from "./hooks/capture.js";
 import {
 	MAX_QUERY_LENGTH,
 	SHORT_QUERY_THRESHOLD,
@@ -342,8 +347,23 @@ export function createNowledgeMemContextEngineFactory(client, cfg, logger) {
 			}) {
 				if (isHeartbeat) return;
 
+				// Normalize sessionKey consistently with hook handlers
+				const normalizedKey = String(sessionKey || sessionId || "");
+
+				// Capture exclusion: pattern-based and marker-based filters
+				if (matchesExcludePattern(normalizedKey, cfg.captureExclude)) {
+					logger.debug?.(`ce: skipped excluded session ${normalizedKey}`);
+					return;
+				}
+				if (hasSkipMarker(messages, cfg.captureSkipMarker)) {
+					logger.debug?.(
+						`ce: skipped session with skip marker ${normalizedKey}`,
+					);
+					return;
+				}
+
 				const event = { messages, sessionFile };
-				const ctx = { sessionId, sessionKey };
+				const ctx = { sessionId, sessionKey: normalizedKey };
 
 				// 1. Always capture thread (idempotent, deduped)
 				const captureResult = await appendOrCreateThread({

package/src/hooks/capture.js

@@ -40,6 +40,63 @@ function _setSyncedMessageCount(threadId, count) {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Capture exclusion filters
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a glob pattern (where `*` matches within a colon-delimited segment)
+ * into a RegExp. Results are cached since patterns are immutable after parse.
+ */
+const _compiledPatterns = new Map();
+function _compileGlob(pattern) {
+	const key = String(pattern).toLowerCase();
+	let re = _compiledPatterns.get(key);
+	if (!re) {
+		re = new RegExp(
+			"^" +
+				key
+					.replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+					.replace(/\*/g, "[^:]*") +
+				"$",
+		);
+		_compiledPatterns.set(key, re);
+	}
+	return re;
+}
+
+/**
+ * Test whether a session key matches any exclusion glob pattern.
+ * Glob `*` matches within a colon-delimited segment (not across colons).
+ * Example: "agent:*:cron:*" matches "agent:main:cron:abc123"
+ *
+ * Exported for reuse by Context Engine and other capture paths.
+ */
+export function matchesExcludePattern(sessionKey, patterns) {
+	if (!Array.isArray(patterns) || patterns.length === 0) return false;
+	const key = String(sessionKey || "").toLowerCase();
+	return patterns.some((pattern) => _compileGlob(pattern).test(key));
+}
+
+/**
+ * Check if any message contains the skip marker text.
+ * Scans both raw message content and nested message objects.
+ *
+ * Exported for reuse by Context Engine and other capture paths.
+ */
+export function hasSkipMarker(messages, marker) {
+	if (!marker || typeof marker !== "string" || !Array.isArray(messages)) return false;
+	const markerLc = marker.toLowerCase();
+	return messages.some((msg) => {
+		const text = extractText(msg?.content ?? msg?.message?.content);
+		return text.toLowerCase().includes(markerLc);
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Message normalization utilities
+// ---------------------------------------------------------------------------
+
 export function truncate(text, max = DEFAULT_MAX_MESSAGE_CHARS) {
 	const str = String(text || "").trim();
 	if (!str) return "";
@@ -197,8 +254,9 @@ export async function appendOrCreateThread({
 	ctx,
 	reason,
 	maxMessageChars = DEFAULT_MAX_MESSAGE_CHARS,
+	resolvedMessages,
 }) {
-	const rawMessages = await resolveHookMessages(event);
+	const rawMessages = resolvedMessages ?? (await resolveHookMessages(event));
 	if (!Array.isArray(rawMessages) || rawMessages.length === 0) return;
 
 	const threadId = buildStableThreadId(event, ctx);
@@ -413,6 +471,22 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 		if (!event?.success) return;
 		if (ctx?.trigger === "heartbeat") return;
 
+		// Layer 1: pattern-based exclusion (e.g. cron jobs, subagent sessions)
+		const sessionKey = String(ctx?.sessionKey || ctx?.sessionId || "");
+		if (matchesExcludePattern(sessionKey, cfg.captureExclude)) {
+			logger.debug?.(`capture: skipped excluded session ${sessionKey}`);
+			return;
+		}
+
+		// Layer 2: marker-based exclusion (user typed #nmem-skip in conversation)
+		const resolvedMessages = await resolveHookMessages(event);
+		if (hasSkipMarker(resolvedMessages, cfg.captureSkipMarker)) {
+			logger.debug?.(
+				`capture: skipped session with skip marker ${sessionKey}`,
+			);
+			return;
+		}
+
 		const captureResult = await appendOrCreateThread({
 			client,
 			logger,
@@ -420,6 +494,7 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 			ctx,
 			reason: "agent_end",
 			maxMessageChars: cfg.maxThreadMessageChars,
+			resolvedMessages,
 		});
 
 		await triageAndDistill({ client, cfg, logger, captureResult, ctx });
@@ -435,10 +510,27 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
  *
  * Heartbeat sessions are skipped (same rationale as agent_end).
  */
-export function buildBeforeResetCaptureHandler(client, _cfg, logger) {
+export function buildBeforeResetCaptureHandler(client, cfg, logger) {
 	return async (event, ctx) => {
 		if (ceState.active) return;
 		if (ctx?.trigger === "heartbeat") return;
+
+		// Layer 1: pattern-based exclusion
+		const sessionKey = String(ctx?.sessionKey || ctx?.sessionId || "");
+		if (matchesExcludePattern(sessionKey, cfg.captureExclude)) {
+			logger.debug?.(`capture: skipped excluded session ${sessionKey}`);
+			return;
+		}
+
+		// Layer 2: marker-based exclusion
+		const resolvedMessages = await resolveHookMessages(event);
+		if (hasSkipMarker(resolvedMessages, cfg.captureSkipMarker)) {
+			logger.debug?.(
+				`capture: skipped session with skip marker ${sessionKey}`,
+			);
+			return;
+		}
+
 		const reason = typeof event?.reason === "string" ? event.reason : undefined;
 		await appendOrCreateThread({
 			client,
@@ -446,7 +538,8 @@ export function buildBeforeResetCaptureHandler(client, _cfg, logger) {
 			event,
 			ctx,
 			reason,
-			maxMessageChars: _cfg?.maxThreadMessageChars,
+			maxMessageChars: cfg.maxThreadMessageChars,
+			resolvedMessages,
 		});
 	};
 }

package/src/index.js

@@ -54,8 +54,14 @@ export default {
 		api.registerTool(createThreadSearchTool(client, logger));
 		api.registerTool(createThreadFetchTool(client, logger));
 
-		// Diagnostics
-		api.registerTool(createStatusTool(client, logger, cfg));
+		// Diagnostics — pass runtime config so the status tool can detect:
+		//   - plugins.allow missing or not including this plugin
+		//   - memory slot pointing elsewhere (e.g. memory-core)
+		const memorySlot = api.config?.plugins?.slots?.memory;
+		const pluginsAllow = api.config?.plugins?.allow;
+		api.registerTool(
+			createStatusTool(client, logger, cfg, { memorySlot, pluginsAllow }),
+		);
 
 		// --- Context Engine registration ---
 		// When the user sets `plugins.slots.contextEngine: "nowledge-mem"`,

package/src/tools/status.js

@@ -7,7 +7,7 @@
  */
 import { isDefaultApiUrl } from "../config.js";
 
-export function createStatusTool(client, _logger, cfg) {
+export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 	return {
 		name: "nowledge_mem_status",
 		description:
@@ -23,6 +23,60 @@ export function createStatusTool(client, _logger, cfg) {
 			const details = {};
 			const sources = cfg._sources || {};
 
+			// 0a. Plugin trust check — detect missing plugins.allow
+			const pluginsAllow = runtimeInfo.pluginsAllow;
+			const pluginId = "openclaw-nowledge-mem";
+			details.pluginsAllow = !Array.isArray(pluginsAllow)
+				? "(not set)"
+				: pluginsAllow.includes(pluginId)
+					? "listed"
+					: "set but plugin not included";
+
+			if (
+				Array.isArray(pluginsAllow) &&
+				pluginsAllow.length > 0 &&
+				!pluginsAllow.includes(pluginId)
+			) {
+				lines.push(
+					`⚠ plugins.allow is set but does not include "${pluginId}".`,
+				);
+				lines.push(
+					"  The plugin will be BLOCKED from loading unless it holds the memory slot or is explicitly enabled.",
+				);
+				lines.push(
+					`  Fix: add "${pluginId}" to plugins.allow in your OpenClaw config.`,
+				);
+				lines.push("");
+			} else if (!Array.isArray(pluginsAllow) || pluginsAllow.length === 0) {
+				lines.push(
+					"Plugin trust: plugins.allow not set (plugin loads via entries.enabled)",
+				);
+				lines.push(
+					`  Tip: set plugins.allow to ["${pluginId}"] to pin trust explicitly.`,
+				);
+				lines.push("");
+			} else {
+				lines.push(`Plugin trust: ${pluginId} (allowlisted)`);
+			}
+
+			// 0b. Memory slot check — detect misconfiguration early
+			const memorySlot = runtimeInfo.memorySlot;
+			details.memorySlot = memorySlot ?? "(unknown)";
+			if (memorySlot && memorySlot !== "openclaw-nowledge-mem") {
+				lines.push(
+					`⚠ Memory slot: "${memorySlot}" — Nowledge Mem is NOT the active memory plugin.`,
+				);
+				lines.push(
+					"  Only memory_search and memory_get will work. Other tools (save, connections, timeline, etc.) are inactive.",
+				);
+				lines.push(
+					'  Fix: run "openclaw plugins install @nowledge/openclaw-nowledge-mem" or set plugins.slots.memory to "openclaw-nowledge-mem" in your config.',
+				);
+				lines.push("");
+			} else if (memorySlot === "openclaw-nowledge-mem") {
+				lines.push("Memory slot: openclaw-nowledge-mem (active)");
+			}
+
 			// 1. Mode + connection target
 			const remote = !isDefaultApiUrl(cfg.apiUrl);
 			const mode = remote ? "remote" : "local";