@nowledge/openclaw-nowledge-mem 0.7.0 → 0.7.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [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
+
+- **Thread sync no longer depends on argv-sized CLI payloads.** OpenClaw conversation capture now creates and appends threads through the Mem HTTP API instead of passing whole message arrays through `nmem ... -m '<json>'`. This removes the transport limit that caused repeated append failures on long or repetitive sessions.
+- **Session capture now syncs only the unsynced tail.** The plugin preserves the real transcript, asks Mem how many messages are already stored, and appends only the new tail instead of replaying the whole session on every hook or Context Engine turn.
+- **Remote config is still unified after the transport change.** The same resolved `apiUrl` and `apiKey` from OpenClaw settings / `~/.nowledge-mem/config.json` now drive both CLI-backed memory tools and API-backed thread sync.
+- **Removed lossy repetitive-session collapse.** The temporary content-based dedup workaround for cron-style sessions has been removed so conversation structure is preserved faithfully.
+
+## [0.7.1] - 2026-03-23
+
+### Fixed
+
+- **Heartbeat sessions no longer trigger thread capture.** Sessions with `ctx.trigger === "heartbeat"` are now skipped in hook handlers. For cron-triggered heartbeat sessions (which use `trigger: "cron"`), a content-based dedup detects repetitive patterns: when >50% of messages in a session are duplicates, only unique messages are kept. This collapses 20 repetitive heartbeat messages down to 2, eliminating the CLI timeout caused by oversized payloads.
+
 ## [0.7.0] - 2026-03-23
 
 ### Added

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

@@ -70,7 +70,7 @@ Connect to a Nowledge Mem server running elsewhere (a VPS, a home server, or a s
 
 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`:
+Or use the shared config file at `~/.nowledge-mem/config.json` so OpenClaw, `nmem`, Bub, Claude Code, and other integrations all point at the same remote Mem:
 
 ```json
 {
@@ -79,7 +79,9 @@ Or use a config file at `~/.nowledge-mem/openclaw.json`:
 }
 ```
 
-The `apiKey` is injected as `NMEM_API_KEY` into the nmem CLI process. Never passed as a CLI argument, never logged.
+Legacy `~/.nowledge-mem/openclaw.json` is still honored first for backward compatibility.
+
+The resolved `apiUrl` and `apiKey` are reused across the plugin: CLI-backed memory tools and API-backed thread sync both talk to the same backend. The `apiKey` is never passed as a CLI argument and is never logged.
 
 ### Configure via WebUI of OpenClaw
 
@@ -154,6 +156,7 @@ flowchart TD
 
 **Key points:**
 - Thread capture is unconditional: every conversation is saved and searchable via `nowledge_mem_thread_search`
+- Thread sync is incremental: the plugin preserves the real transcript but appends only the unsynced tail instead of replaying the whole session
 - LLM distillation only runs at `agent_end`, not during compaction/reset checkpoints
 - Distilled memories carry `sourceThreadId`, linking them back to the source conversation
 - Cooldown (`digestMinInterval`, default 300s) prevents burst distillation
@@ -430,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.0",
+	"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.0",
+	"version": "0.7.3",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {

package/src/client.js

@@ -54,15 +54,11 @@ function patchWmSection(currentContent, heading, { content, append } = {}) {
 }
 
 /**
- * Nowledge Mem client. Wraps the nmem CLI for local-first and remote operations.
+ * Nowledge Mem client. Wraps the nmem CLI plus direct API calls.
  *
- * All operations go through the CLI first. This means:
- * - Local mode: CLI uses http://127.0.0.1:14242 automatically
- * - Remote mode: configure via apiUrl + apiKey (plugin config or env vars)
- *   (see: https://docs.nowledge.co/docs/remote-access)
- *
- * Falls back to direct API calls when a CLI command is too new for the installed
- * version. The fallback path uses the same apiUrl / apiKey.
+ * Most interactive reads/writes stay CLI-first for local-first ergonomics.
+ * Thread create/append are API-first because large message batches should
+ * travel in an HTTP body, not as a single argv-sized JSON argument.
  *
  * Credential rules:
  * - apiUrl: passed to CLI via --api-url flag (not a secret)
@@ -559,42 +555,12 @@ export class NowledgeMemClient {
 			throw new Error("createThread requires at least one message");
 		}
 
-		let data;
-		try {
-			const args = [
-				"--json",
-				"t",
-				"create",
-				"-t",
-				normalizedTitle,
-				"-m",
-				JSON.stringify(messages),
-				"-s",
-				String(source),
-			];
-			if (threadId) {
-				args.push("--id", String(threadId));
-			}
-			data = await this.execJson(args);
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			const needsApiFallback =
-				Boolean(threadId) &&
-				(message.includes("unrecognized arguments: --id") ||
-					message.includes("invalid choice"));
-			if (!needsApiFallback) {
-				throw err;
-			}
-			this.logger.warn(
-				"createThread: CLI missing --id support, falling back to API",
-			);
-			data = await this.apiJson("POST", "/threads", {
-				thread_id: String(threadId),
-				title: normalizedTitle,
-				source: String(source),
-				messages,
-			});
-		}
+		const data = await this.apiJson("POST", "/threads", {
+			...(threadId ? { thread_id: String(threadId) } : {}),
+			title: normalizedTitle,
+			source: String(source),
+			messages,
+		});
 
 		return String(
 			data.id ?? data.thread?.thread_id ?? data.thread_id ?? "created",
@@ -615,50 +581,46 @@ export class NowledgeMemClient {
 			return { messagesAdded: 0, totalMessages: 0 };
 		}
 
+		const data = await this.apiJson(
+			"POST",
+			`/threads/${encodeURIComponent(normalizedThreadId)}/append`,
+			{
+				messages,
+				deduplicate,
+				...(idempotencyKey
+					? { idempotency_key: String(idempotencyKey) }
+					: {}),
+			},
+		);
+		return {
+			messagesAdded: Number(data.messages_added ?? 0),
+			totalMessages: Number(data.total_messages ?? 0),
+		};
+	}
+
+	async getThreadMessageCount(threadId) {
+		const normalizedThreadId = String(threadId || "").trim();
+		if (!normalizedThreadId) {
+			throw new Error("getThreadMessageCount requires threadId");
+		}
+
 		try {
-			const args = [
-				"--json",
-				"t",
-				"append",
-				normalizedThreadId,
-				"-m",
-				JSON.stringify(messages),
-				...(deduplicate ? [] : ["--no-deduplicate"]),
-			];
-			if (idempotencyKey) {
-				args.push("--idempotency-key", String(idempotencyKey));
-			}
-			const data = await this.execJson(args);
-			return {
-				messagesAdded: Number(data.messages_added ?? 0),
-				totalMessages: Number(data.total_messages ?? 0),
-			};
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			const needsApiFallback =
-				message.includes("invalid choice") ||
-				message.includes("unrecognized arguments");
-			if (!needsApiFallback) {
-				throw err;
-			}
-			this.logger.warn(
-				"appendThread: CLI missing append support, falling back to API",
-			);
 			const data = await this.apiJson(
-				"POST",
-				`/threads/${encodeURIComponent(normalizedThreadId)}/append`,
-				{
-					messages,
-					deduplicate,
-					...(idempotencyKey
-						? { idempotency_key: String(idempotencyKey) }
-						: {}),
-				},
+				"GET",
+				`/threads/${encodeURIComponent(normalizedThreadId)}?limit=1`,
+				undefined,
+				15_000,
 			);
-			return {
-				messagesAdded: Number(data.messages_added ?? 0),
-				totalMessages: Number(data.total_messages ?? 0),
-			};
+			return Number(
+				data.message_count ??
+					data.total_messages ??
+					(Array.isArray(data.messages) ? data.messages.length : 0),
+			);
+		} catch (err) {
+			if (this.isThreadNotFoundError(err)) {
+				return null;
+			}
+			throw err;
 		}
 	}
 

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

@@ -12,6 +12,8 @@ export const MIN_MESSAGES_FOR_DISTILL = 4;
 // Evicted opportunistically when new entries are set (see _setLastCapture).
 const _lastCaptureAt = new Map();
 const _MAX_COOLDOWN_ENTRIES = 200;
+const _syncedMessageCounts = new Map();
+const _MAX_SYNC_CURSOR_ENTRIES = 500;
 
 function _setLastCapture(threadId, now) {
 	_lastCaptureAt.set(threadId, now);
@@ -24,6 +26,77 @@ function _setLastCapture(threadId, now) {
 	}
 }
 
+function _setSyncedMessageCount(threadId, count) {
+	if (!threadId || !Number.isFinite(count) || count < 0) return;
+	_syncedMessageCounts.set(threadId, Math.trunc(count));
+	if (_syncedMessageCounts.size > _MAX_SYNC_CURSOR_ENTRIES) {
+		const excess = _syncedMessageCounts.size - _MAX_SYNC_CURSOR_ENTRIES;
+		let removed = 0;
+		for (const key of _syncedMessageCounts.keys()) {
+			_syncedMessageCounts.delete(key);
+			removed += 1;
+			if (removed >= excess) break;
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// 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 "";
@@ -181,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);
@@ -194,7 +268,7 @@ export async function appendOrCreateThread({
 		.filter(Boolean);
 	if (normalized.length === 0) return;
 
-	const messages = normalized.map((message, index) => ({
+	const allMessages = normalized.map((message, index) => ({
 		role: message.role,
 		content: message.content,
 		timestamp: message.timestamp,
@@ -210,16 +284,46 @@ export async function appendOrCreateThread({
 			session_id: sessionId || undefined,
 		},
 	}));
-	const idempotencyKey = buildAppendIdempotencyKey(threadId, reason, messages);
+
+	let syncedCount = _syncedMessageCounts.get(threadId);
+	if (syncedCount === undefined) {
+		syncedCount = await client.getThreadMessageCount(threadId);
+		if (syncedCount !== null) {
+			_setSyncedMessageCount(threadId, syncedCount);
+		}
+	}
+
+	if (typeof syncedCount === "number" && syncedCount > allMessages.length) {
+		// OpenClaw compaction can shrink the active transcript after we already
+		// stored the pre-compaction history. Reset the local cursor to the new
+		// compacted length so future turns append only the post-compaction tail.
+		_setSyncedMessageCount(threadId, allMessages.length);
+		return { threadId, normalized, messagesAdded: 0 };
+	}
+
+	const appendStart =
+		typeof syncedCount === "number" && syncedCount > 0
+			? Math.min(syncedCount, allMessages.length)
+			: 0;
+	const newMessages = allMessages.slice(appendStart);
+	if (newMessages.length === 0) {
+		return { threadId, normalized, messagesAdded: 0 };
+	}
+	const idempotencyKey = buildAppendIdempotencyKey(
+		threadId,
+		reason,
+		newMessages,
+	);
 
 	try {
 		const appended = await client.appendThread({
 			threadId,
-			messages,
+			messages: newMessages,
 			deduplicate: true,
 			idempotencyKey,
 		});
 		const added = appended.messagesAdded ?? 0;
+		_setSyncedMessageCount(threadId, allMessages.length);
 		logger.info(
 			`capture: appended ${added} messages to ${threadId} (${reason || "event"})`,
 		);
@@ -236,13 +340,14 @@ export async function appendOrCreateThread({
 		const createdId = await client.createThread({
 			threadId,
 			title,
-			messages,
+			messages: allMessages,
 			source: "openclaw",
 		});
+		_setSyncedMessageCount(threadId, allMessages.length);
 		logger.info(
-			`capture: created thread ${createdId} with ${messages.length} messages (${reason || "event"})`,
+			`capture: created thread ${createdId} with ${allMessages.length} messages (${reason || "event"})`,
 		);
-		return { threadId, normalized, messagesAdded: messages.length };
+		return { threadId, normalized, messagesAdded: allMessages.length };
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		logger.warn(`capture: thread create failed for ${threadId}: ${message}`);
@@ -354,11 +459,33 @@ export async function triageAndDistill({
  *
  * When the context engine is active, this hook is a no-op — afterTurn
  * handles capture and distillation through the CE lifecycle.
+ *
+ * Heartbeat sessions (ctx.trigger === "heartbeat") are skipped — they
+ * produce repetitive status pings that aren't worth preserving.
+ * Other sessions use incremental tail sync: we preserve the real
+ * transcript, but only append messages that are not already stored.
  */
 export function buildAgentEndCaptureHandler(client, cfg, logger) {
 	return async (event, ctx) => {
 		if (ceState.active) return;
 		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,
@@ -367,6 +494,7 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 			ctx,
 			reason: "agent_end",
 			maxMessageChars: cfg.maxThreadMessageChars,
+			resolvedMessages,
 		});
 
 		await triageAndDistill({ client, cfg, logger, captureResult, ctx });
@@ -379,10 +507,30 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
  *
  * When the context engine is active, this hook is a no-op — afterTurn
  * handles capture through the CE lifecycle.
+ *
+ * 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,
@@ -390,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";