botholomew 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.92.0",
-    "@evantahler/mcpx": "0.21.3",
+    "@evantahler/mcpx": "0.21.6",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",
@@ -36,7 +36,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "istextorbinary": "^9.5.0",
-    "membot": "^0.13.3",
+    "membot": "^0.14.0",
     "nanospinner": "^1.2.2",
     "react": "^19.2.0",
     "uuid": "^14.0.0",

package/src/chat/session.ts

@@ -3,8 +3,8 @@ import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";
 import type { MembotClient } from "membot";
 import { loadConfig } from "../config/loader.ts";
 import type { BotholomewConfig } from "../config/schemas.ts";
-import { createMcpxClient } from "../mcpx/client.ts";
-import { openMembot } from "../mem/client.ts";
+import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
+import { openMembot, resolveMembotDir } from "../mem/client.ts";
 import { loadSkills } from "../skills/loader.ts";
 import type { SkillDefinition } from "../skills/parser.ts";
 import {
@@ -60,7 +60,7 @@ export async function startChatSession(
     );
   }
 
-  const mem = openMembot(projectDir);
+  const mem = openMembot(resolveMembotDir(projectDir, config));
   await mem.connect();
   await ensureThreadsDir(projectDir);
 
@@ -101,7 +101,7 @@ export async function startChatSession(
     );
   }
 
-  const mcpxClient = await createMcpxClient(projectDir);
+  const mcpxClient = await createMcpxClient(resolveMcpxDir(projectDir, config));
   const skills = await loadSkills(projectDir);
 
   const cleanup = async () => {

package/src/commands/capabilities.ts

@@ -1,7 +1,7 @@
 import type { Command } from "commander";
 import { createSpinner } from "nanospinner";
 import { loadConfig } from "../config/loader.ts";
-import { createMcpxClient } from "../mcpx/client.ts";
+import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
 import { writeCapabilitiesFile } from "../prompts/capabilities.ts";
 import { registerAllTools } from "../tools/registry.ts";
 
@@ -19,7 +19,9 @@ export function registerCapabilitiesCommand(program: Command) {
       const spinner = createSpinner("Loading config").start();
       const config = await loadConfig(dir);
       spinner.update({ text: "Connecting to MCPX servers" });
-      const mcpxClient = includeMcp ? await createMcpxClient(dir) : null;
+      const mcpxClient = includeMcp
+        ? await createMcpxClient(resolveMcpxDir(dir, config))
+        : null;
       try {
         const result = await writeCapabilitiesFile(
           dir,

package/src/commands/context.ts

@@ -5,6 +5,8 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import { defaultCliName, OPERATIONS } from "membot";
+import { loadConfig } from "../config/loader.ts";
+import { resolveMembotDir } from "../mem/client.ts";
 import { logger } from "../utils/logger.ts";
 
 const require = createRequire(import.meta.url);
@@ -36,11 +38,14 @@ function getRawContextArgs(): string[] {
 }
 
 async function runMembot(projectDir: string, args: string[]): Promise<number> {
-  // Point membot at <projectDir> as its data dir via the `--config` flag —
-  // each Botholomew project gets its own membot store at
-  // `<projectDir>/index.duckdb`. Forward stdio so the user sees the same
-  // output they would running `membot` directly.
-  const proc = Bun.spawn(["bun", MEMBOT_CLI, "--config", projectDir, ...args], {
+  // Resolve membot's data dir from `membot_scope`:
+  //   - "global"  → ~/.membot (default, shared)
+  //   - "project" → <projectDir>
+  // Forward stdio so the user sees the same output they would running
+  // `membot` directly.
+  const config = await loadConfig(projectDir);
+  const membotDir = resolveMembotDir(projectDir, config);
+  const proc = Bun.spawn(["bun", MEMBOT_CLI, "--config", membotDir, ...args], {
     stdout: "inherit",
     stderr: "inherit",
     stdin: "inherit",
@@ -66,7 +71,7 @@ function registerImportGlobal(parent: Command, program: Command): void {
       "Overwrite an existing index.duckdb in the project",
       false,
     )
-    .action((opts: { force: boolean }) => {
+    .action(async (opts: { force: boolean }) => {
       const globalDir = join(homedir(), ".membot");
       if (!existsSync(globalDir)) {
         logger.error("No global membot data found at ~/.membot");
@@ -74,6 +79,12 @@ function registerImportGlobal(parent: Command, program: Command): void {
       }
 
       const projectDir = getDir(program);
+      const config = await loadConfig(projectDir);
+      if (config.membot_scope !== "project") {
+        logger.warn(
+          `membot_scope is "${config.membot_scope}" — Botholomew currently reads from ~/.membot. After this import, set membot_scope to "project" in ${getDir(program)}/config/config.json for the project-local copy to take effect.`,
+        );
+      }
       const dest = (name: string) => join(projectDir, name);
       const destDb = dest("index.duckdb");
 

package/src/commands/init.ts

@@ -2,6 +2,13 @@ import type { Command } from "commander";
 import { initProject } from "../init/index.ts";
 import { logger } from "../utils/logger.ts";
 
+function parseScope(value: string): "global" | "project" {
+  if (value !== "global" && value !== "project") {
+    throw new Error(`scope must be "global" or "project" (got "${value}")`);
+  }
+  return value;
+}
+
 export function registerInitCommand(program: Command) {
   program
     .command("init")
@@ -10,10 +17,24 @@ export function registerInitCommand(program: Command) {
       "--force",
       "overwrite existing project files; also bypass the unsupported-filesystem check (iCloud/Dropbox/etc)",
     )
+    .option(
+      "--membot-scope <scope>",
+      'where this project reads/writes its knowledge store: "global" (default; shared ~/.membot) or "project" (per-project index.duckdb)',
+      parseScope,
+    )
+    .option(
+      "--mcpx-scope <scope>",
+      'where this project reads its MCPX config: "global" (default; shared ~/.mcpx) or "project" (per-project mcpx/)',
+      parseScope,
+    )
     .action(async (opts) => {
       const dir = program.opts().dir;
       try {
-        await initProject(dir, { force: opts.force });
+        await initProject(dir, {
+          force: opts.force,
+          membotScope: opts.membotScope,
+          mcpxScope: opts.mcpxScope,
+        });
       } catch (err) {
         logger.error(String(err instanceof Error ? err.message : err));
         process.exit(1);

package/src/commands/mcpx.ts

@@ -7,7 +7,7 @@ import type { Command } from "commander";
 import { createSpinner } from "nanospinner";
 import { loadConfig } from "../config/loader.ts";
 import { getMcpxDir } from "../constants.ts";
-import { createMcpxClient } from "../mcpx/client.ts";
+import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
 import { writeCapabilitiesFile } from "../prompts/capabilities.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import { logger } from "../utils/logger.ts";
@@ -29,7 +29,11 @@ export async function runMcpx(
   args: (string | undefined)[],
   opts?: { inherit?: boolean },
 ): Promise<string> {
-  const mcpxDir = getMcpxDir(projectDir);
+  // Resolve mcpx config dir from `mcpx_scope`:
+  //   - "global"  → ~/.mcpx (default, shared)
+  //   - "project" → <projectDir>/mcpx
+  const config = await loadConfig(projectDir);
+  const mcpxDir = resolveMcpxDir(projectDir, config);
   const filteredArgs = args.filter((a): a is string => a !== undefined);
   const proc = Bun.spawn(["bun", MCPX_CLI, ...filteredArgs, "-c", mcpxDir], {
     stdout: opts?.inherit ? "inherit" : "pipe",
@@ -124,7 +128,15 @@ export function registerMcpxCommand(program: Command) {
         process.exit(1);
       }
 
-      const projectMcpxDir = getMcpxDir(getDir(program));
+      const projectDir = getDir(program);
+      const cfg = await loadConfig(projectDir);
+      if (cfg.mcpx_scope !== "project") {
+        logger.warn(
+          `mcpx_scope is "${cfg.mcpx_scope}" — Botholomew currently reads from ~/.mcpx. After this import, set mcpx_scope to "project" in ${projectDir}/config/config.json for the project-local copy to take effect.`,
+        );
+      }
+
+      const projectMcpxDir = getMcpxDir(projectDir);
       if (!existsSync(projectMcpxDir)) {
         mkdirSync(projectMcpxDir, { recursive: true });
       }
@@ -149,16 +161,17 @@ export function registerMcpxCommand(program: Command) {
         `Imported ${copied} file(s) from ~/.mcpx into ${projectMcpxDir}`,
       );
 
-      const projectDir = getDir(program);
       registerAllTools();
-      const config = await loadConfig(projectDir);
-      const mcpxClient = await createMcpxClient(projectDir);
+      // After import-global, the freshly-copied files live in the project's
+      // mcpx dir — read them from there so `capabilities.md` reflects what was
+      // just imported, regardless of the user's current `mcpx_scope` setting.
+      const mcpxClient = await createMcpxClient(projectMcpxDir);
       const spinner = createSpinner("Rebuilding capabilities.md").start();
       try {
         const result = await writeCapabilitiesFile(
           projectDir,
           mcpxClient,
-          config,
+          cfg,
           (phase) => spinner.update({ text: phase }),
         );
         spinner.success({

package/src/commands/nuke.ts

@@ -2,8 +2,9 @@ import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import ansis from "ansis";
 import type { Command } from "commander";
+import { loadConfig } from "../config/loader.ts";
 import { SCHEDULES_DIR, TASKS_DIR, THREADS_DIR } from "../constants.ts";
-import { openMembot } from "../mem/client.ts";
+import { openMembot, resolveMembotDir } from "../mem/client.ts";
 import { deleteAllSchedules } from "../schedules/store.ts";
 import { deleteAllTasks } from "../tasks/store.ts";
 import { deleteAllThreads } from "../threads/store.ts";
@@ -34,9 +35,16 @@ async function ensureNoRunningWorkers(projectDir: string): Promise<boolean> {
  * we fall back to deleting it outright.
  */
 async function nukeKnowledge(projectDir: string): Promise<void> {
-  const indexPath = join(projectDir, "index.duckdb");
+  const config = await loadConfig(projectDir);
+  const membotDir = resolveMembotDir(projectDir, config);
+  const indexPath = join(membotDir, "index.duckdb");
+  if (config.membot_scope !== "project") {
+    logger.warn(
+      `membot_scope is "${config.membot_scope}"; this will erase the SHARED knowledge store at ${membotDir}`,
+    );
+  }
   try {
-    const mem = openMembot(projectDir);
+    const mem = openMembot(membotDir);
     try {
       const list = await mem.list({ limit: 100_000 });
       const paths = list.entries.map((e) => e.logical_path);

package/src/commands/prepare.ts

@@ -1,6 +1,6 @@
 import type { Command } from "commander";
 import { loadConfig } from "../config/loader.ts";
-import { openMembot } from "../mem/client.ts";
+import { openMembot, resolveMembotDir } from "../mem/client.ts";
 import { logger } from "../utils/logger.ts";
 
 export function registerPrepareCommand(program: Command) {
@@ -13,8 +13,7 @@ export function registerPrepareCommand(program: Command) {
       const projectDir = program.opts().dir as string;
       logger.info("Preparing Botholomew...");
       const config = await loadConfig(projectDir);
-      void config;
-      const mem = openMembot(projectDir);
+      const mem = openMembot(resolveMembotDir(projectDir, config));
       try {
         await mem.connect();
         logger.success("membot knowledge store opened successfully");

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/init/index.ts

@@ -21,8 +21,8 @@ import {
   TASKS_DIR,
 } from "../constants.ts";
 import { assertCompatibleFilesystem } from "../fs/compat.ts";
-import { createMcpxClient } from "../mcpx/client.ts";
-import { openMembot } from "../mem/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";
@@ -37,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
@@ -79,43 +87,63 @@ 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 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);
+  // 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(`  Knowledge:    index.duckdb (managed by membot)`);
+  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(`  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`);

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

@@ -1,17 +1,33 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { MembotClient } from "membot";
+import type { BotholomewConfig } from "../config/schemas.ts";
 
 /**
- * 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.
+ * 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
- * `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.
+ * `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 openMembot(projectDir: string): MembotClient {
-  return new MembotClient({ configFlag: projectDir });
+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/worker/index.ts

@@ -1,8 +1,8 @@
 import { hostname } from "node:os";
 import ansis from "ansis";
 import { loadConfig } from "../config/loader.ts";
-import { createMcpxClient } from "../mcpx/client.ts";
-import { openMembot } from "../mem/client.ts";
+import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
+import { openMembot, resolveMembotDir } from "../mem/client.ts";
 import { logger } from "../utils/logger.ts";
 import { uuidv7 } from "../utils/uuid.ts";
 import { markWorkerStopped, registerWorker } from "../workers/store.ts";
@@ -87,12 +87,12 @@ export async function startWorker(
   const evalSchedules = options.evalSchedules ?? !taskId;
 
   const config = await loadConfig(projectDir);
-  const mem = openMembot(projectDir);
+  const mem = openMembot(resolveMembotDir(projectDir, config));
   // Surface init-time failures (bad config, locked DB) up front rather than
   // letting the first tool call do it.
   await mem.connect();
 
-  const mcpxClient = await createMcpxClient(projectDir);
+  const mcpxClient = await createMcpxClient(resolveMcpxDir(projectDir, config));
   if (mcpxClient) {
     logger.info("MCPX client initialized with external tools");
   }