@basicmemory/openclaw-basic-memory 0.2.2 → 0.2.4

package/README.md

@@ -45,6 +45,7 @@ Then install the plugin:
 
 ```bash
 openclaw plugins install @basicmemory/openclaw-basic-memory
+openclaw plugins enable openclaw-basic-memory --slot memory
 openclaw gateway restart
 ```
 
@@ -54,7 +55,8 @@ Verify:
 
 ```bash
 openclaw plugins list
-openclaw plugins info openclaw-basic-memory
+openclaw plugins inspect openclaw-basic-memory --json
+openclaw plugins doctor
 ```
 
 ## Configuration
@@ -63,8 +65,15 @@ openclaw plugins info openclaw-basic-memory
 
 ```json5
 {
-  "openclaw-basic-memory": {
-    enabled: true
+  plugins: {
+    entries: {
+      "openclaw-basic-memory": {
+        enabled: true
+      }
+    },
+    slots: {
+      memory: "openclaw-basic-memory"
+    }
   }
 }
 ```
@@ -75,16 +84,23 @@ This uses sensible defaults: auto-generated project name, maps to your workspace
 
 ```json5
 {
-  "openclaw-basic-memory": {
-    enabled: true,
-    config: {
-      project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
-      projectPath: ".",            // Project directory (default: workspace root)
-      memoryDir: "memory/",        // Where task notes live
-      memoryFile: "MEMORY.md",     // Working memory file
-      autoCapture: true,           // Record conversations as daily notes
-      autoRecall: true,            // Inject active tasks + recent activity at session start
-      debug: false                 // Verbose logging
+  plugins: {
+    entries: {
+      "openclaw-basic-memory": {
+        enabled: true,
+        config: {
+          project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
+          projectPath: ".",            // Project directory (default: workspace root)
+          memoryDir: "memory/",        // Where task notes live
+          memoryFile: "MEMORY.md",     // Working memory file
+          autoCapture: true,           // Record conversations as daily notes
+          autoRecall: true,            // Inject active tasks + recent activity at session start
+          debug: false                 // Verbose logging
+        }
+      }
+    },
+    slots: {
+      memory: "openclaw-basic-memory"
     }
   }
 }
@@ -172,19 +188,23 @@ openclaw basic-memory status
 
 ## Bundled skills
 
-Six skills ship with the plugin — no installation needed:
+Ten skills ship with the plugin — no installation needed:
 
-- **memory-tasks** — structured task tracking that survives context compaction
-- **memory-reflect** — periodic consolidation of recent notes into durable memory
 - **memory-defrag** — cleanup and reorganization of memory files
-- **memory-schema** — schema lifecycle (infer, create, validate, diff)
+- **memory-ingest** — import existing material into Basic Memory
+- **memory-lifecycle** — manage note/project lifecycle workflows
+- **memory-literary-analysis** — analyze texts and reading notes
 - **memory-metadata-search** — query notes by frontmatter fields
 - **memory-notes** — guidance for writing well-structured notes
+- **memory-reflect** — periodic consolidation of recent notes into durable memory
+- **memory-research** — research synthesis into durable notes
+- **memory-schema** — schema lifecycle (infer, create, validate, diff)
+- **memory-tasks** — structured task tracking that survives context compaction
 
 ### Updating skills
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills --agent openclaw
+bun run fetch-skills
 ```
 
 ## Task notes

package/commands/cli.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { log } from "../logger.ts"

package/commands/skills.ts

@@ -1,11 +1,9 @@
-import { readFileSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const SKILLS_DIR = resolve(__dirname, "..", "skills")
-const MANIFEST_PATH = resolve(SKILLS_DIR, "manifest.json")
 
 interface ManifestEntry {
   dir: string
@@ -13,9 +11,22 @@ interface ManifestEntry {
   description: string
 }
 
-function loadManifest(): ManifestEntry[] {
+function resolveSkillsDir(api: OpenClawPluginApi): string {
+  if (api.resolvePath) {
+    return api.resolvePath("skills")
+  }
+
+  const sourceRootSkills = resolve(__dirname, "..", "skills")
+  if (existsSync(sourceRootSkills)) {
+    return sourceRootSkills
+  }
+
+  return resolve(__dirname, "..", "..", "skills")
+}
+
+function loadManifest(skillsDir: string): ManifestEntry[] {
   try {
-    const raw = readFileSync(MANIFEST_PATH, "utf-8")
+    const raw = readFileSync(resolve(skillsDir, "manifest.json"), "utf-8")
     return JSON.parse(raw) as ManifestEntry[]
   } catch {
     throw new Error(
@@ -24,16 +35,17 @@ function loadManifest(): ManifestEntry[] {
   }
 }
 
-function loadSkill(dir: string): string {
-  return readFileSync(resolve(SKILLS_DIR, dir, "SKILL.md"), "utf-8")
+function loadSkill(skillsDir: string, dir: string): string {
+  return readFileSync(resolve(skillsDir, dir, "SKILL.md"), "utf-8")
 }
 
 export function registerSkillCommands(api: OpenClawPluginApi): void {
-  const manifest = loadManifest()
+  const skillsDir = resolveSkillsDir(api)
+  const manifest = loadManifest(skillsDir)
 
   for (const entry of manifest) {
     const commandName = entry.dir.replace(/^memory-/, "")
-    const content = loadSkill(entry.dir)
+    const content = loadSkill(skillsDir, entry.dir)
 
     api.registerCommand({
       name: commandName,

package/commands/slash.ts

@@ -1,7 +1,7 @@
 import { execSync } from "node:child_process"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
@@ -16,7 +16,9 @@ export function registerCommands(
     description: "Install or update the Basic Memory CLI (requires uv)",
     requireAuth: true,
     handler: async () => {
-      const scriptPath = resolve(__dirname, "..", "scripts", "setup-bm.sh")
+      const scriptPath = api.resolvePath
+        ? api.resolvePath("scripts/setup-bm.sh")
+        : resolve(__dirname, "..", "scripts", "setup-bm.sh")
       log.info(`/bm-setup: running ${scriptPath}`)
 
       try {

package/config.ts

@@ -101,6 +101,7 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
   let cloud: CloudConfig | undefined
   if (cfg.cloud && typeof cfg.cloud === "object" && !Array.isArray(cfg.cloud)) {
     const c = cfg.cloud as Record<string, unknown>
+    assertAllowedKeys(c, ["url", "api_key"], "basic-memory cloud config")
     if (typeof c.url === "string" && typeof c.api_key === "string") {
       cloud = { url: c.url, api_key: c.api_key }
     }

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

@@ -1,25 +1,52 @@
-import { createRequire } from "node:module"
-import { dirname, resolve } from "node:path"
-import { pathToFileURL } from "node:url"
 import type { AgentMessage } from "@mariozechner/pi-agent-core"
-import type {
-  AssembleResult,
-  BootstrapResult,
-  CompactResult,
-  ContextEngine,
-} from "openclaw/plugin-sdk"
+import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"
 import type { BmClient } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { selectCaptureTurn } from "../hooks/capture.ts"
 import { loadRecallState } from "../hooks/recall.ts"
 import { log } from "../logger.ts"
 
-const require = createRequire(import.meta.url)
 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
 
+type AssembleResult = {
+  messages: AgentMessage[]
+  estimatedTokens: number
+  systemPromptAddition?: string
+}
+
+type BootstrapResult = {
+  bootstrapped: boolean
+  importedMessages?: number
+  reason?: string
+}
+
+type CompactResult = {
+  ok: boolean
+  compacted: boolean
+  reason?: string
+  result?: {
+    summary?: string
+    firstKeptEntryId?: string
+    tokensBefore: number
+    tokensAfter?: number
+    details?: unknown
+    sessionId?: string
+    sessionFile?: string
+  }
+}
+
+interface ContextEngine {
+  readonly info: {
+    id: string
+    name: string
+    version?: string
+    ownsCompaction?: boolean
+  }
+}
+
 interface SessionMemoryState {
   recallContext: string
 }
@@ -104,36 +131,6 @@ function buildSubagentCompletionUpdate(params: {
   ].join("\n")
 }
 
-type LegacyContextEngineModule = {
-  LegacyContextEngine: new () => {
-    compact(params: {
-      sessionId: string
-      sessionFile: string
-      tokenBudget?: number
-      force?: boolean
-      currentTokenCount?: number
-      compactionTarget?: "budget" | "threshold"
-      customInstructions?: string
-      runtimeContext?: Record<string, unknown>
-    }): Promise<CompactResult>
-  }
-}
-
-async function loadLegacyContextEngine(): Promise<
-  LegacyContextEngineModule["LegacyContextEngine"]
-> {
-  const pluginSdkPath = require.resolve("openclaw/plugin-sdk")
-  const legacyPath = resolve(
-    dirname(pluginSdkPath),
-    "context-engine",
-    "legacy.js",
-  )
-  const module = (await import(
-    pathToFileURL(legacyPath).href
-  )) as LegacyContextEngineModule
-  return module.LegacyContextEngine
-}
-
 export class BasicMemoryContextEngine implements ContextEngine {
   readonly info = {
     id: "openclaw-basic-memory",
@@ -144,9 +141,6 @@ export class BasicMemoryContextEngine implements ContextEngine {
 
   private readonly sessionState = new Map<string, SessionMemoryState>()
   private readonly subagentState = new Map<string, SubagentHandoffState>()
-  private legacyContextEnginePromise: Promise<
-    InstanceType<LegacyContextEngineModule["LegacyContextEngine"]>
-  > | null = null
 
   constructor(
     private readonly client: BmClient,
@@ -243,8 +237,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
     customInstructions?: string
     runtimeContext?: Record<string, unknown>
   }): Promise<CompactResult> {
-    const legacy = await this.getLegacyContextEngine()
-    return legacy.compact(params)
+    return delegateCompactionToRuntime(params)
   }
 
   async prepareSubagentSpawn(params: {
@@ -315,16 +308,4 @@ export class BasicMemoryContextEngine implements ContextEngine {
     this.sessionState.clear()
     this.subagentState.clear()
   }
-
-  private async getLegacyContextEngine(): Promise<
-    InstanceType<LegacyContextEngineModule["LegacyContextEngine"]>
-  > {
-    if (!this.legacyContextEnginePromise) {
-      this.legacyContextEnginePromise = loadLegacyContextEngine().then(
-        (LegacyContextEngine) => new LegacyContextEngine(),
-      )
-    }
-
-    return this.legacyContextEnginePromise
-  }
 }

package/dist/bm-client.d.ts

@@ -0,0 +1,177 @@
+export declare class NoteAlreadyExistsError extends Error {
+    readonly permalink: string;
+    constructor(title: string, permalink: string);
+}
+export interface SearchResult {
+    title: string;
+    permalink: string;
+    content: string;
+    score?: number;
+    file_path: string;
+}
+export interface NoteResult {
+    title: string;
+    permalink: string;
+    content: string;
+    file_path: string;
+    frontmatter?: Record<string, unknown> | null;
+    checksum?: string | null;
+    action?: "created" | "updated";
+}
+export interface EditNoteResult {
+    title: string;
+    permalink: string;
+    file_path: string;
+    operation: "append" | "prepend" | "find_replace" | "replace_section";
+    checksum?: string | null;
+}
+interface ReadNoteOptions {
+    includeFrontmatter?: boolean;
+}
+interface EditNoteOptions {
+    find_text?: string;
+    section?: string;
+    expected_replacements?: number;
+}
+export interface ContextResult {
+    results: Array<{
+        primary_result: NoteResult;
+        observations: Array<{
+            category: string;
+            content: string;
+        }>;
+        related_results: Array<{
+            type: "relation" | "entity";
+            title?: string;
+            permalink: string;
+            relation_type?: string;
+            from_entity?: string;
+            to_entity?: string;
+        }>;
+    }>;
+}
+export interface RecentResult {
+    title: string;
+    permalink: string;
+    file_path: string;
+    created_at: string;
+}
+export interface ProjectListResult {
+    name: string;
+    path: string;
+    display_name?: string | null;
+    is_private?: boolean;
+    is_default?: boolean;
+    isDefault?: boolean;
+    workspace_name?: string | null;
+    workspace_type?: string | null;
+    workspace_tenant_id?: string | null;
+}
+export interface WorkspaceResult {
+    tenant_id: string;
+    name: string;
+    workspace_type: string;
+    role: string;
+    organization_id?: string | null;
+    has_active_subscription: boolean;
+}
+export interface SchemaValidationResult {
+    entity_type: string | null;
+    total_notes: number;
+    total_entities: number;
+    valid_count: number;
+    warning_count: number;
+    error_count: number;
+    results: Array<{
+        identifier: string;
+        valid: boolean;
+        warnings: string[];
+        errors: string[];
+    }>;
+}
+export interface SchemaInferResult {
+    entity_type: string;
+    notes_analyzed: number;
+    field_frequencies: Array<{
+        name: string;
+        percentage: number;
+        count: number;
+        total: number;
+        source: string;
+        sample_values?: string[];
+        is_array?: boolean;
+        target_type?: string | null;
+    }>;
+    suggested_schema: Record<string, unknown>;
+    suggested_required: string[];
+    suggested_optional: string[];
+    excluded: string[];
+}
+export interface SchemaDiffResult {
+    entity_type: string;
+    schema_found: boolean;
+    new_fields: Array<{
+        name: string;
+        source: string;
+        count: number;
+        total: number;
+        percentage: number;
+    }>;
+    dropped_fields: Array<{
+        name: string;
+        source: string;
+        declared_in?: string;
+    }>;
+    cardinality_changes: string[];
+}
+export declare class BmClient {
+    private bmPath;
+    private project;
+    private cwd?;
+    private env?;
+    private shouldRun;
+    private client;
+    private transport;
+    private connectPromise;
+    private retryDelaysMs;
+    constructor(bmPath: string, project: string);
+    start(options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<void>;
+    stop(): Promise<void>;
+    private connectWithRetries;
+    private ensureConnected;
+    private connectFresh;
+    private assertRequiredTools;
+    private disconnectCurrent;
+    private callToolRaw;
+    private callTool;
+    ensureProject(projectPath: string): Promise<void>;
+    listWorkspaces(): Promise<WorkspaceResult[]>;
+    listProjects(workspace?: string): Promise<ProjectListResult[]>;
+    search(query?: string, limit?: number, project?: string, metadata?: {
+        filters?: Record<string, unknown>;
+        tags?: string[];
+        status?: string;
+        note_types?: string[];
+        entity_types?: string[];
+    }): Promise<SearchResult[]>;
+    readNote(identifier: string, options?: ReadNoteOptions, project?: string): Promise<NoteResult>;
+    writeNote(title: string, content: string, folder: string, project?: string, overwrite?: boolean): Promise<NoteResult>;
+    buildContext(url: string, depth?: number, project?: string): Promise<ContextResult>;
+    recentActivity(timeframe?: string, project?: string): Promise<RecentResult[]>;
+    editNote(identifier: string, operation: "append" | "prepend" | "find_replace" | "replace_section", content: string, options?: EditNoteOptions, project?: string): Promise<EditNoteResult>;
+    deleteNote(identifier: string, project?: string): Promise<{
+        title: string;
+        permalink: string;
+        file_path: string;
+    }>;
+    moveNote(identifier: string, newFolder: string, project?: string): Promise<NoteResult>;
+    schemaValidate(noteType?: string, identifier?: string, project?: string): Promise<SchemaValidationResult>;
+    schemaInfer(noteType: string, threshold?: number, project?: string): Promise<SchemaInferResult>;
+    schemaDiff(noteType: string, project?: string): Promise<SchemaDiffResult>;
+    indexConversation(userMessage: string, assistantResponse: string): Promise<void>;
+    getProject(): string;
+}
+export {};