@basicmemory/openclaw-basic-memory 0.1.5 → 0.2.1

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

@@ -0,0 +1,330 @@
+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 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
+
+interface SessionMemoryState {
+  recallContext: string
+}
+
+interface SubagentHandoffState {
+  noteIdentifier: string
+  noteTitle: string
+  parentSessionKey: string
+}
+
+function boundRecallContext(context: string): string {
+  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: string): string {
+  return sessionKey
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80)
+}
+
+function buildSubagentNoteTitle(childSessionKey: string): string {
+  return `subagent-handoff-${slugifySessionKey(childSessionKey)}`
+}
+
+function buildSubagentHandoffContent(params: {
+  parentSessionKey: string
+  childSessionKey: string
+  recallContext?: string
+}): string {
+  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: {
+  childSessionKey: string
+  reason: "deleted" | "completed" | "swept" | "released"
+}): string {
+  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")
+}
+
+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",
+    name: "Basic Memory Context Engine",
+    version: "0.1.5",
+    ownsCompaction: false,
+  } as const
+
+  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,
+    private readonly cfg: BasicMemoryConfig,
+  ) {}
+
+  async bootstrap(params: {
+    sessionId: string
+    sessionFile: string
+  }): Promise<BootstrapResult> {
+    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(): Promise<{ ingested: boolean }> {
+    return { ingested: false }
+  }
+
+  async assemble(params: {
+    sessionId: string
+    messages: AgentMessage[]
+    tokenBudget?: number
+  }): Promise<AssembleResult> {
+    const state = this.sessionState.get(params.sessionId)
+
+    return {
+      messages: params.messages,
+      estimatedTokens: 0,
+      systemPromptAddition: state?.recallContext,
+    }
+  }
+
+  async afterTurn(params: {
+    sessionId: string
+    sessionFile: string
+    messages: AgentMessage[]
+    prePromptMessageCount: number
+    autoCompactionSummary?: string
+    isHeartbeat?: boolean
+    tokenBudget?: number
+    runtimeContext?: Record<string, unknown>
+  }): Promise<void> {
+    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: {
+    sessionId: string
+    sessionFile: string
+    tokenBudget?: number
+    force?: boolean
+    currentTokenCount?: number
+    compactionTarget?: "budget" | "threshold"
+    customInstructions?: string
+    runtimeContext?: Record<string, unknown>
+  }): Promise<CompactResult> {
+    const legacy = await this.getLegacyContextEngine()
+    return legacy.compact(params)
+  }
+
+  async prepareSubagentSpawn(params: {
+    parentSessionKey: string
+    childSessionKey: string
+    ttlMs?: number
+  }): Promise<{ rollback: () => Promise<void> } | undefined> {
+    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: {
+    childSessionKey: string
+    reason: "deleted" | "completed" | "swept" | "released"
+  }): Promise<void> {
+    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(): Promise<void> {
+    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/hooks/capture.ts

@@ -5,7 +5,7 @@ import { log } from "../logger.ts"
 /**
  * Extract text content from a message object.
  */
-function extractText(msg: Record<string, unknown>): string {
+export function extractText(msg: Record<string, unknown>): string {
   const content = msg.content
   if (typeof content === "string") return content
 
@@ -27,7 +27,7 @@ function extractText(msg: Record<string, unknown>): string {
 /**
  * Find the last user+assistant turn from the messages array.
  */
-function getLastTurn(messages: unknown[]): {
+export function getLastTurn(messages: unknown[]): {
   userText: string
   assistantText: string
 } {
@@ -60,6 +60,19 @@ function getLastTurn(messages: unknown[]): {
   return { userText, assistantText }
 }
 
+export function selectCaptureTurn(
+  messages: unknown[],
+  minChars: number,
+): { userText: string; assistantText: string } | null {
+  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.
  *
@@ -77,10 +90,9 @@ export function buildCaptureHandler(client: BmClient, cfg: BasicMemoryConfig) {
       return
     }
 
-    const { userText, assistantText } = getLastTurn(event.messages)
-
-    if (!userText && !assistantText) return
-    if (userText.length < minChars && assistantText.length < minChars) 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`,

package/hooks/recall.ts

@@ -2,6 +2,12 @@ import type { BmClient, RecentResult, SearchResult } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { log } from "../logger.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.
@@ -32,6 +38,24 @@ export function formatRecallContext(
   return `${sections.join("\n\n")}\n\n---\n${prompt}`
 }
 
+export async function loadRecallState(
+  client: BmClient,
+  cfg: BasicMemoryConfig,
+): Promise<RecallState | null> {
+  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.
  *
@@ -41,22 +65,14 @@ export function formatRecallContext(
 export function buildRecallHandler(client: BmClient, cfg: BasicMemoryConfig) {
   return async (_event: Record<string, unknown>) => {
     try {
-      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 {}
+      const recall = await loadRecallState(client, cfg)
+      if (!recall) return {}
 
       log.debug(
-        `recall: ${tasks.length} active tasks, ${recent.length} recent items`,
+        `recall: ${recall.tasks.length} active tasks, ${recall.recent.length} recent items`,
       )
 
-      return { context }
+      return { context: recall.context }
     } catch (err) {
       log.error("recall failed", err)
       return {}

package/index.ts

@@ -10,9 +10,7 @@ import {
   parseConfig,
   resolveProjectPath,
 } from "./config.ts"
-
-import { buildCaptureHandler } from "./hooks/capture.ts"
-import { buildRecallHandler } from "./hooks/recall.ts"
+import { BasicMemoryContextEngine } from "./context-engine/basic-memory-context-engine.ts"
 import { initLogger, log } from "./logger.ts"
 import { CONVERSATION_SCHEMA_CONTENT } from "./schema/conversation-schema.ts"
 import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.ts"
@@ -33,6 +31,8 @@ import { registerSchemaValidateTool } from "./tools/schema-validate.ts"
 import { registerSearchTool } from "./tools/search-notes.ts"
 import { registerWriteTool } from "./tools/write-note.ts"
 
+const BASIC_MEMORY_RELEASE_TAG = "v0.20.2"
+
 export default {
   id: "openclaw-basic-memory",
   name: "Basic Memory",
@@ -69,14 +69,11 @@ export default {
     // --- Composited memory_search + memory_get (always registered) ---
     registerMemoryProvider(api, client, cfg)
     log.info("registered composited memory_search + memory_get")
-
-    if (cfg.autoCapture) {
-      api.on("agent_end", buildCaptureHandler(client, cfg))
-    }
-
-    if (cfg.autoRecall) {
-      api.on("agent_start", buildRecallHandler(client, cfg))
-    }
+    api.registerContextEngine(
+      "openclaw-basic-memory",
+      () => new BasicMemoryContextEngine(client, cfg),
+    )
+    log.info("registered Basic Memory context engine")
 
     // --- Commands ---
     registerCommands(api, client)
@@ -101,7 +98,7 @@ export default {
               "installing basic-memory via uv (this may take a minute)...",
             )
             const result = execSync(
-              'uv tool install "basic-memory @ git+https://github.com/basicmachines-co/basic-memory.git@main" --force',
+              `uv tool install "basic-memory @ git+https://github.com/basicmachines-co/basic-memory.git@${BASIC_MEMORY_RELEASE_TAG}" --force`,
               { encoding: "utf-8", timeout: 120_000, stdio: "pipe" },
             )
             log.info(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -11,6 +11,7 @@
   "files": [
     "index.ts",
     "bm-client.ts",
+    "context-engine/",
     "config.ts",
     "logger.ts",
     "commands/cli.ts",
@@ -31,7 +32,6 @@
     "tools/schema-validate.ts",
     "tools/search-notes.ts",
     "tools/write-note.ts",
-    "types/openclaw.d.ts",
     "schema/task-schema.ts",
     "schema/conversation-schema.ts",
     "skills/",
@@ -49,7 +49,7 @@
     "@sinclair/typebox": "0.34.47"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.29"
+    "openclaw": ">=2026.3.7"
   },
   "scripts": {
     "postinstall": "bash scripts/setup-bm.sh || true",
@@ -69,8 +69,9 @@
     ]
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.8",
+    "@biomejs/biome": "^2.4.6",
     "@types/node": "^20.0.0",
+    "openclaw": "^2026.3.8",
     "typescript": "^5.9.3"
   }
 }

package/scripts/setup-bm.sh

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
-# Install basic-memory CLI via uv from the latest main branch.
+# Install basic-memory CLI via uv from a pinned release tag.
 # Idempotent — safe to re-run. Fails gracefully when uv is absent.
 set -euo pipefail
 
 BM_REPO="https://github.com/basicmachines-co/basic-memory.git"
-BM_REF="${BM_REF:-main}"
+BM_REF="${BM_REF:-v0.20.2}"
 
 # ── check for uv ──────────────────────────────────────────────────
 if ! command -v uv >/dev/null 2>&1; then

package/skills/manifest.json

@@ -14,6 +14,11 @@
     "name": "memory-lifecycle",
     "description": "Manage entity status transitions in Basic Memory: archive completed work, move notes between status folders, update frontmatter, and handle edge cases. Use when marking items complete, archiving old entities, or managing any folder-based status workflow."
   },
+  {
+    "dir": "memory-literary-analysis",
+    "name": "memory-literary-analysis",
+    "description": "Analyze a complete literary work into a structured Basic Memory knowledge graph. Covers schema design, entity seeding, chapter-by-chapter processing, cross-referencing, validation, and visualization."
+  },
   {
     "dir": "memory-metadata-search",
     "name": "memory-metadata-search",