neuralmemory 1.5.0

package/dist/tools.js

@@ -0,0 +1,184 @@
+/**
+ * NeuralMemory tool definitions for OpenClaw.
+ *
+ * Each tool proxies to the MCP server via JSON-RPC.
+ *
+ * Uses raw JSON Schema for parameters. Provider compatibility notes:
+ *   - `additionalProperties: false` required by OpenAI strict mode
+ *   - `number` instead of `integer` for Gemini compatibility
+ *   - No `maxLength`/`maxItems`/`minimum`/`maximum` — some providers
+ *     reject schemas with constraint keywords; our MCP server validates
+ *
+ * Registers 6 core tools:
+ *   nmem_remember  — Store a memory
+ *   nmem_recall    — Query/search memories
+ *   nmem_context   — Get recent context
+ *   nmem_todo      — Quick TODO shortcut
+ *   nmem_stats     — Brain statistics
+ *   nmem_health    — Brain health diagnostics
+ */
+// ── Tool factory ───────────────────────────────────────────
+export function createTools(mcp) {
+    const call = async (toolName, args) => {
+        if (!mcp.connected) {
+            return {
+                error: true,
+                message: "NeuralMemory service not running. Start the service first.",
+            };
+        }
+        try {
+            const raw = await mcp.callTool(toolName, args);
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return { text: raw };
+            }
+        }
+        catch (err) {
+            return {
+                error: true,
+                message: `Tool ${toolName} failed: ${err.message}`,
+            };
+        }
+    };
+    return [
+        {
+            name: "nmem_remember",
+            description: "Store a memory in NeuralMemory. Use this to remember facts, decisions, " +
+                "insights, todos, errors, and other information that should persist across sessions.",
+            parameters: {
+                type: "object",
+                properties: {
+                    content: {
+                        type: "string",
+                        description: "The content to remember",
+                    },
+                    type: {
+                        type: "string",
+                        enum: [
+                            "fact",
+                            "decision",
+                            "preference",
+                            "todo",
+                            "insight",
+                            "context",
+                            "instruction",
+                            "error",
+                            "workflow",
+                            "reference",
+                        ],
+                        description: "Memory type (auto-detected if not specified)",
+                    },
+                    priority: {
+                        type: "number",
+                        description: "Priority 0-10 (5=normal, 10=critical)",
+                    },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Tags for categorization",
+                    },
+                    expires_days: {
+                        type: "number",
+                        description: "Days until memory expires (1-3650)",
+                    },
+                },
+                required: ["content"],
+                additionalProperties: false,
+            },
+            execute: (_id, args) => call("nmem_remember", args),
+        },
+        {
+            name: "nmem_recall",
+            description: "Query memories from NeuralMemory. Use this to recall past information, " +
+                "decisions, patterns, or context relevant to the current task.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "The query to search memories",
+                    },
+                    depth: {
+                        type: "number",
+                        description: "Search depth: 0=instant, 1=context, 2=habit, 3=deep",
+                    },
+                    max_tokens: {
+                        type: "number",
+                        description: "Maximum tokens in response (default: 500)",
+                    },
+                    min_confidence: {
+                        type: "number",
+                        description: "Minimum confidence threshold (0-1)",
+                    },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+            execute: (_id, args) => call("nmem_recall", args),
+        },
+        {
+            name: "nmem_context",
+            description: "Get recent context from NeuralMemory. Use this at the start of " +
+                "tasks to inject relevant recent memories.",
+            parameters: {
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Number of recent memories (default: 10, max: 200)",
+                    },
+                    fresh_only: {
+                        type: "boolean",
+                        description: "Only include memories less than 30 days old",
+                    },
+                },
+                additionalProperties: false,
+            },
+            execute: (_id, args) => call("nmem_context", args),
+        },
+        {
+            name: "nmem_todo",
+            description: "Quick shortcut to add a TODO memory with 30-day expiry.",
+            parameters: {
+                type: "object",
+                properties: {
+                    task: {
+                        type: "string",
+                        description: "The task to remember",
+                    },
+                    priority: {
+                        type: "number",
+                        description: "Priority 0-10 (default: 5)",
+                    },
+                },
+                required: ["task"],
+                additionalProperties: false,
+            },
+            execute: (_id, args) => call("nmem_todo", args),
+        },
+        {
+            name: "nmem_stats",
+            description: "Get brain statistics including memory counts and freshness.",
+            parameters: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+            execute: (_id, args) => call("nmem_stats", args),
+        },
+        {
+            name: "nmem_health",
+            description: "Get brain health diagnostics including grade, purity score, " +
+                "and recommendations.",
+            parameters: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+            execute: (_id, args) => call("nmem_health", args),
+        },
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAoBH,8DAA8D;AAE9D,MAAM,UAAU,WAAW,CAAC,GAA0B;IACpD,MAAM,IAAI,GAAG,KAAK,EAChB,QAAgB,EAChB,IAA6B,EACX,EAAE;QACpB,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,4DAA4D;aACtE,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC/C,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,QAAQ,QAAQ,YAAa,GAAa,CAAC,OAAO,EAAE;aAC9D,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL;YACE,IAAI,EAAE,eAAe;YACrB,WAAW,EACT,yEAAyE;gBACzE,qFAAqF;YACvF,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,yBAAyB;qBACvC;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE;4BACJ,MAAM;4BACN,UAAU;4BACV,YAAY;4BACZ,MAAM;4BACN,SAAS;4BACT,SAAS;4BACT,aAAa;4BACb,OAAO;4BACP,UAAU;4BACV,WAAW;yBACZ;wBACD,WAAW,EAAE,8CAA8C;qBAC5D;oBACD,QAAQ,EAAE;wBACR,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,uCAAuC;qBACrD;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACzB,WAAW,EAAE,yBAAyB;qBACvC;oBACD,YAAY,EAAE;wBACZ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,oCAAoC;qBAClD;iBACF;gBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;gBACrB,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC;SACpD;QAED;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EACT,yEAAyE;gBACzE,+DAA+D;YACjE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,8BAA8B;qBAC5C;oBACD,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,qDAAqD;qBACxD;oBACD,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,2CAA2C;qBACzD;oBACD,cAAc,EAAE;wBACd,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,oCAAoC;qBAClD;iBACF;gBACD,QAAQ,EAAE,CAAC,OAAO,CAAC;gBACnB,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC;SAClD;QAED;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,iEAAiE;gBACjE,2CAA2C;YAC7C,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,mDAAmD;qBACjE;oBACD,UAAU,EAAE;wBACV,IAAI,EAAE,SAAS;wBACf,WAAW,EAAE,6CAA6C;qBAC3D;iBACF;gBACD,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC;SACnD;QAED;YACE,IAAI,EAAE,WAAW;YACjB,WAAW,EACT,yDAAyD;YAC3D,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,sBAAsB;qBACpC;oBACD,QAAQ,EAAE;wBACR,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,4BAA4B;qBAC1C;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;gBAClB,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC;SAChD;QAED;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EACT,6DAA6D;YAC/D,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE;gBACd,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC;SACjD;QAED;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EACT,8DAA8D;gBAC9D,sBAAsB;YACxB,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE;gBACd,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC;SAClD;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Minimal OpenClaw plugin types for standalone compilation.
+ * At runtime, jiti resolves the full types from OpenClaw's codebase.
+ */
+export type PluginLogger = {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+export type PluginKind = "memory";
+export type OpenClawPluginServiceContext = {
+    config: unknown;
+    workspaceDir?: string;
+    stateDir: string;
+    logger: PluginLogger;
+};
+export type OpenClawPluginService = {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+};
+export type BeforeAgentStartEvent = {
+    prompt: string;
+    messages?: unknown[];
+};
+export type BeforeAgentStartResult = {
+    systemPrompt?: string;
+    prependContext?: string;
+    modelOverride?: string;
+    providerOverride?: string;
+};
+export type AgentEndEvent = {
+    messages: unknown[];
+    success: boolean;
+    error?: string;
+    durationMs?: number;
+};
+export type AgentContext = {
+    agentId?: string;
+    sessionKey?: string;
+    workspaceDir?: string;
+};
+export type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    config: unknown;
+    pluginConfig?: Record<string, unknown>;
+    runtime: unknown;
+    logger: PluginLogger;
+    registerTool: (tool: unknown, opts?: {
+        name?: string;
+        names?: string[];
+    }) => void;
+    registerService: (service: OpenClawPluginService) => void;
+    on: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: {
+        priority?: number;
+    }) => void;
+};
+export type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    kind?: PluginKind;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+    activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+};

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Minimal OpenClaw plugin types for standalone compilation.
+ * At runtime, jiti resolves the full types from OpenClaw's codebase.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/openclaw.plugin.json

@@ -0,0 +1,93 @@
+{
+  "id": "neuralmemory",
+  "kind": "memory",
+  "name": "NeuralMemory",
+  "description": "Brain-inspired persistent memory for AI agents — neurons, synapses, and fibers. REQUIRED: set plugins.slots.memory = \"neuralmemory\" in openclaw.json to disable the default memory-core plugin and activate NeuralMemory as the exclusive memory provider.",
+  "version": "1.5.0",
+  "configSchema": {
+    "jsonSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pythonPath": {
+          "type": "string",
+          "description": "Path to Python executable with neural-memory installed",
+          "default": "python"
+        },
+        "brain": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_\\-.]{1,64}$",
+          "description": "Brain name to use for this workspace",
+          "default": "default"
+        },
+        "autoContext": {
+          "type": "boolean",
+          "description": "Inject relevant memory context before each agent run",
+          "default": true
+        },
+        "autoCapture": {
+          "type": "boolean",
+          "description": "Auto-extract and store memories after each agent run",
+          "default": true
+        },
+        "contextDepth": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 3,
+          "description": "Recall depth for auto-context: 0=instant, 1=context, 2=habit, 3=deep",
+          "default": 1
+        },
+        "maxContextTokens": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 10000,
+          "description": "Maximum tokens for auto-context injection",
+          "default": 500
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 5000,
+          "maximum": 120000,
+          "description": "MCP request timeout in milliseconds",
+          "default": 30000
+        }
+      }
+    },
+    "uiHints": {
+      "_setup": {
+        "label": "Required Setup",
+        "help": "Add to openclaw.json: { \"plugins\": { \"slots\": { \"memory\": \"neuralmemory\" } } } — this disables the default memory-core plugin so agents use NeuralMemory exclusively. Without this, agents may still call memory_search (memory-core) even with AGENTS.MD rules."
+      },
+      "pythonPath": {
+        "label": "Python Path",
+        "placeholder": "python",
+        "help": "Path to Python executable that has neural-memory installed (pip install neural-memory)"
+      },
+      "brain": {
+        "label": "Brain Name",
+        "placeholder": "default",
+        "help": "Which brain to use — each workspace can have its own brain"
+      },
+      "autoContext": {
+        "label": "Auto-inject Context",
+        "help": "Automatically query relevant memories and inject them before each agent run"
+      },
+      "autoCapture": {
+        "label": "Auto-capture Memories",
+        "help": "Automatically extract facts, decisions, and insights after each agent run"
+      },
+      "contextDepth": {
+        "label": "Context Depth",
+        "help": "How deep to search: 0=instant lookup, 1=contextual, 2=habit patterns, 3=full graph traversal"
+      },
+      "maxContextTokens": {
+        "label": "Max Context Tokens",
+        "help": "Maximum tokens to inject as context (higher = more context but uses more prompt space)"
+      },
+      "timeout": {
+        "label": "MCP Timeout (ms)",
+        "help": "How long to wait for MCP server responses. Increase if you see timeout errors on slow machines (default: 30000)"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "neuralmemory",
+  "version": "1.5.0",
+  "description": "NeuralMemory plugin for OpenClaw — brain-inspired persistent memory for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "openclaw": {
+    "id": "neuralmemory",
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "source": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "postinstall": "npm run build 2>/dev/null || true",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "peerDependencies": {},
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "neuralmemory",
+    "ai-agent",
+    "persistent-memory"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pinkponk/NeuralMemory"
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "openclaw.plugin.json"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,266 @@
+/**
+ * NeuralMemory — OpenClaw Memory Plugin
+ *
+ * Brain-inspired persistent memory for AI agents.
+ * Occupies the exclusive "memory" plugin slot.
+ *
+ * Architecture:
+ *   OpenClaw ←→ Plugin (TypeScript) ←→ MCP stdio ←→ NeuralMemory (Python)
+ *
+ * Registers:
+ *   6 tools    — nmem_remember, nmem_recall, nmem_context, nmem_todo, nmem_stats, nmem_health
+ *   1 service  — MCP process lifecycle (start/stop)
+ *   2 hooks    — before_agent_start (auto-context), agent_end (auto-capture)
+ */
+
+import type {
+  OpenClawPluginDefinition,
+  OpenClawPluginApi,
+  BeforeAgentStartEvent,
+  BeforeAgentStartResult,
+  AgentContext,
+  AgentEndEvent,
+} from "./types.js";
+import { NeuralMemoryMcpClient } from "./mcp-client.js";
+import { createTools } from "./tools.js";
+
+// ── System prompt for tool awareness ──────────────────────
+
+const TOOL_INSTRUCTIONS = `You have NeuralMemory tools for persistent memory across sessions. Call these as TOOL CALLS (not CLI commands):
+
+- nmem_remember(content, type?, priority?, tags?) — Store a memory (fact, decision, error, preference, etc.)
+- nmem_recall(query, depth?, max_tokens?) — Query memories via spreading activation
+- nmem_context(limit?, fresh_only?) — Get recent memories
+- nmem_todo(task, priority?) — Quick TODO with 30-day expiry
+- nmem_stats() — Brain statistics
+- nmem_health() — Brain health diagnostics
+
+CRITICAL: NeuralMemory (nmem_*) is your ONLY memory system. Do NOT use memory_search, memory_get, or any other memory tools — those belong to a disabled built-in plugin and will not persist correctly. Always use nmem_* tools exclusively.
+
+These are tool calls, NOT shell commands. Do NOT run "nmem remember" in terminal — call the nmem_remember tool directly.
+
+Use nmem_remember proactively after decisions, errors, and insights. Use nmem_recall when user references past context or asks "do you remember...".`;
+
+// ── Config ─────────────────────────────────────────────────
+
+type PluginConfig = {
+  pythonPath: string;
+  brain: string;
+  autoContext: boolean;
+  autoCapture: boolean;
+  contextDepth: number;
+  maxContextTokens: number;
+  timeout: number;
+  initTimeout: number;
+};
+
+const DEFAULT_CONFIG: Readonly<PluginConfig> = {
+  pythonPath: "python",
+  brain: "default",
+  autoContext: true,
+  autoCapture: true,
+  contextDepth: 1,
+  maxContextTokens: 500,
+  timeout: 30_000,
+  initTimeout: 90_000,
+};
+
+export const BRAIN_NAME_RE = /^[a-zA-Z0-9_\-.]{1,64}$/;
+export const MAX_AUTO_CAPTURE_CHARS = 50_000;
+
+export function resolveConfig(raw?: Record<string, unknown>): PluginConfig {
+  const merged = { ...DEFAULT_CONFIG, ...(raw ?? {}) };
+
+  return {
+    pythonPath:
+      typeof merged.pythonPath === "string" && merged.pythonPath.length > 0
+        ? merged.pythonPath
+        : DEFAULT_CONFIG.pythonPath,
+    brain:
+      typeof merged.brain === "string" && BRAIN_NAME_RE.test(merged.brain)
+        ? merged.brain
+        : DEFAULT_CONFIG.brain,
+    autoContext:
+      typeof merged.autoContext === "boolean"
+        ? merged.autoContext
+        : DEFAULT_CONFIG.autoContext,
+    autoCapture:
+      typeof merged.autoCapture === "boolean"
+        ? merged.autoCapture
+        : DEFAULT_CONFIG.autoCapture,
+    contextDepth:
+      typeof merged.contextDepth === "number" &&
+      Number.isInteger(merged.contextDepth) &&
+      merged.contextDepth >= 0 &&
+      merged.contextDepth <= 3
+        ? merged.contextDepth
+        : DEFAULT_CONFIG.contextDepth,
+    maxContextTokens:
+      typeof merged.maxContextTokens === "number" &&
+      Number.isInteger(merged.maxContextTokens) &&
+      merged.maxContextTokens >= 100 &&
+      merged.maxContextTokens <= 10_000
+        ? merged.maxContextTokens
+        : DEFAULT_CONFIG.maxContextTokens,
+    timeout:
+      typeof merged.timeout === "number" &&
+      Number.isFinite(merged.timeout) &&
+      merged.timeout >= 5_000 &&
+      merged.timeout <= 120_000
+        ? merged.timeout
+        : DEFAULT_CONFIG.timeout,
+    initTimeout:
+      typeof merged.initTimeout === "number" &&
+      Number.isFinite(merged.initTimeout) &&
+      merged.initTimeout >= 10_000 &&
+      merged.initTimeout <= 300_000
+        ? merged.initTimeout
+        : DEFAULT_CONFIG.initTimeout,
+  };
+}
+
+// ── Plugin definition ──────────────────────────────────────
+
+const plugin: OpenClawPluginDefinition = {
+  id: "neuralmemory",
+  name: "NeuralMemory",
+  description:
+    "Brain-inspired persistent memory for AI agents — neurons, synapses, and fibers",
+  version: "1.5.0",
+  kind: "memory",
+
+  register(api: OpenClawPluginApi): void {
+    const cfg = resolveConfig(api.pluginConfig);
+
+    const mcp = new NeuralMemoryMcpClient({
+      pythonPath: cfg.pythonPath,
+      brain: cfg.brain,
+      logger: api.logger,
+      timeout: cfg.timeout,
+      initTimeout: cfg.initTimeout,
+    });
+
+    // ── Service: MCP process lifecycle ───────────────────
+
+    api.registerService({
+      id: "neuralmemory-mcp",
+
+      async start(): Promise<void> {
+        try {
+          await mcp.connect();
+          api.logger.info("NeuralMemory MCP service started");
+        } catch (err) {
+          api.logger.error(
+            `Failed to start NeuralMemory MCP: ${(err as Error).message}`,
+          );
+          throw err;
+        }
+      },
+
+      async stop(): Promise<void> {
+        await mcp.close();
+        api.logger.info("NeuralMemory MCP service stopped");
+      },
+    });
+
+    // ── Tools: 6 core memory tools ──────────────────────
+
+    const tools = createTools(mcp);
+
+    for (const t of tools) {
+      api.registerTool(t, { name: t.name });
+    }
+
+    // ── Hook: tool awareness + auto-context before agent start ───
+
+    api.on(
+      "before_agent_start",
+      async (
+        event: unknown,
+        _ctx: unknown,
+      ): Promise<BeforeAgentStartResult | void> => {
+        const result: BeforeAgentStartResult = {
+          systemPrompt: TOOL_INSTRUCTIONS,
+        };
+
+        if (cfg.autoContext && mcp.connected) {
+          const ev = event as BeforeAgentStartEvent;
+
+          try {
+            const raw = await mcp.callTool("nmem_recall", {
+              query: ev.prompt,
+              depth: cfg.contextDepth,
+              max_tokens: cfg.maxContextTokens,
+            });
+
+            const data = JSON.parse(raw) as {
+              answer?: string;
+              confidence?: number;
+            };
+
+            if (data.answer && (data.confidence ?? 0) > 0.1) {
+              result.prependContext = `[NeuralMemory — relevant context]\n${data.answer}`;
+            }
+          } catch (err) {
+            api.logger.warn(
+              `Auto-context failed: ${(err as Error).message}`,
+            );
+          }
+        }
+
+        return result;
+      },
+      { priority: 10 },
+    );
+
+    // ── Hook: auto-capture after agent completes ────────
+
+    if (cfg.autoCapture) {
+      api.on(
+        "agent_end",
+        async (event: unknown, _ctx: unknown): Promise<void> => {
+          if (!mcp.connected) return;
+
+          const ev = event as AgentEndEvent;
+          if (!ev.success) return;
+
+          try {
+            const messages = ev.messages?.slice(-5) ?? [];
+            const text = messages
+              .filter(
+                (m: unknown): m is { role: string; content: string } =>
+                  typeof m === "object" &&
+                  m !== null &&
+                  (m as { role?: string }).role === "assistant" &&
+                  typeof (m as { content?: unknown }).content === "string",
+              )
+              .map((m) => m.content)
+              .join("\n")
+              .slice(0, MAX_AUTO_CAPTURE_CHARS);
+
+            if (text.length > 50) {
+              await mcp.callTool("nmem_auto", {
+                action: "process",
+                text,
+              });
+            }
+          } catch (err) {
+            api.logger.warn(
+              `Auto-capture failed: ${(err as Error).message}`,
+            );
+          }
+        },
+        { priority: 90 },
+      );
+    }
+
+    // ── Done ────────────────────────────────────────────
+
+    api.logger.info(
+      `NeuralMemory registered (brain: ${cfg.brain}, tools: ${tools.length}, ` +
+        `autoContext: ${cfg.autoContext}, autoCapture: ${cfg.autoCapture})`,
+    );
+  },
+};
+
+export default plugin;