@nowledge/openclaw-nowledge-mem 0.3.0 → 0.6.5

package/src/client.js

@@ -359,6 +359,13 @@ export class NowledgeMemClient {
 			eventStart: m.event_start ?? null,
 			eventEnd: m.event_end ?? null,
 			temporalContext: m.temporal_context ?? null,
+			// Thread provenance: links memory to the conversation it was distilled from.
+			// CLI returns `source_thread`, API metadata returns `source_thread_id`.
+			sourceThreadId:
+				m.source_thread ??
+				m.source_thread_id ??
+				m.metadata?.source_thread_id ??
+				null,
 		};
 	}
 
@@ -722,6 +729,181 @@ export class NowledgeMemClient {
 		);
 	}
 
+	// ── Thread search ────────────────────────────────────────────────────────
+
+	/**
+	 * Search conversation threads by keyword. Uses BM25 full-text search
+	 * across all stored messages.
+	 *
+	 * @param {string} query  Search keywords
+	 * @param {number} [limit=3]  Max threads to return
+	 * @returns {Promise<{ threads: Array, totalFound: number }>}
+	 */
+	async searchThreads(query, limit = 3) {
+		const normalizedLimit = Math.min(
+			20,
+			Math.max(1, Math.trunc(Number(limit) || 3)),
+		);
+		const qs = new URLSearchParams({
+			query: String(query || ""),
+			mode: "full",
+			limit: String(normalizedLimit),
+		});
+		try {
+			const data = await this.apiJson(
+				"GET",
+				`/threads/search?${qs.toString()}`,
+			);
+			return {
+				threads: data.threads ?? [],
+				totalFound: Number(data.total_found ?? 0),
+			};
+		} catch (err) {
+			// Thread search is best-effort — don't fail the whole operation
+			this.logger.warn?.(
+				`searchThreads failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+			return { threads: [], totalFound: 0 };
+		}
+	}
+
+	/**
+	 * Full-featured thread search — used by nowledge_mem_thread_search tool.
+	 * Unlike searchThreads() (best-effort, swallows errors), this throws on failure
+	 * and supports additional parameters.
+	 *
+	 * Uses CLI: `nmem --json t search "<query>" --limit N`
+	 * Falls back to API: GET /threads/search
+	 *
+	 * @param {string} query  Search keywords
+	 * @param {{ limit?: number; source?: string }} [options]
+	 * @returns {Promise<{ threads: Array, totalFound: number }>}
+	 */
+	async searchThreadsFull(query, { limit = 10, source } = {}) {
+		const normalizedLimit = Math.min(
+			50,
+			Math.max(1, Math.trunc(Number(limit) || 10)),
+		);
+		const args = [
+			"--json",
+			"t",
+			"search",
+			String(query || ""),
+			"--limit",
+			String(normalizedLimit),
+		];
+		if (source) args.push("--source", String(source));
+
+		try {
+			const data = this.execJson(args);
+			return {
+				threads: data.threads ?? [],
+				totalFound: Number(data.total_found ?? data.total ?? 0),
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const needsFallback =
+				message.includes("unrecognized arguments") ||
+				message.includes("invalid choice") ||
+				message.includes("argument command: invalid choice");
+			if (!needsFallback) throw err;
+
+			this.logger.warn("searchThreadsFull: CLI too old, falling back to API");
+			const qs = new URLSearchParams({
+				query: String(query || ""),
+				mode: "full",
+				limit: String(normalizedLimit),
+			});
+			if (source) qs.set("source", String(source));
+			const data = await this.apiJson(
+				"GET",
+				`/threads/search?${qs.toString()}`,
+			);
+			return {
+				threads: data.threads ?? [],
+				totalFound: Number(data.total_found ?? 0),
+			};
+		}
+	}
+
+	/**
+	 * Fetch full messages from a specific thread.
+	 * Supports pagination for progressive retrieval of long conversations.
+	 *
+	 * Uses CLI: `nmem --json t show <id> --limit N --offset O`
+	 * Falls back to API: GET /threads/{id}
+	 *
+	 * @param {string} threadId  Thread ID
+	 * @param {{ offset?: number; limit?: number }} [options]
+	 */
+	async fetchThread(threadId, { offset = 0, limit = 50 } = {}) {
+		const id = String(threadId || "").trim();
+		if (!id) throw new Error("fetchThread requires threadId");
+
+		const normalizedLimit = Math.min(
+			200,
+			Math.max(1, Math.trunc(Number(limit) || 50)),
+		);
+		const normalizedOffset = Math.max(0, Math.trunc(Number(offset) || 0));
+
+		const args = [
+			"--json",
+			"t",
+			"show",
+			id,
+			"--limit",
+			String(normalizedLimit),
+		];
+		if (normalizedOffset > 0) {
+			args.push("--offset", String(normalizedOffset));
+		}
+
+		try {
+			const data = this.execJson(args);
+			return {
+				threadId: data.thread_id ?? data.id ?? id,
+				title: data.title ?? "(untitled)",
+				source: data.source ?? "unknown",
+				messageCount: Number(data.message_count ?? data.total_messages ?? 0),
+				messages: (data.messages ?? []).map((msg) => ({
+					role: String(msg.role ?? "unknown"),
+					content: String(msg.content ?? ""),
+					timestamp: msg.timestamp ?? msg.created_at ?? null,
+				})),
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const needsFallback =
+				message.includes("unrecognized arguments") ||
+				message.includes("invalid choice") ||
+				message.includes("argument command: invalid choice");
+			if (!needsFallback) throw err;
+
+			this.logger.warn("fetchThread: CLI too old, falling back to API");
+			const qs = new URLSearchParams({
+				limit: String(normalizedLimit),
+			});
+			if (normalizedOffset > 0) {
+				qs.set("offset", String(normalizedOffset));
+			}
+			const data = await this.apiJson(
+				"GET",
+				`/threads/${encodeURIComponent(id)}?${qs.toString()}`,
+			);
+			return {
+				threadId: data.thread_id ?? data.id ?? id,
+				title: data.title ?? "(untitled)",
+				source: data.source ?? "unknown",
+				messageCount: Number(data.message_count ?? data.total_messages ?? 0),
+				messages: (data.messages ?? []).map((msg) => ({
+					role: String(msg.role ?? "unknown"),
+					content: String(msg.content ?? ""),
+					timestamp: msg.timestamp ?? msg.created_at ?? null,
+				})),
+			};
+		}
+	}
+
 	async checkHealth() {
 		try {
 			this.exec(["status"]);

package/src/config.js

@@ -9,21 +9,42 @@ export function isDefaultApiUrl(url) {
 	return !trimmed || trimmed === API_DEFAULT_URL;
 }
 
+// Canonical config keys (new names).
 const ALLOWED_KEYS = new Set([
-	"autoRecall",
-	"autoCapture",
-	"maxRecallResults",
+	"sessionContext",
+	"sessionDigest",
+	"digestMinInterval",
+	"maxContextResults",
 	"apiUrl",
 	"apiKey",
 ]);
 
+// Backward-compatible aliases (old names → new names).
+// Accepted silently so existing users' configs keep working.
+const ALIAS_KEYS = {
+	autoRecall: "sessionContext",
+	autoCapture: "sessionDigest",
+	captureMinInterval: "digestMinInterval",
+	maxRecallResults: "maxContextResults",
+};
+
 export function parseConfig(raw) {
 	const obj = raw && typeof raw === "object" ? raw : {};
 
+	// Resolve aliases: copy old-name values to new-name slots
+	// (new name takes precedence if both are present).
+	const resolved = { ...obj };
+	for (const [oldKey, newKey] of Object.entries(ALIAS_KEYS)) {
+		if (oldKey in resolved) {
+			if (!(newKey in resolved)) {
+				resolved[newKey] = resolved[oldKey];
+			}
+			delete resolved[oldKey];
+		}
+	}
+
 	// Strict: reject unknown keys so users catch typos immediately.
-	// If OpenClaw adds new platform-level keys that should pass through,
-	// add them to ALLOWED_KEYS rather than silently accepting anything.
-	const unknownKeys = Object.keys(obj).filter((k) => !ALLOWED_KEYS.has(k));
+	const unknownKeys = Object.keys(resolved).filter((k) => !ALLOWED_KEYS.has(k));
 	if (unknownKeys.length > 0) {
 		throw new Error(
 			`nowledge-mem: unknown config key${unknownKeys.length > 1 ? "s" : ""}: ${unknownKeys.join(", ")}. ` +
@@ -33,25 +54,36 @@ export function parseConfig(raw) {
 
 	// apiUrl: config wins, then env var, then local default
 	const apiUrl =
-		(typeof obj.apiUrl === "string" && obj.apiUrl.trim()) ||
+		(typeof resolved.apiUrl === "string" && resolved.apiUrl.trim()) ||
 		(typeof process.env.NMEM_API_URL === "string" &&
 			process.env.NMEM_API_URL.trim()) ||
 		"";
 
 	// apiKey: config wins, then env var — never logged, never in CLI args
 	const apiKey =
-		(typeof obj.apiKey === "string" && obj.apiKey.trim()) ||
+		(typeof resolved.apiKey === "string" && resolved.apiKey.trim()) ||
 		(typeof process.env.NMEM_API_KEY === "string" &&
 			process.env.NMEM_API_KEY.trim()) ||
 		"";
 
 	return {
-		autoRecall: typeof obj.autoRecall === "boolean" ? obj.autoRecall : false,
-		autoCapture: typeof obj.autoCapture === "boolean" ? obj.autoCapture : false,
-		maxRecallResults:
-			typeof obj.maxRecallResults === "number" &&
-			Number.isFinite(obj.maxRecallResults)
-				? Math.min(20, Math.max(1, Math.trunc(obj.maxRecallResults)))
+		sessionContext:
+			typeof resolved.sessionContext === "boolean"
+				? resolved.sessionContext
+				: false,
+		sessionDigest:
+			typeof resolved.sessionDigest === "boolean"
+				? resolved.sessionDigest
+				: true,
+		digestMinInterval:
+			typeof resolved.digestMinInterval === "number" &&
+			Number.isFinite(resolved.digestMinInterval)
+				? Math.min(86400, Math.max(0, Math.trunc(resolved.digestMinInterval)))
+				: 300,
+		maxContextResults:
+			typeof resolved.maxContextResults === "number" &&
+			Number.isFinite(resolved.maxContextResults)
+				? Math.min(20, Math.max(1, Math.trunc(resolved.maxContextResults)))
 				: 5,
 		apiUrl,
 		apiKey,

package/src/hooks/behavioral.js

@@ -0,0 +1,43 @@
+/**
+ * Always-on behavioral hook — injected via before_prompt_build on EVERY turn.
+ *
+ * This is the single most impactful change for memory adoption:
+ * most LLMs ignore "call this proactively" in tool descriptions,
+ * but reliably follow behavioral guidance in prepended context.
+ *
+ * Cost: ~50 tokens per turn. Negligible.
+ *
+ * When sessionContext is enabled, guidance is adjusted to note that
+ * relevant memories are already injected — reducing redundant searches
+ * while keeping the save nudge and thread awareness.
+ */
+
+const BASE_GUIDANCE = [
+	"<nowledge-mem-guidance>",
+	"You have access to the user's personal knowledge graph (Nowledge Mem).",
+	"When the conversation produces something worth keeping — a decision made, a preference stated,",
+	"something learned, a plan formed, a useful discovery — save it with nowledge_mem_save. Don't wait to be asked.",
+	"When prior context would improve your response, search with memory_search.",
+	"memory_search also returns relevant past conversation snippets alongside memories.",
+	"When a memory has a sourceThreadId, fetch the full conversation with nowledge_mem_thread_fetch.",
+	"</nowledge-mem-guidance>",
+].join("\n");
+
+const SESSION_CONTEXT_GUIDANCE = [
+	"<nowledge-mem-guidance>",
+	"You have access to the user's personal knowledge graph (Nowledge Mem).",
+	"Relevant memories and your Working Memory have already been injected into this prompt.",
+	"Use memory_search only when you need something specific beyond what was auto-recalled.",
+	"When the conversation produces something worth keeping — a decision made, a preference stated,",
+	"something learned, a plan formed, a useful discovery — save it with nowledge_mem_save. Don't wait to be asked.",
+	"When a memory has a sourceThreadId, fetch the full conversation with nowledge_mem_thread_fetch.",
+	"</nowledge-mem-guidance>",
+].join("\n");
+
+export function buildBehavioralHook(logger, { sessionContext = false } = {}) {
+	const guidance = sessionContext ? SESSION_CONTEXT_GUIDANCE : BASE_GUIDANCE;
+	return (_event, _ctx) => {
+		logger.debug?.("behavioral: injecting guidance");
+		return { prependContext: guidance };
+	};
+}

package/src/hooks/capture.js

@@ -6,6 +6,23 @@ const MAX_DISTILL_MESSAGE_CHARS = 2000;
 const MAX_CONVERSATION_CHARS = 30_000;
 const MIN_MESSAGES_FOR_DISTILL = 4;
 
+// Per-thread triage cooldown: prevents burst triage/distillation from heartbeat.
+// Maps threadId -> timestamp (ms) of last successful triage.
+// Evicted opportunistically when new entries are set (see _setLastCapture).
+const _lastCaptureAt = new Map();
+const _MAX_COOLDOWN_ENTRIES = 200;
+
+function _setLastCapture(threadId, now) {
+	_lastCaptureAt.set(threadId, now);
+	// Opportunistic eviction: sweep stale entries when map grows large
+	if (_lastCaptureAt.size > _MAX_COOLDOWN_ENTRIES) {
+		const cutoff = now - 86_400_000; // 24h — generous TTL
+		for (const [key, ts] of _lastCaptureAt) {
+			if (ts < cutoff) _lastCaptureAt.delete(key);
+		}
+	}
+}
+
 function truncate(text, max = MAX_MESSAGE_CHARS) {
 	const str = String(text || "").trim();
 	if (!str) return "";
@@ -189,10 +206,11 @@ async function appendOrCreateThread({ client, logger, event, ctx, reason }) {
 			deduplicate: true,
 			idempotencyKey,
 		});
+		const added = appended.messagesAdded ?? 0;
 		logger.info(
-			`capture: appended ${appended.messagesAdded} messages to ${threadId} (${reason || "event"})`,
+			`capture: appended ${added} messages to ${threadId} (${reason || "event"})`,
 		);
-		return { threadId, normalized };
+		return { threadId, normalized, messagesAdded: added };
 	} catch (err) {
 		if (!client.isThreadNotFoundError(err)) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -211,7 +229,7 @@ async function appendOrCreateThread({ client, logger, event, ctx, reason }) {
 		logger.info(
 			`capture: created thread ${createdId} with ${messages.length} messages (${reason || "event"})`,
 		);
-		return { threadId, normalized };
+		return { threadId, normalized, messagesAdded: messages.length };
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		logger.warn(`capture: thread create failed for ${threadId}: ${message}`);
@@ -256,10 +274,14 @@ function buildConversationText(normalized) {
  * triage or distillation, since those are mid-session checkpoints.
  */
 export function buildAgentEndCaptureHandler(client, cfg, logger) {
+	const cooldownMs = (cfg.digestMinInterval ?? 300) * 1000;
+
 	return async (event, ctx) => {
 		if (!event?.success) return;
 
 		// 1. Always thread-append (idempotent, self-guards on empty messages).
+		//    Never skip this — messages must always be persisted regardless of
+		//    cooldown state, since appendOrCreateThread is deduped and cheap.
 		const result = await appendOrCreateThread({
 			client,
 			logger,
@@ -271,11 +293,29 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 		// 2. Triage + distill: language-agnostic LLM-based capture.
 		//    Defensive guard — registration in index.js already gates on autoCapture,
 		//    but check here too so the handler is safe if called directly.
-		if (!cfg.autoCapture) return;
+		if (!cfg.sessionDigest) return;
+
+		//    Skip when no new messages were added (e.g. heartbeat re-sync).
+		if (!result || result.messagesAdded === 0) {
+			logger.debug?.("capture: no new messages since last sync, skipping triage");
+			return;
+		}
+
+		//    Triage cooldown: skip expensive LLM triage/distillation if this
+		//    thread was already triaged recently. Thread append above still ran,
+		//    so no messages are lost — only the LLM cost is avoided.
+		if (cooldownMs > 0 && result.threadId) {
+			const lastCapture = _lastCaptureAt.get(result.threadId) || 0;
+			if (Date.now() - lastCapture < cooldownMs) {
+				logger.debug?.(
+					`capture: triage cooldown active for ${result.threadId}, skipping`,
+				);
+				return;
+			}
+		}
 
 		//    Skip short conversations — not worth the triage cost.
 		if (
-			!result ||
 			!result.normalized ||
 			result.normalized.length < MIN_MESSAGES_FOR_DISTILL
 		) {
@@ -285,6 +325,13 @@ export function buildAgentEndCaptureHandler(client, cfg, logger) {
 		const conversationText = buildConversationText(result.normalized);
 		if (conversationText.length < 100) return;
 
+		//    Record cooldown AFTER all eligibility checks pass, right before
+		//    the expensive LLM call. If triage was skipped by filters above,
+		//    the cooldown stays unset so the next call can retry.
+		if (cooldownMs > 0 && result.threadId) {
+			_setLastCapture(result.threadId, Date.now());
+		}
+
 		try {
 			const triage = await client.triageConversation(conversationText);
 			if (!triage?.should_distill) {

package/src/hooks/recall.js

@@ -44,7 +44,7 @@ export function buildRecallHandler(client, cfg, logger) {
 
 		// 2. Relevant memories — enriched with scoring signals and labels
 		try {
-			const results = await client.searchRich(prompt, cfg.maxRecallResults);
+			const results = await client.searchRich(prompt, cfg.maxContextResults);
 			if (results.length > 0) {
 				const lines = results.map((r) => {
 					const title = r.title || "(untitled)";

package/src/index.js

@@ -6,6 +6,7 @@ import {
 	createRememberCommand,
 } from "./commands/slash.js";
 import { isDefaultApiUrl, parseConfig } from "./config.js";
+import { buildBehavioralHook } from "./hooks/behavioral.js";
 import {
 	buildAgentEndCaptureHandler,
 	buildBeforeResetCaptureHandler,
@@ -17,6 +18,8 @@ import { createForgetTool } from "./tools/forget.js";
 import { createMemoryGetTool } from "./tools/memory-get.js";
 import { createMemorySearchTool } from "./tools/memory-search.js";
 import { createSaveTool } from "./tools/save.js";
+import { createThreadFetchTool } from "./tools/thread-fetch.js";
+import { createThreadSearchTool } from "./tools/thread-search.js";
 import { createTimelineTool } from "./tools/timeline.js";
 
 export default {
@@ -45,12 +48,22 @@ export default {
 		api.registerTool(createTimelineTool(client, logger));
 		api.registerTool(createForgetTool(client, logger));
 
-		// Hooks
-		if (cfg.autoRecall) {
-			api.on("before_agent_start", buildRecallHandler(client, cfg, logger));
+		// Thread tools (progressive conversation retrieval)
+		api.registerTool(createThreadSearchTool(client, logger));
+		api.registerTool(createThreadFetchTool(client, logger));
+
+		// Always-on: behavioral guidance so the agent proactively saves and searches.
+		// Fires every turn via before_prompt_build — ~50 tokens, negligible cost.
+		// When sessionContext is on, guidance adjusts to avoid redundant searches.
+		api.on("before_prompt_build", buildBehavioralHook(logger, cfg));
+
+		// Session context: inject Working Memory + recalled memories at prompt time.
+		if (cfg.sessionContext) {
+			api.on("before_prompt_build", buildRecallHandler(client, cfg, logger));
 		}
 
-		if (cfg.autoCapture) {
+		// Session digest: capture threads + LLM distillation at lifecycle events.
+		if (cfg.sessionDigest) {
 			const threadCaptureHandler = buildBeforeResetCaptureHandler(
 				client,
 				cfg,
@@ -75,7 +88,7 @@ export default {
 
 		const remoteMode = !isDefaultApiUrl(cfg.apiUrl);
 		logger.info(
-			`nowledge-mem: initialized (recall=${cfg.autoRecall}, capture=${cfg.autoCapture}, mode=${remoteMode ? `remote → ${cfg.apiUrl}` : "local"})`,
+			`nowledge-mem: initialized (context=${cfg.sessionContext}, digest=${cfg.sessionDigest}, mode=${remoteMode ? `remote → ${cfg.apiUrl}` : "local"})`,
 		);
 	},
 };

package/src/tools/forget.js

@@ -87,8 +87,9 @@ export function createForgetTool(client, logger) {
 					};
 				}
 
-				// Single high-confidence match — delete directly
-				if (results.length === 1 || results[0].score >= 0.85) {
+				// Auto-delete only when exactly one result with high confidence.
+				// Deletion is irreversible — if multiple matches exist, always ask.
+				if (results.length === 1 && results[0].score >= 0.85) {
 					const target = results[0];
 					try {
 						client.exec(["--json", "m", "delete", "-f", target.id]);
@@ -115,7 +116,7 @@ export function createForgetTool(client, logger) {
 					}
 				}
 
-				// Multiple candidates — return list for user to pick
+				// Multiple candidates or low confidence — return list for user to pick
 				const candidates = results.map(
 					(r, i) =>
 						`${i + 1}. ${r.title || "(untitled)"} (${(r.score * 100).toFixed(0)}%) — id: ${r.id}\n   ${r.content.slice(0, 100)}`,

package/src/tools/memory-get.js

@@ -135,19 +135,29 @@ export function createMemoryGetTool(client, logger) {
 					safeParams.lines,
 				);
 
+				// Thread provenance: link to the source conversation
+				const sourceThreadId =
+					memory.source_thread ??
+					memory.source_thread_id ??
+					memory.metadata?.source_thread_id ??
+					null;
+
+				const result = {
+					path,
+					memoryId,
+					title: memory.title || "(untitled)",
+					text: snippet.text,
+					startLine: snippet.startLine,
+					endLine: snippet.endLine,
+					totalLines: snippet.totalLines,
+				};
+				if (sourceThreadId) result.sourceThreadId = sourceThreadId;
+
 				return {
 					content: [
 						{
 							type: "text",
-							text: JSON.stringify({
-								path,
-								memoryId,
-								title: memory.title || "(untitled)",
-								text: snippet.text,
-								startLine: snippet.startLine,
-								endLine: snippet.endLine,
-								totalLines: snippet.totalLines,
-							}),
+							text: JSON.stringify(result),
 						},
 					],
 				};

package/src/tools/memory-search.js

@@ -19,6 +19,7 @@ export function createMemorySearchTool(client, logger) {
 			"Don't wait to be asked — if the conversation topic might have relevant history, search for it. " +
 			"Uses multi-signal scoring: semantic, BM25 keyword, label, graph & community signals, recency/importance decay. " +
 			"Returns snippets with memoryIds — pass a memoryId to nowledge_mem_connections for cross-topic synthesis or source provenance. " +
+			"Also returns relevant past conversation snippets (relatedThreads) when available. " +
 			"Supports bi-temporal filtering: event_date_from/to (when the fact HAPPENED), recorded_date_from/to (when it was SAVED). " +
 			"For browsing recent activity by day use nowledge_mem_timeline instead.",
 		parameters: {
@@ -140,22 +141,50 @@ export function createMemorySearchTool(client, logger) {
 					if (entry.eventEnd) result.eventEnd = entry.eventEnd;
 					if (entry.temporalContext)
 						result.temporalContext = entry.temporalContext;
+					// Thread provenance: link to the source conversation
+					if (entry.sourceThreadId)
+						result.sourceThreadId = entry.sourceThreadId;
 					return result;
 				});
 
+				// Enrich with thread snippets (best-effort, non-blocking)
+				let threadSnippets = [];
+				try {
+					const { threads } = await client.searchThreads(query, 3);
+					if (threads.length > 0) {
+						threadSnippets = threads.map((t) => {
+							const msgs = (t.matched_messages ?? []).slice(0, 2);
+							return {
+								threadId: t.thread_id ?? t.id,
+								title: t.title || "(untitled thread)",
+								source: t.source ?? "unknown",
+								lastActivity: t.last_activity ?? null,
+								relevanceScore: Number(t.relevance_score ?? 0),
+								matchedMessages: msgs.map((m) => ({
+									role: m.role,
+									snippet: truncateSnippet(m.snippet, 200),
+								})),
+							};
+						});
+					}
+				} catch {
+					// Thread search failure is not fatal
+				}
+
+				const responsePayload = {
+					results,
+					provider: "nmem",
+					mode: "multi-signal",
+				};
+				if (threadSnippets.length > 0) {
+					responsePayload.relatedThreads = threadSnippets;
+				}
+
 				return {
 					content: [
 						{
 							type: "text",
-							text: JSON.stringify(
-								{
-									results,
-									provider: "nmem",
-									mode: "multi-signal",
-								},
-								null,
-								2,
-							),
+							text: JSON.stringify(responsePayload, null, 2),
 						},
 					],
 					details: { query, resultCount: results.length },

package/src/tools/save.js

@@ -124,6 +124,39 @@ export function createSaveTool(client, logger) {
 				};
 			}
 
+			// Dedup check: search for near-identical existing memories before saving.
+			// Only blocks at very high similarity (≥0.9) to avoid false positives.
+			// Lower matches (0.7-0.9) are noted but allowed — the Knowledge Agent
+			// handles deeper dedup via EVOLVES chains in the background.
+			try {
+				const query = title || text.slice(0, 200);
+				const existing = await client.searchRich(query, 3);
+				if (existing.length > 0) {
+					const top = existing[0];
+					if (top.score >= 0.9) {
+						logger.info(
+							`save: skipped — near-identical memory exists: ${top.id} (${(top.score * 100).toFixed(0)}%)`,
+						);
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Not saved — a near-identical memory already exists:\n"${top.title}" (id: ${top.id}, similarity: ${(top.score * 100).toFixed(0)}%)\nUse memory_get with id ${top.id} to read it.`,
+								},
+							],
+							details: {
+								skipped: true,
+								reason: "duplicate",
+								existingId: top.id,
+								similarity: top.score,
+							},
+						};
+					}
+				}
+			} catch {
+				// Dedup check is best-effort — never block saves on search failure
+			}
+
 			try {
 				const args = ["--json", "m", "add", text];
 				if (title) args.push("-t", title);