botholomew 0.16.4 → 0.18.0

package/src/config/schemas.ts

@@ -1,3 +1,5 @@
+export type Scope = "global" | "project";
+
 export interface BotholomewConfig {
   anthropic_api_key?: string;
   model?: string;
@@ -16,6 +18,8 @@ export interface BotholomewConfig {
   schedule_claim_stale_seconds?: number;
   tui_idle_timeout_seconds?: number;
   log_level?: string;
+  membot_scope?: Scope;
+  mcpx_scope?: Scope;
 }
 
 export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
@@ -36,4 +40,6 @@ export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
   schedule_claim_stale_seconds: 300,
   tui_idle_timeout_seconds: 180,
   log_level: "",
+  membot_scope: "global",
+  mcpx_scope: "global",
 };

package/src/constants.ts

@@ -6,19 +6,22 @@ import { join } from "node:path";
  *
  *   <projectDir>/
  *     config/config.json
- *     prompts/*.md                     init seeds goals/beliefs/capabilities
+ *     config.json                       membot config (separate from ours)
+ *     index.duckdb                      membot-owned knowledge store
+ *     prompts/*.md                      init seeds goals/beliefs/capabilities
  *     skills/*.md
  *     mcpx/servers.json
- *     models/                          embedding model cache
- *     context/                         user-curated knowledge tree
- *     tasks/<id>.md                    tasks (status in frontmatter)
- *     tasks/.locks/<id>.lock           O_EXCL claim files
- *     schedules/<id>.md                schedules
+ *     tasks/<id>.md                     tasks (status in frontmatter)
+ *     tasks/.locks/<id>.lock            O_EXCL claim files
+ *     schedules/<id>.md
  *     schedules/.locks/<id>.lock
- *     threads/<YYYY-MM-DD>/<id>.csv    conversation history
- *     workers/<id>.json                pidfile + heartbeat
- *     logs/                            worker logs
- *     index.duckdb                     search index (rebuildable from disk)
+ *     threads/<YYYY-MM-DD>/<id>.csv     conversation history
+ *     workers/<id>.json                 pidfile + heartbeat
+ *     logs/                             worker logs
+ *
+ * The agent's knowledge ("what used to be `context/`") now lives in
+ * `index.duckdb`, managed by the `membot` library. Tasks, schedules, threads,
+ * workers, prompts, and skills remain real files on disk.
  */
 
 export const HOME_CONFIG_DIR = join(homedir(), ".botholomew");
@@ -32,14 +35,11 @@ export const DEFAULTS = {
   UPDATE_CHECK_TIMEOUT_MS: 5_000,
 } as const;
 
-export const INDEX_DB_FILENAME = "index.duckdb";
 export const CONFIG_DIR = "config";
 export const CONFIG_FILENAME = "config.json";
 export const PROMPTS_DIR = "prompts";
 export const SKILLS_DIR = "skills";
 export const MCPX_DIR = "mcpx";
-export const MODELS_DIR = "models";
-export const CONTEXT_DIR = "context";
 export const TASKS_DIR = "tasks";
 export const SCHEDULES_DIR = "schedules";
 export const LOCKS_SUBDIR = ".locks";
@@ -47,24 +47,18 @@ export const LOGS_DIR = "logs";
 export const WORKERS_DIR = "workers";
 export const THREADS_DIR = "threads";
 export const MCPX_SERVERS_FILENAME = "servers.json";
-export const EMBEDDING_DIMENSION = 384;
-export const EMBEDDING_MODEL = "Xenova/bge-small-en-v1.5";
 
 /**
- * Top-level areas tools must never touch directly. Use as a safelist when
- * validating tool path arguments — most file/dir tools pin to CONTEXT_DIR.
+ * Top-level areas tools must never touch directly. Tasks/schedule lockfile
+ * dirs are kept off-limits because their `O_EXCL` claim semantics break if
+ * something else writes into them.
  */
 export const PROTECTED_AREAS: ReadonlySet<string> = new Set([
-  MODELS_DIR,
   LOGS_DIR,
   `${TASKS_DIR}/${LOCKS_SUBDIR}`,
   `${SCHEDULES_DIR}/${LOCKS_SUBDIR}`,
 ]);
 
-export function getDbPath(projectDir: string): string {
-  return join(projectDir, INDEX_DB_FILENAME);
-}
-
 export function getWorkerLogsDir(projectDir: string): string {
   return join(projectDir, LOGS_DIR);
 }
@@ -92,12 +86,6 @@ export function getMcpxDir(projectDir: string): string {
   return join(projectDir, MCPX_DIR);
 }
 
-export function getModelsDir(projectDir: string): string {
-  return (
-    process.env.BOTHOLOMEW_MODELS_DIR_OVERRIDE ?? join(projectDir, MODELS_DIR)
-  );
-}
-
 export function getSkillsDir(projectDir: string): string {
   return join(projectDir, SKILLS_DIR);
 }
@@ -106,10 +94,6 @@ export function getPromptsDir(projectDir: string): string {
   return join(projectDir, PROMPTS_DIR);
 }
 
-export function getContextDir(projectDir: string): string {
-  return join(projectDir, CONTEXT_DIR);
-}
-
 export function getTasksDir(projectDir: string): string {
   return join(projectDir, TASKS_DIR);
 }

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 { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
+import { openMembot, resolveMembotDir } from "../mem/client.ts";
+import { writeCapabilitiesFile } from "../prompts/capabilities.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import { logger } from "../utils/logger.ts";
 import {
@@ -40,9 +37,17 @@ import {
   SUMMARIZE_SKILL,
 } from "./templates.ts";
 
+export interface InitOptions {
+  force?: boolean;
+  /** Override the default `membot_scope` written into config/config.json. */
+  membotScope?: "global" | "project";
+  /** Override the default `mcpx_scope` written into config/config.json. */
+  mcpxScope?: "global" | "project";
+}
+
 export async function initProject(
   projectDir: string,
-  opts: { force?: boolean } = {},
+  opts: InitOptions = {},
 ): Promise<void> {
   // Refuse to operate inside iCloud/Dropbox/etc unless --force is passed.
   // Sync overlays break atomic rename / O_EXCL semantics that tasks and
@@ -62,7 +67,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 });
@@ -83,48 +87,69 @@ export async function initProject(
   await Bun.write(join(skillsDir, "standup.md"), STANDUP_SKILL);
   await Bun.write(join(skillsDir, "capabilities.md"), CAPABILITIES_SKILL);
 
-  // Config
-  await Bun.write(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`);
+  // Config — apply scope overrides from caller (CLI flags / tests) on top of
+  // the seeded defaults so tests and `botholomew init --membot-scope=project`
+  // can pick a per-project layout up front.
+  const initialConfig = {
+    ...DEFAULT_CONFIG,
+    ...(opts.membotScope ? { membot_scope: opts.membotScope } : {}),
+    ...(opts.mcpxScope ? { mcpx_scope: opts.mcpxScope } : {}),
+  };
+  await Bun.write(configPath, `${JSON.stringify(initialConfig, null, 2)}\n`);
+  const config = await loadConfig(projectDir);
 
-  // mcpx servers config
-  await Bun.write(
-    join(getMcpxDir(projectDir), MCPX_SERVERS_FILENAME),
-    `${JSON.stringify(DEFAULT_MCPX_SERVERS, null, 2)}\n`,
-  );
+  // mcpx servers config — only seed a project-local servers.json when the
+  // project is opting out of the shared `~/.mcpx`. The empty `mcpx/` directory
+  // is still created above so flipping `mcpx_scope` later is a one-line edit.
+  if (config.mcpx_scope === "project") {
+    await Bun.write(
+      join(getMcpxDir(projectDir), MCPX_SERVERS_FILENAME),
+      `${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. When `membot_scope` is "global"
+  // (the default) we point at `~/.membot` so the shared store is ready;
+  // when "project" we seed `<projectDir>/index.duckdb`.
+  const mem = openMembot(resolveMembotDir(projectDir, config));
+  await mem.connect();
+  await mem.close();
 
   // Populate capabilities.md with the real tool inventory.
   registerAllTools();
-  const config = await loadConfig(projectDir);
-  const mcpxClient = await createMcpxClient(projectDir);
+  const mcpxClient = await createMcpxClient(resolveMcpxDir(projectDir, config));
   try {
     await writeCapabilitiesFile(projectDir, mcpxClient, config);
   } finally {
     await mcpxClient?.close();
   }
 
+  const membotScopeDesc =
+    config.membot_scope === "project"
+      ? `${projectDir}/index.duckdb (project-local)`
+      : `~/.membot (shared across projects — set membot_scope to "project" in ${CONFIG_DIR}/${CONFIG_FILENAME} to isolate)`;
+  const mcpxScopeDesc =
+    config.mcpx_scope === "project"
+      ? `${projectDir}/mcpx/ (project-local)`
+      : `~/.mcpx (shared across projects — set mcpx_scope to "project" in ${CONFIG_DIR}/${CONFIG_FILENAME} to isolate)`;
   logger.success("Initialized Botholomew project");
-  logger.dim(`  Project root: ${projectDir}`);
-  logger.dim(`  Config:       ${CONFIG_DIR}/${CONFIG_FILENAME}`);
-  logger.dim(`  Index DB:     ${dbPath}`);
+  logger.dim(`  Project root:  ${projectDir}`);
+  logger.dim(`  Config:        ${CONFIG_DIR}/${CONFIG_FILENAME}`);
+  logger.dim(`  Knowledge:     ${membotScopeDesc}`);
+  logger.dim(`  MCPX:          ${mcpxScopeDesc}`);
   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(`  ${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/mcpx/client.ts

@@ -1,16 +1,33 @@
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { type CallToolResult, McpxClient } from "@evantahler/mcpx";
+import type { BotholomewConfig } from "../config/schemas.ts";
 import { getMcpxDir, MCPX_SERVERS_FILENAME } from "../constants.ts";
 
 /**
- * Create an McpxClient from the project's mcpx/servers.json.
- * Returns null if the file is missing or has no servers configured.
+ * Resolve the mcpx config directory for a project, honoring `mcpx_scope`:
+ *   - "global"  → `~/.mcpx` (shared across all Botholomew projects)
+ *   - "project" → `<projectDir>/mcpx` (isolated per project)
  */
-export async function createMcpxClient(
+export function resolveMcpxDir(
   projectDir: string,
+  config: Pick<BotholomewConfig, "mcpx_scope">,
+): string {
+  return config.mcpx_scope === "project"
+    ? getMcpxDir(projectDir)
+    : join(homedir(), ".mcpx");
+}
+
+/**
+ * Create an McpxClient from `<mcpxDir>/servers.json`. Returns null if the
+ * file is missing or has no servers configured. The caller is responsible
+ * for resolving `mcpxDir` via `resolveMcpxDir`.
+ */
+export async function createMcpxClient(
+  mcpxDir: string,
 ): Promise<McpxClient | null> {
-  const serversPath = join(getMcpxDir(projectDir), MCPX_SERVERS_FILENAME);
+  const serversPath = join(mcpxDir, MCPX_SERVERS_FILENAME);
   if (!existsSync(serversPath)) return null;
 
   const raw = await Bun.file(serversPath).text();
@@ -20,7 +37,6 @@ export async function createMcpxClient(
     return null;
   }
 
-  const mcpxDir = getMcpxDir(projectDir);
   const authPath = join(mcpxDir, "auth.json");
   const auth = existsSync(authPath)
     ? JSON.parse(await Bun.file(authPath).text())

package/src/mem/client.ts

@@ -0,0 +1,33 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { MembotClient } from "membot";
+import type { BotholomewConfig } from "../config/schemas.ts";
+
+/**
+ * Resolve the membot data directory for a project, honoring `membot_scope`:
+ *   - "global"  → `~/.membot` (shared across all Botholomew projects)
+ *   - "project" → `<projectDir>` (isolated per project)
+ *
+ * Membot's `configFlag` doubles as its data-dir flag (see
+ * `node_modules/membot/src/config/loader.ts::resolveDataDir`): an explicit
+ * value wins over `$MEMBOT_HOME` and the `~/.membot` default. We always pass
+ * an explicit value so a stray `MEMBOT_HOME` cannot redirect Botholomew at a
+ * different store.
+ */
+export function resolveMembotDir(
+  projectDir: string,
+  config: Pick<BotholomewConfig, "membot_scope">,
+): string {
+  return config.membot_scope === "project"
+    ? projectDir
+    : join(homedir(), ".membot");
+}
+
+/**
+ * Open a membot client rooted at `dataDir`. The caller is responsible for
+ * resolving the directory (via `resolveMembotDir`) and for `close()` on
+ * shutdown.
+ */
+export function openMembot(dataDir: string): MembotClient {
+  return new MembotClient({ configFlag: dataDir });
+}

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>;