openclaw-cortex-memory 0.1.0-Alpha.8 → 0.1.0

package/dist/index.js

@@ -39,31 +39,21 @@ exports.getStatus = getStatus;
 exports.unregister = unregister;
 exports.register = register;
 /// <reference types="node" />
-const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
-const net = __importStar(require("net"));
 const ts_engine_1 = require("./src/engine/ts_engine");
 const read_store_1 = require("./src/store/read_store");
 const write_store_1 = require("./src/store/write_store");
 const archive_store_1 = require("./src/store/archive_store");
 const vector_store_1 = require("./src/store/vector_store");
+const graph_memory_store_1 = require("./src/store/graph_memory_store");
 const session_sync_1 = require("./src/sync/session_sync");
 const session_end_1 = require("./src/session/session_end");
 const rule_store_1 = require("./src/rules/rule_store");
 const reflector_1 = require("./src/reflect/reflector");
 const three_stage_deduplicator_1 = require("./src/dedup/three_stage_deduplicator");
+const runtime_env_1 = require("./src/utils/runtime_env");
 const ERROR_CODES = {
-    CONNECTION_REFUSED: {
-        code: "E001",
-        message: "Cannot connect to the memory service",
-        suggestion: "The Python backend may not be running. Try restarting the OpenClaw gateway."
-    },
-    TIMEOUT: {
-        code: "E002",
-        message: "The memory service is not responding",
-        suggestion: "The service may be overloaded. Wait a moment and try again."
-    },
     NOT_FOUND: {
         code: "E003",
         message: "Memory not found",
@@ -74,29 +64,82 @@ const ERROR_CODES = {
         message: "Invalid input provided",
         suggestion: "Please check your input parameters and try again."
     },
-    SERVICE_ERROR: {
-        code: "E005",
-        message: "The memory service encountered an error",
-        suggestion: "Check the service logs for details or try restarting the gateway."
-    },
     PLUGIN_DISABLED: {
         code: "E006",
         message: "Cortex Memory plugin is disabled",
-        suggestion: "Enable the plugin using 'openclaw plugins enable cortex-memory' or check openclaw.json"
+        suggestion: "Enable the plugin using 'openclaw plugins enable openclaw-cortex-memory' or check openclaw.json"
     }
 };
 const SENSITIVE_KEYS = ["API_KEY", "SECRET", "TOKEN", "PASSWORD", "APIKEY"];
 const PLUGIN_ID = "openclaw-cortex-memory";
-const MIN_OPENCLAW_VERSION = "2026.3.8";
-const MAX_OPENCLAW_VERSION = "2027.0.0";
+const TOOL_NAME_CORTEX_DIAGNOSTICS = "cortex_diagnostics";
+const TOOL_NAME_DIAGNOSTICS_LEGACY = "diagnostics";
+const definePluginEntryCompat = (() => {
+    try {
+        const sdk = require("openclaw/plugin-sdk/plugin-entry");
+        if (sdk && typeof sdk.definePluginEntry === "function") {
+            return sdk.definePluginEntry;
+        }
+    }
+    catch {
+        // Fallback keeps compatibility with hosts that only support legacy exports.
+    }
+    return (entry) => entry;
+})();
+const MIN_OPENCLAW_GATEWAY_VERSION = "2026.4.5";
+const MAX_OPENCLAW_GATEWAY_VERSION = "2027.0.0";
 const defaultConfig = {
     autoSync: true,
+    llmRequiredForWrite: true,
     autoReflect: false,
     autoReflectIntervalMinutes: 30,
+    graphQualityMode: "warn",
+    wikiProjection: {
+        enabled: true,
+        mode: "incremental",
+        maxBatch: 100,
+    },
     readFusion: {
         enabled: true,
         maxCandidates: 10,
         authoritative: true,
+        channelWeights: {
+            rules: 1,
+            archive: 1.15,
+            vector: 1.2,
+            graph: 1,
+        },
+        channelTopK: {
+            rules: 8,
+            archive: 20,
+            vector: 20,
+            graph: 12,
+        },
+        minLexicalHits: 1,
+        minSemanticHits: 1,
+        lengthNorm: {
+            enabled: true,
+            pivotChars: 1200,
+            strength: 0.75,
+            minFactor: 0.45,
+        },
+    },
+    vectorChunking: {
+        chunkSize: 600,
+        chunkOverlap: 100,
+        evidenceMaxChunks: 2,
+    },
+    writePolicy: {
+        archiveMinConfidence: 0.35,
+        archiveMinQualityScore: 0.4,
+        activeMinQualityScore: 0.45,
+        activeDedupTailLines: 200,
+        activeTextMaxChars: 200000,
+        archiveSourceTextMaxChars: 500000,
+    },
+    syncPolicy: {
+        includeLocalActiveInput: false,
+        graphQualityMode: "strict",
     },
     memoryDecay: {
         enabled: true,
@@ -126,23 +169,50 @@ const defaultConfig = {
             assumption: 240,
         },
     },
+    readTuning: {
+        scoring: {
+            lexicalWeight: 0.2,
+            bm25Scale: 2,
+            semanticWeight: 0.3,
+            recencyWeight: 0.1,
+            qualityWeight: 0.15,
+            typeMatchWeight: 0.15,
+            graphMatchWeight: 0.1,
+        },
+        rrf: {
+            k: 60,
+            weight: 1.5,
+        },
+        recency: {
+            buckets: [
+                { maxAgeHours: 12, score: 1, bonus: 0.6 },
+                { maxAgeHours: 24, score: 0.8, bonus: 0.6 },
+                { maxAgeHours: 72, score: 0.6, bonus: 0.3 },
+                { maxAgeHours: 168, score: 0.4, bonus: 0.3 },
+                { maxAgeHours: 720, score: 0.2, bonus: 0 },
+                { maxAgeHours: Number.POSITIVE_INFINITY, score: 0.05, bonus: 0 },
+            ],
+        },
+        autoContext: {
+            queryMaxChars: 240,
+            lightweightSearch: true,
+        },
+    },
     enabled: true,
-    fallbackToBuiltin: true,
-    engineMode: "ts",
 };
 let autoSearchCacheBySession = new Map();
+const messageHookInFlightBySession = new Map();
 const AUTO_SEARCH_CACHE_TTL = 60000;
 const MAX_AUTO_SEARCH_CACHE_SESSIONS = 200;
 const HOOK_GUARD_TIMEOUT_MS = 2000;
+const SYNC_DEBOUNCE_WINDOW_MS = 120000;
 let config = null;
 let logger;
-let pythonProcess = null;
 let isShuttingDown = false;
 let isInitializing = false;
 let isRegistered = false;
 let isEnabled = false;
 let api = null;
-let builtinMemory = null;
 let registeredTools = [];
 let registeredHooks = [];
 let registeredFallbackTools = [];
@@ -152,16 +222,44 @@ let autoReflectInterval = null;
 let lastAutoReflectArchiveMarker = "";
 let lastAutoReflectRunAt = 0;
 let configPath = null;
-let pythonStartPromise = null;
 let processHandlersRegistered = false;
-let pythonPidFilePath = null;
 let memoryEngine = null;
-function shouldUsePythonRuntime() {
-    return false;
+let builtinMemory = null;
+const TOOL_TRACE_PAYLOAD_MAX_CHARS = 1500;
+function inferOpenClawBasePathForWorkspace() {
+    const explicitConfigPath = (0, runtime_env_1.getEnvValue)("OPENCLAW_CONFIG_PATH").trim();
+    if (explicitConfigPath) {
+        return path.dirname(path.resolve(explicitConfigPath));
+    }
+    const stateDir = (0, runtime_env_1.getEnvValue)("OPENCLAW_STATE_DIR").trim();
+    if (stateDir) {
+        return path.resolve(stateDir);
+    }
+    const basePath = (0, runtime_env_1.getEnvValue)("OPENCLAW_BASE_PATH").trim();
+    if (basePath) {
+        return path.resolve(basePath);
+    }
+    const discoveredConfigPath = findOpenClawConfig();
+    if (discoveredConfigPath) {
+        return path.dirname(path.resolve(discoveredConfigPath));
+    }
+    return null;
+}
+function resolveDefaultMemoryRoot(projectRoot) {
+    const openClawBasePath = inferOpenClawBasePathForWorkspace();
+    if (openClawBasePath) {
+        return path.join(openClawBasePath, "workspace", "memory", PLUGIN_ID);
+    }
+    return path.join(projectRoot, "data", "memory");
+}
+function resolveConfiguredMemoryRoot(configuredDbPath) {
+    if (typeof configuredDbPath === "string" && configuredDbPath.trim()) {
+        return path.resolve(configuredDbPath.trim());
+    }
+    return resolveDefaultMemoryRoot(findProjectRoot());
 }
 function getMemoryRoot() {
-    const projectRoot = findProjectRoot();
-    return config?.dbPath ? path.resolve(config.dbPath) : path.join(projectRoot, "data", "memory");
+    return resolveConfiguredMemoryRoot(config?.dbPath);
 }
 function getArchiveMarker() {
     try {
@@ -219,8 +317,7 @@ function resolveEngine() {
     if (!config) {
         throw new Error("Configuration not loaded");
     }
-    const selectedMode = "ts";
-    if (memoryEngine && memoryEngine.mode === "ts") {
+    if (memoryEngine) {
         return memoryEngine;
     }
     const projectRoot = findProjectRoot();
@@ -234,16 +331,20 @@ function resolveEngine() {
         llm: config.llm,
         fusion: config.readFusion,
         memoryDecay: config.memoryDecay,
+        readTuning: config.readTuning,
+    });
+    const vectorStore = (0, vector_store_1.createVectorStore)({
+        memoryRoot,
+        logger,
     });
     const writeStore = (0, write_store_1.createWriteStore)({
         projectRoot,
         dbPath: config.dbPath,
         logger,
         embedding: config.embedding,
-    });
-    const vectorStore = (0, vector_store_1.createVectorStore)({
-        memoryRoot,
-        logger,
+        vectorChunking: config.vectorChunking,
+        writePolicy: config.writePolicy,
+        vectorStore,
     });
     const deduplicator = (0, three_stage_deduplicator_1.createThreeStageDeduplicator)({
         memoryRoot,
@@ -254,23 +355,61 @@ function resolveEngine() {
         memoryRoot,
         logger,
         embedding: config.embedding,
+        vectorChunking: config.vectorChunking,
+        writePolicy: config.writePolicy,
         deduplicator,
         vectorStore,
     });
+    const graphMemoryStore = (0, graph_memory_store_1.createGraphMemoryStore)({
+        projectRoot,
+        memoryRoot,
+        logger,
+        qualityMode: config.graphQualityMode || "warn",
+        wikiProjection: config.wikiProjection,
+    });
     const sessionSync = (0, session_sync_1.createSessionSync)({
         projectRoot,
         dbPath: config.dbPath,
         logger,
+        llm: config.llm,
+        graphQualityMode: config.graphQualityMode || "warn",
+        requireLlmForWrite: config.llmRequiredForWrite ?? true,
+        writePolicy: config.writePolicy,
+        syncPolicy: config.syncPolicy,
+        archiveStore,
+        graphMemoryStore,
         writeStore,
     });
+    let syncInFlight = null;
+    let lastSyncFinishedAt = 0;
+    const dedupedSyncMemory = async () => {
+        const now = Date.now();
+        if (syncInFlight) {
+            logger.info("sync_memory dedup: join in-flight run");
+            return syncInFlight;
+        }
+        if ((now - lastSyncFinishedAt) < SYNC_DEBOUNCE_WINDOW_MS) {
+            const waitMs = SYNC_DEBOUNCE_WINDOW_MS - (now - lastSyncFinishedAt);
+            logger.info(`sync_memory dedup: skip due to debounce window (${waitMs}ms remaining)`);
+            return { imported: 0, skipped: 0, filesProcessed: 0 };
+        }
+        syncInFlight = sessionSync.syncMemory();
+        try {
+            const result = await syncInFlight;
+            lastSyncFinishedAt = Date.now();
+            return result;
+        }
+        finally {
+            syncInFlight = null;
+        }
+    };
     const sessionEnd = (0, session_end_1.createSessionEnd)({
         projectRoot,
         dbPath: config.dbPath,
         logger,
-        syncMemory: sessionSync.syncMemory,
+        syncMemory: dedupedSyncMemory,
         syncDailySummaries: sessionSync.syncDailySummaries,
-        archiveStore,
-        llm: config.llm,
+        routeTranscript: sessionSync.routeTranscript,
     });
     const ruleStore = (0, rule_store_1.createRuleStore)({
         projectRoot,
@@ -284,15 +423,25 @@ function resolveEngine() {
         ruleStore,
         llm: config.llm,
     });
+    const sessionSyncBridge = {
+        ...sessionSync,
+        syncMemory: dedupedSyncMemory,
+    };
     memoryEngine = (0, ts_engine_1.createTsEngine)({
         readStore,
         writeStore,
+        vectorStore,
         archiveStore,
-        sessionSync,
+        graphMemoryStore,
+        sessionSync: sessionSyncBridge,
         sessionEnd,
         reflector,
         memoryRoot,
         projectRoot,
+        embedding: config.embedding,
+        llm: config.llm,
+        reranker: config.reranker,
+        vectorChunking: config.vectorChunking,
         getCachedAutoSearch: getSessionCachedAutoSearch,
         resolveSessionId: (context, payload) => resolveSessionId(context, payload),
         normalizeIncomingMessage,
@@ -303,6 +452,84 @@ function resolveEngine() {
     });
     return memoryEngine;
 }
+function normalizeToolNameList(input) {
+    if (!input)
+        return [];
+    if (Array.isArray(input)) {
+        const names = input
+            .map((item) => {
+            if (typeof item === "string")
+                return item.trim();
+            if (item && typeof item === "object") {
+                const name = firstString([item.name]);
+                return name || "";
+            }
+            return "";
+        })
+            .filter(Boolean);
+        return [...new Set(names)].sort();
+    }
+    if (typeof input === "object") {
+        return Object.keys(input).sort();
+    }
+    return [];
+}
+async function getApiVisibleToolNames() {
+    if (!api)
+        return [];
+    const apiObj = api;
+    const readers = [];
+    if (typeof apiObj.listTools === "function") {
+        readers.push(() => apiObj.listTools());
+    }
+    if (typeof apiObj.getTools === "function") {
+        readers.push(() => apiObj.getTools());
+    }
+    if (typeof apiObj.tools === "object" && apiObj.tools !== null) {
+        readers.push(() => apiObj.tools);
+    }
+    if (typeof apiObj.registeredTools === "object" && apiObj.registeredTools !== null) {
+        readers.push(() => apiObj.registeredTools);
+    }
+    for (const read of readers) {
+        try {
+            const value = await Promise.resolve(read());
+            const names = normalizeToolNameList(value);
+            if (names.length > 0) {
+                return names;
+            }
+        }
+        catch (error) {
+            logger.debug(`Failed to read visible tools from API: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return [];
+}
+async function withToolVisibilityDiagnostics(result, context) {
+    if (!result.success || !result.data || typeof result.data !== "object" || Array.isArray(result.data)) {
+        return result;
+    }
+    const visible = await getApiVisibleToolNames();
+    const registered = [...registeredTools].sort();
+    const missingFromVisibility = registered.filter((name) => !visible.includes(name));
+    const data = result.data;
+    return {
+        ...result,
+        data: {
+            ...data,
+            tool_visibility: {
+                lane_context: {
+                    agent_id: context?.agentId || "unknown-agent",
+                    session_id: context?.sessionId || null,
+                    workspace_id: context?.workspaceId || "default",
+                },
+                registered_tools: registered,
+                api_visible_tools: visible,
+                missing_from_visible: missingFromVisibility,
+            },
+        },
+    };
+}
 function clearStaleAutoSearchCache(now = Date.now()) {
     for (const [sessionId, cache] of autoSearchCacheBySession.entries()) {
         if ((now - cache.timestamp) >= AUTO_SEARCH_CACHE_TTL) {
@@ -334,30 +561,120 @@ function createConsoleLogger() {
         error: (message, ...args) => console.error(`[CortexMemory] ${message}`, ...args),
     };
 }
+function toTextContent(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+function truncateForLog(value, maxChars = TOOL_TRACE_PAYLOAD_MAX_CHARS) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, maxChars)}...<truncated>`;
+}
+function formatUnknownForLog(value) {
+    if (typeof value === "string") {
+        return truncateForLog(value);
+    }
+    try {
+        return truncateForLog(JSON.stringify(value));
+    }
+    catch {
+        return truncateForLog(String(value));
+    }
+}
+function createToolTraceId(toolName) {
+    return `${toolName}:${Date.now().toString(36)}:${Math.random().toString(36).slice(2, 8)}`;
+}
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function toAgentToolResult(result, traceId) {
+    if (!result.success) {
+        const errorText = result.error || "Tool execution failed";
+        return {
+            content: [{ type: "text", text: errorText }],
+            details: {
+                status: "error",
+                error: errorText,
+                ...(traceId ? { traceId } : {}),
+                ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+            },
+        };
+    }
+    const payloadText = toTextContent(result.data ?? { ok: true });
+    const detailsData = result.data && typeof result.data === "object" && !Array.isArray(result.data)
+        ? result.data
+        : { value: result.data ?? null };
+    return {
+        content: [{ type: "text", text: payloadText }],
+        details: {
+            status: "ok",
+            ...(traceId ? { traceId } : {}),
+            ...detailsData,
+        },
+    };
+}
 function sanitizeForLogging(obj) {
-    const sanitized = {};
+    const result = {};
     for (const [key, value] of Object.entries(obj)) {
-        const isSensitive = SENSITIVE_KEYS.some(k => key.toUpperCase().includes(k));
-        if (isSensitive) {
-            sanitized[key] = "***REDACTED***";
+        if (SENSITIVE_KEYS.some(k => key.toUpperCase().includes(k))) {
+            result[key] = "***REDACTED***";
         }
-        else if (typeof value === "object" && value !== null) {
-            sanitized[key] = sanitizeForLogging(value);
+        else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            result[key] = sanitizeForLogging(value);
         }
         else {
-            sanitized[key] = value;
+            result[key] = value;
         }
     }
-    return sanitized;
+    return result;
 }
-function logLifecycle(event, details = {}) {
-    const payload = sanitizeForLogging({
-        event,
-        plugin: PLUGIN_ID,
-        ts: new Date().toISOString(),
-        ...details,
-    });
-    logger.info(`[Lifecycle] ${JSON.stringify(payload)}`);
+function findProjectRoot() {
+    let dir = __dirname;
+    while (dir !== path.dirname(dir)) {
+        const pkgPath = path.join(dir, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd();
+}
+function resolveSessionId(context, payload) {
+    const contextObj = (context || {});
+    const payloadObj = (payload || {});
+    const candidates = [
+        contextObj.sessionId,
+        contextObj.session_id,
+        payloadObj.sessionId,
+        payloadObj.session_id,
+        payloadObj.id,
+    ];
+    for (const c of candidates) {
+        if (typeof c === "string" && c.trim()) {
+            return c.trim();
+        }
+    }
+    return `fallback:${Date.now().toString(36)}`;
+}
+function normalizeIncomingMessage(payload) {
+    const p = payload;
+    const text = typeof p.text === "string" ? p.text : (typeof p.content === "string" ? p.content : "");
+    if (!text)
+        return null;
+    const role = typeof p.role === "string" ? p.role : "unknown";
+    const source = typeof p.source === "string" ? p.source : "unknown";
+    return { text, role, source };
 }
 function asRecord(value) {
     if (typeof value === "object" && value !== null) {
@@ -366,191 +683,257 @@ function asRecord(value) {
     return null;
 }
 function firstString(values) {
-    for (const value of values) {
-        if (typeof value === "string" && value.trim()) {
-            return value.trim();
+    for (const v of values) {
+        if (typeof v === "string" && v.trim()) {
+            return v.trim();
         }
     }
     return undefined;
 }
-function normalizeIncomingMessage(payload) {
-    const data = asRecord(payload);
-    if (!data) {
-        return null;
+function validateConfig(cfg) {
+    const errors = [];
+    if (!cfg.embedding?.provider) {
+        errors.push("embedding.provider is required.");
     }
-    const message = asRecord(data.message);
-    const eventData = asRecord(data.data);
-    const update = asRecord(data.update);
-    const updateMessage = update ? asRecord(update.message) : null;
-    const role = firstString([
-        data.role,
-        data.fromRole,
-        data.senderRole,
-        message?.role,
-        eventData?.role,
-        updateMessage?.role,
-    ]) || "user";
-    const source = firstString([
-        data.source,
-        data.platform,
-        data.channel,
-        data.provider,
-        message?.source,
-        eventData?.source,
-    ]) || "message";
-    let text = firstString([
-        data.content,
-        data.text,
-        data.body,
-        data.prompt,
-        data.message,
-        message?.content,
-        message?.text,
-        message?.body,
-        eventData?.content,
-        eventData?.text,
-        updateMessage?.text,
-        updateMessage?.caption,
-    ]);
-    if (!text && Array.isArray(data.messages)) {
-        const merged = data.messages
-            .map(item => {
-            if (typeof item === "string")
-                return item;
-            const msgObj = asRecord(item);
-            if (!msgObj)
-                return "";
-            return firstString([msgObj.content, msgObj.text, msgObj.body]) || "";
-        })
-            .filter(Boolean)
-            .join("\n");
-        text = merged.trim() || undefined;
+    if (!cfg.embedding?.model) {
+        errors.push("embedding.model is required.");
     }
-    if (!text) {
-        return null;
+    if (!cfg.llm?.provider) {
+        errors.push("llm.provider is required.");
     }
-    return { text, role, source };
-}
-function resolveSessionId(context, payload) {
-    const fromContext = typeof context.sessionId === "string" ? context.sessionId.trim() : "";
-    if (fromContext)
-        return fromContext;
-    const data = asRecord(payload);
-    const dataChat = data ? asRecord(data.chat) : null;
-    const message = data ? asRecord(data.message) : null;
-    const messageChat = message ? asRecord(message.chat) : null;
-    const eventData = data ? asRecord(data.data) : null;
-    const eventChat = eventData ? asRecord(eventData.chat) : null;
-    const update = data ? asRecord(data.update) : null;
-    const updateMessage = update ? asRecord(update.message) : null;
-    const updateChat = updateMessage ? asRecord(updateMessage.chat) : null;
-    const direct = firstString([
-        data?.sessionId,
-        data?.session_id,
-        data?.conversationId,
-        data?.conversation_id,
-        data?.threadId,
-        data?.thread_id,
-        message?.sessionId,
-        eventData?.sessionId,
-    ]);
-    if (direct)
-        return direct;
-    const chatId = firstString([
-        data?.chatId,
-        data?.chat_id,
-        dataChat?.id,
-        messageChat?.id,
-        eventChat?.id,
-        updateChat?.id,
-    ]);
-    if (chatId)
-        return `chat:${chatId}`;
-    return `fallback:${context.workspaceId || "default"}:${context.agentId || "agent"}`;
-}
-function compareVersions(a, b) {
-    const partsA = a.split(".").map(Number);
-    const partsB = b.split(".").map(Number);
-    for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-        const valA = partsA[i] || 0;
-        const valB = partsB[i] || 0;
-        if (valA < valB)
-            return -1;
-        if (valA > valB)
-            return 1;
-    }
-    return 0;
-}
-async function checkOpenClawVersion() {
-    try {
-        const version = process.env.OPENCLAW_VERSION;
-        if (version) {
-            if (compareVersions(version, MIN_OPENCLAW_VERSION) < 0) {
-                throw new Error(`Incompatible OpenClaw version: ${version}. Minimum required: ${MIN_OPENCLAW_VERSION}`);
+    if (!cfg.llm?.model) {
+        errors.push("llm.model is required.");
+    }
+    if (cfg.autoReflectIntervalMinutes !== undefined) {
+        if (!Number.isFinite(cfg.autoReflectIntervalMinutes) || cfg.autoReflectIntervalMinutes < 5) {
+            errors.push("autoReflectIntervalMinutes must be >= 5.");
+        }
+    }
+    if (cfg.graphQualityMode !== undefined) {
+        if (!["off", "warn", "strict"].includes(cfg.graphQualityMode)) {
+            errors.push("graphQualityMode must be one of: off, warn, strict.");
+        }
+    }
+    if (cfg.wikiProjection?.mode !== undefined) {
+        if (!["off", "incremental", "rebuild"].includes(cfg.wikiProjection.mode)) {
+            errors.push("wikiProjection.mode must be one of: off, incremental, rebuild.");
+        }
+    }
+    if (cfg.wikiProjection?.maxBatch !== undefined) {
+        if (!Number.isFinite(cfg.wikiProjection.maxBatch) || cfg.wikiProjection.maxBatch < 1) {
+            errors.push("wikiProjection.maxBatch must be >= 1.");
+        }
+    }
+    if (cfg.readFusion?.channelWeights) {
+        const weights = cfg.readFusion.channelWeights;
+        for (const [key, value] of Object.entries(weights)) {
+            if (typeof value === "number" && (!Number.isFinite(value) || value < 0)) {
+                errors.push(`readFusion.channelWeights.${key} must be >= 0.`);
             }
-            if (compareVersions(version, MAX_OPENCLAW_VERSION) >= 0) {
-                throw new Error(`Incompatible OpenClaw version: ${version}. Maximum supported: <${MAX_OPENCLAW_VERSION}`);
+        }
+    }
+    if (cfg.readFusion?.channelTopK) {
+        const topK = cfg.readFusion.channelTopK;
+        for (const [key, value] of Object.entries(topK)) {
+            if (typeof value === "number" && (!Number.isFinite(value) || value < 1)) {
+                errors.push(`readFusion.channelTopK.${key} must be >= 1.`);
             }
-            logger.info(`OpenClaw version check passed: ${version}`);
         }
-        else {
-            logger.warn("Could not determine OpenClaw version, proceeding with caution");
+    }
+    if (cfg.vectorChunking?.chunkSize !== undefined) {
+        if (!Number.isFinite(cfg.vectorChunking.chunkSize) || cfg.vectorChunking.chunkSize < 100) {
+            errors.push("vectorChunking.chunkSize must be >= 100.");
+        }
+    }
+    if (cfg.vectorChunking?.chunkOverlap !== undefined) {
+        if (!Number.isFinite(cfg.vectorChunking.chunkOverlap) || cfg.vectorChunking.chunkOverlap < 0) {
+            errors.push("vectorChunking.chunkOverlap must be >= 0.");
         }
     }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        logger.warn(`Version check warning: ${message}`);
+    if (cfg.vectorChunking?.evidenceMaxChunks !== undefined) {
+        if (!Number.isFinite(cfg.vectorChunking.evidenceMaxChunks) || cfg.vectorChunking.evidenceMaxChunks < 0) {
+            errors.push("vectorChunking.evidenceMaxChunks must be >= 0.");
+        }
     }
-}
-function findProjectRoot() {
-    if (api && api.rootDir) {
-        return api.rootDir;
+    if (cfg.writePolicy) {
+        const wp = cfg.writePolicy;
+        const bounded01 = ["archiveMinConfidence", "archiveMinQualityScore", "activeMinQualityScore"];
+        for (const key of bounded01) {
+            const value = wp[key];
+            if (value !== undefined && (!Number.isFinite(value) || value < 0 || value > 1)) {
+                errors.push(`writePolicy.${key} must be between 0 and 1.`);
+            }
+        }
+        if (wp.activeDedupTailLines !== undefined && (!Number.isFinite(wp.activeDedupTailLines) || wp.activeDedupTailLines < 20)) {
+            errors.push("writePolicy.activeDedupTailLines must be >= 20.");
+        }
+        if (wp.activeTextMaxChars !== undefined && (!Number.isFinite(wp.activeTextMaxChars) || wp.activeTextMaxChars < 500)) {
+            errors.push("writePolicy.activeTextMaxChars must be >= 500.");
+        }
+        if (wp.archiveSourceTextMaxChars !== undefined && (!Number.isFinite(wp.archiveSourceTextMaxChars) || wp.archiveSourceTextMaxChars < 1000)) {
+            errors.push("writePolicy.archiveSourceTextMaxChars must be >= 1000.");
+        }
+    }
+    if (cfg.syncPolicy) {
+        if (cfg.syncPolicy.includeLocalActiveInput !== undefined && typeof cfg.syncPolicy.includeLocalActiveInput !== "boolean") {
+            errors.push("syncPolicy.includeLocalActiveInput must be boolean.");
+        }
+        if (cfg.syncPolicy.graphQualityMode !== undefined && !["off", "warn", "strict"].includes(cfg.syncPolicy.graphQualityMode)) {
+            errors.push("syncPolicy.graphQualityMode must be one of: off, warn, strict.");
+        }
+    }
+    if (cfg.memoryDecay) {
+        if (typeof cfg.memoryDecay.minFloor === "number" && (!Number.isFinite(cfg.memoryDecay.minFloor) || cfg.memoryDecay.minFloor < 0 || cfg.memoryDecay.minFloor > 1)) {
+            errors.push("memoryDecay.minFloor must be between 0 and 1.");
+        }
+        if (typeof cfg.memoryDecay.defaultHalfLifeDays === "number" && (!Number.isFinite(cfg.memoryDecay.defaultHalfLifeDays) || cfg.memoryDecay.defaultHalfLifeDays <= 0)) {
+            errors.push("memoryDecay.defaultHalfLifeDays must be > 0.");
+        }
+        if (cfg.memoryDecay.antiDecay) {
+            const anti = cfg.memoryDecay.antiDecay;
+            if (typeof anti.maxBoost === "number" && (!Number.isFinite(anti.maxBoost) || anti.maxBoost < 1)) {
+                errors.push("memoryDecay.antiDecay.maxBoost must be >= 1.");
+            }
+            if (typeof anti.hitWeight === "number" && (!Number.isFinite(anti.hitWeight) || anti.hitWeight < 0)) {
+                errors.push("memoryDecay.antiDecay.hitWeight must be >= 0.");
+            }
+            if (typeof anti.recentWindowDays === "number" && (!Number.isFinite(anti.recentWindowDays) || anti.recentWindowDays <= 0)) {
+                errors.push("memoryDecay.antiDecay.recentWindowDays must be > 0.");
+            }
+        }
     }
-    let current = process.cwd();
-    while (current !== path.dirname(current)) {
-        if (fs.existsSync(path.join(current, "openclaw.plugin.json")) &&
-            fs.existsSync(path.join(current, "package.json"))) {
-            return current;
+    if (cfg.readTuning) {
+        const numericReadTuningFields = [
+            ["readTuning.scoring.lexicalWeight", cfg.readTuning.scoring?.lexicalWeight, 0],
+            ["readTuning.scoring.bm25Scale", cfg.readTuning.scoring?.bm25Scale, 0],
+            ["readTuning.scoring.semanticWeight", cfg.readTuning.scoring?.semanticWeight, 0],
+            ["readTuning.scoring.recencyWeight", cfg.readTuning.scoring?.recencyWeight, 0],
+            ["readTuning.scoring.qualityWeight", cfg.readTuning.scoring?.qualityWeight, 0],
+            ["readTuning.scoring.typeMatchWeight", cfg.readTuning.scoring?.typeMatchWeight, 0],
+            ["readTuning.scoring.graphMatchWeight", cfg.readTuning.scoring?.graphMatchWeight, 0],
+            ["readTuning.rrf.k", cfg.readTuning.rrf?.k, 1],
+            ["readTuning.rrf.weight", cfg.readTuning.rrf?.weight, 0],
+            ["readTuning.autoContext.queryMaxChars", cfg.readTuning.autoContext?.queryMaxChars, 20],
+        ];
+        for (const [name, value, min] of numericReadTuningFields) {
+            if (typeof value === "number" && (!Number.isFinite(value) || value < min)) {
+                errors.push(`${name} must be >= ${min}.`);
+            }
+        }
+        if (Array.isArray(cfg.readTuning.recency?.buckets)) {
+            const buckets = cfg.readTuning.recency.buckets;
+            for (let i = 0; i < buckets.length; i += 1) {
+                const bucket = buckets[i];
+                const maxAgeHours = bucket.maxAgeHours;
+                const finiteOrInfinity = Number.isFinite(maxAgeHours) || maxAgeHours === Number.POSITIVE_INFINITY;
+                if (!finiteOrInfinity || maxAgeHours <= 0) {
+                    errors.push(`readTuning.recency.buckets[${i}].maxAgeHours must be > 0.`);
+                }
+                if (!Number.isFinite(bucket.score) || bucket.score < 0) {
+                    errors.push(`readTuning.recency.buckets[${i}].score must be >= 0.`);
+                }
+                if (!Number.isFinite(bucket.bonus) || bucket.bonus < 0) {
+                    errors.push(`readTuning.recency.buckets[${i}].bonus must be >= 0.`);
+                }
+            }
         }
-        current = path.dirname(current);
     }
-    throw new Error("Cannot find project root directory");
+    return errors;
+}
+function checkOpenClawVersion() {
+    return new Promise((resolve) => {
+        try {
+            const apiObj = api;
+            const candidates = [
+                { source: "api.openclawVersion", value: apiObj?.openclawVersion },
+                { source: "api.gatewayVersion", value: apiObj?.gatewayVersion },
+                { source: "api.coreVersion", value: apiObj?.coreVersion },
+                { source: "api.openclaw.version", value: apiObj?.openclaw?.version },
+            ].filter((item) => typeof item.value === "string" && item.value.trim().length > 0);
+            const selected = candidates.find((item) => {
+                const value = item.value;
+                const major = Number(value.replace(/[^0-9.]/g, "").split(".")[0] || "0");
+                // OpenClaw release versions are calendar-like (e.g. 2026.x.x),
+                // while plugin/package versions like 0.x should be ignored.
+                return Number.isFinite(major) && major >= 2000;
+            });
+            const version = selected?.value || "";
+            if (!version) {
+                logger.debug("Could not determine OpenClaw gateway/core version from API fields; skip compatibility check");
+                resolve();
+                return;
+            }
+            const parseVersion = (v) => {
+                const parts = v.replace(/[^0-9.]/g, "").split(".").map(Number);
+                return parts.length >= 3 ? parts : [...parts, ...Array(3 - parts.length).fill(0)];
+            };
+            const current = parseVersion(version);
+            const min = parseVersion(MIN_OPENCLAW_GATEWAY_VERSION);
+            const max = parseVersion(MAX_OPENCLAW_GATEWAY_VERSION);
+            const currentNum = current[0] * 10000 + current[1] * 100 + current[2];
+            const minNum = min[0] * 10000 + min[1] * 100 + min[2];
+            const maxNum = max[0] * 10000 + max[1] * 100 + max[2];
+            if (currentNum < minNum) {
+                logger.warn(`OpenClaw gateway/core version ${version} (from ${selected?.source || "unknown"}) is below minimum ${MIN_OPENCLAW_GATEWAY_VERSION}. Some features may not work.`);
+            }
+            else if (currentNum >= maxNum) {
+                logger.warn(`OpenClaw gateway/core version ${version} (from ${selected?.source || "unknown"}) may not be fully compatible. Maximum tested version is ${MAX_OPENCLAW_GATEWAY_VERSION}.`);
+            }
+        }
+        catch (e) {
+            logger.warn(`Version check failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        resolve();
+    });
 }
 function findOpenClawConfig() {
-    const explicitConfigPath = process.env.OPENCLAW_CONFIG_PATH || "";
-    const stateDir = process.env.OPENCLAW_STATE_DIR || "";
-    const basePath = process.env.OPENCLAW_BASE_PATH || "";
-    const homePath = process.env.USERPROFILE || process.env.HOME || "";
-    const possiblePaths = [
-        explicitConfigPath,
-        stateDir ? path.join(stateDir, "openclaw.json") : "",
-        basePath ? path.join(basePath, "openclaw.json") : "",
-        path.join(process.cwd(), "openclaw.json"),
-        homePath ? path.join(homePath, ".openclaw", "openclaw.json") : "",
+    const explicitPath = (0, runtime_env_1.getEnvValue)("OPENCLAW_CONFIG_PATH");
+    if (explicitPath && fs.existsSync(explicitPath)) {
+        return explicitPath;
+    }
+    const stateDir = (0, runtime_env_1.getEnvValue)("OPENCLAW_STATE_DIR");
+    if (stateDir) {
+        const stateConfig = path.join(stateDir, "openclaw.json");
+        if (fs.existsSync(stateConfig)) {
+            return stateConfig;
+        }
+    }
+    const basePath = (0, runtime_env_1.getEnvValue)("OPENCLAW_BASE_PATH");
+    if (basePath) {
+        const baseConfig = path.join(basePath, "openclaw.json");
+        if (fs.existsSync(baseConfig)) {
+            return baseConfig;
+        }
+    }
+    const home = (0, runtime_env_1.getHomeDir)();
+    const candidates = [
+        path.join(home, ".openclaw", "openclaw.json"),
+        path.join(home, ".openclaw", "config.json"),
     ];
-    for (const p of possiblePaths) {
-        if (p && fs.existsSync(p)) {
-            return p;
+    for (const c of candidates) {
+        if (fs.existsSync(c)) {
+            return c;
         }
     }
     return null;
 }
 function loadPluginEnabledState() {
-    if (!configPath || !fs.existsSync(configPath)) {
-        return true;
-    }
     try {
-        const content = fs.readFileSync(configPath, "utf-8");
-        const openclawConfig = JSON.parse(content);
-        const pluginEntry = openclawConfig?.plugins?.entries?.[PLUGIN_ID];
-        if (pluginEntry && typeof pluginEntry === "object") {
-            return pluginEntry.enabled !== false;
+        if (!configPath)
+            return true;
+        const raw = fs.readFileSync(configPath, "utf-8");
+        const cfg = JSON.parse(raw);
+        const entry = cfg?.plugins?.entries?.[PLUGIN_ID];
+        if (entry && typeof entry.enabled === "boolean") {
+            return entry.enabled;
+        }
+        const allow = cfg?.plugins?.allow;
+        if (Array.isArray(allow)) {
+            return allow.includes(PLUGIN_ID);
         }
-        const legacyPluginConfig = openclawConfig?.plugins?.["cortex-memory"];
-        return legacyPluginConfig?.enabled !== false;
+        return true;
     }
-    catch (e) {
-        logger.warn(`Failed to load config state: ${e}`);
+    catch {
         return true;
     }
 }
@@ -558,20 +941,24 @@ function startConfigWatcher() {
     if (configWatchInterval) {
         clearInterval(configWatchInterval);
     }
-    let lastEnabledState = isEnabled;
     configWatchInterval = setInterval(() => {
-        const newState = loadPluginEnabledState();
-        if (newState !== lastEnabledState) {
-            lastEnabledState = newState;
-            if (newState && !isEnabled) {
-                logger.info("Detected config change: enabling Cortex Memory plugin");
-                enable();
-            }
-            else if (!newState && isEnabled) {
-                logger.info("Detected config change: disabling Cortex Memory plugin");
-                disable();
+        try {
+            if (!configPath || !fs.existsSync(configPath))
+                return;
+            const currentEnabled = loadPluginEnabledState();
+            if (currentEnabled !== isEnabled) {
+                logger.info(`Plugin enabled state changed from ${isEnabled} to ${currentEnabled}`);
+                if (currentEnabled) {
+                    enable().catch(e => logger.error(`Failed to enable: ${e}`));
+                }
+                else {
+                    disable().catch(e => logger.error(`Failed to disable: ${e}`));
+                }
             }
         }
+        catch (e) {
+            logger.debug(`Config watch error: ${e}`);
+        }
     }, 5000);
 }
 function stopConfigWatcher() {
@@ -581,43 +968,36 @@ function stopConfigWatcher() {
     }
 }
 function startAutoReflectScheduler() {
-    if (!config?.autoReflect || autoReflectInterval) {
+    if (!config?.autoReflect) {
         return;
     }
-    const intervalMinutes = Math.max(5, Math.floor(config.autoReflectIntervalMinutes ?? 30));
-    const intervalMs = intervalMinutes * 60 * 1000;
-    autoReflectInterval = setInterval(() => {
-        if (!isEnabled) {
-            return;
-        }
-        const schedulerContext = {
-            agentId: "cortex-memory-scheduler",
-            workspaceId: "system",
-        };
-        const marker = getArchiveMarker();
-        const now = Date.now();
-        if (marker === "missing" || marker === "error") {
-            return;
-        }
-        if (marker === lastAutoReflectArchiveMarker) {
-            return;
-        }
-        if (now - lastAutoReflectRunAt < intervalMs) {
+    const intervalMinutes = Math.max(5, config.autoReflectIntervalMinutes ?? 30);
+    if (autoReflectInterval) {
+        clearInterval(autoReflectInterval);
+    }
+    lastAutoReflectArchiveMarker = getArchiveMarker();
+    lastAutoReflectRunAt = Date.now();
+    autoReflectInterval = setInterval(async () => {
+        if (!isEnabled)
             return;
-        }
-        resolveEngine().reflectMemory({}, schedulerContext)
-            .then(result => {
-            if (result.success) {
-                lastAutoReflectArchiveMarker = marker;
-                lastAutoReflectRunAt = now;
-                logger.info("Scheduled reflection complete");
+        const currentMarker = getArchiveMarker();
+        if (currentMarker !== lastAutoReflectArchiveMarker) {
+            lastAutoReflectArchiveMarker = currentMarker;
+            try {
+                const result = await resolveEngine().reflectMemory({}, { agentId: "scheduler", workspaceId: "default" });
+                if (result.success) {
+                    logger.info("Auto-reflect completed successfully");
+                }
+                else {
+                    logger.warn(`Auto-reflect failed: ${result.error}`);
+                }
             }
-            else {
-                logger.warn(`Auto-reflect failed: ${result.error ?? "unknown_error"}`);
+            catch (e) {
+                logger.error(`Auto-reflect error: ${e instanceof Error ? e.message : String(e)}`);
             }
-        })
-            .catch(error => logger.warn(`Auto-reflect failed: ${String(error)}`));
-    }, intervalMs);
+        }
+    }, intervalMinutes * 60 * 1000);
+    logger.info(`Auto-reflect scheduler started (interval: ${intervalMinutes} minutes)`);
 }
 function stopAutoReflectScheduler() {
     if (autoReflectInterval) {
@@ -625,907 +1005,32 @@ function stopAutoReflectScheduler() {
         autoReflectInterval = null;
     }
 }
-function validateConfig(cfg) {
-    const errors = [];
-    if (!cfg.embedding?.provider || !cfg.embedding?.model) {
-        errors.push("embedding.provider and embedding.model are required. Please configure them in openclaw.json");
+function logLifecycle(event, data) {
+    logger.info(`[Lifecycle] ${event}${data ? `: ${JSON.stringify(sanitizeForLogging(data))}` : ""}`);
+}
+async function onMessageHandler(payload, context) {
+    const sessionId = resolveSessionId(context, payload);
+    if (isInternalSession(sessionId)) {
+        return;
     }
-    if (!cfg.embedding?.apiKey || !cfg.embedding?.baseURL) {
-        errors.push("embedding.apiKey and embedding.baseURL are required. Please configure third-party embedding endpoint credentials.");
+    const existing = messageHookInFlightBySession.get(sessionId);
+    if (existing) {
+        logger.debug(`onMessage hook dedup: skip while previous run is in-flight session=${sessionId}`);
+        return;
     }
-    if (typeof cfg.embedding?.timeoutMs === "number" && (!Number.isFinite(cfg.embedding.timeoutMs) || cfg.embedding.timeoutMs < 1000)) {
-        errors.push("embedding.timeoutMs must be a number >= 1000.");
-    }
-    if (typeof cfg.embedding?.maxRetries === "number" && (!Number.isFinite(cfg.embedding.maxRetries) || cfg.embedding.maxRetries < 1 || cfg.embedding.maxRetries > 8)) {
-        errors.push("embedding.maxRetries must be between 1 and 8.");
-    }
-    if (!cfg.llm?.provider || !cfg.llm?.model) {
-        errors.push("llm.provider and llm.model are required. Please configure them in openclaw.json");
-    }
-    if (!cfg.llm?.apiKey || !cfg.llm?.baseURL) {
-        errors.push("llm.apiKey and llm.baseURL are required. Please configure third-party LLM endpoint credentials.");
-    }
-    if (!cfg.reranker?.model) {
-        errors.push("reranker.model is required. Please configure it in openclaw.json");
-    }
-    if (!cfg.reranker?.apiKey || !cfg.reranker?.baseURL) {
-        errors.push("reranker.apiKey and reranker.baseURL are required. Please configure third-party reranker endpoint credentials.");
-    }
-    if (typeof cfg.autoReflectIntervalMinutes === "number" && (!Number.isFinite(cfg.autoReflectIntervalMinutes) || cfg.autoReflectIntervalMinutes < 5)) {
-        errors.push("autoReflectIntervalMinutes must be a number >= 5.");
-    }
-    if (cfg.readFusion && typeof cfg.readFusion.maxCandidates === "number" && (!Number.isFinite(cfg.readFusion.maxCandidates) || cfg.readFusion.maxCandidates < 2)) {
-        errors.push("readFusion.maxCandidates must be a number >= 2.");
-    }
-    if (cfg.memoryDecay) {
-        if (typeof cfg.memoryDecay.minFloor === "number" && (!Number.isFinite(cfg.memoryDecay.minFloor) || cfg.memoryDecay.minFloor < 0 || cfg.memoryDecay.minFloor > 1)) {
-            errors.push("memoryDecay.minFloor must be within [0,1].");
-        }
-        if (typeof cfg.memoryDecay.defaultHalfLifeDays === "number" && (!Number.isFinite(cfg.memoryDecay.defaultHalfLifeDays) || cfg.memoryDecay.defaultHalfLifeDays <= 0)) {
-            errors.push("memoryDecay.defaultHalfLifeDays must be > 0.");
-        }
-        const mapping = cfg.memoryDecay.halfLifeByEventType;
-        if (mapping && typeof mapping === "object") {
-            for (const [key, value] of Object.entries(mapping)) {
-                if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
-                    errors.push(`memoryDecay.halfLifeByEventType.${key} must be > 0.`);
-                    break;
-                }
-            }
-        }
-        const anti = cfg.memoryDecay.antiDecay;
-        if (anti) {
-            if (typeof anti.maxBoost === "number" && (!Number.isFinite(anti.maxBoost) || anti.maxBoost < 1)) {
-                errors.push("memoryDecay.antiDecay.maxBoost must be >= 1.");
-            }
-            if (typeof anti.hitWeight === "number" && (!Number.isFinite(anti.hitWeight) || anti.hitWeight < 0)) {
-                errors.push("memoryDecay.antiDecay.hitWeight must be >= 0.");
-            }
-            if (typeof anti.recentWindowDays === "number" && (!Number.isFinite(anti.recentWindowDays) || anti.recentWindowDays <= 0)) {
-                errors.push("memoryDecay.antiDecay.recentWindowDays must be > 0.");
-            }
-        }
-    }
-    return errors;
-}
-function getApiHostAndPort() {
-    const parsed = new URL(getBaseUrl());
-    const host = parsed.hostname || "127.0.0.1";
-    const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
-    return { host, port };
-}
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-function isPortListening(host, port, timeoutMs = 700) {
-    return new Promise(resolve => {
-        const socket = new net.Socket();
-        let settled = false;
-        const finalize = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            resolve(value);
-        };
-        socket.setTimeout(timeoutMs);
-        socket.once("connect", () => finalize(true));
-        socket.once("timeout", () => finalize(false));
-        socket.once("error", () => finalize(false));
-        socket.connect(port, host);
-    });
-}
-function writePythonPid(pid) {
-    if (!pythonPidFilePath)
-        return;
-    try {
-        fs.writeFileSync(pythonPidFilePath, String(pid), "utf-8");
-    }
-    catch (e) {
-        logger.warn(`Failed to write Python pid file: ${e instanceof Error ? e.message : String(e)}`);
-    }
-}
-function clearPythonPidFile() {
-    if (!pythonPidFilePath)
-        return;
-    try {
-        if (fs.existsSync(pythonPidFilePath)) {
-            fs.unlinkSync(pythonPidFilePath);
-        }
-    }
-    catch (e) {
-        logger.warn(`Failed to clear Python pid file: ${e instanceof Error ? e.message : String(e)}`);
-    }
-}
-function readPythonPid() {
-    if (!pythonPidFilePath || !fs.existsSync(pythonPidFilePath))
-        return null;
-    try {
-        const raw = fs.readFileSync(pythonPidFilePath, "utf-8").trim();
-        const pid = Number(raw);
-        return Number.isInteger(pid) && pid > 0 ? pid : null;
-    }
-    catch {
-        return null;
-    }
-}
-function killProcessByPid(pid) {
-    if (!pid)
-        return;
-    try {
-        if (process.platform === "win32") {
-            (0, child_process_1.execSync)(`taskkill /pid ${pid} /f /t`, { stdio: "ignore" });
-            return;
-        }
-        try {
-            process.kill(pid, "SIGTERM");
-        }
-        catch { }
-        try {
-            process.kill(-pid, "SIGTERM");
-        }
-        catch { }
-        setTimeout(() => {
-            try {
-                process.kill(pid, "SIGKILL");
-            }
-            catch { }
-            try {
-                process.kill(-pid, "SIGKILL");
-            }
-            catch { }
-        }, 2000);
-    }
-    catch (e) {
-        logger.warn(`Failed to kill process ${pid}: ${e instanceof Error ? e.message : String(e)}`);
-    }
-}
-function freePortWithSystemTools(port) {
-    try {
-        if (process.platform === "win32") {
-            const output = (0, child_process_1.execSync)(`netstat -ano | findstr :${port}`, { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] });
-            const pids = output
-                .split(/\r?\n/)
-                .filter(line => line.includes("LISTENING"))
-                .map(line => {
-                const parts = line.trim().split(/\s+/);
-                return Number(parts[parts.length - 1]);
-            })
-                .filter(pid => Number.isInteger(pid) && pid > 0);
-            for (const pid of pids) {
-                killProcessByPid(pid);
-            }
-            return;
-        }
-        const output = (0, child_process_1.execSync)(`sh -lc "lsof -ti tcp:${port} 2>/dev/null || true"`, { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] });
-        const pids = output
-            .split(/\r?\n/)
-            .map(line => Number(line.trim()))
-            .filter(pid => Number.isInteger(pid) && pid > 0);
-        for (const pid of pids) {
-            killProcessByPid(pid);
-        }
-    }
-    catch {
-        // ignore
-    }
-}
-async function checkPortInUse() {
-    const apiUrl = getBaseUrl();
-    try {
-        const response = await fetch(`${apiUrl}/health`, { signal: AbortSignal.timeout(1000) });
-        return response.ok;
-    }
-    catch {
-        return false;
-    }
-}
-async function startPythonService() {
-    if (pythonStartPromise) {
-        return pythonStartPromise;
-    }
-    pythonStartPromise = startPythonServiceInternal().finally(() => {
-        pythonStartPromise = null;
-    });
-    return pythonStartPromise;
-}
-async function startPythonServiceInternal() {
-    if (!config) {
-        throw new Error("Configuration not loaded");
-    }
-    const projectRoot = findProjectRoot();
-    pythonPidFilePath = path.join(projectRoot, ".cortex-memory-python.pid");
-    const { host, port } = getApiHostAndPort();
-    const stalePid = readPythonPid();
-    if (stalePid && (!pythonProcess || pythonProcess.pid !== stalePid)) {
-        logger.info(`Found stale Python pid ${stalePid}, trying to stop it...`);
-        killProcessByPid(stalePid);
-        await sleep(800);
-        clearPythonPidFile();
-    }
-    const healthyRunning = await checkPortInUse();
-    if (healthyRunning) {
-        logger.info("Python service already running, shutting down old instance...");
-        await shutdownPythonApi();
-        await sleep(1000);
-    }
-    const occupied = await isPortListening(host, port);
-    if (occupied) {
-        logger.warn(`Port ${port} is still occupied after graceful shutdown, forcing cleanup...`);
-        freePortWithSystemTools(port);
-        await sleep(1000);
-    }
-    if (await isPortListening(host, port)) {
-        throw new Error(`Port ${port} is already in use by another process. Please stop that process and retry.`);
-    }
-    const venvDir = path.join(projectRoot, "venv");
-    const pythonCmd = process.platform === "win32"
-        ? path.join(venvDir, "Scripts", "python.exe")
-        : path.join(venvDir, "bin", "python");
-    if (!fs.existsSync(pythonCmd)) {
-        throw new Error("Python environment not found. Please run 'npm install' first.");
-    }
-    const errors = validateConfig(config);
-    if (errors.length > 0) {
-        throw new Error(`Configuration errors:\n${errors.join("\n")}`);
-    }
-    logger.info("Starting Cortex Memory Python service...");
-    const env = {
-        ...process.env,
-        CORTEX_MEMORY_EMBEDDING_PROVIDER: config.embedding.provider,
-        CORTEX_MEMORY_EMBEDDING_MODEL: config.embedding.model,
-        CORTEX_MEMORY_LLM_PROVIDER: config.llm.provider,
-        CORTEX_MEMORY_LLM_MODEL: config.llm.model,
-        CORTEX_MEMORY_RERANKER_PROVIDER: config.reranker.provider || "",
-        CORTEX_MEMORY_RERANKER_MODEL: config.reranker.model,
-        CORTEX_MEMORY_DB_PATH: config.dbPath || path.join(process.env.USERPROFILE || process.env.HOME || "", ".openclaw", "agents", "main", "lancedb_store"),
-    };
-    if (config.embedding.apiKey) {
-        env.CORTEX_MEMORY_EMBEDDING_API_KEY = config.embedding.apiKey;
-    }
-    if (config.embedding.baseURL) {
-        env.CORTEX_MEMORY_EMBEDDING_BASE_URL = config.embedding.baseURL;
-    }
-    if (config.embedding.dimensions) {
-        env.CORTEX_MEMORY_EMBEDDING_DIMENSIONS = String(config.embedding.dimensions);
-    }
-    if (config.llm.apiKey) {
-        env.CORTEX_MEMORY_LLM_API_KEY = config.llm.apiKey;
-    }
-    if (config.llm.baseURL) {
-        env.CORTEX_MEMORY_LLM_BASE_URL = config.llm.baseURL;
-    }
-    if (config.reranker.apiKey) {
-        env.CORTEX_MEMORY_RERANKER_API_KEY = config.reranker.apiKey;
-    }
-    if (config.reranker.baseURL) {
-        env.CORTEX_MEMORY_RERANKER_ENDPOINT = config.reranker.baseURL;
-    }
-    return new Promise((resolve, reject) => {
-        pythonProcess = (0, child_process_1.spawn)(pythonCmd, ["-m", "api.server"], {
-            cwd: projectRoot,
-            detached: false,
-            windowsHide: true,
-            env: { ...env, PYTHONWARNINGS: "ignore::RuntimeWarning" },
-        });
-        if (pythonProcess.pid) {
-            writePythonPid(pythonProcess.pid);
-        }
-        let started = false;
-        let stderrBuffer = "";
-        let settled = false;
-        let startupTimeout = null;
-        const resolveOnce = () => {
-            if (settled)
-                return;
-            settled = true;
-            started = true;
-            if (startupTimeout) {
-                clearTimeout(startupTimeout);
-                startupTimeout = null;
-            }
-            resolve();
-        };
-        const rejectOnce = (error) => {
-            if (settled)
-                return;
-            settled = true;
-            if (startupTimeout) {
-                clearTimeout(startupTimeout);
-                startupTimeout = null;
-            }
-            reject(error);
-        };
-        pythonProcess.stdout?.on("data", (data) => {
-            const output = data.toString();
-            if (!output.toLowerCase().includes("key") && !output.toLowerCase().includes("token")) {
-                logger.info(`[Python] ${output.trim()}`);
-            }
-            if (output.includes("Cortex Memory API started") || output.includes("Application startup complete")) {
-                resolveOnce();
-            }
-        });
-        pythonProcess.stderr?.on("data", (data) => {
-            const output = data.toString();
-            stderrBuffer += output;
-            if (!output.toLowerCase().includes("key") && !output.toLowerCase().includes("token")) {
-                logger.warn(`[Python] ${output.trim()}`);
-            }
-            if (output.includes("Cortex Memory API started") ||
-                output.includes("Application startup complete") ||
-                output.includes("Uvicorn running on")) {
-                resolveOnce();
-            }
-        });
-        pythonProcess.on("error", (error) => {
-            logger.error("Failed to start Python service:", error.message);
-            rejectOnce(error);
-        });
-        pythonProcess.on("exit", (code) => {
-            clearPythonPidFile();
-            pythonProcess = null;
-            if (!started && code !== 0 && !isShuttingDown) {
-                rejectOnce(new Error(`Python service exited with code ${code}. Stderr: ${stderrBuffer.slice(-500)}`));
-            }
-        });
-        startupTimeout = setTimeout(() => {
-            if (!started) {
-                const tail = stderrBuffer ? `\nLast stderr: ${stderrBuffer.slice(-500)}` : "";
-                killPythonProcess();
-                rejectOnce(new Error(`Timeout waiting for Python service to start (300s)${tail}`));
-            }
-        }, 300000);
-    });
-}
-async function shutdownPythonApi() {
-    const apiUrl = getBaseUrl();
-    try {
-        await fetch(`${apiUrl}/shutdown`, { method: "POST", signal: AbortSignal.timeout(2000) });
-        await new Promise(resolve => setTimeout(resolve, 500));
-    }
-    catch {
-        // ignore
-    }
-}
-function killPythonProcess() {
-    const directPid = pythonProcess?.pid ?? null;
-    const pidFromFile = readPythonPid();
-    const pid = directPid || pidFromFile;
-    if (!pid)
-        return;
-    try {
-        killProcessByPid(pid);
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        logger.warn(`Failed to kill Python process: ${message}`);
-    }
-    finally {
-        pythonProcess = null;
-        clearPythonPidFile();
-    }
-}
-async function stopPythonServiceAsync() {
-    if (pythonStartPromise) {
-        try {
-            await pythonStartPromise;
-        }
-        catch {
-            // ignore
-        }
-    }
-    await shutdownPythonApi();
-    killPythonProcess();
-}
-function stopPythonService() {
-    stopPythonServiceAsync();
-}
-function getBaseUrl() {
-    return config?.apiUrl ?? "http://localhost:8765";
-}
-async function waitForService(maxAttempts = 30) {
-    const apiUrl = getBaseUrl();
-    for (let i = 0; i < maxAttempts; i++) {
-        try {
-            const response = await fetch(`${apiUrl}/health`, { signal: AbortSignal.timeout(1000) });
-            if (response.ok)
-                return;
-        }
-        catch { }
-        await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-    throw new Error("Service failed to become ready");
-}
-function formatApiError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const lower = message.toLowerCase();
-    if (lower.includes("econnrefused") || lower.includes("enotfound") || lower.includes("fetch failed")) {
-        const err = ERROR_CODES.CONNECTION_REFUSED;
-        return `${err.message} (${err.code}). ${err.suggestion}`;
-    }
-    if (lower.includes("abort") || lower.includes("timed out")) {
-        const err = ERROR_CODES.TIMEOUT;
-        return `${err.message} (${err.code}). ${err.suggestion}`;
-    }
-    if (lower.includes("404") || lower.includes("not found")) {
-        const err = ERROR_CODES.NOT_FOUND;
-        return `${err.message} (${err.code}). ${err.suggestion}`;
-    }
-    if (lower.includes("400") || lower.includes("invalid")) {
-        const err = ERROR_CODES.INVALID_INPUT;
-        return `${err.message} (${err.code}). ${err.suggestion}`;
-    }
-    const err = ERROR_CODES.SERVICE_ERROR;
-    return `${err.message} (${err.code}). Details: ${message}`;
-}
-const pendingRequests = new Map();
-const requestDebounceMs = 100;
-function getRequestKey(endpoint, method, body) {
-    const bodyHash = body ? JSON.stringify(body).slice(0, 100) : "";
-    return `${method}:${endpoint}:${bodyHash}`;
-}
-async function apiCallWithRetry(endpoint, method = "GET", body, options) {
-    const { maxRetries = 3, baseDelay = 1000, timeout = 30000, skipDebounce = false } = options || {};
-    if (!skipDebounce) {
-        const requestKey = getRequestKey(endpoint, method, body);
-        const pending = pendingRequests.get(requestKey);
-        if (pending) {
-            logger.debug(`Reusing pending request for ${endpoint}`);
-            return pending.promise;
-        }
-        const requestPromise = apiCallInternal(endpoint, method, body, maxRetries, baseDelay, timeout)
-            .finally(() => {
-            setTimeout(() => pendingRequests.delete(requestKey), requestDebounceMs);
-        });
-        pendingRequests.set(requestKey, {
-            promise: requestPromise
-        });
-        return await requestPromise;
-    }
-    return apiCallInternal(endpoint, method, body, maxRetries, baseDelay, timeout);
-}
-async function apiCallInternal(endpoint, method, body, maxRetries, baseDelay, timeout) {
-    let lastError = null;
-    for (let attempt = 0; attempt < maxRetries; attempt++) {
-        try {
-            return await apiCall(endpoint, method, body, timeout);
-        }
-        catch (error) {
-            lastError = error instanceof Error ? error : new Error(String(error));
-            const isRetryable = lastError.message.includes("E001") ||
-                lastError.message.includes("E002") ||
-                lastError.message.includes("timeout") ||
-                lastError.message.includes("ECONNREFUSED") ||
-                lastError.message.includes("ENOTFOUND");
-            if (attempt < maxRetries - 1 && isRetryable) {
-                const delay = baseDelay * Math.pow(2, attempt);
-                logger.warn(`API call failed (attempt ${attempt + 1}/${maxRetries}), retrying in ${delay}ms: ${lastError.message.split(".")[0]}`);
-                await new Promise(resolve => setTimeout(resolve, delay));
-            }
-        }
-    }
-    throw lastError;
-}
-async function apiCall(endpoint, method = "GET", body, timeout = 30000) {
-    const url = `${getBaseUrl()}${endpoint}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    const options = {
-        method,
-        headers: { "Content-Type": "application/json" },
-        signal: controller.signal,
-    };
-    if (body)
-        options.body = JSON.stringify(body);
-    try {
-        const response = await fetch(url, options);
-        const text = await response.text();
-        if (!response.ok) {
-            try {
-                const errorData = JSON.parse(text);
-                throw new Error(errorData.error || errorData.detail || `HTTP ${response.status}`);
-            }
-            catch {
-                throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
-            }
-        }
-        if (!text)
-            return {};
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            throw new Error("Invalid JSON response");
-        }
-    }
-    catch (error) {
-        throw new Error(formatApiError(error));
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
-async function searchMemoryWithFallback(args, context) {
-    if (!args || !args.query) {
-        logger.error(`search_memory called with invalid args: ${JSON.stringify(args)}`);
-        return { success: false, error: ERROR_CODES.INVALID_INPUT.message + " Missing 'query' parameter.", errorCode: ERROR_CODES.INVALID_INPUT.code };
-    }
-    if (!isEnabled) {
-        if (config?.fallbackToBuiltin && builtinMemory) {
-            logger.info("Using builtin memory (plugin disabled)");
-            try {
-                const results = await builtinMemory.search(args.query, args.top_k || 3);
-                return { success: true, data: results };
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return { success: false, error: `Builtin memory error: ${message}` };
-            }
-        }
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        const result = await apiCallWithRetry("/search", "POST", {
-            query: args.query,
-            top_k: args.top_k || 3,
-        });
-        return { success: true, data: result.results };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`search_memory failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function storeEventWithFallback(args, context) {
-    if (!isEnabled) {
-        if (config?.fallbackToBuiltin && builtinMemory) {
-            logger.info("Using builtin memory (plugin disabled)");
-            try {
-                const id = await builtinMemory.store(args.summary, {
-                    entities: args.entities,
-                    outcome: args.outcome,
-                    relations: args.relations
-                });
-                return { success: true, data: { event_id: id } };
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return { success: false, error: `Builtin memory error: ${message}` };
-            }
-        }
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        const result = await apiCallWithRetry("/event", "POST", {
-            summary: args.summary,
-            entities: args.entities,
-            outcome: args.outcome,
-            relations: args.relations,
-        });
-        return { success: true, data: result };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`store_event failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function queryGraph(args, _context) {
-    if (!args || !args.entity) {
-        logger.error(`query_graph called with invalid args: ${JSON.stringify(args)}`);
-        return { success: false, error: ERROR_CODES.INVALID_INPUT.message + " Missing 'entity' parameter.", errorCode: ERROR_CODES.INVALID_INPUT.code };
-    }
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        const result = await apiCallWithRetry("/graph/query", "POST", { entity: args.entity });
-        return { success: true, data: result.graph };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`query_graph failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function getHotContext(args, _context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : 20;
-        const result = await apiCallWithRetry(`/hot-context?limit=${limit}`, "GET");
-        return { success: true, data: result.context };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`get_hot_context failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function getAutoContext(args, context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    const now = Date.now();
-    const result = {};
-    const sessionId = resolveSessionId(context);
-    clearStaleAutoSearchCache(now);
-    const sessionCache = autoSearchCacheBySession.get(sessionId);
-    if (sessionCache) {
-        result.auto_search = {
-            query: sessionCache.query,
-            results: sessionCache.results,
-            age_seconds: Math.floor((now - sessionCache.timestamp) / 1000),
-        };
-    }
-    if (args.include_hot !== false) {
-        try {
-            const hotResult = await apiCallWithRetry("/hot-context", "GET");
-            result.hot_context = hotResult.context;
-        }
-        catch (error) {
-            logger.debug(`Failed to get hot context: ${formatApiError(error)}`);
-        }
-    }
-    if (!result.auto_search && !result.hot_context) {
-        return {
-            success: true,
-            data: {
-                message: "No session-scoped auto-search results cached and hot context unavailable",
-                suggestion: "Send a user message in this session or call get_hot_context."
-            }
-        };
-    }
-    return { success: true, data: result };
-}
-async function reflectMemory(_args, _context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        await apiCallWithRetry("/reflect", "POST", undefined, {
-            timeout: 120000,
-            maxRetries: 2,
-        });
-        return { success: true };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`reflect_memory failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function syncMemory(_args, _context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        await apiCallWithRetry("/sync", "POST", undefined, {
-            timeout: 300000,
-            maxRetries: 2,
-        });
-        return { success: true };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`sync_memory failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function promoteMemory(_args, _context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        await apiCallWithRetry("/promote", "POST", undefined, {
-            timeout: 120000,
-            maxRetries: 2,
-        });
-        return { success: true };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`promote_memory failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function deleteMemory(args, _context) {
-    if (!isEnabled) {
-        if (config?.fallbackToBuiltin && builtinMemory) {
-            try {
-                const success = await builtinMemory.delete(args.memory_id);
-                return { success };
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return { success: false, error: `Builtin memory error: ${message}` };
-            }
-        }
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        await apiCallWithRetry(`/memory/${args.memory_id}`, "DELETE");
-        return { success: true };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`delete_memory failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function updateMemory(args, _context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        await apiCallWithRetry(`/memory/${args.memory_id}`, "PATCH", {
-            text: args.text,
-            type: args.type,
-            weight: args.weight,
-        });
-        return { success: true };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`update_memory failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function cleanupMemories(args, _context) {
-    if (!isEnabled) {
-        return { success: false, error: ERROR_CODES.PLUGIN_DISABLED.message, errorCode: ERROR_CODES.PLUGIN_DISABLED.code };
-    }
-    try {
-        const result = await apiCallWithRetry("/cleanup", "POST", {
-            days_old: args.days_old || 90,
-            memory_type: args.memory_type,
-        });
-        return { success: true, data: { deletedCount: result.deleted_count } };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`cleanup_memories failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function runDiagnostics(_args, _context) {
-    if (!isEnabled) {
-        return {
-            success: true,
-            data: {
-                status: "disabled",
-                message: "Cortex Memory plugin is disabled",
-                suggestion: "Enable the plugin using 'openclaw plugins enable cortex-memory'"
-            }
-        };
-    }
-    try {
-        const result = await apiCallWithRetry("/doctor", "GET");
-        return { success: true, data: result };
-    }
-    catch (error) {
-        const message = formatApiError(error);
-        logger.error(`diagnostics failed: ${message}`);
-        return { success: false, error: message };
-    }
-}
-async function getPluginStatus(_args, _context) {
-    return {
-        success: true,
-        data: {
-            enabled: isEnabled,
-            service_running: pythonProcess !== null,
-            fallback_enabled: config?.fallbackToBuiltin ?? true,
-            builtin_memory_available: builtinMemory !== null,
-            engine_mode: config?.engineMode ?? "python",
-        }
-    };
-}
-async function onMessagePythonHandler(payload, context) {
-    if (!isEnabled)
-        return;
-    const normalized = normalizeIncomingMessage(payload);
-    if (!normalized)
-        return;
-    const { text, role, source } = normalized;
-    const sessionId = resolveSessionId(context, payload);
-    try {
-        const writeResult = await apiCallWithRetry("/write", "POST", {
-            text,
-            source,
-            role,
-            session_id: sessionId
-        });
-        if (writeResult.status === "ok") {
-            logger.info(`Stored ${role} message for session ${sessionId}`);
-        }
-        else {
-            logger.debug(`Write skipped for session ${sessionId}: ${writeResult.reason || writeResult.status || "unknown"}`);
-        }
-    }
-    catch (error) {
-        logger.warn(`Failed to store message: ${formatApiError(error)}`);
-    }
-    if (role === "user" && text.length > 5) {
-        try {
-            const searchResult = await apiCallWithRetry("/search", "POST", {
-                query: text,
-                top_k: 3,
-                session_id: sessionId,
-            });
-            if (searchResult.results && searchResult.results.length > 0) {
-                setSessionAutoSearchCache(sessionId, text, searchResult.results);
-                logger.info(`Auto-search cached ${searchResult.results.length} results for context`);
-            }
-            else if (searchResult.skipped) {
-                logger.debug(`Auto-search skipped for session ${sessionId}: ${searchResult.reason || "query filtered"}`);
-            }
-        }
-        catch (error) {
-            logger.debug(`Auto-search skipped: ${formatApiError(error)}`);
-        }
-    }
-}
-async function onSessionEndPythonHandler(payload, context) {
-    if (!isEnabled)
-        return;
-    const sessionId = resolveSessionId(context, payload);
-    try {
-        const endResult = await apiCallWithRetry("/session-end", "POST", {
-            session_id: sessionId,
-            sync_records: config?.autoSync ?? true,
-        });
-        logger.info(`Session ${sessionId} ended, generated ${endResult.events_generated} events`);
-    }
-    catch (error) {
-        logger.warn(`Failed to end session: ${formatApiError(error)}`);
-    }
-}
-async function onTimerPythonHandler(payload, _context) {
-    if (!isEnabled)
-        return;
-    const data = payload;
-    const action = data.action;
-    try {
-        if (action === "sync") {
-            await apiCallWithRetry("/sync", "POST", undefined, {
-                timeout: 300000,
-                maxRetries: 2,
-            });
-            logger.info("Scheduled sync complete");
-        }
-        else if (action === "reflect" || (config?.autoReflect && !action)) {
-            await apiCallWithRetry("/reflect", "POST", undefined, {
-                timeout: 120000,
-                maxRetries: 2,
-            });
-            logger.info("Scheduled reflection complete");
-        }
-        else if (action === "promote") {
-            await apiCallWithRetry("/promote", "POST", undefined, {
-                timeout: 120000,
-                maxRetries: 2,
-            });
-            logger.info("Scheduled promotion complete");
-        }
-    }
-    catch (error) {
-        logger.warn(`Timer action failed: ${formatApiError(error)}`);
-    }
-}
-async function onMessageHandler(payload, context) {
-    const sessionId = resolveSessionId(context, payload);
-    if (isInternalSession(sessionId)) {
-        return;
-    }
-    await runWithTimeout(resolveEngine().onMessage(payload, context), HOOK_GUARD_TIMEOUT_MS, "onMessage hook");
-}
-async function onSessionEndHandler(payload, context) {
-    const sessionId = resolveSessionId(context, payload);
-    if (isInternalSession(sessionId)) {
-        return;
+    let task;
+    task = resolveEngine().onMessage(payload, context).finally(() => {
+        if (messageHookInFlightBySession.get(sessionId) === task) {
+            messageHookInFlightBySession.delete(sessionId);
+        }
+    });
+    messageHookInFlightBySession.set(sessionId, task);
+    await runWithTimeout(task, HOOK_GUARD_TIMEOUT_MS, "onMessage hook");
+}
+async function onSessionEndHandler(payload, context) {
+    const sessionId = resolveSessionId(context, payload);
+    if (isInternalSession(sessionId)) {
+        return;
     }
     await runWithTimeout(resolveEngine().onSessionEnd(payload, context), HOOK_GUARD_TIMEOUT_MS, "onSessionEnd hook");
 }
@@ -1535,6 +1040,8 @@ async function onTimerHandler(payload, context) {
 function registerTools() {
     if (!api)
         return;
+    const apiObj = api;
+    logger.info(`registerTools API capability: registerTool=${typeof apiObj.registerTool === "function"}, registerTools=${typeof apiObj.registerTools === "function"}, tools.register=${typeof apiObj.tools?.register === "function"}`);
     const tools = [
         {
             name: "search_memory",
@@ -1544,12 +1051,24 @@ function registerTools() {
                 properties: {
                     query: { type: "string", description: "Search query" },
                     top_k: { type: "integer", description: "Number of results to return" },
+                    fusion_mode: {
+                        type: "string",
+                        enum: ["auto", "authoritative", "candidates", "off"],
+                        description: "LLM fusion behavior: auto honors config, authoritative returns fused answer only, candidates returns fusion plus ranked candidates, off disables fusion",
+                    },
+                    track_hits: {
+                        type: "boolean",
+                        description: "Whether to update anti-decay hit statistics; set false for diagnostics or benchmarks",
+                    },
                 },
                 required: ["query"],
                 additionalProperties: false,
             },
             execute: async (params) => {
+                logger.info(`search_memory execute called with params: ${JSON.stringify(params)}`);
+                logger.info(`params.args: ${JSON.stringify(params.args)}`);
                 const args = params.args || params;
+                logger.info(`args after extraction: ${JSON.stringify(args)}`);
                 return resolveEngine().searchMemory(args, params.context);
             },
         },
@@ -1559,41 +1078,158 @@ function registerTools() {
             parameters: {
                 type: "object",
                 properties: {
-                    summary: { type: "string", description: "Event summary" },
-                    entities: {
-                        type: "array",
-                        description: "Involved entities",
-                        items: { type: "string" }
-                    },
-                    outcome: { type: "string", description: "Event outcome" },
-                    relations: {
-                        type: "array",
-                        description: "Entity relationships",
-                        items: { type: "string" }
+                    summary: { type: "string", description: "Event summary" },
+                    cause: { type: "string", description: "What triggered the event (task/request/problem statement)" },
+                    process: { type: "string", description: "How the task was handled (steps/attempts/iterations)" },
+                    result: { type: "string", description: "Final result and acceptance outcome" },
+                    entities: {
+                        type: "array",
+                        description: "Involved entities",
+                        items: {
+                            oneOf: [
+                                { type: "string" },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        id: { type: "string" },
+                                        name: { type: "string" },
+                                        type: { type: "string" },
+                                    },
+                                    additionalProperties: false,
+                                },
+                            ],
+                        },
+                    },
+                    entity_types: {
+                        type: "object",
+                        description: "Entity type map, key is entity name and value is type",
+                        additionalProperties: { type: "string" },
+                    },
+                    outcome: { type: "string", description: "Event outcome" },
+                    relations: {
+                        type: "array",
+                        description: "Entity relationships",
+                        items: {
+                            oneOf: [
+                                { type: "string" },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        source: { type: "string" },
+                                        target: { type: "string" },
+                                        type: { type: "string" },
+                                        evidence_span: { type: "string" },
+                                        confidence: { type: "number" },
+                                    },
+                                    required: ["source", "target"],
+                                    additionalProperties: false,
+                                },
+                            ],
+                        }
+                    },
+                },
+                required: ["summary"],
+                additionalProperties: false,
+            },
+            execute: async (params) => {
+                const args = params.args || params;
+                return resolveEngine().storeEvent(args, params.context);
+            },
+        },
+        {
+            name: "query_graph",
+            description: "Query memory graph for entity relationships",
+            parameters: {
+                type: "object",
+                properties: {
+                    entity: { type: "string", description: "Entity name" },
+                    rel: { type: "string", description: "Optional relation type filter" },
+                    dir: {
+                        type: "string",
+                        description: "Relation direction filter",
+                        enum: ["incoming", "outgoing", "both"],
+                    },
+                    path_to: { type: "string", description: "Find path from entity to this target entity" },
+                    max_depth: { type: "integer", description: "Path query max depth (2~4)" },
+                },
+                required: ["entity"],
+                additionalProperties: false,
+            },
+            execute: async (params) => {
+                const args = params.args || params;
+                return resolveEngine().queryGraph(args, params.context);
+            },
+        },
+        {
+            name: "export_graph_view",
+            description: "Export status-aware graph view and optionally write wiki graph snapshots",
+            parameters: {
+                type: "object",
+                properties: {
+                    write_snapshot: {
+                        type: "boolean",
+                        description: "When true (default), write wiki/graph/view.json, timeline.jsonl and Mermaid network snapshots",
+                    },
+                },
+                required: [],
+                additionalProperties: false,
+            },
+            execute: async (params) => {
+                const args = params.args || params;
+                return resolveEngine().exportGraphView(args, params.context);
+            },
+        },
+        {
+            name: "lint_memory_wiki",
+            description: "Run wiki memory lint checks for graph consistency, evidence coverage, page quality, and structured repair guidance",
+            parameters: {
+                type: "object",
+                properties: {},
+                required: [],
+                additionalProperties: false,
+            },
+            execute: async (params) => {
+                const args = params.args || params;
+                return resolveEngine().lintMemoryWiki(args, params.context);
+            },
+        },
+        {
+            name: "list_graph_conflicts",
+            description: "List pending/handled graph memory conflicts that require user confirmation",
+            parameters: {
+                type: "object",
+                properties: {
+                    status: {
+                        type: "string",
+                        enum: ["pending", "accepted", "rejected", "all"],
+                        description: "Filter conflict status",
                     },
+                    limit: { type: "integer", description: "Maximum returned conflicts" },
                 },
-                required: ["summary"],
+                required: [],
                 additionalProperties: false,
             },
             execute: async (params) => {
                 const args = params.args || params;
-                return resolveEngine().storeEvent(args, params.context);
+                return resolveEngine().listGraphConflicts(args, params.context);
             },
         },
         {
-            name: "query_graph",
-            description: "Query memory graph for entity relationships",
+            name: "resolve_graph_conflict",
+            description: "Resolve a graph conflict by accepting or rejecting the new candidate fact",
             parameters: {
                 type: "object",
                 properties: {
-                    entity: { type: "string", description: "Entity name" }
+                    conflict_id: { type: "string", description: "Conflict ID from list_graph_conflicts" },
+                    action: { type: "string", enum: ["accept", "reject"], description: "Resolution action" },
+                    note: { type: "string", description: "Optional note for audit trail" },
                 },
-                required: ["entity"],
+                required: ["conflict_id", "action"],
                 additionalProperties: false,
             },
             execute: async (params) => {
                 const args = params.args || params;
-                return resolveEngine().queryGraph(args, params.context);
+                return resolveEngine().resolveGraphConflict(args, params.context);
             },
         },
         {
@@ -1656,6 +1292,26 @@ function registerTools() {
                 return resolveEngine().syncMemory(args, params.context);
             },
         },
+        {
+            name: "backfill_embeddings",
+            description: "Backfill missing embeddings for active/archive records",
+            parameters: {
+                type: "object",
+                properties: {
+                    layer: { type: "string", enum: ["active", "archive", "all"], description: "Target layer to backfill" },
+                    batch_size: { type: "integer", description: "Batch size per processing window" },
+                    max_retries: { type: "integer", description: "Max retry count for failed records" },
+                    retry_failed_only: { type: "boolean", description: "Only retry failed records" },
+                    rebuild_mode: { type: "string", enum: ["incremental", "vector_only", "full"], description: "Rebuild mode" },
+                },
+                required: [],
+                additionalProperties: false,
+            },
+            execute: async (params) => {
+                const args = params.args || params;
+                return resolveEngine().backfillEmbeddings(args, params.context);
+            },
+        },
         {
             name: "delete_memory",
             description: "Delete a memory by ID",
@@ -1673,7 +1329,7 @@ function registerTools() {
             },
         },
         {
-            name: "diagnostics",
+            name: TOOL_NAME_CORTEX_DIAGNOSTICS,
             description: "Check memory system status",
             parameters: {
                 type: "object",
@@ -1683,43 +1339,242 @@ function registerTools() {
             },
             execute: async (params) => {
                 const args = params.args || params;
-                return resolveEngine().runDiagnostics(args, params.context);
+                const result = await resolveEngine().runDiagnostics(args, params.context);
+                return withToolVisibilityDiagnostics(result, params.context);
+            },
+        },
+        {
+            name: TOOL_NAME_DIAGNOSTICS_LEGACY,
+            description: "Legacy alias for cortex_diagnostics",
+            optional: true,
+            parameters: {
+                type: "object",
+                properties: {},
+                required: [],
+                additionalProperties: false,
+            },
+            execute: async (params) => {
+                const args = params.args || params;
+                const result = await resolveEngine().runDiagnostics(args, params.context);
+                return withToolVisibilityDiagnostics(result, params.context);
             },
         },
     ];
+    let successCount = 0;
     for (const tool of tools) {
-        registerToolCompat(tool);
-        registeredTools.push(tool.name);
+        try {
+            registerToolCompat(tool);
+            registeredTools.push(tool.name);
+            successCount += 1;
+        }
+        catch (error) {
+            logger.error(`Failed to register tool ${tool.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    logger.info(`registerTools completed: ${successCount}/${tools.length} tools registered`);
+}
+function sanitizeToolParametersSchemaValue(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return {};
+    }
+    const source = schema;
+    const target = {};
+    if (typeof source.type === "string") {
+        target.type = source.type;
+    }
+    if (typeof source.description === "string" && source.description.trim()) {
+        target.description = source.description;
+    }
+    if (Array.isArray(source.enum)) {
+        const values = source.enum.filter(item => typeof item === "string" || typeof item === "number" || typeof item === "boolean" || item === null);
+        if (values.length > 0) {
+            target.enum = values;
+        }
+    }
+    if (source.properties && typeof source.properties === "object" && !Array.isArray(source.properties)) {
+        const sanitizedProperties = {};
+        for (const [key, value] of Object.entries(source.properties)) {
+            sanitizedProperties[key] = sanitizeToolParametersSchemaValue(value);
+        }
+        target.properties = sanitizedProperties;
+    }
+    if (Array.isArray(source.required)) {
+        const required = source.required.filter(item => typeof item === "string");
+        if (required.length > 0) {
+            target.required = required;
+        }
+    }
+    if (source.items && typeof source.items === "object" && !Array.isArray(source.items)) {
+        target.items = sanitizeToolParametersSchemaValue(source.items);
+    }
+    if (typeof source.additionalProperties === "boolean") {
+        target.additionalProperties = source.additionalProperties;
+    }
+    else if (source.additionalProperties && typeof source.additionalProperties === "object") {
+        target.additionalProperties = true;
     }
+    return target;
+}
+function sanitizeToolParametersSchema(schema) {
+    const sanitized = sanitizeToolParametersSchemaValue(schema);
+    if (sanitized.type !== "object") {
+        sanitized.type = "object";
+    }
+    if (!sanitized.properties || typeof sanitized.properties !== "object" || Array.isArray(sanitized.properties)) {
+        sanitized.properties = {};
+    }
+    if (!Array.isArray(sanitized.required)) {
+        sanitized.required = [];
+    }
+    if (typeof sanitized.additionalProperties !== "boolean") {
+        sanitized.additionalProperties = false;
+    }
+    return sanitized;
 }
 function registerToolCompat(tool) {
     if (!api)
         return;
-    const execute = async (params) => tool.execute({
-        args: params?.args || {},
-        context: params.context,
-    });
-    const handler = async (...params) => {
+    const normalizeContext = (value) => {
+        const contextObj = asRecord(value) || {};
+        return {
+            agentId: firstString([contextObj.agentId, contextObj.agent_id]) || "unknown-agent",
+            workspaceId: firstString([contextObj.workspaceId, contextObj.workspace_id]) || "default",
+            sessionId: firstString([contextObj.sessionId, contextObj.session_id]) || undefined,
+        };
+    };
+    const normalizeInvocation = (...params) => {
+        logger.info(`normalizeInvocation called with params: ${JSON.stringify(params)}`);
+        if (params.length === 1) {
+            const first = params[0];
+            const firstObj = asRecord(first);
+            if (firstObj && ("context" in firstObj || "args" in firstObj)) {
+                const explicitArgs = asRecord(firstObj.args);
+                if (explicitArgs) {
+                    logger.info(`normalizeInvocation: single param with explicit args: ${JSON.stringify(explicitArgs)}`);
+                    return {
+                        args: explicitArgs,
+                        context: normalizeContext(firstObj.context),
+                    };
+                }
+                const directArgs = { ...firstObj };
+                delete directArgs.context;
+                delete directArgs.args;
+                logger.info(`normalizeInvocation: single param with direct args: ${JSON.stringify(directArgs)}`);
+                return {
+                    args: directArgs,
+                    context: normalizeContext(firstObj.context),
+                };
+            }
+            if (firstObj) {
+                logger.info(`normalizeInvocation: single param as args: ${JSON.stringify(firstObj)}`);
+                return {
+                    args: firstObj,
+                    context: normalizeContext(undefined),
+                };
+            }
+        }
         const first = params[0];
         const second = params[1];
-        if (first && typeof first === "object" && "context" in first) {
-            return execute({
-                args: first.args || {},
-                context: first.context,
+        const third = params[2];
+        const firstObj = asRecord(first);
+        const secondObj = asRecord(second);
+        if (typeof first === "string" && secondObj) {
+            logger.info(`normalizeInvocation: first is string (tool call ID), second is args: ${JSON.stringify(secondObj)}`);
+            return {
+                args: secondObj,
+                context: normalizeContext(third),
+            };
+        }
+        if (firstObj && ("context" in firstObj || "args" in firstObj)) {
+            const explicitArgs = asRecord(firstObj.args);
+            if (explicitArgs) {
+                logger.info(`normalizeInvocation: first has explicit args: ${JSON.stringify(explicitArgs)}`);
+                return {
+                    args: explicitArgs,
+                    context: normalizeContext(firstObj.context),
+                };
+            }
+            const directArgs = { ...firstObj };
+            delete directArgs.context;
+            delete directArgs.args;
+            logger.info(`normalizeInvocation: first has direct args: ${JSON.stringify(directArgs)}`);
+            return {
+                args: directArgs,
+                context: normalizeContext(firstObj.context),
+            };
+        }
+        if (firstObj && Object.keys(firstObj).length > 0) {
+            logger.info(`normalizeInvocation: first is args, second is context: ${JSON.stringify(firstObj)}`);
+            return {
+                args: firstObj,
+                context: normalizeContext(second),
+            };
+        }
+        logger.info(`normalizeInvocation: fallback to firstObj as args: ${JSON.stringify(firstObj)}`);
+        return {
+            args: firstObj || {},
+            context: normalizeContext(second),
+        };
+    };
+    const invoke = async (...params) => {
+        const traceId = createToolTraceId(tool.name);
+        const startedAt = Date.now();
+        logger.info(`[ToolTrace] start traceId=${traceId} tool=${tool.name} paramCount=${params.length}`);
+        const normalized = normalizeInvocation(...params);
+        logger.debug(`[ToolTrace] normalized traceId=${traceId} tool=${tool.name} args=${formatUnknownForLog(sanitizeForLogging(normalized.args))} context=${formatUnknownForLog(sanitizeForLogging(normalized.context))}`);
+        try {
+            const result = await tool.execute({
+                args: normalized.args,
+                context: normalized.context,
             });
+            const durationMs = Date.now() - startedAt;
+            logger.info(`[ToolTrace] success traceId=${traceId} tool=${tool.name} durationMs=${durationMs} resultSuccess=${result.success}`);
+            if (!result.success) {
+                logger.error(`[ToolTrace] tool_failure traceId=${traceId} tool=${tool.name} error=${truncateForLog(result.error || "unknown_error")} errorCode=${result.errorCode || "none"} args=${formatUnknownForLog(sanitizeForLogging(normalized.args))}`);
+            }
+            return toAgentToolResult(result, traceId);
+        }
+        catch (error) {
+            const durationMs = Date.now() - startedAt;
+            const message = toErrorMessage(error);
+            logger.error(`[ToolTrace] exception traceId=${traceId} tool=${tool.name} durationMs=${durationMs} message=${truncateForLog(message)} args=${formatUnknownForLog(sanitizeForLogging(normalized.args))} context=${formatUnknownForLog(sanitizeForLogging(normalized.context))}`);
+            if (error instanceof Error && error.stack) {
+                logger.error(`[ToolTrace] stack traceId=${traceId} tool=${tool.name} ${truncateForLog(error.stack, 4000)}`);
+            }
+            return toAgentToolResult({
+                success: false,
+                error: `Tool execution failed [traceId=${traceId}]: ${message}`,
+                errorCode: "TOOL_EXECUTION_EXCEPTION",
+            }, traceId);
         }
-        return execute({
-            args: first || {},
-            context: (second || {}),
-        });
     };
-    api.registerTool({
+    const payload = {
         name: tool.name,
         description: tool.description,
-        parameters: tool.parameters,
-        execute,
-        handler,
-    });
+        parameters: sanitizeToolParametersSchema(tool.parameters),
+        ...(tool.optional ? { optional: true } : {}),
+        execute: invoke,
+        handler: invoke,
+    };
+    const apiObj = api;
+    if (typeof apiObj.registerTool === "function") {
+        if (tool.optional) {
+            apiObj.registerTool(payload, { optional: true });
+        }
+        else {
+            apiObj.registerTool(payload);
+        }
+        return;
+    }
+    if (typeof apiObj.registerTools === "function") {
+        apiObj.registerTools([payload]);
+        return;
+    }
+    if (typeof apiObj.tools?.register === "function") {
+        apiObj.tools.register(payload);
+        return;
+    }
+    throw new Error("No supported tool registration API found");
 }
 function unregisterTools() {
     if (!api || !api.unregisterTool)
@@ -1734,6 +1589,110 @@ function unregisterTools() {
     }
     registeredTools = [];
 }
+function registerFallbackTools() {
+    if (!api || !builtinMemory)
+        return;
+    for (const name of ["search_memory", "store_event", "cortex_memory_status"]) {
+        try {
+            if (api.unregisterTool) {
+                api.unregisterTool(name);
+                logger.info(`Unregistered existing tool ${name} before registering fallback`);
+            }
+        }
+        catch (e) {
+            // ignore
+        }
+    }
+    registerToolCompat({
+        name: "search_memory",
+        description: "Search memory (using builtin system - Cortex Memory disabled)",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                top_k: { type: "integer", description: "Number of results" },
+                fusion_mode: { type: "string", enum: ["auto", "authoritative", "candidates", "off"], description: "Ignored by builtin fallback" },
+                track_hits: { type: "boolean", description: "Ignored by builtin fallback" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        execute: async (params) => {
+            const args = (params.args || params);
+            const query = args.query || "";
+            const topK = args.top_k || 5;
+            try {
+                const results = await builtinMemory.search(query, topK);
+                return { success: true, data: results };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { success: false, error: `Builtin memory error: ${message}` };
+            }
+        },
+    });
+    registeredFallbackTools.push("search_memory");
+    registerToolCompat({
+        name: "store_event",
+        description: "Store event (using builtin system - Cortex Memory disabled)",
+        parameters: {
+            type: "object",
+            properties: {
+                summary: { type: "string", description: "Event summary" },
+            },
+            required: ["summary"],
+            additionalProperties: false,
+        },
+        execute: async (params) => {
+            const args = (params.args || params);
+            const summary = args.summary || "";
+            try {
+                const id = await builtinMemory.store(summary);
+                return { success: true, data: { id } };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { success: false, error: `Builtin memory error: ${message}` };
+            }
+        },
+    });
+    registeredFallbackTools.push("store_event");
+    registerToolCompat({
+        name: "cortex_memory_status",
+        description: "Get the current status of the Cortex Memory plugin",
+        parameters: {
+            type: "object",
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        },
+        execute: async (_params) => {
+            return {
+                success: true,
+                data: {
+                    enabled: isEnabled,
+                    fallback_enabled: config?.fallbackToBuiltin ?? true,
+                    builtin_memory_available: builtinMemory !== null,
+                }
+            };
+        },
+    });
+    registeredFallbackTools.push("cortex_memory_status");
+    logger.info(`Registered ${registeredFallbackTools.length} fallback tools`);
+}
+function unregisterFallbackTools() {
+    if (!api || !api.unregisterTool)
+        return;
+    for (const name of registeredFallbackTools) {
+        try {
+            api.unregisterTool(name);
+        }
+        catch (e) {
+            logger.warn(`Failed to unregister fallback tool ${name}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    registeredFallbackTools = [];
+}
 function registerHooks() {
     if (!api)
         return;
@@ -1794,27 +1753,15 @@ function setupProcessHandlers() {
         isShuttingDown = true;
         logger.info(`Received ${signal}, shutting down...`);
         stopConfigWatcher();
-        if (!shouldUsePythonRuntime()) {
-            process.exit(0);
-            return;
-        }
-        shutdownPythonApi().then(() => {
-            killPythonProcess();
-            process.exit(0);
-        }).catch(() => {
-            killPythonProcess();
-            process.exit(0);
-        });
+        process.exit(0);
     };
     process.on("exit", () => {
-        killPythonProcess();
         stopConfigWatcher();
     });
     process.on("SIGINT", () => gracefulShutdown("SIGINT"));
     process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
     process.on("uncaughtException", (err) => {
         logger.error("Uncaught exception:", err.message);
-        killPythonProcess();
         stopConfigWatcher();
         process.exit(1);
     });
@@ -1828,10 +1775,6 @@ async function enable() {
     logLifecycle("enable_start");
     try {
         unregisterFallbackTools();
-        if (shouldUsePythonRuntime()) {
-            await startPythonService();
-            await waitForService();
-        }
         isEnabled = true;
         registerTools();
         registerHooks();
@@ -1855,12 +1798,9 @@ async function disable() {
     logLifecycle("disable_start");
     unregisterHooks();
     unregisterTools();
-    unregisterFallbackTools();
     stopAutoReflectScheduler();
-    if (shouldUsePythonRuntime()) {
-        await stopPythonServiceAsync();
-    }
     isEnabled = false;
+    messageHookInFlightBySession.clear();
     memoryEngine = null;
     if (config?.fallbackToBuiltin && builtinMemory) {
         logger.info("Falling back to OpenClaw builtin memory system");
@@ -1870,68 +1810,9 @@ async function disable() {
     logger.info("Cortex Memory plugin disabled successfully");
     logLifecycle("disable_success", { fallbackEnabled: registeredFallbackTools.length > 0 });
 }
-function registerFallbackTools() {
-    if (!api || !builtinMemory)
-        return;
-    registerToolCompat({
-        name: "search_memory",
-        description: "Search memory (using builtin system - Cortex Memory disabled)",
-        parameters: {
-            type: "object",
-            properties: {
-                query: { type: "string", description: "Search query" },
-                top_k: { type: "integer", description: "Number of results" },
-            },
-            required: ["query"],
-            additionalProperties: false,
-        },
-        execute: async ({ args, context }) => searchMemoryWithFallback((args || {}), context),
-    });
-    registeredFallbackTools.push("search_memory");
-    registerToolCompat({
-        name: "store_event",
-        description: "Store event (using builtin system - Cortex Memory disabled)",
-        parameters: {
-            type: "object",
-            properties: {
-                summary: { type: "string", description: "Event summary" },
-            },
-            required: ["summary"],
-            additionalProperties: false,
-        },
-        execute: async ({ args, context }) => storeEventWithFallback((args || {}), context),
-    });
-    registeredFallbackTools.push("store_event");
-    registerToolCompat({
-        name: "cortex_memory_status",
-        description: "Get the current status of the Cortex Memory plugin",
-        parameters: {
-            type: "object",
-            properties: {},
-            required: [],
-            additionalProperties: false,
-        },
-        execute: async ({ args, context }) => getPluginStatus(args || {}, context),
-    });
-    registeredFallbackTools.push("cortex_memory_status");
-}
-function unregisterFallbackTools() {
-    if (!api || !api.unregisterTool)
-        return;
-    for (const name of registeredFallbackTools) {
-        try {
-            api.unregisterTool(name);
-        }
-        catch (e) {
-            logger.warn(`Failed to unregister fallback tool ${name}: ${e instanceof Error ? e.message : String(e)}`);
-        }
-    }
-    registeredFallbackTools = [];
-}
 function getStatus() {
     return {
-        enabled: isEnabled,
-        serviceRunning: pythonProcess !== null
+        enabled: isEnabled
     };
 }
 async function unregister() {
@@ -1942,25 +1823,19 @@ async function unregister() {
     unregisterHooks();
     unregisterTools();
     unregisterFallbackTools();
-    if (shouldUsePythonRuntime()) {
-        await stopPythonServiceAsync();
-    }
-    else {
-        killPythonProcess();
-    }
     isEnabled = false;
     isInitializing = false;
     isRegistered = false;
     api = null;
     config = null;
     autoSearchCacheBySession.clear();
-    builtinMemory = null;
+    messageHookInFlightBySession.clear();
     memoryEngine = null;
+    builtinMemory = null;
     registeredTools = [];
     registeredHooks = [];
     registeredFallbackTools = [];
     registeredHookHandlers.clear();
-    stopAutoReflectScheduler();
     configPath = null;
     logger.info("Cortex Memory plugin unregistered successfully");
     logLifecycle("unregister_success");
@@ -1971,12 +1846,13 @@ function register(pluginApi, userConfig) {
     }
     isInitializing = true;
     api = pluginApi;
-    logger = api.getLogger?.() || createConsoleLogger();
+    logger = api.logger || api.getLogger?.() || createConsoleLogger();
     const apiPluginConfig = api.pluginConfig || {};
     const openclawConfig = api.config || {};
     const pluginEntry = openclawConfig?.plugins?.entries?.[PLUGIN_ID];
     const pluginConfig = Object.keys(apiPluginConfig).length > 0 ? apiPluginConfig : (pluginEntry?.config || {});
     const effectiveConfig = userConfig || pluginConfig || {};
+    const resolvedDbPath = resolveConfiguredMemoryRoot(typeof effectiveConfig.dbPath === "string" ? effectiveConfig.dbPath : undefined);
     const embeddingConfigRaw = (effectiveConfig.embedding || { provider: "openai-compatible", model: "" });
     const llmConfigRaw = (effectiveConfig.llm || { provider: "openai", model: "" });
     const rerankerConfigRaw = (effectiveConfig.reranker || { provider: "", model: "" });
@@ -1996,14 +1872,47 @@ function register(pluginApi, userConfig) {
         embedding: embeddingConfig,
         llm: llmConfig,
         reranker: rerankerConfig,
-        dbPath: effectiveConfig.dbPath,
+        dbPath: resolvedDbPath,
         autoSync: effectiveConfig.autoSync ?? defaultConfig.autoSync,
         autoReflect: effectiveConfig.autoReflect ?? defaultConfig.autoReflect,
         autoReflectIntervalMinutes: effectiveConfig.autoReflectIntervalMinutes ?? defaultConfig.autoReflectIntervalMinutes,
+        graphQualityMode: effectiveConfig.graphQualityMode ?? defaultConfig.graphQualityMode,
+        wikiProjection: {
+            enabled: effectiveConfig.wikiProjection?.enabled ?? defaultConfig.wikiProjection?.enabled,
+            mode: effectiveConfig.wikiProjection?.mode ?? defaultConfig.wikiProjection?.mode,
+            maxBatch: effectiveConfig.wikiProjection?.maxBatch ?? defaultConfig.wikiProjection?.maxBatch,
+        },
         readFusion: {
             enabled: effectiveConfig.readFusion?.enabled ?? defaultConfig.readFusion?.enabled,
             maxCandidates: effectiveConfig.readFusion?.maxCandidates ?? defaultConfig.readFusion?.maxCandidates,
             authoritative: effectiveConfig.readFusion?.authoritative ?? defaultConfig.readFusion?.authoritative,
+            channelWeights: effectiveConfig.readFusion?.channelWeights ?? defaultConfig.readFusion?.channelWeights,
+            channelTopK: effectiveConfig.readFusion?.channelTopK ?? defaultConfig.readFusion?.channelTopK,
+            minLexicalHits: effectiveConfig.readFusion?.minLexicalHits ?? defaultConfig.readFusion?.minLexicalHits,
+            minSemanticHits: effectiveConfig.readFusion?.minSemanticHits ?? defaultConfig.readFusion?.minSemanticHits,
+            lengthNorm: {
+                enabled: effectiveConfig.readFusion?.lengthNorm?.enabled ?? defaultConfig.readFusion?.lengthNorm?.enabled,
+                pivotChars: effectiveConfig.readFusion?.lengthNorm?.pivotChars ?? defaultConfig.readFusion?.lengthNorm?.pivotChars,
+                strength: effectiveConfig.readFusion?.lengthNorm?.strength ?? defaultConfig.readFusion?.lengthNorm?.strength,
+                minFactor: effectiveConfig.readFusion?.lengthNorm?.minFactor ?? defaultConfig.readFusion?.lengthNorm?.minFactor,
+            },
+        },
+        vectorChunking: {
+            chunkSize: effectiveConfig.vectorChunking?.chunkSize ?? defaultConfig.vectorChunking?.chunkSize,
+            chunkOverlap: effectiveConfig.vectorChunking?.chunkOverlap ?? defaultConfig.vectorChunking?.chunkOverlap,
+            evidenceMaxChunks: effectiveConfig.vectorChunking?.evidenceMaxChunks ?? defaultConfig.vectorChunking?.evidenceMaxChunks,
+        },
+        writePolicy: {
+            archiveMinConfidence: effectiveConfig.writePolicy?.archiveMinConfidence ?? defaultConfig.writePolicy?.archiveMinConfidence,
+            archiveMinQualityScore: effectiveConfig.writePolicy?.archiveMinQualityScore ?? defaultConfig.writePolicy?.archiveMinQualityScore,
+            activeMinQualityScore: effectiveConfig.writePolicy?.activeMinQualityScore ?? defaultConfig.writePolicy?.activeMinQualityScore,
+            activeDedupTailLines: effectiveConfig.writePolicy?.activeDedupTailLines ?? defaultConfig.writePolicy?.activeDedupTailLines,
+            activeTextMaxChars: effectiveConfig.writePolicy?.activeTextMaxChars ?? defaultConfig.writePolicy?.activeTextMaxChars,
+            archiveSourceTextMaxChars: effectiveConfig.writePolicy?.archiveSourceTextMaxChars ?? defaultConfig.writePolicy?.archiveSourceTextMaxChars,
+        },
+        syncPolicy: {
+            includeLocalActiveInput: effectiveConfig.syncPolicy?.includeLocalActiveInput ?? defaultConfig.syncPolicy?.includeLocalActiveInput,
+            graphQualityMode: effectiveConfig.syncPolicy?.graphQualityMode ?? defaultConfig.syncPolicy?.graphQualityMode,
         },
         memoryDecay: {
             enabled: effectiveConfig.memoryDecay?.enabled ?? defaultConfig.memoryDecay?.enabled,
@@ -2017,10 +1926,30 @@ function register(pluginApi, userConfig) {
                 recentWindowDays: effectiveConfig.memoryDecay?.antiDecay?.recentWindowDays ?? defaultConfig.memoryDecay?.antiDecay?.recentWindowDays,
             },
         },
+        readTuning: {
+            scoring: {
+                lexicalWeight: effectiveConfig.readTuning?.scoring?.lexicalWeight ?? defaultConfig.readTuning?.scoring?.lexicalWeight,
+                bm25Scale: effectiveConfig.readTuning?.scoring?.bm25Scale ?? defaultConfig.readTuning?.scoring?.bm25Scale,
+                semanticWeight: effectiveConfig.readTuning?.scoring?.semanticWeight ?? defaultConfig.readTuning?.scoring?.semanticWeight,
+                recencyWeight: effectiveConfig.readTuning?.scoring?.recencyWeight ?? defaultConfig.readTuning?.scoring?.recencyWeight,
+                qualityWeight: effectiveConfig.readTuning?.scoring?.qualityWeight ?? defaultConfig.readTuning?.scoring?.qualityWeight,
+                typeMatchWeight: effectiveConfig.readTuning?.scoring?.typeMatchWeight ?? defaultConfig.readTuning?.scoring?.typeMatchWeight,
+                graphMatchWeight: effectiveConfig.readTuning?.scoring?.graphMatchWeight ?? defaultConfig.readTuning?.scoring?.graphMatchWeight,
+            },
+            rrf: {
+                k: effectiveConfig.readTuning?.rrf?.k ?? defaultConfig.readTuning?.rrf?.k,
+                weight: effectiveConfig.readTuning?.rrf?.weight ?? defaultConfig.readTuning?.rrf?.weight,
+            },
+            recency: {
+                buckets: effectiveConfig.readTuning?.recency?.buckets ?? defaultConfig.readTuning?.recency?.buckets,
+            },
+            autoContext: {
+                queryMaxChars: effectiveConfig.readTuning?.autoContext?.queryMaxChars ?? defaultConfig.readTuning?.autoContext?.queryMaxChars,
+                lightweightSearch: effectiveConfig.readTuning?.autoContext?.lightweightSearch ?? defaultConfig.readTuning?.autoContext?.lightweightSearch,
+            },
+        },
         enabled: effectiveConfig.enabled ?? defaultConfig.enabled,
-        fallbackToBuiltin: effectiveConfig.fallbackToBuiltin ?? defaultConfig.fallbackToBuiltin,
-        apiUrl: effectiveConfig.apiUrl ?? "http://localhost:8765",
-        engineMode: "ts",
+        fallbackToBuiltin: effectiveConfig.fallbackToBuiltin ?? true,
     };
     memoryEngine = null;
     if (api.getBuiltinMemory) {
@@ -2039,8 +1968,12 @@ function register(pluginApi, userConfig) {
         reranker: { model: config.reranker.model },
         enabled: config.enabled,
         fallbackToBuiltin: config.fallbackToBuiltin,
-        engineMode: config.engineMode,
     });
+    logger.info(`Runtime config snapshot: ${JSON.stringify(safeConfig)}`);
+    const configErrors = validateConfig(config);
+    if (configErrors.length > 0) {
+        logger.warn(`Cortex Memory config validation warnings: ${configErrors.join(" | ")}`);
+    }
     checkOpenClawVersion().catch(e => logger.warn(`Version check failed: ${e}`));
     configPath = findOpenClawConfig();
     if (configPath) {
@@ -2053,40 +1986,23 @@ function register(pluginApi, userConfig) {
     isInitializing = false;
     isRegistered = true;
     logger.info("Cortex Memory plugin registered successfully");
-    logger.info(`Cortex Memory engine mode: ${resolveEngine().mode}`);
     logLifecycle("register_success", {
-        engineMode: config.engineMode,
         enabled: isEnabled,
-        hasBuiltinFallback: Boolean(builtinMemory),
     });
     if (isEnabled) {
         registerTools();
         registerHooks();
         startAutoReflectScheduler();
-        initializeAsync().catch(error => {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.error(`Failed to initialize Cortex Memory: ${message}`);
-            if (config?.fallbackToBuiltin && builtinMemory) {
-                unregisterHooks();
-                unregisterTools();
-                logger.info("Falling back to builtin memory");
-                isEnabled = false;
-                registerFallbackTools();
-                logLifecycle("fallback_after_init_error", { fallbackTools: registeredFallbackTools.length, error: message });
-            }
-        });
-    }
-    else if (config?.fallbackToBuiltin && builtinMemory) {
-        registerFallbackTools();
-        logLifecycle("fallback_registered_on_start", { fallbackTools: registeredFallbackTools.length });
     }
 }
-async function initializeAsync() {
-    if (!shouldUsePythonRuntime()) {
-        return;
-    }
-    await startPythonService();
-    await waitForService();
-    logger.info("Cortex Memory Python service started successfully");
-}
+const pluginEntry = definePluginEntryCompat({
+    id: PLUGIN_ID,
+    name: "Cortex Memory",
+    register,
+    unregister,
+    enable,
+    disable,
+    getStatus,
+});
+exports.default = pluginEntry;
 //# sourceMappingURL=index.js.map