neuralmemory 1.5.0

package/src/mcp-client.ts

@@ -0,0 +1,322 @@
+/**
+ * NeuralMemory MCP Client — JSON-RPC 2.0 over stdio.
+ *
+ * Spawns `python -m neural_memory.mcp` and communicates using the
+ * MCP protocol (newline-delimited JSON Lines).
+ *
+ * Zero external dependencies — implements the protocol directly.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import type { PluginLogger } from "./types.js";
+
+// ── Types ──────────────────────────────────────────────────
+
+type PendingRequest = {
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (error: Error) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+};
+
+type JsonRpcMessage = {
+  jsonrpc: "2.0";
+  id?: number;
+  method?: string;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+export type McpClientOptions = {
+  readonly pythonPath: string;
+  readonly brain: string;
+  readonly logger: PluginLogger;
+  readonly timeout?: number;
+  readonly initTimeout?: number;
+};
+
+// ── Constants ──────────────────────────────────────────────
+
+const PROTOCOL_VERSION = "2024-11-05";
+const DEFAULT_TIMEOUT = 30_000;
+const CLIENT_NAME = "openclaw-neuralmemory";
+const CLIENT_VERSION = "1.5.0";
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024; // 10 MB safety cap
+const MAX_STDERR_LINES = 50;
+
+/** Env vars forwarded to the MCP child process (least-privilege). */
+export const ALLOWED_ENV_KEYS: ReadonlySet<string> = new Set([
+  "PATH",
+  "PATHEXT",
+  "HOME",
+  "USERPROFILE",
+  "SYSTEMROOT",
+  "TEMP",
+  "TMP",
+  "LANG",
+  "LC_ALL",
+  "VIRTUAL_ENV",
+  "CONDA_PREFIX",
+  "PYTHONPATH",
+  "PYTHONHOME",
+  "NEURALMEMORY_DIR",
+  "NEURALMEMORY_BRAIN",
+  "NEURAL_MEMORY_DIR",
+  "NEURAL_MEMORY_JSON",
+  "NEURAL_MEMORY_DEBUG",
+]);
+
+// ── Client ─────────────────────────────────────────────────
+
+export class NeuralMemoryMcpClient {
+  private proc: ChildProcess | null = null;
+  private requestId = 0;
+  private readonly pending = new Map<number, PendingRequest>();
+  private rawBuffer: Buffer = Buffer.alloc(0);
+  private readonly pythonPath: string;
+  private readonly brain: string;
+  private readonly logger: PluginLogger;
+  private readonly timeout: number;
+  private readonly initTimeout: number;
+  private _connected = false;
+
+  constructor(options: McpClientOptions) {
+    this.pythonPath = options.pythonPath;
+    this.brain = options.brain;
+    this.logger = options.logger;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.initTimeout = options.initTimeout ?? 90_000;
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  async connect(): Promise<void> {
+    const env = buildChildEnv(this.brain);
+
+    this.proc = spawn(this.pythonPath, ["-m", "neural_memory.mcp"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env,
+    });
+
+    this.proc.stdout!.on("data", (chunk: Buffer) => {
+      this.rawBuffer = Buffer.concat([this.rawBuffer, chunk]);
+      if (this.rawBuffer.length > MAX_BUFFER_BYTES) {
+        this.logger.error(
+          `MCP buffer exceeded ${MAX_BUFFER_BYTES} bytes — killing process`,
+        );
+        this.proc?.kill("SIGKILL");
+        return;
+      }
+      this.drainBuffer();
+    });
+
+    const stderrChunks: string[] = [];
+
+    this.proc.stderr!.on("data", (chunk: Buffer) => {
+      const msg = chunk.toString("utf-8").trim();
+      if (msg) {
+        if (stderrChunks.length < MAX_STDERR_LINES) {
+          stderrChunks.push(msg);
+        }
+        this.logger.warn(`[mcp stderr] ${msg}`);
+      }
+    });
+
+    this.proc.on("exit", (code) => {
+      this._connected = false;
+      const hint =
+        code === 1
+          ? " — check that neural-memory is installed: pip install neural-memory"
+          : "";
+      this.rejectAll(new Error(`MCP process exited with code ${code}${hint}`));
+      this.logger.error(`MCP process exited (code: ${code})${hint}`);
+    });
+
+    this.proc.on("error", (err) => {
+      this._connected = false;
+      const hint =
+        err.message.includes("ENOENT")
+          ? ` — "${this.pythonPath}" not found. Check pythonPath in plugin config.`
+          : "";
+      this.rejectAll(new Error(`MCP process error: ${err.message}${hint}`));
+      this.logger.error(`MCP process error: ${err.message}${hint}`);
+    });
+
+    // MCP initialize handshake (uses longer timeout for cold starts)
+    try {
+      await this.send("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: CLIENT_NAME, version: CLIENT_VERSION },
+      }, this.initTimeout);
+    } catch (err) {
+      const stderr = stderrChunks.join("\n");
+      const detail = stderr
+        ? `\nPython stderr:\n${stderr}`
+        : "\nNo stderr output — the Python process may have hung.";
+      throw new Error(
+        `MCP initialize failed: ${(err as Error).message}${detail}\n` +
+          `Verify: ${this.pythonPath} -m neural_memory.mcp`,
+      );
+    }
+
+    // Send initialized notification (no response expected)
+    this.notify("notifications/initialized", {});
+
+    this._connected = true;
+    this.logger.info(
+      `MCP connected (brain: ${this.brain}, protocol: ${PROTOCOL_VERSION})`,
+    );
+  }
+
+  async callTool(
+    name: string,
+    args: Record<string, unknown> = {},
+  ): Promise<string> {
+    const result = (await this.send("tools/call", {
+      name,
+      arguments: args,
+    })) as { content?: Array<{ type: string; text: string }>; isError?: boolean };
+
+    if (result.isError) {
+      const text = result.content?.[0]?.text ?? "Unknown MCP error";
+      throw new Error(text);
+    }
+
+    return result.content?.[0]?.text ?? "";
+  }
+
+  async close(): Promise<void> {
+    this._connected = false;
+    this.rejectAll(new Error("Client closing"));
+
+    const proc = this.proc;
+    this.proc = null;
+    this.rawBuffer = Buffer.alloc(0);
+
+    if (proc) {
+      proc.removeAllListeners();
+      proc.stdout?.removeAllListeners();
+      proc.stderr?.removeAllListeners();
+
+      const exited = new Promise<void>((resolve) => {
+        proc.once("exit", () => resolve());
+        setTimeout(() => {
+          proc.kill("SIGKILL");
+          resolve();
+        }, 3_000);
+      });
+
+      proc.kill("SIGTERM");
+      await exited;
+    }
+
+    this.logger.info("MCP client closed");
+  }
+
+  // ── JSON-RPC protocol layer ──────────────────────────────
+
+  private send(method: string, params: unknown, timeoutOverride?: number): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (!this.proc?.stdin?.writable) {
+        reject(new Error("MCP process not available"));
+        return;
+      }
+
+      const id = ++this.requestId;
+      const ms = timeoutOverride ?? this.timeout;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`MCP timeout: ${method} (${ms}ms)`));
+      }, ms);
+
+      this.pending.set(id, { resolve, reject, timer });
+      this.writeMessage({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  private notify(method: string, params: unknown): void {
+    if (!this.proc?.stdin?.writable) return;
+    this.writeMessage({ jsonrpc: "2.0", method, params });
+  }
+
+  private writeMessage(message: object): void {
+    if (!this.proc?.stdin?.writable) return;
+    const json = JSON.stringify(message);
+    const frame = `${json}\n`;
+    this.proc.stdin.write(frame);
+  }
+
+  // ── Response parsing (newline-delimited JSON Lines) ────────
+
+  private drainBuffer(): void {
+    while (true) {
+      const newlineIndex = this.rawBuffer.indexOf("\n");
+      if (newlineIndex === -1) break;
+
+      const line = this.rawBuffer.subarray(0, newlineIndex).toString("utf-8");
+      this.rawBuffer = this.rawBuffer.subarray(newlineIndex + 1);
+
+      if (!line.trim()) continue;
+
+      try {
+        const message = JSON.parse(line) as JsonRpcMessage;
+        this.handleMessage(message);
+      } catch (err) {
+        this.logger.error(
+          `Failed to parse MCP message: ${(err as Error).message}`,
+        );
+      }
+    }
+  }
+
+  private handleMessage(message: JsonRpcMessage): void {
+    // Notifications (no id) — ignore silently
+    if (message.id == null) return;
+
+    const pending = this.pending.get(message.id);
+    if (!pending) return;
+
+    this.pending.delete(message.id);
+    clearTimeout(pending.timer);
+
+    if (message.error) {
+      pending.reject(
+        new Error(
+          `MCP error ${message.error.code}: ${message.error.message}`,
+        ),
+      );
+    } else {
+      pending.resolve(message.result);
+    }
+  }
+
+  private rejectAll(error: Error): void {
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────
+
+/** Build a minimal env for the child process (least-privilege). */
+export function buildChildEnv(brain: string): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of ALLOWED_ENV_KEYS) {
+    const value = process.env[key];
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
+
+  if (brain !== "default") {
+    env.NEURALMEMORY_BRAIN = brain;
+  }
+
+  return env;
+}

package/src/tools.ts

@@ -0,0 +1,218 @@
+/**
+ * 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
+ */
+
+import type { NeuralMemoryMcpClient } from "./mcp-client.js";
+
+// ── Types ──────────────────────────────────────────────────
+
+type JsonSchema = {
+  readonly type: "object";
+  readonly properties: Record<string, unknown>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean;
+};
+
+export type ToolDefinition = {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: JsonSchema;
+  readonly execute: (id: string, args: Record<string, unknown>) => Promise<unknown>;
+};
+
+// ── Tool factory ───────────────────────────────────────────
+
+export function createTools(mcp: NeuralMemoryMcpClient): ToolDefinition[] {
+  const call = async (
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<unknown> => {
+    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 as Error).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),
+    },
+  ];
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * 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;     // Appended to system prompt — last handler wins
+  prependContext?: string;   // Prepended to conversation context — all handlers concatenated
+  modelOverride?: string;    // Override model for this run — first defined wins
+  providerOverride?: string; // Override provider for this run — first defined wins
+};
+
+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>;
+};