openclaw-memory-atmem 1.0.0

package/dist/src/rpc-client.js

@@ -0,0 +1,190 @@
+/**
+ * Newline-delimited JSON-RPC 2.0 client for the `atmem mcp` stdio server.
+ *
+ * The child process is spawned lazily on first call, the MCP initialize
+ * handshake runs once, and calls are matched to responses by request id.
+ * If the child dies it is respawned on the next call.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+export class AtmemClient {
+    options;
+    child = null;
+    reader = null;
+    pending = new Map();
+    nextId = 1;
+    initialized = null;
+    idleTimer = null;
+    toolNames = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Verify that the engine starts and completes the MCP handshake. */
+    async connect() {
+        try {
+            this.cancelIdleClose();
+            await this.ensureInitialized();
+        }
+        finally {
+            this.scheduleIdleClose();
+        }
+    }
+    /** Call an MCP tool; returns the parsed JSON payload of the text block. */
+    async callTool(name, args, timeoutMs) {
+        try {
+            this.cancelIdleClose();
+            await this.ensureInitialized();
+            const result = (await this.request("tools/call", { name, arguments: args }, timeoutMs));
+            const text = result?.content?.[0]?.text ?? "";
+            if (result?.isError) {
+                throw new Error(`atmem tool ${name} failed: ${text}`);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+        finally {
+            this.scheduleIdleClose();
+        }
+    }
+    /** Discover optional server capabilities without assuming a package version. */
+    async hasTool(name, timeoutMs) {
+        try {
+            this.cancelIdleClose();
+            if (this.toolNames === null) {
+                await this.ensureInitialized();
+                const result = (await this.request("tools/list", {}, timeoutMs));
+                this.toolNames = new Set((result?.tools ?? [])
+                    .map((tool) => String(tool.name ?? ""))
+                    .filter(Boolean));
+            }
+            return this.toolNames.has(name);
+        }
+        finally {
+            this.scheduleIdleClose();
+        }
+    }
+    close() {
+        this.cancelIdleClose();
+        if (this.child) {
+            this.child.stdin.end();
+            this.child.kill();
+        }
+        this.teardown(new Error("client closed"));
+    }
+    cancelIdleClose() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = null;
+    }
+    scheduleIdleClose() {
+        this.cancelIdleClose();
+        const timeout = this.options.idleTimeoutMs ?? 250;
+        this.idleTimer = setTimeout(() => this.close(), timeout);
+    }
+    async ensureInitialized() {
+        if (!this.child || this.child.exitCode !== null) {
+            this.startChild();
+            this.initialized = this.handshake();
+        }
+        await this.initialized;
+    }
+    startChild() {
+        const { command, args } = this.options;
+        this.options.log?.(`[atmem] spawning: ${command} ${args.join(" ")}`);
+        const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+        this.child = child;
+        this.reader = createInterface({ input: child.stdout });
+        this.reader.on("line", (line) => this.onLine(line));
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString().trim();
+            if (text)
+                this.options.logError?.(`[atmem stderr] ${text}`);
+        });
+        child.on("exit", (code) => {
+            this.options.logError?.(`[atmem] server exited (code ${code})`);
+            this.teardown(new Error(`atmem server exited (code ${code})`));
+        });
+        child.on("error", (error) => {
+            const spawnError = error;
+            const actionable = spawnError.code === "ENOENT"
+                ? new Error(`AtMem engine executable '${command}' was not found. ` +
+                    "Install the engine first with `python3 -m pip install atmem`, " +
+                    "verify `atmem --version`, or set the plugin `command` option " +
+                    "to the executable's absolute path.")
+                : error instanceof Error
+                    ? error
+                    : new Error(String(error));
+            this.options.logError?.(`[atmem] spawn failed: ${actionable.message}`);
+            this.teardown(actionable);
+        });
+    }
+    async handshake() {
+        await this.request("initialize", {
+            protocolVersion: "2025-06-18",
+            capabilities: {},
+            clientInfo: {
+                name: "openclaw-memory-atmem",
+                version: "1.0.0",
+            },
+        });
+        this.notify("notifications/initialized", {});
+    }
+    request(method, params, timeoutMs) {
+        const child = this.child;
+        if (!child)
+            return Promise.reject(new Error("atmem server not running"));
+        const id = this.nextId++;
+        const timeout = timeoutMs ?? this.options.defaultTimeoutMs ?? 10_000;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`atmem ${method} timed out after ${timeout}ms`));
+            }, timeout);
+            this.pending.set(id, { resolve, reject, timer });
+            child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+        });
+    }
+    notify(method, params) {
+        this.child?.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    }
+    onLine(line) {
+        if (!line.trim())
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            this.options.logError?.(`[atmem] unparseable line: ${line.slice(0, 200)}`);
+            return;
+        }
+        if (message.id === undefined)
+            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(`atmem rpc error ${message.error.code}: ${message.error.message}`));
+        }
+        else {
+            pending.resolve(message.result);
+        }
+    }
+    teardown(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        this.reader?.close();
+        this.reader = null;
+        this.child = null;
+        this.initialized = null;
+    }
+}

package/dist/src/setup.js

@@ -0,0 +1,120 @@
+import { accessSync, constants } from "node:fs";
+import { delimiter, isAbsolute } from "node:path";
+import { spawnSync } from "node:child_process";
+function executableExists(command) {
+    if (command.includes("/") || isAbsolute(command)) {
+        try {
+            accessSync(command, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return (process.env.PATH ?? "")
+        .split(delimiter)
+        .some((entry) => {
+        try {
+            accessSync(`${entry}/${command}`, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function currentOpenClawInvocation() {
+    const script = process.argv[1];
+    if (script && /node(?:\.exe)?$/i.test(process.execPath)) {
+        return { command: process.execPath, prefix: [script] };
+    }
+    return { command: process.argv[0] || "openclaw", prefix: [] };
+}
+export function setupWrites(options) {
+    const config = {
+        command: options.command,
+        dbPath: options.dbPath,
+        subject: options.subject,
+        recall: {
+            enabled: true,
+            maxRecords: 3,
+            maxChars: 1200,
+            minScore: 0.3,
+            timeoutMs: 3000,
+        },
+        persona: { enabled: true, maxChars: 600, ttlSeconds: 300 },
+        capture: { enabled: true, captureAssistant: true },
+        cacheAware: { enabled: true, compactReferences: true },
+        tools: { enabled: true },
+    };
+    return [
+        ["plugins.entries.memory-atmem.enabled", "true", true],
+        ["plugins.entries.memory-atmem.hooks.allowConversationAccess", "true", true],
+        [
+            "plugins.entries.memory-atmem.config.command",
+            JSON.stringify(config.command),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.dbPath",
+            JSON.stringify(config.dbPath),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.subject",
+            JSON.stringify(config.subject),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.recall",
+            JSON.stringify(config.recall),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.persona",
+            JSON.stringify(config.persona),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.capture",
+            JSON.stringify(config.capture),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.cacheAware",
+            JSON.stringify(config.cacheAware),
+            true,
+        ],
+        [
+            "plugins.entries.memory-atmem.config.tools",
+            JSON.stringify(config.tools),
+            true,
+        ],
+    ];
+}
+export async function runSetup(options, dependencies = {}) {
+    if (!options.subject.trim())
+        throw new Error("--subject must not be empty");
+    if (!executableExists(options.command)) {
+        throw new Error(`AtMem executable not found: ${options.command}. Run: python3 -m pip install --upgrade atmem`);
+    }
+    const invocation = dependencies.invocation ?? currentOpenClawInvocation();
+    const runner = dependencies.runner ?? ((command, args) => spawnSync(command, args, { stdio: "inherit" }));
+    for (const [key, value, strictJson] of setupWrites(options)) {
+        const args = [...invocation.prefix, "config", "set", key, value];
+        if (strictJson)
+            args.push("--strict-json");
+        const result = runner(invocation.command, args);
+        if (result.status !== 0) {
+            throw new Error(`OpenClaw rejected configuration key: ${key}`);
+        }
+    }
+    if (options.restart) {
+        const result = runner(invocation.command, [...invocation.prefix, "gateway", "restart"]);
+        if (result.status !== 0) {
+            throw new Error("Configuration was saved, but the OpenClaw gateway restart failed");
+        }
+    }
+    process.stdout.write("AtMem bounded recall and capture are configured. " +
+        "Use `atmem openclaw install` for verified shadowing and reversible activation.\n");
+}

package/dist/src/types.js

@@ -0,0 +1,7 @@
+/**
+ * Minimal structural types for the OpenClaw plugin API surface this plugin
+ * uses. Kept local (instead of importing "openclaw/plugin-sdk/core") so the
+ * plugin builds without the SDK on the compile path; the shapes match the
+ * hook/tool contracts observed in OpenClaw's plugin SDK.
+ */
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,120 @@
+{
+  "id": "memory-atmem",
+  "name": "Memory (atmem)",
+  "description": "OpenClaw bridge installed and managed by the AtMem memory control plane.",
+  "version": "1.0.0",
+  "commandAliases": ["memory-atmem"],
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "memory_search",
+      "memory_get",
+      "memory_remember",
+      "atmem_search",
+      "atmem_forget",
+      "atmem_observe",
+      "atmem_forget_artifact"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "command": {
+        "type": "string",
+        "default": "atmem",
+        "description": "Executable that serves the engine (absolute path if not on PATH, e.g. /path/to/venv/bin/atmem). Use a python binary together with commandArgs [\"-m\",\"atmem.cli\",\"mcp\",...] as an alternative."
+      },
+      "commandArgs": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Override the full argument list. Default: [\"mcp\", \"--db\", <dbPath>, \"--subject\", <subject>]"
+      },
+      "dbPath": {
+        "type": "string",
+        "default": "~/.atmem/memories.db",
+        "description": "SQLite database path (also auditable from outside OpenClaw via `atmem verify`)"
+      },
+      "subject": {
+        "type": "string",
+        "default": "default",
+        "description": "Subject id used for all memory operations (single-user assistant)"
+      },
+      "takeoverActive": {
+        "type": "boolean",
+        "default": false,
+        "description": "Set only by verified native-memory takeover. Adds system guidance requiring memory_search/memory_get and forbidding direct MEMORY.md or memory/* filesystem access."
+      },
+      "nativeWorkspace": {
+        "type": "string",
+        "description": "Absolute OpenClaw workspace path protected during verified takeover. Set by `atmem control activate`; do not configure manually."
+      },
+      "recall": {
+        "type": "object",
+        "description": "Auto-recall injection before each prompt",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "maxRecords": { "type": "number", "default": 3, "description": "Max memories injected per turn" },
+          "maxChars": { "type": "number", "default": 1200, "description": "Total character budget for the injected block" },
+          "minScore": { "type": "number", "default": 0.3, "description": "Minimum relevance score; 0.3 requires a lexical match (priors alone never inject)" },
+          "timeoutMs": { "type": "number", "default": 4000, "description": "Recall timeout; on timeout the turn proceeds without injection" }
+        }
+      },
+      "persona": {
+        "type": "object",
+        "description": "L3 persona snapshot injected alongside recall",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "maxChars": { "type": "number", "default": 600, "description": "Character budget for the <user_persona> block" },
+          "ttlSeconds": { "type": "number", "default": 300, "description": "Persona cache lifetime; also invalidated whenever new memory is captured" }
+        }
+      },
+      "capture": {
+        "type": "object",
+        "description": "Auto-capture after each turn",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "captureAssistant": { "type": "boolean", "default": true, "description": "Log assistant replies to the audit chain (digest only, never stored as memory)" }
+        }
+      },
+      "cacheAware": {
+        "type": "object",
+        "description": "Preserve a stable cacheable system prefix and place query-specific recall at the prompt tail",
+        "properties": {
+          "enabled": { "type": "boolean", "default": false, "description": "Use appendSystemContext for persona and appendContext for recall; false preserves pre-0.2.4 layout" },
+          "compactReferences": { "type": "boolean", "default": true, "description": "Use short model-visible references while full record IDs remain in audit evidence" }
+        }
+      },
+      "tools": {
+        "type": "object",
+        "description": "Agent-callable explicit memory tools; automatic recall/capture continue when disabled",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true, "description": "Register atmem_search and atmem_forget tool schemas" }
+        }
+      },
+      "controlPlane": {
+        "type": "object",
+        "description": "Reversible memory control plane. Shadow mode does not change model context; active mode replaces native supplemental memory.",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Route hooks through the private memory control plane protocol; agent-callable memory tools are disabled in shadow mode."
+          },
+          "statePath": {
+            "type": "string",
+            "default": "~/.atmem/control-plane.json",
+            "description": "Digest-bound control file written by `atmem control`."
+          },
+          "blackboxEnabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Record content-minimizing agent flights through the private control protocol. Managed automatically by the AtMem installer."
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "openclaw-memory-atmem",
+  "version": "1.0.0",
+  "description": "OpenClaw Agent Black Box and memory control-plane bridge for AtMem",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aetna000/atmem.git",
+    "directory": "integrations/openclaw"
+  },
+  "homepage": "https://github.com/aetna000/atmem/tree/main/integrations/openclaw",
+  "bugs": {
+    "url": "https://github.com/aetna000/atmem/issues"
+  },
+  "license": "AGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.7.1-2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node test/setup.mjs && node test/hooks.mjs",
+    "smoke": "node test/smoke.mjs",
+    "prepack": "npm run build && npm run typecheck && npm test && npm run smoke"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "5.6"
+  }
+}