@theronap/cortex-mcp 0.9.16 → 0.9.18

package/bin/cortex-mcp.mjs

@@ -46,6 +46,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  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` +
     `  skills          install/repair the managed Cortex skills (also wired by setup)\n` +
+    `  materialize [--drain]  build brain pages on your Claude subscription (claude -p); --drain clears the backlog\n` +
     `  snapshot-context save the exact startup context Cortex served to a local snapshot\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
@@ -102,6 +103,20 @@ if (cmd === 'setup') {
   await runRelationships()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'links') {
+  // CU-2 cross-user link judge: judge server-flagged candidate pairs ("do these interconnect?") via
+  // `claude -p` and push verdicts back (queue/reject — never an auto-write). Sibling of `relationships`.
+  const { runLinks } = await import('../lib/links.mjs')
+  await runLinks()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'materialize') {
+  // Brain-page summarizer on the SUBSCRIPTION (claude -p): claim authorized digest jobs, summarize
+  // locally, submit the text for the server to write. `--drain` clears the whole backlog.
+  const { runMaterializeCli } = await import('../lib/materialize.mjs')
+  process.exitCode = await runMaterializeCli(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'ingest-folder') {
   const { runIngestFolder } = await import('../lib/ingest_folder.mjs')
   await runIngestFolder(rest)

package/lib/capture.mjs

@@ -5,6 +5,7 @@ import { createHash } from 'crypto'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 import { extractSession } from './edge_extract.mjs'
 import { extractTyped } from './extract_typed.mjs'
+import { runMaterialize } from './materialize.mjs'
 import { redactSecrets } from './redact.mjs'
 
 // Fetch the node-type registry (global + this org's custom types) — the catalog the typed extractor
@@ -164,4 +165,12 @@ export async function runCapture() {
     const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
     process.stderr.write(`cortex: ingest failed — ${d.message}\n`)
   }
+
+  // Keystone fix (b): ingest just marked this session's nodes dirty server-side. Summarize the freshly
+  // dirtied pages on the SUBSCRIPTION (claude -p) so the brain stays current without the dead server
+  // API. OPT-IN (CORTEX_MATERIALIZE) + bounded so it never adds unbounded latency to session stop;
+  // `cortex-mcp materialize --drain` is the bulk/backlog path. Best-effort: never blocks capture.
+  if (process.env.CORTEX_MATERIALIZE) {
+    try { await runMaterialize({ max: 3 }) } catch { /* best-effort */ }
+  }
 }

package/lib/context_log.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
@@ -28,6 +28,23 @@ function snapshotDir() {
   return join(homedir(), '.cortex', 'context-snapshots')
 }
 
+// Keep only the most recent N timestamped snapshots; latest.md + index.jsonl are
+// always preserved. Without this the per-session-start archives grow unbounded
+// (2k+ files / ~40MB observed in the field). Best-effort: a prune failure must
+// never break session start.
+const SNAPSHOT_RETENTION = 50
+
+function pruneSnapshots(dir, keep = SNAPSHOT_RETENTION) {
+  try {
+    const stamped = readdirSync(dir)
+      .filter((f) => /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}\.md$/.test(f))
+      .sort() // stamp() is zero-padded, so lexicographic order === chronological
+    for (const f of stamped.slice(0, Math.max(0, stamped.length - keep))) {
+      try { unlinkSync(join(dir, f)) } catch { /* ignore individual failures */ }
+    }
+  } catch { /* ignore — never break session start */ }
+}
+
 export async function runSnapshotContext() {
   const out = (m) => process.stdout.write(m + '\n')
   const token = resolveToken()
@@ -75,6 +92,8 @@ export async function runSnapshotContext() {
     chars: context.length,
   }) + '\n', { flag: 'a' })
 
+  pruneSnapshots(dir)
+
   out(`Cortex: logged startup context → ${file}`)
   return 0
 }

package/lib/links.mjs

@@ -0,0 +1,105 @@
+import { spawnSync } from 'child_process'
+import { fetchCortex, resolveBase, classify } from './diagnose.mjs'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// `cortex-mcp links` — the JUDGE half of CU-2 (cross-user link curation), sibling of `relationships`.
+// The server FLAGS proposed candidate pairs (GET /api/link-judge-candidates) with resolved endpoint names
+// + co-usage evidence; this command judges each LOCALLY via `claude -p` (the server never calls the metered
+// API) — "do these two genuinely interconnect?" — and pushes verdicts back (POST /api/link-judge-apply).
+// SAFETY: the apply only ever moves a candidate to `queued` (human approval) or `rejected`; it never writes
+// a cross_user_links row. Conservative by construction: the prompt asks the model to default to "incidental".
+
+export async function runLinks() {
+  // recursion guard (we spawn `claude --print`; its Stop hook capture no-ops on this flag)
+  if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
+  const token = process.env.CORTEX_TOKEN
+  if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  // 1. pull proposed candidates (each with resolved endpoint names + co-usage count)
+  let candidates = []
+  try {
+    const res = await fetchCortex(`${base}/api/link-judge-candidates`, { headers: { Authorization: `Bearer ${token}` } })
+    if (!res.ok) {
+      const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+      process.stderr.write(`cortex: link-judge-candidates failed — ${d.message}\n`); return
+    }
+    const j = await res.json().catch(() => ({}))
+    candidates = Array.isArray(j.candidates) ? j.candidates : []
+  } catch (e) { process.stderr.write(`cortex: links fetch failed — ${e.message}\n`); return }
+
+  if (!candidates.length) { process.stderr.write('cortex: no link candidates to judge\n'); return }
+  process.stderr.write(`cortex: judging ${candidates.length} link candidate(s) locally…\n`)
+
+  // 2. judge locally on the subscription — ONE call per candidate (each is a single pair)
+  const judgments = []
+  let judged = 0
+  for (const c of candidates) {
+    const verdict = judgeLink(c)
+    if (verdict === null) { process.stderr.write('cortex: judge unavailable (is `claude` on PATH?) — skipping\n'); break }
+    judged++
+    if (verdict) judgments.push(verdict)
+  }
+  if (!judged) return
+  if (!judgments.length) { process.stderr.write(`cortex: judged ${judged} candidate(s), no verdicts produced\n`); return }
+
+  // 3. apply the verdicts (queue / reject)
+  try {
+    const res = await fetchCortex(`${base}/api/link-judge-apply`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ judgments }),
+    })
+    if (res.ok) {
+      const j = await res.json().catch(() => ({}))
+      process.stderr.write(`cortex: links — queued ${j.queued ?? 0}, rejected ${j.rejected ?? 0}, skipped ${j.skipped ?? 0}\n`)
+    } else {
+      const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+      process.stderr.write(`cortex: link-judge-apply failed — ${d.message}\n`)
+    }
+  } catch (e) { process.stderr.write(`cortex: link-judge-apply failed — ${e.message}\n`) }
+}
+
+// ONE `claude --print` call decides whether a candidate pair genuinely interconnects. Returns a judgment
+// { candidateId, interconnected, confidence, relationship, reason }, or null if the CLI is unavailable.
+// Mirrors web/lib/engine/link_judge.ts buildJudgePrompt/parseJudgeResponse (kept in sync).
+function judgeLink(c) {
+  if (!c || typeof c.candidateId !== 'string' || !c.src || !c.dst) return false
+  const co = c.coUsageCount != null ? `They have been surfaced together ${c.coUsageCount} time(s) when answering questions.` : ''
+  const prompt = [
+    `Two entities in an organization's knowledge graph keep showing up together but are not yet linked.`,
+    `A: ${c.src.name} (${c.src.kind})`,
+    `B: ${c.dst.name} (${c.dst.kind})`,
+    co,
+    `Question: do A and B genuinely interconnect (a real working/organizational relationship), or is the co-occurrence incidental?`,
+    `Reply with ONLY a JSON object: {"interconnected": boolean, "confidence": 0..1, "relationship": "<short label>", "reason": "<one line>"}.`,
+    `Be conservative — if it looks incidental, say interconnected:false. Never invent specifics you weren't given.`,
+  ].filter(Boolean).join('\n')
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
+      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: 120_000, maxBuffer: 4 * 1024 * 1024 },
+    )
+    if (r.status !== 0 || !r.stdout) return null
+    return parseVerdict(r.stdout, c.candidateId)
+  } catch {
+    return null
+  }
+}
+
+function parseVerdict(out, candidateId) {
+  const start = out.indexOf('{')
+  const end = out.lastIndexOf('}')
+  if (start < 0 || end <= start) return false
+  let o
+  try { o = JSON.parse(out.slice(start, end + 1)) } catch { return false }
+  const confidence = Math.max(0, Math.min(1, Number(o.confidence) || 0))
+  return {
+    candidateId,
+    interconnected: !!o.interconnected,
+    confidence,
+    relationship: typeof o.relationship === 'string' ? o.relationship.trim().slice(0, 80) : undefined,
+    reason: typeof o.reason === 'string' ? o.reason.trim().slice(0, 280) : undefined,
+  }
+}

package/lib/materialize.mjs

@@ -0,0 +1,117 @@
+import { spawnSync } from 'child_process'
+import { fetchCortex, resolveBase } from './diagnose.mjs'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// Edge materialize worker (keystone fix "b"): the brain-page summarizer moved OFF the dead server-side
+// Anthropic API onto the user's Claude SUBSCRIPTION (`claude -p`), mirroring edge extraction + edge
+// relationship inference. The SERVER still owns gather + tier-authorization + the write
+// (/api/brain/materialize/{claim,submit}); this worker ONLY runs the LLM step. It claims a batch of
+// jobs the user is authorized to summarize, runs `claude --print` per (node, tier), and POSTs the RAW
+// model text back for the server to parse + validate + write. The edge is never trusted: it cannot
+// pick a node, choose a tier, or shape a section — it only turns a server-handed corpus into text.
+//
+// Best-effort throughout: a tier the edge can't summarize is simply not submitted and stays queued for
+// a later run. Guarded by CORTEX_SUMMARIZING so it never recurses through the Stop-hook capturer.
+
+const SUMMARY_MODEL = process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5'
+
+// ONE `claude --print` call → the raw model text for a single tier's digest prompt. Subscription auth
+// via edgeSafeEnv (keeps CLAUDE_CODE_OAUTH_TOKEN, strips billed/proxy ANTHROPIC_*). null on any failure.
+// The server returns a separate system + user prompt; claude --print takes one prompt, so we prepend
+// the system instructions (same as edge_extract puts its instructions in the prompt body).
+function summarizeTier(tier) {
+  const prompt = `${tier.system}\n\n${tier.user}`
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', SUMMARY_MODEL, prompt],
+      {
+        env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }),
+        encoding: 'utf8',
+        timeout: 120_000,
+        maxBuffer: 8 * 1024 * 1024,
+      },
+    )
+    if (r.status !== 0 || !r.stdout) return null
+    return r.stdout.trim() || null
+  } catch {
+    return null
+  }
+}
+
+async function claimBatch(base, token, max) {
+  const res = await fetchCortex(`${base}/api/brain/materialize/claim`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ max }),
+  })
+  if (!res.ok) throw new Error(`claim HTTP ${res.status}`)
+  const j = await res.json().catch(() => ({}))
+  return Array.isArray(j.jobs) ? j.jobs : []
+}
+
+async function submitNode(base, token, kind, ref, results) {
+  const res = await fetchCortex(`${base}/api/brain/materialize/submit`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ kind, ref, results }),
+  })
+  if (!res.ok) throw new Error(`submit HTTP ${res.status}`)
+  return res.json().catch(() => ({}))
+}
+
+// Claim → summarize → submit. opts.drain loops until the queue is empty (clears a backlog); otherwise
+// it does ONE bounded batch (the freshness path called after a capture). Returns a tally.
+export async function runMaterialize(opts = {}) {
+  const log = opts.log ?? ((m) => process.stderr.write(`${m}\n`))
+  const token = process.env.CORTEX_TOKEN
+  if (!token) { log('cortex: CORTEX_TOKEN not set, skipping materialize'); return { built: 0, batches: 0 } }
+  // Never run inside the summarizer subprocess (it sets CORTEX_SUMMARIZING) — would recurse.
+  if (process.env.CORTEX_SUMMARIZING) return { built: 0, batches: 0 }
+
+  const base = resolveBase(process.env.CORTEX_URL)
+  const max = Math.min(Math.max(Number(opts.max) || 6, 1), 12)
+  const maxBatches = opts.drain ? (Number(opts.maxBatches) || 50) : 1
+
+  let built = 0
+  let batches = 0
+  for (let i = 0; i < maxBatches; i++) {
+    let jobs
+    try {
+      jobs = await claimBatch(base, token, max)
+    } catch (e) {
+      log(`cortex: materialize claim failed — ${e.message}`)
+      break
+    }
+    if (!jobs.length) break
+    batches++
+    for (const job of jobs) {
+      const results = []
+      for (const tier of job.tiers ?? []) {
+        const text = summarizeTier(tier)
+        if (text) results.push({ tier: tier.tier, text })
+      }
+      if (!results.length) { log(`cortex: ${job.kind} "${job.name}" — summarizer produced nothing, leaving queued`); continue }
+      try {
+        const out = await submitNode(base, token, job.kind, job.ref, results)
+        const n = out.built ?? 0
+        built += n
+        log(`cortex: materialized ${job.kind} "${job.name}" — ${n} tier${n === 1 ? '' : 's'}${out.settled ? '' : ' (partial)'}`)
+      } catch (e) {
+        log(`cortex: materialize submit failed for ${job.kind} "${job.name}" — ${e.message}`)
+      }
+    }
+  }
+  if (opts.drain) log(`cortex: materialize drain complete — ${built} tier-page(s) built across ${batches} batch(es)`)
+  return { built, batches }
+}
+
+// CLI entry: `cortex-mcp materialize [--drain] [--max N]`. --drain clears the whole backlog now;
+// without it, one bounded batch. Always exits 0 (best-effort maintenance, never a hard failure).
+export async function runMaterializeCli(args = []) {
+  const drain = args.includes('--drain')
+  const mi = args.indexOf('--max')
+  const max = mi >= 0 ? Number(args[mi + 1]) : undefined
+  await runMaterialize({ drain, max })
+  return 0
+}

package/package.json

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