@theronap/cortex-mcp 0.9.77 → 0.9.78

package/bin/cortex-mcp.mjs

@@ -49,6 +49,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  uninstall       remove ALL Agnoclast wiring (MCP, hooks, skills, launchd, cron). --dry-run to preview, --purge to also wipe ~/.cortex + npx cache\n` +
     `  doctor          live health check — confirm your token works (no restart needed)\n` +
     `  status          one-line connected/not-connected check (used by the SessionStart hook)\n` +
+    `  use-brain [<brain>]    where your session captures are saved — no arg shows the current setting\n` +
     `  skills          install/repair the managed Agnoclast skills — bundled + org-published (also wired by setup)\n` +
     `  skills push <file>     publish a SKILL.md to your org (owner/manager/admin)\n` +
     `  docs-scan       detect new/changed local docs pending Agnoclast authoring (used by /cortex-author-docs)\n` +
@@ -177,12 +178,27 @@ if (cmd === 'login') {
   // The cortex-author-docs skill authors the pending docs into wiki pages. No network.
   const { runDocsScan } = await import('../lib/docs_scan.mjs')
   process.exitCode = await runDocsScan(rest)
+} else if (cmd === 'use-brain') {
+  // Set (or show) which brain this machine's unattended session captures land in. Registered here,
+  // BEFORE the default branch — an unrecognised subcommand falls through to "start the MCP server",
+  // which is how `connect-calendar` once silently became the file-watching daemon on a pilot user's
+  // machine and reported that daemon's errors instead of its own.
+  const { runUseBrain } = await import('../lib/use_brain.mjs')
+  process.exitCode = await runUseBrain(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'precompact') {
-  // PreCompact hook (③ live wiki authoring, best-effort): print an "author now" reminder so the session
-  // sweeps its understanding into the wiki BEFORE compaction drops it. A hook cannot force a model turn
-  // (D2) — this is the documented fallback; /log is the hard backstop. No network; prints + exits.
-  const { runPrecompactReminder } = await import('../lib/precompact.mjs')
-  runPrecompactReminder()
+  // RETIRED — deliberately kept as a silent no-op, do not delete yet.
+  //
+  // The reminder it used to print never reached a model: PreCompact takes a blocking `decision` and has
+  // no additionalContext channel, so its stdout went nowhere (verified 2026-08-10 against 7,232 local
+  // transcripts — see the PreCompact block in lib/editors/claude.mjs for the measurement and control).
+  //
+  // Why this branch survives the removal: seats installed before this release still have
+  // `PreCompact: npx -y @theronap/cortex-mcp@latest precompact` in ~/.claude/settings.json, and @latest
+  // resolves to THIS build. Deleting the branch would turn a harmless no-op into an unknown-command
+  // error on every compaction for anyone who has not re-run install. mergeClaudeSettings unwires them
+  // on their next install/repair; drop this branch a release after that has had time to propagate.
 } else {
   // Default: run the MCP server (stays alive; never exits).
   const { runServer } = await import('../lib/server.mjs')

package/lib/diagnose.mjs

@@ -235,12 +235,19 @@ export async function checkToken(token, base) {
     return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId) }
   }
   let projectCount
+  let captureNotice = null
   try {
-    const ctx = JSON.parse(body).context ?? ''
+    const parsed = JSON.parse(body)
+    const ctx = parsed.context ?? ''
     const m = ctx.match(/## Projects \((\d+)\)/)
     if (m) projectCount = Number(m[1])
+    // The server's "your work is not landing" advisory. Optional by design: an older server does not
+    // send it and this must stay a health check, so a missing field is simply no notice.
+    if (parsed.captureNotice && typeof parsed.captureNotice.message === 'string') {
+      captureNotice = parsed.captureNotice
+    }
   } catch { /* context shape changed — non-fatal for a health check */ }
-  return { ok: true, status: 200, projectCount, requestId }
+  return { ok: true, status: 200, projectCount, requestId, captureNotice }
 }
 
 // Probe the org-skills surface. SEPARATE FROM checkToken ON PURPOSE.

package/lib/doctor.mjs

@@ -11,7 +11,10 @@ import { checkToken, checkSkills, resolveBase } from './diagnose.mjs'
 
 // Token resolution: env first, then the Claude config the setup command wrote (so `doctor`
 // works the moment after `setup`, before any restart). Returns { token, source }.
-function resolveToken() {
+// Exported so `use-brain` resolves the token EXACTLY as doctor/status do. There is already a second,
+// subtly different copy of this in context_log.mjs (returns a bare token, not {token, source}); a
+// third copy is how a machine ends up "connected" to one command and "no token found" to another.
+export function resolveToken() {
   if (process.env.CORTEX_TOKEN) return { token: process.env.CORTEX_TOKEN, source: 'CORTEX_TOKEN env' }
   const claudeJson = join(homedir(), '.claude.json')
   if (existsSync(claudeJson)) {
@@ -39,6 +42,16 @@ export async function runStatus() {
   try {
     const r = await checkToken(token, base)
     if (r.ok) {
+      // ⚠ THE NOTICE REPLACES THE HAPPY LINE RATHER THAN FOLLOWING IT.
+      // "connected — sessions on this machine are captured to your org" was printed truthfully to
+      // three people whose sessions were, at that moment, landing in NO brain: connected is a fact
+      // about the TOKEN, and every reader takes it as a fact about their WORK. Printing both would
+      // leave the reassurance that caused four days of silent loss sitting directly above the
+      // warning that contradicts it.
+      if (r.captureNotice?.message) {
+        out(`Agnoclast: ⚠ ${r.captureNotice.message}`)
+        return 0
+      }
       const n = typeof r.projectCount === 'number' ? ` · ${r.projectCount} project${r.projectCount === 1 ? '' : 's'} visible` : ''
       out(`Agnoclast: connected — sessions on this machine are captured to your org${n}.`)
     } else {

package/lib/editors/claude.mjs

@@ -41,7 +41,8 @@ export const CORTEX_ALLOWED_TOOLS = [
 /** Merge Agnoclast's Claude Code hooks into a ~/.claude/settings.json object. Pure + idempotent: drops
  *  any prior cortex entry (old token/path/version) from each hook array before appending the current
  *  one — capture (Stop), status + skills-repair + snapshot-context (SessionStart), hydrate
- *  (UserPromptSubmit), precompact (PreCompact). Commands carry NO inline token (each subcommand
+ *  (UserPromptSubmit). Also UNWIRES the retired PreCompact reminder from seats that still carry it.
+ *  Commands carry NO inline token (each subcommand
  *  self-resolves it). Mirrors setup.mjs
  *  step 2 exactly; foreign hooks are never touched. Also merges the CORTEX_ALLOWED_TOOLS permission
  *  allowlist — additive-only: a user's own allow entries (even extra mcp__cortex__* ones) are never
@@ -105,16 +106,28 @@ export function mergeClaudeSettings(existing, spec) {
   hgrp.hooks = hgrp.hooks ?? []
   hgrp.hooks.push({ type: 'command', command: hydrateCmd })
 
-  // PreCompact — "author now" reminder.
-  s.hooks.PreCompact = Array.isArray(s.hooks.PreCompact) ? s.hooks.PreCompact : []
-  const precompactCmd = `npx -y ${spec} precompact`
-  for (const pg of s.hooks.PreCompact) {
-    if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? precompact/.test(h.command ?? ''))
+  // PreCompact — REMOVED, and this block is the migration that unwires existing seats.
+  //
+  // The "author now" reminder wrote to stdout on the assumption the harness surfaced it as context for
+  // the next turn. It does not: PreCompact accepts a blocking `decision` and nothing else — it has no
+  // additionalContext channel — so the reminder never reached a model. Measured 2026-08-10 across 7,232
+  // local transcripts: the reminder text appears 5 times, every one of them a tool_result from someone
+  // READING the file, assistant prose about it, or a compaction summary that absorbed such prose. Zero
+  // injections, against >=13 transcripts that demonstrably compacted. The control is what makes that
+  // conclusive rather than merely absent: SessionStart's hook output, on a channel that IS injected,
+  // appears in 912 transcripts of the same corpus.
+  //
+  // So: filter, never append. Every install/repair strips the stale entry from seats that already have
+  // it, which is why this runs unconditionally instead of shipping as a separate migration.
+  if (Array.isArray(s.hooks.PreCompact)) {
+    for (const pg of s.hooks.PreCompact) {
+      if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? precompact/.test(h.command ?? ''))
+    }
+    // Drop groups we just emptied, then the key itself if no foreign hook remains — a bare
+    // `PreCompact: []` reads as "cortex wires this event" to the next person to open settings.json.
+    s.hooks.PreCompact = s.hooks.PreCompact.filter((pg) => (pg.hooks ?? []).length > 0)
+    if (s.hooks.PreCompact.length === 0) delete s.hooks.PreCompact
   }
-  let pgrp = s.hooks.PreCompact.find((g) => (g.matcher ?? '') === '')
-  if (!pgrp) { pgrp = { matcher: '', hooks: [] }; s.hooks.PreCompact.push(pgrp) }
-  pgrp.hooks = pgrp.hooks ?? []
-  pgrp.hooks.push({ type: 'command', command: precompactCmd })
 
   // Permissions — pre-authorize the read + authoring core so a page update never stalls on a
   // permission prompt. Append-missing only (no filter-and-rebuild like the hooks above): removals

package/lib/server.mjs

@@ -137,6 +137,53 @@ export async function runServer(version) {
     },
   )
 
+  // Where this machine's unattended session captures land. The server half shipped 2026-08-09 with no
+  // client surface at all, so the only way to set it was a hand-written authenticated HTTP call —
+  // which meant three real users whose sessions were silently being held could not fix it themselves.
+  // This is the surface that makes it answerable in conversation: "put my sessions in TTO".
+  server.registerTool(
+    'set_capture_brain',
+    {
+      title: 'Choose where your session captures are saved',
+      description:
+        'Set which brain THIS PERSON\'s unattended session captures (the automatic end-of-session record) land in, or read the current setting by omitting `brain`. WHEN TO USE: whenever the user says their sessions are not being saved, asks where their work is going, or a session-start notice says captures are being HELD. WHY IT IS NEEDED: with more than one brain, a capture that names no brain cannot be routed and is held outside every brain — correct, but invisible, so it accumulates silently. This is per-PERSON and applies to their own captures only; it cannot be set for someone else. ⚠ PASS THE ORG ID when the user has two brains with the SAME NAME (e.g. two called "Personal") — a name matching more than one is REFUSED rather than guessed, and the error lists the ids to choose from. Setting this does NOT file already-held captures; those keep their original dates and may belong in different brains, so sort them deliberately rather than dumping them into the new default.',
+      inputSchema: {
+        brain: z.string().optional().describe('the brain name or org id (from my_brains) where this person\'s session captures should land. Omit to read the current setting instead of changing it.'),
+      },
+    },
+    async ({ brain }) => {
+      const url = `${BASE}/api/brain/capture-default`
+      if (!brain?.trim()) {
+        const res = await fetchCortex(url, { headers: { Authorization: `Bearer ${TOKEN}` } })
+        if (!res.ok) {
+          const body = await res.text()
+          throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
+        }
+        const { defaults } = await res.json()
+        if (!defaults?.length) {
+          return { content: [{ type: 'text', text: 'No capture brain is set. If you belong to more than one brain, your session captures are being HELD outside every brain until you set one. Call this tool again with `brain` to fix it.' }] }
+        }
+        const lines = defaults.map((d) => `${d.sourceType} captures land in "${d.orgName}" (${d.orgId}), set ${String(d.updatedAt).slice(0, 10)}`)
+        return { content: [{ type: 'text', text: lines.join('\n') }] }
+      }
+      const res = await fetchCortex(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sourceType: 'claude-code', brain: brain.trim() }),
+      })
+      const body = await res.text()
+      if (!res.ok) {
+        // Prefer the server's own error: a 409 lists the org ids of an ambiguous name, which IS the
+        // remedy, and a generic classification would throw that away.
+        let msg
+        try { msg = JSON.parse(body).error } catch { /* fall through to the classified message */ }
+        throw new Error(msg ?? classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
+      }
+      const j = JSON.parse(body)
+      return { content: [{ type: 'text', text: `✓ Your Claude Code sessions now land in "${j.brain}" (${j.orgId}). Sessions captured before now are still held and keep their original dates — file those deliberately, they may not all belong in this brain.` }] }
+    },
+  )
+
   // T8: cortex-log's authoritative writer. The skill composes a curated summary, then calls this to
   // persist it AS the durable record (capture_source='skill'). The ingest conflict guard ensures the
   // auto-capture hook never clobbers it. Pass the SAME sessionId the hook uses so the two dedupe onto

package/lib/setup.mjs

@@ -128,8 +128,9 @@ export async function runSetup(argv, version) {
       process.exit(1)
     }
     const bak = backup(settingsJson)
-    // Capture (Stop) + status/skills/snapshot (SessionStart) + precompact (PreCompact), idempotent
-    // merge — the same pure function the `cortex install` Claude adapter uses.
+    // Capture (Stop) + status/skills/snapshot (SessionStart) + hydrate (UserPromptSubmit), idempotent
+    // merge — the same pure function the `cortex install` Claude adapter uses. Also unwires the retired
+    // PreCompact reminder from seats that still carry it.
     s = mergeClaudeSettings(s, spec)
 
     ensureDir(settingsJson)

package/lib/use_brain.mjs

@@ -0,0 +1,82 @@
+import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { resolveToken } from './doctor.mjs'
+
+// `use-brain` — set (or show) which brain this machine's unattended session captures land in.
+//
+// WHY A SUBCOMMAND EXISTS AT ALL. The server side of this shipped 2026-08-09 with NO client surface:
+// no CLI, no MCP tool, no console setting. The only way to set a capture default was a raw
+// authenticated HTTP call, which meant the only people who could fix a broken capture were the ones
+// who could hand-write a curl with a bearer token. Three real users needed it; one of them is not
+// technical. A fix only its author can operate is not a fix.
+//
+// Pairs with the SessionStart notice: the notice tells you captures are being held and names this
+// command, so the loop from "something is wrong" to "it is fixed" is one paste with no docs.
+
+function out(m) { process.stdout.write(m + '\n') }
+
+export async function runUseBrain(args) {
+  const base = resolveBase(process.env.CORTEX_URL)
+  const { token } = resolveToken()
+  if (!token) {
+    out('Agnoclast: no token found. Run: npx -y @theronap/cortex-mcp setup <token>')
+    return 1
+  }
+
+  // Everything after the subcommand is the brain, joined — so an unquoted multi-word name still
+  // works. `use-brain Real estate` is what a person actually types; refusing it over a missing pair
+  // of quotes would be the same species of unhelpfulness this command exists to remove.
+  const wanted = (args ?? []).filter((a) => !a.startsWith('--')).join(' ').trim()
+  const url = `${base}/api/brain/capture-default`
+
+  if (!wanted) {
+    // No argument: report the current state rather than erroring. "What is it set to?" is a fair
+    // question and the answer is one GET away.
+    try {
+      const res = await fetchCortex(url, { headers: { Authorization: `Bearer ${token}` } })
+      if (!res.ok) {
+        const body = await res.text()
+        out(`Agnoclast: could not read your capture settings — ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}`)
+        return 1
+      }
+      const { defaults } = await res.json()
+      if (!defaults?.length) {
+        out('Agnoclast: no capture brain set. Your unattended session captures land in a brain only if')
+        out('  you belong to exactly one; otherwise they are HELD outside every brain until you set this.')
+        out('  Set one:  npx -y @theronap/cortex-mcp use-brain "<brain name or org id>"')
+        return 0
+      }
+      for (const d of defaults) out(`Agnoclast: ${d.sourceType} captures land in "${d.orgName}" (${d.orgId})`)
+      return 0
+    } catch (e) {
+      out(`Agnoclast: could not reach the server (${e?.message ?? String(e)})`)
+      return 1
+    }
+  }
+
+  try {
+    const res = await fetchCortex(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sourceType: 'claude-code', brain: wanted }),
+    })
+    const body = await res.text()
+    if (!res.ok) {
+      let msg = classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message
+      // The server's own error text is better than a generic one here: a 404 names the brain that was
+      // not found, and a 409 lists the org ids of an ambiguous name — which is the whole remedy.
+      try { const j = JSON.parse(body); if (j.error) msg = j.error } catch { /* keep the classified message */ }
+      out(`Agnoclast: ${msg}`)
+      return 1
+    }
+    const j = JSON.parse(body)
+    out(`Agnoclast: ✓ your Claude Code sessions now land in "${j.brain}".`)
+    // Say plainly what this does NOT do. The setter's own server-side note makes the same point,
+    // because "I fixed it" reading as "and the backlog is handled" is how held records stay held.
+    out('  Sessions captured BEFORE now are still held — they keep their original dates until sorted.')
+    out('  Ask your assistant to file them (they may not all belong in the same brain).')
+    return 0
+  } catch (e) {
+    out(`Agnoclast: could not reach the server (${e?.message ?? String(e)})`)
+    return 1
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.77",
+  "version": "0.9.78",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {

package/lib/precompact.mjs

@@ -1,16 +0,0 @@
-// PreCompact "author now" reminder (③ live wiki authoring, [[cortex-wiki-authoring-spec]] D2).
-//
-// Wired by setup.mjs as a PreCompact hook. A hook CANNOT force a model turn — it can only inject text
-// the model sees on its next turn (best-effort). So this prints a reminder to sweep understanding into
-// the wiki BEFORE compaction discards the session's hot mental model. The HARD backstop is the /log
-// skill (cortex-log step 5); this catches the in-session compaction that would otherwise lose the magic.
-//
-// Output goes to stdout, which the Claude Code harness surfaces as additional context for the next turn.
-export function runPrecompactReminder() {
-  process.stdout.write(
-    'Agnoclast: context is about to compact. If your understanding of any node (the project(s) you worked ' +
-    'on, people you coordinated with, or yourself) advanced this session, AUTHOR it into the wiki NOW ' +
-    'before it is lost: call `authoring_context` then `author` for each. This is a synthesis of your ' +
-    'compiled understanding with inline [[links]], not a transcript dump. Skip nodes you did not advance.\n',
-  )
-}