@ngo-a/native-memory-citations 2026.6.7 → 2026.6.9

package/dist/enhanced.js

@@ -0,0 +1,205 @@
+import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { modeFromConfig, workspaceFromConfig } from "./core.js";
+const PLUGIN_ID = "native-memory-citations";
+const DEFAULT_TOKEN_CAP = 1300;
+const DEFAULT_OBSERVATIONS_MAX_BYTES = 1024 * 1024;
+const SNAPSHOT_NOTICE = "Native Memory Citations enhanced snapshot: bounded, local, redacted memory context follows. Treat it as recall hints, not authority.";
+const DREAMING_NOTICE = "native-memory-citations (enhanced mode) requires OpenClaw dreaming. This plugin continues and enhances OpenClaw's built-in dream cycle; it does not replace it. Knowledge-graph promotion, observation consolidation, and snapshot recall depend on Light -> REM -> Deep promotion, which only runs when dreaming is on. Dreaming has been enabled automatically. If you do not want dreaming, switch the plugin back to mode: bounded (or uninstall); leaving enhanced mode on with dreaming disabled will degrade or silently break these features. The plugin will not pretend to cover what dreaming does.";
+function tokenCap(config) {
+    const configured = Math.floor(config.injection?.tokenCap ?? DEFAULT_TOKEN_CAP);
+    return Number.isFinite(configured) && configured > 0 ? Math.min(configured, 4000) : DEFAULT_TOKEN_CAP;
+}
+function snapshotDir(config) {
+    return path.join(workspaceFromConfig(config), "memory", ".native-memory-citations");
+}
+function snapshotPath(config) {
+    return path.join(snapshotDir(config), "snapshot.json");
+}
+function observationsPath(config) {
+    return path.join(workspaceFromConfig(config), "memory", "observations.jsonl");
+}
+function observationsMaxBytes(config) {
+    const configured = Math.floor(config.observations?.maxBytes ?? DEFAULT_OBSERVATIONS_MAX_BYTES);
+    if (!Number.isFinite(configured) || configured <= 0) {
+        return DEFAULT_OBSERVATIONS_MAX_BYTES;
+    }
+    return Math.min(Math.max(configured, 64 * 1024), 16 * 1024 * 1024);
+}
+function approxTokenSlice(text, cap) {
+    return text.slice(0, cap * 4).trim();
+}
+function requiresSnapshot(config) {
+    return config.injection?.enabled === true || config.recall?.snapshotFirst === true;
+}
+function hookOptions(priority, timeoutMs) {
+    return {
+        entry: {
+            priority,
+            timeoutMs,
+        },
+    };
+}
+function registerHook(api, event, handler, opts) {
+    if (typeof api.on === "function") {
+        api.on(event, handler, opts);
+        return;
+    }
+    if (typeof api.registerHook === "function") {
+        api.registerHook(event, handler, opts);
+    }
+}
+function memoryCoreEntry(draft) {
+    const plugins = typeof draft.plugins === "object" && draft.plugins !== null
+        ? draft.plugins
+        : {};
+    const entries = typeof plugins.entries === "object" && plugins.entries !== null
+        ? plugins.entries
+        : {};
+    const entry = typeof entries["memory-core"] === "object" && entries["memory-core"] !== null
+        ? entries["memory-core"]
+        : {};
+    plugins.entries = entries;
+    entries["memory-core"] = entry;
+    draft.plugins = plugins;
+    return entry;
+}
+function setDreamingEnabledOnConfig(draft) {
+    const entry = memoryCoreEntry(draft);
+    const config = typeof entry.config === "object" && entry.config !== null
+        ? entry.config
+        : {};
+    const dreaming = typeof config.dreaming === "object" && config.dreaming !== null
+        ? config.dreaming
+        : {};
+    dreaming.enabled = true;
+    config.dreaming = dreaming;
+    entry.config = config;
+}
+async function buildSnapshot(config, logger) {
+    const workspace = workspaceFromConfig(config);
+    const parts = [];
+    for (const source of ["MEMORY.md", "DREAMS.md"]) {
+        const text = await readFile(path.join(workspace, source), "utf8").catch(() => "");
+        if (text.trim()) {
+            parts.push(`## ${source}\n${text.trim()}`);
+        }
+    }
+    const content = approxTokenSlice(parts.join("\n\n"), tokenCap(config));
+    await mkdir(snapshotDir(config), { recursive: true });
+    await writeFile(snapshotPath(config), `${JSON.stringify({
+        createdAt: new Date().toISOString(),
+        tokenCap: tokenCap(config),
+        content,
+    })}\n`, "utf8");
+    logger?.debug?.(`native-memory-citations: refreshed enhanced snapshot (${content.length} chars)`);
+}
+async function readSnapshot(config) {
+    const raw = await readFile(snapshotPath(config), "utf8").catch(() => "");
+    if (!raw.trim()) {
+        return undefined;
+    }
+    const parsed = JSON.parse(raw);
+    return typeof parsed.content === "string" && parsed.content.trim() ? parsed.content.trim() : undefined;
+}
+async function appendObservation(config, event) {
+    const file = observationsPath(config);
+    const record = {
+        timestamp: new Date().toISOString(),
+        turn: event && typeof event === "object" && "runId" in event ? String(event.runId ?? "") : "",
+        type: config.observations?.extraction === false ? "raw" : "none",
+        content: config.observations?.extraction === false ? JSON.stringify(event).slice(0, 4000) : "",
+        confidence: config.observations?.extraction === false ? 0.2 : 0,
+        sources: [],
+        action: config.observations?.extraction === false ? "ADD" : "NONE",
+    };
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
+    await enforceObservationLimit(file, observationsMaxBytes(config));
+}
+async function enforceObservationLimit(file, maxBytes) {
+    const size = (await stat(file).catch(() => null))?.size ?? 0;
+    if (size <= maxBytes) {
+        return;
+    }
+    const content = await readFile(file, "utf8");
+    if (Buffer.byteLength(content, "utf8") <= maxBytes) {
+        return;
+    }
+    let retained = Buffer.from(content, "utf8").subarray(-maxBytes).toString("utf8");
+    const firstNewline = retained.indexOf("\n");
+    if (firstNewline >= 0) {
+        retained = retained.slice(firstNewline + 1);
+    }
+    await writeFile(file, retained, "utf8");
+}
+function hostDreamingEnabled(api) {
+    const current = (typeof api.runtime?.config?.current === "function" ? api.runtime.config.current() : api.config);
+    if (current?.memory?.dreaming?.enabled === true) {
+        return true;
+    }
+    const memoryCore = current?.plugins?.entries?.["memory-core"];
+    if (memoryCore && typeof memoryCore === "object") {
+        return memoryCore.config?.dreaming?.enabled === true;
+    }
+    return false;
+}
+async function runDreamingGuard(api, config) {
+    if (modeFromConfig(config) !== "enhanced" || config.dreaming?.enforce === false) {
+        return;
+    }
+    if (hostDreamingEnabled(api)) {
+        return;
+    }
+    if (config.dreaming?.autoEnable === false || typeof api.runtime?.config?.mutateConfigFile !== "function") {
+        api.logger?.warn?.("native-memory-citations enhanced mode is enabled, but OpenClaw memory-core dreaming is not true.");
+        return;
+    }
+    await api.runtime.config.mutateConfigFile({
+        afterWrite: { mode: "auto" },
+        mutate: setDreamingEnabledOnConfig,
+    });
+    api.logger?.warn?.(DREAMING_NOTICE);
+}
+export function registerEnhancedLifecycle(api) {
+    const config = api.pluginConfig ?? {};
+    if (modeFromConfig(config) !== "enhanced") {
+        return;
+    }
+    void runDreamingGuard(api, config).catch((error) => {
+        api.logger?.warn?.(`native-memory-citations dreaming guard failed open: ${String(error)}`);
+    });
+    registerHook(api, "cron_changed", () => {
+        void runDreamingGuard(api, config).catch((error) => {
+            api.logger?.warn?.(`native-memory-citations dreaming guard failed open: ${String(error)}`);
+        });
+    }, hookOptions(100, 3000));
+    if (requiresSnapshot(config)) {
+        registerHook(api, "session_start", async () => {
+            await buildSnapshot(config, api.logger);
+        }, hookOptions(90, 5000));
+    }
+    if (config.injection?.enabled === true) {
+        registerHook(api, "before_prompt_build", async () => {
+            const snapshot = await readSnapshot(config);
+            if (!snapshot) {
+                return;
+            }
+            return {
+                prependContext: `${SNAPSHOT_NOTICE}\n\n${snapshot}`,
+            };
+        }, hookOptions(80, 5000));
+    }
+    if (config.observations?.enabled === true) {
+        registerHook(api, "agent_end", (event) => {
+            void appendObservation(config, event).catch((error) => {
+                api.logger?.warn?.(`native-memory-citations observation tagging failed open: ${String(error)}`);
+            });
+        }, hookOptions(10, 3000));
+    }
+}
+export const enhancedLifecycleForTest = {
+    DREAMING_NOTICE,
+    PLUGIN_ID,
+    setDreamingEnabledOnConfig,
+};

package/dist/health.d.ts

@@ -0,0 +1 @@
+export declare function registerNativeMemoryHealthChecks(): void;

package/dist/health.js

@@ -0,0 +1,164 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerHealthCheck } from "openclaw/plugin-sdk/health";
+import { graphEnabled, modeFromConfig, workspaceFromConfig } from "./core.js";
+const PLUGIN_ID = "native-memory-citations";
+const EXPECTED_TOOLS = [
+    "native_memory_answer",
+    "native_memory_extract",
+    "native_memory_fetch",
+    "native_memory_graph",
+    "native_memory_search",
+];
+let registered = false;
+function memoryDreamingEnabled(cfg) {
+    const record = cfg;
+    if (record.memory?.dreaming?.enabled === true) {
+        return true;
+    }
+    const memoryCore = record.plugins?.entries?.["memory-core"];
+    if (memoryCore && typeof memoryCore === "object") {
+        return memoryCore.config?.dreaming?.enabled === true;
+    }
+    return false;
+}
+function pluginConfigFromOpenClawConfig(cfg) {
+    const record = cfg;
+    const entry = record.plugins?.entries?.[PLUGIN_ID];
+    if (entry && typeof entry === "object") {
+        const maybeConfig = entry.config;
+        if (maybeConfig && typeof maybeConfig === "object") {
+            return maybeConfig;
+        }
+        return entry;
+    }
+    return {};
+}
+async function manifestTools() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const manifestPath = path.resolve(here, "..", "openclaw.plugin.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    return manifest.contracts?.tools ?? [];
+}
+async function collectMemoryMtimes(root) {
+    const info = await stat(root).catch(() => null);
+    if (!info) {
+        return [];
+    }
+    if (info.isFile()) {
+        return [info.mtimeMs];
+    }
+    if (!info.isDirectory()) {
+        return [];
+    }
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const mtimes = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules") {
+            continue;
+        }
+        const child = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            mtimes.push(...await collectMemoryMtimes(child));
+        }
+        else if (entry.isFile()) {
+            const childInfo = await stat(child).catch(() => null);
+            if (childInfo) {
+                mtimes.push(childInfo.mtimeMs);
+            }
+        }
+    }
+    return mtimes;
+}
+export function registerNativeMemoryHealthChecks() {
+    if (registered) {
+        return;
+    }
+    registered = true;
+    registerHealthCheck({
+        id: "native-memory-citations/manifest-tools",
+        kind: "plugin",
+        source: PLUGIN_ID,
+        description: "Native Memory Citations generated manifest lists the registered tools.",
+        async detect() {
+            const tools = await manifestTools().catch(() => []);
+            const missing = EXPECTED_TOOLS.filter((tool) => !tools.includes(tool));
+            if (missing.length === 0) {
+                return [];
+            }
+            return [{
+                    checkId: "native-memory-citations/manifest-tools",
+                    severity: "error",
+                    message: `Generated manifest is missing tools: ${missing.join(", ")}`,
+                    source: PLUGIN_ID,
+                    fixHint: "Run npm run plugin:build and commit the regenerated openclaw.plugin.json.",
+                }];
+        },
+    });
+    registerHealthCheck({
+        id: "native-memory-citations/dreaming-required",
+        kind: "plugin",
+        source: PLUGIN_ID,
+        description: "Enhanced mode warns when OpenClaw dreaming is disabled.",
+        async detect(ctx) {
+            const config = pluginConfigFromOpenClawConfig(ctx.cfg);
+            if (modeFromConfig(config) !== "enhanced") {
+                return [];
+            }
+            if (memoryDreamingEnabled(ctx.cfg)) {
+                return [];
+            }
+            return [{
+                    checkId: "native-memory-citations/dreaming-required",
+                    severity: config.dreaming?.blockToolsWhenOff ? "error" : "warning",
+                    message: "native-memory-citations enhanced mode is enabled but OpenClaw memory-core dreaming is not true.",
+                    source: PLUGIN_ID,
+                    ocPath: "plugins.entries.memory-core.config.dreaming.enabled",
+                    fixHint: "Enable OpenClaw dreaming or switch native-memory-citations back to mode: bounded.",
+                }];
+        },
+    });
+    registerHealthCheck({
+        id: "native-memory-citations/graph-fresh",
+        kind: "plugin",
+        source: PLUGIN_ID,
+        description: "Enhanced graph sidecar exists and is fresh enough for configured memory files.",
+        async detect(ctx) {
+            const config = pluginConfigFromOpenClawConfig(ctx.cfg);
+            if (!graphEnabled(config)) {
+                return [];
+            }
+            const workspace = workspaceFromConfig(config);
+            const graphPath = path.join(workspace, "memory", "graph.jsonl");
+            const graphInfo = await stat(graphPath).catch(() => null);
+            if (!graphInfo?.isFile()) {
+                return [{
+                        checkId: "native-memory-citations/graph-fresh",
+                        severity: "warning",
+                        message: "Enhanced graph mode is enabled but memory/graph.jsonl does not exist yet.",
+                        source: PLUGIN_ID,
+                        path: graphPath,
+                        fixHint: "Run native_memory_extract to build the graph sidecar.",
+                    }];
+            }
+            const memoryMtimes = [
+                ...await collectMemoryMtimes(path.join(workspace, "memory")),
+                ...await collectMemoryMtimes(path.join(workspace, "MEMORY.md")),
+            ];
+            const newestMemory = Math.max(0, ...memoryMtimes);
+            const findings = [];
+            if (newestMemory > graphInfo.mtimeMs + 1000) {
+                findings.push({
+                    checkId: "native-memory-citations/graph-fresh",
+                    severity: "warning",
+                    message: "memory/graph.jsonl is older than at least one memory source file.",
+                    source: PLUGIN_ID,
+                    path: graphPath,
+                    fixHint: "Run native_memory_extract to refresh the graph sidecar.",
+                });
+            }
+            return findings;
+        },
+    });
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("openclaw/plugin-sdk/tool-plugin").DefinedToolPluginEntry;
-export default _default;
+declare const plugin: import("openclaw/plugin-sdk/tool-plugin").DefinedToolPluginEntry;
+export default plugin;

package/dist/index.js

@@ -1,22 +1,88 @@
-import { Type } from "typebox";
 import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
-import { answerFromMemory, fetchMemorySource, searchMemory } from "./core.js";
+import { answerFromMemory, extractMemoryGraph, fetchMemorySource, modeFromConfig, queryMemoryGraph, searchMemory, } from "./core.js";
+import { registerEnhancedLifecycle } from "./enhanced.js";
+import { registerNativeMemoryHealthChecks } from "./health.js";
+registerNativeMemoryHealthChecks();
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false,
+    };
+}
+function stringSchema(description) {
+    return { type: "string", description };
+}
+function numberSchema(description) {
+    return { type: "number", description };
+}
+function booleanSchema(description) {
+    return { type: "boolean", description };
+}
+function stringUnionSchema(values, description) {
+    return {
+        anyOf: values.map((value) => ({ type: "string", const: value })),
+        ...(description ? { description } : {}),
+    };
+}
+const graphEdgeType = stringUnionSchema([
+    "works_at",
+    "invested_in",
+    "founded",
+    "advises",
+    "attended",
+    "mentions",
+]);
 // Declared config schema. Without this, OpenClaw applies a strict empty-object
 // schema and rejects every config key below. The generated manifest is produced
 // from this by `openclaw plugins build`; do not hand-edit it.
-const configSchema = Type.Object({
-    workspace: Type.Optional(Type.String({
-        description: "Absolute path to the OpenClaw workspace. Defaults to $OPENCLAW_WORKSPACE or ~/.openclaw/workspace.",
-    })),
-    allowedRoots: Type.Optional(Type.Array(Type.String(), {
+const configSchema = objectSchema({
+    workspace: stringSchema("Absolute path to the OpenClaw workspace. Defaults to $OPENCLAW_WORKSPACE or ~/.openclaw/workspace."),
+    allowedRoots: {
+        type: "array",
+        items: { type: "string" },
         description: "Workspace-relative memory roots to search. Overrides the built-in default set.",
-    })),
-    sharedMode: Type.Optional(Type.Boolean({ description: "When true, exclude the private MEMORY.md from the default root set." })),
-    maxFileBytes: Type.Optional(Type.Number({
-        description: "Per-file size cap in bytes. Files larger than this are skipped. Default 1048576.",
-    })),
-}, { additionalProperties: false });
-export default defineToolPlugin({
+    },
+    sharedMode: booleanSchema("When true, exclude the private MEMORY.md from the default root set."),
+    maxFileBytes: numberSchema("Per-file size cap in bytes. Files larger than this are skipped. Default 1048576."),
+    mode: stringUnionSchema(["bounded", "enhanced"], "Operating mode. bounded is default and preserves 2026.6.x behavior; enhanced enables explicitly configured pillars."),
+    dreaming: objectSchema({
+        autoEnable: booleanSchema("In enhanced mode, allow the dreaming guard to enable OpenClaw dreaming."),
+        enforce: booleanSchema("In enhanced mode, warn when dreaming-dependent features run without host dreaming."),
+        blockToolsWhenOff: booleanSchema("In enhanced mode, make dreaming-dependent tools fail hard when dreaming is off."),
+    }),
+    graph: objectSchema({
+        enabled: booleanSchema("Enable the local zero-LLM graph sidecar tools. Default false."),
+        edgeTypes: {
+            type: "array",
+            items: graphEdgeType,
+            description: "Typed graph edges to extract.",
+        },
+        maxDepth: numberSchema("Maximum traversal depth for native_memory_graph. Default 3."),
+    }),
+    recall: objectSchema({
+        semantic: booleanSchema("Enhanced mode placeholder for host semantic recall fusion. Default false."),
+        rerank: booleanSchema("Enhanced mode placeholder for reranking fused candidates. Default false."),
+        snapshotFirst: booleanSchema("Enhanced mode placeholder for tier-0 snapshot recall. Default false."),
+        intentClassifier: booleanSchema("Enhanced mode placeholder for intent classification. Default false."),
+    }),
+    injection: objectSchema({
+        enabled: booleanSchema("Enhanced mode placeholder for snapshot prompt injection. Default false."),
+        tokenCap: numberSchema("Maximum injected snapshot budget. Default 1300."),
+    }),
+    observations: objectSchema({
+        enabled: booleanSchema("Enhanced mode placeholder for observation tagging. Default false."),
+        model: stringSchema("Optional host model profile for future observation extraction. When omitted, use the host configured summarization or fast model."),
+        extraction: booleanSchema("When false, observation tagging uses raw append fallback. Default true."),
+        maxBytes: numberSchema("Maximum retained observations.jsonl size in bytes. Default 1048576."),
+    }),
+    wikiBridge: objectSchema({
+        enabled: booleanSchema("Enable optional memory-wiki bridge when present. Default false."),
+    }),
+});
+const ENHANCED_TOOL_NAMES = new Set(["native_memory_graph", "native_memory_extract"]);
+const plugin = defineToolPlugin({
     id: "native-memory-citations",
     name: "Native Memory Citations",
     description: "Search and fetch local OpenClaw memory with source citations and extractive cited answers.",
@@ -26,29 +92,34 @@ export default defineToolPlugin({
             name: "native_memory_search",
             label: "Memory Search (cited)",
             description: "Search approved local memory roots and return snippets with source paths and line numbers.",
-            parameters: Type.Object({
-                query: Type.String({ description: "Search query." }),
-                limit: Type.Optional(Type.Number({ description: "Maximum hits to return. Default 8, max 50." })),
-                contextLines: Type.Optional(Type.Number({ description: "Context lines around each hit. Default 2, max 8." })),
-            }),
-            execute: async ({ query, limit, contextLines }, config, context) => {
+            parameters: objectSchema({
+                query: stringSchema("Search query."),
+                limit: numberSchema("Maximum hits to return. Default 8, max 50."),
+                contextLines: numberSchema("Context lines around each hit. Default 2, max 8."),
+            }, ["query"]),
+            execute: async (input, config, context) => {
+                const { query, limit, contextLines } = input;
                 context.signal?.throwIfAborted();
-                return searchMemory(query, { limit, contextLines, config, signal: context.signal, logger: context.api.logger });
+                return searchMemory(query, {
+                    limit,
+                    contextLines,
+                    config: config,
+                    signal: context.signal,
+                    logger: context.api.logger,
+                });
             },
         }),
         tool({
             name: "native_memory_fetch",
             label: "Memory Fetch (cited)",
             description: "Fetch cited local memory content by sourceId/path and optional line range.",
-            parameters: Type.Object({
-                sourceId: Type.Optional(Type.String({ description: "Source id returned by native_memory_search." })),
-                filePath: Type.Optional(Type.String({ description: "Workspace-relative path inside an allowed memory root." })),
-                lineStart: Type.Optional(Type.Number({ description: "1-based starting line." })),
-                lineEnd: Type.Optional(Type.Number({ description: "1-based ending line." })),
-                maxChars: Type.Optional(Type.Number({ description: "Maximum characters returned. Default 8000." })),
-                expectedSha256: Type.Optional(Type.String({
-                    description: "Optional SHA-256 from a prior citation. When it differs from the current file hash, the result is marked stale.",
-                })),
+            parameters: objectSchema({
+                sourceId: stringSchema("Source id returned by native_memory_search."),
+                filePath: stringSchema("Workspace-relative path inside an allowed memory root."),
+                lineStart: numberSchema("1-based starting line."),
+                lineEnd: numberSchema("1-based ending line."),
+                maxChars: numberSchema("Maximum characters returned. Default 8000."),
+                expectedSha256: stringSchema("Optional SHA-256 from a prior citation. When it differs from the current file hash, the result is marked stale."),
             }),
             execute: async (input, config, context) => {
                 context.signal?.throwIfAborted();
@@ -59,14 +130,66 @@ export default defineToolPlugin({
             name: "native_memory_answer",
             label: "Memory Answer (cited)",
             description: "Answer from approved local memory using extractive snippets with citations. Says when no cited memory is found.",
-            parameters: Type.Object({
-                query: Type.String({ description: "Question to answer from local memory." }),
-                limit: Type.Optional(Type.Number({ description: "Maximum cited search hits to consider. Default 6." })),
-            }),
-            execute: async ({ query, limit }, config, context) => {
+            parameters: objectSchema({
+                query: stringSchema("Question to answer from local memory."),
+                limit: numberSchema("Maximum cited search hits to consider. Default 6."),
+            }, ["query"]),
+            execute: async (input, config, context) => {
+                const { query, limit } = input;
+                context.signal?.throwIfAborted();
+                return answerFromMemory(query, {
+                    limit,
+                    config: config,
+                    signal: context.signal,
+                    logger: context.api.logger,
+                });
+            },
+        }),
+        tool({
+            name: "native_memory_graph",
+            label: "Memory Graph (enhanced)",
+            description: "Query the opt-in local memory graph sidecar. Returns no data unless mode is enhanced and graph.enabled is true.",
+            optional: true,
+            parameters: objectSchema({
+                query: stringSchema("Entity or phrase to start traversal from."),
+                maxDepth: numberSchema("Maximum graph traversal depth. Default 3, max 6."),
+            }, ["query"]),
+            execute: async (input, config, context) => {
+                const { query, maxDepth } = input;
+                context.signal?.throwIfAborted();
+                return queryMemoryGraph(query, { maxDepth, config: config });
+            },
+        }),
+        tool({
+            name: "native_memory_extract",
+            label: "Memory Graph Extract (maintenance)",
+            description: "Rebuild the opt-in deterministic zero-LLM memory graph sidecar. Writes only when mode is enhanced and graph.enabled is true.",
+            optional: true,
+            parameters: objectSchema({}),
+            execute: async (_input, config, context) => {
                 context.signal?.throwIfAborted();
-                return answerFromMemory(query, { limit, config, signal: context.signal, logger: context.api.logger });
+                return extractMemoryGraph(config, { logger: context.api.logger });
             },
         }),
     ],
 });
+const registerAllTools = plugin.register.bind(plugin);
+plugin.register = (api) => {
+    const boundedMode = modeFromConfig(api.pluginConfig) === "bounded";
+    const filteredApi = {
+        ...api,
+        registerTool(toolDefinition, options) {
+            const name = typeof toolDefinition === "function"
+                ? options?.name
+                : toolDefinition?.name;
+            if (boundedMode && name && ENHANCED_TOOL_NAMES.has(name)) {
+                return;
+            }
+            return api.registerTool(toolDefinition, options);
+        },
+    };
+    const result = registerAllTools(filteredApi);
+    registerEnhancedLifecycle(api);
+    return result;
+};
+export default plugin;