@basicmemory/openclaw-basic-memory 0.2.3 → 0.23.0

package/dist/hooks/recall.js

@@ -0,0 +1,56 @@
+import { log } from "../logger.js";
+/**
+ * Format recalled context from active tasks and recent activity.
+ * Returns empty string if nothing was found.
+ */
+export function formatRecallContext(tasks, recent, prompt) {
+    const sections = [];
+    if (tasks.length > 0) {
+        const taskLines = tasks.map((t) => {
+            const preview = t.content.length > 120 ? `${t.content.slice(0, 120)}...` : t.content;
+            return `- **${t.title}** — ${preview}`;
+        });
+        sections.push(`## Active Tasks\n${taskLines.join("\n")}`);
+    }
+    if (recent.length > 0) {
+        const recentLines = recent.map((r) => `- ${r.title} (${r.file_path})`);
+        sections.push(`## Recent Activity\n${recentLines.join("\n")}`);
+    }
+    if (sections.length === 0)
+        return "";
+    return `${sections.join("\n\n")}\n\n---\n${prompt}`;
+}
+export async function loadRecallState(client, cfg) {
+    const [tasks, recent] = await Promise.all([
+        client.search(undefined, 5, undefined, {
+            note_types: ["Task"],
+            status: "active",
+        }),
+        client.recentActivity("1d"),
+    ]);
+    const context = formatRecallContext(tasks, recent, cfg.recallPrompt);
+    if (!context)
+        return null;
+    return { tasks, recent, context };
+}
+/**
+ * Build the pre-turn recall handler.
+ *
+ * On agent_start, queries active tasks and recent activity from Basic Memory,
+ * then returns formatted context for injection into the conversation.
+ */
+export function buildRecallHandler(client, cfg) {
+    return async (_event) => {
+        try {
+            const recall = await loadRecallState(client, cfg);
+            if (!recall)
+                return {};
+            log.debug(`recall: ${recall.tasks.length} active tasks, ${recall.recent.length} recent items`);
+            return { context: recall.context };
+        }
+        catch (err) {
+            log.error("recall failed", err);
+            return {};
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export declare function isCommandAvailable(command: string): boolean;
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;

package/dist/index.js

@@ -0,0 +1,135 @@
+import { execFileSync } from "node:child_process";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { BmClient } from "./bm-client.js";
+import { registerCli } from "./commands/cli.js";
+import { registerSkillCommands } from "./commands/skills.js";
+import { registerCommands } from "./commands/slash.js";
+import { basicMemoryConfigSchema, parseConfig, resolveProjectPath, } from "./config.js";
+import { BasicMemoryContextEngine } from "./context-engine/basic-memory-context-engine.js";
+import { initLogger, log } from "./logger.js";
+import { CONVERSATION_SCHEMA_CONTENT } from "./schema/conversation-schema.js";
+import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.js";
+import { registerContextTool } from "./tools/build-context.js";
+import { registerDeleteTool } from "./tools/delete-note.js";
+import { registerEditTool } from "./tools/edit-note.js";
+import { registerProjectListTool } from "./tools/list-memory-projects.js";
+import { registerWorkspaceListTool } from "./tools/list-workspaces.js";
+import { registerMemoryProvider, setWorkspaceDir, } from "./tools/memory-provider.js";
+import { registerMoveTool } from "./tools/move-note.js";
+import { registerReadTool } from "./tools/read-note.js";
+import { registerSchemaDiffTool } from "./tools/schema-diff.js";
+import { registerSchemaInferTool } from "./tools/schema-infer.js";
+import { registerSchemaValidateTool } from "./tools/schema-validate.js";
+import { registerSearchTool } from "./tools/search-notes.js";
+import { registerWriteTool } from "./tools/write-note.js";
+export function isCommandAvailable(command) {
+    try {
+        execFileSync(command, ["--version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export default definePluginEntry({
+    id: "openclaw-basic-memory",
+    name: "Basic Memory",
+    description: "Local-first knowledge graph for OpenClaw — persistent memory with graph search and composited memory_search",
+    configSchema: basicMemoryConfigSchema,
+    register(api) {
+        const cfg = parseConfig(api.pluginConfig);
+        initLogger(api.logger, cfg.debug);
+        log.info(`project=${cfg.project} memoryDir=${cfg.memoryDir} memoryFile=${cfg.memoryFile}`);
+        const client = new BmClient(cfg.bmPath, cfg.project);
+        // --- BM Tools (always registered) ---
+        registerSearchTool(api, client);
+        registerProjectListTool(api, client);
+        registerWorkspaceListTool(api, client);
+        registerReadTool(api, client);
+        registerWriteTool(api, client);
+        registerEditTool(api, client);
+        registerContextTool(api, client);
+        registerDeleteTool(api, client);
+        registerMoveTool(api, client);
+        registerSchemaValidateTool(api, client);
+        registerSchemaInferTool(api, client);
+        registerSchemaDiffTool(api, client);
+        // --- Composited memory_search + memory_get (always registered) ---
+        registerMemoryProvider(api, client, cfg);
+        log.info("registered composited memory_search + memory_get");
+        api.registerContextEngine("openclaw-basic-memory", () => new BasicMemoryContextEngine(client, cfg));
+        log.info("registered Basic Memory context engine");
+        // --- Commands ---
+        registerCommands(api, client);
+        registerSkillCommands(api);
+        registerCli(api, client, cfg);
+        // --- Service lifecycle ---
+        api.registerService({
+            id: "openclaw-basic-memory",
+            start: async (ctx) => {
+                log.info("starting...");
+                // Auto-install bm CLI if not found
+                const bmBin = cfg.bmPath || "bm";
+                if (!isCommandAvailable(bmBin)) {
+                    log.info("bm CLI not found on PATH — attempting auto-install...");
+                    try {
+                        if (!isCommandAvailable("uv")) {
+                            throw new Error("uv not found");
+                        }
+                        log.info("installing basic-memory via uv (this may take a minute)...");
+                        const result = execFileSync("uv", ["tool", "install", "basic-memory", "--force"], {
+                            encoding: "utf-8",
+                            timeout: 120_000,
+                            stdio: ["ignore", "pipe", "pipe"],
+                        });
+                        log.info(`basic-memory installed: ${result.trim().split("\n").pop()}`);
+                        // Verify it worked
+                        if (isCommandAvailable(bmBin)) {
+                            log.info("bm CLI now available on PATH");
+                        }
+                        else {
+                            log.error("bm installed but not found on PATH. You may need to add uv's bin directory to your PATH (typically ~/.local/bin).");
+                        }
+                    }
+                    catch (_uvErr) {
+                        log.error("Cannot auto-install basic-memory: uv not found. " +
+                            "Install uv first (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh), " +
+                            "then restart the gateway.");
+                    }
+                }
+                const workspace = ctx.workspaceDir ?? process.cwd();
+                const projectPath = resolveProjectPath(cfg.projectPath, workspace);
+                cfg.projectPath = projectPath;
+                await client.start({ cwd: workspace });
+                await client.ensureProject(projectPath);
+                log.debug(`project "${cfg.project}" at ${projectPath}`);
+                // Seed schemas if not already present
+                for (const [name, content] of [
+                    ["Task", TASK_SCHEMA_CONTENT],
+                    ["Conversation", CONVERSATION_SCHEMA_CONTENT],
+                ]) {
+                    try {
+                        await client.readNote(`schema/${name}`);
+                        log.debug(`${name} schema already exists, skipping seed`);
+                    }
+                    catch {
+                        try {
+                            await client.writeNote(name, content, "schema");
+                            log.debug(`seeded ${name} schema note`);
+                        }
+                        catch (err) {
+                            log.debug(`${name} schema seed failed (non-fatal)`, err);
+                        }
+                    }
+                }
+                setWorkspaceDir(workspace);
+                log.info("connected — BM MCP stdio session running");
+            },
+            stop: async () => {
+                log.info("stopping BM MCP session...");
+                await client.stop();
+                log.info("stopped");
+            },
+        });
+    },
+});

package/dist/logger.d.ts

@@ -0,0 +1,13 @@
+export type LoggerBackend = {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    debug?(msg: string, ...args: unknown[]): void;
+};
+export declare function initLogger(backend: LoggerBackend, debug: boolean): void;
+export declare const log: {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, err?: unknown): void;
+    debug(msg: string, ...args: unknown[]): void;
+};

package/dist/logger.js

@@ -0,0 +1,34 @@
+const NOOP_LOGGER = {
+    info() { },
+    warn() { },
+    error() { },
+    debug() { },
+};
+let _backend = NOOP_LOGGER;
+let _debug = false;
+export function initLogger(backend, debug) {
+    _backend = backend;
+    _debug = debug;
+}
+export const log = {
+    info(msg, ...args) {
+        _backend.info(`basic-memory: ${msg}`, ...args);
+    },
+    warn(msg, ...args) {
+        _backend.warn(`basic-memory: ${msg}`, ...args);
+    },
+    error(msg, err) {
+        const detail = err instanceof Error
+            ? err.message
+            : err !== undefined && err !== ""
+                ? String(err)
+                : "";
+        _backend.error(`basic-memory: ${msg}${detail ? ` — ${detail}` : ""}`);
+    },
+    debug(msg, ...args) {
+        if (!_debug)
+            return;
+        const fn = _backend.debug ?? _backend.info;
+        fn(`basic-memory [debug]: ${msg}`, ...args);
+    },
+};

package/dist/schema/conversation-schema.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Canonical Conversation schema note content, seeded into new projects on first startup.
+ * If the schema already exists (user may have customized it), seeding is skipped.
+ */
+export declare const CONVERSATION_SCHEMA_CONTENT = "---\ntitle: Conversation\ntype: schema\nentity: Conversation\nversion: 1\nschema:\n  date: \"string, ISO date YYYY-MM-DD\"\n  session_id?: \"string, unique session identifier\"\n  channel?: \"string, where the conversation happened (webchat, telegram, discord, etc)\"\n  participants?: \"array, who was in the conversation\"\n  topic?: \"string, brief description of main topic\"\n  summary?: \"string, one-paragraph summary of key points\"\n  key_decisions?: \"array, decisions made during conversation\"\n  action_items?: \"array, things to do as a result\"\nsettings:\n  validation: warn\n---\n\n# Conversation\n\nA record of a conversation session between the agent and user(s).\n\n## Observations\n- [convention] Conversation files live in memory/conversations/ with format conversations-YYYY-MM-DD.md\n- [convention] Messages are appended as the conversation progresses\n- [convention] Summary and key_decisions populated at session end or by memory-reflect\n- [convention] Skip routine greetings, heartbeat acks, and tool call details\n- [convention] Focus on decisions, actions taken, and key context needed for continuity\n";

package/dist/schema/conversation-schema.js

@@ -0,0 +1,33 @@
+/**
+ * Canonical Conversation schema note content, seeded into new projects on first startup.
+ * If the schema already exists (user may have customized it), seeding is skipped.
+ */
+export const CONVERSATION_SCHEMA_CONTENT = `---
+title: Conversation
+type: schema
+entity: Conversation
+version: 1
+schema:
+  date: "string, ISO date YYYY-MM-DD"
+  session_id?: "string, unique session identifier"
+  channel?: "string, where the conversation happened (webchat, telegram, discord, etc)"
+  participants?: "array, who was in the conversation"
+  topic?: "string, brief description of main topic"
+  summary?: "string, one-paragraph summary of key points"
+  key_decisions?: "array, decisions made during conversation"
+  action_items?: "array, things to do as a result"
+settings:
+  validation: warn
+---
+
+# Conversation
+
+A record of a conversation session between the agent and user(s).
+
+## Observations
+- [convention] Conversation files live in memory/conversations/ with format conversations-YYYY-MM-DD.md
+- [convention] Messages are appended as the conversation progresses
+- [convention] Summary and key_decisions populated at session end or by memory-reflect
+- [convention] Skip routine greetings, heartbeat acks, and tool call details
+- [convention] Focus on decisions, actions taken, and key context needed for continuity
+`;

package/dist/schema/task-schema.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Canonical Task schema note content, seeded into new projects on first startup.
+ * If the schema already exists (user may have customized it), seeding is skipped.
+ */
+export declare const TASK_SCHEMA_CONTENT = "---\ntitle: Task\ntype: schema\nentity: Task\nversion: 1\nschema:\n  description: \"string, what needs to be done\"\n  status?(enum): \"[active, blocked, done, abandoned], current state\"\n  assigned_to?: \"string, who is working on this\"\n  steps?(array): \"string, ordered steps to complete\"\n  current_step?: \"integer, which step number we're on (1-indexed)\"\n  context?: \"string, key context needed to resume after memory loss\"\n  started?: \"string, when work began\"\n  completed?: \"string, when work finished\"\n  blockers?(array): \"string, what's preventing progress\"\n  parent_task?: \"Task, parent task if this is a subtask\"\nsettings:\n  validation: warn\n---\n\n# Task\n\nStructured task note for tracking multi-step work that survives context compaction.\n\n## Observations\n- [convention] Task files live in memory/tasks/ with format YYYY-MM-DD-short-name.md\n- [convention] Status transitions: active \u2192 blocked \u2192 done or abandoned\n- [convention] Include a ## Context section for resumption after memory loss\n- [convention] Include a ## Steps section with numbered checkbox items for step tracking\n";

package/dist/schema/task-schema.js

@@ -0,0 +1,34 @@
+/**
+ * Canonical Task schema note content, seeded into new projects on first startup.
+ * If the schema already exists (user may have customized it), seeding is skipped.
+ */
+export const TASK_SCHEMA_CONTENT = `---
+title: Task
+type: schema
+entity: Task
+version: 1
+schema:
+  description: "string, what needs to be done"
+  status?(enum): "[active, blocked, done, abandoned], current state"
+  assigned_to?: "string, who is working on this"
+  steps?(array): "string, ordered steps to complete"
+  current_step?: "integer, which step number we're on (1-indexed)"
+  context?: "string, key context needed to resume after memory loss"
+  started?: "string, when work began"
+  completed?: "string, when work finished"
+  blockers?(array): "string, what's preventing progress"
+  parent_task?: "Task, parent task if this is a subtask"
+settings:
+  validation: warn
+---
+
+# Task
+
+Structured task note for tracking multi-step work that survives context compaction.
+
+## Observations
+- [convention] Task files live in memory/tasks/ with format YYYY-MM-DD-short-name.md
+- [convention] Status transitions: active → blocked → done or abandoned
+- [convention] Include a ## Context section for resumption after memory loss
+- [convention] Include a ## Steps section with numbered checkbox items for step tracking
+`;

package/dist/tools/build-context.d.ts

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

package/dist/tools/build-context.js

@@ -0,0 +1,100 @@
+import { Type } from "@sinclair/typebox";
+import { log } from "../logger.js";
+export function registerContextTool(api, client) {
+    api.registerTool({
+        name: "build_context",
+        label: "Build Context",
+        description: "Navigate the Basic Memory knowledge graph via memory:// URLs. " +
+            "Returns the target note plus related notes connected through the graph. " +
+            "Use this to follow relations and discover connected concepts.",
+        parameters: Type.Object({
+            url: Type.String({
+                description: 'Memory URL to navigate, e.g. "memory://agents/decisions" or "projects/my-project"',
+            }),
+            depth: Type.Optional(Type.Number({
+                description: "How many relation hops to follow (default: 1)",
+            })),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            const depth = params.depth ?? 1;
+            log.debug(`build_context: url="${params.url}" depth=${depth}`);
+            try {
+                const ctx = await client.buildContext(params.url, depth, params.project);
+                if (!ctx.results || ctx.results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `No context found for "${params.url}".`,
+                            },
+                        ],
+                        details: {
+                            url: params.url,
+                            depth,
+                            resultCount: 0,
+                        },
+                    };
+                }
+                const sections = [];
+                for (const result of ctx.results) {
+                    const primary = result.primary_result;
+                    sections.push(`## ${primary.title}\n${primary.content}`);
+                    if (result.observations?.length > 0) {
+                        const obs = result.observations
+                            .map((o) => `- [${o.category}] ${o.content}`)
+                            .join("\n");
+                        sections.push(`### Observations\n${obs}`);
+                    }
+                    if (result.related_results?.length > 0) {
+                        const rels = result.related_results
+                            .map((r) => {
+                            if (r.type === "relation") {
+                                return `- ${r.relation_type} → **${r.to_entity}**`;
+                            }
+                            const label = r.relation_type
+                                ? `${r.relation_type} → **${r.title}**`
+                                : `**${r.title}**`;
+                            return r.permalink
+                                ? `- ${label} (${r.permalink})`
+                                : `- ${label}`;
+                        })
+                            .join("\n");
+                        sections.push(`### Related\n${rels}`);
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: sections.join("\n\n"),
+                        },
+                    ],
+                    details: {
+                        url: params.url,
+                        depth,
+                        resultCount: ctx.results.length,
+                    },
+                };
+            }
+            catch (err) {
+                log.error("build_context failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to build context for "${params.url}". Check logs for details.`,
+                        },
+                    ],
+                    details: {
+                        url: params.url,
+                        depth,
+                        error: "build_context_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "build_context" });
+}

package/dist/tools/delete-note.d.ts

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

package/dist/tools/delete-note.js

@@ -0,0 +1,52 @@
+import { Type } from "@sinclair/typebox";
+import { log } from "../logger.js";
+export function registerDeleteTool(api, client) {
+    api.registerTool({
+        name: "delete_note",
+        label: "Delete Note",
+        description: "Delete a note from the Basic Memory knowledge graph. " +
+            "The note is permanently removed from the filesystem and the search index.",
+        parameters: Type.Object({
+            identifier: Type.String({
+                description: "Note title, permalink, or memory:// URL to delete",
+            }),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            log.debug(`delete_note: identifier="${params.identifier}"`);
+            try {
+                const result = await client.deleteNote(params.identifier, params.project);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Deleted: ${result.title} (${result.permalink})`,
+                        },
+                    ],
+                    details: {
+                        title: result.title,
+                        permalink: result.permalink,
+                        file_path: result.file_path,
+                    },
+                };
+            }
+            catch (err) {
+                log.error("delete_note failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to delete "${params.identifier}". It may not exist.`,
+                        },
+                    ],
+                    details: {
+                        identifier: params.identifier,
+                        error: "delete_note_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "delete_note" });
+}

package/dist/tools/edit-note.d.ts

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

package/dist/tools/edit-note.js

@@ -0,0 +1,81 @@
+import { Type } from "@sinclair/typebox";
+import { log } from "../logger.js";
+export function registerEditTool(api, client) {
+    api.registerTool({
+        name: "edit_note",
+        label: "Edit Note",
+        description: "Incrementally edit an existing note in the Basic Memory knowledge graph. " +
+            "Supports append, prepend, find/replace, and section replacement " +
+            "without rewriting the entire note.",
+        parameters: Type.Object({
+            identifier: Type.String({
+                description: "Note title, permalink, or memory:// URL to edit",
+            }),
+            operation: Type.Union([
+                Type.Literal("append"),
+                Type.Literal("prepend"),
+                Type.Literal("find_replace"),
+                Type.Literal("replace_section"),
+            ], {
+                description: "Edit operation: append (add to end), prepend (add to start), " +
+                    "find_replace (replace matching text), replace_section (replace a heading section)",
+            }),
+            content: Type.String({
+                description: "New content to add or replace with",
+            }),
+            find_text: Type.Optional(Type.String({
+                description: "Text to find (required for find_replace)",
+            })),
+            section: Type.Optional(Type.String({
+                description: "Section heading to replace (required for replace_section)",
+            })),
+            expected_replacements: Type.Optional(Type.Number({
+                description: "Expected replacement count for find_replace (default: 1)",
+            })),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            log.debug(`edit_note: id="${params.identifier}" op=${params.operation}`);
+            try {
+                const note = await client.editNote(params.identifier, params.operation, params.content, {
+                    find_text: params.find_text,
+                    section: params.section,
+                    expected_replacements: params.expected_replacements,
+                }, params.project);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Note updated: ${note.title} (${note.permalink})`,
+                        },
+                    ],
+                    details: {
+                        title: note.title,
+                        permalink: note.permalink,
+                        file_path: note.file_path,
+                        operation: params.operation,
+                        checksum: note.checksum ?? null,
+                    },
+                };
+            }
+            catch (err) {
+                log.error("edit_note failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to edit note "${params.identifier}". It may not exist.`,
+                        },
+                    ],
+                    details: {
+                        identifier: params.identifier,
+                        operation: params.operation,
+                        error: "edit_note_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "edit_note" });
+}

package/dist/tools/list-memory-projects.d.ts

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