@openclaw/memory-lancedb 2026.7.2-beta.4 → 2026.7.2-beta.7

package/dist/cli-metadata.js

@@ -1,3 +1,4 @@
+import { isMemoryMachineOutput } from "./cli-output-mode.js";
 import { definePluginEntry } from "openclaw/plugin-sdk/core";
 //#region extensions/memory-lancedb/cli-metadata.ts
 var cli_metadata_default = definePluginEntry({
@@ -8,7 +9,8 @@ var cli_metadata_default = definePluginEntry({
 		api.registerCli(() => {}, { descriptors: [{
 			name: "ltm",
 			description: "Inspect and query LanceDB-backed memory",
-			hasSubcommands: true
+			hasSubcommands: true,
+			machineOutput: isMemoryMachineOutput
 		}] });
 	}
 });

package/dist/cli-output-mode.js

@@ -0,0 +1,13 @@
+import { getRootOptionAwareCommandPath } from "openclaw/plugin-sdk/cli-argv";
+//#region extensions/memory-lancedb/cli-output-mode.ts
+/** LanceDB inspection commands emit JSON as their only presentation. */
+function isMemoryMachineOutput(params) {
+	const [, command] = getRootOptionAwareCommandPath(params.argv, 2);
+	return [
+		"list",
+		"query",
+		"search"
+	].includes(command ?? "");
+}
+//#endregion
+export { isMemoryMachineOutput };

package/dist/config.js

@@ -1,7 +1,6 @@
-import { parseFiniteNumber } from "openclaw/plugin-sdk/number-runtime";
-import fs from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { parseFiniteNumber } from "openclaw/plugin-sdk/number-runtime";
 //#region extensions/memory-lancedb/config.ts
 const MEMORY_CATEGORIES = [
 	"preference",
@@ -13,22 +12,7 @@ const MEMORY_CATEGORIES = [
 const DEFAULT_MODEL = "text-embedding-3-small";
 const DEFAULT_CAPTURE_MAX_CHARS = 500;
 const DEFAULT_RECALL_MAX_CHARS = 1e3;
-const LEGACY_STATE_DIRS = [];
-function resolveDefaultDbPath() {
-	const home = homedir();
-	const preferred = join(home, ".openclaw", "memory", "lancedb");
-	try {
-		if (fs.existsSync(preferred)) return preferred;
-	} catch {}
-	for (const legacy of LEGACY_STATE_DIRS) {
-		const candidate = join(home, legacy, "memory", "lancedb");
-		try {
-			if (fs.existsSync(candidate)) return candidate;
-		} catch {}
-	}
-	return preferred;
-}
-const DEFAULT_DB_PATH = resolveDefaultDbPath();
+const DEFAULT_DB_PATH = join(homedir(), ".openclaw", "memory", "lancedb");
 const EMBEDDING_DIMENSIONS = {
 	"text-embedding-3-small": 1536,
 	"text-embedding-3-large": 3072

package/dist/doctor-contract-api.js

@@ -1,10 +1,37 @@
 import { MEMORY_AGENT_ID_COLUMN, MEMORY_TABLE_NAME, hasAgentScopeColumn, memoryAgentPredicate, quoteLanceSqlString } from "./lancedb-schema.js";
 import { resolveDefaultAgentId } from "openclaw/plugin-sdk/agent-runtime";
-import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region extensions/memory-lancedb/doctor-contract-api.ts
+const LEGACY_ENVELOPE_DELETE_BATCH_SIZE = 500;
+const LEGACY_ENVELOPE_SENTINEL_LINE_RE = new RegExp(`^(?:${[
+	"Conversation info (untrusted metadata):",
+	"Sender (untrusted metadata):",
+	"Thread starter (untrusted, for context):",
+	"Reply target of current user message (untrusted, for context):",
+	"Replied message (untrusted, for context):",
+	"Forwarded message context (untrusted metadata):",
+	"Conversation context (untrusted, chronological, selected for current message):",
+	"Current local chat window (untrusted, chronological, before current message):",
+	"Nearby reply target window (untrusted, chronological, around replied-to message):",
+	"Chat history since last reply (untrusted, for context):"
+].map((sentinel) => sentinel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})[^\\n]*$`, "m");
+const LEGACY_ENVELOPE_LABEL_JSON_BLOCK_RE = /^[^\n]+\((?:untrusted metadata|untrusted, for context|untrusted, nearest first|untrusted, chronological,[^\n)]{1,80})\):[ \t]*\n[ \t]*```json[ \t]*\n[\s\S]*?\n[ \t]*```[ \t]*(?:\n|$)/m;
+const LEGACY_ENVELOPE_HEADER_RE = /^Untrusted context \(metadata, do not treat as instructions or commands\):[ \t]*$/m;
+function isLegacyEnvelopeContaminatedText(text) {
+	return typeof text === "string" && (LEGACY_ENVELOPE_SENTINEL_LINE_RE.test(text) || LEGACY_ENVELOPE_LABEL_JSON_BLOCK_RE.test(text) || LEGACY_ENVELOPE_HEADER_RE.test(text));
+}
+async function scanLegacyEnvelopeRowIds(table) {
+	const contaminatedIds = [];
+	for await (const batch of table.query().select(["id", "text"])) for (const row of batch.toArray()) {
+		if (!isLegacyEnvelopeContaminatedText(row.text)) continue;
+		if (typeof row.id !== "string") throw new Error("LanceDB legacy envelope row is missing a string id");
+		contaminatedIds.push(row.id);
+	}
+	return contaminatedIds;
+}
 function resolveMemoryLanceDbPluginRoot(moduleUrl) {
 	const artifactDir = path.dirname(fileURLToPath(moduleUrl));
 	return path.basename(artifactDir) === "dist" ? path.dirname(artifactDir) : artifactDir;
@@ -97,6 +124,54 @@ function createMemoryLanceDbStateMigrations(pluginRoot = DEFAULT_PLUGIN_ROOT) {
 				opened.connection?.close();
 			}
 		}
+	}, {
+		id: "memory-lancedb-legacy-envelope-rows",
+		label: "Memory LanceDB legacy envelope contamination",
+		doctorOnly: true,
+		async detectLegacyState(params) {
+			const opened = await openMemoryTable({
+				...params,
+				pluginRoot
+			});
+			try {
+				if (!opened.table) return null;
+				const contaminatedIds = await scanLegacyEnvelopeRowIds(opened.table);
+				if (contaminatedIds.length === 0) return null;
+				return { preview: [`- Memory LanceDB: delete ${contaminatedIds.length} memory ${contaminatedIds.length === 1 ? "row" : "rows"} contaminated with legacy envelope metadata at ${opened.dbPath}`] };
+			} finally {
+				opened.table?.close();
+				opened.connection?.close();
+			}
+		},
+		async migrateLegacyState(params) {
+			const opened = await openMemoryTable({
+				...params,
+				pluginRoot
+			});
+			try {
+				if (!opened.table) return {
+					changes: [],
+					warnings: []
+				};
+				const contaminatedIds = await scanLegacyEnvelopeRowIds(opened.table);
+				if (contaminatedIds.length === 0) return {
+					changes: [],
+					warnings: []
+				};
+				for (let offset = 0; offset < contaminatedIds.length; offset += LEGACY_ENVELOPE_DELETE_BATCH_SIZE) {
+					const batch = contaminatedIds.slice(offset, offset + LEGACY_ENVELOPE_DELETE_BATCH_SIZE);
+					await opened.table.delete(`id IN (${batch.map((id) => quoteLanceSqlString(id)).join(", ")})`);
+				}
+				if ((await scanLegacyEnvelopeRowIds(opened.table)).length !== 0) throw new Error("LanceDB legacy envelope row migration verification failed");
+				return {
+					changes: [`Deleted ${contaminatedIds.length} Memory LanceDB ${contaminatedIds.length === 1 ? "row" : "rows"} contaminated with legacy envelope metadata`],
+					warnings: []
+				};
+			} finally {
+				opened.table?.close();
+				opened.connection?.close();
+			}
+		}
 	}];
 }
 const stateMigrations = createMemoryLanceDbStateMigrations();

package/dist/embeddings.js

@@ -0,0 +1,312 @@
+import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
+import { asOptionalRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { resolveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
+import { Buffer } from "node:buffer";
+import { toErrorObject } from "openclaw/plugin-sdk/error-runtime";
+import { resolveGlobalSingleton } from "openclaw/plugin-sdk/global-singleton";
+import { canonicalizeBase64 } from "openclaw/plugin-sdk/media-runtime";
+import { ensureGlobalUndiciEnvProxyDispatcher } from "openclaw/plugin-sdk/runtime-env";
+//#region extensions/memory-lancedb/embeddings.ts
+const loadOpenAiModule = createLazyRuntimeModule(() => import("openai"));
+const loadMemoryEmbeddingProviderModule = createLazyRuntimeModule(() => import("openclaw/plugin-sdk/memory-core-host-engine-embeddings"));
+const loadMemoryHostCoreModule = createLazyRuntimeModule(() => import("openclaw/plugin-sdk/memory-host-core"));
+const PROVIDER_ADAPTER_LIFECYCLE = resolveGlobalSingleton(Symbol.for("openclaw.memoryLanceDbEmbeddingProviderLifecycle.v1"), () => ({
+	retainedProviders: /* @__PURE__ */ new Set(),
+	tail: Promise.resolve()
+}));
+function runProviderAdapterLifecycle(operation) {
+	const result = PROVIDER_ADAPTER_LIFECYCLE.tail.then(operation, operation);
+	PROVIDER_ADAPTER_LIFECYCLE.tail = result.then(() => void 0, () => void 0);
+	return result;
+}
+async function drainRetainedProviders() {
+	let firstError;
+	let closeFailed = false;
+	for (const provider of PROVIDER_ADAPTER_LIFECYCLE.retainedProviders) try {
+		await provider.close?.();
+		PROVIDER_ADAPTER_LIFECYCLE.retainedProviders.delete(provider);
+	} catch (err) {
+		if (!closeFailed) firstError = err;
+		closeFailed = true;
+	}
+	if (closeFailed) throw toErrorObject(firstError, "memory-lancedb embedding provider retirement failed");
+}
+var OpenAiCompatibleEmbeddings = class {
+	constructor(apiKey, model, baseUrl, dimensions) {
+		this.model = model;
+		this.dimensions = dimensions;
+		this.clientPromise = loadOpenAiModule().then(({ default: OpenAI }) => new OpenAI({
+			apiKey,
+			baseURL: baseUrl
+		}));
+	}
+	async embed(text, options) {
+		const dimensions = this.dimensions;
+		const startedAtMs = options?.timeoutMs && Number.isFinite(options.timeoutMs) ? Date.now() : null;
+		try {
+			return normalizeEmbeddingVector((await this.postEmbedding(text, {
+				includeDimensions: true,
+				options
+			})).data?.[0]?.embedding);
+		} catch (error) {
+			if (typeof dimensions !== "number" || !isEmbeddingDimensionsRejectedError(error)) throw error;
+		}
+		const fallbackOptions = startedAtMs === null || options?.timeoutMs === void 0 ? options : { timeoutMs: Math.max(1, options.timeoutMs - (Date.now() - startedAtMs)) };
+		return truncateEmbeddingVector(normalizeEmbeddingVector((await this.postEmbedding(text, {
+			includeDimensions: false,
+			options: fallbackOptions
+		})).data?.[0]?.embedding), dimensions, this.model);
+	}
+	async postEmbedding(text, request) {
+		const params = {
+			model: this.model,
+			input: text,
+			...request.includeDimensions && typeof this.dimensions === "number" ? { dimensions: this.dimensions } : {}
+		};
+		ensureGlobalUndiciEnvProxyDispatcher();
+		return await (await this.clientPromise).post("/embeddings", {
+			body: params,
+			...request.options?.timeoutMs ? {
+				timeout: request.options.timeoutMs,
+				maxRetries: 0
+			} : {}
+		});
+	}
+};
+function isEmbeddingDimensionsRejectedError(error) {
+	const record = asOptionalRecord(error);
+	if (record?.status !== 400 && record?.status !== 422) return false;
+	const details = stringifyEmbeddingApiError(error).toLowerCase();
+	return /\bdimensions\b/.test(details) && isUnsupportedEmbeddingFieldError(details);
+}
+function isUnsupportedEmbeddingFieldError(details) {
+	if (/\b(?:parameter|field|argument)[_ -]value\b/.test(details)) return false;
+	return /\bextra[_ -]forbidden\b/.test(details) || /\bextra inputs? (?:are )?not permitted\b/.test(details) || /\bextra fields? (?:are )?not permitted\b/.test(details) || /\b(?:unknown|unrecognized|unexpected|unsupported)[_ -](?:request[_ -])?(?:parameter|field|argument)\b/.test(details);
+}
+function stringifyEmbeddingApiError(error) {
+	const record = asOptionalRecord(error);
+	const parts = error instanceof Error ? [error.message] : [];
+	for (const value of [
+		record?.code,
+		record?.type,
+		record?.param,
+		record?.error
+	]) {
+		if (typeof value === "string" || typeof value === "number") {
+			parts.push(String(value));
+			continue;
+		}
+		if (value && typeof value === "object") try {
+			parts.push(JSON.stringify(value));
+		} catch {}
+	}
+	return parts.join("\n");
+}
+function truncateEmbeddingVector(embedding, dimensions, model) {
+	if (embedding.length < dimensions) throw new Error(`Embedding model ${model} returned ${embedding.length} dimensions, need at least ${dimensions} for local truncation`);
+	const truncated = embedding.slice(0, dimensions);
+	const magnitude = Math.sqrt(truncated.reduce((sum, value) => sum + value * value, 0));
+	return magnitude > 0 ? truncated.map((value) => value / magnitude) : truncated;
+}
+var ProviderAdapterEmbeddings = class {
+	constructor(api, embedding) {
+		this.api = api;
+		this.embedding = embedding;
+		this.closePromise = null;
+		this.closed = false;
+		this.activeUses = 0;
+		this.idleWaiters = /* @__PURE__ */ new Set();
+	}
+	getProvider() {
+		this.providerPromise ??= this.createProvider().catch((err) => {
+			this.providerPromise = void 0;
+			throw err;
+		});
+		return this.providerPromise;
+	}
+	acquireUse() {
+		if (this.closed) throw new Error("memory-lancedb embeddings are closed");
+		this.activeUses += 1;
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.activeUses -= 1;
+			if (this.activeUses === 0) {
+				const waiters = Array.from(this.idleWaiters);
+				this.idleWaiters.clear();
+				for (const resolve of waiters) resolve();
+			}
+		};
+	}
+	async awaitIdle() {
+		if (this.activeUses === 0) return;
+		await new Promise((resolve) => {
+			this.idleWaiters.add(resolve);
+		});
+	}
+	async createProvider() {
+		return await runProviderAdapterLifecycle(async () => {
+			await drainRetainedProviders();
+			return await this.createProviderAfterRetirement();
+		});
+	}
+	async createProviderAfterRetirement() {
+		const cfg = this.api.runtime.config?.current?.() ?? this.api.config;
+		const providerId = this.embedding.provider;
+		const { getMemoryEmbeddingProvider } = await loadMemoryEmbeddingProviderModule();
+		const adapter = getMemoryEmbeddingProvider(providerId, cfg);
+		if (!adapter) throw new Error(`Unknown memory embedding provider: ${providerId}`);
+		const { resolveDefaultAgentId } = await loadMemoryHostCoreModule();
+		const defaultAgentId = resolveDefaultAgentId(cfg);
+		const agentDir = this.api.runtime.agent.resolveAgentDir(cfg, defaultAgentId);
+		const remote = this.embedding.apiKey || this.embedding.baseUrl ? {
+			...this.embedding.apiKey ? { apiKey: this.embedding.apiKey } : {},
+			...this.embedding.baseUrl ? { baseUrl: this.embedding.baseUrl } : {}
+		} : void 0;
+		const result = await adapter.create({
+			config: cfg,
+			agentDir,
+			provider: providerId,
+			fallback: "none",
+			model: this.embedding.model,
+			...remote ? { remote } : {},
+			...typeof this.embedding.dimensions === "number" ? { outputDimensionality: this.embedding.dimensions } : {}
+		});
+		if (!result.provider) throw new Error(`Memory embedding provider ${providerId} is unavailable.`);
+		return result.provider;
+	}
+	async embed(text, options) {
+		const releaseUse = this.acquireUse();
+		try {
+			const provider = await this.getProvider();
+			if (!options?.timeoutMs) return await provider.embedQuery(text);
+			const controller = new AbortController();
+			let timer;
+			try {
+				timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("memory-lancedb embedding timed out")), resolveTimerTimeoutMs(options.timeoutMs, 1));
+				timer.unref?.();
+				return await provider.embedQuery(text, { signal: controller.signal });
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+		} finally {
+			releaseUse();
+		}
+	}
+	async close() {
+		const existingClose = this.closePromise;
+		if (existingClose) {
+			await existingClose;
+			return;
+		}
+		const closeOperation = this.closeOnce();
+		this.closePromise = closeOperation;
+		try {
+			await closeOperation;
+		} catch (err) {
+			if (this.closePromise === closeOperation) this.closePromise = null;
+			throw err;
+		}
+	}
+	async closeOnce() {
+		this.closed = true;
+		const providerPromise = this.providerPromise;
+		await runProviderAdapterLifecycle(async () => {
+			await this.awaitIdle();
+			const provider = await providerPromise?.catch(() => null);
+			if (provider) PROVIDER_ADAPTER_LIFECYCLE.retainedProviders.add(provider);
+			try {
+				await drainRetainedProviders();
+			} finally {
+				if (this.providerPromise === providerPromise) this.providerPromise = void 0;
+			}
+		});
+	}
+};
+async function runWithTimeout(params) {
+	let timeout;
+	const TIMEOUT = Symbol("timeout");
+	const timeoutPromise = new Promise((resolve) => {
+		timeout = setTimeout(() => resolve(TIMEOUT), resolveTimerTimeoutMs(params.timeoutMs, 1));
+		timeout.unref?.();
+	});
+	const taskPromise = params.task();
+	taskPromise.catch(() => void 0);
+	try {
+		const result = await Promise.race([taskPromise, timeoutPromise]);
+		if (result === TIMEOUT) return { status: "timeout" };
+		return {
+			status: "ok",
+			value: result
+		};
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+function formatMemoryRecallError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isMemoryRecallTimeoutError(error) {
+	let current = error;
+	for (let depth = 0; depth < 3 && current !== void 0; depth += 1) {
+		const record = asOptionalRecord(current);
+		const name = current instanceof Error ? current.name : typeof record?.name === "string" ? record.name : "";
+		const message = current instanceof Error ? current.message : typeof record?.message === "string" ? record.message : "";
+		const code = typeof record?.code === "string" ? record.code : "";
+		if (name === "APIConnectionTimeoutError" || name === "TimeoutError" || code === "ETIMEDOUT" || /^UND_ERR_.*_TIMEOUT$/.test(code) || /\btimed out\b/i.test(message)) return true;
+		current = record?.cause;
+	}
+	return false;
+}
+function buildMemoryRecallUnavailableResult(error) {
+	return {
+		content: [{
+			type: "text",
+			text: "Memory recall is unavailable right now."
+		}],
+		details: {
+			count: 0,
+			disabled: true,
+			unavailable: true,
+			error
+		}
+	};
+}
+var MemoryRecallEmbeddingError = class extends Error {
+	constructor(originalError) {
+		super(formatMemoryRecallError(originalError));
+		this.originalError = originalError;
+		this.name = "MemoryRecallEmbeddingError";
+	}
+};
+const testing = {
+	isEmbeddingDimensionsRejectedError,
+	isMemoryRecallTimeoutError,
+	runWithTimeout,
+	truncateEmbeddingVector
+};
+function createEmbeddings(api, cfg) {
+	const { provider, model, dimensions, apiKey, baseUrl } = cfg.embedding;
+	if (provider === "openai" && apiKey) return new OpenAiCompatibleEmbeddings(apiKey, model, baseUrl, dimensions);
+	return new ProviderAdapterEmbeddings(api, cfg.embedding);
+}
+function normalizeEmbeddingVector(value) {
+	if (Array.isArray(value)) {
+		if (!value.every((item) => typeof item === "number" && Number.isFinite(item))) throw new Error("Embedding response contains non-numeric values");
+		return value;
+	}
+	if (typeof value === "string") {
+		const canonicalEmbedding = canonicalizeBase64(value);
+		if (!canonicalEmbedding) throw new Error("Base64 embedding response is malformed");
+		const bytes = Buffer.from(canonicalEmbedding, "base64");
+		if (bytes.byteLength % Float32Array.BYTES_PER_ELEMENT !== 0) throw new Error("Base64 embedding response has invalid byte length");
+		const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+		const floats = [];
+		for (let offset = 0; offset < bytes.byteLength; offset += Float32Array.BYTES_PER_ELEMENT) floats.push(view.getFloat32(offset, true));
+		return floats;
+	}
+	throw new Error("Embedding response is missing a vector");
+}
+//#endregion
+export { MemoryRecallEmbeddingError, buildMemoryRecallUnavailableResult, createEmbeddings, formatMemoryRecallError, isMemoryRecallTimeoutError, normalizeEmbeddingVector, runWithTimeout, testing };