@basicmemory/openclaw-basic-memory 0.2.0 → 0.2.2

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

@@ -0,0 +1,398 @@
+import { beforeEach, describe, expect, it, jest } from "bun:test"
+import type { AgentMessage } from "@mariozechner/pi-agent-core"
+import type { BmClient } from "../bm-client.ts"
+import type { BasicMemoryConfig } from "../config.ts"
+import {
+  BasicMemoryContextEngine,
+  MAX_ASSEMBLE_RECALL_CHARS,
+} from "./basic-memory-context-engine.ts"
+
+function makeConfig(overrides?: Partial<BasicMemoryConfig>): BasicMemoryConfig {
+  return {
+    project: "test-project",
+    bmPath: "bm",
+    memoryDir: "memory/",
+    memoryFile: "MEMORY.md",
+    projectPath: "/tmp/test-project",
+    autoCapture: true,
+    captureMinChars: 10,
+    autoRecall: true,
+    recallPrompt:
+      "Check for active tasks and recent activity. Summarize anything relevant to the current session.",
+    debug: false,
+    ...overrides,
+  }
+}
+
+function makeMessages(
+  messages: Array<Record<string, unknown>>,
+): AgentMessage[] {
+  return messages as AgentMessage[]
+}
+
+describe("BasicMemoryContextEngine", () => {
+  let mockClient: {
+    search: jest.Mock
+    recentActivity: jest.Mock
+    indexConversation: jest.Mock
+    writeNote: jest.Mock
+    editNote: jest.Mock
+    deleteNote: jest.Mock
+  }
+
+  beforeEach(() => {
+    mockClient = {
+      search: jest.fn().mockResolvedValue([
+        {
+          title: "Fix auth rollout",
+          permalink: "fix-auth-rollout",
+          content: "Continue staging verification for auth rollout.",
+          file_path: "memory/tasks/fix-auth-rollout.md",
+        },
+      ]),
+      recentActivity: jest.fn().mockResolvedValue([
+        {
+          title: "API review",
+          permalink: "api-review",
+          file_path: "memory/api-review.md",
+          created_at: "2026-03-09T12:00:00Z",
+        },
+      ]),
+      indexConversation: jest.fn().mockResolvedValue(undefined),
+      writeNote: jest.fn().mockResolvedValue({
+        title: "subagent-handoff-agent-test-subagent-child-1",
+        permalink:
+          "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+        file_path:
+          "memory/agent/subagents/subagent-handoff-agent-test-subagent-child-1.md",
+        content: "",
+      }),
+      editNote: jest.fn().mockResolvedValue({
+        title: "subagent-handoff-agent-test-subagent-child-1",
+        permalink:
+          "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+        file_path:
+          "memory/agent/subagents/subagent-handoff-agent-test-subagent-child-1.md",
+        operation: "append",
+      }),
+      deleteNote: jest.fn().mockResolvedValue({
+        title: "subagent-handoff-agent-test-subagent-child-1",
+        permalink:
+          "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+        file_path:
+          "memory/agent/subagents/subagent-handoff-agent-test-subagent-child-1.md",
+      }),
+    }
+  })
+
+  it("bootstraps recall state from active tasks and recent activity", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await expect(
+      engine.bootstrap({
+        sessionId: "session-1",
+        sessionFile: "/tmp/session-1.jsonl",
+      }),
+    ).resolves.toEqual({ bootstrapped: true })
+    expect(mockClient.search).toHaveBeenCalledWith(undefined, 5, undefined, {
+      note_types: ["Task"],
+      status: "active",
+    })
+    expect(mockClient.recentActivity).toHaveBeenCalledWith("1d")
+  })
+
+  it("skips bootstrap when recall is disabled", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig({ autoRecall: false }),
+    )
+
+    await expect(
+      engine.bootstrap({
+        sessionId: "session-2",
+        sessionFile: "/tmp/session-2.jsonl",
+      }),
+    ).resolves.toEqual({
+      bootstrapped: false,
+      reason: "autoRecall disabled",
+    })
+
+    const result = await engine.assemble({
+      sessionId: "session-2",
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+    })
+
+    expect(result).toEqual({
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+      estimatedTokens: 0,
+    })
+  })
+
+  it("injects bounded BM recall during assemble when bootstrap found context", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await engine.bootstrap({
+      sessionId: "session-assemble",
+      sessionFile: "/tmp/session-assemble.jsonl",
+    })
+
+    const result = await engine.assemble({
+      sessionId: "session-assemble",
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+    })
+
+    expect(result.messages).toEqual(
+      makeMessages([{ role: "user", content: "hello" }]),
+    )
+    expect(result.systemPromptAddition).toContain("## Active Tasks")
+    expect(result.systemPromptAddition).toContain("Fix auth rollout")
+    expect(result.systemPromptAddition).toContain("## Recent Activity")
+    expect(result.systemPromptAddition).toContain("API review")
+  })
+
+  it("returns a no-op bootstrap result when there is no recall context", async () => {
+    mockClient.search.mockResolvedValue([])
+    mockClient.recentActivity.mockResolvedValue([])
+
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await expect(
+      engine.bootstrap({
+        sessionId: "session-3",
+        sessionFile: "/tmp/session-3.jsonl",
+      }),
+    ).resolves.toEqual({
+      bootstrapped: false,
+      reason: "no recall context found",
+    })
+
+    const result = await engine.assemble({
+      sessionId: "session-3",
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+    })
+
+    expect(result).toEqual({
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+      estimatedTokens: 0,
+    })
+  })
+
+  it("keeps assemble recall stable and within the hard bound", async () => {
+    mockClient.search.mockResolvedValue([
+      {
+        title: "Long task",
+        permalink: "long-task",
+        content: "A".repeat(4000),
+        file_path: "memory/tasks/long-task.md",
+      },
+    ])
+    mockClient.recentActivity.mockResolvedValue([
+      {
+        title: "Long recent item",
+        permalink: "long-recent-item",
+        file_path: "memory/long-recent-item.md",
+        created_at: "2026-03-09T12:00:00Z",
+      },
+    ])
+
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig({
+        recallPrompt: "P".repeat(4000),
+      }),
+    )
+
+    await engine.bootstrap({
+      sessionId: "session-bounded",
+      sessionFile: "/tmp/session-bounded.jsonl",
+    })
+
+    const first = await engine.assemble({
+      sessionId: "session-bounded",
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+    })
+    const second = await engine.assemble({
+      sessionId: "session-bounded",
+      messages: makeMessages([{ role: "user", content: "hello" }]),
+    })
+
+    expect(first.systemPromptAddition).toBeDefined()
+    expect(first.systemPromptAddition?.length).toBeLessThanOrEqual(
+      MAX_ASSEMBLE_RECALL_CHARS,
+    )
+    expect(first.systemPromptAddition).toContain(
+      "[Basic Memory recall truncated]",
+    )
+    expect(second.systemPromptAddition).toBe(first.systemPromptAddition)
+  })
+
+  it("creates a parent-to-child BM handoff note on subagent spawn", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await engine.bootstrap({
+      sessionId: "parent-session",
+      sessionFile: "/tmp/parent-session.jsonl",
+    })
+
+    const preparation = await engine.prepareSubagentSpawn({
+      parentSessionKey: "parent-session",
+      childSessionKey: "agent:test:subagent:child-1",
+    })
+
+    expect(preparation).toBeDefined()
+    expect(mockClient.writeNote).toHaveBeenCalledWith(
+      "subagent-handoff-agent-test-subagent-child-1",
+      expect.stringContaining("## Parent Basic Memory Context"),
+      "agent/subagents",
+    )
+  })
+
+  it("rolls back the handoff note when subagent spawn fails after preparation", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    const preparation = await engine.prepareSubagentSpawn({
+      parentSessionKey: "parent-session",
+      childSessionKey: "agent:test:subagent:child-rollback",
+    })
+
+    expect(preparation).toBeDefined()
+    await preparation?.rollback()
+
+    expect(mockClient.deleteNote).toHaveBeenCalledWith(
+      "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+    )
+  })
+
+  it("appends completion details to the handoff note when a child session completes", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await engine.prepareSubagentSpawn({
+      parentSessionKey: "parent-session",
+      childSessionKey: "agent:test:subagent:child-complete",
+    })
+
+    await engine.onSubagentEnded({
+      childSessionKey: "agent:test:subagent:child-complete",
+      reason: "completed",
+    })
+
+    expect(mockClient.editNote).toHaveBeenCalledWith(
+      "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+      "append",
+      expect.stringContaining("Reason: completed"),
+    )
+    expect(mockClient.editNote).toHaveBeenCalledWith(
+      "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+      "append",
+      expect.stringContaining(
+        "Durable conversation capture continues through the normal afterTurn path.",
+      ),
+    )
+  })
+
+  it("handles deleted, released, and swept child endings without errors", async () => {
+    const reasons = ["deleted", "released", "swept"] as const
+
+    for (const reason of reasons) {
+      const engine = new BasicMemoryContextEngine(
+        mockClient as unknown as BmClient,
+        makeConfig(),
+      )
+
+      await engine.prepareSubagentSpawn({
+        parentSessionKey: "parent-session",
+        childSessionKey: `agent:test:subagent:${reason}`,
+      })
+
+      await expect(
+        engine.onSubagentEnded({
+          childSessionKey: `agent:test:subagent:${reason}`,
+          reason,
+        }),
+      ).resolves.toBeUndefined()
+    }
+
+    expect(mockClient.editNote).toHaveBeenCalledTimes(3)
+  })
+
+  it("captures only the current turn after prePromptMessageCount", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await engine.afterTurn({
+      sessionId: "session-4",
+      sessionFile: "/tmp/session-4.jsonl",
+      prePromptMessageCount: 2,
+      messages: makeMessages([
+        { role: "user", content: "Old question" },
+        { role: "assistant", content: "Old answer" },
+        { role: "user", content: "Current question with enough detail" },
+        { role: "assistant", content: "Current answer with enough detail" },
+      ]),
+    })
+
+    expect(mockClient.indexConversation).toHaveBeenCalledWith(
+      "Current question with enough detail",
+      "Current answer with enough detail",
+    )
+  })
+
+  it("respects captureMinChars for afterTurn capture", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig({ captureMinChars: 50 }),
+    )
+
+    await engine.afterTurn({
+      sessionId: "session-5",
+      sessionFile: "/tmp/session-5.jsonl",
+      prePromptMessageCount: 0,
+      messages: makeMessages([
+        { role: "user", content: "short" },
+        { role: "assistant", content: "tiny" },
+      ]),
+    })
+
+    expect(mockClient.indexConversation).not.toHaveBeenCalled()
+  })
+
+  it("swallows capture failures in afterTurn", async () => {
+    mockClient.indexConversation.mockRejectedValue(new Error("BM down"))
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await expect(
+      engine.afterTurn({
+        sessionId: "session-6",
+        sessionFile: "/tmp/session-6.jsonl",
+        prePromptMessageCount: 0,
+        messages: makeMessages([
+          { role: "user", content: "Current question with enough detail" },
+          { role: "assistant", content: "Current answer with enough detail" },
+        ]),
+      }),
+    ).resolves.toBeUndefined()
+  })
+})

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/openclaw.plugin.json

@@ -1,6 +1,24 @@
 {
   "id": "openclaw-basic-memory",
   "kind": "memory",
+  "contracts": {
+    "tools": [
+      "build_context",
+      "delete_note",
+      "edit_note",
+      "list_memory_projects",
+      "list_workspaces",
+      "memory_get",
+      "memory_search",
+      "move_note",
+      "read_note",
+      "schema_diff",
+      "schema_infer",
+      "schema_validate",
+      "search_notes",
+      "write_note"
+    ]
+  },
   "skills": [
     "skills/memory-defrag",
     "skills/memory-ingest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.5.2"
   },
   "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:-v0.19.0}"
+BM_REF="${BM_REF:-v0.20.2}"
 
 # ── check for uv ──────────────────────────────────────────────────
 if ! command -v uv >/dev/null 2>&1; then

package/tools/build-context.ts

@@ -114,6 +114,11 @@ export function registerContextTool(
                 text: `Failed to build context for "${params.url}". Check logs for details.`,
               },
             ],
+            details: {
+              url: params.url,
+              depth,
+              error: "build_context_failed",
+            },
           }
         }
       },

package/tools/delete-note.ts

@@ -58,6 +58,10 @@ export function registerDeleteTool(
                 text: `Failed to delete "${params.identifier}". It may not exist.`,
               },
             ],
+            details: {
+              identifier: params.identifier,
+              error: "delete_note_failed",
+            },
           }
         }
       },

package/tools/edit-note.ts

@@ -109,6 +109,11 @@ export function registerEditTool(
                 text: `Failed to edit note "${params.identifier}". It may not exist.`,
               },
             ],
+            details: {
+              identifier: params.identifier,
+              operation: params.operation,
+              error: "edit_note_failed",
+            },
           }
         }
       },

package/tools/list-memory-projects.ts

@@ -85,6 +85,12 @@ export function registerProjectListTool(
                 text: "Failed to list Basic Memory projects. Is Basic Memory running? Check logs for details.",
               },
             ],
+            details: {
+              count: 0,
+              projects: [],
+              workspace: params.workspace ?? null,
+              error: "list_memory_projects_failed",
+            },
           }
         }
       },

package/tools/list-workspaces.ts

@@ -66,6 +66,11 @@ export function registerWorkspaceListTool(
                 text: "Failed to list workspaces. Is Basic Memory running? Check logs for details.",
               },
             ],
+            details: {
+              count: 0,
+              workspaces: [],
+              error: "list_workspaces_failed",
+            },
           }
         }
       },

package/tools/memory-provider.ts

@@ -235,6 +235,13 @@ export function registerMemoryProvider(
                 text: "No matches found across memory sources.",
               },
             ],
+            details: {
+              query: params.query,
+              sectionCount: 0,
+              hasMemoryFileMatches: false,
+              hasKnowledgeGraphMatches: false,
+              hasTaskMatches: false,
+            },
           }
         }
 
@@ -245,6 +252,13 @@ export function registerMemoryProvider(
               text: sections.join("\n\n"),
             },
           ],
+          details: {
+            query: params.query,
+            sectionCount: sections.length,
+            hasMemoryFileMatches: memoryMd.length > 0,
+            hasKnowledgeGraphMatches: bmResults.length > 0,
+            hasTaskMatches: taskResults.length > 0,
+          },
         }
       },
     },
@@ -293,6 +307,11 @@ export function registerMemoryProvider(
                 text: `# ${note.title}\n\n${note.content}`,
               },
             ],
+            details: {
+              title: note.title,
+              permalink: note.permalink,
+              file_path: note.file_path,
+            },
           }
         } catch (err) {
           log.error("memory_get failed", err)
@@ -303,6 +322,10 @@ export function registerMemoryProvider(
                 text: `Could not read "${params.path}". It may not exist in the knowledge graph.`,
               },
             ],
+            details: {
+              path: params.path,
+              error: "memory_get_failed",
+            },
           }
         }
       },

package/tools/move-note.ts

@@ -65,6 +65,11 @@ export function registerMoveTool(
                 text: `Failed to move "${params.identifier}". It may not exist.`,
               },
             ],
+            details: {
+              identifier: params.identifier,
+              newFolder: params.newFolder,
+              error: "move_note_failed",
+            },
           }
         }
       },

package/tools/read-note.ts

@@ -70,6 +70,11 @@ export function registerReadTool(
                 text: `Could not read note "${params.identifier}". It may not exist yet.`,
               },
             ],
+            details: {
+              identifier: params.identifier,
+              include_frontmatter: params.include_frontmatter === true,
+              error: "read_note_failed",
+            },
           }
         }
       },

package/tools/schema-diff.ts

@@ -46,6 +46,7 @@ export function registerSchemaDiffTool(
                   text: `No schema found for type "${params.noteType}". Use schema_infer to generate one.`,
                 },
               ],
+              details: result,
             }
           }
 
@@ -95,6 +96,10 @@ export function registerSchemaDiffTool(
                 text: "Schema diff failed. Check logs for details.",
               },
             ],
+            details: {
+              noteType: params.noteType,
+              error: "schema_diff_failed",
+            },
           }
         }
       },

package/tools/schema-infer.ts

@@ -94,6 +94,11 @@ export function registerSchemaInferTool(
                 text: "Schema inference failed. Check logs for details.",
               },
             ],
+            details: {
+              noteType: params.noteType,
+              threshold: params.threshold ?? 0.25,
+              error: "schema_infer_failed",
+            },
           }
         }
       },

package/tools/schema-validate.ts

@@ -53,6 +53,7 @@ export function registerSchemaValidateTool(
           if ("error" in result && typeof resultRecord.error === "string") {
             return {
               content: [{ type: "text" as const, text: resultRecord.error }],
+              details: result,
             }
           }
 
@@ -91,6 +92,11 @@ export function registerSchemaValidateTool(
                 text: "Schema validation failed. Check logs for details.",
               },
             ],
+            details: {
+              noteType: params.noteType ?? null,
+              identifier: params.identifier ?? null,
+              error: "schema_validate_failed",
+            },
           }
         }
       },

package/tools/search-notes.ts

@@ -83,6 +83,10 @@ export function registerSearchTool(
                   text: "No matching notes found in the knowledge graph.",
                 },
               ],
+              details: {
+                count: 0,
+                results: [],
+              },
             }
           }
 
@@ -121,6 +125,12 @@ export function registerSearchTool(
                 text: "Search failed. Is Basic Memory running? Check logs for details.",
               },
             ],
+            details: {
+              count: 0,
+              results: [],
+              query: params.query,
+              error: "search_notes_failed",
+            },
           }
         }
       },

package/tools/write-note.ts

@@ -83,6 +83,11 @@ export function registerWriteTool(
 
             return {
               content: [{ type: "text" as const, text: hint }],
+              details: {
+                title: params.title,
+                permalink: err.permalink,
+                error: "note_already_exists",
+              },
             }
           }
 
@@ -94,6 +99,11 @@ export function registerWriteTool(
                 text: "Failed to write note. Is Basic Memory running? Check logs for details.",
               },
             ],
+            details: {
+              title: params.title,
+              folder: params.folder,
+              error: "write_note_failed",
+            },
           }
         }
       },

package/types/openclaw.d.ts

@@ -1,24 +0,0 @@
-declare module "openclaw/plugin-sdk" {
-  export interface OpenClawPluginApi {
-    pluginConfig: unknown
-    logger: {
-      info: (msg: string) => void
-      warn: (msg: string) => void
-      error: (msg: string, ...args: unknown[]) => void
-      debug: (msg: string) => void
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
-    registerTool(tool: any, options: any): void
-    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
-    registerCommand(command: any): void
-    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
-    registerCli(handler: any, options?: any): void
-    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
-    registerService(service: any): void
-    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
-    on(event: string, handler: (...args: any[]) => any): void
-  }
-
-  // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
-  export function stringEnum(values: readonly string[]): any
-}