botholomew 0.16.3 → 0.17.0

package/src/init/index.ts

@@ -4,9 +4,7 @@ import { loadConfig } from "../config/loader.ts";
 import {
   CONFIG_DIR,
   CONFIG_FILENAME,
-  CONTEXT_DIR,
   getConfigPath,
-  getDbPath,
   getMcpxDir,
   getPromptsDir,
   getSchedulesDir,
@@ -22,11 +20,10 @@ import {
   SCHEDULES_DIR,
   TASKS_DIR,
 } from "../constants.ts";
-import { writeCapabilitiesFile } from "../context/capabilities.ts";
-import { getConnection } from "../db/connection.ts";
-import { migrate } from "../db/schema.ts";
 import { assertCompatibleFilesystem } from "../fs/compat.ts";
 import { createMcpxClient } from "../mcpx/client.ts";
+import { openMembot } from "../mem/client.ts";
+import { writeCapabilitiesFile } from "../prompts/capabilities.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import { logger } from "../utils/logger.ts";
 import {
@@ -62,7 +59,6 @@ export async function initProject(
   await mkdir(getPromptsDir(projectDir), { recursive: true });
   await mkdir(getSkillsDir(projectDir), { recursive: true });
   await mkdir(getMcpxDir(projectDir), { recursive: true });
-  await mkdir(join(projectDir, CONTEXT_DIR), { recursive: true });
   await mkdir(getTasksDir(projectDir), { recursive: true });
   await mkdir(getTasksLockDir(projectDir), { recursive: true });
   await mkdir(getSchedulesDir(projectDir), { recursive: true });
@@ -92,11 +88,12 @@ export async function initProject(
     `${JSON.stringify(DEFAULT_MCPX_SERVERS, null, 2)}\n`,
   );
 
-  // Initialize the index database (search index sidecar; rebuildable).
-  const dbPath = getDbPath(projectDir);
-  const conn = await getConnection(dbPath);
-  await migrate(conn);
-  conn.close();
+  // Initialize the membot knowledge store. Opening + closing the client
+  // triggers membot's first-run migration so the project ships with a
+  // ready-to-use index.duckdb.
+  const mem = openMembot(projectDir);
+  await mem.connect();
+  await mem.close();
 
   // Populate capabilities.md with the real tool inventory.
   registerAllTools();
@@ -111,20 +108,20 @@ export async function initProject(
   logger.success("Initialized Botholomew project");
   logger.dim(`  Project root: ${projectDir}`);
   logger.dim(`  Config:       ${CONFIG_DIR}/${CONFIG_FILENAME}`);
-  logger.dim(`  Index DB:     ${dbPath}`);
+  logger.dim(`  Knowledge:    index.duckdb (managed by membot)`);
   logger.dim("");
   logger.dim("Layout:");
   logger.dim(`  ${CONFIG_DIR}/         settings`);
   logger.dim(
     `  prompts/         goals, beliefs, capabilities (and any you add)`,
   );
-  logger.dim(`  ${CONTEXT_DIR}/        agent-writable knowledge tree`);
+  logger.dim(`  index.duckdb     agent's knowledge store (membot)`);
   logger.dim(`  ${TASKS_DIR}/          one markdown file per task`);
   logger.dim(`    ${LOCKS_SUBDIR}/        worker claim lockfiles`);
   logger.dim(`  ${SCHEDULES_DIR}/      one markdown file per schedule`);
   logger.dim(`  threads/         one CSV per conversation, by UTC date`);
   logger.dim(`  workers/         one JSON pidfile per worker (heartbeats)`);
-  logger.dim(`  skills/, mcpx/, models/, logs/`);
+  logger.dim(`  skills/, mcpx/, logs/`);
   logger.dim("");
   logger.dim("Next steps:");
   logger.dim(

package/src/mem/client.ts

@@ -0,0 +1,17 @@
+import { MembotClient } from "membot";
+
+/**
+ * Open a per-project membot client. Each Botholomew project gets its own
+ * membot data dir (`<projectDir>/config.json` + `<projectDir>/index.duckdb`)
+ * so projects don't share knowledge. The caller is responsible for `close()`
+ * on shutdown.
+ *
+ * Membot's `configFlag` doubles as its data-dir flag (see
+ * `membot/src/config/loader.ts::resolveDataDir`): an explicit value wins over
+ * `$MEMBOT_HOME` and the `~/.membot` default. We pass the project directory
+ * unconditionally so a stray `MEMBOT_HOME` in the user's environment cannot
+ * redirect Botholomew at a different store.
+ */
+export function openMembot(projectDir: string): MembotClient {
+  return new MembotClient({ configFlag: projectDir });
+}

package/src/{context → prompts}/capabilities.ts

@@ -27,8 +27,9 @@ type AnyTool = ToolDefinition<any, any>;
 const GROUP_ORDER = [
   "task",
   "schedule",
-  "context",
-  "search",
+  "membot",
+  "prompt",
+  "skill",
   "thread",
   "mcp",
   "worker",
@@ -38,8 +39,9 @@ const GROUP_ORDER = [
 const GROUP_HEADINGS: Record<string, string> = {
   task: "Task management",
   schedule: "Schedules",
-  context: "Virtual filesystem & self-reflection",
-  search: "Search",
+  membot: "Knowledge store (membot)",
+  prompt: "Prompts",
+  skill: "Skills",
   thread: "Threads",
   mcp: "MCPX meta-tools",
   worker: "Workers",
@@ -367,9 +369,11 @@ function renderFallback(inv: RawInventory, now: Date): string {
     task: "create, list, view, update, complete, fail, and wait on tasks in the agent's work queue",
     schedule:
       "create and list recurring schedules that automatically generate tasks",
-    context:
-      "read, write, edit, move, copy, delete, and navigate files in the agent's context/ tree; update beliefs and goals; read large tool results",
-    search: "keyword, semantic, and regexp search over files in context/",
+    membot:
+      "add, read, write, edit, move, copy, delete, and search content in the agent's knowledge store; track every version and refresh from URL sources",
+    prompt:
+      "list, read, create, edit, and delete the project's prompt files (goals, beliefs, capabilities, plus any agent-authored ones)",
+    skill: "list, read, write, edit, delete, and search slash-command skills",
     thread: "list and view past conversation threads and tool interactions",
     mcp: "search, list, inspect, and execute tools exposed by configured MCPX servers",
     worker: "spawn background workers to run tasks asynchronously",

package/src/schedules/store.ts

@@ -2,7 +2,6 @@ import { readdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import matter from "gray-matter";
 import { getSchedulesDir, getSchedulesLockDir } from "../constants.ts";
-import { uuidv7 } from "../db/uuid.ts";
 import {
   acquireLock,
   atomicWrite,
@@ -13,6 +12,7 @@ import {
   releaseLock,
 } from "../fs/atomic.ts";
 import { logger } from "../utils/logger.ts";
+import { uuidv7 } from "../utils/uuid.ts";
 import {
   type Schedule,
   type ScheduleFrontmatter,

package/src/tasks/store.ts

@@ -2,7 +2,6 @@ import { readdir, stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import matter from "gray-matter";
 import { getTasksDir, getTasksLockDir } from "../constants.ts";
-import { uuidv7 } from "../db/uuid.ts";
 import {
   acquireLock,
   atomicWrite,
@@ -13,6 +12,7 @@ import {
   releaseLock,
 } from "../fs/atomic.ts";
 import { logger } from "../utils/logger.ts";
+import { uuidv7 } from "../utils/uuid.ts";
 import {
   type Task,
   type TaskFrontmatter,

package/src/threads/store.ts

@@ -1,8 +1,8 @@
 import { appendFile, readdir, readFile, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { getThreadsDir } from "../constants.ts";
-import { uuidv7 } from "../db/uuid.ts";
 import { atomicWrite } from "../fs/atomic.ts";
+import { uuidv7 } from "../utils/uuid.ts";
 import { DATE_DIR_RE, dateForId } from "../utils/v7-date.ts";
 
 /**

package/src/tools/capabilities/refresh.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { writeCapabilitiesFile } from "../../context/capabilities.ts";
+import { writeCapabilitiesFile } from "../../prompts/capabilities.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({

package/src/tools/membot/adapter.ts

@@ -0,0 +1,111 @@
+import type { Operation } from "membot";
+import { composeDescription, isHelpfulError } from "membot";
+import { z } from "zod";
+import type { ToolContext, ToolDefinition } from "../tool.ts";
+
+/**
+ * Common output envelope for every membot-backed tool. The membot operation's
+ * own result is parked under `data` so the LLM gets a single, predictable
+ * shape across all 14 verbs. Errors flatten the HelpfulError's `kind`/`hint`
+ * into `error_type` / `next_action_hint`, which is the recovery cue Botholomew
+ * agents already know from the rest of the tool surface.
+ */
+export const membotOutputSchema = z.object({
+  is_error: z.boolean(),
+  data: z.unknown().optional(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export type MembotOutput = z.infer<typeof membotOutputSchema>;
+
+type MembotMethodName =
+  | "add"
+  | "list"
+  | "tree"
+  | "read"
+  | "search"
+  | "info"
+  | "stats"
+  | "versions"
+  | "diff"
+  | "write"
+  | "move"
+  | "remove"
+  | "refresh"
+  | "prune";
+
+/**
+ * Map an Operation's exposed name (`membot_add`, `membot_delete`, …) to the
+ * `MembotClient` method that actually runs it. The two diverge in a couple
+ * of spots — `membot_delete` calls `client.remove`, `membot_move` calls
+ * `client.move` — so we keep the routing explicit rather than guessing.
+ */
+const METHOD_BY_OP_NAME: Record<string, MembotMethodName> = {
+  membot_add: "add",
+  membot_list: "list",
+  membot_tree: "tree",
+  membot_read: "read",
+  membot_search: "search",
+  membot_info: "info",
+  membot_stats: "stats",
+  membot_versions: "versions",
+  membot_diff: "diff",
+  membot_write: "write",
+  membot_move: "move",
+  membot_delete: "remove",
+  membot_refresh: "refresh",
+  membot_prune: "prune",
+};
+
+/**
+ * Adapt one membot {@link Operation} into a Botholomew {@link ToolDefinition}.
+ * The input schema passes through unchanged so the LLM sees membot's
+ * upstream prose/aliases verbatim. Success calls return `{ is_error: false,
+ * data: <op output> }`; HelpfulErrors return the flattened error envelope.
+ * Unknown errors are wrapped as `internal_error` so a thrown handler never
+ * crashes the agent loop.
+ */
+export function adaptOperation(
+  // biome-ignore lint/suspicious/noExplicitAny: Operation generic is heterogeneous across 14 verbs
+  op: Operation<any, any>,
+): ToolDefinition<z.ZodObject<z.ZodRawShape>, typeof membotOutputSchema> {
+  const methodName = METHOD_BY_OP_NAME[op.name];
+  if (!methodName) {
+    throw new Error(
+      `adaptOperation: no MembotClient method registered for op '${op.name}'. ` +
+        `Add it to METHOD_BY_OP_NAME in src/tools/membot/adapter.ts.`,
+    );
+  }
+  return {
+    name: op.name,
+    description: composeDescription(op),
+    group: "membot",
+    inputSchema: op.inputSchema as z.ZodObject<z.ZodRawShape>,
+    outputSchema: membotOutputSchema,
+    execute: async (input, ctx: ToolContext) => {
+      try {
+        const method = ctx.mem[methodName] as (i: unknown) => Promise<unknown>;
+        const data = await method.call(ctx.mem, input);
+        return { is_error: false, data };
+      } catch (err) {
+        if (isHelpfulError(err)) {
+          return {
+            is_error: true,
+            error_type: err.kind,
+            message: err.message,
+            next_action_hint: err.hint,
+          };
+        }
+        return {
+          is_error: true,
+          error_type: "internal_error",
+          message: err instanceof Error ? err.message : String(err),
+          next_action_hint:
+            "Check the project's membot store (run `botholomew context stats`) and try again. If this persists, file a bug.",
+        };
+      }
+    },
+  };
+}

package/src/tools/membot/copy.ts

@@ -0,0 +1,59 @@
+import { isHelpfulError } from "membot";
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  from_logical_path: z.string().describe("Source path"),
+  to_logical_path: z.string().describe("Destination path"),
+  change_note: z.string().optional(),
+});
+
+const outputSchema = z.object({
+  is_error: z.boolean(),
+  from_logical_path: z.string().optional(),
+  to_logical_path: z.string().optional(),
+  new_version_id: z.string().optional(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const membotCopyTool = {
+  name: "membot_copy",
+  description:
+    "[[ bash equivalent command: cp ]] Duplicate a file's current content under a new logical_path. The source is left untouched; the destination becomes a new inline-source version. Use membot_move to rename instead (the source is tombstoned in that case).",
+  group: "membot",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    try {
+      const src = await ctx.mem.read({ logical_path: input.from_logical_path });
+      const written = await ctx.mem.write({
+        logical_path: input.to_logical_path,
+        content: src.content ?? "",
+        change_note:
+          input.change_note ?? `copied from ${input.from_logical_path}`,
+      });
+      return {
+        is_error: false,
+        from_logical_path: input.from_logical_path,
+        to_logical_path: written.logical_path,
+        new_version_id: written.version_id,
+      };
+    } catch (err) {
+      if (isHelpfulError(err)) {
+        return {
+          is_error: true,
+          error_type: err.kind,
+          message: err.message,
+          next_action_hint: err.hint,
+        };
+      }
+      return {
+        is_error: true,
+        error_type: "internal_error",
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/membot/count_lines.ts

@@ -0,0 +1,53 @@
+import { isHelpfulError } from "membot";
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  logical_path: z.string().describe("Logical path of the file to count."),
+});
+
+const outputSchema = z.object({
+  is_error: z.boolean(),
+  logical_path: z.string().optional(),
+  line_count: z.number().optional(),
+  size_bytes: z.number().nullable().optional(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const membotCountLinesTool = {
+  name: "membot_count_lines",
+  description:
+    "[[ bash equivalent command: wc -l ]] Count lines in a stored file's markdown surrogate. Useful before a large membot_read or membot_edit to decide whether to fetch the whole body or page through it with `offset`/`limit`.",
+  group: "membot",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    try {
+      const result = await ctx.mem.read({ logical_path: input.logical_path });
+      const content = result.content ?? "";
+      const lineCount = content === "" ? 0 : content.split("\n").length;
+      return {
+        is_error: false,
+        logical_path: result.logical_path,
+        line_count: lineCount,
+        size_bytes: result.size_bytes,
+      };
+    } catch (err) {
+      if (isHelpfulError(err)) {
+        return {
+          is_error: true,
+          error_type: err.kind,
+          message: err.message,
+          next_action_hint: err.hint,
+        };
+      }
+      return {
+        is_error: true,
+        error_type: "internal_error",
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/membot/edit.ts

@@ -0,0 +1,72 @@
+import { isHelpfulError } from "membot";
+import { z } from "zod";
+import { applyLinePatches, LinePatchSchema } from "../../fs/patches.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  logical_path: z
+    .string()
+    .describe("Logical path of the file to edit (e.g. 'notes/foo.md')."),
+  patches: z
+    .array(LinePatchSchema)
+    .min(1)
+    .describe(
+      "Git-hunk-style edits applied bottom-up. `end_line: 0` inserts; empty `content` deletes.",
+    ),
+  change_note: z
+    .string()
+    .optional()
+    .describe("Free-text note attached to the new version."),
+});
+
+const outputSchema = z.object({
+  is_error: z.boolean(),
+  logical_path: z.string().optional(),
+  version_id: z.string().optional(),
+  size_bytes: z.number().optional(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const membotEditTool = {
+  name: "membot_edit",
+  description:
+    "[[ bash equivalent command: patch ]] Apply line-range edits to a stored file: reads the current version, applies bottom-up patches, and writes the result back as a new version. Prefer this over membot_write when you only need to change part of a file — the diff is small and the change_note travels with the new version. To replace the whole body, use membot_write. To delete the file, use membot_delete.",
+  group: "membot",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    try {
+      const current = await ctx.mem.read({ logical_path: input.logical_path });
+      const next = applyLinePatches(current.content ?? "", input.patches);
+      const result = await ctx.mem.write({
+        logical_path: input.logical_path,
+        content: next,
+        change_note: input.change_note,
+      });
+      return {
+        is_error: false,
+        logical_path: result.logical_path,
+        version_id: result.version_id,
+        size_bytes: result.size_bytes,
+      };
+    } catch (err) {
+      if (isHelpfulError(err)) {
+        return {
+          is_error: true,
+          error_type: err.kind,
+          message: err.message,
+          next_action_hint: err.hint,
+        };
+      }
+      return {
+        is_error: true,
+        error_type: "internal_error",
+        message: err instanceof Error ? err.message : String(err),
+        next_action_hint:
+          "Re-read the file with membot_read to confirm current line numbers, then retry.",
+      };
+    }
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/membot/exists.ts

@@ -0,0 +1,54 @@
+import { isHelpfulError } from "membot";
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  logical_path: z.string().describe("Logical path to check."),
+});
+
+const outputSchema = z.object({
+  is_error: z.boolean(),
+  exists: z.boolean().optional(),
+  logical_path: z.string().optional(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+});
+
+export const membotExistsTool = {
+  name: "membot_exists",
+  description:
+    "[[ bash equivalent command: test -e ]] Check whether a logical_path has a current (non-tombstoned) version in the store. Returns `{ exists: true|false }` — never throws on absence. Use before membot_write when you want to avoid clobbering, or to disambiguate a not_found from a real error.",
+  group: "membot",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    try {
+      await ctx.mem.info({ logical_path: input.logical_path });
+      return {
+        is_error: false,
+        exists: true,
+        logical_path: input.logical_path,
+      };
+    } catch (err) {
+      if (isHelpfulError(err) && err.kind === "not_found") {
+        return {
+          is_error: false,
+          exists: false,
+          logical_path: input.logical_path,
+        };
+      }
+      if (isHelpfulError(err)) {
+        return {
+          is_error: true,
+          error_type: err.kind,
+          message: err.message,
+        };
+      }
+      return {
+        is_error: true,
+        error_type: "internal_error",
+        message: err instanceof Error ? err.message : String(err),
+      };
+    }
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/membot/index.ts

@@ -0,0 +1,26 @@
+import { OPERATIONS } from "membot";
+import { type AnyToolDefinition, registerTool } from "../tool.ts";
+import { adaptOperation } from "./adapter.ts";
+import { membotCopyTool } from "./copy.ts";
+import { membotCountLinesTool } from "./count_lines.ts";
+import { membotEditTool } from "./edit.ts";
+import { membotExistsTool } from "./exists.ts";
+import { membotPipeTool } from "./pipe.ts";
+
+/**
+ * Register every membot operation as a Botholomew tool. The 14 verbs that
+ * have a direct membot Operation (add, list, tree, read, search, info,
+ * stats, versions, diff, write, move, delete, refresh, prune) are wired via
+ * `adaptOperation`; the five Botholomew-side wrappers (edit, copy, exists,
+ * count_lines, pipe) bolt on the file-shaped UX our agents already know.
+ */
+export function registerMembotTools(): void {
+  for (const op of OPERATIONS) {
+    registerTool(adaptOperation(op) as unknown as AnyToolDefinition);
+  }
+  registerTool(membotEditTool);
+  registerTool(membotCopyTool);
+  registerTool(membotExistsTool);
+  registerTool(membotCountLinesTool);
+  registerTool(membotPipeTool);
+}