@100xprompt/brain 0.1.2 → 0.1.4

package/src/lock.ts

@@ -0,0 +1,269 @@
+// The brain lock: one brain at a time changes the files brain manages (a coding tool's config, brain's own settings).
+// Two brains run at once more often than it seems: a command in the terminal and, later, the background agent; two
+// terminals; a tool starting `brain mcp serve` while the person runs `brain gateway connect`. Each of them reads a file,
+// changes it and writes it back, so without a lock one could silently undo the other's change.
+//
+//   - It waits: a brain that finds it taken waits its turn (up to 30 s, BRAIN_LOCK_TIMEOUT_MS), then says who holds it.
+//   - A lock never exists without its owner: the folder is made with owner.json inside, then renamed into place.
+//   - It is cleared only when its holder is gone: the holder's process id and start time are in owner.json, and a lock
+//     whose process has ended (or whose id now belongs to a process that started at another time) is removed, under a
+//     short second lock, after checking again that it is still that same lock. A slow holder is never pushed aside.
+//   - It is re-entrant within one process: a command that holds it can call code that takes it again. Two unrelated async
+//     flows in ONE process would share it: nothing in brain runs those yet (a background agent must keep one at a time).
+//   - Network checks happen before taking it; nothing slow runs while it is held.
+//   - Where <home>/.brain cannot be written (a read-only or root-owned folder), brain goes on without it, as it did before
+//     there was a lock: there is nothing to coordinate with there.
+// Never taken by the session-start hook or by `brain mcp serve`: those only read.
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+export const lockPath = (home: string) => join(home, ".brain", "lock")
+const ownerPath = (home: string) => join(lockPath(home), "owner.json")
+
+export interface LockOwner {
+  pid: number
+  /** When the holding process started (epoch ms, as `ps` sees it), to tell it from a newer process that got the same id. */
+  startedAt: number
+  /** When it took the lock. */
+  at: string
+  /** What it was doing, for the message a waiting brain prints. */
+  what?: string
+}
+
+/** Thrown when the lock stays taken longer than the wait allows. */
+export class BrainBusy extends Error {
+  constructor(
+    public owner: LockOwner | undefined,
+    waitedMs: number,
+  ) {
+    super(
+      `another brain${owner ? ` (process ${owner.pid}${owner.what ? `, ${owner.what}` : ""})` : ""} has been changing settings for more than ${waitedMs < 10_000 ? (waitedMs / 1000).toFixed(1) : Math.round(waitedMs / 1000)} s; try again in a moment`,
+    )
+    this.name = "BrainBusy"
+  }
+}
+
+/** A lock folder without an owner file this old is not a lock brain made (or one from before owner files came with it). */
+const ORPHAN_MS = 10_000
+/** Process start times are compared with this much slack (ps reports whole seconds). */
+const START_SLACK_MS = 5_000
+/** A holder found alive is not looked up again for this long (each look runs `ps`). */
+const ALIVE_RECHECK_MS = 1_000
+
+const depth = new Map<string, number>()
+/** Homes this process goes on in without a lock (their .brain cannot be written). */
+const unlocked = new Set<string>()
+let seenAlive: { key: string; at: number } | undefined
+
+const code = (e: unknown) => (e as NodeJS.ErrnoException)?.code
+const unwritable = (e: unknown) => ["EACCES", "EPERM", "EROFS"].includes(code(e) ?? "")
+const rand = () => Math.random().toString(36).slice(2, 10)
+
+export function lockTimeout(env: Record<string, string | undefined> = process.env): number {
+  const n = Number(env.BRAIN_LOCK_TIMEOUT_MS)
+  return env.BRAIN_LOCK_TIMEOUT_MS && Number.isFinite(n) && n >= 0 ? n : 30_000
+}
+
+/** `ps` elapsed time ([[dd-]hh:]mm:ss) in seconds. */
+export function elapsedSeconds(etime: string): number | undefined {
+  const m = /^\s*(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)\s*$/.exec(etime)
+  if (!m) return undefined
+  return Number(m[1] ?? 0) * 86_400 + Number(m[2] ?? 0) * 3_600 + Number(m[3]) * 60 + Number(m[4])
+}
+
+/**
+ * When a running process started (epoch ms), or undefined when that cannot be told here. From how long it has run
+ * (`ps -o etime=`, [[dd-]hh:]mm:ss), not from its start date, which ps prints in a time zone this process may not share.
+ */
+export function processStart(pid: number, now = Date.now()): number | undefined {
+  if (process.platform === "win32") return undefined
+  try {
+    const p = Bun.spawnSync(["ps", "-o", "etime=", "-p", String(pid)], { stdout: "pipe", stderr: "ignore", timeout: 2_000, env: { ...process.env, LC_ALL: "C" } })
+    const s = elapsedSeconds(p.stdout.toString())
+    return s === undefined ? undefined : now - s * 1000
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * This process's start as a waiting brain will see it: measured the same way (`ps`), so a process that started well before
+ * Bun did (a wrapper that runs `exec brain` later) is not mistaken for a newer one. Measured once, when first needed.
+ */
+let started: number | undefined
+const myStart = () => (started ??= processStart(process.pid) ?? Math.round(performance.timeOrigin))
+
+function readOwner(home: string): LockOwner | undefined {
+  try {
+    const o = JSON.parse(readFileSync(ownerPath(home), "utf8"))
+    return Number.isInteger(o?.pid) && Number.isFinite(o?.startedAt) ? (o as LockOwner) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether the lock's holder has ended: its process is gone, or its id now belongs to a process that started at another
+ * time. A process of another user (EPERM) is not taken as alive by that alone: its start time is still compared.
+ */
+export function holderGone(o: LockOwner): boolean {
+  if (o.pid === process.pid) return o.startedAt !== myStart()
+  try {
+    process.kill(o.pid, 0)
+  } catch (e) {
+    if (code(e) === "ESRCH") return true
+    if (code(e) !== "EPERM") return false
+  }
+  const s = processStart(o.pid)
+  return s !== undefined && Math.abs(s - o.startedAt) > START_SLACK_MS
+}
+
+/** Takes the lock if it is free: a folder holding owner.json is made aside, then renamed into place in one step. */
+function tryTake(home: string, what: string | undefined): "taken" | "busy" | "unavailable" {
+  const tmp = `${lockPath(home)}.new-${process.pid}-${rand()}`
+  try {
+    mkdirSync(join(home, ".brain"), { recursive: true, mode: 0o700 })
+    mkdirSync(tmp, { mode: 0o700 })
+    const owner: LockOwner = { pid: process.pid, startedAt: myStart(), at: new Date().toISOString(), ...(what ? { what } : {}) }
+    writeFileSync(join(tmp, "owner.json"), JSON.stringify(owner), { mode: 0o600 })
+  } catch (e) {
+    rmSync(tmp, { recursive: true, force: true })
+    if (unwritable(e)) return "unavailable"
+    throw e
+  }
+  try {
+    renameSync(tmp, lockPath(home))
+    return "taken"
+  } catch (e) {
+    rmSync(tmp, { recursive: true, force: true })
+    // ENOTEMPTY / EEXIST: another brain's lock is there. ENOTDIR: something else is in its place.
+    if (["ENOTEMPTY", "EEXIST", "ENOTDIR", "EISDIR"].includes(code(e) ?? "")) return "busy"
+    if (unwritable(e)) return "unavailable"
+    throw e
+  }
+}
+
+/** Removes the lock folder in one step (moved aside first, so no other brain ever sees it half removed). */
+function removeLock(home: string) {
+  const aside = `${lockPath(home)}.gone-${process.pid}-${rand()}`
+  try {
+    renameSync(lockPath(home), aside)
+  } catch (e) {
+    if (code(e) === "ENOENT") return
+    throw e
+  }
+  rmSync(aside, { recursive: true, force: true })
+}
+
+/**
+ * Clears a lock whose holder has ended, and says whether it did. Done under a short second lock (lock.break), after reading
+ * the owner again: only that same abandoned lock is removed, never one another brain took meanwhile.
+ */
+function clearIfAbandoned(home: string): boolean {
+  const o = readOwner(home)
+  let mtime: number | undefined
+  if (o) {
+    const key = `${home}\0${o.pid}\0${o.startedAt}`
+    if (seenAlive?.key === key && Date.now() - seenAlive.at < ALIVE_RECHECK_MS) return false
+    if (!holderGone(o)) {
+      seenAlive = { key, at: Date.now() }
+      return false
+    }
+  } else {
+    try {
+      mtime = statSync(lockPath(home)).mtimeMs
+    } catch (e) {
+      if (code(e) === "ENOENT") return true
+      throw e
+    }
+    if (Date.now() - mtime < ORPHAN_MS) return false
+  }
+  const brk = `${lockPath(home)}.break`
+  try {
+    mkdirSync(brk)
+  } catch (e) {
+    if (code(e) !== "EEXIST") throw e
+    // Another brain is clearing it; one that died doing so leaves an old helper behind, which goes.
+    try {
+      if (Date.now() - statSync(brk).mtimeMs > ORPHAN_MS) rmSync(brk, { recursive: true, force: true })
+    } catch {}
+    return false
+  }
+  try {
+    const again = readOwner(home)
+    const same = o ? !!again && again.pid === o.pid && again.startedAt === o.startedAt : !again && statSync(lockPath(home), { throwIfNoEntry: false })?.mtimeMs === mtime
+    if (!same) return false
+    removeLock(home)
+    return true
+  } catch (e) {
+    if (code(e) === "ENOENT") return true
+    throw e
+  } finally {
+    rmSync(brk, { recursive: true, force: true })
+  }
+}
+
+function acquire(home: string, what: string | undefined, timeoutMs: number) {
+  const n = depth.get(home) ?? 0
+  if (n > 0) {
+    depth.set(home, n + 1)
+    return
+  }
+  const start = Date.now()
+  for (let i = 0; ; i++) {
+    if (i > 0 && Date.now() - start >= timeoutMs) throw new BrainBusy(readOwner(home), Date.now() - start)
+    const r = tryTake(home, what)
+    if (r === "unavailable") unlocked.add(home)
+    if (r !== "busy") break
+    if (clearIfAbandoned(home)) continue
+    Bun.sleepSync(Math.min(25 * 2 ** Math.min(i, 3), 200) + Math.floor(Math.random() * 20))
+  }
+  depth.set(home, 1)
+}
+
+function release(home: string) {
+  const n = depth.get(home) ?? 0
+  if (n > 1) {
+    depth.set(home, n - 1)
+    return
+  }
+  depth.delete(home)
+  if (unlocked.delete(home)) return
+  // Only a lock that is positively ours: one cleared and retaken by another brain is not ours to remove.
+  const o = readOwner(home)
+  if (!o || o.pid !== process.pid || o.startedAt !== myStart()) return
+  removeLock(home)
+}
+
+/** Whether this process holds the lock for `home` right now. */
+export const holdsLock = (home: string) => (depth.get(home) ?? 0) > 0
+
+/** Runs `fn` while holding the brain lock for `home`. */
+export function withBrainLockSync<T>(home: string, fn: () => T, o: { what?: string; timeoutMs?: number } = {}): T {
+  acquire(home, o.what, o.timeoutMs ?? lockTimeout())
+  try {
+    return fn()
+  } finally {
+    release(home)
+  }
+}
+
+/** The same for async work. Hold it only around reading, changing and writing files: never across a network call. */
+export async function withBrainLock<T>(home: string, fn: () => Promise<T> | T, o: { what?: string; timeoutMs?: number } = {}): Promise<T> {
+  acquire(home, o.what, o.timeoutMs ?? lockTimeout())
+  try {
+    return await fn()
+  } finally {
+    release(home)
+  }
+}
+
+// A brain that exits while holding the lock (process.exit in a command) leaves nothing behind.
+process.on("exit", () => {
+  for (const home of [...depth.keys()]) {
+    depth.set(home, 1)
+    try {
+      release(home)
+    } catch {}
+  }
+})

package/src/memory/audit.ts

@@ -6,7 +6,7 @@
 
 import { closeSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs"
 import { dirname, isAbsolute, join, relative, resolve } from "node:path"
-import { LEAN_AUTO_TOKENS } from "./prepare.ts"
+import { leanSettings } from "../settings/values.ts"
 import { approxTokens } from "./types.ts"
 
 export const FILE_WARN_TOKENS = 2_000
@@ -69,7 +69,8 @@ export interface AuditReport {
     lockfilesUncovered: string[]
   }
   large: LargeFile[]
-  brain: { installedIn: string[]; leanThresholdTokens: number }
+  /** leanThresholdTokens: from how many tokens a session is made lean by itself; null when that is turned off (brain settings). */
+  brain: { installedIn: string[]; leanThresholdTokens: number | null }
   findings: Finding[]
   /** Instruction-file tokens: what is certainly paid on every request. MCP tool definitions come on top and are not measured. */
   reloadedTokens: number
@@ -435,6 +436,7 @@ export function auditTokens(dirIn: string, home: string): AuditReport {
   const installedIn = mcp.filter((c) => c.servers.includes("brain")).map((c) => c.tool)
   if (!installedIn.length) findings.push({ severity: 1, area: "brain", message: "the brain MCP server is not installed in any tool, so digests of big tool output cannot be expanded", fix: "run `brain mcp install`" })
 
+  const lean = leanSettings(home)
   findings.sort((a, b) => b.severity - a.severity || (b.tokens ?? 0) - (a.tokens ?? 0) || (a.message < b.message ? -1 : a.message > b.message ? 1 : 0))
   return {
     dir,
@@ -445,7 +447,7 @@ export function auditTokens(dirIn: string, home: string): AuditReport {
     mcpServersMax,
     ignore,
     large,
-    brain: { installedIn, leanThresholdTokens: LEAN_AUTO_TOKENS },
+    brain: { installedIn, leanThresholdTokens: lean.auto ? lean.threshold : null },
     findings,
     reloadedTokens: instructionTokens,
   }
@@ -474,7 +476,7 @@ export function formatAudit(r: AuditReport): string[] {
   out.push("", `ignore: .gitignore ${ig.gitignore ? "present" : "missing"}; agent ignore files: ${ig.agentIgnores.join(", ") || "none"}`)
   out.push(`large files (${r.gitTracked ? "git-tracked" : "not a git repo: folder walk"}, text over ${LARGE_FILE_BYTES / 1024} KB): ${r.large.length ? "" : "none"}`.trimEnd())
   for (const f of r.large) out.push(`  ${f.path}  ${n(f.tokens)} tokens`)
-  out.push("", `brain: MCP server ${r.brain.installedIn.length ? `installed (${r.brain.installedIn.join(", ")})` : "not installed"}; lean is automatic from ${n(r.brain.leanThresholdTokens)} tokens`)
+  out.push("", `brain: MCP server ${r.brain.installedIn.length ? `installed (${r.brain.installedIn.join(", ")})` : "not installed"}; ${r.brain.leanThresholdTokens === null ? "lean is not automatic on this computer (brain settings: lean.auto off)" : `lean is automatic from ${n(r.brain.leanThresholdTokens)} tokens`}`)
   out.push("", `tokens reloaded on every request: about ${n(r.reloadedTokens)} (instruction files)${r.mcpServersMax ? `, plus the tool definitions of ${r.mcpServersMax} MCP server${r.mcpServersMax === 1 ? "" : "s"} (not measured)` : ""}`)
   return out
 }

package/src/memory/cli.ts

@@ -8,6 +8,7 @@ import { projectKey } from "./project.ts"
 import { redact } from "./redact.ts"
 import { openMemory, storeBytes } from "./store.ts"
 import type { ProjectKey } from "./types.ts"
+import { MEMORY_OFF, memoryOn } from "../settings/values.ts"
 
 function flag(args: string[], name: string): string | undefined {
   const i = args.indexOf(`--${name}`)
@@ -46,6 +47,11 @@ async function pickProject(args: string[], mem: ReturnType<typeof openMemory>):
 
 export async function memoryCommand(args: string[], home: string, resolve: (id: string) => Promise<Session>, out: (line: string) => void = console.log): Promise<number> {
   const [sub, ...rest] = args
+  // Turned off on this computer: nothing is stored or searched (forgetting still works: it only removes).
+  if (!memoryOn(home) && sub !== "forget") {
+    if (sub === "status" || !sub) return out(`memory: off`), out(`why: ${MEMORY_OFF}`), 0
+    if (sub === "ingest" || sub === "search") return out(MEMORY_OFF), 1
+  }
   const mem = openMemory(home)
   try {
     if (sub === "status" || !sub) {

package/src/memory/externalize.ts

@@ -397,6 +397,18 @@ export const KEEP_RECENT_SHARE = 0.2
 export interface BudgetOptions {
   targetTokens: number
   tidy?: boolean
+  /** Level 1's size from which an output is replaced (the `lean.minChars` setting); the later levels never take less than it would. Default 1,500. */
+  minChars?: number
+}
+
+/** The levels for a level-1 size of `minChars`: level 1 is the plain lean size, and each later level goes no higher than the one before. */
+export function budgetLevels(minChars = BUDGET_LEVELS[0]!.minChars): Array<{ minChars: number; keepRecent: number }> {
+  let prev = minChars
+  return BUDGET_LEVELS.map((l, i) => {
+    const m = i === 0 ? minChars : Math.min(l.minChars, prev)
+    prev = m
+    return { minChars: m, keepRecent: l.keepRecent }
+  })
 }
 export interface BudgetOutcome extends ExternalizeOutcome {
   /** 0: the tidied session already fits; 1..4: the first level at which it fits (4 when none does). */
@@ -415,20 +427,21 @@ export function externalizeToBudget(session: Session, store: BlobStore, o: Budge
   const target = Math.max(0, Math.floor(o.targetTokens))
   const cap = Math.round(target * KEEP_RECENT_SHARE)
   const common = { keepRecentTokens: cap, ...(o.tidy === false ? { tidy: false } : {}) }
+  const levels = budgetLevels(o.minChars)
   let level = 0
-  const trialTokens = (idx: number) => approxTokens("x".repeat(externalize(session, countingBlobs(), { ...BUDGET_LEVELS[idx]!, ...common }).after))
-  const base = externalize(session, countingBlobs(), { ...BUDGET_LEVELS[0]!, ...common, stopAtTokens: target })
+  const trialTokens = (idx: number) => approxTokens("x".repeat(externalize(session, countingBlobs(), { ...levels[idx]!, ...common }).after))
+  const base = externalize(session, countingBlobs(), { ...levels[0]!, ...common, stopAtTokens: target })
   if (base.replaced === 0 && approxTokens("x".repeat(base.after)) <= target) {
     level = 0
   } else {
-    for (let i = 0; i < BUDGET_LEVELS.length; i++) {
+    for (let i = 0; i < levels.length; i++) {
       level = i + 1
       if (trialTokens(i) <= target) {
         break
       }
     }
   }
-  const opts: ExternalizeOpts = { ...BUDGET_LEVELS[Math.max(0, level - 1)]!, ...common, stopAtTokens: target }
+  const opts: ExternalizeOpts = { ...levels[Math.max(0, level - 1)]!, ...common, stopAtTokens: target }
   const r = externalize(session, store, opts)
   const tokens = estimateTokens(r.session)
   return { ...r, level, reached: tokens <= target, tokens }

package/src/memory/mcp-install.ts

@@ -1,7 +1,9 @@
 import { PACKAGE, selfArgs, stableBun } from "../self.ts"
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { runMcpServer } from "./mcp-server.ts"
+import { writeAtomic } from "../fsutil.ts"
+import { withBrainLockSync } from "../lock.ts"
 import type { ProjectKey } from "./types.ts"
 
 // `brain mcp serve | install | uninstall | status`. The installer writes one entry named "brain" into each tool's
@@ -106,11 +108,7 @@ function writeFile(home: string, tool: string, path: string, text: string) {
   } catch {
     // New file: default mode.
   }
-  const tmp = `${real}.brain-tmp`
-  rmSync(tmp, { force: true })
-  writeFileSync(tmp, text, mode === undefined ? {} : { mode })
-  if (mode !== undefined) chmodSync(tmp, mode)
-  renameSync(tmp, real)
+  writeAtomic(real, text, mode)
 }
 
 /** An entry is ours when it runs `... mcp serve` through a cli.ts, or through the brain package (`bun x @100xprompt/brain@...`). */
@@ -175,6 +173,12 @@ function hasRun(t: McpTool, home: string): boolean {
   return t.probe.some((p) => existsSync(join(home, p)))
 }
 
+/** Whether a tool the installer knows has run on this machine (its config or folder exists). */
+export function mcpHasRun(home: string, tool: string): boolean {
+  const t = MCP_TOOLS.find((x) => x.id === tool)
+  return !!t && hasRun(t, home)
+}
+
 function prepare(tool: string, home: string): { t: McpTool; path: string } | McpChange {
   const t = MCP_TOOLS.find((x) => x.id === tool)
   if (!t) return { tool, path: "", action: "skipped", why: `no MCP installer for "${tool}"; available: ${MCP_TOOLS.map((x) => x.id).join(", ")}` }
@@ -191,6 +195,10 @@ function currentJson(t: McpTool, config: Json): { entry: unknown } | { error: st
 }
 
 export function installMcp(tools: string[], home: string, opts: Opts = {}): McpChange[] {
+  return opts.dryRun ? installLocked(tools, home, opts) : withBrainLockSync(home, () => installLocked(tools, home, opts), { what: "installing the brain tools" })
+}
+
+function installLocked(tools: string[], home: string, opts: Opts): McpChange[] {
   const out: McpChange[] = []
   const args = argsFor(opts.cli)
   for (const tool of [...new Set(tools)]) {
@@ -278,6 +286,10 @@ export function installMcp(tools: string[], home: string, opts: Opts = {}): McpC
 }
 
 export function uninstallMcp(tools: string[], home: string, opts: Opts = {}): McpChange[] {
+  return opts.dryRun ? uninstallLocked(tools, home, opts) : withBrainLockSync(home, () => uninstallLocked(tools, home, opts), { what: "removing the brain tools" })
+}
+
+function uninstallLocked(tools: string[], home: string, opts: Opts): McpChange[] {
   const out: McpChange[] = []
   for (const tool of [...new Set(tools)]) {
     const p = prepare(tool, home)
@@ -366,6 +378,38 @@ export function statusMcp(home: string): McpChange[] {
   })
 }
 
+/**
+ * Whether brain's entry is in a tool's config, and whether it can still start: its bun and its cli.ts are where it says.
+ * Any brain's entry counts as installed (one from another checkout, or a pinned package): settings leave a working entry
+ * as it is, so two brains never keep rewriting each other's, and repair only one that cannot start.
+ */
+export function mcpEntry(home: string, tool: string): { installed: boolean; broken?: string; off?: boolean } {
+  const t = MCP_TOOLS.find((x) => x.id === tool)
+  if (!t) return { installed: false }
+  const path = configPath(t, home)
+  let entry: unknown
+  try {
+    if (t.format === "toml") entry = existsSync(path) ? parseToml(readFileSync(path, "utf8"))?.mcp_servers?.[NAME] : undefined
+    else {
+      const loaded = loadJson(path)
+      const cur = "error" in loaded ? undefined : currentJson(t, loaded.config)
+      entry = cur && "entry" in cur ? cur.entry : undefined
+    }
+  } catch {
+    return { installed: false }
+  }
+  if (!isOurs(entry)) return { installed: false }
+  const e = entry as Json
+  const argv = (Array.isArray(e.command) ? e.command : [e.command, ...(Array.isArray(e.args) ? e.args : [])]).filter((x: unknown): x is string => typeof x === "string")
+  const bun = argv[0] ?? ""
+  const cli = argv[argv.length - 3] ?? ""
+  if (!(bun.includes("/") ? existsSync(bun) : Bun.which(bun))) return { installed: true, broken: `its bun (${bun}) is not there any more` }
+  if (/cli\.ts$/.test(cli) && !existsSync(cli)) return { installed: true, broken: `the brain it runs (${cli}) is not there any more` }
+  // Turned off in the tool's own settings (OpenCode's enabled: false, a disabled flag elsewhere).
+  if (e.enabled === false || e.disabled === true) return { installed: true, off: true }
+  return { installed: true }
+}
+
 // ---- the command ----
 
 const flag = (args: string[], name: string) => {
@@ -387,7 +431,19 @@ export async function mcpCommand(args: string[], home: string): Promise<number>
     const tool = flag(rest, "--tool")
     const ids = tool ? [tool] : MCP_TOOLS.map((t) => t.id)
     const dryRun = rest.includes("--dry-run")
-    const changes = action === "install" ? installMcp(ids, home, { dryRun }) : action === "uninstall" ? uninstallMcp(ids, home, { dryRun }) : tool ? statusMcp(home).filter((c) => c.tool === tool) : statusMcp(home)
+    // A real install or uninstall is recorded as this computer's setting (tools.<tool>.mcp) in the same hold of the brain
+    // lock as the change, so `brain settings` shows who set it. (The settings modules import this one: loaded here.)
+    const change = (action === "install" || action === "uninstall") && !dryRun
+    const settings = change ? { ...(await import("../settings/apply.ts")), ...(await import("../settings/catalog.ts")) } : undefined
+    const run = () => {
+      const cs = action === "install" ? installMcp(ids, home, { dryRun }) : action === "uninstall" ? uninstallMcp(ids, home, { dryRun }) : tool ? statusMcp(home).filter((c) => c.tool === tool) : statusMcp(home)
+      if (settings) {
+        const done = cs.filter((c) => (action === "install" ? ["installed", "already-installed"] : ["removed", "not-installed"]).includes(c.action))
+        settings.recordChanges(home, done.map((c) => ({ id: `tools.${settings.toolOfMcpInstaller(c.tool)}.mcp`, value: action === "install" })), `brain mcp ${action}`)
+      }
+      return cs
+    }
+    const changes = change ? withBrainLockSync(home, run, { what: `${action === "install" ? "installing" : "removing"} the brain tools` }) : run()
     if (!changes.length) {
       say(`no tool "${tool}"; available: ${MCP_TOOLS.map((t) => t.id).join(", ")}`)
       return 1

package/src/memory/mcp-server.ts

@@ -19,6 +19,7 @@ import { windowOf } from "./relevance.ts"
 import { logLookup } from "./lookups.ts"
 import { openMemory } from "./store.ts"
 import { approxTokens, type BlobStore, type Memory, type ProjectKey } from "./types.ts"
+import { MEMORY_OFF, memoryOn } from "../settings/values.ts"
 
 export interface McpServerOptions {
   home: string
@@ -102,6 +103,8 @@ export async function runMcpServer(opts: McpServerOptions): Promise<void> {
   async function recall(args: Json) {
     const query = typeof args.query === "string" ? args.query.trim() : ""
     if (!query) return fail("query is required")
+    // Read on every call: the person can turn memory off while the tool keeps this server running.
+    if (!memoryOn(opts.home)) return ok(MEMORY_OFF)
     const st = await mem().status()
     if (!st.available) return ok(`memory is not available: ${st.why ?? "unknown reason"}`)
     const limit = Math.max(1, Math.min(50, Math.floor(Number(args.limit)) || 8))
@@ -184,6 +187,7 @@ export async function runMcpServer(opts: McpServerOptions): Promise<void> {
   }
 
   async function status() {
+    if (!memoryOn(opts.home)) return ok(redact([`project: ${project.label} (${project.id})`, `memory: off (${MEMORY_OFF})`, `blobs: ${blob().dir}`].join("\n")))
     const st = await mem().status()
     const lines = [`project: ${project.label} (${project.id})`, `memory: ${st.available ? "available" : `not available: ${st.why ?? "unknown reason"}`}`]
     if (st.store) lines.push(`store: ${st.store}`)

package/src/memory/prepare.ts

@@ -16,8 +16,12 @@ import { repoMap } from "./repomap.ts"
 import { logLookup } from "./lookups.ts"
 import { openMemory } from "./store.ts"
 import { approxTokens, type BlobRef, type BlobStore, type Memory, type ProjectKey } from "./types.ts"
+import { leanSettings, MEMORY_OFF, memoryOn } from "../settings/values.ts"
 
-/** Sessions with at least this many tokens are made lean when nothing says otherwise: below it, full fidelity costs little. */
+/**
+ * Sessions with at least this many tokens are made lean when nothing says otherwise: below it, full fidelity costs little.
+ * The default of the `lean.threshold` setting (`brain settings`), which can also turn it off (`lean.auto`).
+ */
 export const LEAN_AUTO_TOKENS = 50_000
 /** Above this many tokens a native continuation cannot fit the context of most models. */
 export const WINDOW_WARN_TOKENS = 400_000
@@ -105,14 +109,17 @@ export async function prepare(session: Session, o: PrepareOptions, deps: { memor
   const notes: string[] = []
   const tokens = sessionTokens(session)
   const budget = o.budget !== undefined && Number.isFinite(o.budget) && o.budget > 0 ? Math.floor(o.budget) : undefined
-  const lean = o.lean ?? (tokens >= LEAN_AUTO_TOKENS || (budget !== undefined && tokens > budget))
+  // This computer's settings (ways 1 and 2): when a long session is made lean, and from what size an output is digested.
+  const ls = leanSettings(o.home)
+  const lean = o.lean ?? ((ls.auto && tokens >= ls.threshold) || (budget !== undefined && tokens > budget))
+  if (o.lean === undefined && !ls.auto && tokens >= ls.threshold && !lean) notes.push(`lean: not automatic on this computer (brain settings: lean.auto off); --lean makes this ${tokens.toLocaleString()}-token session lean`)
   const brief: Prepared["brief"] = { lean }
   let out = session
   const tidy = o.tidy !== false
 
   if (lean) {
     const blobs = deps.blobs ?? (o.dryRun ? scratchBlobs() : openBlobStore(o.home))
-    const r = budget !== undefined ? externalizeToBudget(session, blobs, { targetTokens: budget, tidy }) : externalize(session, blobs, { tidy })
+    const r = budget !== undefined ? externalizeToBudget(session, blobs, { targetTokens: budget, tidy, minChars: ls.minChars }) : externalize(session, blobs, { tidy, minChars: ls.minChars })
     out = r.session
     if (!o.dryRun && r.replaced) logLookup(o.home, { event: "stubs", at: new Date().toISOString(), session: session.header.id, byKind: r.byKind as Record<string, number> })
     const digested = Math.round((r.before - r.after - r.tidied) / 4)
@@ -136,7 +143,8 @@ export async function prepare(session: Session, o: PrepareOptions, deps: { memor
   const left = sessionTokens(out)
   if (left > WINDOW_WARN_TOKENS) notes.push(`size: still about ${left.toLocaleString()} tokens, more than most models take at once; \`--way brief\` carries the essentials and what the project remembers in about ${(BRIEF_TOKENS_HINT).toLocaleString()} tokens`)
 
-  if (!o.noMemory) {
+  if (!o.noMemory && !memoryOn(o.home)) notes.push(`memory: not used (${MEMORY_OFF})`)
+  else if (!o.noMemory) {
     const memory = deps.memory ?? openMemory(o.home)
     const status = await memory.status().catch((e: Error) => ({ available: false as const, why: e.message }))
     if (!status.available) notes.push(`memory: not used (${status.why ?? "unavailable"})`)

package/src/memory/sync.ts

@@ -10,6 +10,7 @@ import { distill } from "./distill.ts"
 import { projectKey } from "./project.ts"
 import { openMemory } from "./store.ts"
 import type { Memory } from "./types.ts"
+import { MEMORY_OFF, memoryOn } from "../settings/values.ts"
 
 export interface SessionSource {
   /** Portable id (`<tool>:<id>`). */
@@ -112,6 +113,7 @@ export async function syncMemory(o: SyncOptions, deps: { memory?: Memory; sessio
   const result: SyncResult = { ingested: 0, items: 0, upToDate: 0, deferred: 0, errors: [], ms: 0 }
   const done = (): SyncResult => ({ ...result, ms: now() - t0 })
 
+  if (!memoryOn(o.home)) return { ...done(), unavailable: MEMORY_OFF }
   const memory = deps.memory ?? openMemory(o.home)
   const status = await memory.status().catch((e: Error) => ({ available: false as const, why: e.message }))
   if (!status.available) return { ...done(), unavailable: status.why ?? "unavailable" }
@@ -156,6 +158,7 @@ export async function syncMemory(o: SyncOptions, deps: { memory?: Memory; sessio
 export function syncInBackground(home: string, cwd: string, cli: string) {
   if (process.env.BRAIN_NO_MEMORY === "1") return
   try {
+    if (!memoryOn(home)) return
     // Only where memory has been set up on this machine: a person who never used it does not get a store created by a hook.
     if (!existsSync(join(home, ".brain", "memory"))) return
     const child = Bun.spawn([process.execPath, cli, "memory", "sync", "--here", "--quiet"], { cwd, stdin: "ignore", stdout: "ignore", stderr: "ignore", env: { ...process.env, BRAIN_HOME: home } })