@nowledge/openclaw-nowledge-mem 0.8.31 → 0.8.34

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to the Nowledge Mem OpenClaw plugin will be documented in th
 
 ## Unreleased
 
+## [0.8.34] - 2026-08-31
+
+- Fixed automatic capture for agent-scoped OpenClaw 2.0 Incognito session keys.
+- Added regression coverage for bare and agent-prefixed Incognito sessions.
+
+## [0.8.33] - 2026-08-31
+
+### Fixed
+
+- Automatic thread capture now honors OpenClaw 2.0 Incognito session keys.
+  Incognito conversations remain process-only unless the user explicitly calls
+  a memory-writing tool.
+- Context Engine diagnostics now report the package version instead of a stale
+  hardcoded version.
+
+## [0.8.32] - 2026-08-21
+
+### Fixed
+
+- Automatic thread capture now sends the paired Mem checkpoint contract
+  (`expected_message_count`, a content-bound idempotency key, and
+  `append_mode: "checkpointed"`) and only advances the local cursor after an
+  explicit append/create acknowledgement.
+- Same-length and earlier-prefix replacements reset to a full replay. OpenClaw
+  compaction shrinks still reset the local cursor without replaying the
+  compacted summary.
+- Destination-lane cursor state is isolated by API URL, credentials, and space.
+- Thread create/append honor `NMEM_SYNC_TIMEOUT_MS` with a 120s default and
+  1-second to 30-minute bounds.
+- Automatic capture now skips persist until a user+assistant pair exists,
+  so a user-only reset checkpoint is not stored as a complete thread.
+
+
 ## [0.8.31] - 2026-07-12
 
 ### Improved

package/CLAUDE.md

@@ -7,7 +7,7 @@ Continuation guide for `community/nowledge-mem-openclaw-plugin`.
 - Plugin target: OpenClaw plugin runtime (memory slot + context engine)
 - Runtime: JS ESM modules under `src/`, no TS build pipeline
 - Memory backend: `nmem` CLI (fallback: `uvx --from nmem-cli nmem`)
-- OpenClaw minimum: `2026.4.5` (`registerMemoryCorpusSupplement` for dreaming integration)
+- OpenClaw minimum: `2026.5.3` (`registerMemoryCorpusSupplement` for dreaming integration)
 - Architecture: **CLI-first via OpenClaw runtime** - all CLI execution goes through `api.runtime.system.runCommandWithTimeout`, not direct `child_process`
 - Context engine: registered under the canonical id `nowledge-mem` plus the compatibility alias `openclaw-nowledge-mem`. Activated when OpenClaw sets either value in `plugins.slots.contextEngine`. Manual config should still prefer `nowledge-mem`. Falls back to hooks when CE is not active.
 - Remote mode: `~/.nowledge-mem/config.json` (shared) or OpenClaw dashboard. Legacy `openclaw.json` still honored.
@@ -58,6 +58,8 @@ openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema,
 ~/.nowledge-mem/config.json   - shared credentials (apiUrl/apiKey) read by all Nowledge Mem tools
 ```
 
+Automatic capture excludes OpenClaw 2.0's canonical Incognito session keys. Explicit memory tool calls remain available for intentional saves.
+
 ## Corpus Supplement (Dreaming Integration)
 
 When `corpusSupplement: true`, the plugin registers a `MemoryCorpusSupplement` via `api.registerMemoryCorpusSupplement()`. This makes Nowledge Mem's knowledge graph searchable through memory-core's recall pipeline, including its three-phase dreaming system (light, deep, REM).

package/README.md

@@ -11,10 +11,15 @@ This is not a flat note store. Nowledge Mem links related knowledge into a graph
 - [Nowledge Mem](https://mem.nowledge.co) desktop app **or** `nmem` CLI
 - [OpenClaw](https://openclaw.ai) >= 2026.5.3 for ClawHub installs. Older 2026.4.x builds can reject current ClawHub packages with an archive integrity mismatch before the plugin is installed.
 
+OpenClaw 2.0 (`2026.8.1`) is supported. Automatic capture follows OpenClaw's
+privacy boundary: Incognito sessions are never copied to Nowledge Mem or
+distilled automatically. An explicit memory tool call can still save something
+the user intentionally asks Mem to keep.
+
 ## Installation
 
 ```bash
-openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem
+openclaw plugins install clawhub:nowledge-mem
 ```
 
 OpenClaw's installer writes the install record, enables the plugin, and switches the `memory` slot to `openclaw-nowledge-mem`. On current OpenClaw builds, that same install flow may also set `plugins.slots.contextEngine` to `openclaw-nowledge-mem`. Plugin `0.8.18+` accepts that automatically as a compatibility alias.
@@ -30,7 +35,7 @@ If `openclaw config get tools` shows a restrictive profile such as `coding`, pre
 To update the plugin, re-run the ClawHub install with `--force`:
 
 ```bash
-openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem --force
+openclaw plugins install clawhub:nowledge-mem --force
 ```
 
 Use this instead of `openclaw plugins update openclaw-nowledge-mem` when an old install record is pinned to a specific version.
@@ -220,7 +225,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
+- Thread sync is incremental: the plugin preserves the real transcript, appends only the unsynced tail, and requires Mem's checkpointed acknowledgement before the local cursor advances
 - 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
@@ -498,6 +503,7 @@ NMEM_CORPUS_MAX_RESULTS=5
 NMEM_CORPUS_MIN_SCORE=0
 NMEM_API_URL=https://...
 NMEM_API_KEY=your-key
+NMEM_SYNC_TIMEOUT_MS=120000
 ```
 
 ### Priority
@@ -537,7 +543,7 @@ If you also use linked or workspace copies, review `plugins.load.paths` before r
 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 clawhub:@nowledge/openclaw-nowledge-mem
+openclaw plugins install clawhub:nowledge-mem
 ```
 
 Or set the slot manually in `~/.openclaw/openclaw.json`:

package/SKILL.md

@@ -28,6 +28,8 @@ When talking to users:
 - For remote mode, say "Set `apiUrl`, and add `apiKey` when the server requires auth."
 - Do not imply that OpenClaw is the only source of truth. It is one client of the user's larger memory system.
 - Do not imply that cloud backup is the default. Our default story is local-first.
+- OpenClaw 2.0 Incognito sessions are never automatically captured or distilled.
+  Only an explicit memory-writing tool call persists information by user choice.
 
 Good user-facing explanation:
 
@@ -103,7 +105,7 @@ Success means the backend responds correctly through `nmem`. Do not skip this st
 Default install:
 
 ```bash
-openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem
+openclaw plugins install clawhub:nowledge-mem
 ```
 
 If this fails with `archive integrity mismatch`, update OpenClaw first, then
@@ -112,7 +114,7 @@ retry. Current ClawHub packages require OpenClaw 2026.5.3 or later.
 To update an existing install:
 
 ```bash
-openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem --force
+openclaw plugins install clawhub:nowledge-mem --force
 ```
 
 Alternatively, if the user is installing from OpenClaw's default registry rather than ClawHub, this also works:
@@ -230,7 +232,7 @@ If only `memory_search` and `memory_get` tools are available (other Nowledge Mem
 }
 ```
 
-If missing, reinstall (`openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem`) which sets the slot automatically. This is common after upgrading OpenClaw to 3.22+ where the default memory slot changed.
+If missing, reinstall (`openclaw plugins install clawhub: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.
 
@@ -280,7 +282,7 @@ What to expect:
 | `nmem --json status` fails in local mode | Start Nowledge Mem locally first |
 | Remote mode fails | Re-run `nmem --json --api-url ... status` with the exact URL and auth you plan to use |
 | `openclaw nowledge-mem status` fails after install | Restart OpenClaw and confirm the plugin was installed successfully |
-| ClawHub reports `archive integrity mismatch` | Update OpenClaw to 2026.5.3+ or latest, then reinstall with `openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem --force` |
+| ClawHub reports `archive integrity mismatch` | Update OpenClaw to 2026.5.3+ or latest, then reinstall with `openclaw plugins install clawhub:nowledge-mem --force` |
 | `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` |

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
 	"id": "openclaw-nowledge-mem",
 	"name": "Nowledge Mem",
 	"description": "Cross-tool knowledge graph memory for OpenClaw with startup context, graph search, and session distillation.",
-	"version": "0.8.31",
+	"version": "0.8.34",
 	"kind": ["memory", "context-engine"],
 	"contracts": {
 		"tools": [

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
 	"displayName": "Nowledge Mem for OpenClaw",
-	"version": "0.8.31",
+	"version": "0.8.34",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {
@@ -29,7 +29,7 @@
 			"./src/index.js"
 		],
 		"install": {
-			"clawhubSpec": "clawhub:@nowledge/openclaw-nowledge-mem",
+			"clawhubSpec": "clawhub:nowledge-mem",
 			"npmSpec": "@nowledge/openclaw-nowledge-mem",
 			"defaultChoice": "clawhub"
 		},
@@ -37,7 +37,7 @@
 			"pluginApi": ">=2026.5.3"
 		},
 		"build": {
-			"openclawVersion": "2026.6.10"
+			"openclawVersion": "2026.8.1"
 		},
 		"release": {
 			"publishToClawHub": true,

package/src/client.js

@@ -1,4 +1,11 @@
 import { buildNmemSpawnEnv } from "./spawn-env.js";
+import {
+	isCheckpointConflictResponse,
+	isCheckpointedAppendAck,
+	isThreadAppendAck,
+	sessionSyncLaneKey,
+	threadCreateAck,
+} from "./session-delta.js";
 
 /**
  * Patch a single markdown section in a Working Memory document.
@@ -94,6 +101,26 @@ export class NowledgeMemClient {
 				? credentials.spaceId
 				: "";
 		this._spaceRef = String(resolvedSpace ?? "").trim();
+		this._threadSyncTimeoutMs = Number.isInteger(credentials.threadSyncTimeoutMs)
+			? credentials.threadSyncTimeoutMs
+			: 120_000;
+	}
+
+	getSpaceRef() {
+		return this._spaceRef;
+	}
+
+	getThreadSyncTimeoutMs() {
+		return this._threadSyncTimeoutMs;
+	}
+
+	cursorKey(threadId) {
+		return sessionSyncLaneKey(
+			threadId,
+			this._apiUrl,
+			this._apiKey,
+			this._spaceRef,
+		);
 	}
 
 	// ── API helpers (fallback path and direct operations) ─────────────────────
@@ -162,7 +189,11 @@ export class NowledgeMemClient {
 							: typeof data?.raw === "string"
 								? data.raw
 								: `HTTP ${response.status}`;
-				throw new Error(detail);
+				const error = new Error(detail);
+				error.status = response.status;
+				error.code =
+					typeof data?.error_code === "string" ? data.error_code : undefined;
+				throw error;
 			}
 			return data;
 		} finally {
@@ -585,6 +616,10 @@ export class NowledgeMemClient {
 	}
 
 	async createThread({ threadId, title, messages, source = "openclaw" }) {
+		const normalizedThreadId = String(threadId || "").trim();
+		if (!normalizedThreadId) {
+			throw new Error("createThread requires threadId");
+		}
 		const normalizedTitle = String(title || "").trim();
 		if (!normalizedTitle) {
 			throw new Error("createThread requires a non-empty title");
@@ -597,16 +632,21 @@ export class NowledgeMemClient {
 			"POST",
 			"/threads",
 			{
-				...(threadId ? { thread_id: String(threadId) } : {}),
+				thread_id: normalizedThreadId,
 				title: normalizedTitle,
 				source: String(source),
 				messages,
 			},
+			this._threadSyncTimeoutMs,
 		);
 
-		return String(
-			data.id ?? data.thread?.thread_id ?? data.thread_id ?? "created",
-		);
+		const ack = threadCreateAck(data, normalizedThreadId);
+		if (!ack) {
+			throw new Error(
+				"Thread create did not include an explicit persistence acknowledgement",
+			);
+		}
+		return ack;
 	}
 
 	async appendThread({
@@ -614,6 +654,7 @@ export class NowledgeMemClient {
 		messages,
 		deduplicate = true,
 		idempotencyKey,
+		expectedMessageCount,
 	}) {
 		const normalizedThreadId = String(threadId || "").trim();
 		if (!normalizedThreadId) {
@@ -623,6 +664,7 @@ export class NowledgeMemClient {
 			return { messagesAdded: 0, totalMessages: 0 };
 		}
 
+		const checkpointed = Number.isInteger(expectedMessageCount);
 		const data = await this.apiJson(
 			"POST",
 			`/threads/${encodeURIComponent(normalizedThreadId)}/append`,
@@ -632,11 +674,25 @@ export class NowledgeMemClient {
 				...(idempotencyKey
 					? { idempotency_key: String(idempotencyKey) }
 					: {}),
+				...(checkpointed
+					? { expected_message_count: expectedMessageCount }
+					: {}),
 			},
+			this._threadSyncTimeoutMs,
 		);
+		if (!isThreadAppendAck(data)) {
+			throw new Error(
+				"Thread append did not include an explicit persistence acknowledgement",
+			);
+		}
+		if (checkpointed && !isCheckpointedAppendAck(data)) {
+			throw new Error(
+				"Thread append was not acknowledged as checkpointed",
+			);
+		}
 		return {
-			messagesAdded: Number(data.messages_added ?? 0),
-			totalMessages: Number(data.total_messages ?? 0),
+			messagesAdded: data.messages_added,
+			totalMessages: data.total_messages,
 		};
 	}
 
@@ -679,9 +735,16 @@ export class NowledgeMemClient {
 			err instanceof Error ? err.message : String(err)
 		).toLowerCase();
 		return (
-			message.includes("thread not found") ||
-			message.includes("404") ||
-			message.includes("not found")
+			err?.code === "thread_not_found" ||
+			err?.status === 404 ||
+			(err?.status === 400 && message.includes("thread not found"))
+		);
+	}
+
+	isCheckpointConflictError(err) {
+		return (
+			err?.code === "checkpoint_conflict" ||
+			isCheckpointConflictResponse({ error_code: err?.code })
 		);
 	}
 

package/src/context-engine.js

@@ -30,8 +30,8 @@ import { BASE_GUIDANCE, SESSION_CONTEXT_GUIDANCE } from "./hooks/behavioral.js";
 import {
 	appendOrCreateThread,
 	hasSkipMarker,
-	isInternalCaptureSessionKey,
 	isCronCaptureSessionKey,
+	isInternalCaptureSessionKey,
 	matchesExcludePattern,
 	triageAndDistill,
 } from "./hooks/capture.js";
@@ -41,6 +41,7 @@ import {
 	buildRecalledKnowledgeBlock,
 	escapeForPrompt,
 } from "./hooks/recall.js";
+import { NOWLEDGE_MEM_PLUGIN_VERSION } from "./plugin-version.js";
 
 // ---------------------------------------------------------------------------
 // Per-session state
@@ -183,7 +184,7 @@ export function createNowledgeMemContextEngineFactory(
 			info: {
 				id: "nowledge-mem",
 				name: "Nowledge Mem",
-				version: "0.8.25",
+				version: NOWLEDGE_MEM_PLUGIN_VERSION,
 				ownsCompaction: false,
 			},
 

package/src/hooks/capture.js

@@ -1,6 +1,12 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { buildStableThreadId } from "./thread-identity.js";
+import {
+	contentBoundIdempotencyKey,
+	hasUserAndAssistant,
+	prefixFingerprint,
+	selectSnapshotDelta,
+} from "../session-delta.js";
 export {
 	_resetConversationRoots,
 	buildStableThreadId,
@@ -25,7 +31,7 @@ const OPENCLAW_INTERNAL_SENDER_BLOCK_RE =
 // Evicted opportunistically when new entries are set (see _setLastCapture).
 const _lastCaptureAt = new Map();
 const _MAX_COOLDOWN_ENTRIES = 200;
-const _syncedMessageCounts = new Map();
+const _acknowledgedCursors = new Map();
 const _MAX_SYNC_CURSOR_ENTRIES = 500;
 const CAPTURE_MESSAGE_MODE_AUTO = "auto";
 const CAPTURE_MESSAGE_MODE_SNAPSHOT = "snapshot";
@@ -70,20 +76,34 @@ 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;
+function _laneKey(client, threadId) {
+	return typeof client?.cursorKey === "function"
+		? client.cursorKey(threadId)
+		: String(threadId || "");
+}
+
+function _getCursor(client, threadId) {
+	return _acknowledgedCursors.get(_laneKey(client, threadId));
+}
+
+function _setAcknowledgedCursor(client, threadId, cursor) {
+	if (!threadId || !cursor) return;
+	_acknowledgedCursors.set(_laneKey(client, threadId), cursor);
+	if (_acknowledgedCursors.size > _MAX_SYNC_CURSOR_ENTRIES) {
+		const excess = _acknowledgedCursors.size - _MAX_SYNC_CURSOR_ENTRIES;
 		let removed = 0;
-		for (const key of _syncedMessageCounts.keys()) {
-			_syncedMessageCounts.delete(key);
+		for (const key of _acknowledgedCursors.keys()) {
+			_acknowledgedCursors.delete(key);
 			removed += 1;
 			if (removed >= excess) break;
 		}
 	}
 }
 
+export function _resetSyncCursors() {
+	_acknowledgedCursors.clear();
+}
+
 // ---------------------------------------------------------------------------
 // Capture exclusion filters
 // ---------------------------------------------------------------------------
@@ -136,6 +156,20 @@ export function isCronCaptureSessionKey(sessionKey) {
 	return isAgentCronSessionKey(raw);
 }
 
+/**
+ * OpenClaw 2.0 reserves these process-only keys for Incognito sessions.
+ * Keep this aligned with the host's routing helper so automatic capture does
+ * not turn an in-memory conversation into a durable external transcript.
+ * Explicit memory tool calls are unaffected because this only guards hooks.
+ */
+export function isIncognitoCaptureSessionKey(sessionKey) {
+	const raw = String(sessionKey || "")
+		.trim()
+		.toLowerCase();
+	const candidate = parseAgentSessionKey(raw)?.rest ?? raw;
+	return /^(?:dashboard|subagent|internal-session-effects):incognito-[^:]+$/u.test(candidate);
+}
+
 /**
  * Check if any message contains the skip marker text.
  * Scans both raw message content and nested message objects.
@@ -164,7 +198,7 @@ export function isInternalCaptureSessionKey(sessionKey) {
 		.toLowerCase();
 	if (!raw) return false;
 	if (raw.startsWith("temp:")) return true;
-	return isSubagentSessionKey(raw);
+	return isSubagentSessionKey(raw) || isIncognitoCaptureSessionKey(raw);
 }
 
 function stripOpenClawDirectiveTags(text) {
@@ -386,18 +420,18 @@ function buildExternalId({
 	return `oc-msg:${digest}`;
 }
 
-function buildAppendIdempotencyKey(threadId, reason, messages) {
-	const seed = {
-		threadId: String(threadId || ""),
-		reason: String(reason || "event"),
-		count: Array.isArray(messages) ? messages.length : 0,
-		externalIds: Array.isArray(messages)
-			? messages
-					.map((m) => m?.metadata?.external_id)
-					.filter((v) => typeof v === "string" && v.length > 0)
-			: [],
-	};
-	return `oc-batch:${createHash("sha1").update(JSON.stringify(seed)).digest("hex")}`;
+function messageExternalId(message) {
+	return String(message?.metadata?.external_id || "");
+}
+
+function buildContentBoundIdempotencyKey(threadId, reason, start, end, fingerprint) {
+	return contentBoundIdempotencyKey(
+		`oc:${String(reason || "event")}`,
+		threadId,
+		start,
+		end,
+		fingerprint,
+	);
 }
 
 function hasStableExternalHints(normalized) {
@@ -466,10 +500,28 @@ export async function appendOrCreateThread({
 		.map((message) => normalizeRoleMessage(message, maxMessageChars))
 		.filter(Boolean);
 	if (normalized.length === 0) return;
-	const title = buildThreadTitle(ctx, normalized);
+	const resolvedMessageMode =
+		messageMode === CAPTURE_MESSAGE_MODE_DELTA ||
+		(messageMode === CAPTURE_MESSAGE_MODE_AUTO &&
+			hasStableExternalHints(normalized))
+			? CAPTURE_MESSAGE_MODE_DELTA
+			: CAPTURE_MESSAGE_MODE_SNAPSHOT;
+	let captured = normalized;
+	if (resolvedMessageMode === CAPTURE_MESSAGE_MODE_SNAPSHOT) {
+		let lastAssistantIndex = -1;
+		for (let index = normalized.length - 1; index >= 0; index -= 1) {
+			if (normalized[index].role === "assistant") {
+				lastAssistantIndex = index;
+				break;
+			}
+		}
+		captured = normalized.slice(0, lastAssistantIndex + 1);
+	}
+	if (!hasUserAndAssistant(captured)) return;
+	const title = buildThreadTitle(ctx, captured);
 
 	const buildMessages = (resolvedMessageMode) =>
-		normalized.map((message, index) => ({
+		captured.map((message, index) => ({
 			role: message.role,
 			content: message.content,
 			timestamp: message.timestamp,
@@ -495,111 +547,174 @@ export async function appendOrCreateThread({
 			: CAPTURE_MESSAGE_MODE_SNAPSHOT,
 	);
 
-	let syncedCount = _syncedMessageCounts.get(threadId);
-	if (syncedCount === undefined) {
-		syncedCount = await client.getThreadMessageCount(threadId);
-		if (syncedCount !== null) {
-			_setSyncedMessageCount(threadId, syncedCount);
+	let cursor = _getCursor(client, threadId);
+	if (cursor === undefined) {
+		let remoteCount = null;
+		try {
+			remoteCount = await client.getThreadMessageCount(threadId);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			logger.warn(
+				`capture: remote message count failed for ${threadId}: ${message}`,
+			);
+		}
+		if (remoteCount !== null && Number.isFinite(remoteCount) && remoteCount >= 0) {
+			cursor = {
+				count: 0,
+				remoteCount: Math.trunc(remoteCount),
+				prefixFingerprint: "",
+			};
 		}
 	}
 
-	const resolvedMessageMode =
-		messageMode === CAPTURE_MESSAGE_MODE_DELTA ||
-		(messageMode === CAPTURE_MESSAGE_MODE_AUTO &&
-			hasStableExternalHints(normalized))
-			? CAPTURE_MESSAGE_MODE_DELTA
-			: CAPTURE_MESSAGE_MODE_SNAPSHOT;
 	if (resolvedMessageMode === CAPTURE_MESSAGE_MODE_DELTA) {
 		allMessages = buildMessages(CAPTURE_MESSAGE_MODE_DELTA);
-		const idempotencyKey = buildAppendIdempotencyKey(
+		const next = {
+			count: allMessages.length,
+			remoteCount: cursor?.remoteCount ?? allMessages.length,
+			...(allMessages.length > 0
+				? { lastExternalId: messageExternalId(allMessages[allMessages.length - 1]) }
+				: {}),
+			prefixFingerprint: prefixFingerprint(allMessages, allMessages.length),
+		};
+		return persistMessages({
+			client,
+			logger,
 			threadId,
+			title,
 			reason,
+			normalized,
 			allMessages,
-		);
-		try {
-			const appended = await client.appendThread({
-				threadId,
-				messages: allMessages,
-				deduplicate: true,
-				idempotencyKey,
-			});
-			const added = appended.messagesAdded ?? 0;
-			const total =
-				Number.isFinite(appended.totalMessages) && appended.totalMessages >= 0
-					? appended.totalMessages
-					: typeof syncedCount === "number"
-						? syncedCount + added
-						: allMessages.length;
-			_setSyncedMessageCount(threadId, total);
-			logger.info(
-				`capture: appended ${added} delta messages to ${threadId} (${reason || "event"})`,
-			);
-			return { threadId, normalized, messagesAdded: added };
-		} catch (err) {
-			if (!client.isThreadNotFoundError(err)) {
-				const message = err instanceof Error ? err.message : String(err);
-				logger.warn(
-					`capture: thread append failed for ${threadId}: ${message}`,
-				);
-				return null;
-			}
-		}
-
-		try {
-			const createdId = await client.createThread({
-				threadId,
-				title,
-				messages: allMessages,
-				source: "openclaw",
-			});
-			_setSyncedMessageCount(threadId, allMessages.length);
-			logger.info(
-				`capture: created thread ${createdId} with ${allMessages.length} delta messages (${reason || "event"})`,
-			);
-			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}`);
-			return null;
-		}
+			toSend: allMessages,
+			start: 0,
+			end: allMessages.length,
+			next,
+			cursor,
+			reset: false,
+			label: "delta",
+		});
 	}
 
-	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 tail after compaction.
-		_setSyncedMessageCount(threadId, allMessages.length);
+	const delta = selectSnapshotDelta(
+		allMessages,
+		cursor,
+		messageExternalId,
+	);
+	if (delta.compactionShrink) {
+		_setAcknowledgedCursor(client, threadId, delta.next);
 		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) {
+	if (delta.messages.length === 0) {
 		return { threadId, normalized, messagesAdded: 0 };
 	}
-	const idempotencyKey = buildAppendIdempotencyKey(
+	return persistMessages({
+		client,
+		logger,
 		threadId,
+		title,
 		reason,
-		newMessages,
+		normalized,
+		allMessages,
+		toSend: delta.messages,
+		start: delta.start,
+		end: delta.end,
+		next: delta.next,
+		cursor,
+		reset: delta.reset,
+		label: "snapshot",
+	});
+}
+
+async function persistMessages({
+	client,
+	logger,
+	threadId,
+	title,
+	reason,
+	normalized,
+	allMessages,
+	toSend,
+	start,
+	end,
+	next,
+	cursor,
+	reset,
+	label,
+}) {
+	const fingerprint = next.prefixFingerprint;
+	const idempotencyKey = buildContentBoundIdempotencyKey(
+		threadId,
+		reason,
+		start,
+		end,
+		fingerprint,
 	);
+	const expectedMessageCount =
+		!reset && Number.isInteger(cursor?.remoteCount) && cursor.prefixFingerprint
+			? cursor.remoteCount
+			: undefined;
+
+	const acknowledge = (remoteCount, added) => {
+		_setAcknowledgedCursor(client, threadId, {
+			...next,
+			remoteCount,
+		});
+		return { threadId, normalized, messagesAdded: added };
+	};
 
 	try {
 		const appended = await client.appendThread({
 			threadId,
-			messages: newMessages,
+			messages: toSend,
 			deduplicate: true,
 			idempotencyKey,
+			expectedMessageCount,
 		});
 		const added = appended.messagesAdded ?? 0;
-		_setSyncedMessageCount(threadId, allMessages.length);
+		const total =
+			Number.isInteger(appended.totalMessages) && appended.totalMessages >= 0
+				? appended.totalMessages
+				: toSend.length;
 		logger.info(
-			`capture: appended ${added} messages to ${threadId} (${reason || "event"})`,
+			`capture: appended ${added} ${label} messages to ${threadId} (${reason || "event"})`,
 		);
-		return { threadId, normalized, messagesAdded: added };
+		return acknowledge(total, added);
 	} catch (err) {
+		if (client.isCheckpointConflictError?.(err)) {
+			try {
+				const reconciled = await client.appendThread({
+					threadId,
+					messages: allMessages,
+					deduplicate: true,
+					idempotencyKey: buildContentBoundIdempotencyKey(
+						threadId,
+						`${reason || "event"}-reconcile`,
+						0,
+						allMessages.length,
+						fingerprint,
+					),
+				});
+				const added = reconciled.messagesAdded ?? allMessages.length;
+				const total =
+					Number.isInteger(reconciled.totalMessages) &&
+					reconciled.totalMessages >= 0
+						? reconciled.totalMessages
+						: allMessages.length;
+				logger.info(
+					`capture: reconciled ${added} messages to ${threadId} (${reason || "event"})`,
+				);
+				return acknowledge(total, added);
+			} catch (reconcileErr) {
+				const message =
+					reconcileErr instanceof Error
+						? reconcileErr.message
+						: String(reconcileErr);
+				logger.warn(
+					`capture: thread reconcile failed for ${threadId}: ${message}`,
+				);
+				return null;
+			}
+		}
 		if (!client.isThreadNotFoundError(err)) {
 			const message = err instanceof Error ? err.message : String(err);
 			logger.warn(`capture: thread append failed for ${threadId}: ${message}`);
@@ -608,17 +723,16 @@ export async function appendOrCreateThread({
 	}
 
 	try {
-		const createdId = await client.createThread({
+		const created = await client.createThread({
 			threadId,
 			title,
 			messages: allMessages,
 			source: "openclaw",
 		});
-		_setSyncedMessageCount(threadId, allMessages.length);
 		logger.info(
-			`capture: created thread ${createdId} with ${allMessages.length} messages (${reason || "event"})`,
+			`capture: created thread ${created.threadId} with ${created.totalMessages} persisted messages (${reason || "event"})`,
 		);
-		return { threadId, normalized, messagesAdded: allMessages.length };
+		return acknowledge(created.totalMessages, allMessages.length);
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		logger.warn(`capture: thread create failed for ${threadId}: ${message}`);

package/src/index.js

@@ -1,4 +1,5 @@
 import { NowledgeMemClient } from "./client.js";
+import { resolveThreadSyncTimeoutMs } from "./thread-sync-timeout.js";
 import { createCliRegistrar } from "./commands/cli.js";
 import {
 	createForgetCommand,
@@ -46,6 +47,7 @@ export default {
 			apiUrl: cfg.apiUrl,
 			apiKey: cfg.apiKey,
 			space: cfg.space,
+			threadSyncTimeoutMs: resolveThreadSyncTimeoutMs(process.env.NMEM_SYNC_TIMEOUT_MS),
 		});
 
 		const { memorySlot, memorySlotSelected } = resolveRegistrationMode({

package/src/plugin-version.js

@@ -0,0 +1,3 @@
+import packageJson from "../package.json" with { type: "json" };
+
+export const NOWLEDGE_MEM_PLUGIN_VERSION = packageJson.version;

package/src/session-delta.js

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+
+export function sessionSyncLaneKey(threadId, apiUrl, apiKey, spaceId) {
+	const destination = createHash("sha256")
+		.update(
+			[String(apiUrl || ""), String(apiKey || ""), String(spaceId || "")].join(
+				"\0",
+			),
+		)
+		.digest("hex");
+	return `${destination}\0${String(threadId || "")}`;
+}
+
+export function stableMessageFingerprint(message) {
+	return JSON.stringify({
+		role: message?.role,
+		content: message?.content,
+		external_id: message?.metadata?.external_id,
+	});
+}
+
+export function prefixFingerprint(
+	messages,
+	end,
+	messageFingerprint = stableMessageFingerprint,
+) {
+	const hash = createHash("sha256");
+	for (const message of messages.slice(0, end)) {
+		const value = messageFingerprint(message);
+		hash.update(String(Buffer.byteLength(value)));
+		hash.update(":");
+		hash.update(value);
+	}
+	return hash.digest("hex");
+}
+
+export function isThreadAppendAck(data) {
+	return (
+		data !== null &&
+		typeof data === "object" &&
+		data.success === true &&
+		Number.isInteger(data.messages_added) &&
+		data.messages_added >= 0 &&
+		Number.isInteger(data.total_messages) &&
+		data.total_messages >= 0
+	);
+}
+
+export function threadCreateAck(data, expectedThreadId) {
+	if (data === null || typeof data !== "object") return null;
+	const thread =
+		data.thread !== null && typeof data.thread === "object" ? data.thread : data;
+	const threadId = String(thread.thread_id ?? "").trim();
+	const totalMessages = thread.message_count ?? thread.total_messages;
+	if (
+		threadId !== String(expectedThreadId || "").trim() ||
+		!Number.isInteger(totalMessages) ||
+		totalMessages < 0
+	) {
+		return null;
+	}
+	return { threadId, totalMessages };
+}
+
+export function isCheckpointedAppendAck(data) {
+	return isThreadAppendAck(data) && data.append_mode === "checkpointed";
+}
+
+export function isCheckpointConflictResponse(data) {
+	return (
+		data !== null &&
+		typeof data === "object" &&
+		data.error_code === "checkpoint_conflict"
+	);
+}
+
+export function selectSnapshotDelta(
+	messages,
+	cursor,
+	externalId,
+	messageFingerprint = stableMessageFingerprint,
+) {
+	let start = cursor?.count ?? 0;
+	let reset = false;
+	if (start > messages.length) {
+		// OpenClaw compaction shrinks the live transcript after we already
+		// stored the pre-compaction history. Reset the local cursor to the
+		// compacted length so later turns append only the post-compaction tail.
+		const end = messages.length;
+		return {
+			start: end,
+			end,
+			messages: [],
+			next: {
+				count: end,
+				remoteCount: cursor?.remoteCount ?? end,
+				...(end > 0 ? { lastExternalId: externalId(messages[end - 1]) } : {}),
+				prefixFingerprint: prefixFingerprint(messages, end, messageFingerprint),
+			},
+			reset: false,
+			compactionShrink: true,
+		};
+	}
+	const acknowledgedPrefix =
+		start >= 0
+			? prefixFingerprint(messages, start, messageFingerprint)
+			: "";
+	const fingerprintTrusted = Boolean(cursor?.prefixFingerprint);
+	const externalIdTrusted = Boolean(cursor?.lastExternalId);
+	if (
+		start < 0 ||
+		(start > 0 &&
+			((externalIdTrusted &&
+				externalId(messages[start - 1]) !== cursor.lastExternalId) ||
+				(fingerprintTrusted &&
+					acknowledgedPrefix !== cursor.prefixFingerprint)))
+	) {
+		start = 0;
+		reset = true;
+	}
+	const end = messages.length;
+	return {
+		start,
+		end,
+		messages: messages.slice(start),
+		next: {
+			count: end,
+			remoteCount: cursor?.remoteCount ?? end,
+			...(end > 0 ? { lastExternalId: externalId(messages[end - 1]) } : {}),
+			prefixFingerprint: prefixFingerprint(messages, end, messageFingerprint),
+		},
+		reset,
+		compactionShrink: false,
+	};
+}
+
+export function contentBoundIdempotencyKey(prefix, threadId, start, end, fingerprint) {
+	return `${prefix}:${threadId}:${start}-${end}:${fingerprint}`;
+}
+
+export function hasUserAndAssistant(messages) {
+	if (!Array.isArray(messages) || messages.length < 2) return false;
+	let hasUser = false;
+	let hasAssistant = false;
+	for (const message of messages) {
+		if (message?.role === "user") hasUser = true;
+		else if (message?.role === "assistant") hasAssistant = true;
+		if (hasUser && hasAssistant) return true;
+	}
+	return false;
+}

package/src/thread-sync-timeout.js

@@ -0,0 +1,14 @@
+const DEFAULT_THREAD_SYNC_TIMEOUT_MS = 120_000;
+const MIN_THREAD_SYNC_TIMEOUT_MS = 1_000;
+const MAX_THREAD_SYNC_TIMEOUT_MS = 30 * 60_000;
+
+export function resolveThreadSyncTimeoutMs(raw) {
+	const parsed = Number(raw);
+	if (!String(raw ?? "").trim() || !Number.isSafeInteger(parsed) || parsed <= 0) {
+		return DEFAULT_THREAD_SYNC_TIMEOUT_MS;
+	}
+	return Math.min(
+		MAX_THREAD_SYNC_TIMEOUT_MS,
+		Math.max(MIN_THREAD_SYNC_TIMEOUT_MS, parsed),
+	);
+}