Merge pull request #139 from vvvvroot/feat/capture-exclude

feat(capture): add captureExclude and captureSkipMarker

Author: wey-gu

nowledge-mem-openclaw-plugin/CLAUDE.md

@@ -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. |
 

nowledge-mem-openclaw-plugin/openclaw.plugin.json

@@ -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": "",

nowledge-mem-openclaw-plugin/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,13 +345,52 @@ 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,
 		digestMinInterval,
 		maxContextResults,
 		recallMinScore,
 		maxThreadMessageChars,
+		captureExclude,
+		captureSkipMarker,
 		apiUrl,
 		apiKey,
 		_sources,

nowledge-mem-openclaw-plugin/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({

nowledge-mem-openclaw-plugin/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,13 +471,30 @@ 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,
 			event,
 			ctx,
 			reason: "agent_end",
 			maxMessageChars: cfg.maxThreadMessageChars,
+			resolvedMessages,
 		});
 
 		await triageAndDistill({ client, cfg, logger, captureResult, ctx });
@@ -435,18 +510,36 @@ 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,
 			logger,
 			event,
 			ctx,
 			reason,
-			maxMessageChars: _cfg?.maxThreadMessageChars,
+			maxMessageChars: cfg.maxThreadMessageChars,
+			resolvedMessages,
 		});
 	};
 }