openbot 0.3.0 → 0.3.2

package/dist/plugins/ai-sdk/index.js

@@ -1,5 +1,4 @@
 import { aiSdkRuntime } from './runtime.js';
-import { AI_SDK_SYSTEM_PROMPT } from './system-prompt.js';
 /**
  * `ai-sdk` — generic LLM runtime plugin built on the Vercel AI SDK.
  *
@@ -11,7 +10,6 @@ export const aiSdkPlugin = {
     id: 'ai-sdk',
     name: 'AI SDK Runtime',
     description: 'Generic LLM runtime built on the Vercel AI SDK. Consumes tools contributed by other plugins.',
-    defaultInstructions: AI_SDK_SYSTEM_PROMPT,
     configSchema: {
         type: 'object',
         properties: {
@@ -28,7 +26,6 @@ export const aiSdkPlugin = {
             : 'openai/gpt-4o-mini';
         return aiSdkRuntime({
             model,
-            system: agentDetails.instructions || AI_SDK_SYSTEM_PROMPT,
             storage,
             toolDefinitions: tools,
         });

package/dist/plugins/ai-sdk/runtime.js

@@ -21,6 +21,78 @@ function resolveModel(modelString) {
 const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
     ? value
     : {};
+/** Per-message hard cap (in characters) on tool-result payloads we feed back
+ *  to the model. Prevents one huge tool output from eating the context window;
+ *  the original event remains intact in storage. */
+const TOOL_RESULT_MAX_CHARS = 8000;
+/** Sliding window: max number of messages we replay to the model on each
+ *  invocation. Older turns stay on disk but are not sent. Keeps both the
+ *  recent prompts and the prompt token budget bounded. */
+const MAX_WINDOW_MESSAGES = 80;
+const truncateToolPayload = (raw) => {
+    const serialized = typeof raw === 'string' ? raw : JSON.stringify(raw);
+    if (serialized.length <= TOOL_RESULT_MAX_CHARS)
+        return serialized;
+    const dropped = serialized.length - TOOL_RESULT_MAX_CHARS;
+    return `${serialized.slice(0, TOOL_RESULT_MAX_CHARS)}\n…[truncated ${dropped} chars]`;
+};
+/**
+ * Trim the message history to a sliding window while preserving tool-call
+ * integrity. Drops any leading orphan `tool` messages whose matching
+ * assistant call was sliced off, since most providers reject that.
+ */
+const buildMessageWindow = (messages) => {
+    if (messages.length <= MAX_WINDOW_MESSAGES)
+        return messages;
+    const tail = messages.slice(-MAX_WINDOW_MESSAGES);
+    const knownAssistantCallIds = new Set();
+    for (const m of tail) {
+        if (m.role === 'assistant' && m.toolCalls) {
+            for (const tc of m.toolCalls)
+                knownAssistantCallIds.add(tc.id);
+        }
+    }
+    return tail.filter((m) => m.role !== 'tool' || knownAssistantCallIds.has(m.toolCallId));
+};
+/**
+ * Self-healing pass: every assistant tool_call must have a matching tool
+ * result before the next user/assistant turn, or providers (OpenAI in
+ * particular) reject the request with "Tool result is missing for tool call".
+ *
+ * This can happen when a handler emits a `:result` event without `meta`
+ * (orphaning the call), the process restarts mid-run, or a tool handler
+ * crashes. Rather than refuse to continue, we inject synthetic tool messages
+ * with a clear error payload — the LLM can then explain the failure to the
+ * user and proceed.
+ */
+const repairOpenToolCalls = (messages) => {
+    const fulfilled = new Set();
+    for (const m of messages) {
+        if (m.role === 'tool')
+            fulfilled.add(m.toolCallId);
+    }
+    const repaired = [];
+    for (const m of messages) {
+        repaired.push(m);
+        if (m.role !== 'assistant' || !m.toolCalls)
+            continue;
+        for (const tc of m.toolCalls) {
+            if (fulfilled.has(tc.id))
+                continue;
+            repaired.push({
+                role: 'tool',
+                toolCallId: tc.id,
+                toolName: tc.function.name,
+                content: JSON.stringify({
+                    success: false,
+                    error: 'Tool result was lost (handler did not emit a matching :result event).',
+                }),
+            });
+            fulfilled.add(tc.id);
+        }
+    }
+    return repaired;
+};
 const readPersistedShortTermMessages = (state) => {
     const source = state.threadDetails?.state ?? state.channelDetails?.state;
     const record = asRecord(source);
@@ -44,15 +116,8 @@ const persistShortTermMessages = async (state, storage) => {
         state: { shortTermMessages },
     });
 };
-async function buildSystemPrompt(state, system, context, storage, contextEngine) {
-    const sections = [];
-    if (system && typeof system === 'string')
-        sections.push(system);
-    if (system && typeof system === 'function' && context)
-        sections.push(await system(context));
-    if (contextEngine)
-        sections.push(await contextEngine.buildContext(state, storage));
-    return sections.join('\n\n');
+async function buildSystemPrompt(state, storage, contextEngine) {
+    return contextEngine.buildContext(state, storage);
 }
 /**
  * Generic ai-sdk runtime plugin.
@@ -62,7 +127,7 @@ async function buildSystemPrompt(state, system, context, storage, contextEngine)
  * loader (merged from every tool plugin attached to the same agent).
  */
 export const aiSdkRuntime = (options) => (builder) => {
-    const { model: modelString = 'openai/gpt-4o-mini', system, storage, contextEngine = createDefaultContextEngine(), toolDefinitions = {}, } = options;
+    const { model: modelString = 'openai/gpt-4o-mini', storage, contextEngine = createDefaultContextEngine(), toolDefinitions = {}, } = options;
     let currentModelString = modelString;
     let model = resolveModel(currentModelString);
     const ensureShortTermMessages = (state) => {
@@ -107,8 +172,8 @@ export const aiSdkRuntime = (options) => (builder) => {
     };
     const runLLM = async function* (context, threadId) {
         ensureShortTermMessages(context.state);
-        const systemPrompt = await buildSystemPrompt(context.state, system, context, storage, contextEngine);
-        const coreMessages = mapToCoreMessages(context.state.shortTermMessages || []);
+        const systemPrompt = await buildSystemPrompt(context.state, storage, contextEngine);
+        const coreMessages = mapToCoreMessages(buildMessageWindow(repairOpenToolCalls(context.state.shortTermMessages || [])));
         try {
             const result = await generateText({
                 model,
@@ -246,7 +311,7 @@ export const aiSdkRuntime = (options) => (builder) => {
         ensureShortTermMessages(context.state);
         const toolName = event.type.replace(/^action:/, '').replace(/:result$/, '');
         const resultData = event.data;
-        const content = typeof resultData === 'string' ? resultData : JSON.stringify(resultData);
+        const content = truncateToolPayload(resultData);
         context.state.shortTermMessages = [
             ...(context.state.shortTermMessages ?? []),
             { role: 'tool', content, toolCallId, toolName },

package/dist/plugins/ai-sdk/system-prompt.js

@@ -1,3 +1,18 @@
-export const AI_SDK_SYSTEM_PROMPT = 'You are a helpful AI assistant on the OpenBot platform. ' +
-    'Use the tools available to you to help the user. ' +
-    'Be concise unless the user asks for depth.';
+export const AI_SDK_SYSTEM_PROMPT = [
+    'You are a helpful AI assistant on the OpenBot platform.',
+    'Use the tools available to you to help the user.',
+    'Be concise unless the user asks for depth.',
+    '',
+    '## Planning with todos',
+    'The current thread has a shared todo list (visible under "Shared todo plan" in context).',
+    'It is the single source of truth for multi-step work and is shared across every agent in the thread.',
+    '',
+    'When planning:',
+    '- For any task that needs more than one step, call `todo_write` ONCE with the full ordered plan, then stop. Do not call any other tool in the same turn.',
+    '- The platform dispatches assignees automatically and completes their todo when their run ends. You do NOT need to call `handoff` to start the plan or `todo_update` to finish items.',
+    '- Each item must be concrete and atomic (one verb, one outcome). Skip the list entirely for trivial single-step requests.',
+    '',
+    'When you are an assignee (you have an `in_progress` todo addressed to you):',
+    '- Just do the work and reply. The platform will mark your todo done and dispatch the next one.',
+    '- If you genuinely cannot complete it, call `todo_update(id, status: "cancelled")` with a brief reason in your reply.',
+].join('\n');

package/dist/plugins/delegation/index.js

@@ -1,21 +1,14 @@
 import z from 'zod';
-const delegationToolDefinitions = {
+const handoffToolDefinitions = {
     handoff: {
-        description: 'Transfer control to another agent. The target agent continues the task and you do not wait for a tool result.',
+        description: 'Transfer control to another agent. The target agent continues the task in this thread.',
         inputSchema: z.object({
             agentId: z.string().describe('The ID of the target agent.'),
             content: z.string().describe('The message or task to hand off.'),
         }),
     },
-    delegate: {
-        description: 'Delegate a subtask to another agent and wait for its result so you can continue.',
-        inputSchema: z.object({
-            agentId: z.string().describe('The ID of the target agent.'),
-            content: z.string().describe('The subtask you want the target agent to execute.'),
-        }),
-    },
 };
-const delegationPluginRuntime = () => (builder) => {
+const handoffPluginRuntime = () => (builder) => {
     builder.on('action:handoff', async function* (event, context) {
         const { agentId, content } = event.data;
         yield {
@@ -36,44 +29,12 @@ const delegationPluginRuntime = () => (builder) => {
             };
         }
     });
-    builder.on('action:delegate', async function* (event, context) {
-        const { agentId, content } = event.data;
-        const widgetId = event.meta?.toolCallId
-            ? `delegate_${event.meta.toolCallId}`
-            : `delegate_${Date.now()}`;
-        yield {
-            type: 'client:ui:widget',
-            data: {
-                kind: 'message',
-                widgetId,
-                title: `Delegation started: ${agentId}`,
-                body: `Running delegated task in background.\n\n${content}`,
-                state: 'open',
-                metadata: {
-                    type: 'delegation:status',
-                    phase: 'started',
-                    delegatedAgentId: agentId,
-                },
-            },
-            meta: { ...(event.meta || {}), agentId: context.state.agentId },
-        };
-        yield {
-            type: 'delegation:request',
-            data: { agentId, content },
-            meta: {
-                ...(event.meta || {}),
-                parentAgentId: context.state.agentId,
-                delegationWidgetId: widgetId,
-                agentId: context.state.agentId,
-            },
-        };
-    });
 };
 export const delegationPlugin = {
     id: 'delegation',
-    name: 'Delegation',
-    description: 'Hand off or delegate sub-tasks to other agents on the bus.',
-    toolDefinitions: delegationToolDefinitions,
-    factory: () => delegationPluginRuntime(),
+    name: 'Handoff',
+    description: 'Hand off tasks to other agents on the bus.',
+    toolDefinitions: handoffToolDefinitions,
+    factory: () => handoffPluginRuntime(),
 };
 export default delegationPlugin;

package/dist/plugins/memory/index.js

@@ -0,0 +1,71 @@
+import z from 'zod';
+/**
+ * `memory` — exposes the global memory store as agent tools.
+ *
+ * The actual handlers live in `bus/services.ts` because memory is platform
+ * infrastructure (shared across every agent on the bus); this plugin only
+ * contributes the tool definitions so a runtime plugin (e.g. `ai-sdk`) can
+ * surface them to the LLM.
+ *
+ * Scopes
+ * ------
+ * - `global`  (default) — visible to every agent and channel.
+ * - `agent`   — visible only to the agent that wrote it.
+ * - `channel` — visible only inside the active channel.
+ */
+const memoryToolDefinitions = {
+    remember: {
+        description: 'Persist a durable fact, preference, or note to long-term memory so it can be recalled in future turns and runs. Use for stable information (user preferences, project conventions, contact details, decisions); avoid using it for transient chatter or per-step scratch state — that belongs in thread state. Keep entries short and self-contained.',
+        inputSchema: z.object({
+            content: z
+                .string()
+                .min(1)
+                .describe('The fact to remember, written so it makes sense out of context (e.g. "User prefers TypeScript over JavaScript.").'),
+            scope: z
+                .enum(['global', 'agent', 'channel'])
+                .optional()
+                .describe('Visibility: `global` (default, all agents everywhere), `agent` (only this agent), `channel` (only this channel).'),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe('Optional tags for filtering with `recall`.'),
+        }),
+    },
+    recall: {
+        description: 'Search long-term memory for facts you previously stored with `remember`. Returns up to `limit` matching records with their ids so you can `forget` stale ones.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('Case-insensitive substring filter against memory content.'),
+            tag: z.string().optional().describe('Only return memories that include this tag.'),
+            scope: z
+                .enum(['global', 'agent', 'channel', 'all'])
+                .optional()
+                .describe('Restrict the search to a single scope. Default `all` returns global + this agent + this channel.'),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .optional()
+                .describe('Maximum records to return (default 20, max 50).'),
+        }),
+    },
+    forget: {
+        description: 'Delete a memory by id. Use after the user asks to forget something or when a previously remembered fact is now wrong. Get ids from `recall`.',
+        inputSchema: z.object({
+            id: z.string().describe('The memory record id (returned by `recall`/`remember`).'),
+        }),
+    },
+};
+export const memoryPlugin = {
+    id: 'memory',
+    name: 'Memory',
+    description: 'Global long-term memory: remember/recall/forget facts across runs and agents.',
+    toolDefinitions: memoryToolDefinitions,
+    factory: () => () => {
+        // Handlers live in bus/services.ts; this plugin only contributes tool definitions.
+    },
+};
+export default memoryPlugin;

package/dist/plugins/storage-tools/index.js

@@ -42,20 +42,11 @@ const storageToolDefinitions = {
             .refine((value) => value.state !== undefined || value.spec !== undefined || value.cwd !== undefined, { message: 'Provide at least one of state, spec, or cwd.' }),
     },
     patch_thread_details: {
-        description: 'Patch current thread details (state and/or spec).',
-        inputSchema: z
-            .object({
+        description: 'Patch current thread details (state).',
+        inputSchema: z.object({
             state: z
                 .record(z.string(), z.unknown())
-                .optional()
                 .describe('JSON state object for the thread. Use for structured data like `todos` or progress.'),
-            spec: z
-                .string()
-                .optional()
-                .describe('Markdown content for the thread specification (SPEC.md). Use for plans and goals.'),
-        })
-            .refine((value) => value.state !== undefined || value.spec !== undefined, {
-            message: 'Provide at least one of state or spec.',
         }),
     },
     create_variable: {

package/dist/plugins/todo/index.js

@@ -0,0 +1,54 @@
+import z from 'zod';
+/**
+ * `todo` — shared, per-thread task list for autonomous multi-agent flows.
+ *
+ * Todos live in `threadDetails.state.todos` and are owned by the system
+ * (handlers in `bus/services.ts`). Any agent in the thread can read the
+ * list via context, and propose mutations through these tools. Each item
+ * may carry an `assignee` agent id; combine with `handoff` to drive an
+ * autonomous, multi-step plan across agents.
+ *
+ * Keep the surface minimal: two tools (replace-all, patch-one) cover plan
+ * authoring, status transitions, and reassignment.
+ */
+const todoStatus = z.enum(['pending', 'in_progress', 'done', 'cancelled']);
+const todoToolDefinitions = {
+    todo_write: {
+        description: 'Author or rewrite the shared todo plan for the current thread. Pass the full ordered list — missing items are removed. Use at the start of multi-step work, or whenever the plan changes shape. For status flips, prefer `todo_update`.',
+        inputSchema: z.object({
+            todos: z
+                .array(z.object({
+                id: z
+                    .string()
+                    .optional()
+                    .describe('Stable id. Reuse existing ids to preserve history; omit to create.'),
+                content: z.string().min(1).describe('What needs to be done. One concrete step.'),
+                status: todoStatus.optional().describe('Defaults to `pending`.'),
+                assignee: z
+                    .string()
+                    .optional()
+                    .describe('Agent id responsible for this step. Pair with `handoff` to delegate.'),
+            }))
+                .describe('The complete, ordered plan.'),
+        }),
+    },
+    todo_update: {
+        description: 'Patch a single todo by id. Use to mark progress (`in_progress`, `done`, `cancelled`), rephrase, or reassign without rewriting the whole list.',
+        inputSchema: z.object({
+            id: z.string().describe('Todo id from `todo_write` or the rendered list.'),
+            status: todoStatus.optional(),
+            content: z.string().min(1).optional(),
+            assignee: z.string().optional().describe('Use empty string to clear.'),
+        }),
+    },
+};
+export const todoPlugin = {
+    id: 'todo',
+    name: 'Todo',
+    description: 'Shared per-thread task list for coordinating multi-step, multi-agent work.',
+    toolDefinitions: todoToolDefinitions,
+    factory: () => () => {
+        // Handlers live in bus/services.ts; this plugin only contributes tool definitions.
+    },
+};
+export default todoPlugin;

package/dist/plugins/workflow/index.js

@@ -0,0 +1,65 @@
+import z from 'zod';
+import { setWorkflowPlan, updateWorkflowTodo } from '../../workflow/service.js';
+const workflowToolDefinitions = {
+    workflow_set_plan: {
+        description: 'Define or replace the multi-agent plan for this thread.',
+        inputSchema: z.object({
+            title: z.string().optional().describe('Optional title for the plan.'),
+            todos: z.array(z.object({
+                id: z.string().optional().describe('Optional stable id.'),
+                text: z.string().describe('What needs to be done.'),
+            })).min(1).describe('Ordered steps.'),
+        }),
+    },
+    workflow_update_todo: {
+        description: 'Update a step in the plan with progress or results.',
+        inputSchema: z.object({
+            todoId: z.string().describe('The id of the todo to update.'),
+            status: z.enum(['pending', 'done', 'failed']).optional().describe('New status.'),
+            summary: z.string().optional().describe('Concise result or note about this step.'),
+        }),
+    },
+};
+const workflowPluginRuntime = () => (builder) => {
+    builder.on('action:workflow_set_plan', async function* (event, context) {
+        const { threadId, channelId } = context.state;
+        if (!threadId) {
+            yield { type: 'action:workflow_set_plan:result', data: { success: false, error: 'No active thread.' }, meta: event.meta };
+            return;
+        }
+        try {
+            const workflow = await setWorkflowPlan({ channelId, threadId, plan: event.data });
+            yield { type: 'action:workflow_set_plan:result', data: { success: true, workflowId: workflow.id }, meta: event.meta };
+            yield {
+                type: 'agent:output',
+                data: { content: `Plan updated: **${workflow.title || workflow.id}** (${workflow.todos.length} steps).` },
+                meta: { ...(event.meta || {}), agentId: context.state.agentId, threadId },
+            };
+        }
+        catch (error) {
+            yield { type: 'action:workflow_set_plan:result', data: { success: false, error: String(error) }, meta: event.meta };
+        }
+    });
+    builder.on('action:workflow_update_todo', async function* (event, context) {
+        const { threadId, channelId } = context.state;
+        if (!threadId) {
+            yield { type: 'action:workflow_update_todo:result', data: { success: false, error: 'No active thread.' }, meta: event.meta };
+            return;
+        }
+        try {
+            const workflow = await updateWorkflowTodo({ channelId, threadId, update: event.data });
+            yield { type: 'action:workflow_update_todo:result', data: { success: true, todoId: event.data.todoId }, meta: event.meta };
+        }
+        catch (error) {
+            yield { type: 'action:workflow_update_todo:result', data: { success: false, error: String(error) }, meta: event.meta };
+        }
+    });
+};
+export const workflowPlugin = {
+    id: 'workflow',
+    name: 'Workflow',
+    description: 'Simple thread-scoped planning for multi-agent coordination.',
+    toolDefinitions: workflowToolDefinitions,
+    factory: () => workflowPluginRuntime(),
+};
+export default workflowPlugin;

package/dist/registry/plugins.js

@@ -8,6 +8,8 @@ import { delegationPlugin } from '../plugins/delegation/index.js';
 import { storageToolsPlugin } from '../plugins/storage-tools/index.js';
 import { uiPlugin } from '../plugins/ui/index.js';
 import { approvalPlugin } from '../plugins/approval/index.js';
+import { memoryPlugin } from '../plugins/memory/index.js';
+import { todoPlugin } from '../plugins/todo/index.js';
 import { DEFAULT_PLUGINS_DIR, DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
 let pluginsDir = null;
 const loadedPlugins = new Set();
@@ -20,6 +22,8 @@ const BUILT_IN = {
     [storageToolsPlugin.id]: storageToolsPlugin,
     [uiPlugin.id]: uiPlugin,
     [approvalPlugin.id]: approvalPlugin,
+    [memoryPlugin.id]: memoryPlugin,
+    [todoPlugin.id]: todoPlugin,
 };
 /** Normalize a dynamically imported plugin module. Supports `plugin`, `default`. */
 export function parsePluginModule(module) {
@@ -33,14 +37,12 @@ export function parsePluginModule(module) {
     const name = typeof raw.name === 'string' ? raw.name : '';
     const description = typeof raw.description === 'string' ? raw.description : '';
     const image = typeof raw.image === 'string' ? raw.image : undefined;
-    const defaultInstructions = typeof raw.defaultInstructions === 'string' ? raw.defaultInstructions : undefined;
     const configSchema = raw.configSchema;
     const toolDefinitions = raw.toolDefinitions;
     return {
         name,
         description,
         image,
-        defaultInstructions,
         configSchema,
         toolDefinitions,
         factory: factory,

package/dist/services/memory.js

@@ -0,0 +1,152 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+const getMemoryDir = () => {
+    const config = loadConfig();
+    return path.join(resolvePath(config.baseDir || DEFAULT_BASE_DIR), 'memory');
+};
+const getLogPath = () => path.join(getMemoryDir(), 'log.jsonl');
+const ensureDir = async () => {
+    await fs.mkdir(getMemoryDir(), { recursive: true });
+};
+const readLog = async () => {
+    try {
+        const raw = await fs.readFile(getLogPath(), 'utf-8');
+        return raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => !!e);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+};
+const replay = (entries) => {
+    const out = new Map();
+    for (const entry of entries) {
+        if (entry.op === 'add') {
+            out.set(entry.record.id, entry.record);
+        }
+        else if (entry.op === 'delete') {
+            out.delete(entry.id);
+        }
+        else if (entry.op === 'update') {
+            const existing = out.get(entry.id);
+            if (!existing)
+                continue;
+            out.set(entry.id, {
+                ...existing,
+                ...entry.patch,
+                id: existing.id,
+                updatedAt: entry.at,
+            });
+        }
+    }
+    return out;
+};
+const appendEntry = async (entry) => {
+    await ensureDir();
+    await fs.appendFile(getLogPath(), `${JSON.stringify(entry)}\n`, 'utf-8');
+};
+const matchesQuery = (record, query, tag) => {
+    if (tag) {
+        if (!record.tags || !record.tags.includes(tag))
+            return false;
+    }
+    if (query) {
+        const q = query.toLowerCase();
+        if (!record.content.toLowerCase().includes(q))
+            return false;
+    }
+    return true;
+};
+export const memoryService = {
+    appendMemory: async (args) => {
+        const now = new Date().toISOString();
+        const record = {
+            id: crypto.randomUUID(),
+            scope: args.scope,
+            content: args.content,
+            tags: args.tags?.length ? args.tags : undefined,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await appendEntry({ op: 'add', record });
+        return record;
+    },
+    updateMemory: async (args) => {
+        const entries = await readLog();
+        const map = replay(entries);
+        if (!map.has(args.id))
+            return false;
+        const at = new Date().toISOString();
+        const patch = {};
+        if (args.content !== undefined)
+            patch.content = args.content;
+        if (args.tags !== undefined)
+            patch.tags = args.tags.length ? args.tags : undefined;
+        if (Object.keys(patch).length === 0)
+            return true;
+        await appendEntry({ op: 'update', id: args.id, patch, at });
+        return true;
+    },
+    deleteMemory: async (args) => {
+        const entries = await readLog();
+        const map = replay(entries);
+        if (!map.has(args.id))
+            return false;
+        await appendEntry({ op: 'delete', id: args.id, at: new Date().toISOString() });
+        return true;
+    },
+    listMemories: async (args = {}) => {
+        const entries = await readLog();
+        const map = replay(entries);
+        const limit = Math.min(Math.max(args.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+        const scopeSet = (() => {
+            if (args.scope)
+                return new Set([args.scope]);
+            if (args.scopes && args.scopes.length > 0)
+                return new Set(args.scopes);
+            return null;
+        })();
+        const filtered = [];
+        for (const record of map.values()) {
+            if (scopeSet && !scopeSet.has(record.scope))
+                continue;
+            if (!matchesQuery(record, args.query, args.tag))
+                continue;
+            filtered.push(record);
+        }
+        filtered.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+        return filtered.slice(0, limit);
+    },
+    /**
+     * Compact the log into a single `add` per surviving record. Cheap to call
+     * occasionally; not required for correctness.
+     */
+    compact: async () => {
+        const entries = await readLog();
+        const map = replay(entries);
+        const surviving = Array.from(map.values());
+        await ensureDir();
+        const tmp = `${getLogPath()}.tmp`;
+        const body = surviving.map((record) => JSON.stringify({ op: 'add', record })).join('\n');
+        await fs.writeFile(tmp, body ? `${body}\n` : '', 'utf-8');
+        await fs.rename(tmp, getLogPath());
+        return surviving.length;
+    },
+};