@nowledge/openclaw-nowledge-mem 0.8.8 → 0.8.12

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## Unreleased
+
+### Fixed
+
+- OpenClaw now preserves an explicit empty `space` setting as a real choice to stay on `Default`, instead of silently falling through to ambient `NMEM_SPACE`.
+- CLI-backed OpenClaw operations now honor that same explicit Default-space choice. Earlier builds could still inherit `NMEM_SPACE` in child `nmem` processes, which split CLI-backed reads and writes away from HTTP-backed thread sync.
+- Fallback HTTP requests now carry the ambient lane through one shared path, so direct API calls stay aligned with CLI-backed memory operations.
+- `nowledge_mem_status` now reports the configured Context Engine slot correctly instead of reading from an unset field.
+- `nowledge_mem_status` now reports `legacy` when no Context Engine slot is configured, instead of surfacing `undefined` in default OpenClaw setups.
+- Legacy `~/.nowledge-mem/openclaw.json` now gets the same strict key validation as dashboard config, so typoed or unsupported keys fail loudly instead of silently altering runtime behavior.
+- Thread capture no longer fails at runtime after the thread-identity refactor. The crypto import used by external IDs and append idempotency keys is restored, so `sessionDigest` capture keeps creating and appending threads normally.
+
+### Changed
+
+- Lower-priority `spaceTemplate` values are now evaluated lazily. A broken template no longer overrides a higher-priority concrete `space` value.
+- Thread-identity tests now reset conversation-root state between cases, so the suite matches real runtime boundaries more closely.
+
+## [0.8.12] - 2026-04-10
+
+### Changed
+
+- OpenClaw's space settings and setup guidance now lead with profile-owned config (`space`, `spaceTemplate`) and keep `NMEM_SPACE` as a fallback for launcher-driven sessions without a richer config surface.
+
+## [0.8.11] - 2026-04-10
+
+### Added
+
+- OpenClaw profiles can now own one ambient space directly through plugin config `space` or `spaceTemplate`, instead of relying only on the process-wide `NMEM_SPACE` environment variable.
+
+### Changed
+
+- `nowledge_mem_status` now reports the effective ambient space and where it came from.
+
+## [0.8.10] - 2026-04-10
+
+### Changed
+
+- Clarified OpenClaw's ambient space model. `NMEM_SPACE` now remains the single session lane across CLI-backed memory calls and API-backed thread/feed fallbacks, while shared spaces, default retrieval, and agent guidance stay in Mem's shared `/spaces` profile.
+
+## [0.8.9] - 2026-04-10
+
+### Fixed
+
+- **`/new` once again starts a fresh Mem thread.** Thread identity now follows OpenClaw's session lifecycle instead of collapsing everything under the channel-level `sessionKey`. Explicit `/new`, `/reset`, idle rollovers, and daily rollovers create a new Mem thread as users expect.
+- **Compaction still stays inside the same Mem thread.** When OpenClaw rotates the underlying transcript during compaction, the plugin now carries the existing conversation root forward so compaction does not fork a second thread for the same chat.
+
+### Changed
+
+- **Capture now uses lifecycle-aware conversation roots.** `session_end` and `session_start` hooks teach the plugin when a new chat begins and when a transcript rotation is only internal maintenance. Context Engine capture and hook-based capture still converge on the same thread, but `/new` is no longer merged into the prior conversation.
+
 ## [0.8.8] - 2026-04-09
 
 ### Fixed

package/CLAUDE.md

@@ -11,6 +11,7 @@ Continuation guide for `community/nowledge-mem-openclaw-plugin`.
 - Architecture: **CLI-first via OpenClaw runtime** - all CLI execution goes through `api.runtime.system.runCommandWithTimeout`, not direct `child_process`
 - Context engine: registered via `api.registerContextEngine("nowledge-mem", factory)`. Activated when user sets `plugins.slots.contextEngine: "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.
+- Ambient space lane: prefer plugin config `space` or `spaceTemplate`. Use `NMEM_SPACE` only when OpenClaw is launched in one stable lane and there is no better profile-owned config surface. Legacy `NMEM_SPACE_ID` still works for older setups.
 
 ## Design Philosophy
 
@@ -165,6 +166,7 @@ When `contextEngine` points elsewhere (or is absent), hooks handle everything. N
 
 Plugin settings: OpenClaw dashboard (pluginConfig). Legacy `~/.nowledge-mem/openclaw.json` still honored.
 Credentials (apiUrl/apiKey): also reads `~/.nowledge-mem/config.json` (shared with all Nowledge Mem tools).
+Ambient space: choose one real lane through plugin config `space` or `spaceTemplate` first. Use `NMEM_SPACE` only as the fallback for launcher-driven sessions that already belong to one real lane. Do not introduce a second plugin-local vault concept. Legacy `NMEM_SPACE_ID` remains compatibility-only.
 
 | Key | Type | Default | Env Var | Description |
 |-----|------|---------|---------|-------------|
@@ -181,6 +183,8 @@ Credentials (apiUrl/apiKey): also reads `~/.nowledge-mem/config.json` (shared wi
 | `corpusMinScore` | integer 0-100 | `0` | `NMEM_CORPUS_MIN_SCORE` | Min score for supplement results (0 = all) |
 | `apiUrl` | string | `""` | `NMEM_API_URL` | Remote server URL. Empty = local (127.0.0.1:14242) |
 | `apiKey` | string | `""` | `NMEM_API_KEY` | API key. Never logged. |
+| `space` | string | `""` | `NMEM_SPACE` (fallback only) | Fixed ambient space name for this OpenClaw profile or agent lane |
+| `spaceTemplate` | string | `""` | — | Template with `${ENV_VAR}` placeholders, used only when `space` is empty |
 
 **Priority** (plugin-specific keys): `openclaw.json` (legacy) > pluginConfig > env var > default.
 **Priority** (apiUrl/apiKey): `openclaw.json` (legacy) > pluginConfig > `config.json` (shared) > env var > default.

package/README.md

@@ -97,6 +97,31 @@ Legacy `~/.nowledge-mem/openclaw.json` is still honored first for backward compa
 
 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.
 
+### Spaces
+
+Spaces are optional. OpenClaw should choose one ambient lane only when the profile or process already belongs to one real project or agent lane.
+
+The OpenClaw plugin settings can own that lane directly:
+
+```json
+{
+  "space": "Research Agent",
+  "spaceTemplate": "agent-${OPENCLAW_AGENT_NAME}"
+}
+```
+
+Use `space` when one OpenClaw profile belongs to one stable lane. Use `spaceTemplate` only when your launcher or host environment already sets a trustworthy variable that identifies the lane. If your OpenClaw runtime does not expose per-agent identity to plugins, do not fake it. Use one profile/process per lane or stay on `Default`.
+
+If you are running OpenClaw from a launcher or script with no richer config surface, you can still set one session-wide fallback lane with:
+
+```bash
+NMEM_SPACE="Research Agent"
+```
+
+Nowledge Mem's CLI-backed Working Memory, memory search/save, and the plugin's API-backed thread/feed fallbacks will then stay in that lane together. There is no second OpenClaw-only vault setting; the shared Mem boundary is still one hidden space key, but humans and agents should normally work with the space name instead.
+
+Shared spaces, default retrieval, and agent guidance still live in Mem's own space profile. OpenClaw chooses the lane and preserves it across transports; it should not duplicate the profile semantics.
+
 ### Configure via WebUI of OpenClaw
 
 <img width="1192" height="2007" alt="openclaw-config" src="https://github.com/user-attachments/assets/a4abd855-db56-4a1f-b0ac-0114909d0c20" />
@@ -365,7 +390,7 @@ The behavioral guidance adjusts when `sessionContext` is enabled. Instead of "se
 
 **What happens to conversations I don't explicitly save?**
 
-With `sessionDigest` enabled (the default), every conversation is saved as a searchable thread. One OpenClaw chat becomes one Mem thread: capture uses the stable OpenClaw `sessionKey`, not transient runtime ids, so Context Engine capture and hook-based capture append to the same conversation. Internal helper sessions like `temp:*` and subagent runs are excluded, so your recent threads stay focused on real chats. On top of thread capture, a lightweight LLM triage checks if the conversation contained decisions, insights, or preferences worth keeping as structured memories. If yes, they're extracted with proper types, labels, and temporal context. If the conversation was routine ("fix this typo"), nothing extra is saved.
+With `sessionDigest` enabled (the default), every conversation is saved as a searchable thread. The boundary follows OpenClaw's own session lifecycle: one active chat becomes one Mem thread, `/new` or `/reset` starts a fresh thread, and internal compaction keeps appending to the same thread instead of forking a duplicate. Context Engine capture and hook-based capture still converge on the same conversation. Internal helper sessions like `temp:*` and subagent runs are excluded, so your recent threads stay focused on real chats. On top of thread capture, a lightweight LLM triage checks if the conversation contained decisions, insights, or preferences worth keeping as structured memories. If yes, they're extracted with proper types, labels, and temporal context. If the conversation was routine ("fix this typo"), nothing extra is saved.
 
 **Can memories be wrong or outdated?**
 
@@ -530,7 +555,9 @@ Remember: OpenClaw applies plugin setting changes after restart. If you turned `
 
 What healthy OpenClaw thread sync looks like:
 
-- one visible chat becomes one Mem thread
+- one active OpenClaw chat becomes one Mem thread
+- running `/new` or `/reset` starts a fresh Mem thread
+- compaction does not fork a second thread for the same chat
 - helper sessions like `temp:slug-generator` do not appear
 - the synthetic `/new` / `/reset` startup prompt is not stored as the first user message
 

package/SKILL.md

@@ -63,6 +63,7 @@ Explain the difference plainly:
 
 - Local mode: OpenClaw talks to the local Nowledge Mem app/server through `nmem`
 - Remote mode: OpenClaw talks to a remote Nowledge Mem server through `nmem --api-url ...`; add `apiKey` when that server has auth enabled
+- If the user wants one agent-specific lane, use plugin config `space` first, plugin config `spaceTemplate` only when the launcher already exposes a trustworthy lane signal, and `NMEM_SPACE="<space name>"` only as the fallback for CLI-style launches instead of inventing a second OpenClaw-only memory namespace
 
 ### Step 1 — Verify `nmem`
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
 	"id": "openclaw-nowledge-mem",
 	"name": "Nowledge Mem",
 	"description": "Cross-tool knowledge graph memory for OpenClaw with Working Memory, graph search, and session distillation.",
-	"version": "0.8.8",
+	"version": "0.8.12",
 	"kind": "memory",
 	"skills": [
 		"skills/memory-guide"
@@ -60,6 +60,14 @@
 			"label": "API key (remote mode)",
 			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument. Injected as NMEM_API_KEY env var only.",
 			"sensitive": true
+		},
+		"space": {
+			"label": "Ambient space",
+			"help": "Optional fixed space name for this OpenClaw profile or agent lane. Leave empty to stay on Default."
+		},
+		"spaceTemplate": {
+			"label": "Ambient space template",
+			"help": "Optional template with ${ENV_VAR} placeholders, used only when Ambient space is empty and your launcher already exports a trustworthy lane signal. Example: agent-${OPENCLAW_AGENT_NAME}."
 		}
 	},
 	"configSchema": {
@@ -144,6 +152,16 @@
 				"type": "string",
 				"default": "",
 				"description": "API key for remote access. Stored in plugin config, injected as NMEM_API_KEY env var. Never logged."
+			},
+			"space": {
+				"type": "string",
+				"default": "",
+				"description": "Optional fixed space name for this OpenClaw profile or agent lane."
+			},
+			"spaceTemplate": {
+				"type": "string",
+				"default": "",
+				"description": "Optional template with ${ENV_VAR} placeholders. Used only when space is empty."
 			}
 		}
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
 	"displayName": "Nowledge Mem for OpenClaw",
-	"version": "0.8.8",
+	"version": "0.8.12",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {
@@ -42,6 +42,7 @@
 	},
 	"main": "src/index.js",
 	"scripts": {
+		"test": "node --test tests/*.test.mjs",
 		"validate": "node scripts/validate-plugin.mjs",
 		"lint": "biome check .",
 		"format": "biome format --write ."

package/src/client.js

@@ -70,7 +70,7 @@ export class NowledgeMemClient {
 	/**
 	 * @param {object} logger
 	 * @param {object} runtimeSystem
-	 * @param {{ apiUrl?: string; apiKey?: string }} [credentials]
+	 * @param {{ apiUrl?: string; apiKey?: string; space?: string; spaceId?: string }} [credentials]
 	 */
 	constructor(logger, runtimeSystem, credentials = {}) {
 		this.logger = logger;
@@ -82,6 +82,18 @@ export class NowledgeMemClient {
 			(credentials.apiUrl || "").trim() || "http://127.0.0.1:14242"
 		).replace(/\/+$/, "");
 		this._apiKey = (credentials.apiKey || "").trim();
+		const hasSpace = Object.prototype.hasOwnProperty.call(credentials, "space");
+		const hasSpaceId = Object.prototype.hasOwnProperty.call(
+			credentials,
+			"spaceId",
+		);
+		this._hasExplicitSpace = hasSpace || hasSpaceId;
+		const resolvedSpace = hasSpace
+			? credentials.space
+			: hasSpaceId
+				? credentials.spaceId
+				: process.env.NMEM_SPACE ?? process.env.NMEM_SPACE_ID ?? "";
+		this._spaceRef = String(resolvedSpace ?? "").trim();
 	}
 
 	// ── API helpers (fallback path and direct operations) ─────────────────────
@@ -99,15 +111,39 @@ export class NowledgeMemClient {
 		return headers;
 	}
 
+	_withSpaceQuery(path) {
+		if (!this._spaceRef) return path;
+		const [pathname, rawQuery = ""] = String(path).split("?", 2);
+		const query = new URLSearchParams(rawQuery);
+		if (!query.has("space_id")) {
+			query.set("space_id", this._spaceRef);
+		}
+		const rendered = query.toString();
+		return rendered ? `${pathname}?${rendered}` : pathname;
+	}
+
+	_withSpaceBody(body) {
+		if (!this._spaceRef || body == null || Array.isArray(body)) {
+			return body;
+		}
+		if (Object.prototype.hasOwnProperty.call(body, "space_id")) {
+			return body;
+		}
+		return { ...body, space_id: this._spaceRef };
+	}
+
 	async apiJson(method, path, body, timeout = 30_000) {
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(), timeout);
-		const url = `${this.getApiBaseUrl()}${path}`;
+		const scopedPath = this._withSpaceQuery(path);
+		const scopedBody = this._withSpaceBody(body);
+		const url = `${this.getApiBaseUrl()}${scopedPath}`;
 		try {
 			const response = await fetch(url, {
 				method,
 				headers: this.getApiHeaders(),
-				body: body === undefined ? undefined : JSON.stringify(body),
+				body:
+					scopedBody === undefined ? undefined : JSON.stringify(scopedBody),
 				signal: controller.signal,
 			});
 
@@ -184,6 +220,8 @@ export class NowledgeMemClient {
 		return buildNmemSpawnEnv({
 			apiUrl: this._apiUrl,
 			apiKey: this._apiKey,
+			spaceId: this._spaceRef,
+			hasExplicitSpace: this._hasExplicitSpace,
 		});
 	}
 
@@ -557,12 +595,16 @@ export class NowledgeMemClient {
 			throw new Error("createThread requires at least one message");
 		}
 
-		const data = await this.apiJson("POST", "/threads", {
-			...(threadId ? { 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",
@@ -692,7 +734,11 @@ export class NowledgeMemClient {
 			});
 			if (updated === null) throw new Error(`Section not found: ${heading}`);
 
-			return this.apiJson("PUT", "/agent/working-memory", { content: updated });
+			return this.apiJson(
+				"PUT",
+				"/agent/working-memory",
+				{ content: updated },
+			);
 		}
 	}
 

package/src/config.js

@@ -28,6 +28,8 @@ const ALLOWED_KEYS = new Set([
 	"corpusMinScore",
 	"apiUrl",
 	"apiKey",
+	"space",
+	"spaceTemplate",
 	// Legacy aliases — accepted but not advertised
 	"autoRecall",
 	"autoCapture",
@@ -128,6 +130,30 @@ function envInt(name) {
 	return Number.isFinite(n) ? n : undefined;
 }
 
+function pickStr(obj, key) {
+	if (typeof obj[key] !== "string") return undefined;
+	const trimmed = obj[key].trim();
+	return trimmed || undefined;
+}
+
+function pickPresentString(obj, key) {
+	if (!Object.prototype.hasOwnProperty.call(obj, key)) return undefined;
+	if (typeof obj[key] !== "string") return undefined;
+	return obj[key].trim();
+}
+
+function resolveEnvTemplate(value) {
+	return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
+		const envValue = process.env[envVar];
+		if (typeof envValue !== "string" || !envValue.trim()) {
+			throw new Error(
+				`nowledge-mem: environment variable ${envVar} is required by spaceTemplate`,
+			);
+		}
+		return envValue.trim();
+	});
+}
+
 // --- helpers to read a boolean/number from resolved sources --------------
 
 function pickBool(obj, key) {
@@ -162,7 +188,8 @@ function resolveAliases(obj) {
  */
 function firstDefined(...options) {
 	for (const opt of options) {
-		if (opt.value !== undefined) return opt;
+		const value = typeof opt.resolve === "function" ? opt.resolve() : opt.value;
+		if (value !== undefined) return { ...opt, value };
 	}
 	return options[options.length - 1];
 }
@@ -185,7 +212,8 @@ function firstDefined(...options) {
  * but is no longer the recommended path.
  *
  * Canonical keys: sessionContext, sessionDigest, digestMinInterval,
- *                 maxContextResults, recallMinScore, maxThreadMessageChars, apiUrl, apiKey
+ *                 maxContextResults, recallMinScore, maxThreadMessageChars,
+ *                 apiUrl, apiKey, space, spaceTemplate
  *
  * Legacy aliases (accepted from all sources; never shown in docs):
  *   autoRecall → sessionContext
@@ -205,6 +233,7 @@ function firstDefined(...options) {
  *   NMEM_CORPUS_MIN_SCORE      — integer (0-100)
  *   NMEM_API_URL               — remote server URL
  *   NMEM_API_KEY               — API key (never logged)
+ *   NMEM_SPACE                 — ambient space name (legacy: NMEM_SPACE_ID)
  */
 export function parseConfig(raw, logger) {
 	const pluginCfg = raw && typeof raw === "object" ? raw : {};
@@ -215,16 +244,19 @@ export function parseConfig(raw, logger) {
 	const resolvedPlugin = resolveAliases(pluginCfg);
 	const resolvedFile = resolveAliases(fileCfg);
 
-	// Strict: reject unknown keys in pluginConfig (typo catcher).
-	const unknownKeys = Object.keys(resolvedPlugin).filter(
-		(k) => !ALLOWED_KEYS.has(k),
-	);
-	if (unknownKeys.length > 0) {
-		throw new Error(
-			`nowledge-mem: unknown config key${unknownKeys.length > 1 ? "s" : ""}: ${unknownKeys.join(", ")}. ` +
-				`Allowed keys: ${[...ALLOWED_KEYS].filter((k) => !Object.keys(ALIAS_KEYS).includes(k)).join(", ")}`,
-		);
-	}
+	const validateKnownKeys = (obj, sourceLabel) => {
+		const unknownKeys = Object.keys(obj).filter((k) => !ALLOWED_KEYS.has(k));
+		if (unknownKeys.length > 0) {
+			throw new Error(
+				`nowledge-mem: unknown config key${unknownKeys.length > 1 ? "s" : ""} in ${sourceLabel}: ${unknownKeys.join(", ")}. ` +
+					`Allowed keys: ${[...ALLOWED_KEYS].filter((k) => !Object.keys(ALIAS_KEYS).includes(k)).join(", ")}`,
+			);
+		}
+	};
+
+	// Strict: reject unknown keys in both legacy file config and dashboard config.
+	validateKnownKeys(resolvedFile, "~/.nowledge-mem/openclaw.json");
+	validateKnownKeys(resolvedPlugin, "plugin config");
 
 	const _sources = {};
 
@@ -351,6 +383,31 @@ export function parseConfig(raw, logger) {
 	const apiKey = ak.value;
 	_sources.apiKey = ak.source;
 
+	// --- space: file (legacy) > pluginConfig > template > env > default ---
+	const fs = pickPresentString(resolvedFile, "space");
+	const ps = pickPresentString(resolvedPlugin, "space");
+	const fst = pickStr(resolvedFile, "spaceTemplate");
+	const pst = pickStr(resolvedPlugin, "spaceTemplate");
+	const spaceChoice = firstDefined(
+		{ value: fs, source: "file" },
+		{ value: ps, source: "pluginConfig" },
+		{
+			resolve: () => (fst ? resolveEnvTemplate(fst) : undefined),
+			source: "file:template",
+		},
+		{
+			resolve: () => (pst ? resolveEnvTemplate(pst) : undefined),
+			source: "pluginConfig:template",
+		},
+		{
+			value: envStr("NMEM_SPACE") ?? envStr("NMEM_SPACE_ID"),
+			source: "env",
+		},
+		{ value: "", source: "default" },
+	);
+	const space = spaceChoice.value || "";
+	_sources.space = spaceChoice.source;
+
 	// --- corpusSupplement: file > pluginConfig > env > default ---
 	const cs = firstDefined(
 		{ value: pickBool(resolvedFile, "corpusSupplement"), source: "file" },
@@ -445,6 +502,7 @@ export function parseConfig(raw, logger) {
 		corpusMinScore,
 		apiUrl,
 		apiKey,
+		space,
 		_sources,
 	};
 }

package/src/hooks/capture.js

@@ -1,6 +1,15 @@
-import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { isCronSessionKey, isSubagentSessionKey } from "openclaw/plugin-sdk/routing";
+import {
+	buildStableThreadId,
+} from "./thread-identity.js";
+export {
+	_resetConversationRoots,
+	buildStableThreadId,
+	registerSessionEndConversation,
+	registerSessionStartConversation,
+} from "./thread-identity.js";
 
 export const DEFAULT_MAX_MESSAGE_CHARS = 800;
 export const MAX_DISTILL_MESSAGE_CHARS = 2000;
@@ -20,7 +29,6 @@ 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);
 	// Opportunistic eviction: sweep stale entries when map grows large
@@ -255,17 +263,6 @@ function sanitizeIdPart(input, max = 48) {
 	return normalized.slice(0, max);
 }
 
-export function buildStableThreadId(event, ctx) {
-	const base =
-		String(ctx?.sessionKey || "").trim() ||
-		String(ctx?.sessionId || "").trim() ||
-		String(event?.sessionFile || "").trim() ||
-		"session";
-	const slug = sanitizeIdPart(base);
-	const digest = createHash("sha1").update(base).digest("hex").slice(0, 10);
-	return `openclaw-${slug}-${digest}`;
-}
-
 function buildExternalId({ normalized, index, threadId, sessionKey }) {
 	if (normalized.externalHint) {
 		return `oc:${sanitizeIdPart(normalized.externalHint, 96)}`;

package/src/hooks/thread-identity.js

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+
+const _conversationRootsBySessionId = new Map();
+const _activeConversationRootsBySessionKey = new Map();
+const _MAX_CONVERSATION_ROOT_ENTRIES = 500;
+
+function sanitizeIdPart(input, max = 48) {
+	const normalized = String(input || "")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	if (!normalized) return "session";
+	return normalized.slice(0, max);
+}
+
+function _setConversationRoot({ sessionId, sessionKey, rootId }) {
+	const normalizedRoot = String(rootId || "").trim();
+	if (!normalizedRoot) return;
+	const normalizedSessionId = String(sessionId || "").trim();
+	const normalizedSessionKey = String(sessionKey || "").trim();
+
+	if (normalizedSessionId) {
+		_conversationRootsBySessionId.set(normalizedSessionId, normalizedRoot);
+		if (_conversationRootsBySessionId.size > _MAX_CONVERSATION_ROOT_ENTRIES) {
+			const excess =
+				_conversationRootsBySessionId.size - _MAX_CONVERSATION_ROOT_ENTRIES;
+			let removed = 0;
+			for (const key of _conversationRootsBySessionId.keys()) {
+				_conversationRootsBySessionId.delete(key);
+				removed += 1;
+				if (removed >= excess) break;
+			}
+		}
+	}
+
+	if (normalizedSessionKey) {
+		_activeConversationRootsBySessionKey.set(
+			normalizedSessionKey,
+			normalizedRoot,
+		);
+		if (
+			_activeConversationRootsBySessionKey.size > _MAX_CONVERSATION_ROOT_ENTRIES
+		) {
+			const excess =
+				_activeConversationRootsBySessionKey.size - _MAX_CONVERSATION_ROOT_ENTRIES;
+			let removed = 0;
+			for (const key of _activeConversationRootsBySessionKey.keys()) {
+				_activeConversationRootsBySessionKey.delete(key);
+				removed += 1;
+				if (removed >= excess) break;
+			}
+		}
+	}
+}
+
+export function resolveConversationRoot(event, ctx) {
+	const sessionId = String(ctx?.sessionId || event?.sessionId || "").trim();
+	if (sessionId) {
+		const mappedRoot = _conversationRootsBySessionId.get(sessionId);
+		if (mappedRoot) return mappedRoot;
+	}
+
+	const sessionKey = String(ctx?.sessionKey || event?.sessionKey || "").trim();
+	if (sessionKey) {
+		const activeRoot = _activeConversationRootsBySessionKey.get(sessionKey);
+		if (activeRoot) return activeRoot;
+	}
+
+	return (
+		sessionId ||
+		sessionKey ||
+		String(event?.sessionFile || "").trim() ||
+		"session"
+	);
+}
+
+export function registerSessionStartConversation(event, ctx) {
+	const sessionId = String(event?.sessionId || ctx?.sessionId || "").trim();
+	const sessionKey = String(event?.sessionKey || ctx?.sessionKey || "").trim();
+	if (!sessionId && !sessionKey) return;
+
+	const resumedFrom = String(event?.resumedFrom || "").trim();
+	const inheritedRoot =
+		_conversationRootsBySessionId.get(sessionId) ||
+		(resumedFrom && _conversationRootsBySessionId.get(resumedFrom)) ||
+		sessionId;
+
+	_setConversationRoot({
+		sessionId,
+		sessionKey,
+		rootId: inheritedRoot || sessionId || sessionKey,
+	});
+}
+
+export function registerSessionEndConversation(event, ctx) {
+	const sessionId = String(event?.sessionId || ctx?.sessionId || "").trim();
+	const sessionKey = String(event?.sessionKey || ctx?.sessionKey || "").trim();
+	if (!sessionId && !sessionKey) return;
+
+	const currentRoot = resolveConversationRoot(event, ctx);
+	_setConversationRoot({
+		sessionId,
+		sessionKey,
+		rootId: currentRoot,
+	});
+
+	const nextSessionId = String(event?.nextSessionId || "").trim();
+	if (!nextSessionId) return;
+
+	const reason = String(event?.reason || "").trim().toLowerCase();
+	const nextRoot = reason === "compaction" ? currentRoot : nextSessionId;
+	_setConversationRoot({
+		sessionId: nextSessionId,
+		sessionKey,
+		rootId: nextRoot,
+	});
+}
+
+export function buildStableThreadId(event, ctx) {
+	const base = resolveConversationRoot(event, ctx);
+	const slug = sanitizeIdPart(base);
+	const digest = createHash("sha1").update(base).digest("hex").slice(0, 10);
+	return `openclaw-${slug}-${digest}`;
+}
+
+export function _resetConversationRoots() {
+	_conversationRootsBySessionId.clear();
+	_activeConversationRootsBySessionKey.clear();
+}

package/src/index.js

@@ -12,6 +12,8 @@ import { buildBehavioralHook } from "./hooks/behavioral.js";
 import {
 	buildAgentEndCaptureHandler,
 	buildBeforeResetCaptureHandler,
+	registerSessionEndConversation,
+	registerSessionStartConversation,
 } from "./hooks/capture.js";
 import { buildRecallHandler } from "./hooks/recall.js";
 import { createConnectionsTool } from "./tools/connections.js";
@@ -38,6 +40,7 @@ export default {
 		const client = new NowledgeMemClient(logger, api.runtime.system, {
 			apiUrl: cfg.apiUrl,
 			apiKey: cfg.apiKey,
+			space: cfg.space,
 		});
 
 		// OpenClaw memory-slot compatibility (required for system prompt activation)
@@ -137,6 +140,8 @@ export default {
 				cfg,
 				logger,
 			);
+			api.on("session_start", registerSessionStartConversation);
+			api.on("session_end", registerSessionEndConversation);
 			api.on("agent_end", buildAgentEndCaptureHandler(client, cfg, logger));
 			api.on("after_compaction", (event, ctx) =>
 				threadCaptureHandler({ ...event, reason: "compaction" }, ctx),

package/src/spawn-env.js

@@ -3,17 +3,31 @@ const LOCAL_API_URL = "http://127.0.0.1:14242";
 /**
  * Build the child env for nmem CLI execution.
  * apiKey stays in env only and is never passed as a CLI flag.
- * Clear inherited NMEM_* values first so the resolved plugin config wins.
+ * Clear inherited API endpoint/auth values first so the resolved plugin config wins.
+ * Keep the ambient space lane unless an explicit override is provided. Prefer
+ * NMEM_SPACE for the human-facing contract, while preserving legacy
+ * NMEM_SPACE_ID for older setups. An explicit empty override means "stay on
+ * Default", so inherited ambient space vars must be cleared too.
  */
-export function buildNmemSpawnEnv({ apiUrl, apiKey } = {}) {
+export function buildNmemSpawnEnv(
+	{ apiUrl, apiKey, spaceId, hasExplicitSpace = false } = {},
+) {
 	const env = { ...process.env };
 	delete env.NMEM_API_URL;
 	delete env.NMEM_API_KEY;
+	if (hasExplicitSpace) {
+		delete env.NMEM_SPACE;
+		delete env.NMEM_SPACE_ID;
+	}
 	if (apiUrl && apiUrl !== LOCAL_API_URL) {
 		env.NMEM_API_URL = apiUrl;
 	}
 	if (apiKey) {
 		env.NMEM_API_KEY = apiKey;
 	}
+	if (hasExplicitSpace && typeof spaceId === "string" && spaceId.length > 0) {
+		env.NMEM_SPACE = spaceId;
+		env.NMEM_SPACE_ID = spaceId;
+	}
 	return env;
 }

package/src/tools/status.js

@@ -63,18 +63,18 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 			const memorySlot = runtimeInfo.memorySlot;
 			const contextEngineSlot = runtimeInfo.contextEngineSlot;
 			const contextEngineRegistered = runtimeInfo.contextEngineRegistered === true;
-			const contextEngineRegistrationError =
-				typeof runtimeInfo.contextEngineRegistrationError === "string" &&
-				runtimeInfo.contextEngineRegistrationError.trim()
-					? runtimeInfo.contextEngineRegistrationError.trim()
-					: null;
-			details.memorySlot = memorySlot ?? "(unknown)";
-			const ceSlot =
-				contextEngineSlot && String(contextEngineSlot).trim()
-					? String(contextEngineSlot).trim()
-					: "legacy";
-			details.contextEngineSlot = ceSlot;
-			details.contextEngineRegistered = contextEngineRegistered;
+				const contextEngineRegistrationError =
+					typeof runtimeInfo.contextEngineRegistrationError === "string" &&
+					runtimeInfo.contextEngineRegistrationError.trim()
+						? runtimeInfo.contextEngineRegistrationError.trim()
+						: null;
+				details.memorySlot = memorySlot ?? "(unknown)";
+				const ceSlot =
+					typeof contextEngineSlot === "string" && contextEngineSlot.trim()
+						? contextEngineSlot.trim()
+						: "legacy";
+				details.contextEngineSlot = ceSlot;
+				details.contextEngineRegistered = contextEngineRegistered;
 			if (memorySlot && memorySlot !== "openclaw-nowledge-mem") {
 				const corpusOn = cfg.corpusSupplement === true;
 				if (corpusOn) {
@@ -134,6 +134,10 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 			}
 			if (!cfg.sessionDigest) {
 				lines.push("Thread capture: disabled (sessionDigest=false)");
+			} else {
+				lines.push(
+					"  Thread identity follows OpenClaw session lifecycle: /new or /reset starts a fresh thread, while compaction stays in the same thread.",
+				);
 			}
 
 			// 1. Mode + connection target
@@ -142,11 +146,16 @@ export function createStatusTool(client, _logger, cfg, runtimeInfo = {}) {
 			details.mode = mode;
 			details.apiUrl = cfg.apiUrl || "http://127.0.0.1:14242";
 			details.apiKeySet = Boolean(cfg.apiKey);
+			details.space = cfg.space || null;
+			details.spaceSource = sources.space || "default";
 
 			lines.push(
 				`Mode: ${remote ? `Remote (${cfg.apiUrl})` : "Local (127.0.0.1:14242)"}`,
 			);
 			lines.push(`API key: ${cfg.apiKey ? "set" : "not set"}`);
+			lines.push(
+				`Ambient space: ${cfg.space ? `${cfg.space} (${details.spaceSource})` : "Default"}`,
+			);
 			lines.push("Memory tools: nmem CLI");
 			lines.push("Thread sync: Mem HTTP API");