@basicmemory/openclaw-basic-memory 0.2.3 → 0.23.0

package/dist/bm-client.js

@@ -0,0 +1,582 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { log } from "./logger.js";
+const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000];
+export class NoteAlreadyExistsError extends Error {
+    permalink;
+    constructor(title, permalink) {
+        super(`Note already exists: "${title}" (${permalink})`);
+        this.name = "NoteAlreadyExistsError";
+        this.permalink = permalink;
+    }
+}
+const REQUIRED_TOOLS = [
+    "search_notes",
+    "read_note",
+    "write_note",
+    "edit_note",
+    "build_context",
+    "recent_activity",
+    "list_memory_projects",
+    "list_workspaces",
+    "create_memory_project",
+    "delete_note",
+    "move_note",
+    "schema_validate",
+    "schema_infer",
+    "schema_diff",
+];
+function getErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function extractTextFromContent(content) {
+    if (!Array.isArray(content))
+        return "";
+    const textBlocks = content
+        .filter((block) => isRecord(block) &&
+        block.type === "text" &&
+        typeof block.text === "string")
+        .map((block) => block.text);
+    return textBlocks.join("\n").trim();
+}
+function isRecoverableConnectionError(err) {
+    const msg = getErrorMessage(err).toLowerCase();
+    return (msg.includes("connection closed") ||
+        msg.includes("not connected") ||
+        msg.includes("transport") ||
+        msg.includes("broken pipe") ||
+        msg.includes("econnreset") ||
+        msg.includes("epipe") ||
+        msg.includes("failed to start bm mcp stdio") ||
+        msg.includes("client is closed"));
+}
+function isNoteNotFoundError(err) {
+    const msg = getErrorMessage(err).toLowerCase();
+    return (msg.includes("entity not found") ||
+        msg.includes("note not found") ||
+        msg.includes("resource not found") ||
+        msg.includes("could not find note matching") ||
+        msg.includes("404"));
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function projectMatchesWorkspace(project, workspace) {
+    const requested = workspace.trim().toLowerCase();
+    if (!requested)
+        return true;
+    return [
+        project.workspace_name,
+        project.workspace_slug,
+        project.workspace_tenant_id,
+    ].some((value) => typeof value === "string" && value.toLowerCase() === requested);
+}
+export class BmClient {
+    bmPath;
+    project;
+    cwd;
+    env;
+    shouldRun = false;
+    client = null;
+    transport = null;
+    connectPromise = null;
+    retryDelaysMs = [...DEFAULT_RETRY_DELAYS_MS];
+    constructor(bmPath, project) {
+        this.bmPath = bmPath;
+        this.project = project;
+    }
+    async start(options) {
+        this.shouldRun = true;
+        if (options?.cwd) {
+            this.cwd = options.cwd;
+        }
+        if (options?.env) {
+            this.env = options.env;
+        }
+        await this.connectWithRetries();
+    }
+    async stop() {
+        this.shouldRun = false;
+        await this.disconnectCurrent(this.client, this.transport);
+        this.client = null;
+        this.transport = null;
+    }
+    async connectWithRetries() {
+        let lastErr;
+        for (let attempt = 0; attempt <= this.retryDelaysMs.length; attempt++) {
+            try {
+                await this.ensureConnected();
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                await this.disconnectCurrent(this.client, this.transport);
+                this.client = null;
+                this.transport = null;
+                if (attempt === this.retryDelaysMs.length) {
+                    break;
+                }
+                const waitMs = this.retryDelaysMs[attempt];
+                log.warn(`BM MCP connect failed (attempt ${attempt + 1}/${this.retryDelaysMs.length + 1}): ${getErrorMessage(err)}; retrying in ${waitMs}ms`);
+                await delay(waitMs);
+            }
+        }
+        throw new Error(`BM MCP unavailable: ${getErrorMessage(lastErr)}`);
+    }
+    async ensureConnected() {
+        if (!this.shouldRun) {
+            this.shouldRun = true;
+        }
+        if (this.client && this.transport) {
+            return this.client;
+        }
+        if (!this.connectPromise) {
+            this.connectPromise = this.connectFresh();
+        }
+        try {
+            await this.connectPromise;
+        }
+        finally {
+            this.connectPromise = null;
+        }
+        if (!this.client) {
+            throw new Error("BM MCP client was not initialized");
+        }
+        return this.client;
+    }
+    async connectFresh() {
+        const transport = new StdioClientTransport({
+            command: this.bmPath,
+            args: ["mcp", "--transport", "stdio"],
+            cwd: this.cwd,
+            env: this.env,
+            stderr: "pipe",
+        });
+        const client = new Client({
+            name: "openclaw-basic-memory",
+            version: "0.1.0",
+        }, { capabilities: {} });
+        const stderr = transport.stderr;
+        if (stderr) {
+            stderr.on("data", (data) => {
+                const msg = data.toString().trim();
+                if (msg.length > 0) {
+                    log.debug(`[bm mcp] ${msg}`);
+                }
+            });
+        }
+        transport.onclose = () => {
+            if (this.transport !== transport)
+                return;
+            log.warn("BM MCP stdio session closed");
+            this.client = null;
+            this.transport = null;
+        };
+        transport.onerror = (err) => {
+            if (this.transport !== transport)
+                return;
+            log.warn(`BM MCP transport error: ${getErrorMessage(err)}`);
+        };
+        this.client = client;
+        this.transport = transport;
+        try {
+            await client.connect(transport);
+            const tools = await client.listTools();
+            this.assertRequiredTools(tools.tools.map((tool) => tool.name));
+            log.info(`connected to BM MCP stdio (project=${this.project}, pid=${transport.pid ?? "unknown"})`);
+        }
+        catch (err) {
+            await this.disconnectCurrent(client, transport);
+            if (this.client === client) {
+                this.client = null;
+            }
+            if (this.transport === transport) {
+                this.transport = null;
+            }
+            throw new Error(`failed to start BM MCP stdio: ${getErrorMessage(err)}`);
+        }
+    }
+    assertRequiredTools(toolNames) {
+        const available = new Set(toolNames);
+        const missing = REQUIRED_TOOLS.filter((name) => !available.has(name));
+        if (missing.length > 0) {
+            throw new Error(`BM MCP server missing required tools: ${missing.join(", ")}`);
+        }
+    }
+    async disconnectCurrent(client, transport) {
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch {
+                // ignore shutdown errors
+            }
+        }
+        if (transport) {
+            try {
+                await transport.close();
+            }
+            catch {
+                // ignore shutdown errors
+            }
+        }
+    }
+    async callToolRaw(name, args) {
+        let lastErr;
+        for (let attempt = 0; attempt <= this.retryDelaysMs.length; attempt++) {
+            try {
+                const client = await this.ensureConnected();
+                const result = await client.callTool({
+                    name,
+                    arguments: args,
+                });
+                if (isRecord(result) && result.isError === true) {
+                    const message = extractTextFromContent(result.content);
+                    throw new Error(`BM MCP tool ${name} failed${message ? `: ${message}` : ""}`);
+                }
+                return result;
+            }
+            catch (err) {
+                if (!isRecoverableConnectionError(err)) {
+                    throw err;
+                }
+                lastErr = err;
+                await this.disconnectCurrent(this.client, this.transport);
+                this.client = null;
+                this.transport = null;
+                if (attempt === this.retryDelaysMs.length) {
+                    break;
+                }
+                const waitMs = this.retryDelaysMs[attempt];
+                log.warn(`BM MCP call ${name} failed (attempt ${attempt + 1}/${this.retryDelaysMs.length + 1}): ${getErrorMessage(err)}; retrying in ${waitMs}ms`);
+                await delay(waitMs);
+            }
+        }
+        throw new Error(`BM MCP unavailable: ${getErrorMessage(lastErr)}`);
+    }
+    async callTool(name, args) {
+        const result = await this.callToolRaw(name, args);
+        if (!isRecord(result) || result.structuredContent === undefined) {
+            throw new Error(`BM MCP tool ${name} returned no structured payload`);
+        }
+        const structuredPayload = result.structuredContent;
+        if (isRecord(structuredPayload) && structuredPayload.result !== undefined) {
+            return structuredPayload.result;
+        }
+        return structuredPayload;
+    }
+    routedProject(project) {
+        return project ?? this.project;
+    }
+    async ensureProject(projectPath) {
+        const payload = await this.callTool("create_memory_project", {
+            project_name: this.project,
+            project_path: projectPath,
+            set_default: true,
+            output_format: "json",
+        });
+        if (!isRecord(payload)) {
+            throw new Error("invalid create_memory_project response");
+        }
+    }
+    async listWorkspaces() {
+        const payload = await this.callTool("list_workspaces", {
+            output_format: "json",
+        });
+        if (isRecord(payload) && Array.isArray(payload.workspaces)) {
+            return payload.workspaces;
+        }
+        throw new Error("invalid list_workspaces response");
+    }
+    async listProjects(workspace) {
+        const payload = await this.callTool("list_memory_projects", {
+            output_format: "json",
+        });
+        if (isRecord(payload) && Array.isArray(payload.projects)) {
+            const projects = payload.projects;
+            if (workspace) {
+                return projects.filter((project) => projectMatchesWorkspace(project, workspace));
+            }
+            return projects;
+        }
+        throw new Error("invalid list_memory_projects response");
+    }
+    async search(query, limit = 10, project, metadata) {
+        const args = {
+            page: 1,
+            page_size: limit,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        if (query)
+            args.query = query;
+        if (metadata?.filters)
+            args.metadata_filters = metadata.filters;
+        if (metadata?.tags)
+            args.tags = metadata.tags;
+        if (metadata?.status)
+            args.status = metadata.status;
+        if (metadata?.note_types)
+            args.note_types = metadata.note_types;
+        if (metadata?.entity_types)
+            args.entity_types = metadata.entity_types;
+        const payload = await this.callTool("search_notes", args);
+        if (!isRecord(payload) || !Array.isArray(payload.results)) {
+            throw new Error("invalid search_notes response");
+        }
+        return payload.results;
+    }
+    async readNote(identifier, options = {}, project) {
+        const args = {
+            identifier,
+            include_frontmatter: options.includeFrontmatter === true,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("read_note", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid read_note response");
+        }
+        const title = asString(payload.title);
+        const permalink = asString(payload.permalink);
+        const content = asString(payload.content);
+        const filePath = asString(payload.file_path);
+        if (!title || !permalink || content === null || !filePath) {
+            throw new Error("invalid read_note payload");
+        }
+        return {
+            title,
+            permalink,
+            content,
+            file_path: filePath,
+            frontmatter: isRecord(payload.frontmatter) ? payload.frontmatter : null,
+        };
+    }
+    async writeNote(title, content, folder, project, overwrite) {
+        const args = {
+            title,
+            content,
+            directory: folder,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        if (overwrite !== undefined)
+            args.overwrite = overwrite;
+        const payload = await this.callTool("write_note", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid write_note response");
+        }
+        if (payload.error === "NOTE_ALREADY_EXISTS") {
+            throw new NoteAlreadyExistsError(asString(payload.title) ?? title, asString(payload.permalink) ?? "");
+        }
+        const resultTitle = asString(payload.title);
+        const permalink = asString(payload.permalink);
+        const filePath = asString(payload.file_path);
+        if (!resultTitle || !permalink || !filePath) {
+            throw new Error("invalid write_note payload");
+        }
+        return {
+            title: resultTitle,
+            permalink,
+            content,
+            file_path: filePath,
+            checksum: asString(payload.checksum),
+            action: payload.action === "created" || payload.action === "updated"
+                ? payload.action
+                : undefined,
+        };
+    }
+    async buildContext(url, depth = 1, project) {
+        const args = {
+            url,
+            depth,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("build_context", args);
+        if (!isRecord(payload) || !Array.isArray(payload.results)) {
+            throw new Error("invalid build_context response");
+        }
+        return payload;
+    }
+    async recentActivity(timeframe = "24h", project) {
+        const args = {
+            timeframe,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("recent_activity", args);
+        if (Array.isArray(payload)) {
+            return payload;
+        }
+        throw new Error("invalid recent_activity response");
+    }
+    async editNote(identifier, operation, content, options = {}, project) {
+        const args = {
+            identifier,
+            operation,
+            content,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        if (options.find_text)
+            args.find_text = options.find_text;
+        if (options.section)
+            args.section = options.section;
+        if (options.expected_replacements != null)
+            args.expected_replacements = options.expected_replacements;
+        const payload = await this.callTool("edit_note", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid edit_note response");
+        }
+        const title = asString(payload.title);
+        const permalink = asString(payload.permalink);
+        const filePath = asString(payload.file_path);
+        if (!title || !permalink || !filePath) {
+            throw new Error("invalid edit_note payload");
+        }
+        return {
+            title,
+            permalink,
+            file_path: filePath,
+            operation,
+            checksum: asString(payload.checksum),
+        };
+    }
+    async deleteNote(identifier, project) {
+        const args = {
+            identifier,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("delete_note", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid delete_note response");
+        }
+        if (payload.deleted !== true) {
+            throw new Error(`delete_note did not delete "${identifier}"`);
+        }
+        return {
+            title: asString(payload.title) ?? identifier,
+            permalink: asString(payload.permalink) ?? identifier,
+            file_path: asString(payload.file_path) ?? identifier,
+        };
+    }
+    async moveNote(identifier, newFolder, project) {
+        const args = {
+            identifier,
+            destination_folder: newFolder,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("move_note", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid move_note response");
+        }
+        if (payload.moved !== true) {
+            throw new Error(asString(payload.error) ??
+                `move_note did not move "${identifier}" to "${newFolder}"`);
+        }
+        return {
+            title: asString(payload.title) ?? identifier,
+            permalink: asString(payload.permalink) ?? identifier,
+            content: "",
+            file_path: asString(payload.file_path) ?? "",
+        };
+    }
+    async schemaValidate(noteType, identifier, project) {
+        const args = {
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        if (noteType)
+            args.note_type = noteType;
+        if (identifier)
+            args.identifier = identifier;
+        const payload = await this.callTool("schema_validate", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid schema_validate response");
+        }
+        return payload;
+    }
+    async schemaInfer(noteType, threshold = 0.25, project) {
+        const args = {
+            note_type: noteType,
+            threshold,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("schema_infer", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid schema_infer response");
+        }
+        return payload;
+    }
+    async schemaDiff(noteType, project) {
+        const args = {
+            note_type: noteType,
+            output_format: "json",
+            project: this.routedProject(project),
+        };
+        const payload = await this.callTool("schema_diff", args);
+        if (!isRecord(payload)) {
+            throw new Error("invalid schema_diff response");
+        }
+        return payload;
+    }
+    async indexConversation(userMessage, assistantResponse) {
+        const now = new Date();
+        const dateStr = now.toISOString().split("T")[0];
+        const timeStr = now.toTimeString().slice(0, 5);
+        const title = `conversations-${dateStr}`;
+        const entry = [
+            `### ${timeStr}`,
+            "",
+            "**User:**",
+            userMessage,
+            "",
+            "**Assistant:**",
+            assistantResponse,
+            "",
+            "---",
+        ].join("\n");
+        try {
+            await this.editNote(title, "append", entry);
+            log.debug(`appended conversation to: ${title}`);
+            return;
+        }
+        catch (err) {
+            if (!isNoteNotFoundError(err)) {
+                log.error(`conversation append failed: ${getErrorMessage(err)}`, err);
+                throw err;
+            }
+            log.debug(`conversation note missing, will create: ${getErrorMessage(err)}`);
+        }
+        // Create the note with frontmatter and first entry
+        const content = [
+            "---",
+            `title: Conversations ${dateStr}`,
+            "type: Conversation",
+            `date: "${dateStr}"`,
+            "---",
+            "",
+            `# Conversations ${dateStr}`,
+            "",
+            entry,
+        ].join("\n");
+        try {
+            await this.writeNote(title, content, "conversations");
+            log.debug(`created conversation note: ${title}`);
+        }
+        catch (err) {
+            log.error("conversation index failed", err);
+        }
+    }
+    getProject() {
+        return this.project;
+    }
+}

package/dist/commands/cli.d.ts

@@ -0,0 +1,4 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { BmClient } from "../bm-client.ts";
+import type { BasicMemoryConfig } from "../config.ts";
+export declare function registerCli(api: OpenClawPluginApi, client: BmClient, cfg: BasicMemoryConfig): void;

package/dist/commands/cli.js

@@ -0,0 +1,116 @@
+import { log } from "../logger.js";
+export function registerCli(api, client, cfg) {
+    api.registerCli(
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    ({ program }) => {
+        const cmd = program
+            .command("basic-memory")
+            .description("Basic Memory knowledge graph commands");
+        cmd
+            .command("search")
+            .argument("<query>", "Search query")
+            .option("--limit <n>", "Max results", "10")
+            .action(async (query, opts) => {
+            const limit = Number.parseInt(opts.limit, 10) || 10;
+            log.debug(`cli search: query="${query}" limit=${limit}`);
+            const results = await client.search(query, limit);
+            if (results.length === 0) {
+                console.log("No notes found.");
+                return;
+            }
+            for (const r of results) {
+                const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : "";
+                console.log(`- ${r.title}${score}`);
+                if (r.content) {
+                    const preview = r.content.length > 100
+                        ? `${r.content.slice(0, 100)}...`
+                        : r.content;
+                    console.log(`  ${preview}`);
+                }
+            }
+        });
+        cmd
+            .command("read")
+            .argument("<identifier>", "Note title, permalink, or memory:// URL")
+            .option("--raw", "Return raw markdown including frontmatter", false)
+            .action(async (identifier, opts) => {
+            log.debug(`cli read: identifier="${identifier}"`);
+            const note = await client.readNote(identifier, {
+                includeFrontmatter: opts.raw === true,
+            });
+            console.log(`# ${note.title}`);
+            console.log(`permalink: ${note.permalink}`);
+            console.log(`file: ${note.file_path}`);
+            console.log("");
+            console.log(note.content);
+        });
+        cmd
+            .command("edit")
+            .argument("<identifier>", "Note title, permalink, or memory:// URL")
+            .requiredOption("--operation <operation>", "Edit operation: append|prepend|find_replace|replace_section")
+            .requiredOption("--content <content>", "Edit content")
+            .option("--find-text <text>", "Text to find for find_replace")
+            .option("--section <heading>", "Section heading for replace_section")
+            .option("--expected-replacements <n>", "Expected replacement count for find_replace", "1")
+            .action(async (identifier, opts) => {
+            const expectedReplacements = Number.parseInt(opts.expectedReplacements, 10) || 1;
+            log.debug(`cli edit: identifier="${identifier}" op=${opts.operation} expected_replacements=${expectedReplacements}`);
+            const result = await client.editNote(identifier, opts.operation, opts.content, {
+                find_text: opts.findText,
+                section: opts.section,
+                expected_replacements: expectedReplacements,
+            });
+            console.log(`Edited: ${result.title}`);
+            console.log(`permalink: ${result.permalink}`);
+            console.log(`file: ${result.file_path}`);
+            console.log(`operation: ${result.operation}`);
+            if (result.checksum) {
+                console.log(`checksum: ${result.checksum}`);
+            }
+        });
+        cmd
+            .command("context")
+            .argument("<url>", "Memory URL to navigate")
+            .option("--depth <n>", "Relation hops to follow", "1")
+            .action(async (url, opts) => {
+            const depth = Number.parseInt(opts.depth, 10) || 1;
+            log.debug(`cli context: url="${url}" depth=${depth}`);
+            const ctx = await client.buildContext(url, depth);
+            if (!ctx.results || ctx.results.length === 0) {
+                console.log(`No context found for "${url}".`);
+                return;
+            }
+            for (const result of ctx.results) {
+                console.log(`## ${result.primary_result.title}`);
+                console.log(result.primary_result.content);
+                console.log("");
+            }
+        });
+        cmd
+            .command("recent")
+            .option("--timeframe <t>", "Timeframe (e.g. 24h, 7d)", "24h")
+            .action(async (opts) => {
+            log.debug(`cli recent: timeframe="${opts.timeframe}"`);
+            const results = await client.recentActivity(opts.timeframe);
+            if (results.length === 0) {
+                console.log("No recent activity.");
+                return;
+            }
+            for (const r of results) {
+                console.log(`- ${r.title} (${r.permalink})`);
+            }
+        });
+        cmd
+            .command("status")
+            .description("Show plugin status")
+            .action(() => {
+            console.log(`Project: ${cfg.project}`);
+            console.log(`Project path: ${cfg.projectPath}`);
+            console.log(`BM CLI: ${cfg.bmPath}`);
+            console.log(`Memory dir: ${cfg.memoryDir}`);
+            console.log(`Memory file: ${cfg.memoryFile}`);
+            console.log(`Auto-capture: ${cfg.autoCapture}`);
+            console.log(`Debug: ${cfg.debug}`);
+        });
+    }, { commands: ["basic-memory"] });
+}