@basicmemory/openclaw-basic-memory 0.2.3 → 0.23.0

package/dist/commands/skills.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+export declare function registerSkillCommands(api: OpenClawPluginApi): void;

package/dist/commands/skills.js

@@ -0,0 +1,86 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function resolveSkillsDir(api) {
+    if (api.resolvePath) {
+        return api.resolvePath("skills");
+    }
+    const sourceRootSkills = resolve(__dirname, "..", "skills");
+    if (existsSync(sourceRootSkills)) {
+        return sourceRootSkills;
+    }
+    return resolve(__dirname, "..", "..", "skills");
+}
+function loadManifest(skillsDir) {
+    try {
+        const raw = readFileSync(resolve(skillsDir, "manifest.json"), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error("skills/manifest.json not found. Run `bun scripts/fetch-skills.ts` first.");
+    }
+}
+function loadSkill(skillsDir, dir) {
+    return readFileSync(resolve(skillsDir, dir, "SKILL.md"), "utf-8");
+}
+/**
+ * List a skill's bundled resource files (references/, assets/, ...) so the
+ * command can tell the assistant where they live on disk. SKILL.md workflows
+ * reference these by relative path; without the mapping, bundled commands
+ * would direct the assistant to files it was never given. evals/ is excluded
+ * as test fixtures.
+ */
+function listResourceFiles(skillsDir, dir) {
+    const root = resolve(skillsDir, dir);
+    const files = [];
+    const walk = (rel) => {
+        for (const entry of readdirSync(resolve(root, rel), {
+            withFileTypes: true,
+        })) {
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (relPath !== "evals")
+                    walk(relPath);
+            }
+            else if (relPath !== "SKILL.md") {
+                files.push(relPath);
+            }
+        }
+    };
+    walk("");
+    return files.sort();
+}
+function resourceSection(skillsDir, dir, files) {
+    if (files.length === 0)
+        return "";
+    const lines = files
+        .map((f) => `- \`${f}\` → ${resolve(skillsDir, dir, f)}`)
+        .join("\n");
+    return ("\n\n## Bundled resource files\n\n" +
+        "This skill references companion files by relative path. They are installed at:\n\n" +
+        `${lines}\n\n` +
+        "When the workflow directs you to read one of these files, read it from the absolute path listed above.");
+}
+export function registerSkillCommands(api) {
+    const skillsDir = resolveSkillsDir(api);
+    const manifest = loadManifest(skillsDir);
+    for (const entry of manifest) {
+        const commandName = entry.dir.replace(/^memory-/, "");
+        const content = loadSkill(skillsDir, entry.dir) +
+            resourceSection(skillsDir, entry.dir, listResourceFiles(skillsDir, entry.dir));
+        api.registerCommand({
+            name: commandName,
+            description: entry.description,
+            acceptsArgs: true,
+            requireAuth: true,
+            handler: async (ctx) => {
+                const args = ctx.args?.trim();
+                const prefix = args
+                    ? `User request: ${args}\n\nFollow this workflow:\n\n`
+                    : "Follow this workflow:\n\n";
+                return { text: prefix + content };
+            },
+        });
+    }
+}

package/dist/commands/slash.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 registerCommands(api: OpenClawPluginApi, client: BmClient): void;

package/dist/commands/slash.js

@@ -0,0 +1,92 @@
+import { execSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log } from "../logger.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function registerCommands(api, client) {
+    api.registerCommand({
+        name: "bm-setup",
+        description: "Install or update the Basic Memory CLI (requires uv)",
+        requireAuth: true,
+        handler: async () => {
+            const scriptPath = api.resolvePath
+                ? api.resolvePath("scripts/setup-bm.sh")
+                : resolve(__dirname, "..", "scripts", "setup-bm.sh");
+            log.info(`/bm-setup: running ${scriptPath}`);
+            try {
+                const output = execSync(`bash "${scriptPath}"`, {
+                    encoding: "utf-8",
+                    timeout: 180_000,
+                    stdio: "pipe",
+                    env: { ...process.env },
+                });
+                return { text: output.trim() };
+            }
+            catch (err) {
+                const execErr = err;
+                const detail = execErr.stderr || execErr.stdout || String(err);
+                log.error("/bm-setup failed", err);
+                return {
+                    text: `Setup failed:\n${detail.trim()}`,
+                };
+            }
+        },
+    });
+    api.registerCommand({
+        name: "remember",
+        description: "Save something to the Basic Memory knowledge graph",
+        acceptsArgs: true,
+        requireAuth: true,
+        handler: async (ctx) => {
+            const text = ctx.args?.trim();
+            if (!text) {
+                return { text: "Usage: /remember <text to save as a note>" };
+            }
+            log.debug(`/remember: "${text.slice(0, 50)}"`);
+            try {
+                const title = text.length > 60 ? text.slice(0, 60) : text;
+                await client.writeNote(title, text, "agent/memories");
+                const preview = text.length > 60 ? `${text.slice(0, 60)}...` : text;
+                return { text: `Remembered: "${preview}"` };
+            }
+            catch (err) {
+                log.error("/remember failed", err);
+                return {
+                    text: "Failed to save memory. Is Basic Memory running?",
+                };
+            }
+        },
+    });
+    api.registerCommand({
+        name: "recall",
+        description: "Search the Basic Memory knowledge graph",
+        acceptsArgs: true,
+        requireAuth: true,
+        handler: async (ctx) => {
+            const query = ctx.args?.trim();
+            if (!query) {
+                return { text: "Usage: /recall <search query>" };
+            }
+            log.debug(`/recall: "${query}"`);
+            try {
+                const results = await client.search(query, 5);
+                if (results.length === 0) {
+                    return { text: `No notes found for: "${query}"` };
+                }
+                const lines = results.map((r, i) => {
+                    const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : "";
+                    return `${i + 1}. ${r.title}${score}`;
+                });
+                return {
+                    text: `Found ${results.length} notes:\n\n${lines.join("\n")}`,
+                };
+            }
+            catch (err) {
+                log.error("/recall failed", err);
+                return {
+                    text: "Failed to search. Is Basic Memory running?",
+                };
+            }
+        },
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export type BasicMemoryConfig = {
+    project: string;
+    bmPath: string;
+    memoryDir: string;
+    memoryFile: string;
+    projectPath: string;
+    autoCapture: boolean;
+    captureMinChars: number;
+    autoRecall: boolean;
+    recallPrompt: string;
+    debug: boolean;
+};
+export declare function resolveProjectPath(projectPath: string, workspaceDir: string): string;
+export declare function parseConfig(raw: unknown): BasicMemoryConfig;
+export declare const basicMemoryConfigSchema: {
+    parse: typeof parseConfig;
+};

package/dist/config.js

@@ -0,0 +1,99 @@
+import { homedir, hostname } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+const ALLOWED_KEYS = [
+    "project",
+    "bmPath",
+    "memoryDir",
+    "memory_dir",
+    "memoryFile",
+    "memory_file",
+    "projectPath",
+    "autoCapture",
+    "captureMinChars",
+    "capture_min_chars",
+    "autoRecall",
+    "auto_recall",
+    "recallPrompt",
+    "recall_prompt",
+    "debug",
+];
+function assertAllowedKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+        throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
+    }
+}
+function defaultProject() {
+    return `openclaw-${hostname()
+        .replace(/[^a-zA-Z0-9-]/g, "-")
+        .toLowerCase()}`;
+}
+function expandUserPath(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return `${homedir()}/${path.slice(2)}`;
+    return path;
+}
+export function resolveProjectPath(projectPath, workspaceDir) {
+    const expanded = expandUserPath(projectPath);
+    if (isAbsolute(expanded))
+        return expanded;
+    return resolve(workspaceDir, expanded);
+}
+export function parseConfig(raw) {
+    const cfg = raw && typeof raw === "object" && !Array.isArray(raw)
+        ? raw
+        : {};
+    if (Object.keys(cfg).length > 0) {
+        assertAllowedKeys(cfg, ALLOWED_KEYS, "basic-memory config");
+    }
+    // Support both camelCase and snake_case for memory_dir / memory_file
+    const memoryDir = typeof cfg.memoryDir === "string" && cfg.memoryDir.length > 0
+        ? cfg.memoryDir
+        : typeof cfg.memory_dir === "string" &&
+            cfg.memory_dir.length > 0
+            ? cfg.memory_dir
+            : "memory/";
+    const memoryFile = typeof cfg.memoryFile === "string" && cfg.memoryFile.length > 0
+        ? cfg.memoryFile
+        : typeof cfg.memory_file === "string" &&
+            cfg.memory_file.length > 0
+            ? cfg.memory_file
+            : "MEMORY.md";
+    return {
+        project: typeof cfg.project === "string" && cfg.project.length > 0
+            ? cfg.project
+            : defaultProject(),
+        projectPath: typeof cfg.projectPath === "string" && cfg.projectPath.length > 0
+            ? cfg.projectPath
+            : ".",
+        bmPath: typeof cfg.bmPath === "string" && cfg.bmPath.length > 0
+            ? cfg.bmPath
+            : "bm",
+        memoryDir,
+        memoryFile,
+        autoCapture: typeof cfg.autoCapture === "boolean" ? cfg.autoCapture : true,
+        captureMinChars: typeof cfg.captureMinChars === "number" && cfg.captureMinChars >= 0
+            ? cfg.captureMinChars
+            : typeof cfg.capture_min_chars === "number" &&
+                cfg.capture_min_chars >= 0
+                ? cfg.capture_min_chars
+                : 10,
+        autoRecall: typeof cfg.autoRecall === "boolean"
+            ? cfg.autoRecall
+            : typeof cfg.auto_recall === "boolean"
+                ? cfg.auto_recall
+                : true,
+        recallPrompt: typeof cfg.recallPrompt === "string" && cfg.recallPrompt.length > 0
+            ? cfg.recallPrompt
+            : typeof cfg.recall_prompt === "string" &&
+                cfg.recall_prompt.length > 0
+                ? cfg.recall_prompt
+                : "Check for active tasks and recent activity. Summarize anything relevant to the current session.",
+        debug: typeof cfg.debug === "boolean" ? cfg.debug : false,
+    };
+}
+export const basicMemoryConfigSchema = {
+    parse: parseConfig,
+};

package/dist/context-engine/basic-memory-context-engine.d.ts

@@ -0,0 +1,34 @@
+import type { AssembleResult, BootstrapResult, CompactResult, ContextEngine, SubagentSpawnPreparation } from "openclaw/plugin-sdk";
+import type { BmClient } from "../bm-client.ts";
+import type { BasicMemoryConfig } from "../config.ts";
+export declare const MAX_ASSEMBLE_RECALL_CHARS = 1200;
+type BootstrapParams = Parameters<NonNullable<ContextEngine["bootstrap"]>>[0];
+type AssembleParams = Parameters<ContextEngine["assemble"]>[0];
+type AfterTurnParams = Parameters<NonNullable<ContextEngine["afterTurn"]>>[0];
+type CompactParams = Parameters<ContextEngine["compact"]>[0];
+type PrepareSubagentSpawnParams = Parameters<NonNullable<ContextEngine["prepareSubagentSpawn"]>>[0];
+type OnSubagentEndedParams = Parameters<NonNullable<ContextEngine["onSubagentEnded"]>>[0];
+export declare class BasicMemoryContextEngine implements ContextEngine {
+    private readonly client;
+    private readonly cfg;
+    readonly info: {
+        readonly id: "openclaw-basic-memory";
+        readonly name: "Basic Memory Context Engine";
+        readonly version: "0.1.5";
+        readonly ownsCompaction: false;
+    };
+    private readonly sessionState;
+    private readonly subagentState;
+    constructor(client: BmClient, cfg: BasicMemoryConfig);
+    bootstrap(params: BootstrapParams): Promise<BootstrapResult>;
+    ingest(): Promise<{
+        ingested: boolean;
+    }>;
+    assemble(params: AssembleParams): Promise<AssembleResult>;
+    afterTurn(params: AfterTurnParams): Promise<void>;
+    compact(params: CompactParams): Promise<CompactResult>;
+    prepareSubagentSpawn(params: PrepareSubagentSpawnParams): Promise<SubagentSpawnPreparation | undefined>;
+    onSubagentEnded(params: OnSubagentEndedParams): Promise<void>;
+    dispose(): Promise<void>;
+}
+export {};

package/dist/context-engine/basic-memory-context-engine.js

@@ -0,0 +1,176 @@
+import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core";
+import { selectCaptureTurn } from "../hooks/capture.js";
+import { loadRecallState } from "../hooks/recall.js";
+import { log } from "../logger.js";
+export const MAX_ASSEMBLE_RECALL_CHARS = 1200;
+const TRUNCATED_RECALL_SUFFIX = "\n\n[Basic Memory recall truncated]";
+const SUBAGENT_HANDOFF_FOLDER = "agent/subagents";
+const MAX_SUBAGENT_RECALL_CHARS = 800;
+function boundRecallContext(context) {
+    if (context.length <= MAX_ASSEMBLE_RECALL_CHARS) {
+        return context;
+    }
+    const trimmed = context
+        .slice(0, Math.max(0, MAX_ASSEMBLE_RECALL_CHARS - TRUNCATED_RECALL_SUFFIX.length))
+        .trimEnd();
+    return `${trimmed}${TRUNCATED_RECALL_SUFFIX}`;
+}
+function slugifySessionKey(sessionKey) {
+    return sessionKey
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+function buildSubagentNoteTitle(childSessionKey) {
+    return `subagent-handoff-${slugifySessionKey(childSessionKey)}`;
+}
+function buildSubagentHandoffContent(params) {
+    const sections = [
+        "# Subagent Handoff",
+        "",
+        "## Sessions",
+        `- Parent: ${params.parentSessionKey}`,
+        `- Child: ${params.childSessionKey}`,
+        "",
+        "## Lifecycle",
+        `- Spawned: ${new Date().toISOString()}`,
+    ];
+    if (params.recallContext) {
+        sections.push("", "## Parent Basic Memory Context", params.recallContext.slice(0, MAX_SUBAGENT_RECALL_CHARS).trimEnd());
+    }
+    return sections.join("\n");
+}
+function buildSubagentCompletionUpdate(params) {
+    const statusLine = params.reason === "completed"
+        ? "Child run completed. Durable conversation capture continues through the normal afterTurn path."
+        : `Child run ended with reason: ${params.reason}.`;
+    return [
+        "",
+        "## Completion",
+        `- Child: ${params.childSessionKey}`,
+        `- Ended: ${new Date().toISOString()}`,
+        `- Reason: ${params.reason}`,
+        "",
+        statusLine,
+    ].join("\n");
+}
+export class BasicMemoryContextEngine {
+    client;
+    cfg;
+    info = {
+        id: "openclaw-basic-memory",
+        name: "Basic Memory Context Engine",
+        version: "0.1.5",
+        ownsCompaction: false,
+    };
+    sessionState = new Map();
+    subagentState = new Map();
+    constructor(client, cfg) {
+        this.client = client;
+        this.cfg = cfg;
+    }
+    async bootstrap(params) {
+        if (!this.cfg.autoRecall) {
+            this.sessionState.delete(params.sessionId);
+            return { bootstrapped: false, reason: "autoRecall disabled" };
+        }
+        try {
+            const recall = await loadRecallState(this.client, this.cfg);
+            if (!recall) {
+                this.sessionState.delete(params.sessionId);
+                return { bootstrapped: false, reason: "no recall context found" };
+            }
+            this.sessionState.set(params.sessionId, {
+                recallContext: boundRecallContext(recall.context),
+            });
+            log.debug(`context-engine bootstrap: session=${params.sessionId} tasks=${recall.tasks.length} recent=${recall.recent.length}`);
+            return { bootstrapped: true };
+        }
+        catch (err) {
+            this.sessionState.delete(params.sessionId);
+            log.error("context-engine bootstrap failed", err);
+            return { bootstrapped: false, reason: "recall failed" };
+        }
+    }
+    async ingest() {
+        return { ingested: false };
+    }
+    async assemble(params) {
+        const state = this.sessionState.get(params.sessionId);
+        return {
+            messages: params.messages,
+            estimatedTokens: 0,
+            systemPromptAddition: state?.recallContext,
+        };
+    }
+    async afterTurn(params) {
+        if (!this.cfg.autoCapture)
+            return;
+        const newMessages = params.messages.slice(params.prePromptMessageCount);
+        const turn = selectCaptureTurn(newMessages, this.cfg.captureMinChars) ??
+            selectCaptureTurn(params.messages, this.cfg.captureMinChars);
+        if (!turn)
+            return;
+        log.debug(`context-engine afterTurn: session=${params.sessionId} user=${turn.userText.length} assistant=${turn.assistantText.length}`);
+        try {
+            await this.client.indexConversation(turn.userText, turn.assistantText);
+        }
+        catch (err) {
+            log.error("context-engine capture failed", err);
+        }
+    }
+    async compact(params) {
+        return delegateCompactionToRuntime(params);
+    }
+    async prepareSubagentSpawn(params) {
+        const parentState = this.sessionState.get(params.parentSessionKey);
+        const noteTitle = buildSubagentNoteTitle(params.childSessionKey);
+        try {
+            const note = await this.client.writeNote(noteTitle, buildSubagentHandoffContent({
+                parentSessionKey: params.parentSessionKey,
+                childSessionKey: params.childSessionKey,
+                recallContext: parentState?.recallContext,
+            }), SUBAGENT_HANDOFF_FOLDER);
+            this.subagentState.set(params.childSessionKey, {
+                noteIdentifier: note.permalink,
+                noteTitle: note.title,
+                parentSessionKey: params.parentSessionKey,
+            });
+            return {
+                rollback: async () => {
+                    const handoff = this.subagentState.get(params.childSessionKey);
+                    this.subagentState.delete(params.childSessionKey);
+                    if (!handoff)
+                        return;
+                    try {
+                        await this.client.deleteNote(handoff.noteIdentifier);
+                    }
+                    catch (err) {
+                        log.error("context-engine subagent rollback failed", err);
+                    }
+                },
+            };
+        }
+        catch (err) {
+            log.error("context-engine prepareSubagentSpawn failed", err);
+            return undefined;
+        }
+    }
+    async onSubagentEnded(params) {
+        const handoff = this.subagentState.get(params.childSessionKey);
+        if (!handoff)
+            return;
+        this.subagentState.delete(params.childSessionKey);
+        try {
+            await this.client.editNote(handoff.noteIdentifier, "append", buildSubagentCompletionUpdate(params));
+        }
+        catch (err) {
+            log.error("context-engine onSubagentEnded failed", err);
+        }
+    }
+    async dispose() {
+        this.sessionState.clear();
+        this.subagentState.clear();
+    }
+}

package/dist/hooks/capture.d.ts

@@ -0,0 +1,24 @@
+import type { BmClient } from "../bm-client.ts";
+import type { BasicMemoryConfig } from "../config.ts";
+/**
+ * Extract text content from a message object.
+ */
+export declare function extractText(msg: Record<string, unknown>): string;
+/**
+ * Find the last user+assistant turn from the messages array.
+ */
+export declare function getLastTurn(messages: unknown[]): {
+    userText: string;
+    assistantText: string;
+};
+export declare function selectCaptureTurn(messages: unknown[], minChars: number): {
+    userText: string;
+    assistantText: string;
+} | null;
+/**
+ * Build the post-turn capture handler for Mode B.
+ *
+ * After each agent turn, extracts the conversation content and indexes it
+ * into the Basic Memory knowledge graph as a conversation note.
+ */
+export declare function buildCaptureHandler(client: BmClient, cfg: BasicMemoryConfig): (event: Record<string, unknown>) => Promise<void>;

package/dist/hooks/capture.js

@@ -0,0 +1,88 @@
+import { log } from "../logger.js";
+/**
+ * Extract text content from a message object.
+ */
+export function extractText(msg) {
+    const content = msg.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string") {
+                parts.push(b.text);
+            }
+        }
+        return parts.join("\n");
+    }
+    return "";
+}
+/**
+ * Find the last user+assistant turn from the messages array.
+ */
+export function getLastTurn(messages) {
+    let lastUserIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg &&
+            typeof msg === "object" &&
+            msg.role === "user") {
+            lastUserIdx = i;
+            break;
+        }
+    }
+    if (lastUserIdx < 0)
+        return { userText: "", assistantText: "" };
+    let userText = "";
+    let assistantText = "";
+    for (let i = lastUserIdx; i < messages.length; i++) {
+        const msg = messages[i];
+        if (!msg?.role)
+            continue;
+        const text = extractText(msg);
+        if (msg.role === "user")
+            userText = text;
+        else if (msg.role === "assistant")
+            assistantText = text;
+    }
+    return { userText, assistantText };
+}
+export function selectCaptureTurn(messages, minChars) {
+    const turn = getLastTurn(messages);
+    if (!turn.userText && !turn.assistantText)
+        return null;
+    if (turn.userText.length < minChars && turn.assistantText.length < minChars) {
+        return null;
+    }
+    return turn;
+}
+/**
+ * Build the post-turn capture handler for Mode B.
+ *
+ * After each agent turn, extracts the conversation content and indexes it
+ * into the Basic Memory knowledge graph as a conversation note.
+ */
+export function buildCaptureHandler(client, cfg) {
+    const minChars = cfg.captureMinChars;
+    return async (event) => {
+        if (!event.success ||
+            !Array.isArray(event.messages) ||
+            event.messages.length === 0) {
+            return;
+        }
+        const turn = selectCaptureTurn(event.messages, minChars);
+        if (!turn)
+            return;
+        const { userText, assistantText } = turn;
+        log.debug(`capturing conversation: user=${userText.length} chars, assistant=${assistantText.length} chars`);
+        try {
+            await client.indexConversation(userText, assistantText);
+        }
+        catch (err) {
+            log.error("capture failed", err);
+        }
+    };
+}

package/dist/hooks/recall.d.ts

@@ -0,0 +1,24 @@
+import type { BmClient, RecentResult, SearchResult } from "../bm-client.ts";
+import type { BasicMemoryConfig } from "../config.ts";
+export interface RecallState {
+    tasks: SearchResult[];
+    recent: RecentResult[];
+    context: string;
+}
+/**
+ * Format recalled context from active tasks and recent activity.
+ * Returns empty string if nothing was found.
+ */
+export declare function formatRecallContext(tasks: SearchResult[], recent: RecentResult[], prompt: string): string;
+export declare function loadRecallState(client: BmClient, cfg: BasicMemoryConfig): Promise<RecallState | null>;
+/**
+ * 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 declare function buildRecallHandler(client: BmClient, cfg: BasicMemoryConfig): (_event: Record<string, unknown>) => Promise<{
+    context?: undefined;
+} | {
+    context: string;
+}>;